Core 런타임 헬퍼

HTTP 서버를 거치지 않고 agent runtime을 호출하려면 이 API를 사용합니다. 같은 Node 프로세스 안에서 실행되는 로컬 orchestration, 테스트, 도구에 적합합니다.

HTTP 대응 표면은 agent completion, run once, run once stream에 정리되어 있습니다.

Helper 선택 기준

함수 레퍼런스

completion(input)

설정된 runtime을 통해 completion-style call을 한 번 실행합니다. 장기적인 coding session보다 text generation, summarization, classification, lightweight transformation에 가까운 작업에 사용합니다. Runtime 응답이 완료되면 반환됩니다.

주요 option은 prompt, model, systemPrompt, appendSystemPrompt, label, timeout, env, reasoningLevel, providerOptions입니다.

runOnce(input)

runtime을 통해 하나의 agent task를 끝까지 실행하고 최종 결과를 반환합니다. Agent가 plan, tool call, finish를 한 번의 흐름에서 처리할 수 있는 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에는 이미 네이티브 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을 소유합니다. 대부분의 애플리케이션은 getRuntimePool을 사용하면 충분합니다. Test나 embedded host에서 격리가 필요할 때만 직접 생성하십시오.

toClaudeEffort(level)

SNA reasoning level을 Claude 호환 effort 값으로 매핑합니다. Application code 곳곳에 runtime-specific string을 흩뜨리지 말고 runtime adapter에서 사용하십시오.

toCodexEffort(level)

SNA reasoning level을 Codex 호환 effort 값으로 매핑합니다. UI-level reasoning choice를 runtime-neutral하게 유지합니다.

toGrokEffort(level)

Grok runtime adapter가 사용할 수 있도록 SNA reasoning level을 Grok-compatible effort value로 매핑합니다.

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를 다시 쓸 필요가 없습니다.