@nomix-ai/nomix-harness 0.2.5 → 0.2.6

package/dist/kernel/subagent-codex/lib/types/index.d.ts

@@ -1,29 +1,34 @@
 /**
- * Fixed Codex one-shot subagent provider. Every accepted run starts a fresh
- * official `codex app-server --stdio` process in the delegating Session's
- * workspace and publishes only after an ephemeral thread exists.
+ * Profile-named Codex one-shot subagent provider. Every accepted run starts a
+ * fresh official package-local Codex wrapper with `app-server --stdio` in the
+ * delegating Session's workspace and publishes only after an ephemeral thread exists.
  *
  * @module @nomix-ai/nomix-subagent-codex
  */
 import type { Context } from '../../../cordis/lib/index.js';
 import z from '../../../schemastery/lib/index.mjs';
+import { type CodexPermissionMode } from './run.ts';
 export declare const name = "subagent-codex";
 export declare const inject: string[];
-/** Deployment-owned environment and process-release bound. */
+/** Deployment-owned permission, environment, and process-release settings. */
 export interface Config {
+    /** Provider name on `ctx.subagents` (default `codex`). */
+    providerName?: string;
     /**
      * Explicit environment entries layered over the subprocess seam's
      * credential-scrubbed parent environment.
      */
     env?: Record<string, string>;
+    /** Native non-interactive permission mode fixed for this Provider instance. */
+    permissionMode?: CodexPermissionMode;
     /** Grace in milliseconds for app-server process-tree termination. */
     disposeGraceMs?: number;
 }
 export declare const Config: z<Config>;
 /**
- * Register the fixed `codex` provider.
+ * Register one Profile-named Codex provider.
  * @param ctx - context carrying shared subagent and subprocess services.
- * @param config - explicit child environment and disposal grace.
+ * @param config - registry name, permission mode, child environment, and disposal grace.
  */
 export declare function apply(ctx: Context, config: Config): void;
 //# sourceMappingURL=index.d.ts.map

package/dist/kernel/subagent-codex/lib/types/index.js

@@ -1,27 +1,32 @@
 /**
- * Fixed Codex one-shot subagent provider. Every accepted run starts a fresh
- * official `codex app-server --stdio` process in the delegating Session's
- * workspace and publishes only after an ephemeral thread exists.
+ * Profile-named Codex one-shot subagent provider. Every accepted run starts a
+ * fresh official package-local Codex wrapper with `app-server --stdio` in the
+ * delegating Session's workspace and publishes only after an ephemeral thread exists.
  *
  * @module @nomix-ai/nomix-subagent-codex
  */
 import z from '../../../schemastery/lib/index.mjs';
 import { MAX_TIMER_DELAY_MS } from '../../../timeout/lib/index.js';
 import { assertPositiveFinite, NO_START_CAPABILITIES, resolveChildCwd, } from '../../../subagent/lib/index.js';
-import { DEFAULT_DISPOSE_GRACE_MS, startCodexRun, } from "./run.js";
+import { CODEX_PERMISSION_MODES, DEFAULT_CODEX_PERMISSION_MODE, DEFAULT_DISPOSE_GRACE_MS, codexStartupFailure, startCodexRun, } from "./run.js";
 export const name = 'subagent-codex';
 export const inject = ['subagents', 'subprocess'];
+const DEFAULT_PROVIDER_NAME = 'codex';
 export const Config = z.object({
+    providerName: z.string().min(1).default(DEFAULT_PROVIDER_NAME),
     env: z.dict(z.string()).default({}),
+    permissionMode: z.union([...CODEX_PERMISSION_MODES])
+        .default(DEFAULT_CODEX_PERMISSION_MODE),
     disposeGraceMs: z.number().default(DEFAULT_DISPOSE_GRACE_MS),
 });
 class CodexProvider {
+    name;
     ctx;
     config;
-    name = 'codex';
     capabilities = NO_START_CAPABILITIES;
     inheritsParentContext = false;
-    constructor(ctx, config) {
+    constructor(name, ctx, config) {
+        this.name = name;
         this.ctx = ctx;
         this.config = config;
     }
@@ -30,29 +35,45 @@ class CodexProvider {
         if (parentCwd === undefined) {
             throw new Error('subagent-codex: no working directory for the child — delegate from a parent session that has one');
         }
+        let cwd;
+        try {
+            cwd = resolveChildCwd('subagent-codex', undefined, parentCwd);
+        }
+        catch (error) {
+            if (request.signal.aborted) {
+                throw new Error('subagent-codex: request was aborted before app-server startup');
+            }
+            throw codexStartupFailure(error);
+        }
         const spec = {
-            cwd: resolveChildCwd('subagent-codex', undefined, parentCwd),
+            cwd,
+            permissionMode: this.config.permissionMode,
             env: this.config.env,
             disposeGraceMs: this.config.disposeGraceMs,
             spawn: spawnSpec => this.ctx.subprocess.spawn(spawnSpec),
             onError: (error, stopReason) => {
-                this.ctx.logger.warn(`subagent-codex: child run failed (${stopReason}): ${error.message}`);
+                this.ctx.logger.warn(`subagent-codex "${this.name}": child run failed (${stopReason}): ${error.message}`);
             },
         };
         return startCodexRun(request, spec);
     }
 }
 /**
- * Register the fixed `codex` provider.
+ * Register one Profile-named Codex provider.
  * @param ctx - context carrying shared subagent and subprocess services.
- * @param config - explicit child environment and disposal grace.
+ * @param config - registry name, permission mode, child environment, and disposal grace.
  */
 export function apply(ctx, config) {
-    const resolved = config;
+    const resolved = {
+        providerName: config.providerName ?? DEFAULT_PROVIDER_NAME,
+        env: config.env,
+        permissionMode: config.permissionMode ?? DEFAULT_CODEX_PERMISSION_MODE,
+        disposeGraceMs: config.disposeGraceMs,
+    };
     assertPositiveFinite('subagent-codex', 'disposeGraceMs', resolved.disposeGraceMs);
     if (resolved.disposeGraceMs > MAX_TIMER_DELAY_MS) {
         throw new Error(`subagent-codex: disposeGraceMs must be no greater than ${MAX_TIMER_DELAY_MS}`);
     }
-    ctx.subagents.registerProvider(new CodexProvider(ctx, resolved));
+    ctx.subagents.registerProvider(new CodexProvider(resolved.providerName, ctx, resolved));
 }
 //# sourceMappingURL=index.js.map

package/dist/kernel/subagent-codex/lib/types/run.d.ts

@@ -12,20 +12,29 @@ import type { SubprocessHandle, SubprocessSpawnSpec } from '../../../subprocess/
 import { CodexAppServerWire } from './wire.ts';
 /** Default POSIX grace between subprocess termination tiers. */
 export declare const DEFAULT_DISPOSE_GRACE_MS = 3000;
+/** Profile-selectable non-interactive Codex permission mode. */
+export type CodexPermissionMode = 'never' | 'approve-for-me' | 'dangerously-bypass-approvals-and-sandbox';
+/** Native non-interactive Codex modes mapped to official `thread/start` fields. */
+export declare const CODEX_PERMISSION_MODES: readonly ["never", "approve-for-me", "dangerously-bypass-approvals-and-sandbox"];
+/** Safe default for unattended Codex runs. */
+export declare const DEFAULT_CODEX_PERMISSION_MODE: CodexPermissionMode;
 /**
- * Resolve the fixed app-server command for a platform.
- *
- * Windows npm and pnpm installs expose `codex.cmd`, which requires `cmd.exe`;
- * the argv is constant so no task or configuration text enters the
- * shell boundary.
- * @param platform - host platform used to select the executable boundary.
- * @returns argv for the fixed Codex app-server command.
+ * Hide an unpublished Host failure behind fixed safe startup facts.
+ * @param cause Original Host failure retained for internal diagnostics.
+ * @returns A startup failure whose message contains only fixed safe facts.
+ */
+export declare function codexStartupFailure(cause: unknown): Error;
+/**
+ * Fixed package-local app-server command, independent of the host `PATH`.
+ * @returns Node, the official wrapper, and the fixed app-server arguments.
  */
-export declare function codexAppServerArgv(platform?: NodeJS.Platform): string[];
+export declare function codexAppServerArgv(): string[];
 /** Fully resolved inputs for one Codex app-server run. */
 export interface CodexRunSpec {
     /** Parent Session workspace, also supplied to `thread/start`. */
     readonly cwd: string;
+    /** Profile-selected native non-interactive permission mode. */
+    readonly permissionMode: CodexPermissionMode;
     /** Explicit deployment/test environment layered after the shared scrub. */
     readonly env: Record<string, string>;
     /** Subprocess termination grace passed to the shared process-tree owner. */

package/dist/kernel/subagent-codex/lib/types/run.js

@@ -7,24 +7,70 @@
  * @module @nomix-ai/nomix-subagent-codex/run
  */
 import { randomUUID } from 'node:crypto';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, resolve } from 'node:path';
 import { SessionId } from '../../../session/lib/index.js';
 import { settleRunResult, subprocessRunHandle, } from '../../../subagent/lib/index.js';
-import { CodexAppServerWire } from "./wire.js";
+import { CodexAppServerWire, } from "./wire.js";
 /** Default POSIX grace between subprocess termination tiers. */
 export const DEFAULT_DISPOSE_GRACE_MS = 3_000;
+const codexPackageJsonPath = createRequire(import.meta.url).resolve('@openai/codex/package.json');
+const codexPackageManifest = JSON.parse(readFileSync(codexPackageJsonPath, 'utf8'));
+/** Absolute package-local JavaScript wrapper selected by the package manifest. */
+const CODEX_PACKAGE_BIN = resolve(dirname(codexPackageJsonPath), codexPackageManifest.bin.codex);
+/** Native non-interactive Codex modes mapped to official `thread/start` fields. */
+export const CODEX_PERMISSION_MODES = [
+    'never',
+    'approve-for-me',
+    'dangerously-bypass-approvals-and-sandbox',
+];
+/** Safe default for unattended Codex runs. */
+export const DEFAULT_CODEX_PERMISSION_MODE = 'never';
+function failureDiagnostic(facts) {
+    const fields = [
+        'product: Codex',
+        `stage: ${facts.stage}`,
+        `category: ${facts.category}`,
+    ];
+    if (facts.httpStatus !== undefined) {
+        fields.push(`HTTP status: ${facts.httpStatus}`);
+    }
+    const processFields = [
+        ['exit code', facts.outcome?.exitCode],
+        ['signal', facts.outcome?.signal],
+    ];
+    for (const [label, value] of processFields) {
+        if (value !== null && value !== undefined)
+            fields.push(`${label}: ${value}`);
+    }
+    return `Product subagent failure (${fields.join('; ')})`;
+}
+class CodexRunFailure extends Error {
+    facts;
+    constructor(facts, cause) {
+        super(`subagent-codex: ${failureDiagnostic(facts)}`, cause === undefined ? undefined : { cause });
+        this.facts = facts;
+        this.name = 'CodexRunFailure';
+    }
+}
 /**
- * Resolve the fixed app-server command for a platform.
- *
- * Windows npm and pnpm installs expose `codex.cmd`, which requires `cmd.exe`;
- * the argv is constant so no task or configuration text enters the
- * shell boundary.
- * @param platform - host platform used to select the executable boundary.
- * @returns argv for the fixed Codex app-server command.
+ * Hide an unpublished Host failure behind fixed safe startup facts.
+ * @param cause Original Host failure retained for internal diagnostics.
+ * @returns A startup failure whose message contains only fixed safe facts.
  */
-export function codexAppServerArgv(platform = process.platform) {
-    return platform === 'win32'
-        ? ['cmd.exe', '/d', '/s', '/c', 'codex', 'app-server', '--stdio']
-        : ['codex', 'app-server', '--stdio'];
+export function codexStartupFailure(cause) {
+    return new CodexRunFailure({
+        stage: 'initialize',
+        category: 'unknown',
+    }, cause);
+}
+/**
+ * Fixed package-local app-server command, independent of the host `PATH`.
+ * @returns Node, the official wrapper, and the fixed app-server arguments.
+ */
+export function codexAppServerArgv() {
+    return [process.execPath, CODEX_PACKAGE_BIN, 'app-server', '--stdio'];
 }
 function thrown(value) {
     /* v8 ignore next -- typed subprocess/wire failures reject with Error. */
@@ -59,19 +105,33 @@ export function textTask(prompt) {
  */
 export async function disposeCodexChild(wire, child) {
     wire.close();
-    if (child.pid <= 0) {
-        await child.done.catch(() => { });
-        return;
-    }
-    try {
-        child.stdin?.end();
+    if (child.pid > 0) {
+        let outcome;
+        void child.done.then((value) => { outcome = value; }, 
+        /* v8 ignore next -- a positive pid excludes spawn-level done rejection. */
+        () => { });
+        try {
+            child.stdin?.end();
+        }
+        catch {
+            // A concurrently closed stdin does not change tree ownership below.
+        }
+        child.terminate();
+        try {
+            await child.waitForExit();
+        }
+        catch (error) {
+            throw new CodexRunFailure({
+                stage: 'teardown',
+                category: 'unknown',
+                outcome,
+            }, thrown(error));
+        }
+        await child.done;
     }
-    catch {
-        // A concurrently closed stdin does not change tree ownership below.
+    else {
+        await child.done.catch(() => { });
     }
-    child.terminate();
-    await child.waitForExit();
-    await child.done;
 }
 /**
  * Start the real `codex app-server --stdio` child and publish its one-shot run.
@@ -84,19 +144,70 @@ export async function startCodexRun(request, spec) {
     if (request.signal.aborted) {
         throw new Error('subagent-codex: request was aborted before app-server startup');
     }
-    const child = spec.spawn({
-        argv: codexAppServerArgv(),
-        cwd: spec.cwd,
-        stdio: { stdin: 'pipe', stdout: 'pipe', stderr: 'inherit' },
-        graceMs: spec.disposeGraceMs,
-        env: spec.env,
+    let child;
+    try {
+        child = spec.spawn({
+            argv: codexAppServerArgv(),
+            cwd: spec.cwd,
+            stdio: { stdin: 'pipe', stdout: 'pipe', stderr: 'pipe' },
+            graceMs: spec.disposeGraceMs,
+            env: spec.env,
+        });
+    }
+    catch (error) {
+        throw new CodexRunFailure({
+            stage: 'initialize',
+            category: 'unknown',
+        }, thrown(error));
+    }
+    const wire = new CodexAppServerWire(child.stdout, child.stdin, spec.permissionMode);
+    const onStderr = (chunk) => {
+        const bytes = typeof chunk === 'string' ? Buffer.from(chunk) : chunk;
+        wire.observeStderr(bytes.toString());
+        try {
+            // Synchronous fd forwarding preserves byte order without owning a
+            // backpressure queue. A slow host sink can block this event-loop turn.
+            writeFileSync(process.stderr.fd, bytes);
+        }
+        catch {
+            // Host stderr is an observation sink, not a child-run failure authority.
+        }
+    };
+    const onStderrError = () => {
+        // Stderr observation is auxiliary. JSON-RPC and child.done remain the
+        // only terminal authorities if the diagnostic stream itself fails.
+    };
+    child.stderr?.on('data', onStderr);
+    child.stderr?.on('error', onStderrError);
+    const disposeProcess = async () => {
+        try {
+            await disposeCodexChild(wire, child);
+            // Let stderr already queued by the process close reach both bounded
+            // diagnostic consumers before their listeners are detached.
+            await new Promise((resolve) => { setImmediate(resolve); });
+        }
+        finally {
+            child.stderr?.off('data', onStderr);
+            child.stderr?.off('error', onStderrError);
+        }
+    };
+    let processFailureFacts;
+    const processFailure = child.done.then((outcome) => {
+        processFailureFacts = {
+            stage: 'process',
+            category: 'process-exit',
+            outcome,
+        };
+        throw new CodexRunFailure(processFailureFacts);
+    }, (error) => {
+        processFailureFacts = {
+            stage: 'process',
+            category: 'unknown',
+        };
+        throw new CodexRunFailure(processFailureFacts, thrown(error));
     });
-    const wire = new CodexAppServerWire(child.stdout, child.stdin);
-    const disposeProcess = () => disposeCodexChild(wire, child);
-    const processFailure = child.done.then(outcome => Promise.reject(new Error('subagent-codex: app-server exited before the run settled '
-        + `(code ${String(outcome.exitCode)}, signal ${String(outcome.signal)})`)), (error) => Promise.reject(thrown(error)));
-    // A normal post-result dispose also closes the process. Keep that expected
-    // late rejection observed after the result race has already settled.
+    // A normal post-result dispose also closes the process. Keep its expected
+    // late rejection observed when the terminal result settles first.
     processFailure.catch(() => { });
     const runAbort = new AbortController();
     const requestCancel = () => {
@@ -107,31 +218,113 @@ export async function startCodexRun(request, spec) {
     };
     const onAbort = () => { requestCancel(); };
     request.signal.addEventListener('abort', onAbort, { once: true });
+    let startupStage = 'initialize';
     try {
         wire.start();
         await Promise.race([wire.initialize(request.signal), processFailure]);
+        startupStage = 'thread-start';
         await Promise.race([wire.startThread(spec.cwd, request.signal), processFailure]);
     }
     catch (error) {
         request.signal.removeEventListener('abort', onAbort);
+        const cancelledBeforeCleanup = runAbort.signal.aborted;
+        if (!(error instanceof CodexRunFailure) && !cancelledBeforeCleanup) {
+            // Node reports stdout EOF before the child close that owns its outcome.
+            // Let an already-exiting process publish those facts before rollback.
+            await new Promise((resolve) => { setImmediate(resolve); });
+        }
+        const failure = new CodexRunFailure({
+            stage: startupStage,
+            category: 'unknown',
+            outcome: error instanceof CodexRunFailure
+                ? error.facts.outcome
+                : processFailureFacts?.outcome,
+        }, thrown(error));
         try {
             await disposeProcess();
         }
         catch (disposeError) {
-            throw new AggregateError([thrown(error), thrown(disposeError)], 'subagent-codex: startup failed and app-server cleanup also failed');
+            const cleanupFailure = thrown(disposeError);
+            throw new AggregateError([failure, cleanupFailure], `${failure.message}; ${cleanupFailure.message}`);
+        }
+        if (cancelledBeforeCleanup) {
+            throw new Error('subagent-codex: request was aborted before run publication');
         }
-        if (runAbort.signal.aborted) {
+        try {
+            request.signal.throwIfAborted();
+        }
+        catch {
             throw new Error('subagent-codex: request was aborted before run publication');
         }
-        throw thrown(error);
+        throw failure;
     }
     const collectOutput = () => wire.collectOutput();
+    let diagnostic;
+    const recordFailureDiagnostic = (facts) => {
+        const failure = failureDiagnostic(facts);
+        const permission = wire.collectDiagnostic();
+        diagnostic = permission === undefined
+            ? failure
+            : `${failure}\n${permission}`;
+        return diagnostic;
+    };
+    const withProcessOutcome = (facts) => {
+        const outcome = processFailureFacts?.outcome;
+        return outcome === undefined
+            ? facts
+            : { ...facts, outcome };
+    };
+    const publishedProcessFailure = processFailure.catch(async (error) => {
+        // Frames already queued by the exiting app-server remain authoritative.
+        // One I/O turn lets them settle before process exit ends the run.
+        await new Promise((resolve) => { setImmediate(resolve); });
+        throw error;
+    });
     const result = settleRunResult({
-        attempt: () => Promise.race([
-            wire.runTurn(texts, runAbort.signal),
-            processFailure,
-        ]),
+        attempt: async () => {
+            try {
+                const terminal = await Promise.race([
+                    wire.runTurn(texts, runAbort.signal),
+                    publishedProcessFailure,
+                ]);
+                if (terminal.stopReason === 'completed')
+                    return terminal;
+                // Let stderr already queued with the terminal frame contribute its
+                // fixed permission fact before the non-completed result is snapshotted.
+                await new Promise((resolve) => { setImmediate(resolve); });
+                const facts = withProcessOutcome(wire.collectFailure());
+                return { ...terminal, diagnostic: recordFailureDiagnostic(facts) };
+            }
+            catch (error) {
+                // Give stderr data already queued in Node one turn to reach the wire
+                // before settlement snapshots the diagnostic.
+                await new Promise((resolve) => { setImmediate(resolve); });
+                const endedBeforeTerminal = wire.endedBeforeTerminal();
+                if (endedBeforeTerminal
+                    && processFailureFacts === undefined
+                    && !runAbort.signal.aborted) {
+                    try {
+                        const exited = await child.waitForExit(AbortSignal.timeout(Math.ceil(spec.disposeGraceMs)));
+                        if (exited)
+                            await child.done;
+                    }
+                    catch {
+                        // The wire failure remains authoritative when exit observation fails.
+                    }
+                }
+                const facts = error instanceof CodexRunFailure
+                    ? error.facts
+                    : endedBeforeTerminal && processFailureFacts !== undefined
+                        ? processFailureFacts
+                        : withProcessOutcome(wire.collectFailure());
+                recordFailureDiagnostic(facts);
+                throw error instanceof CodexRunFailure
+                    ? error
+                    : new CodexRunFailure(facts, thrown(error));
+            }
+        },
         collectOutput,
+        collectDiagnostic: () => diagnostic,
         cancelled: () => runAbort.signal.aborted,
         onError: spec.onError,
         signal: request.signal,

package/dist/kernel/subagent-codex/lib/types/wire.d.ts

@@ -9,6 +9,13 @@
 import type { Readable, Writable } from 'node:stream';
 import type { ContentBlock } from '../../../llm/lib/index.js';
 import type { SubagentResult } from '../../../subagent/lib/index.js';
+import type { CodexPermissionMode } from './run.ts';
+/** Product facts owned by the Codex wire after publication. */
+export interface CodexWireFailureFacts {
+    readonly stage: 'turn-start' | 'turn';
+    readonly category: string;
+    readonly httpStatus?: number | undefined;
+}
 /**
  * One app-server connection and its single ephemeral thread/turn.
  *
@@ -17,6 +24,7 @@ import type { SubagentResult } from '../../../subagent/lib/index.js';
  */
 export declare class CodexAppServerWire {
     private readonly input;
+    private readonly permissionMode;
     private readonly transport;
     private readonly fatal;
     private threadId;
@@ -26,10 +34,23 @@ export declare class CodexAppServerWire {
     private readonly earlyTurnNotifications;
     private lastFinalAnswer;
     private lastUnphasedAnswer;
+    private diagnostic;
+    private failure;
+    private diagnosticOrder;
+    private observationOrder;
+    private pendingDiagnostic;
+    private stderrTail;
+    private inputEnded;
+    private terminalObserved;
     private closed;
-    constructor(input: Readable, output: Writable);
+    constructor(input: Readable, output: Writable, permissionMode: CodexPermissionMode);
     /** Start reading app-server frames. */
     start(): void;
+    /**
+     * Whether protocol output ended before a terminal turn notification.
+     * @returns `true` only for an early protocol close without a terminal turn.
+     */
+    endedBeforeTerminal(): boolean;
     /**
      * Perform the required app-server initialize/initialized handshake.
      * @param signal - unpublished-start cancellation.
@@ -59,6 +80,23 @@ export declare class CodexAppServerWire {
      * @returns the selected final or nullable-phase text block, if any.
      */
     collectOutput(): ContentBlock[];
+    /**
+     * The latest safe unattended permission fact observed for this run.
+     * @returns provider-authored diagnostic text, when one was observed.
+     */
+    collectDiagnostic(): string | undefined;
+    /**
+     * The structured failure fact observed for this published turn.
+     * Call only after a non-completed return or rejection from {@link runTurn}.
+     * @returns the fixed stage/category pair and optional HTTP status.
+     */
+    collectFailure(): CodexWireFailureFacts;
+    /**
+     * Observe product stderr while retaining only enough tail to recognize fixed
+     * permission signatures. The raw text is never copied into the diagnostic.
+     * @param chunk - one decoded stderr chunk already forwarded to the host.
+     */
+    observeStderr(chunk: string): void;
     /** Detach JSON-RPC listeners and reject outstanding requests. Idempotent. */
     close(): void;
     private guarded;
@@ -68,7 +106,17 @@ export declare class CodexAppServerWire {
     private readonly onInputEnd;
     private observePendingTurnId;
     private commitTurnId;
+    /**
+     * Validate the request's thread and turn association.
+     * @returns `true` when the matching turn is still provisional, so the caller
+     * defers its diagnostic until `commitTurnId()`.
+     */
     private validateRunIds;
+    private recordRequestDiagnostic;
+    private recordDiagnostic;
+    private recordFailure;
+    private nextObservationOrder;
+    private recordDeclinedItem;
     private handleServerRequest;
     private handleNotification;
 }