SimpleFunctions Developer Manual

This is an advanced operator checklist for an unattended or semi-attended SimpleFunctions CLI agent. Use it after you understand Quickstart, Agentic CLI, and Headless agent. The headless page explains the interface; this page explains how to operate it without accidentally turning research automation into uncontrolled execution. This page is intentionally not part of the first-run path. Most users should start with the CLI quickstart and only come here when promoting a recurring job.

Operating principle

Production agents should run in phases:

Phase	Allowed by default	Purpose
Diagnose	read, diagnostic	Verify CLI, auth, JSON, manifest, and user-data readiness.
Read	read, user_data, market_data, research	Build current context and candidate actions.
Propose	none beyond read	Emit commands it wants to run, with reasons and side-effect class.
Approve	human or policy service	Decide whether writes, runtime, or trade actions are allowed.
Execute	explicit allowlist only	Run approved write/runtime/trade commands.
Audit	diagnostic, read	Save 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:

Command	Healthy signal
`sf status --json`	Config, API URL, auth, exchange, and runtime status are visible.
`sf doctor --agent --deep --json`	Public health, world JSON, manifest truth, and intended user reads are `ok`.
`sf describe --all --json`	Manifest parses as one JSON array.
`sf guide --agent --json`	Local playbook parses without network dependency.
`sf tools plan ... --json`	Returns 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:

Class	Meaning	Examples
`none`	Read-only or diagnostic.	`world`, `discover`, `inspect`, `book`, `trace receipt`
`write`	Mutates SimpleFunctions state but does not hit an exchange.	`watchlist add`, `alerts create`, `monitor create`, `thesis signal`
`runtime`	Starts or stops a local daemon.	`runtime start`, `quoteengine start`
`trade`	Creates 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:

Question	Evidence
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

Symptom	First response
`doctor` public health fails	Check network/sandbox first; then retry `sf world --json`.
JSON parse fails	Run `sf doctor --agent --deep --json`; inspect the failing check id.
Agent proposes direct order	Reject; ask for an intent or paper quote proposal with pre-read context.
Runtime is running unexpectedly	`sf runtime status --json`, then human-approved `sf runtime stop`.
QuoteEngine is running unexpectedly	`sf quoteengine status --json`, then human-approved `sf quoteengine stop`.
Output too large	Use `--limit`, `--since`, `--hours`, `--cursor`, or `--include` flags.
Tool output on stderr	Keep stdout for JSON/protocol, stderr for progress and warnings.

Promotion checklist

Before promoting a new agent prompt, model, or workflow:

Run it read-only with --deny trade,runtime,fs,write.
Record trace.
Run sf trace receipt.
Replay the same trace when possible.
Check it never depends on rendered UI or terminal tables.
Check it proposes side-effecting commands instead of running them.
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.

​Operating principle

​Boot sequence

​Default policy

​Side-effect classes

​Cron pattern

​Claude Code or Codex host

​Approval packet

​Trace and receipt

​Recovery

​Promotion checklist

​Related docs