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.

Status: completed alpha release checklist. This checklist records the gates used before publishing @spfunctions/sdk@0.1.0-alpha.0 and @spfunctions/agent@0.1.0-alpha.0. The alpha packages are now published. This page remains as release evidence and rollback guidance.

​
Current package status

PackageCurrent statusVersionPublish status
@spfunctions/sdkalpha typed data and contract client0.1.0-alpha.0published
@spfunctions/agentalpha governed direct runner plus v1 model loop0.1.0-alpha.0published
@spfunctions/clipublic operator and automation surface3.0.46published
The CLI is not the Agent SDK. sf agent --tool is the command-line wrapper around direct canonical tool semantics.

​
Release boundary

Alpha release means publishing a package for explicit early adopters after approval. It does not mean GA, stable API, or live-trading automation. @spfunctions/sdk alpha scope:
  • typed client over stable SimpleFunctions object and contract surfaces
  • API-key-first identity
  • strict manifest access through GET /api/contracts/tools
  • read, research, authenticated read, and explicit thesis-write surfaces
  • typed errors and contract preflight
@spfunctions/agent alpha scope:
  • governed direct tool runner
  • describe(), call(), and stream()
  • strict canonical tool names only
  • policy gates for permissions, sideEffect, and costEffect
  • trace record/replay
  • live execution through an API-keyed SimpleFunctions client
  • v1 model loop with provider adapter, sessions, hooks, watch primitives, and Cursor-style compatibility
Out of scope:
  • MCP runtime
  • browser runtime with long-lived keys
  • hosted sessions, hosted traces, or human approval services
  • events.*
  • market.related
  • auth.status
  • investigations.create
  • intents.propose
  • webhooks.create
  • live_trade

​
Required gates

GateSDKAgentEvidence required
Package privacy intentionally removed in release PRRequiredRequiredpackage.json has no private:true
Version policy approvedRequiredRequiredrelease issue or PR approval
Package surface snapshotRequiredRequiredexported symbols test
TypecheckRequiredRequiredpackage typecheck passes
Unit testsRequiredRequiredpackage test suite passes
BuildRequiredRequiredpackage build passes
Tarball contentsRequiredRequirednpm pack --dry-run --json guard
Fresh install smokeRequiredRequiredtarball install in temp consumer
No-key behaviorRequiredRequiredmanifest-only SDK bootstrap; Agent live no-key throws
API-key live smokeRequired for readsRequired for world.readproduction world.read smoke with SF_API_KEY
Strict manifest smokeRequiredRequiredschema 0.3.0-draft, canonical names only
Docs validationRequiredRequiredmint validate passes
Browser key warningRequiredRequiredno long-lived browser API key examples
Public install docs after publishRequiredRequireddocs/package README show alpha pin

​
Verification commands

Run these commands as package verification. They do not publish by themselves. Full local readiness gate: 
npm run release-check:sdk-agent-alpha
This command ran the SDK/Agent release gate before publication. It verifies no-key live smoke skips cleanly, dry-runs both package tarballs, inspects tarball contents, and checks package metadata/docs for alpha consistency. Individual checks: 
npm --prefix packages/sdk test
npm --prefix packages/sdk run typecheck
npm --prefix packages/sdk run build

npm --prefix packages/agent test
npm --prefix packages/agent run typecheck
npm --prefix packages/agent run build

npm --prefix packages/agent run pack:smoke
npm --prefix packages/agent run smoke:live

npm test -- src/lib/contracts/tools-manifest.test.ts
cd docs && mint validate
No-key smoke must skip cleanly: 
env -u SF_API_KEY -u SIMPLEFUNCTIONS_API_KEY -u SIMPLEFUNCTIONS_API_TOKEN -u API_KEY \
  npm --prefix packages/agent run smoke:live
Production contract smoke must confirm: 
schemaVersion = 0.3.0-draft
world.read present
world.read.sideEffect = none
world.read.costEffect = api_cost
world.read.access.anonymousAllowed = false
manifest.list/get access.anonymousAllowed = true
active sideEffect values do not include write
get_world_state absent from active strict tools
get_regime_history absent
events.* absent
live_trade absent

​
Manual publish procedure

The following commands are the manual alpha publish shape used by the release operator. Preconditions:
  • approval explicitly says which package to publish
  • private:true has been intentionally removed in a reviewed release PR
  • version has been chosen and committed in git
  • tarball smoke has passed from a clean worktree
  • production smoke has passed
  • npm account is logged in and 2FA OTP is available
SDK publish shape: 
cd packages/sdk
npm pack --dry-run
npm publish --access public --otp <OTP>
Agent publish shape: 
cd packages/agent
npm pack --dry-run
npm publish --access public --otp <OTP>
Do not use a shared SimpleFunctions service key in either package. Do not publish from a stale worktree.

​
Rollback and deprecate plan

If a bad alpha package is published:
  1. Publish a fixed patch version from latest origin/main.
  2. Fresh-install smoke the fixed version.
  3. Deprecate the bad version with an npm 2FA OTP.
  4. Update docs and release notes to point at the fixed version.
CLI reminder: 
npm deprecate @spfunctions/cli@3.0.45 "Stale publish missing sf agent --tool; upgrade to @spfunctions/cli@3.0.46." --otp <OTP>
This is a manual npm auth task if it has not already been completed. It is not a code blocker and must not be retried without OTP.

​
API key policy

SDK and Agent packages are API-key-first.
  • SDK constructor may accept apiKey?: string
  • SDK no-key access is limited to strict manifest inspection and explicitly allowlisted free public reads
  • current no-key SDK live data calls such as sf.world.get() must throw MissingApiKeyError
  • Agent live execution requires an API-keyed SimpleFunctions client
  • Agent inspectOnly and replayOnly may run without a key
  • replay miss must never fall through to live execution
  • browser examples must not expose long-lived API keys
Future scoped browser or session tokens require a separate design.

​
v0 and v1 Agent boundary

@spfunctions/agent v0 is the governed direct tool runner. It is not a model-backed runtime. v0 includes:
  • strict tool registry loading
  • direct canonical calls
  • stream events
  • policy gates
  • trace and replay
  • typed errors
v1 is now an alpha model-loop surface under @spfunctions/agent/v1. v1 alpha includes:
  • query() and startup() APIs
  • model provider interfaces
  • OpenRouter provider
  • local sessions and resume/fork behavior
  • hooks
  • subagents
  • watch primitives
Hosted sessions, hosted traces, human approval services, live trading, and endpoint expansion remain out of scope.

​
Decision checklist

Before approving alpha publish, answer these questions:
QuestionRequired answer
Were both packages private before the release PR?Yes
Did a reviewed release PR remove private:true intentionally?Yes
Are package versions explicit and committed?Yes
Did SDK and Agent package tests pass?Yes
Did SDK and Agent builds pass?Yes
Did pack/fresh-install smoke pass?Yes
Did live smoke pass with SF_API_KEY?Yes
Did no-key smoke skip or fail safely?Yes
Does /api/contracts/tools remain strict truth?Yes
Are /api/tools and MCP still compatibility surfaces only?Yes
Are browser long-lived key examples absent?Yes
Are live trading and write/default Agent tools absent?Yes
If any answer is not “Yes”, do not publish.