@skelm/codex 0.3.9

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Scott Glover
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,131 @@
+# @skelm/codex
+
+> OpenAI Codex backend for [skelm](https://github.com/scottgl9/skelm) — wraps the official [`@openai/codex-sdk`](https://github.com/openai/codex/blob/main/sdk/typescript/README.md) with full skelm permission enforcement, MCP injection, skill loading, and streaming.
+
+[![npm](https://img.shields.io/npm/v/@skelm/codex)](https://www.npmjs.com/package/@skelm/codex)
+
+Part of [skelm](https://github.com/scottgl9/skelm).
+
+Codex authenticates via the host `codex` CLI (`codex login`) or the `CODEX_API_KEY` env var. The SDK spawns codex under the hood and exchanges JSONL events — skelm enforces permissions at the boundary, pins the workspace, optionally routes egress through the gateway's CONNECT proxy, and emits audit events as Codex completes commands, file changes, and MCP tool calls.
+
+| Capability         | Value                                                          |
+|--------------------|----------------------------------------------------------------|
+| `prompt`           | `false` (codex-sdk is agent-loop only)                         |
+| `streaming`        | `true` (`agent_message` text deltas flow to `onPartial`)       |
+| `sessionLifecycle` | `true` (`request.sessionId` → `Codex.resumeThread`)            |
+| `mcp`              | `true` (skelm MCP servers injected via `config.mcp_servers`)   |
+| `skills`           | `true` (skill bodies concatenated into the system prompt)      |
+| `toolPermissions`  | `'native'` (Codex enforces sandbox / approval / network in its own process; skelm checks at the boundary) |
+
+## Prerequisites
+
+- `codex` CLI on PATH (`codex --version` ≥ 0.130.0)
+- Authenticated session — `codex login` once, or `CODEX_API_KEY` in env
+
+## Install
+
+```bash
+npm install @skelm/codex
+```
+
+## Quick start
+
+```ts
+// skelm.config.ts
+import { defineConfig } from 'skelm'
+
+export default defineConfig({
+  backends: {
+    agent: 'codex',
+    codex: {
+      model: 'gpt-5.3-codex',
+      modelReasoningEffort: 'medium',
+      skipGitRepoCheck: true,
+    },
+  },
+  defaults: {
+    permissions: {
+      networkEgress: 'deny',
+      allowedTools: [],
+      allowedExecutables: [],
+      allowedSkills: [],
+      allowedMcpServers: [],
+      fsRead: [],
+      fsWrite: [],
+    },
+  },
+})
+```
+
+```ts
+// codex-smoke.pipeline.ts
+import { agent, pipeline } from 'skelm'
+import { z } from 'zod'
+
+export default pipeline({
+  id: 'codex-smoke',
+  input:  z.object({ task: z.string() }),
+  output: z.object({ result: z.string() }),
+  steps: [
+    agent({
+      id: 'work',
+      backend: 'codex',
+      prompt: (ctx) => (ctx.input as { task: string }).task,
+      permissions: {
+        // For a real read-write workflow grant fsWrite roots + relevant tools.
+        // The mapper refuses fsWrite: ['*'] unless approval policy is empty.
+        fsRead: [],
+        fsWrite: [],
+        networkEgress: 'deny',
+      },
+    }),
+  ],
+})
+```
+
+```bash
+skelm run codex-smoke.pipeline.ts --input '{"task":"say ok"}'
+```
+
+## Permission mapping
+
+The boundary-time mapper translates a resolved skelm policy into Codex SDK options. If the policy can't be honored safely, it throws `CodexPermissionError` before any Codex invocation.
+
+| Skelm policy                                | Codex SDK option                                              |
+|---------------------------------------------|---------------------------------------------------------------|
+| `fsWrite: []`, `fsRead: []`                 | `sandboxMode: 'read-only'`                                    |
+| `fsWrite: [<roots>]`                        | `sandboxMode: 'workspace-write'`, first root → `workingDirectory`, rest → `additionalDirectories` |
+| `request.cwd` set                           | overrides `workingDirectory`                                  |
+| `fsWrite: ['*']` AND no approval policy     | `sandboxMode: 'danger-full-access'`                           |
+| `fsWrite: ['*']` AND approval policy set    | **refused** — never silently escalate                         |
+| `networkEgress: 'deny'`                     | `networkAccessEnabled: false`                                 |
+| `networkEgress: 'allow'` or `{ allowHosts }` | `networkAccessEnabled: true` (gateway proxy enforces hosts)  |
+| `approval.on` covers `tool` / `executable`  | `approvalPolicy: 'untrusted'`                                 |
+| anything else                               | `approvalPolicy: 'on-request'`                                |
+
+## MCP, skills, streaming
+
+- **MCP** — `request.mcpServers` is filtered by `policy.allowedMcpServers`, then passed to `Codex({ config: { mcp_servers: { … } } })`. Stdio transports are translated today; HTTP/SSE transports are dropped with `permission.denied` audit so the gap is visible.
+- **Skills** — When `request.skills` is set and the policy permits, the backend calls `context.loadSkill(id)` for each id and concatenates the formatted skill blocks into the system prompt.
+- **Streaming** — `agent_message.text` deltas flow to `BackendContext.onPartial`. `command_execution`, `file_change`, and `mcp_tool_call` items surface via `onItem` for audit emission.
+
+## API surface
+
+- `createCodexBackend(options?: CodexBackendOptions): SkelmBackend` — the factory.
+- `mapPermissionsToCodex({ policy, workingDirectory })` — boundary mapper; throws `CodexPermissionError` on unsafe widening.
+- `buildAuditEntry(...)` — hash-chained-audit-ready record of the mapping decision.
+- `filterIds(ids, allowlist)` — partition step-requested ids by an allowlist.
+- Re-exports: `CodexPermissionError`, types `CodexBackendOptions`, `MappedCodexPolicy`, `CodexPermissionAuditEntry`.
+
+## Live integration test
+
+```bash
+codex login
+SKELM_CODEX_INTEGRATION=1 pnpm test packages/codex/test/integration.test.ts
+```
+
+The skill-injection test registers a `magic-word` skill and asserts the agent surfaces the skill-provided answer — a real end-to-end verification.
+
+## License
+
+MIT

package/dist/backend.d.ts

@@ -0,0 +1,21 @@
+import type { SkelmBackend } from '@skelm/core';
+import type { CodexBackendOptions } from './types.js';
+/**
+ * SkelmBackend for OpenAI Codex via the official `@openai/codex-sdk`.
+ *
+ * Surfaces the full skelm feature set against Codex:
+ *
+ *   - MCP servers injected through `CodexOptions.config.mcp_servers`.
+ *   - Skills concatenated into the system prompt before each turn.
+ *   - Permissions translated to Codex sandbox + approval modes.
+ *   - Streaming events relayed via `BackendContext.onPartial`.
+ *   - Session resumption via `Codex.resumeThread`.
+ *   - Cancellation via the SDK's per-turn `signal: AbortSignal`.
+ *
+ * Permission enforcement is `'native'`: Codex enforces sandbox / approval /
+ * network natively in its own process. Skelm validates at the boundary
+ * (pre-run refusal, workspace pinning, egress proxy envelope, post-event
+ * audit) — never widening what the policy permits.
+ */
+export declare function createCodexBackend(options?: CodexBackendOptions): SkelmBackend;
+//# sourceMappingURL=backend.d.ts.map

package/dist/backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAOV,YAAY,EACb,MAAM,aAAa,CAAA;AAUpB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAErD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,mBAAwB,GAAG,YAAY,CA+HlF"}

package/dist/backend.js

@@ -0,0 +1,208 @@
+import { buildSystemPromptFromRequest, loadSkillBodies, resolvePermissions } from '@skelm/core';
+import { buildCodexOptions, buildMcpServerConfig, buildThreadOptions, consumeStream, makeCodexClient, } from './client.js';
+import { mapPermissionsToCodex } from './permission-mapper.js';
+/**
+ * SkelmBackend for OpenAI Codex via the official `@openai/codex-sdk`.
+ *
+ * Surfaces the full skelm feature set against Codex:
+ *
+ *   - MCP servers injected through `CodexOptions.config.mcp_servers`.
+ *   - Skills concatenated into the system prompt before each turn.
+ *   - Permissions translated to Codex sandbox + approval modes.
+ *   - Streaming events relayed via `BackendContext.onPartial`.
+ *   - Session resumption via `Codex.resumeThread`.
+ *   - Cancellation via the SDK's per-turn `signal: AbortSignal`.
+ *
+ * Permission enforcement is `'native'`: Codex enforces sandbox / approval /
+ * network natively in its own process. Skelm validates at the boundary
+ * (pre-run refusal, workspace pinning, egress proxy envelope, post-event
+ * audit) — never widening what the policy permits.
+ */
+export function createCodexBackend(options = {}) {
+    const capabilities = {
+        prompt: false,
+        streaming: true,
+        sessionLifecycle: true,
+        mcp: true,
+        skills: true,
+        modelSelection: options.model !== undefined,
+        // Codex enforces sandbox / approval / network natively in its own process.
+        // Skelm checks at the boundary (refusing unsafe combinations before any
+        // Codex call); Codex enforces at runtime.
+        toolPermissions: 'native',
+    };
+    const backend = {
+        id: options.id ?? 'codex',
+        capabilities,
+        ...(options.label !== undefined && { label: options.label }),
+        async run(request, context) {
+            // When neither the request nor the context carries a resolved policy,
+            // synthesize an empty-deny ResolvedPolicy from `resolvePermissions(
+            // undefined, undefined)`. This matches the documented default-deny
+            // intent of skelm: an omitted policy must deny everything, not crash
+            // the run. Previously we threw "codex backend requires a resolved
+            // permission policy" here, which forced every codex agent() step to
+            // restate the same empty allowlists even when config-level defaults
+            // were set. The mapper below still translates this into Codex's
+            // strictest sandbox/approval/network settings.
+            const policy = request.permissions ?? context.permissions ?? resolvePermissions(undefined, undefined);
+            // Boundary check + sandbox/approval translation. Throws on refusal.
+            const mapped = mapPermissionsToCodex({
+                policy,
+                ...(request.cwd !== undefined && { workingDirectory: request.cwd }),
+            });
+            // Filter requested MCP servers through the allowlist.
+            const allowed = filterAllowedMcp(request.mcpServers, policy.allowedMcpServers);
+            const mcpConfig = buildMcpServerConfig(allowed.allowed);
+            const deniedMcp = allowed.denied.map((s) => s.id);
+            // Audit-only for now; the runner's audit writer is the durable record.
+            const logDenial = (dimension, ids, reason) => console.warn(JSON.stringify({ event: 'permission.denied', dimension, ids, reason, backend: 'codex' }));
+            if (deniedMcp.length > 0) {
+                logDenial('mcp', deniedMcp, 'not-in-allowlist');
+            }
+            if (mcpConfig !== null && mcpConfig.dropped.length > 0) {
+                logDenial('mcp', mcpConfig.dropped, 'transport-unsupported');
+            }
+            // Construct the SDK client with config + proxy env. Only forward
+            // `mcp_servers` to Codex — never leak the `dropped` bookkeeping field.
+            const codexOpts = buildCodexOptions(options, {
+                ...(context.proxyEnv !== undefined && { env: context.proxyEnv }),
+                ...(mcpConfig !== null && { config: { mcp_servers: mcpConfig.mcp_servers } }),
+            });
+            const codex = makeCodexClient(codexOpts);
+            // Compose the system prompt via @skelm/core's shared builder so
+            // systemPromptMode / systemPromptIncludeAgentDef take effect here.
+            const systemPrompt = await composeSystemPrompt(request, context, options.model);
+            const userPrompt = systemPrompt === undefined ? request.prompt : `${systemPrompt}\n\n---\n\n${request.prompt}`;
+            // Build the thread (resume vs fresh) honoring per-step sandbox/approval.
+            const threadOpts = buildThreadOptions(options, {
+                sandboxMode: mapped.sandboxMode,
+                approvalPolicy: mapped.approvalPolicy,
+                networkAccessEnabled: mapped.networkAccessEnabled,
+                webSearchEnabled: mapped.webSearchEnabled,
+                webSearchMode: mapped.webSearchMode,
+                ...(mapped.workingDirectory !== undefined && {
+                    workingDirectory: mapped.workingDirectory,
+                }),
+                ...(mapped.additionalDirectories !== undefined && {
+                    additionalDirectories: mapped.additionalDirectories,
+                }),
+            });
+            const sessionId = readSessionId(request);
+            const thread = sessionId !== undefined
+                ? codex.resumeThread(sessionId, threadOpts)
+                : codex.startThread(threadOpts);
+            // Compose abort: the runner-supplied `context.signal` AND the
+            // backend's `timeoutMs` (defensive ceiling). The SDK honors a single
+            // AbortSignal on TurnOptions natively.
+            const turnSignal = composeAbortSignal(context.signal, options.timeoutMs ?? 300_000);
+            const { events } = await thread.runStreamed(userPrompt, {
+                ...(request.outputSchema !== undefined && { outputSchema: request.outputSchema }),
+                signal: turnSignal.signal,
+            });
+            let result;
+            try {
+                result = await consumeStream(events, {
+                    ...(context.onPartial !== undefined && { onText: context.onPartial }),
+                });
+            }
+            finally {
+                turnSignal.cancel();
+            }
+            const response = {
+                text: result.finalText,
+                stopReason: result.stopReason,
+            };
+            if (result.usage !== undefined) {
+                response.usage = {
+                    ...(result.usage.inputTokens !== undefined && { inputTokens: result.usage.inputTokens }),
+                    ...(result.usage.outputTokens !== undefined && {
+                        outputTokens: result.usage.outputTokens,
+                    }),
+                    ...(result.usage.reasoningTokens !== undefined && {
+                        reasoningTokens: result.usage.reasoningTokens,
+                    }),
+                };
+            }
+            return response;
+        },
+    };
+    return backend;
+}
+function filterAllowedMcp(servers, allowlist) {
+    if (servers === undefined || servers.length === 0)
+        return { allowed: [], denied: [] };
+    const allowed = [];
+    const denied = [];
+    for (const s of servers) {
+        if (allowlist.has(s.id))
+            allowed.push(s);
+        else
+            denied.push(s);
+    }
+    return { allowed, denied };
+}
+async function composeSystemPrompt(req, ctx, model) {
+    // Route through @skelm/core's shared builder so `systemPromptMode` and
+    // `systemPromptIncludeAgentDef` actually take effect on codex. Without
+    // this, codex previously hand-rolled the prompt out of soul +
+    // instructions + system + skills, ignoring both flags — the same input
+    // produced identical token counts in extend vs replace mode.
+    //
+    // The builder owns the "extend" vs "replace" composition and the
+    // "include AGENTS.md/SOUL.md when replacing" carve-out. We pass an
+    // empty tool list because codex enforces its tool surface natively and
+    // skelm doesn't dispatch tools through this backend — there's no
+    // skelm-side tool inventory worth injecting.
+    const base = buildSystemPromptFromRequest(req, {
+        cwd: req.cwd ?? process.cwd(),
+        platform: process.platform,
+        date: new Date().toISOString().slice(0, 10),
+        ...(model !== undefined && { model }),
+        tools: [],
+    });
+    const skillBodies = await loadSkillBodies(req, ctx);
+    const parts = [];
+    if (base.length > 0)
+        parts.push(base);
+    parts.push(...skillBodies);
+    if (parts.length === 0)
+        return undefined;
+    return parts.join('\n\n---\n\n');
+}
+/**
+ * AgentRequest doesn't have a typed sessionId field at the moment, but
+ * runners may attach one through structural typing. Read defensively.
+ * TODO(@skelm/core): promote `sessionId?: string` to AgentRequest so this
+ * cast goes away.
+ */
+function readSessionId(request) {
+    const sid = request.sessionId;
+    return typeof sid === 'string' && sid.length > 0 ? sid : undefined;
+}
+/**
+ * Compose the runner's signal with a backend-side timeout. The returned
+ * signal aborts when either fires; `cancel()` clears the timer so a
+ * successful run doesn't leak it.
+ */
+function composeAbortSignal(upstream, timeoutMs) {
+    const controller = new AbortController();
+    if (upstream.aborted)
+        controller.abort(upstream.reason);
+    const onAbort = () => controller.abort(upstream.reason);
+    upstream.addEventListener('abort', onAbort, { once: true });
+    const timer = setTimeout(() => {
+        controller.abort(new Error(`codex backend timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+    // Don't keep the event loop alive solely for this timer.
+    if (typeof timer === 'object' && 'unref' in timer)
+        timer.unref();
+    return {
+        signal: controller.signal,
+        cancel: () => {
+            clearTimeout(timer);
+            upstream.removeEventListener('abort', onAbort);
+        },
+    };
+}
+//# sourceMappingURL=backend.js.map

package/dist/backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.js","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"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"}

package/dist/client.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Thin wrapper around `@openai/codex-sdk`'s `Codex` and `Thread`.
+ *
+ * - Owns a memoized `Codex` instance keyed by the constructed options. The
+ *   SDK spawns the `codex` CLI per turn, but we want each backend instance
+ *   to share auth/env/config across calls.
+ * - Translates `Codex` JSONL events into a normalized shape the backend
+ *   can publish onto skelm's event bus and `onPartial` callback.
+ */
+import { Codex, type CodexOptions, type ThreadEvent, type ThreadOptions } from '@openai/codex-sdk';
+import type { CodexBackendOptions } from './types.js';
+/** Build CodexOptions from CodexBackendOptions + per-run overrides. */
+export declare function buildCodexOptions(opts: CodexBackendOptions, overrides?: {
+    env?: Record<string, string>;
+    config?: Record<string, unknown>;
+}): CodexOptions;
+/** Build ThreadOptions for `Codex.startThread`. */
+export declare function buildThreadOptions(opts: CodexBackendOptions, extras: Partial<ThreadOptions>): ThreadOptions;
+/**
+ * Translate a skelm `McpServerConfig` array into the JS shape that the
+ * Codex SDK's `config.mcp_servers` accepts. Today Codex's TOML config only
+ * supports stdio MCP servers via `command` + `args` + `env`; HTTP/SSE
+ * transports are dropped with a warning so the caller can audit the gap.
+ *
+ * The caller is expected to have already filtered by `policy.allowedMcpServers`.
+ */
+export declare function buildMcpServerConfig(servers: ReadonlyArray<{
+    id: string;
+    transport: 'stdio' | 'http' | 'sse';
+    command?: string;
+    args?: readonly string[];
+    env?: Readonly<Record<string, string>>;
+    url?: string;
+}>): {
+    mcp_servers: Record<string, unknown>;
+    dropped: string[];
+} | null;
+/**
+ * Iterate the Codex event stream and dispatch normalized events. The
+ * caller decides how to surface each event (onPartial, audit emission,
+ * etc.). Returns the aggregated final assistant text and usage.
+ */
+export interface IterateResult {
+    finalText: string;
+    usage: {
+        inputTokens?: number;
+        outputTokens?: number;
+        reasoningTokens?: number;
+    } | undefined;
+    stopReason: string;
+}
+export declare function consumeStream(events: AsyncIterable<ThreadEvent>, callbacks: {
+    onText?: (delta: string) => void;
+    onItem?: (event: Extract<ThreadEvent, {
+        type: 'item.completed';
+    }>) => void;
+    onError?: (message: string) => void;
+}): Promise<IterateResult>;
+/** Construct a `Codex` instance. Exposed for testing. */
+export declare function makeCodexClient(opts: CodexOptions): Codex;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,EAAE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAElG,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAErD,uEAAuE;AACvE,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,mBAAmB,EACzB,SAAS,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAO,GACjF,YAAY,CAuCd;AAED,mDAAmD;AACnD,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,mBAAmB,EACzB,MAAM,EAAE,OAAO,CAAC,aAAa,CAAC,GAC7B,aAAa,CAQf;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,aAAa,CAAC;IACrB,EAAE,EAAE,MAAM,CAAA;IACV,SAAS,EAAE,OAAO,GAAG,MAAM,GAAG,KAAK,CAAA;IACnC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACxB,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACtC,GAAG,CAAC,EAAE,MAAM,CAAA;CACb,CAAC,GACD;IAAE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,IAAI,CAmBpE;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,eAAe,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAA;IAC5F,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,wBAAsB,aAAa,CACjC,MAAM,EAAE,aAAa,CAAC,WAAW,CAAC,EAClC,SAAS,EAAE;IACT,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IAChC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,WAAW,EAAE;QAAE,IAAI,EAAE,gBAAgB,CAAA;KAAE,CAAC,KAAK,IAAI,CAAA;IAC1E,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CACpC,GACA,OAAO,CAAC,aAAa,CAAC,CA6CxB;AAED,yDAAyD;AACzD,wBAAgB,eAAe,CAAC,IAAI,EAAE,YAAY,GAAG,KAAK,CAEzD"}

package/dist/client.js

@@ -0,0 +1,154 @@
+/**
+ * Thin wrapper around `@openai/codex-sdk`'s `Codex` and `Thread`.
+ *
+ * - Owns a memoized `Codex` instance keyed by the constructed options. The
+ *   SDK spawns the `codex` CLI per turn, but we want each backend instance
+ *   to share auth/env/config across calls.
+ * - Translates `Codex` JSONL events into a normalized shape the backend
+ *   can publish onto skelm's event bus and `onPartial` callback.
+ */
+import { Codex } from '@openai/codex-sdk';
+/** Build CodexOptions from CodexBackendOptions + per-run overrides. */
+export function buildCodexOptions(opts, overrides = {}) {
+    const out = {};
+    if (opts.codexPathOverride !== undefined)
+        out.codexPathOverride = opts.codexPathOverride;
+    if (opts.baseUrl !== undefined)
+        out.baseUrl = opts.baseUrl;
+    if (opts.apiKey !== undefined)
+        out.apiKey = opts.apiKey;
+    // env: merge skelm proxyEnv with the user's static env. The SDK does NOT
+    // inherit process.env when env is set, so we must replay any vars the
+    // codex CLI needs from the parent unless the caller opts out.
+    if (overrides.env !== undefined || opts.env !== undefined) {
+        const merged = {};
+        // Inherit common auth-relevant vars from process.env unless the user
+        // pinned env themselves.
+        if (opts.env === undefined) {
+            const passthrough = [
+                'HOME',
+                'PATH',
+                'USER',
+                'CODEX_API_KEY',
+                'OPENAI_API_KEY',
+                'OPENAI_BASE_URL',
+            ];
+            for (const k of passthrough) {
+                const v = process.env[k];
+                if (v !== undefined)
+                    merged[k] = v;
+            }
+        }
+        else {
+            for (const [k, v] of Object.entries(opts.env))
+                merged[k] = v;
+        }
+        if (overrides.env !== undefined) {
+            for (const [k, v] of Object.entries(overrides.env))
+                merged[k] = v;
+        }
+        out.env = merged;
+    }
+    if (overrides.config !== undefined) {
+        out.config = overrides.config;
+    }
+    return out;
+}
+/** Build ThreadOptions for `Codex.startThread`. */
+export function buildThreadOptions(opts, extras) {
+    const out = {};
+    if (opts.model !== undefined)
+        out.model = opts.model;
+    if (opts.modelReasoningEffort !== undefined)
+        out.modelReasoningEffort = opts.modelReasoningEffort;
+    if (opts.skipGitRepoCheck !== undefined)
+        out.skipGitRepoCheck = opts.skipGitRepoCheck;
+    else
+        out.skipGitRepoCheck = true;
+    Object.assign(out, extras);
+    return out;
+}
+/**
+ * Translate a skelm `McpServerConfig` array into the JS shape that the
+ * Codex SDK's `config.mcp_servers` accepts. Today Codex's TOML config only
+ * supports stdio MCP servers via `command` + `args` + `env`; HTTP/SSE
+ * transports are dropped with a warning so the caller can audit the gap.
+ *
+ * The caller is expected to have already filtered by `policy.allowedMcpServers`.
+ */
+export function buildMcpServerConfig(servers) {
+    if (servers.length === 0)
+        return null;
+    const out = {};
+    const dropped = [];
+    for (const s of servers) {
+        if (s.transport === 'stdio' && s.command !== undefined) {
+            const entry = { command: s.command };
+            if (s.args !== undefined)
+                entry.args = [...s.args];
+            if (s.env !== undefined)
+                entry.env = { ...s.env };
+            out[s.id] = entry;
+        }
+        else {
+            // Codex CLI's stable config.toml schema doesn't expose HTTP/SSE MCP
+            // transports; users with remote MCP must wire ~/.codex/config.toml
+            // manually. Surface the drop in audit instead of silently swallowing.
+            dropped.push(s.id);
+        }
+    }
+    if (Object.keys(out).length === 0)
+        return null;
+    return { mcp_servers: out, dropped };
+}
+export async function consumeStream(events, callbacks) {
+    let finalText = '';
+    let usage = undefined;
+    let stopReason = 'turn.completed';
+    for await (const ev of events) {
+        switch (ev.type) {
+            case 'item.completed': {
+                // Aggregate assistant message text. `agent_message.text` is the
+                // full cumulative text up to this point — `onText` per skelm's
+                // BackendContext.onPartial contract should receive *deltas*, so we
+                // emit only the new suffix on each event.
+                if (ev.item.type === 'agent_message') {
+                    const next = ev.item.text;
+                    const delta = next.startsWith(finalText) ? next.slice(finalText.length) : next;
+                    finalText = next;
+                    if (delta.length > 0)
+                        callbacks.onText?.(delta);
+                }
+                callbacks.onItem?.(ev);
+                break;
+            }
+            case 'turn.completed':
+                usage = {
+                    inputTokens: ev.usage.input_tokens,
+                    outputTokens: ev.usage.output_tokens,
+                    reasoningTokens: ev.usage.reasoning_output_tokens,
+                };
+                stopReason = 'turn.completed';
+                break;
+            case 'turn.failed':
+                stopReason = 'turn.failed';
+                callbacks.onError?.(ev.error.message);
+                throw new Error(`codex turn failed: ${ev.error.message}`);
+            case 'error':
+                stopReason = 'error';
+                callbacks.onError?.(ev.message);
+                throw new Error(`codex stream error: ${ev.message}`);
+            // thread.started, turn.started, item.started, item.updated: not
+            // material to the final response; surface via onItem if the caller
+            // wants per-item audit (it doesn't, by default).
+            default:
+                break;
+        }
+    }
+    return { finalText, usage, stopReason };
+}
+/** Construct a `Codex` instance. Exposed for testing. */
+export function makeCodexClient(opts) {
+    return new Codex(opts);
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @skelm/codex — OpenAI Codex backend for skelm via `@openai/codex-sdk`.
+ *
+ * Codex authenticates via the host `codex` CLI (`codex login`) or
+ * `CODEX_API_KEY`. The SDK spawns codex under the hood and exchanges JSONL
+ * events; skelm enforces permissions at the boundary and records audit
+ * events as Codex emits tool calls, file changes, and shell executions.
+ */
+export { createCodexBackend } from './backend.js';
+export { CodexPermissionError, buildAuditEntry, filterIds, mapPermissionsToCodex, } from './permission-mapper.js';
+export type { CodexBackendOptions, CodexPermissionAuditEntry, MappedCodexPolicy, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AACjD,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,SAAS,EACT,qBAAqB,GACtB,MAAM,wBAAwB,CAAA;AAC/B,YAAY,EACV,mBAAmB,EACnB,yBAAyB,EACzB,iBAAiB,GAClB,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * @skelm/codex — OpenAI Codex backend for skelm via `@openai/codex-sdk`.
+ *
+ * Codex authenticates via the host `codex` CLI (`codex login`) or
+ * `CODEX_API_KEY`. The SDK spawns codex under the hood and exchanges JSONL
+ * events; skelm enforces permissions at the boundary and records audit
+ * events as Codex emits tool calls, file changes, and shell executions.
+ */
+export { createCodexBackend } from './backend.js';
+export { CodexPermissionError, buildAuditEntry, filterIds, mapPermissionsToCodex, } from './permission-mapper.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AACjD,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,SAAS,EACT,qBAAqB,GACtB,MAAM,wBAAwB,CAAA"}

package/dist/permission-mapper.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Translate a resolved skelm permission policy into Codex SDK options.
+ *
+ * Codex enforces its own sandbox in-process; the mapper is the boundary —
+ * if it can't translate the policy without widening, it refuses the run.
+ *
+ * Rules:
+ *
+ *   fsWrite: ∅ and fsRead: ∅     → sandboxMode: 'read-only'
+ *   fsWrite: ['*']               → 'danger-full-access' iff approval.mode === 'never'
+ *                                   (otherwise refuse — never silently escalate)
+ *   fsWrite: [<roots>]           → 'workspace-write', primary root → workingDirectory,
+ *                                   extras → additionalDirectories
+ *   networkEgress: 'deny'        → networkAccessEnabled: false
+ *   networkEgress: anything else → networkAccessEnabled: true
+ *                                   (host allowlists are enforced by skelm's
+ *                                    gateway egress proxy, not by Codex)
+ *
+ * Approval:
+ *
+ *   approval == null             → 'on-request' (Codex's safest default)
+ *   approval.on.includes('*')    → 'untrusted'
+ *   otherwise                    → 'on-request'
+ *
+ * Refusals throw `CodexPermissionError` and are emitted as audit entries.
+ */
+import type { ResolvedPolicy } from '@skelm/core';
+import type { CodexPermissionAuditEntry, MappedCodexPolicy } from './types.js';
+export declare class CodexPermissionError extends Error {
+    readonly dimension: 'fs.write' | 'fs.read' | 'network' | 'approval';
+    readonly name = "CodexPermissionError";
+    constructor(message: string, dimension: 'fs.write' | 'fs.read' | 'network' | 'approval');
+}
+export interface MapInputs {
+    /** Resolved policy after profiles + step-level merging. */
+    policy: ResolvedPolicy;
+    /** Working directory hint from the runtime (`WorkspaceHandle.path`). */
+    workingDirectory?: string;
+}
+/**
+ * Produce the Codex `ThreadOptions`-compatible mapping. Throws
+ * `CodexPermissionError` when the policy cannot be honored safely.
+ */
+export declare function mapPermissionsToCodex(input: MapInputs): MappedCodexPolicy;
+/**
+ * Compute which skill / MCP ids the step requested but the resolved policy
+ * disallows. Caller fires `permission.denied` events for each.
+ */
+export declare function filterByPolicy<T extends {
+    id: string;
+}>(items: readonly T[] | undefined, allowlist: ReadonlySet<string>): {
+    allowed: T[];
+    denied: T[];
+};
+/** Same as filterByPolicy but for plain string ids (skills, secrets). */
+export declare function filterIds(ids: readonly string[] | undefined, allowlist: ReadonlySet<string>): {
+    allowed: string[];
+    denied: string[];
+};
+/**
+ * Build an audit entry recording how a policy was translated. Useful for
+ * the gateway's hash-chained audit writer.
+ */
+export declare function buildAuditEntry(runId: string, stepId: string, policy: ResolvedPolicy, mapped: MappedCodexPolicy, denied: readonly string[]): CodexPermissionAuditEntry;
+//# sourceMappingURL=permission-mapper.d.ts.map

package/dist/permission-mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-mapper.d.ts","sourceRoot":"","sources":["../src/permission-mapper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AACjD,OAAO,KAAK,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAI9E,qBAAa,oBAAqB,SAAQ,KAAK;IAI3C,QAAQ,CAAC,SAAS,EAAE,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,UAAU;IAHrE,SAAkB,IAAI,0BAAyB;gBAE7C,OAAO,EAAE,MAAM,EACN,SAAS,EAAE,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,UAAU;CAItE;AAED,MAAM,WAAW,SAAS;IACxB,2DAA2D;IAC3D,MAAM,EAAE,cAAc,CAAA;IACtB,wEAAwE;IACxE,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,SAAS,GAAG,iBAAiB,CAiEzE;AAkBD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,EACrD,KAAK,EAAE,SAAS,CAAC,EAAE,GAAG,SAAS,EAC/B,SAAS,EAAE,WAAW,CAAC,MAAM,CAAC,GAC7B;IAAE,OAAO,EAAE,CAAC,EAAE,CAAC;IAAC,MAAM,EAAE,CAAC,EAAE,CAAA;CAAE,CAS/B;AAED,yEAAyE;AACzE,wBAAgB,SAAS,CACvB,GAAG,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EAClC,SAAS,EAAE,WAAW,CAAC,MAAM,CAAC,GAC7B;IAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CASzC;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,iBAAiB,EACzB,MAAM,EAAE,SAAS,MAAM,EAAE,GACxB,yBAAyB,CAwB3B"}

package/dist/permission-mapper.js

@@ -0,0 +1,176 @@
+/**
+ * Translate a resolved skelm permission policy into Codex SDK options.
+ *
+ * Codex enforces its own sandbox in-process; the mapper is the boundary —
+ * if it can't translate the policy without widening, it refuses the run.
+ *
+ * Rules:
+ *
+ *   fsWrite: ∅ and fsRead: ∅     → sandboxMode: 'read-only'
+ *   fsWrite: ['*']               → 'danger-full-access' iff approval.mode === 'never'
+ *                                   (otherwise refuse — never silently escalate)
+ *   fsWrite: [<roots>]           → 'workspace-write', primary root → workingDirectory,
+ *                                   extras → additionalDirectories
+ *   networkEgress: 'deny'        → networkAccessEnabled: false
+ *   networkEgress: anything else → networkAccessEnabled: true
+ *                                   (host allowlists are enforced by skelm's
+ *                                    gateway egress proxy, not by Codex)
+ *
+ * Approval:
+ *
+ *   approval == null             → 'on-request' (Codex's safest default)
+ *   approval.on.includes('*')    → 'untrusted'
+ *   otherwise                    → 'on-request'
+ *
+ * Refusals throw `CodexPermissionError` and are emitted as audit entries.
+ */
+const STAR = '*';
+export class CodexPermissionError extends Error {
+    dimension;
+    name = 'CodexPermissionError';
+    constructor(message, dimension) {
+        super(message);
+        this.dimension = dimension;
+    }
+}
+/**
+ * Produce the Codex `ThreadOptions`-compatible mapping. Throws
+ * `CodexPermissionError` when the policy cannot be honored safely.
+ */
+export function mapPermissionsToCodex(input) {
+    const { policy, workingDirectory } = input;
+    const fsWrite = Array.from(policy.fsWrite);
+    const fsRead = Array.from(policy.fsRead);
+    // Sandbox tier.
+    let sandboxMode;
+    let primary = workingDirectory;
+    const extras = [];
+    const hasStarWrite = fsWrite.includes(STAR);
+    if (hasStarWrite) {
+        // Broad write requires explicit no-approval acknowledgement.
+        if (policy.approval !== null) {
+            throw new CodexPermissionError('fsWrite includes "*" but an approval policy is set; refusing danger-full-access', 'fs.write');
+        }
+        sandboxMode = 'danger-full-access';
+    }
+    else if (fsWrite.length === 0) {
+        sandboxMode = 'read-only';
+    }
+    else {
+        sandboxMode = 'workspace-write';
+        if (primary === undefined)
+            primary = fsWrite[0];
+        for (const root of fsWrite) {
+            if (root !== primary && !extras.includes(root))
+                extras.push(root);
+        }
+    }
+    // Read-only sandbox doesn't need fsRead roots (codex's read-only mode is
+    // unrestricted by default; the read allowlist is informational here).
+    void fsRead;
+    // Network. Codex has two distinct network surfaces:
+    //   1. `networkAccessEnabled` — sandbox-shell egress (curl, wget, etc).
+    //      The gateway egress proxy can enforce host allowlists for this
+    //      surface when `networkEgress: { allowHosts }` is set.
+    //   2. `webSearchEnabled` / `webSearchMode` — the model's built-in web
+    //      tool. This runs INSIDE the Codex process and does NOT go through
+    //      the gateway proxy, so per-host allowlists cannot be enforced.
+    //
+    // Implication: a `{ allowHosts: ['api.example.com'] }` policy would, if
+    // we left web_search enabled, let Codex reach arbitrary URLs through its
+    // built-in tool — bypassing the allowlist the user just declared. To
+    // honor the policy faithfully, web_search is enabled ONLY when
+    // networkEgress === 'allow' (blanket allow). Anything else disables it.
+    const networkAccessEnabled = policy.networkEgress !== 'deny';
+    const webSearchAllowed = policy.networkEgress === 'allow';
+    const webSearchEnabled = webSearchAllowed;
+    const webSearchMode = webSearchAllowed ? 'live' : 'disabled';
+    // Approval mode.
+    const approvalPolicy = pickApprovalMode(policy);
+    const mapped = {
+        sandboxMode,
+        approvalPolicy,
+        networkAccessEnabled,
+        webSearchEnabled,
+        webSearchMode,
+        ...(primary !== undefined && { workingDirectory: primary }),
+        ...(extras.length > 0 && { additionalDirectories: extras }),
+    };
+    return mapped;
+}
+function pickApprovalMode(policy) {
+    // No explicit approval policy → don't escalate. Codex's sandbox is already
+    // enforcing what's allowed (sandboxMode + workingDirectory + network); the
+    // skelm boundary check has already refused unsafe combinations before we
+    // got here. Using 'on-request' here would deadlock every shell command in
+    // automated environments because skelm doesn't supply a Codex-side
+    // approval handler. Per project tenet "default-deny is structural": the
+    // sandbox is the deny, not approval prompts.
+    if (policy.approval === null)
+        return 'never';
+    // Explicit approval policy from the workflow author → respect it.
+    if (policy.approval.on.some((d) => d === 'tool' || d === 'executable')) {
+        return 'untrusted';
+    }
+    return 'on-request';
+}
+/**
+ * Compute which skill / MCP ids the step requested but the resolved policy
+ * disallows. Caller fires `permission.denied` events for each.
+ */
+export function filterByPolicy(items, allowlist) {
+    if (items === undefined)
+        return { allowed: [], denied: [] };
+    const allowed = [];
+    const denied = [];
+    for (const item of items) {
+        if (allowlist.has(item.id))
+            allowed.push(item);
+        else
+            denied.push(item);
+    }
+    return { allowed, denied };
+}
+/** Same as filterByPolicy but for plain string ids (skills, secrets). */
+export function filterIds(ids, allowlist) {
+    if (ids === undefined)
+        return { allowed: [], denied: [] };
+    const allowed = [];
+    const denied = [];
+    for (const id of ids) {
+        if (allowlist.has(id))
+            allowed.push(id);
+        else
+            denied.push(id);
+    }
+    return { allowed, denied };
+}
+/**
+ * Build an audit entry recording how a policy was translated. Useful for
+ * the gateway's hash-chained audit writer.
+ */
+export function buildAuditEntry(runId, stepId, policy, mapped, denied) {
+    return {
+        runId,
+        stepId,
+        timestamp: new Date().toISOString(),
+        event: 'permission_check',
+        details: {
+            declaredPermissions: {
+                allowedExecutables: Array.from(policy.allowedExecutables),
+                allowedMcpServers: Array.from(policy.allowedMcpServers),
+                allowedSkills: Array.from(policy.allowedSkills),
+                fsRead: Array.from(policy.fsRead),
+                fsWrite: Array.from(policy.fsWrite),
+                networkEgress: typeof policy.networkEgress === 'string'
+                    ? policy.networkEgress
+                    : `allowHosts:${policy.networkEgress.allowHosts.join(',')}`,
+            },
+            mapped,
+            decision: denied.length === 0 ? 'allow' : 'deny',
+            deniedItems: Array.from(denied),
+            backend: 'codex',
+        },
+    };
+}
+//# sourceMappingURL=permission-mapper.js.map

package/dist/permission-mapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-mapper.js","sourceRoot":"","sources":["../src/permission-mapper.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,83 @@
+/**
+ * `@skelm/codex` configuration types.
+ *
+ * The backend wraps OpenAI's official `@openai/codex-sdk`. The SDK spawns
+ * the `codex` CLI under the hood and exchanges JSONL events over stdio, so
+ * authentication piggybacks on `codex login` (`~/.codex/auth.json`) or the
+ * `CODEX_API_KEY` env var.
+ */
+import type { ApprovalMode, ModelReasoningEffort, SandboxMode, WebSearchMode } from '@openai/codex-sdk';
+export interface CodexBackendOptions {
+    /** Backend id. Defaults to 'codex' when only one codex backend is registered. */
+    id?: string;
+    /** Human-readable label for diagnostics. */
+    label?: string;
+    /** Path to the codex CLI. Default: 'codex' on PATH (the SDK resolves it). */
+    codexPathOverride?: string;
+    /** Override the Codex API base URL (self-hosted / proxied deployments). */
+    baseUrl?: string;
+    /** API key. Overrides the ambient `CODEX_API_KEY` env var. */
+    apiKey?: string;
+    /**
+     * Extra env vars passed to the spawned codex process. When set, the SDK
+     * does NOT inherit `process.env` — it uses these vars as the full env.
+     * Skelm always merges `BackendContext.proxyEnv` into this map at run time.
+     */
+    env?: Record<string, string>;
+    /** Default model id, e.g. 'gpt-5.2' or 'gpt-5.3-codex'. */
+    model?: string;
+    /** Default reasoning effort. */
+    modelReasoningEffort?: ModelReasoningEffort;
+    /**
+     * Skip the SDK's "is this a git repo" sanity check. Defaults to `true` for
+     * ephemeral skelm workspaces (which usually have no `.git`).
+     */
+    skipGitRepoCheck?: boolean;
+    /**
+     * Per-step abort timeout. The runtime's own abort signal already drives
+     * cancellation; this is a defensive ceiling. Default: 300_000 (5 min).
+     */
+    timeoutMs?: number;
+}
+/**
+ * Resolved Codex SDK options after skelm permissions are applied. Produced
+ * by `permission-mapper.ts` and fed into `Codex.startThread()`.
+ */
+export interface MappedCodexPolicy {
+    sandboxMode: SandboxMode;
+    approvalPolicy: ApprovalMode;
+    networkAccessEnabled: boolean;
+    /**
+     * Codex's built-in web search bypasses `networkAccessEnabled` (that flag
+     * governs sandbox-shell egress only). When networkEgress is 'deny' we set
+     * webSearchMode to 'disabled' too so the agent cannot reach the public
+     * web through its built-in tool.
+     */
+    webSearchMode: WebSearchMode;
+    webSearchEnabled: boolean;
+    /** Primary working directory (== WorkspaceHandle.path when present). */
+    workingDirectory?: string;
+    /** Extra writable directories beyond `workingDirectory`. */
+    additionalDirectories?: string[];
+}
+export interface CodexPermissionAuditEntry {
+    runId: string;
+    stepId: string;
+    timestamp: string;
+    event: 'permission_check';
+    details: {
+        declaredPermissions: {
+            allowedExecutables: string[];
+            allowedMcpServers: string[];
+            allowedSkills: string[];
+            fsRead: string[];
+            fsWrite: string[];
+            networkEgress: string;
+        };
+        mapped: MappedCodexPolicy;
+        decision: 'allow' | 'deny';
+        deniedItems: string[];
+        backend: 'codex';
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,oBAAoB,EACpB,WAAW,EACX,aAAa,EACd,MAAM,mBAAmB,CAAA;AAE1B,MAAM,WAAW,mBAAmB;IAClC,iFAAiF;IACjF,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAA;IAId,6EAA6E;IAC7E,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAI5B,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,gCAAgC;IAChC,oBAAoB,CAAC,EAAE,oBAAoB,CAAA;IAI3C;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,WAAW,CAAA;IACxB,cAAc,EAAE,YAAY,CAAA;IAC5B,oBAAoB,EAAE,OAAO,CAAA;IAC7B;;;;;OAKG;IACH,aAAa,EAAE,aAAa,CAAA;IAC5B,gBAAgB,EAAE,OAAO,CAAA;IACzB,wEAAwE;IACxE,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,4DAA4D;IAC5D,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAA;CACjC;AAED,MAAM,WAAW,yBAAyB;IACxC,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,kBAAkB,CAAA;IACzB,OAAO,EAAE;QACP,mBAAmB,EAAE;YACnB,kBAAkB,EAAE,MAAM,EAAE,CAAA;YAC5B,iBAAiB,EAAE,MAAM,EAAE,CAAA;YAC3B,aAAa,EAAE,MAAM,EAAE,CAAA;YACvB,MAAM,EAAE,MAAM,EAAE,CAAA;YAChB,OAAO,EAAE,MAAM,EAAE,CAAA;YACjB,aAAa,EAAE,MAAM,CAAA;SACtB,CAAA;QACD,MAAM,EAAE,iBAAiB,CAAA;QACzB,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAA;QAC1B,WAAW,EAAE,MAAM,EAAE,CAAA;QACrB,OAAO,EAAE,OAAO,CAAA;KACjB,CAAA;CACF"}

package/dist/types.js

@@ -0,0 +1,10 @@
+/**
+ * `@skelm/codex` configuration types.
+ *
+ * The backend wraps OpenAI's official `@openai/codex-sdk`. The SDK spawns
+ * the `codex` CLI under the hood and exchanges JSONL events over stdio, so
+ * authentication piggybacks on `codex login` (`~/.codex/auth.json`) or the
+ * `CODEX_API_KEY` env var.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@skelm/codex",
+  "version": "0.3.9",
+  "description": "OpenAI Codex backend for skelm via the official @openai/codex-sdk",
+  "license": "MIT",
+  "author": "Scott Glover <scottgl@gmail.com>",
+  "homepage": "https://skelm.dev/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/scottgl9/skelm.git",
+    "directory": "packages/codex"
+  },
+  "bugs": {
+    "url": "https://github.com/scottgl9/skelm/issues"
+  },
+  "keywords": [
+    "skelm",
+    "codex",
+    "openai",
+    "agent",
+    "backend",
+    "coding-agent"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo"
+  },
+  "dependencies": {
+    "@openai/codex-sdk": "^0.130.0"
+  },
+  "peerDependencies": {
+    "@skelm/core": "^0.3.9"
+  },
+  "devDependencies": {
+    "@skelm/core": "^0.3.9",
+    "@types/node": "^20.10.0",
+    "typescript": "^5.3.0",
+    "vitest": "^2.1.5"
+  }
+}