Core Runtime Helpers
Direct runtime helpers exported from `@sna-sdk/core`.
Core Runtime Helpers
Use these APIs when you want to invoke the agent runtime without going through the HTTP server. They are useful for local orchestration, tests, and tools that already run in the same Node process.
| Surface | Purpose |
|---|---|
completion(input) | Runs a single completion-style runtime call. |
runOnce(input) | Runs one agent task and returns the final result. |
getRuntimePool() | Returns the shared runtime pool used to manage runtime processes. |
RuntimePool | Runtime pool class for advanced lifecycle control. |
toClaudeEffort(level) | Maps SNA reasoning levels to Claude-oriented effort values. |
toCodexEffort(level) | Maps SNA reasoning levels to Codex-oriented effort values. |
toGrokEffort(level) | Maps SNA reasoning levels to Grok-compatible effort values. |
toCursorEffortSuffix(level) / applyCursorReasoning(...) | Maps reasoning levels into Cursor CLI arguments. |
buildCanonicalFromDb(...) | Rebuilds canonical history from persisted database rows. |
The HTTP equivalents are documented under agent completion, run once, and run once stream.
Choosing the right helper
| Need | Use |
|---|---|
| Text generation without tools or a persistent session | completion |
| A self-contained agent task that can use tools and then finish | runOnce |
| Long-lived interactive sessions | createSnaApp or SnaClient.agent.start/send |
| Runtime process reuse across several direct calls | getRuntimePool() |
Function reference
completion(input)
Runs a single completion-style call through the configured runtime. Use it when the task is closer to text generation, summarization, classification, or lightweight transformation than to a long-lived coding session. It returns after the runtime response is complete.
Common options include prompt, model, systemPrompt, appendSystemPrompt, label, timeout, env, reasoningLevel, and providerOptions.
runOnce(input)
Runs one complete agent task through the runtime and returns the final result. Use it for automation where the agent can plan, call tools, and finish without a follow-up conversation.
Common options include message, provider, model, permissionMode, cwd, timeout, systemPrompt, appendSystemPrompt, reasoningLevel, and providerOptions.
Codex providerOptions
When provider: "codex" is selected, providerOptions.profile is passed to both codex app-server and codex exec as --profile <name>. providerOptions.config is a record of Codex -c key=value overrides; SNA passes those overrides to both runtime paths and includes the object in the runtime-pool key so sessions with different Codex config do not share the same daemon. providerOptions.serviceTier remains the request-priority lane ("priority", "flex", or "batch").
OpenRouter or local OpenAI-compatible endpoints
Use the Codex runtime for OpenAI-compatible gateways. SNA does not expose a
runtime-neutral apiBaseUrl, because the supported endpoint override surface
differs by runtime. Codex already has a native model-provider configuration
surface, so SNA forwards it through providerOptions.config.
The endpoint must match the wire API supported by your installed Codex CLI.
Codex 0.132.0 expects wire_api = "responses" for custom providers; a
legacy chat-completions-only endpoint is not enough for this path.
process.env.OPENROUTER_API_KEY = "...";
await completion({
provider: "codex",
model: "openrouter/model-id",
prompt: "Implement the requested change.",
providerOptions: {
config: {
model_provider: "openrouter",
"model_providers.openrouter.name": "OpenRouter",
"model_providers.openrouter.base_url": "https://openrouter.ai/api/v1",
"model_providers.openrouter.env_key": "OPENROUTER_API_KEY",
"model_providers.openrouter.wire_api": "responses",
},
},
});For a local model server, keep the same shape and replace the provider id,
base_url, env_key, and model with values accepted by that server. Do
not route OpenRouter or local OpenAI-compatible servers through Claude Code's
Anthropic environment variables; that bypasses the Codex harness SNA is meant
to preserve.
getRuntimePool()
Returns the shared runtime pool used by the process. Use this when multiple call sites should reuse the same runtime process management instead of creating independent pools.
RuntimePool
Owns runtime lifecycle. Most applications should use getRuntimePool; construct RuntimePool directly only when isolation is required for tests or embedded hosts.
toClaudeEffort(level)
Maps SNA reasoning levels into Claude-compatible effort values. Use it in runtime adapters rather than scattering runtime-specific strings across application code.
toCodexEffort(level)
Maps SNA reasoning levels into Codex-compatible effort values. It keeps UI-level reasoning choices runtime-neutral.
toGrokEffort(level)
Maps SNA reasoning levels into Grok-compatible effort values for the Grok runtime adapter.
toCursorEffortSuffix(level) / applyCursorReasoning(...)
Builds Cursor CLI reasoning arguments from the runtime-neutral reasoning level. Use these helpers only in runtime adapters or host code that launches Cursor directly.
Reasoning levels
SNA exposes one reasoningLevel scale so UI and SDK callers do not need runtime-specific effort strings.
| Level | Meaning | Claude mapping | Codex mapping |
|---|---|---|---|
0 | Minimal or disabled reasoning | low | none |
1 | Very light reasoning | low | minimal |
2 | Light reasoning | medium | low |
3 | Balanced reasoning | high | medium |
4 | Heavy reasoning | xhigh | high |
5 | Maximum reasoning | max | xhigh |
Runtime adapters may ignore unsupported levels. Codex minimal can be incompatible with some built-in tools, so production UIs should expose level 1 only when they also control the allowed tool set.
buildCanonicalFromDb(...)
Reconstructs canonical history from database rows. Use it when a server process needs to replay persisted history into a runtime-neutral actor/kind shape.
Canonical history uses actor and kind rather than runtime-specific message names. That lets the same stored session replay into Claude Code, Codex, OpenCode, or another adapter without rewriting the database rows.