logos

README

logos

Stateless agent loop for Go. LLMs think in plain text and act via § prefixed shell commands inside <cmd> blocks — no tool schemas, no JSON.

prompt → LLM → scan <cmd> blocks for "§ command" → execute in sandbox → feed <result> back → repeat

Install

go get github.com/tta-lab/logos

Usage

result, err := logos.Run(ctx, logos.Config{
    Provider:     provider,        // fantasy.Provider (LLM abstraction)
    Model:        "claude-sonnet-4-6",
    SystemPrompt: systemPrompt,
    Temenos:      temenosClient,   // sandboxed command runner
    SandboxEnv:   map[string]string{"HOME": "/app"},
    AllowedPaths: []client.AllowedPath{
        {Path: "/app", Permission: "rw"},
    },
}, history, "read main.go and explain what it does", logos.Callbacks{
    OnDelta: func(text string) {
        fmt.Print(text) // stream to terminal
    },
    OnCommandStart: func(cmd string) {
        fmt.Printf("\n> %s\n", cmd)
    },
})

The LLM responds in plain text. When it wants to act, it wraps commands in a <cmd> block:

Let me check the file structure first.

<cmd>
§ ls -la /app
</cmd>

logos detects the commands, executes them in a temenos sandbox, and feeds the output back wrapped in <result>. The loop continues until the LLM responds without any <cmd> blocks.

How it works

1. Run() takes config, conversation history, a prompt, and streaming callbacks
2. Each turn, the LLM streams a response
3. scanAllCommands() extracts all § lines from <cmd>...</cmd> blocks
4. Commands run via the CommandRunner interface (temenos sandbox)
5. Output wrapped in <result> becomes the next user message; loop repeats
6. When the LLM responds with no <cmd> blocks, the loop ends and returns RunResult

Key types

Type	Purpose
Config	Provider, model, temenos client, sandbox env, allowed paths
RunResult	Final response text + all step messages
StepMessage	One message in the loop (assistant text, with optional reasoning, or command output)
Callbacks	Optional OnDelta and OnCommandStart streaming hooks
CommandRunner	Interface for command execution — temenos satisfies it

System prompt

BuildSystemPrompt() renders an embedded template with runtime context (working dir, platform, date, available commands). Consumers typically append their own instructions after the base prompt:

base, _ := logos.BuildSystemPrompt(logos.PromptData{
    WorkingDir: "/app",
    Platform:   "linux",
    Date:       "2026-03-16",
    Commands:   availableCommands,
})
systemPrompt := base + "\n\n" + customInstructions

Design

• Stateless — Run() takes history in, returns steps out. The caller owns persistence.
• Multi-command blocks — all § lines inside a <cmd> block run sequentially; bare § outside blocks are prose and ignored.
• Sandboxed — commands execute in temenos, not on the host.
• Provider-agnostic — uses fantasy for LLM abstraction.
• Reasoning round-trip — thinking blocks (Anthropic extended thinking) captured in StepMessage.Reasoning and ReasoningSignature for conversation restoration.

Dependencies

• fantasy — LLM provider abstraction (streaming, messages)
• temenos — sandboxed command execution daemon

License

MIT

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)
• func ContainsToolCallHallucination(text string) bool
• type AllowedPath
• type Callbacks
• type Command
  • func ParseCommand(line string) (Command, bool)
• type CommandDoc
• type CommandRunner
  • func NewClient(addr string) (CommandRunner, error)
• type Config
• type PromptData
• type RunRequest
• type RunResponse
• type RunResult
  • func Run(ctx context.Context, cfg Config, history []fantasy.Message, prompt string, ...) (*RunResult, error)
• type StepMessage
• type StepRole

Constants

const CommandPrefix = "§ "

CommandPrefix is the prefix for agent commands in LLM output.

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.

const MaxHallucinationRetries = 3

MaxHallucinationRetries is the maximum number of tool call hallucination retries before Run() returns an error.

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.

func ContainsToolCallHallucination

func ContainsToolCallHallucination(text string) bool

ContainsToolCallHallucination returns true if text contains tool call patterns produced by models that hallucinate structured formats — XML tags (e.g. <tool_call>) or bracket delimiters (e.g. [TOOL_CALL]...[/TOOL_CALL]). Standalone utility — internal detection is handled by streamFilter during streaming.

Types

type AllowedPath

type AllowedPath = client.AllowedPath

AllowedPath specifies a filesystem path allowed in the sandbox.

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)
	// OnCommandResult is called after a command executes with the command string,
	// raw combined stdout+stderr output (no exit code suffix), and the exit code.
	// exitCode is -1 if the sandbox itself failed to execute the command (temenos
	// transport error), in which case output contains the error description.
	OnCommandResult func(command string, output string, exitCode int)
	// OnRetry is called when a tool call hallucination (XML or bracket) is detected
	// and an "unprocessed" directive is injected. reason is "tool_call".
	OnRetry func(reason string, step int)
}

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 CommandDoc

type CommandDoc struct {
	Name    string // command name, e.g. "url", "web", "rg"
	Summary string // one-line description shown under the heading
	Help    string // full help text (flags, examples, caveats)
}

CommandDoc describes a command available to the agent. Callers provide these to control which commands appear in the system prompt.

type CommandRunner

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

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

func NewClient

func NewClient(addr string) (CommandRunner, error)

NewClient creates a CommandRunner connected to a temenos daemon. addr formats:

• Empty string: resolve from TEMENOS_LISTEN_ADDR → TEMENOS_SOCKET_PATH → default socket
• Starts with "/" or ".": unix socket path
• Starts with "http://": HTTP base URL (TCP)
• Otherwise (e.g. ":8081", "localhost:8081"): TCP

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 []AllowedPath
}

Config holds everything needed to run one agent loop iteration.

type PromptData

type PromptData struct {
	WorkingDir string
	Platform   string
	Date       string
	Commands   []CommandDoc // caller-provided command documentation
}

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

type RunRequest

type RunRequest = client.RunRequest

RunRequest is the request payload for sandboxed command execution.

type RunResponse

type RunResponse = client.RunResponse

RunResponse is the response from sandboxed command execution.

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
	Reasoning          string // thinking block text (empty if no reasoning)
	ReasoningSignature string // provider signature for round-trip
	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" // LLM turn (with or without commands)
	StepRoleUser      StepRole = "user"      // human input
	StepRoleResult    StepRole = "result"    // command output fed back to LLM
)