salambo-codex-agent-sdk

TypeScript SDK wrapper around codex app-server, with:

• V2 session API (createSession)
• V1 compat API (query)
• Hooks, approvals, multi-turn, model switching
• Upstream fallback support + fork hook protocol support

Install

pnpm add salambo-codex-agent-sdk

Node requirement: >=20.

Binary Resolution

Session startup resolves the app-server binary in this order:

1. options.codexPath
2. SALAMBO_CODEX_PATH
3. Platform binary package:
   • salambo-codex-bin-darwin-arm64
   • salambo-codex-bin-darwin-x64
   • salambo-codex-bin-linux-arm64
   • salambo-codex-bin-linux-x64
   • salambo-codex-bin-win32-x64
4. codex / codex-app-server in PATH

Supported platform matrix (v1):

• darwin-arm64
• darwin-x64
• linux-arm64
• linux-x64
• win32-x64

Override example:

export SALAMBO_CODEX_PATH=/absolute/path/to/codex-app-server

Quickstart (V2)

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

await using session = createSession({
  model: "gpt-5.2-codex",
  provider: "openai",
  permissionMode: "bypassPermissions",
});

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

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

Quickstart (V1 compat)

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

for await (const msg of query({
  prompt: "Say hello",
  options: { model: "gpt-5.2-codex", provider: "openai" },
})) {
  console.log(msg);
}

Dev Commands

• pnpm build builds the SDK
• pnpm typecheck runs TypeScript checks
• pnpm lint runs ESLint
• pnpm test runs unit + integration (live integration is opt-in only)
• pnpm test:unit runs unit tests only
• pnpm test:integration runs integration suite (live tests still opt-in)
• pnpm test:hooks runs hook-focused unit tests
• pnpm test:ci runs deterministic CI profile
• pnpm test:live:isolated runs live integration tests in an isolated Codex home
• pnpm test:live:fork-isolated runs live fork hook E2E tests in an isolated Codex home
• pnpm release:patch release prep (checks + bump + tag + push)
• pnpm release:minor same flow for minor releases
• pnpm release:major same flow for major releases

Release Flow (release-please style, manual)

Run one command:

pnpm release:patch

It does:

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

Optional strict mode (includes live tests):

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.

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 forked codex or codex-app-server binary; default codex)

Examples:

pnpm test:live:isolated

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

Fork hook E2E:

SALAMBO_CODEX_PATH=/absolute/path/to/codex-app-server pnpm test:live:fork-isolated

This script writes an isolated CODEX_HOME/config.toml with:

[hook_protocol]
enabled = true
pre_tool_use = true
post_tool_use = true

Binary Troubleshooting

If session startup fails with a binary resolution error:

1. Check platform package install: pnpm ls salambo-codex-bin-<platform>
2. Or set explicit binary path with SALAMBO_CODEX_PATH
3. Or ensure codex is available in PATH