@skelm/codex 0.4.1 → 0.4.3

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,4 +1,7 @@
-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 { mapPermissionsToCodex } from './permission-mapper.js';
 /**
@@ -30,6 +33,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 +60,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 +74,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,
@@ -108,6 +121,7 @@ export function createCodexBackend(options = {}) {
             }
             finally {
                 turnSignal.cancel();
+                cleanupTempImageRoots(imageRoots);
             }
             const response = {
                 text: result.finalText,
@@ -129,6 +143,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: [] };

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/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.1",
+  "version": "0.4.3",
   "description": "OpenAI Codex backend for skelm via the official @openai/codex-sdk",
   "license": "MIT",
   "author": "Scott Glover <scottgl@gmail.com>",
@@ -27,7 +27,7 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "default": "./dist/index.js"
     }
   },
   "files": [
@@ -49,10 +49,10 @@
     "@openai/codex-sdk": "^0.130.0"
   },
   "peerDependencies": {
-    "@skelm/core": "^0.4.1"
+    "@skelm/core": "^0.4.3"
   },
   "devDependencies": {
-    "@skelm/core": "^0.4.1",
+    "@skelm/core": "^0.4.3",
     "@types/node": "^20.10.0",
     "typescript": "^5.3.0",
     "vitest": "^2.1.5"