salambo-codex-agent-sdk

TypeScript SDK around codex app-server.

This SDK is a thin runtime boundary for:

• creating and resuming sessions
• starting, steering, and interrupting turns
• streaming raw inbound App Server events
• opting into experimental raw response items when Codex supports them

It is not:

• a custom hook framework
• a Responses-compatible SSE adapter
• a bundled Codex binary distribution

Stability

Stable SDK surface today:

• createSession()
• session.send(prompt)
• session.steer(prompt)
• session.stream()
• session.interrupt()
• session.abort()
• configProfile
• cwd
• systemPrompt
• resume
• ephemeral
• outputSchema

Experimental SDK surface:

• experimentalRawEvents
• rawResponseItem/completed as a product-facing dependency

Guidance:

• build production integrations on the stable session API plus app_server_raw
• treat experimental raw response items as optional diagnostics / research inputs
• do not assume experimental features are always available across Codex runtimes
• build any Responses-compatible SSE layer outside this SDK, on top of the raw App Server stream

Install

pnpm add salambo-codex-agent-sdk

Requirements:

• Node >=20
• Codex installed locally and available via PATH or SALAMBO_CODEX_PATH

Codex Runtime Resolution

Session startup resolves Codex in this order:

1. SALAMBO_CODEX_PATH
2. codex in PATH
3. codex-app-server in PATH

Example override:

export SALAMBO_CODEX_PATH=/absolute/path/to/codex

Codex Version Compatibility

This SDK currently:

• requires Codex >= 0.114.0
• is tested against Codex 0.114.0

If the installed Codex version is older than the supported minimum, session startup fails with a clear error.

Quickstart

session.stream() yields raw inbound app-server messages exactly as they are parsed from stdout, plus local parse-error events when a line cannot be parsed.

Examples:

• notifications: { method, params }
• server requests: { id, method, params }
• responses: { id, result } or { id, error }
• parse failures: { type: "parse_error", line, error }

The raw Responses-style model item is still available at: rawResponseItem/completed.params.item

This raw response item path is experimental. The stable runtime contract of the SDK is still the raw App Server stream from session.stream().

import { createSession } from "salambo-codex-agent-sdk";

await using session = createSession({
  configProfile: "default",
  cwd: process.cwd(),
});

await session.send("Say hello and nothing else.");

for await (const msg of session.stream()) {
  console.log(msg);
}

API

const session = createSession({
  configProfile?: string,
  cwd?: string,
  systemPrompt?: string,
  resume?: string,
  ephemeral?: boolean,
  experimentalRawEvents?: boolean,
  outputSchema?: JsonValue,
});

Session methods:

• await session.send(prompt)
• await session.steer(prompt)
• for await (const event of session.stream()) { ... }
• await session.interrupt()
• session.abort()

Dev Commands

• pnpm build builds the SDK
• pnpm typecheck runs TypeScript checks
• pnpm lint runs ESLint
• pnpm test runs all Vitest suites
• pnpm test:confidence runs the primary local/CI confidence gate
• pnpm test:unit runs unit tests only
• pnpm test:protocol runs the deterministic fake app-server contract suite
• pnpm test:e2e runs the E2E suite
• pnpm test:integration runs integration tests (live tests are opt-in)
• pnpm test:ci runs the deterministic CI profile
• pnpm test:live:isolated runs live integration tests in an isolated Codex home
• pnpm release:patch prepares a patch release
• pnpm release:minor prepares a minor release
• pnpm release:major prepares a major release

Release Flow

Run one command:

pnpm release:patch

It does:

1. pnpm test:confidence
2. npm pack --dry-run
3. npm version patch (creates commit + tag)
4. git push origin HEAD --follow-tags

Optional strict mode:

RUN_LIVE_RELEASE_CHECKS=1 pnpm release:patch

Final publish step stays manual:

npm publish

Isolated Live Test Flow

scripts/test-live-isolated.sh does:

1. Load .env if present.
2. Require OPENAI_API_KEY.
3. Use isolated CODEX_HOME (default /tmp/salambo-codex-home).
4. Run codex login --with-api-key.
5. Set SALAMBO_RUN_LIVE_TESTS=1.
6. Run tests/integration/phase1.test.ts and tests/e2e/upstream.test.ts.

Environment:

• Required: OPENAI_API_KEY
• Optional: SALAMBO_TEST_MODEL (default gpt-5.2-codex)
• Optional: CODEX_HOME (default /tmp/salambo-codex-home)
• Optional: SALAMBO_CODEX_PATH (path to codex or codex-app-server)

Examples:

pnpm test:live:isolated

SALAMBO_TEST_MODEL=gpt-5.2-codex pnpm test:live:isolated

Troubleshooting

If session startup fails:

1. Check that codex --version works, or set SALAMBO_CODEX_PATH
2. Make sure Codex is at least 0.114.0
3. Ensure codex app-server --help works from the same environment