logos

README

logos

Bash-only reasoning engine. LLMs think in plain text, act with $ commands. No tool schemas, no JSON ceremony.

Documentation

Overview

Package logos provides a reusable stateless agent loop.

Run() executes one agent loop iteration: prompt → LLM → tool calls → response. The caller provides conversation history, a system prompt, tools, and an optional sandbox env. No persistence — the caller receives StepMessages and handles storage.

Plane: shared

Index

• Constants
• func BuildSystemPrompt(data PromptData) (string, error)
• type Callbacks
• type Command
  • func ParseCommand(line string) (Command, bool)
• type CommandRunner
• type Config
• type PromptData
• type RunResult
  • func Run(ctx context.Context, cfg Config, history []fantasy.Message, prompt string, ...) (*RunResult, error)
• type StepMessage
• type StepRole

Constants

const DefaultMaxSteps = 30

DefaultMaxSteps is the fallback max steps when Config.MaxSteps is 0.

const DefaultMaxTokens = 16384

DefaultMaxTokens is the fallback max output tokens when Config.MaxTokens is 0.

Functions

func BuildSystemPrompt

func BuildSystemPrompt(data PromptData) (string, error)

BuildSystemPrompt renders the default system prompt with runtime context. The result is the base prompt — consumers append their own instructions after this.

Types

type Callbacks

type Callbacks struct {
	// OnDelta is called with each text delta as the LLM streams its response.
	OnDelta func(text string)
	// OnCommandStart is called when a $ command is detected, before execution.
	OnCommandStart func(command string)
}

Callbacks holds optional streaming callbacks for the agent loop. All fields are nil-safe — unset callbacks are simply not called.

type Command

type Command struct {
	Raw  string // full original line (e.g. "$ ls -la")
	Args string // everything after "$ " (e.g. "ls -la")
}

Command represents a parsed $ command from assistant output.

func ParseCommand

func ParseCommand(line string) (Command, bool)

ParseCommand checks if a line is a $ command. Returns the command and true if the line starts with "$ ". Returns zero Command and false otherwise.

type CommandRunner

type CommandRunner interface {
	Run(ctx context.Context, req client.RunRequest) (*client.RunResponse, error)
}

CommandRunner executes a sandboxed command and returns the result. *client.Client satisfies this interface automatically.

type Config

type Config struct {
	Provider     fantasy.Provider
	Model        string
	SystemPrompt string
	MaxSteps     int // 0 means use default (DefaultMaxSteps)
	MaxTokens    int // 0 means use default (DefaultMaxTokens)
	Temenos      CommandRunner
	SandboxEnv   map[string]string // env vars passed to temenos per-request
	// AllowedPaths lists filesystem paths accessible during command execution.
	// Path validation (non-empty, absolute) is enforced by the temenos daemon.
	AllowedPaths []client.AllowedPath
}

Config holds everything needed to run one agent loop iteration.

type PromptData

type PromptData struct {
	WorkingDir string
	Platform   string
	Date       string
	Commands   []tools.CommandHelp // selected per agent
}

PromptData holds the runtime context used to render the default system prompt.

type RunResult

type RunResult struct {
	Response string        // final text response (accumulated assistant text)
	Steps    []StepMessage // all messages generated (for persistence by caller)
}

RunResult contains the agent's output after a loop completes.

func Run

func Run(
	ctx context.Context,
	cfg Config,
	history []fantasy.Message,
	prompt string,
	cbs Callbacks,
) (*RunResult, error)

Run executes the agent loop: prompt → LLM → $ commands → repeat. Stateless — the caller handles conversation persistence.

type StepMessage

type StepMessage struct {
	Role      StepRole
	Content   string
	Timestamp time.Time
}

StepMessage represents one message generated during the agent loop.

type StepRole

type StepRole string

StepRole represents the role of a message step in the agent loop.

const (
	StepRoleAssistant StepRole = "assistant"
	StepRoleCommand   StepRole = "command"
)