Core ランタイムヘルパー

HTTP server を経由せずに agent runtime を呼び出したい場合に使う API です。同じ Node process 内で動く local orchestration、test、tool に適しています。

HTTP 側の対応 API は agent completion、run once、run once stream にまとまっています。

Helper の選び方

関数リファレンス

completion(input)

設定された runtime 経由で completion-style call を 1 回実行します。長期の coding session よりも text generation、summarization、classification、lightweight transformation に近い作業に使います。Runtime response が完了すると返ります。

主な option は prompt、model、systemPrompt、appendSystemPrompt、label、timeout、env、reasoningLevel、providerOptions です。

runOnce(input)

runtime 経由で 1 つの agent task を最後まで実行し、最終結果を返します。Agent が plan、tool call、finish を 1 回の流れで処理できる automation に使います。

主な option は message、provider、model、permissionMode、cwd、timeout、systemPrompt、appendSystemPrompt、reasoningLevel、providerOptions です。

Codex providerOptions

provider: "codex" を選ぶと、providerOptions.profile は codex app-server と codex exec の両方に --profile <name> として渡されます。providerOptions.config は Codex の -c key=value override 一覧です。SNA はこの override を両方の実行経路に渡し、runtime pool key にも含めるため、Codex 設定が異なるセッションが同じデーモンを共有しません。providerOptions.serviceTier は従来通り、リクエスト優先度レーン ("priority", "flex", "batch") を指定します。

OpenRouter またはローカル OpenAI-compatible endpoint

OpenAI-compatible gateway は Codex runtime で接続してください。SNA はランタイム中立の apiBaseUrl を提供しません。Endpoint override の対応方法がランタイムごとに 異なるためです。Codex には native の model-provider 設定があり、SNA はその値を providerOptions.config からそのまま渡します。

Endpoint は、インストール済みの Codex CLI が対応する wire API と一致している必要があります。 Codex 0.132.0 では custom provider に wire_api = "responses" が必要です。 legacy chat-completions-only endpoint だけではこの経路は使えません。

process.env.OPENROUTER_API_KEY = "...";

await completion({
  provider: "codex",
  model: "openrouter/model-id",
  prompt: "依頼された変更を実装してください。",
  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",
    },
  },
});

ローカルモデルサーバーも同じ形を使い、provider id、base_url、env_key、 model をそのサーバーが受け付ける値に置き換えます。OpenRouter やローカル OpenAI-compatible server を Claude Code の Anthropic 環境変数で迂回しないでください。 それでは SNA が維持したい Codex harness を使えません。

getRuntimePool()

現在の process が使う shared runtime pool を返します。複数の call site が独立 pool を作らず、同じ runtime process management を再利用したい場合に使います。

RuntimePool

runtime lifecycle を所有します。ほとんどの application では getRuntimePool で十分です。Test や embedded host で隔離が必要な場合だけ直接作成してください。

toClaudeEffort(level)

SNA reasoning level を Claude-compatible effort value へ mapping します。Application code に runtime-specific string を散らさず、runtime adapter で使ってください。

toCodexEffort(level)

SNA reasoning level を Codex-compatible effort value へ mapping します。UI-level reasoning choice を runtime-neutral に保ちます。

toGrokEffort(level)

Grok runtime adapter が使えるように、SNA reasoning level を Grok-compatible effort value へ mapping します。

toCursorEffortSuffix(level) / applyCursorReasoning(...)

Runtime-neutral reasoning level から Cursor CLI reasoning argument を作ります。Runtime adapter または Cursor を直接起動する host code だけで使ってください。

Reasoning level

SNA は、UI や SDK caller が runtime-specific effort string を知らなくて済むよう、単一の reasoningLevel scale を提供します。

Runtime adapter は、未対応の level を無視する場合があります。Codex minimal は一部の built-in tool と相性が悪いことがあるため、production UI では allowed tool set まで制御できる場合にだけ level 1 を出すのが安全です。

buildCanonicalFromDb(...)

database row から canonical history を再構成します。Server process が保存済み history を runtime-neutral な actor/kind 形式で replay する必要がある場合に使います。

Canonical history は runtime-specific message name ではなく actor と kind を使います。そのため、同じ stored session を Claude Code、Codex、OpenCode、その他 adapter へ replay するときに database row を書き換える必要がありません。