Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.simplefunctions.dev/llms.txt

Use this file to discover all available pages before exploring further.

This is the production checklist for an unattended or semi-attended SimpleFunctions agent. Use it after you understand Headless agent. The headless page explains the interface. This page explains how to operate it without accidentally turning research automation into uncontrolled execution. Last live probe: 2026-05-06 UTC. sf doctor --agent --deep --json returned 224 manifest entries, 172 JSON-capable commands, 162 read-only commands, 46 write commands, 12 trade-level commands, and 4 runtime-level commands.

​
Operating principle

Production agents should run in phases:
PhaseAllowed by defaultPurpose
Diagnoseread, diagnosticVerify CLI, auth, JSON, manifest, and user-data readiness.
Readread, user_data, market_data, researchBuild current context and candidate actions.
Proposenone beyond readEmit commands it wants to run, with reasons and side-effect class.
Approvehuman or policy serviceDecide whether writes, runtime, or trade actions are allowed.
Executeexplicit allowlist onlyRun approved write/runtime/trade commands.
Auditdiagnostic, readSave trace, summarize receipts, record outcome.
Do not let a single prompt both discover an opportunity and place a trade. Split those into separate runs.

​
Boot sequence

Every host should begin with the same read-only checks: 
sf status --json
sf doctor --agent --deep --json
sf describe --all --json
sf guide --agent --json
sf tools plan "task" --json
Expected behavior:
CommandHealthy signal
sf status --jsonConfig, API URL, auth, exchange, and runtime status are visible.
sf doctor --agent --deep --jsonPublic health, world JSON, manifest truth, and intended user reads are ok.
sf describe --all --jsonManifest parses as one JSON array.
sf guide --agent --jsonLocal playbook parses without network dependency.
sf tools plan ... --jsonReturns ordered commands and side-effect metadata.
If doctor fails because the sandbox cannot reach the network, rerun outside the sandbox before declaring the surface broken.

​
Default policy

For production research jobs: 
sf agent --plain \
  --new \
  --allow read,user_data,research \
  --deny trade,runtime,fs,write \
  --budget-usd 0.25 \
  --once "Summarize material changes, candidate markets, and next read-only checks."
For jobs that may write non-trading workflow state, remove write from --deny only after approval: 
sf agent --plain \
  --new \
  --allow read,user_data,research,write \
  --deny trade,runtime,fs \
  --budget-usd 0.25 \
  --once "Create an approved watchlist item and alert. Do not create intents or start runtime."
Do not add trade or runtime to unattended cron, CI, or external coding-agent prompts.

​
Side-effect classes

Use sf describe --all --json as ground truth. Current side-effect classes include:
ClassMeaningExamples
noneRead-only or diagnostic.world, discover, inspect, book, trace receipt
writeMutates SimpleFunctions state but does not hit an exchange.watchlist add, alerts create, monitor create, thesis signal
runtimeStarts or stops a local daemon.runtime start, quoteengine start
tradeCreates exchange-facing intent or order behavior.intent buy, buy, quote create, quoteengine stop
Production approval should be keyed to this class, not to free-form command text.

​
Cron pattern

Use cron for read-only recurring review: 
15 * * * * /usr/bin/env bash -lc 'mkdir -p "$HOME/.sf/logs" "$HOME/.sf/traces"; sf agent --plain --new --allow read,user_data,research --deny trade,runtime,fs,write --budget-usd 0.25 --record-trace "$HOME/.sf/traces/hourly-$(date +\%Y-\%m-\%d-\%H).ndjson" --once "Run hourly market/thesis review. Return material changes, candidate tickers, and commands for human approval. Do not write state or trade." >> "$HOME/.sf/logs/hourly-agent.log" 2>&1'
Keep trace files and logs separate. Trace files are for structured audit. Logs are for process and stderr output.

​
Claude Code or Codex host

When Claude Code, Codex, or another coding agent drives sf, give it command boundaries: 
Allowed without approval:
- sf status --json
- sf doctor --agent --deep --json
- sf describe --all --json
- sf tools search ... --json
- sf tools plan ... --json
- sf world ... --json
- sf discover --quality --json
- sf investigate ... --json
- sf query ... --json
- sf inspect ... --json
- sf book ... --json
- sf trace receipt ... --json

Approval required:
- sf thesis signal ...
- sf watchlist add ...
- sf alerts create ...
- sf monitor create ...
- sf webhooks add/test ...

Never unattended:
- sf buy / sell / cancel
- sf intent buy / sell / cancel
- sf runtime start / stop
- sf quote create / pause / resume / cancel
- sf quoteengine start / stop
Use sf tools plan "<task>" --json before writing custom command plans. The live plan includes skipped side effects and candidate tools.

​
Approval packet

Before any write, runtime, or trade action, the agent should emit: 
{
  "command": "sf alerts create --watch <watch-id> --type price_above --threshold 60 --json",
  "side_effect_level": "write",
  "reason": "Alert is needed for the approved monitored market.",
  "inputs_checked": [
    "sf watchlist list --json",
    "sf inspect KX... --json"
  ],
  "rollback": "sf alerts delete <id> --json",
  "requires_human": true
}
For trade or runtime commands, include portfolio state, active intents, runtime status, and explicit stop command.

​
Trace and receipt

Record every production agent run: 
sf agent --plain \
  --new \
  --allow read,user_data,research \
  --deny trade,runtime,fs,write \
  --record-trace traces/review.ndjson \
  --once "Review active thesis risk."
Summarize the trace: 
sf trace receipt traces/review.ndjson --json
Use receipts in CI, incident review, and model comparisons. A production trace should answer:
QuestionEvidence
What tools did the agent call?Trace receipt tool list.
Did it attempt a blocked action?Policy and stderr logs.
What did it spend?Agent usage in trace and run logs.
What state changed?Approval packet plus command output.

​
Recovery

SymptomFirst response
doctor public health failsCheck network/sandbox first; then retry sf world --json.
JSON parse failsRun sf doctor --agent --deep --json; inspect the failing check id.
Agent proposes direct orderReject; ask for an intent or paper quote proposal with pre-read context.
Runtime is running unexpectedlysf runtime status --json, then human-approved sf runtime stop.
QuoteEngine is running unexpectedlysf quoteengine status --json, then human-approved sf quoteengine stop.
Output too largeUse --limit, --since, --hours, --cursor, or --include flags.
Tool output on stderrKeep stdout for JSON/protocol, stderr for progress and warnings.

​
Promotion checklist

Before promoting a new agent prompt, model, or workflow:
  1. Run it read-only with --deny trade,runtime,fs,write.
  2. Record trace.
  3. Run sf trace receipt.
  4. Replay the same trace when possible.
  5. Check it never depends on rendered UI or terminal tables.
  6. Check it proposes side-effecting commands instead of running them.
  7. Run one live dry-run workflow such as sf workflow demo monitor --dry-run --json.

Headless agent

Interface patterns for sf agent --plain and sf agent --headless.

Evaluation and replay

Trace receipts, replay, backtests, and model comparison.

Agentic CLI

Full command control plane and permission categories.

Trade intents

Declarative execution boundary.