@skelm/codex 0.4.2 → 0.4.4

package/README.md

@@ -58,7 +58,7 @@ export default defineConfig({
 ```
 
 ```ts
-// codex-smoke.pipeline.ts
+// codex-smoke.pipeline.mts
 import { agent, pipeline } from 'skelm'
 import { z } from 'zod'
 
@@ -84,7 +84,7 @@ export default pipeline({
 ```
 
 ```bash
-skelm run codex-smoke.pipeline.ts --input '{"task":"say ok"}'
+skelm run codex-smoke.pipeline.mts --input '{"task":"say ok"}'
 ```
 
 ## Permission mapping

package/dist/backend.js

@@ -1,5 +1,9 @@
-import { buildSystemPromptFromRequest, loadSkillBodies, resolvePermissions } from '@skelm/core';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { BackendConfigError, buildSystemPromptFromRequest, extractPromptText, loadSkillBodies, resolvePermissions, } from '@skelm/core';
 import { buildCodexOptions, buildMcpServerConfig, buildThreadOptions, consumeStream, makeCodexClient, } from './client.js';
+import { toCodexOutputSchema } from './output-schema.js';
 import { mapPermissionsToCodex } from './permission-mapper.js';
 /**
  * SkelmBackend for OpenAI Codex via the official `@openai/codex-sdk`.
@@ -30,6 +34,12 @@ export function createCodexBackend(options = {}) {
         // Skelm checks at the boundary (refusing unsafe combinations before any
         // Codex call); Codex enforces at runtime.
         toolPermissions: 'native',
+        // Image content is forwarded as `{type:'local_image', path}` per the
+        // codex-sdk schema; bytes are materialized to a temp file for the turn
+        // and cleaned up afterwards. Whether the configured codex model can
+        // actually process images is up to the model — non-vision models will
+        // surface a provider error that propagates as a step failure.
+        vision: options.vision ?? true,
     };
     const backend = {
         id: options.id ?? 'codex',
@@ -51,18 +61,10 @@ export function createCodexBackend(options = {}) {
                 policy,
                 ...(request.cwd !== undefined && { workingDirectory: request.cwd }),
             });
-            // Filter requested MCP servers through the allowlist.
+            // Filter requested MCP servers through the allowlist; the runner's
+            // audit writer is the single durable record for denials.
             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, {
@@ -73,7 +75,19 @@ export function createCodexBackend(options = {}) {
             // 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}`;
+            // Codex SDK accepts string OR Array<{type:'text'}|{type:'local_image',path}>.
+            // For image-bearing prompts we materialize each image to a temp file
+            // (Codex requires filesystem paths, not data URLs) and clean up after
+            // the turn. Pure-text prompts keep the prior compact "<system>\n\n---\n\n<text>" shape.
+            const imageRoots = [];
+            const userPrompt = typeof request.prompt === 'string' || extractImageParts(request.prompt).length === 0
+                ? (() => {
+                    const promptText = extractPromptText(request.prompt);
+                    return systemPrompt === undefined
+                        ? promptText
+                        : `${systemPrompt}\n\n---\n\n${promptText}`;
+                })()
+                : buildCodexMultimodalInput(request.prompt, systemPrompt, imageRoots);
             // Build the thread (resume vs fresh) honoring per-step sandbox/approval.
             const threadOpts = buildThreadOptions(options, {
                 sandboxMode: mapped.sandboxMode,
@@ -96,8 +110,13 @@ export function createCodexBackend(options = {}) {
             // backend's `timeoutMs` (defensive ceiling). The SDK honors a single
             // AbortSignal on TurnOptions natively.
             const turnSignal = composeAbortSignal(context.signal, options.timeoutMs ?? 300_000);
+            // The SDK writes outputSchema verbatim to the --output-schema file, and
+            // the OpenAI structured-output API requires strict JSON Schema
+            // (additionalProperties:false + required). Convert the step's schema here
+            // rather than handing the SDK a raw standard-schema object.
+            const codexOutputSchema = await toCodexOutputSchema(request.outputSchema);
             const { events } = await thread.runStreamed(userPrompt, {
-                ...(request.outputSchema !== undefined && { outputSchema: request.outputSchema }),
+                ...(codexOutputSchema !== undefined && { outputSchema: codexOutputSchema }),
                 signal: turnSignal.signal,
             });
             let result;
@@ -108,6 +127,7 @@ export function createCodexBackend(options = {}) {
             }
             finally {
                 turnSignal.cancel();
+                cleanupTempImageRoots(imageRoots);
             }
             const response = {
                 text: result.finalText,
@@ -129,6 +149,74 @@ export function createCodexBackend(options = {}) {
     };
     return backend;
 }
+function extractImageParts(prompt) {
+    if (typeof prompt === 'string')
+        return [];
+    return prompt.filter((p) => p.type === 'image');
+}
+function mimeToExt(mime) {
+    switch (mime) {
+        case 'image/png':
+            return '.png';
+        case 'image/jpeg':
+            return '.jpg';
+        case 'image/webp':
+            return '.webp';
+        case 'image/gif':
+            return '.gif';
+        default:
+            return '.bin';
+    }
+}
+function buildCodexMultimodalInput(prompt, systemPrompt, imageRoots) {
+    const tmp = mkdtempSync(join(tmpdir(), 'skelm-codex-img-'));
+    imageRoots.push(tmp);
+    const parts = [];
+    let imgIdx = 0;
+    // Seed the text buffer with the system prompt block so it always lands as
+    // the FIRST text part — even when the prompt is `[image, text, ...]` and we
+    // would otherwise flush a `local_image` before seeing any user text.
+    // Mirrors the pure-text fallback `"<system>\n\n---\n\n<text>"` higher up,
+    // so callers see consistent ordering regardless of which path the request
+    // takes.
+    let textBuf = systemPrompt !== undefined ? `${systemPrompt}\n\n---\n\n` : '';
+    if (typeof prompt === 'string') {
+        parts.push({ type: 'text', text: `${textBuf}${prompt}` });
+        return parts;
+    }
+    for (const part of prompt) {
+        if (part.type === 'text') {
+            textBuf += part.text;
+        }
+        else if (part.type === 'image') {
+            if (textBuf.length > 0) {
+                parts.push({ type: 'text', text: textBuf });
+                textBuf = '';
+            }
+            const file = join(tmp, `img${imgIdx++}${mimeToExt(part.mimeType)}`);
+            try {
+                writeFileSync(file, Buffer.from(part.data, 'base64'));
+            }
+            catch (err) {
+                throw new BackendConfigError(`codex backend: failed to materialize image to ${file}: ${err.message}`, 'codex');
+            }
+            parts.push({ type: 'local_image', path: file });
+        }
+    }
+    if (textBuf.length > 0)
+        parts.push({ type: 'text', text: textBuf });
+    return parts;
+}
+function cleanupTempImageRoots(roots) {
+    for (const root of roots) {
+        try {
+            rmSync(root, { recursive: true, force: true });
+        }
+        catch {
+            // Best-effort cleanup; OS will eventually reap /tmp anyway.
+        }
+    }
+}
 function filterAllowedMcp(servers, allowlist) {
     if (servers === undefined || servers.length === 0)
         return { allowed: [], denied: [] };
@@ -170,12 +258,6 @@ async function composeSystemPrompt(req, ctx, model) {
         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;

package/dist/client.js

@@ -8,6 +8,7 @@
  *   can publish onto skelm's event bus and `onPartial` callback.
  */
 import { Codex } from '@openai/codex-sdk';
+import { BackendUpstreamError } from '@skelm/core';
 /** Build CodexOptions from CodexBackendOptions + per-run overrides. */
 export function buildCodexOptions(opts, overrides = {}) {
     const out = {};
@@ -133,11 +134,11 @@ export async function consumeStream(events, callbacks) {
             case 'turn.failed':
                 stopReason = 'turn.failed';
                 callbacks.onError?.(ev.error.message);
-                throw new Error(`codex turn failed: ${ev.error.message}`);
+                throw new BackendUpstreamError(`codex turn failed: ${ev.error.message}`, 'codex');
             case 'error':
                 stopReason = 'error';
                 callbacks.onError?.(ev.message);
-                throw new Error(`codex stream error: ${ev.message}`);
+                throw new BackendUpstreamError(`codex stream error: ${ev.message}`, 'codex');
             // 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).

package/dist/output-schema.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Convert a step's output schema into the strict JSON Schema the Codex SDK
+ * requires. Codex writes `outputSchema` to a file and passes it to the OpenAI
+ * structured-output API via `--output-schema`; that API rejects any object
+ * schema that omits `additionalProperties: false` or doesn't list every
+ * property in `required`. The schema reaching this point is a standard-schema
+ * (Zod is the documented default) or an already-plain JSON Schema object.
+ *
+ * Returns `undefined` when no schema was requested.
+ */
+export declare function toCodexOutputSchema(schema: unknown): Promise<Record<string, unknown> | undefined>;

package/dist/output-schema.js

@@ -0,0 +1,60 @@
+import { BackendConfigError } from '@skelm/core';
+/**
+ * Convert a step's output schema into the strict JSON Schema the Codex SDK
+ * requires. Codex writes `outputSchema` to a file and passes it to the OpenAI
+ * structured-output API via `--output-schema`; that API rejects any object
+ * schema that omits `additionalProperties: false` or doesn't list every
+ * property in `required`. The schema reaching this point is a standard-schema
+ * (Zod is the documented default) or an already-plain JSON Schema object.
+ *
+ * Returns `undefined` when no schema was requested.
+ */
+export async function toCodexOutputSchema(schema) {
+    if (schema === undefined)
+        return undefined;
+    const json = await toJsonSchema(schema);
+    return enforceStrict(json);
+}
+async function toJsonSchema(schema) {
+    if (typeof schema !== 'object' || schema === null) {
+        throw new BackendConfigError('codex outputSchema must be a Zod schema or a JSON Schema object', 'codex');
+    }
+    const standard = schema['~standard'];
+    if (standard !== undefined) {
+        if (standard.vendor !== 'zod') {
+            throw new BackendConfigError(`codex outputSchema: cannot convert a '${String(standard.vendor)}' schema to JSON Schema; use Zod or pass a JSON Schema object`, 'codex');
+        }
+        const z = (await import('zod'));
+        const fn = z.toJSONSchema ?? z.default?.toJSONSchema;
+        if (typeof fn !== 'function') {
+            throw new BackendConfigError('codex outputSchema: installed zod lacks toJSONSchema', 'codex');
+        }
+        return fn(schema);
+    }
+    // Already a plain JSON Schema object.
+    return schema;
+}
+/**
+ * Deep-clone the JSON Schema, forcing `additionalProperties: false` and
+ * `required: <all keys>` on every object node (recursing through properties,
+ * items, $defs/definitions, and the anyOf/oneOf/allOf combinators). This is
+ * what OpenAI strict structured output demands.
+ */
+function enforceStrict(node) {
+    if (Array.isArray(node))
+        return node.map(enforceStrict);
+    if (node === null || typeof node !== 'object')
+        return node;
+    const out = {};
+    for (const [key, value] of Object.entries(node)) {
+        out[key] = enforceStrict(value);
+    }
+    const props = out.properties;
+    if (out.type === 'object' || (props !== null && typeof props === 'object')) {
+        out.additionalProperties = false;
+        if (props !== null && typeof props === 'object') {
+            out.required = Object.keys(props);
+        }
+    }
+    return out;
+}

package/dist/types.d.ts

@@ -38,6 +38,14 @@ export interface CodexBackendOptions {
      * cancellation; this is a defensive ceiling. Default: 300_000 (5 min).
      */
     timeoutMs?: number;
+    /**
+     * Advertise `capabilities.vision`. Defaults to `true`: image content is
+     * materialized to a temp file and forwarded as `{type:'local_image', path}`
+     * per the codex-sdk Input schema. Set `false` for codex configurations
+     * pinned to a known text-only model — the framework gate then rejects
+     * image prompts at step start with no codex turn ever started.
+     */
+    vision?: boolean;
 }
 /**
  * Resolved Codex SDK options after skelm permissions are applied. Produced

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skelm/codex",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "OpenAI Codex backend for skelm via the official @openai/codex-sdk",
   "license": "MIT",
   "author": "Scott Glover <scottgl@gmail.com>",
@@ -49,10 +49,10 @@
     "@openai/codex-sdk": "^0.130.0"
   },
   "peerDependencies": {
-    "@skelm/core": "^0.4.2"
+    "@skelm/core": "^0.4.4"
   },
   "devDependencies": {
-    "@skelm/core": "^0.4.2",
+    "@skelm/core": "^0.4.4",
     "@types/node": "^20.10.0",
     "typescript": "^5.3.0",
     "vitest": "^2.1.5"