@ckanner/flywheel 0.32.1 → 0.33.1

package/node_modules/dsh-subagent-codex-pro/lib/index.js

@@ -0,0 +1,830 @@
+/**
+ * A Codex delegation that can carry a model and a reasoning effort.
+ *
+ * ## Why this exists
+ *
+ * `@deepseek-ai/dsh-subagent-codex` declares `NO_START_CAPABILITIES`, so its
+ * `tool-subagent` row cannot enable `modelSelectionSettings` — that requires a
+ * provider declaring `agentOptions`, which the Codex provider does not. The
+ * Codex protocol supports the choices this package exposes: `model` on
+ * `thread/start`, per-turn `effort` on `turn/start`, and model/cwd/permission
+ * overrides on `thread/resume` (0.165+). The official adapter sends none of
+ * them; a thinking level is not a `thread/start` field in 0.165/0.166.
+ *
+ * Enabling the flag on a Codex row of our own provider was tried and did not
+ * work: the row vanished with no tool and no error, while a control row — same
+ * provider, same row, flag off — registered fine. That defect belongs to the
+ * flag, not to the provider, and is reported upstream.
+ *
+ * ## What this does instead
+ *
+ * Two things, both under this package's control:
+ *
+ * 1. **Execution** is a port of the official app-server adapter (`wire.ts`,
+ *    `run.ts`), with `model` on `thread/start`, `effort` on `turn/start`, and
+ *    explicit model/cwd/permission overrides plus effective-config verification
+ *    on `thread/resume`. That is the same protocol the official provider speaks,
+ *    including its initialize handshake, ephemeral thread, unattended approval
+ *    decisions, and terminal-answer selection.
+ * 2. **The tool** is registered on `agent/created` into that Agent's own context
+ *    — the path `dsh-plugin-lcu` uses — so the harness's preset-row machinery
+ *    stays out of the way. `presets` names the presets that get it.
+ *
+ * `model` and `reasoning_effort` appear while this plugin's independent
+ * modelSelection setting is enabled. Codex model ids are not DSH LLM routes.
+ *
+ * @module dsh-subagent-codex-pro
+ */
+import { appendFileSync, readFileSync, statSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { settleJob } from "./jobs.js";
+import { CodexRunFailure, DEFAULT_RUN_TIMEOUT_MS, chooseThread, delegateOnce, startCodexRun } from "./run.js";
+import { DEFAULT_ORIGINATOR } from "./wire.js";
+import { createCodexTool } from "./tool.js";
+/** Cordis plugin name. */
+export const name = 'codex-pro';
+/**
+ * The services this plugin cannot work without.
+ *
+ * `subagents` is the provider registry. Everything else — the Agent registry,
+ * the preset registry, the host opt-in — is looked up with `ctx.get`, so a
+ * deployment missing one degrades instead of failing to load.
+ */
+export const inject = ['subagents'];
+/**
+ * Check a caller-named deadline.
+ *
+ * A duration, so it must be a whole number of milliseconds: negative and
+ * fractional values have no meaning, and silently rounding one would give a
+ * caller a deadline it did not ask for. `0` is allowed and means no deadline,
+ * which is what the plugin's own configuration uses to disable it.
+ *
+ * @param value - the deadline a call named.
+ * @returns the deadline, unchanged.
+ * @throws when it is not a whole non-negative number of milliseconds.
+ */
+export function checkedTimeout(value) {
+    if (!Number.isFinite(value))
+        throw new Error('subagent_codex: timeout_ms must be a finite number');
+    if (!Number.isInteger(value))
+        throw new Error('subagent_codex: timeout_ms must be whole milliseconds');
+    if (value < 0)
+        throw new Error('subagent_codex: timeout_ms must not be negative');
+    return value;
+}
+/**
+ * Check a caller-named output schema's shape.
+ *
+ * The harness applies the same rule to a schema it passes a provider —
+ * `assertObjectJsonSchema` — so matching it means a schema this tool accepts is
+ * one the harness would too. Only the root is checked: it must be an object with
+ * `type: "object"`, because Codex constrains a whole answer and a bare array or
+ * scalar has nowhere to put the shape.
+ *
+ * @param value - the schema a call named.
+ * @returns the schema, unchanged.
+ * @throws when it is not an object-rooted JSON Schema.
+ */
+export function checkedOutputSchema(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new Error('subagent_codex: output_schema must be a JSON Schema object');
+    }
+    const schema = value;
+    if (schema.type !== 'object') {
+        throw new Error('subagent_codex: output_schema must have "type": "object" at its root');
+    }
+    return schema;
+}
+/**
+ * Check one caller-named image path.
+ *
+ * The path must be absolute and must name a file this plugin could hand the
+ * app-server. Whether it exists is checked where the run is prepared, next to
+ * the check for the working directory, because that is where a real path is.
+ *
+ * @param requested - the path a call named.
+ * @returns the path, unchanged.
+ * @throws when it is not an absolute path.
+ */
+export function checkedImagePath(requested) {
+    if (requested.trim() === '')
+        throw new Error('subagent_codex: image paths must not be empty');
+    if (!requested.startsWith('/')) {
+        throw new Error(`subagent_codex: image paths must be absolute, got "${requested}"`);
+    }
+    return requested;
+}
+/**
+ * Check a caller-named working directory's shape.
+ *
+ * Only the shape is checked — absolute and non-empty — so the rule is testable
+ * without a filesystem. Whether the path exists and is a directory is checked
+ * where the run is prepared, because that is where a real path matters.
+ *
+ * @param requested - the path a call named.
+ * @returns the path, unchanged.
+ * @throws when it is not an absolute path.
+ */
+export function checkedWorkdir(requested) {
+    if (requested.trim() === '')
+        throw new Error('subagent_codex: cwd must not be empty');
+    if (!requested.startsWith('/')) {
+        throw new Error(`subagent_codex: cwd must be an absolute path, got "${requested}"`);
+    }
+    return requested;
+}
+/**
+ * Whether a model route's declared modalities refuse images.
+ *
+ * This is the harness's own rule, and matching it exactly is the point: an image
+ * is refused only when the route **declares** input modalities and `image` is not
+ * among them. An undeclared route is left to the harness, which rejects an
+ * attachment for a model that cannot read it anyway.
+ *
+ * Being stricter cost a real screenshot. The default `deepseek-flash` entry
+ * declares `['text', 'image']`, and an earlier guard here failed closed whenever
+ * the route could not be resolved — which turned every image into a text note in
+ * a session that could have displayed it.
+ *
+ * @param info - the resolved model route, when it could be resolved.
+ * @returns whether the route says it cannot take images.
+ */
+export function routeRefusesImages(info) {
+    const declared = info?.inputModalities;
+    return declared !== undefined && !declared.includes('image');
+}
+/** Media types this plugin hands the attachment store, by file extension. */
+const IMAGE_MEDIA_TYPES = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.webp': 'image/webp',
+    '.gif': 'image/gif',
+};
+/** A cap on one image, so a stray large file cannot stall a delegation. */
+const MAX_IMAGE_BYTES = 20 * 1024 * 1024;
+/**
+ * A line naming where each image is, appended to the text.
+ *
+ * A foreground call carries the pictures as blocks, but a background call's
+ * result is a string by contract — its reader sees this text and nothing else. So
+ * the paths go in the text as well: a screenshot a background delegation took is
+ * still a file on this host, and naming it is the difference between the work
+ * being usable and being lost.
+ *
+ * @param text - the delegation's answer.
+ * @param images - the images the run produced.
+ * @returns the answer with the image line appended.
+ */
+export function withImageNote(text, images) {
+    if (images.length === 0)
+        return text;
+    const paths = images.map((image) => image.path).filter((path) => path !== undefined);
+    const label = images.length === 1 ? 'image' : 'images';
+    return paths.length === 0
+        ? `${text}\n\n[${String(images.length)} ${label}]`
+        : `${text}\n\n[${String(images.length)} ${label}: ${paths.join(', ')}]`;
+}
+/** Stable text for an image the model could not be handed. */
+function imageNote(reason) {
+    return `[image not delivered: ${reason}]`;
+}
+/** The media type for a path, when its extension names one this store admits. */
+function mediaTypeOf(path) {
+    const dot = path.lastIndexOf('.');
+    return dot < 0 ? undefined : IMAGE_MEDIA_TYPES[path.slice(dot).toLowerCase()];
+}
+/** This package's own version, read once for the diagnostic line. */
+const PLUGIN_VERSION = (() => {
+    try {
+        const require_ = createRequire(import.meta.url);
+        const pkg = require_('../package.json');
+        return pkg.version ?? 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+})();
+/** The effort values Codex accepts; used only for diagnostics. */
+const KNOWN_EFFORTS = ['minimal', 'low', 'medium', 'high', 'xhigh', 'max'];
+/** The unattended default: a delegated task must run without a human present. */
+const DEFAULT_PERMISSION_MODE = 'workspace-write';
+/** Tool calls may narrow their configured policy, never expand it implicitly. */
+export function resolvePermissionOverride(configured, requested) {
+    const permission = requested ?? configured;
+    if (permission !== configured && permission !== 'read-only'
+        && !(configured === 'dangerously-bypass-approvals-and-sandbox' && permission === 'workspace-write')) {
+        throw new Error('subagent_codex: permission override exceeds the configured policy; change plugin configuration explicitly');
+    }
+    return permission;
+}
+/**
+ * Append one line to `~/.dsh/codex-pro.log`.
+ *
+ * A plugin has no log surface a running session can read, and a tool that fails
+ * to register is otherwise silent. Never throws.
+ *
+ * @param message - the line to record.
+ */
+function diag(message) {
+    try {
+        appendFileSync(join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), 'codex-pro.log'), `${new Date().toISOString()} ${message}\n`);
+    }
+    catch {
+        // Diagnostics must never affect what they describe.
+    }
+}
+/** Join the textual blocks of a delegated prompt. */
+function promptText(prompt) {
+    return prompt
+        .filter((block) => block.type === 'text')
+        .map((block) => block.text)
+        .join('\n\n');
+}
+/**
+ * One delegation to Codex, exposed as a provider the harness can start.
+ *
+ * Exported so the provider adapter can be exercised against the same fake
+ * app-server as the tool path; the plugin's `apply` is its only production
+ * constructor.
+ */
+export class CodexExecProvider {
+    name;
+    inheritsParentContext = false;
+    /**
+     * The declaration that unlocks the delegation tool's model surface.
+     *
+     * `agentOptions: true` is what `tool-subagent` checks before accepting either a
+     * configured `agentOptions` or `modelSelectionSettings: true` on its row.
+     */
+    capabilities = {
+        agentOptions: true,
+        agentPreset: false,
+        outputSchema: true,
+        depthLimit: false,
+    };
+    /**
+     * The resolved configuration.
+     *
+     * A plain field rather than a constructor parameter property: Node's
+     * type-stripping mode rejects that syntax outright, which made this module
+     * unimportable from a test and left its pure helpers untestable.
+     */
+    resolved;
+    constructor(resolved) {
+        this.resolved = resolved;
+        this.name = resolved.providerName;
+    }
+    /**
+     * Start one Codex run over the app-server protocol.
+     *
+     * @param request - the delegation the harness resolved.
+     * @returns a run handle; its `result` settles with the child's final message.
+     */
+    async start(request) {
+        const cwd = request.cwd ?? request.parent.session.header.cwd;
+        if (cwd === undefined) {
+            throw new Error('codex-pro: the parent session has no working directory to delegate from');
+        }
+        const options = request.agentOptions;
+        // Host AgentOptions are not Codex configuration. Unsupported fields must
+        // never disappear behind the coarse agentOptions capability flag.
+        if (options?.provider !== undefined || options?.maxTokens !== undefined) {
+            throw new Error('codex-pro: provider and maxTokens overrides are not supported by this Codex backend');
+        }
+        const model = options?.model ?? this.resolved.model;
+        const effort = options?.reasoningEffort ?? this.resolved.reasoningEffort;
+        const spec = {
+            cwd,
+            command: this.resolved.command,
+            permissionMode: this.resolved.permissionMode,
+            model,
+            reasoningEffort: effort,
+            effort,
+            runTimeoutMs: this.resolved.runTimeoutMs,
+            ...(request.outputSchema === undefined
+                ? {}
+                : { outputSchema: request.outputSchema }),
+            env: this.resolved.env,
+            onProgress: (text) => { diag(`provider progress: ${text}`); },
+        };
+        diag(`provider start: model=${model ?? '<default>'} effort=${effort ?? '<default>'} cwd=${cwd} via=app-server`);
+        let run;
+        try {
+            run = await startCodexRun(request.prompt, spec, request.signal);
+        }
+        catch (error) {
+            diag(`provider start FAILED: ${error instanceof Error ? error.message : String(error)}`);
+            throw error;
+        }
+        diag(`provider start: published run ${run.id}`);
+        return {
+            id: run.id,
+            localAgent: undefined,
+            result: run.result.then((outcome) => {
+                diag(`provider done: stop=${outcome.stopReason} thread=${outcome.threadId ?? '<none>'} `
+                    + `usage=${outcome.usage.status}${outcome.usage.run === undefined ? '' : `(${String(outcome.usage.run.totalTokens)} tokens)`} `
+                    + `cleanup=${outcome.cleanup.confirmed ? 'confirmed' : 'UNCONFIRMED'} `
+                    + `rateLimits=${String(outcome.rateLimits.observations)} `
+                    + `config=${outcome.configuration === undefined ? 'n/a' : String(outcome.configuration.matched)}`);
+                if (outcome.configuration !== undefined) {
+                    diag(`provider config: requested=${JSON.stringify(outcome.configuration.requested)} `
+                        + `effective=${JSON.stringify(outcome.configuration.effective)}`);
+                }
+                // DSH diagnostics are bounded metadata, never raw server messages,
+                // prompts, paths, environment values, or structured answer contents.
+                const failure = outcome.execution.failure;
+                const diagnostic = [
+                    ...(outcome.stopReason === 'completed' ? [] : ['codex-pro: run ended as ' + outcome.stopReason]),
+                    ...(outcome.cleanup.confirmed ? [] : ['process cleanup could not be confirmed']),
+                    ...(outcome.schemaError === undefined ? [] : ['structured output did not satisfy the requested schema']),
+                    ...(failure === null ? [] : [`failure: ${failure.stage}/${failure.category}`
+                            + (failure.httpStatus === undefined ? '' : ` (HTTP ${String(failure.httpStatus)})`)]),
+                    ...(outcome.approvalDiagnostic === undefined ? [] : [outcome.approvalDiagnostic]),
+                ].join('; ').slice(0, 4096);
+                return {
+                    output: outcome.output,
+                    // The harness's own vocabulary has no `timeout`; its `aborted` is what
+                    // a cancelled run is, and the diagnostic carries the reason either way.
+                    stopReason: outcome.stopReason === 'timeout' ? 'aborted' : outcome.stopReason,
+                    ...(outcome.structured === undefined ? {} : { structured: outcome.structured }),
+                    ...(diagnostic === '' ? {} : { diagnostic }),
+                };
+            }),
+            // Host dispose returns void on success, but rejects when teardown cannot
+            // be confirmed. The manager records that failure separately from output.
+            dispose: async () => {
+                const cleanup = await run.teardown();
+                if (!cleanup.confirmed)
+                    throw new Error('codex-pro: process cleanup could not be confirmed');
+            },
+        };
+    }
+}
+/**
+ * Register the provider and the delegation tool.
+ *
+ * @param ctx - context carrying the subagent registry.
+ * @param config - provider name, defaults, and the presets to serve.
+ */
+export function apply(ctx, config = {}) {
+    const resolved = {
+        providerName: config.providerName ?? name,
+        command: config.command ?? 'codex',
+        permissionMode: config.permissionMode ?? DEFAULT_PERMISSION_MODE,
+        modelSelection: config.modelSelection ?? true,
+        threadMode: config.threadMode ?? 'ephemeral',
+        originator: config.originator ?? DEFAULT_ORIGINATOR,
+        runTimeoutMs: config.runTimeoutMs ?? DEFAULT_RUN_TIMEOUT_MS,
+        ...(config.model === undefined ? {} : { model: config.model }),
+        ...(config.reasoningEffort === undefined ? {} : { reasoningEffort: config.reasoningEffort }),
+        ...(config.env === undefined ? {} : { env: config.env }),
+    };
+    const presets = config.presets ?? ['codexprobe'];
+    try {
+        ctx.subagents.registerProvider(new CodexExecProvider(resolved));
+        diag(`apply: v${PLUGIN_VERSION} provider "${resolved.providerName}" registered with agentOptions: true `
+            + `(efforts: ${KNOWN_EFFORTS.join('/')}, permission=${resolved.permissionMode}); `
+            + `threadMode=${resolved.threadMode} originator=${JSON.stringify(resolved.originator)} `
+            + `timeout=${String(resolved.runTimeoutMs)}ms; `
+            + `presets=${JSON.stringify(presets)}`);
+    }
+    catch (error) {
+        diag(`apply: provider registration FAILED: ${String(error)}`);
+    }
+    /**
+     * Whether one Agent's committed preset is one this plugin serves.
+     *
+     * The registry is authoritative; the session header is only the value the
+     * session was created with, which the picker replaces afterwards.
+     */
+    const presetAllows = (agent) => {
+        const registry = ctx.get('agentPresets');
+        let composed;
+        let composeError;
+        try {
+            composed = registry?.composedPreset?.(agent.ctx);
+        }
+        catch (error) {
+            composeError = error instanceof Error ? error.message : String(error);
+        }
+        const header = agent.session.header.agentPreset;
+        const preset = composed ?? header;
+        const allowed = preset !== undefined && presets.includes(preset);
+        diag(`decide ${String(agent.id)} composed=${String(composed)} header=${String(header)} `
+            + `err=${String(composeError)} -> ${allowed ? 'serve' : 'skip'}`);
+        return allowed;
+    };
+    /** Register the delegation tool for one Agent. */
+    const serve = (agent) => {
+        const cwd = agent.session.header.cwd;
+        if (cwd === undefined) {
+            diag(`serve ${String(agent.id)}: skipped, the session has no working directory`);
+            return;
+        }
+        const selection = resolved.modelSelection;
+        // A delegation takes a minute or more, so a background job is the default
+        // shape: it keeps the turn free. Without the jobs service the tool still
+        // works, it just runs in the foreground and says nothing about it.
+        const jobs = ctx.get('jobs');
+        /**
+         * Whether the calling Agent's model route refuses images.
+         *
+         * The rule is the harness's own, deliberately: an image is refused only when
+         * the route **declares** input modalities and `image` is not among them. An
+         * undeclared route is left to the harness, which is where an attachment for a
+         * model that cannot read it is rejected anyway.
+         *
+         * Being stricter here was a real mistake: the default `deepseek-flash` entry
+         * declares `['text', 'image']`, and a guard that failed closed on an
+         * unresolvable route silently turned every screenshot into a text note. So an
+         * unresolvable route now delivers the image and lets the harness decide.
+         *
+         * @returns whether this plugin should withhold images.
+         */
+        const shouldWithholdImages = async () => {
+            const llm = ctx.get('llm');
+            const header = agent.session.requestHeader?.();
+            const options = agent.options;
+            const provider = header?.config?.provider ?? options?.provider;
+            const model = header?.config?.model ?? options?.model;
+            if (llm === undefined || provider === undefined || model === undefined)
+                return false;
+            try {
+                return routeRefusesImages(await llm.resolveModelInfo(provider, model));
+            }
+            catch {
+                return false;
+            }
+        };
+        /**
+         * Turn one finished delegation into the blocks the model receives.
+         *
+         * A run's images are read here, because the app-server reports them as paths
+         * on this host rather than as bytes, and handed to the attachment store so
+         * the model gets an image instead of a description of one. Nothing here can
+         * fail the delegation: a store that is absent, a route that cannot take
+         * images, and a file that cannot be read all become a text note, because the
+         * answer the delegation produced matters more than the picture beside it.
+         *
+         * @param outcome - the finished run.
+         * @param mode - the thread mode the run used.
+         * @returns the text, the thread id, and any content blocks to deliver.
+         */
+        const deliverResult = async (outcome, mode, machineOutput) => {
+            const text = withThreadMarker(outcome, mode, machineOutput);
+            const images = outcome.images ?? [];
+            if (images.length === 0)
+                return { text, threadId: outcome.threadId };
+            const notes = [];
+            const notesFor = (reason) => { notes.push(imageNote(reason)); };
+            const store = ctx.get('attachments');
+            if (store === undefined) {
+                for (let i = 0; i < images.length; i += 1)
+                    notesFor('no attachment store is mounted');
+                diag(`deliver: ${String(notes.length)} image(s) could not be attached (no store)`);
+                return { text: machineOutput ? text : `${text}\n\n${notes.join('\n')}`, threadId: outcome.threadId };
+            }
+            if (await shouldWithholdImages()) {
+                for (let i = 0; i < images.length; i += 1)
+                    notesFor('this model route declares no image input');
+                diag(`deliver: ${String(notes.length)} image(s) withheld from this model route`);
+                return { text: machineOutput ? text : `${text}\n\n${notes.join('\n')}`, threadId: outcome.threadId };
+            }
+            const payloads = [];
+            for (const image of images) {
+                try {
+                    if (image.data !== undefined) {
+                        payloads.push({ data: Buffer.from(image.data, 'base64'), mediaType: image.mimeType ?? 'image/png' });
+                        continue;
+                    }
+                    if (image.path === undefined) {
+                        notesFor('the image had neither a path nor data');
+                        continue;
+                    }
+                    const mediaType = mediaTypeOf(image.path);
+                    if (mediaType === undefined) {
+                        notesFor(`unsupported image type: ${image.path}`);
+                        continue;
+                    }
+                    const stat = statSync(image.path);
+                    if (stat.size > MAX_IMAGE_BYTES) {
+                        notesFor(`larger than ${String(MAX_IMAGE_BYTES)} bytes: ${image.path}`);
+                        continue;
+                    }
+                    payloads.push({ data: readFileSync(image.path), mediaType });
+                }
+                catch (error) {
+                    notesFor(`could not read ${image.path ?? 'the image'}: ${String(error)}`.slice(0, 200));
+                }
+            }
+            if (payloads.length === 0) {
+                diag(`deliver: ${String(notes.length)} image(s) could not be read`);
+                return { text: machineOutput ? text : `${text}\n\n${notes.join('\n')}`, threadId: outcome.threadId };
+            }
+            try {
+                const refs = await store.saveImages(payloads);
+                const deliveredText = machineOutput ? text : withImageNote(text, images);
+                const blocks = [
+                    { type: 'text', text: deliveredText },
+                    ...refs.map((ref) => ({ type: 'image', attachment: ref })),
+                ];
+                diag(`deliver: ${String(refs.length)} image(s) attached to the delegation result`);
+                return { text: deliveredText, threadId: outcome.threadId, blocks };
+            }
+            catch (error) {
+                notesFor(`the attachment store refused them: ${String(error)}`.slice(0, 200));
+                diag(`deliver: attachment store refused ${String(payloads.length)} image(s)`);
+                return { text: machineOutput ? text : `${text}\n\n${notes.join('\n')}`, threadId: outcome.threadId };
+            }
+        };
+        /**
+         * The durable thread this Agent session is reusing, for `threadMode: session`.
+         *
+         * One Agent is one session, so this map is that session's memory of the
+         * thread it opened; it is deliberately per-Agent rather than global, because
+         * two sessions delegating at once must not continue each other's work.
+         */
+        const sessionThread = new Map();
+        /**
+         * Threads this Agent is delegating in right now.
+         *
+         * A thread carries one turn at a time, so the session's remembered thread
+         * cannot be handed to two calls at once. Tracking it here turns that into a
+         * decision before the call starts rather than a failure after it.
+         */
+        const inFlight = new Set();
+        /** Run one call over the app-server protocol. */
+        const runCall = async (call, signal, onProgress) => {
+            // A delegation may name its own working directory; the session's is the
+            // default. The path is a working directory, not a sandbox boundary: what a
+            // run may touch is the permission mode's decision, not this one's.
+            let runCwd = cwd;
+            if (call.cwd !== undefined) {
+                runCwd = checkedWorkdir(call.cwd);
+                let stat;
+                try {
+                    stat = statSync(runCwd);
+                }
+                catch {
+                    throw new Error(`subagent_codex: cwd does not exist: ${runCwd}`);
+                }
+                if (!stat.isDirectory())
+                    throw new Error(`subagent_codex: cwd is not a directory: ${runCwd}`);
+            }
+            // Images are checked here, before anything is spawned: a path that does not
+            // exist should fail the call, not start a run that silently lacks the
+            // picture the task was about.
+            let runImages;
+            if (call.images !== undefined && call.images.length > 0) {
+                runImages = [];
+                for (const image of call.images) {
+                    const path = checkedImagePath(image);
+                    let stat;
+                    try {
+                        stat = statSync(path);
+                    }
+                    catch {
+                        throw new Error(`subagent_codex: image does not exist: ${path}`);
+                    }
+                    if (!stat.isFile())
+                        throw new Error(`subagent_codex: image is not a file: ${path}`);
+                    runImages.push(path);
+                }
+            }
+            const runTimeout = call.timeoutMs === undefined ? undefined : checkedTimeout(call.timeoutMs);
+            const runSchema = call.outputSchema === undefined
+                ? undefined
+                : checkedOutputSchema(call.outputSchema);
+            const callPermission = resolvePermissionOverride(resolved.permissionMode, call.permissionMode);
+            const timeoutMs = runTimeout ?? resolved.runTimeoutMs;
+            // One absolute deadline for this call, shared by the auto-resume retry: a
+            // second attempt after a failed resume must not receive a fresh budget.
+            const deadlineAt = timeoutMs > 0 ? Date.now() + timeoutMs : undefined;
+            const machineOutput = runSchema !== undefined;
+            // An explicit thread id wins; then an explicit mode; then the session's
+            // remembered thread; then the configured default.
+            const configured = resolved.threadMode;
+            const mode = call.threadMode ?? (configured === 'ephemeral' ? 'ephemeral' : 'persistent');
+            const remembered = sessionThread.get(String(agent.id));
+            const explicit = call.threadId;
+            const choice = chooseThread({
+                explicit,
+                configured,
+                // A remembered thread is only reusable for a durable call, and only in
+                // the directory it was created in: a Codex thread belongs to its own
+                // working directory, so a call that names another one starts fresh.
+                remembered: mode === 'persistent' && call.cwd === undefined ? remembered : undefined,
+                inFlight,
+            });
+            const reuse = choice.reuse;
+            if (choice.skippedBusy !== undefined) {
+                diag(`run: session thread ${choice.skippedBusy} is busy with another delegation - `
+                    + `this call gets a thread of its own`);
+            }
+            diag(`run: model=${call.model ?? '<default>'} effort=${call.reasoningEffort ?? '<default>'} `
+                + `thread=${mode}${reuse === undefined ? '' : ` resume=${reuse}`} `
+                + `cwd=${runCwd}${call.cwd === undefined ? '' : ' (call-named)'} `
+                + `images=${String(runImages?.length ?? 0)} `
+                + `schema=${runSchema === undefined ? 'none' : 'yes'} `
+                + `timeout=${String(runTimeout ?? resolved.runTimeoutMs)}ms`
+                + `${runTimeout === undefined ? '' : ' (call-named)'} `
+                + `prompt=${String(call.prompt.length)}B via=app-server`);
+            // Claim the thread for the whole call, so a concurrent delegation sees it
+            // as busy before it tries rather than failing when it does.
+            if (reuse !== undefined)
+                inFlight.add(reuse);
+            try {
+                const outcome = await delegateOnce({
+                    prompt: call.prompt,
+                    cwd: runCwd,
+                    command: resolved.command,
+                    permissionMode: callPermission,
+                    model: call.model,
+                    reasoningEffort: call.reasoningEffort,
+                    threadMode: mode,
+                    threadId: reuse,
+                    originator: resolved.originator,
+                    runTimeoutMs: timeoutMs,
+                    ...(deadlineAt === undefined ? {} : { deadlineAt }),
+                    images: runImages,
+                    outputSchema: runSchema,
+                    threadName: threadNameFor(call.label),
+                    env: resolved.env,
+                    signal,
+                    onStart: (id) => { diag(`run: published ${id}`); },
+                    onProgress,
+                });
+                if (mode === 'persistent' && outcome.threadId !== undefined) {
+                    sessionThread.set(String(agent.id), outcome.threadId);
+                }
+                diag(`run done: text=${String(outcome.text.length)}B thread=${outcome.threadId ?? '<none>'} `
+                    + `images=${String(outcome.images?.length ?? 0)} usage=${outcome.usage.status}`
+                    + `${outcome.usage.run === undefined ? '' : `(${String(outcome.usage.run.totalTokens)} tokens)`} `
+                    + `cleanup=${outcome.cleanup.confirmed ? 'confirmed' : 'UNCONFIRMED'} `
+                    + `rateLimits=${String(outcome.rateLimits.observations)} `
+                    + `config=${outcome.configuration === undefined ? 'n/a' : String(outcome.configuration.matched)}`);
+                if (outcome.configuration !== undefined) {
+                    diag(`run config: requested=${JSON.stringify(outcome.configuration.requested)} `
+                        + `effective=${JSON.stringify(outcome.configuration.effective)}`);
+                }
+                return await deliverResult(outcome, mode, machineOutput);
+            }
+            catch (error) {
+                // A session's remembered thread can be gone — the user removed it, or the
+                // Codex state moved. That is this plugin's own bookkeeping, so a fresh
+                // thread is the right repair; an id the caller passed explicitly is not
+                // repaired silently, because continuing it was the whole request.
+                // Only a resume that the app-server refused is repaired here. A turn that
+                // failed for its own reasons must not be retried: that would pay for the
+                // same work twice and hide the real failure behind a second attempt.
+                if (reuse !== undefined
+                    && explicit === undefined
+                    && mode === 'persistent'
+                    && error instanceof CodexRunFailure
+                    && error.facts.stage === 'thread-resume'
+                    // A protocol-level refusal or configuration mismatch is what a fresh
+                    // thread repairs. A timeout, caller abort, or process failure is not:
+                    // retrying those would muddy the reason the delegation stopped.
+                    && error.facts.category === 'protocol') {
+                    if (deadlineAt !== undefined && deadlineAt <= Date.now()) {
+                        diag(`run: remembered thread ${reuse} could not be resumed and the call has no budget left; not retrying`);
+                        throw error;
+                    }
+                    diag(`run: remembered thread ${reuse} could not be resumed (${String(error)}) - starting a new one `
+                        + `with ${deadlineAt === undefined ? 'no deadline' : `${String(deadlineAt - Date.now())}ms remaining`}`);
+                    sessionThread.delete(String(agent.id));
+                    const outcome = await delegateOnce({
+                        prompt: call.prompt,
+                        cwd: runCwd,
+                        command: resolved.command,
+                        permissionMode: callPermission,
+                        model: call.model,
+                        reasoningEffort: call.reasoningEffort,
+                        threadMode: mode,
+                        originator: resolved.originator,
+                        runTimeoutMs: timeoutMs,
+                        ...(deadlineAt === undefined ? {} : { deadlineAt }),
+                        images: runImages,
+                        outputSchema: runSchema,
+                        threadName: threadNameFor(call.label),
+                        env: resolved.env,
+                        signal,
+                        onStart: (id) => { diag(`run: published ${id}`); },
+                        onProgress,
+                    });
+                    if (outcome.threadId !== undefined)
+                        sessionThread.set(String(agent.id), outcome.threadId);
+                    diag(`run done: text=${String(outcome.text.length)}B thread=${outcome.threadId ?? '<none>'} `
+                        + `images=${String(outcome.images?.length ?? 0)} usage=${outcome.usage.status} `
+                        + `cleanup=${outcome.cleanup.confirmed ? 'confirmed' : 'UNCONFIRMED'}`);
+                    return await deliverResult(outcome, mode, machineOutput);
+                }
+                throw error;
+            }
+            finally {
+                if (reuse !== undefined)
+                    inFlight.delete(reuse);
+            }
+        };
+        try {
+            agent.ctx.tools.register(createCodexTool({
+                cwd,
+                modelSelectionEnabled: selection,
+                backgroundEnabled: jobs !== undefined,
+                defaultThreadMode: resolved.threadMode,
+                permissionMode: resolved.permissionMode,
+                threadControlEnabled: true,
+                ...(resolved.model === undefined ? {} : { model: resolved.model }),
+                ...(resolved.reasoningEffort === undefined ? {} : { reasoningEffort: resolved.reasoningEffort }),
+                run: (call) => runCall(call, call.signal),
+                startBackground: (call) => {
+                    if (jobs === undefined) {
+                        throw new Error('subagent_codex: background runs need the jobs service (@deepseek-ai/dsh-jobs)');
+                    }
+                    const controller = new AbortController();
+                    const id = jobs.start({
+                        kind: 'subagent',
+                        label: call.label,
+                        owner: String(agent.id),
+                        run: (handle) => {
+                            handle.updateProgress('starting Codex');
+                            return {
+                                cancel: (reason) => {
+                                    controller.abort(new Error(reason ?? 'codex delegation killed'));
+                                },
+                                // The child's own activity becomes the job's output, so
+                                // `job_output` shows how a long delegation is going rather than
+                                // only what it finally said. `settleJob` turns the delegation
+                                // into the outcome record the registry requires.
+                                done: settleJob(runCall(call, controller.signal, (text) => { handle.append(text); }))
+                                    .finally(() => { handle.updateProgress(''); }),
+                            };
+                        },
+                    });
+                    diag(`serve: background job ${id} started for "${call.label}"`);
+                    return id;
+                },
+            }));
+            diag(`serve ${String(agent.id)}: subagent_codex registered `
+                + `(modelSelection=${String(selection)}, background=${String(jobs !== undefined)}, `
+                + `model=${resolved.model ?? '<default>'}, via=app-server)`);
+        }
+        catch (error) {
+            diag(`serve ${String(agent.id)} FAILED: ${error instanceof Error ? `${error.name}: ${error.message}` : String(error)}`);
+        }
+    };
+    ctx.on('agent/created', ({ agent }) => {
+        if (!presetAllows(agent))
+            return;
+        serve(agent);
+    });
+    // A new task starts on the deployment default and the picker's mode is applied
+    // afterwards, so `agent/created` alone can see the wrong composition.
+    ctx.on('agent-preset/selected', (sessionId, presetId) => {
+        if (!presets.includes(presetId))
+            return;
+        const agents = ctx.get('agents');
+        const agent = agents?.get?.(String(sessionId));
+        if (agent === undefined) {
+            diag(`preset/selected ${String(sessionId)}: no live agent`);
+            return;
+        }
+        serve(agent);
+    });
+}
+/**
+ * Append the thread marker to a human-text delegation result.
+ *
+ * A machine-readable answer (one carrying `output_schema`) must stay valid JSON:
+ * appending a marker would make the whole result unparseable. Such a run keeps
+ * its thread id in the result envelope/diagnostic log instead of in the text.
+ *
+ * @param outcome - the finished run.
+ * @param mode - the thread mode the run used.
+ * @param machineOutput - whether the answer is schema-constrained JSON.
+ * @returns the text to report.
+ */
+export function withThreadMarker(outcome, mode, machineOutput) {
+    if (machineOutput || mode === 'ephemeral' || outcome.threadId === undefined)
+        return outcome.text;
+    return `${outcome.text}\n\n[codex thread ${outcome.threadId} · persistent · pass it as thread_id to continue]`;
+}
+/**
+ * The name a persistent thread carries in the Codex application.
+ *
+ * A thread from this provider has to report itself as `Codex Desktop` to be
+ * listed there at all, so the name is the only place that can say the work came
+ * from DSH and what it was. The model's own short description is the best label
+ * available, and the prefix keeps them together in a list sorted by recency.
+ *
+ * @param label - the call's short description.
+ * @returns the name to record.
+ */
+function threadNameFor(label) {
+    const trimmed = label.trim();
+    return trimmed === '' ? 'DSH · Codex delegation' : `DSH · ${trimmed}`;
+}
+//# sourceMappingURL=index.js.map