> ## 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.

# SDK and Agent SDK roadmap

> Current SimpleFunctions SDK, Agent SDK, CLI, API, and contract boundaries after the 1.0 release.

This page is the current public status map for SimpleFunctions developer
surfaces. The SDK and Agent SDK are now published as stable packages, while the
CLI and HTTP API remain separate surfaces with their own contracts.

## Current state

| Surface                 | Current status                            | Use it for                                                                                                  |
| ----------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| HTTP API                | Public raw network surface                | Language-neutral access to SimpleFunctions endpoints                                                        |
| CLI                     | Published operator and automation surface | Terminal workflows, local agent loop, headless mode, daemon/runtime controls                                |
| `/api/contracts/tools`  | Strict SDK/Agent contract truth           | Canonical tool names, auth, access, `sideEffect`, `costEffect`, replay metadata                             |
| `/api/tools`            | Broad hosted compatibility inventory      | HTTP-native and MCP compatibility discovery                                                                 |
| `@spfunctions/sdk`      | Published stable, `1.0.1`                 | Typed data, contract client, and governed Kalshi or Polymarket execution primitives for TypeScript          |
| `@spfunctions/agent/v1` | Published stable, `1.0.2`                 | Cursor-style market agent loop, watch primitives, sessions, hooks, strict tools, and policy-gated execution |
| Low-level direct runner | Included in `@spfunctions/agent`          | Deterministic canonical tool calls, local trace, and replay harnesses                                       |

## Which surface should I use?

Use the HTTP API if:

* you are not writing TypeScript
* you need direct control over requests and response handling
* you are integrating from a service that already owns auth, retries, and error mapping

Use the CLI if:

* a human, shell script, CI job, or coding agent is operating from a terminal
* you want the richer `sf agent` local loop
* you need headless NDJSON tooling
* you need local runtime controls such as `sf runtime`

Use the SDK if:

* you are writing TypeScript
* you want typed reads and stable resource objects
* you want API-key-first client behavior
* you want strict manifest inspection through `sf.manifest.*`
* you need K-line/OHLCV candle reads and watchlist-first screening through `sf.markets.candles()` and `sf.markets.screenCandles()`
* you need Kalshi or Polymarket `execution.place`, runtime orchestration, and intent management with explicit auth

Use the Agent SDK if:

* you already have an application, worker, or agent harness
* you want a Cursor-style `Agent.create().send().stream()` lifecycle
* you want SimpleFunctions strict tools mounted into a model loop
* you need policy hooks, `sideEffect`, `costEffect`, sessions, watch inputs, local trace, and replay
* you want to compose research, monitoring, execution, and management agents behind configurable safety valves

Use the low-level direct runner only when you need deterministic canonical tool calls without a model loop.

## What is not shipped

These are not shipped as stable SDK/Agent capabilities:

* GA semver compatibility
* browser runtime or long-lived browser API keys
* MCP runtime inside the Agent SDK
* `events.*`
* `market.related` semantic graph
* `auth.status`
* `investigations.create`
* `intents.propose`
* `webhooks.create`

`runtime.status` and `runtime.ensure` are canonical SDK methods for runtime readiness. `live_trade` is a side-effect class and compatibility alias for `execution.place`; it is not a canonical SDK method.

## Tool truth hierarchy

For SDK and Agent SDK work, use this hierarchy:

| Source                     | Meaning                                      |
| -------------------------- | -------------------------------------------- |
| `GET /api/contracts/tools` | Strict SDK/Agent contract truth              |
| `sf describe --all --json` | Local installed CLI command manifest         |
| `GET /api/tools`           | Broad hosted compatibility inventory         |
| MCP tools                  | Adapter inventory for MCP-compatible clients |

Do not treat `/api/tools` or MCP names as SDK/Agent canonical names.

For example:

```text theme={null}
world.read       canonical SDK/Agent tool
get_world_state  broad compatibility name, not SDK/Agent truth
```

## Roadmap

The current sequence is:

1. Keep the current stable SDK and Agent SDK versions pinned in examples and customer projects.
2. Keep execution expansion contract-first through `/api/contracts/tools`.
3. Harden watch/model-loop/execution examples against real production workloads.
4. Add public support, rate-limit, and error-handling commitments before GA.
5. Keep 1.x stable releases backward-compatible for direct-runner replay, trace behavior, and policy gates.

Browser runtime, MCP runtime, or broad `/api/tools` aliasing is not part of the current SDK roadmap.