SimpleFunctions Developer Manual

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

Current package status

Package	Current status	Version	Publish status
`@spfunctions/sdk`	typed data, contract client, and dual-venue execution client	`1.0.1`	published
`@spfunctions/agent`	governed direct runner plus v1 model loop	`1.0.2`	published
`@spfunctions/cli`	public operator and automation surface	`3.0.47`	ready to publish

The CLI is not the Agent SDK. sf agent --tool is the command-line wrapper around direct canonical tool semantics.

Release boundary

The 1.0 release means publishing the stable TypeScript package surfaces after approval. Live execution remains policy-gated and opt-in. @spfunctions/sdk release 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, explicit thesis-write surfaces, and governed Kalshi/Polymarket execution
typed errors and contract preflight

@spfunctions/agent release scope:

governed direct tool runner
describe(), call(), and stream()
strict canonical tool names only
policy gates for permissions, sideEffect, and costEffect
trace record/replay
policy-gated 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
unguarded live trading

Required gates

Gate	SDK	Agent	Evidence required
Package privacy intentionally removed in release PR	Required	Required	`package.json` has no `private:true`
Version policy approved	Required	Required	release issue or PR approval
Package surface snapshot	Required	Required	exported symbols test
Typecheck	Required	Required	package typecheck passes
Unit tests	Required	Required	package test suite passes
Build	Required	Required	package build passes
Tarball contents	Required	Required	`npm pack --dry-run --json` guard
Source-map leakage	Required	Required	package-surface tests reject `.map`, `.tsbuildinfo`, and JS `sourceMappingURL`
Fresh install smoke	Required	Required	tarball install in temp consumer
No-key behavior	Required	Required	manifest-only SDK bootstrap; Agent live no-key throws
API-key live smoke	Required for reads	Required for `world.read`	production `world.read` smoke with `SF_API_KEY`
Strict manifest smoke	Required	Required	schema `0.3.0-draft`, canonical names only
Docs validation	Required	Required	`mint validate` passes
Mintlify sync gate	Required	Required	public docs/API/SDK/Agent changes reference a merged `simplefunctions-docs` PR
Browser key warning	Required	Required	no long-lived browser API key examples
Public install docs after publish	Required	Required	docs/package README show stable install

Verification commands

Run these commands as package verification. They do not publish by themselves. Full local readiness gate:

npm run release-check:sdk-agent

This command ran the SDK/Agent release gate before publication. It verifies the Mintlify sync gate, no-key live smoke skips cleanly, dry-runs both package tarballs, inspects tarball contents, and checks package metadata/docs for release consistency. Individual checks:

npm run check:mintlify-sync
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

Package hardening gate:

SDK and Agent build must clean stale dist/ before compiling.
SDK and Agent packages must not publish src/, examples, scripts, tests, .env, source maps, declaration maps, or sourceMappingURL.
SDK and Agent should not use CLI-style single-file bundling unless the package API, declarations, subpath exports, and consumer tree-shaking are revalidated.

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 stable 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 stable package is published:

Publish a fixed patch version from latest origin/main.
Fresh-install smoke the fixed version.
Deprecate the bad version with an npm 2FA OTP.
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.47 or later." --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 a model-loop surface under @spfunctions/agent/v1. v1 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, unguarded live trading, and endpoint expansion remain out of scope.

Decision checklist

Before approving stable publish, answer these questions:

Question	Required 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 unguarded live trading and default write Agent tools absent?	Yes

If any answer is not “Yes”, do not publish.

Help

Advanced operations

Historical RFCs

SDK and Agent release checklist

Current package status

Release boundary

Required gates

Verification commands

Manual publish procedure

Rollback and deprecate plan

API key policy

v0 and v1 Agent boundary

Decision checklist

​Current package status

​Release boundary

​Required gates

​Verification commands

​Manual publish procedure

​Rollback and deprecate plan

​API key policy

​v0 and v1 Agent boundary

​Decision checklist

Current package status

Release boundary

Required gates

Verification commands

Manual publish procedure

Rollback and deprecate plan

API key policy

v0 and v1 Agent boundary

Decision checklist