@astrosheep/square 0.3.91 → 0.3.93

package/dist/harness-links.js

@@ -1,79 +1,10 @@
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { isDeepStrictEqual } from 'node:util';
 import crossSpawn from 'cross-spawn';
+import { applyEdits, createScanner, findNodeAtLocation, modify, parse, parseTree } from 'jsonc-parser';
 import { SQUARE_IDENTITY } from './identity.js';
 import { truncateExternalDiagnostic } from './presentation.js';
-function packageRoot() {
-    // Emitted modules live in dist; package assets are one level above them.
-    return fileURLToPath(new URL('../', import.meta.url));
-}
-export function installHarnessLinks(links, force = false) {
-    const prepared = links.map((link) => {
-        if (!fs.existsSync(link.source)) {
-            throw new Error(`Harness link source is missing: ${link.source}`);
-        }
-        const existing = (() => {
-            try {
-                return fs.lstatSync(link.target);
-            }
-            catch (error) {
-                if (error.code === 'ENOENT')
-                    return undefined;
-                throw error;
-            }
-        })();
-        return {
-            ...link,
-            existing,
-            sourceIsDirectory: fs.statSync(link.source).isDirectory(),
-            alreadyManaged: existing !== undefined && sameLink(link.source, link.target),
-        };
-    });
-    for (const { target, existing, alreadyManaged } of prepared) {
-        if (existing !== undefined && !alreadyManaged && !force)
-            throw new Error(`Refusing to overwrite existing link: ${target}\nPass -f to replace it.`);
-    }
-    for (const { source, target, existing, sourceIsDirectory, alreadyManaged } of prepared) {
-        if (alreadyManaged)
-            continue;
-        fs.mkdirSync(path.dirname(target), { recursive: true });
-        if (existing !== undefined)
-            fs.rmSync(target, { recursive: true, force: true });
-        const symlinkType = os.platform() === 'win32' && sourceIsDirectory ? 'junction' : 'file';
-        fs.symlinkSync(source, target, symlinkType);
-    }
-    return prepared.map(({ target }) => target);
-}
-function sameLink(source, target) {
-    try {
-        return fs.realpathSync(source) === fs.realpathSync(target);
-    }
-    catch {
-        return false;
-    }
-}
-export function uninstallHarnessLinks(links) {
-    const removed = [];
-    for (const link of links) {
-        try {
-            if (fs.lstatSync(link.target).isSymbolicLink() && sameLink(link.source, link.target)) {
-                fs.rmSync(link.target, { force: true });
-                removed.push(link.target);
-            }
-        }
-        catch {
-            // A missing or user-owned target is preserved.
-        }
-    }
-    return removed;
-}
-export function doctorHarnessLinks(links) {
-    return links.map((link) => sameLink(link.source, link.target)
-        ? `✓ Square ${link.kind ?? 'link'} ${link.target}`
-        : `○ Square ${link.kind ?? 'link'} missing ${link.target}`);
-}
 function runOpenCode(homeDir, args) {
     const prefix = (() => {
         try {
@@ -94,39 +25,150 @@ function runOpenCode(homeDir, args) {
     return { status: result.status ?? 1, stdout: result.stdout || '', stderr: result.stderr || '' };
 }
 export function installOpenCodePlugin(homeDir, force = false, run = runOpenCode) {
-    // OpenCode v2's `plugin add` is idempotent and has no --global/--force flags.
+    // Explicit `square install` replaces owned pins/duplicates with one unpinned
+    // current-field entry; updating an exact old pin otherwise succeeds unchanged.
     void force;
-    const args = ['plugin', 'add', SQUARE_IDENTITY.packageName];
+    const configs = readOpenCodeConfigs(homeDir);
+    const entries = configs.flatMap((config) => config.entries);
+    const options = entries.map((entry) => entry.options).filter((value) => value !== undefined);
+    if (options.some((value) => !isDeepStrictEqual(value, options[0]))) {
+        throw new Error('Conflicting Square plugin options in OpenCode configuration; reconcile the owned plugin/plugins entries before installing.');
+    }
+    const canonical = options.length ? { package: SQUARE_IDENTITY.packageName, options: options[0] } : SQUARE_IDENTITY.packageName;
+    const targets = configs.length ? configs : [{ target: openCodeConfigPaths(homeDir)[0], source: '{}', entries: [] }];
+    const alreadyCanonical = entries.length === 1 && configs[0]?.entries[0]?.field === 'plugins'
+        && isDeepStrictEqual(entries[0].value, canonical);
+    const changes = alreadyCanonical ? [] : targets.map(({ target, source, entries }, index) => {
+        let next = source;
+        for (const { field, index } of entries.toReversed())
+            next = removeOpenCodeEntry(next, field, index);
+        if (index === 0)
+            next = applyEdits(next, modify(next, ['plugins', -1], canonical, {}));
+        return { target, source, next };
+    }).filter(({ source, next }) => source !== next);
+    // Appending just our element avoids native add's whole-array rewrite, which
+    // drops comments belonging to unrelated plugins. Native add still owns npm.
+    for (const { target, next } of changes) {
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, next);
+    }
+    if (!entries.some(({ spec }) => spec === SQUARE_IDENTITY.packageName)) {
+        try {
+            openCodeCommand(homeDir, ['plugin', 'add', SQUARE_IDENTITY.packageName], run, 'install');
+        }
+        catch (error) {
+            // Undo only our preparation, never files the native command/user changed.
+            for (const { target, source, next } of changes) {
+                if (fs.existsSync(target) && fs.readFileSync(target, 'utf8') === next) {
+                    if (configs.length)
+                        fs.writeFileSync(target, source);
+                    else
+                        fs.rmSync(target);
+                }
+            }
+            throw error;
+        }
+    }
+    // Even add can reuse an older cached package. Always request the latest.
+    openCodeCommand(homeDir, ['plugin', 'update', SQUARE_IDENTITY.packageName], run, 'update');
+    return [SQUARE_IDENTITY.packageName];
+}
+function openCodeCommand(homeDir, args, run, operation) {
     const result = run(homeDir, args);
     if (result.status !== 0)
-        throw new Error(`OpenCode plugin install failed: ${result.stderr.trim() || result.stdout.trim() || `exit ${result.status}`}`);
-    return [SQUARE_IDENTITY.packageName];
+        throw new Error(`OpenCode ${operation} failed: ${result.stderr.trim() || result.stdout.trim() || `exit ${result.status}`}`);
+    return result.stdout;
 }
-function configPath(homeDir) {
+function openCodeConfigPaths(homeDir) {
     const configHome = process.env.XDG_CONFIG_HOME ?? path.join(homeDir, '.config');
-    return path.join(configHome, 'opencode', 'opencode.jsonc');
+    const root = path.resolve(configHome, 'opencode');
+    return [root, path.join(root, '.opencode')].flatMap((directory) => ['opencode.json', 'opencode.jsonc'].map((name) => path.join(directory, name)));
+}
+function readOpenCodeConfigs(homeDir) {
+    return openCodeConfigPaths(homeDir).flatMap((target) => {
+        let source;
+        try {
+            source = fs.readFileSync(target, 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return [];
+            throw error;
+        }
+        const errors = [];
+        const config = parse(source, errors, { allowTrailingComma: true });
+        if (errors.length || typeof config !== 'object' || config === null || Array.isArray(config)) {
+            throw new Error(`Invalid OpenCode configuration: ${target}`);
+        }
+        const entries = ['plugin', 'plugins'].flatMap((field) => {
+            const plugins = config[field];
+            if (plugins === undefined)
+                return [];
+            if (!Array.isArray(plugins))
+                throw new Error(`Invalid OpenCode ${field} configuration: ${target}`);
+            return plugins.flatMap((entry, index) => {
+                const spec = openCodePluginSpec(entry);
+                const options = Array.isArray(entry) ? entry[1]
+                    : typeof entry === 'object' && entry !== null ? entry.options : undefined;
+                return spec === undefined ? [] : [{ field, index, spec, options, value: entry }];
+            });
+        });
+        return [{ target, source, entries }];
+    });
 }
-function removeConfiguredPlugin(homeDir) {
-    const target = configPath(homeDir);
-    let source;
+export function uninstallOpenCodePlugin(homeDir) {
+    // Native remove only handles `plugins` in one file. Delete our elements in
+    // both fields/files, from the end so indexes remain stable, keeping JSONC.
+    const changes = readOpenCodeConfigs(homeDir).filter(({ entries }) => entries.length).map(({ target, source, entries }) => {
+        for (const { field, index } of entries.reverse()) {
+            source = removeOpenCodeEntry(source, field, index);
+        }
+        return { target, source };
+    });
+    for (const { target, source } of changes)
+        fs.writeFileSync(target, source);
+    return changes.length ? [SQUARE_IDENTITY.packageName] : [];
+}
+// jsonc-parser's array `modify` also removes intervening comments. Use its AST
+// and scanner to remove only the owned value and one separator, not the trivia.
+function removeOpenCodeEntry(source, field, index) {
+    const array = findNodeAtLocation(parseTree(source), [field]);
+    const node = array.children[index];
+    const scanner = createScanner(source, true);
+    scanner.setPosition(node.offset + node.length);
+    let comma = scanner.scan() === 5 /* SyntaxKind.CommaToken */ ? scanner.getTokenOffset() : undefined;
+    if (comma === undefined && index > 0) {
+        const previous = array.children[index - 1];
+        scanner.setPosition(previous.offset + previous.length);
+        if (scanner.scan() === 5 /* SyntaxKind.CommaToken */)
+            comma = scanner.getTokenOffset();
+    }
+    return applyEdits(source, [
+        { offset: node.offset, length: node.length, content: '' },
+        ...(comma === undefined ? [] : [{ offset: comma, length: 1, content: '' }]),
+    ]);
+}
+function openCodePluginSpec(entry) {
+    const spec = typeof entry === 'string' ? entry : Array.isArray(entry) ? entry[0]
+        : typeof entry === 'object' && entry !== null && 'package' in entry ? entry.package : undefined;
+    return typeof spec === 'string' && (spec === SQUARE_IDENTITY.packageName || spec.startsWith(`${SQUARE_IDENTITY.packageName}@`))
+        ? spec : undefined;
+}
+function parseOpenCodeConfig(stdout) {
+    let sources;
     try {
-        source = fs.readFileSync(target, 'utf8');
+        sources = JSON.parse(stdout);
     }
     catch {
-        return false;
+        throw new Error('OpenCode debug config returned invalid JSON');
     }
-    const escaped = SQUARE_IDENTITY.packageName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    const packageLine = new RegExp(`^\\s*"${escaped}(?:@[^"\\n]+)?"\\s*,?\\s*$`, 'm');
-    const next = source.replace(packageLine, '');
-    if (next === source)
-        return false;
-    fs.writeFileSync(target, next);
-    return true;
-}
-export function uninstallOpenCodePlugin(homeDir) {
-    return removeConfiguredPlugin(homeDir) ? [SQUARE_IDENTITY.packageName] : [];
+    if (!Array.isArray(sources) || sources.some((source) => source === null || typeof source !== 'object'
+        || !['document', 'directory'].includes(source.type))) {
+        throw new Error('OpenCode debug config returned unexpected configuration sources');
+    }
+    return sources;
 }
-/** Verify that OpenCode accepts its resolved runtime configuration after links are installed. */
+/** Config sources prove configuration, not that a running session loaded the plugin. */
 export function verifyOpenCodeRuntime(homeDir, run = runOpenCode) {
     try {
         const result = run(homeDir, ['debug', 'config']);
@@ -134,28 +176,21 @@ export function verifyOpenCodeRuntime(homeDir, run = runOpenCode) {
             const diagnostic = result.stderr.trim() || result.stdout.trim() || `exit ${result.status}`;
             return `✕ OpenCode debug config failed: ${truncateExternalDiagnostic(diagnostic)}`;
         }
-        let config;
+        let sources;
         try {
-            config = JSON.parse(result.stdout);
+            sources = parseOpenCodeConfig(result.stdout);
         }
-        catch {
-            return '✕ OpenCode debug config returned invalid JSON';
+        catch (error) {
+            return `✕ ${error.message}`;
         }
-        const plugin = config.config?.plugin;
-        const expected = SQUARE_IDENTITY.packageName;
-        if (Array.isArray(plugin) && plugin.includes(expected))
-            return '✓ OpenCode npm plugin loaded';
-        return `○ OpenCode npm plugin not loaded: ${expected}`;
+        const configured = sources.some((source) => source.type === 'document'
+            && Array.isArray(source.info?.plugins) && source.info.plugins.some((entry) => openCodePluginSpec(entry) !== undefined));
+        return configured
+            ? '✓ OpenCode npm plugin configured (runtime loading not verified)'
+            : `○ OpenCode npm plugin not configured: ${SQUARE_IDENTITY.packageName}`;
     }
     catch (error) {
         const diagnostic = error instanceof Error ? error.message : String(error);
         return `○ OpenCode runtime unavailable (${truncateExternalDiagnostic(diagnostic)})`;
     }
 }
-export function skillLinks(homeDir = os.homedir(), parents = ['.claude', '.agents']) {
-    return parents.flatMap((parent) => ['square'].map((name) => ({
-        source: path.join(packageRoot(), 'skills', name),
-        target: path.join(homeDir, parent, 'skills', name),
-        kind: 'skill',
-    })));
-}

package/dist/harness.js

@@ -5,7 +5,7 @@ import { truncateExternalDiagnostic } from './presentation.js';
 import { doctorClaudePlugin, installClaudePlugin, uninstallClaudePlugin, } from './harness-claude.js';
 import { doctorCodexPlugin, installCodexPlugin, uninstallCodexPlugin, } from './harness-codex.js';
 import { doctorPiPackage, installPiPackage, uninstallPiPackage, } from './harness-pi.js';
-import { doctorHarnessLinks, installHarnessLinks, installOpenCodePlugin, skillLinks, uninstallOpenCodePlugin, uninstallHarnessLinks, verifyOpenCodeRuntime, } from './harness-links.js';
+import { installOpenCodePlugin, uninstallOpenCodePlugin, verifyOpenCodeRuntime, } from './harness-links.js';
 function result(lines, notes = []) {
     return { lines, notes };
 }
@@ -18,9 +18,6 @@ async function doctorHost(label, inspect) {
         return result([`○ ${label} doctor unavailable (${truncateExternalDiagnostic(diagnostic)})`]);
     }
 }
-function openCodeLinks(homeDir) {
-    return skillLinks(homeDir, ['.agents']);
-}
 function readableSquarePath(squarePath) {
     if (squarePath === undefined)
         return false;
@@ -67,15 +64,9 @@ const TARGETS = [
     {
         name: 'opencode',
         capabilities: ['install', 'uninstall', 'doctor'],
-        install: async ({ homeDir, force }) => result([
-            ...installOpenCodePlugin(homeDir, force),
-            ...installHarnessLinks(openCodeLinks(homeDir), force),
-        ]),
-        uninstall: ({ homeDir }) => result([
-            ...uninstallOpenCodePlugin(homeDir),
-            ...uninstallHarnessLinks(openCodeLinks(homeDir)),
-        ]),
-        doctor: ({ homeDir }) => result([verifyOpenCodeRuntime(homeDir), ...doctorHarnessLinks(openCodeLinks(homeDir))]),
+        install: ({ homeDir, force }) => result(installOpenCodePlugin(homeDir, force)),
+        uninstall: ({ homeDir }) => result(uninstallOpenCodePlugin(homeDir)),
+        doctor: ({ homeDir }) => result([verifyOpenCodeRuntime(homeDir)]),
     },
     {
         name: 'pi',

package/dist/mcp.js

@@ -2,6 +2,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { SQUARE_TOOLS, SQUARE_TOOL_INSTRUCTIONS, squareToolFailure, squareToolFailureText } from './square-tools.js';
 import { operationEnv } from './participant-identity.js';
+import { codexWakeAddress } from './codex-address.js';
 import { readClaudeMcpCall } from './claude-mcp-context.js';
 import { SQUARE_IDENTITY } from './identity.js';
 import { Square, createSquareResourceOwner } from './square-api.js';
@@ -46,7 +47,7 @@ export function createSquareMcpServer(options) {
                         ...options, env, body, cwd: claude?.cwd ?? options.cwd,
                         // A call-local Codex thread uses its native queue even when managed by Paseo.
                         wakeAddress: claude === undefined && typeof threadId === 'string' && threadId.trim()
-                            ? { kind: 'codex-queue', address: { threadId } } : options.wakeAddress,
+                            ? codexWakeAddress(threadId, env) : options.wakeAddress,
                         path: location ?? options.path,
                         participant: participant ?? options.participant,
                         // The server owner is bound to its configured square; overrides close after each call.

package/dist/packages/agent-delivery/src/codex-boundary.d.ts

@@ -0,0 +1,13 @@
+export interface CodexBoundary {
+    readonly lastStop: number;
+    readonly lastNonStop: number;
+    readonly ended?: true;
+}
+export interface CodexBoundaryStore {
+    read(sessionId: string): Promise<CodexBoundary | undefined>;
+    queueEligible(sessionId: string): Promise<boolean>;
+    record(sessionId: string, event: 'Stop' | 'non-stop' | 'start' | 'end', signal?: AbortSignal): Promise<void>;
+    clear(sessionId: string, signal?: AbortSignal): Promise<void>;
+}
+/** Caller-owned observation file, shared by independent hook and sender processes. */
+export declare function createCodexBoundaryStore(file: string): CodexBoundaryStore;

package/dist/packages/agent-delivery/src/codex-boundary.js

@@ -0,0 +1,75 @@
+import { promises as fs } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { withFileLock } from './file-lock.js';
+const empty = () => ({ v: 1, nextSequence: 0, threads: Object.create(null) });
+/** Caller-owned observation file, shared by independent hook and sender processes. */
+export function createCodexBoundaryStore(file) {
+    const load = async () => {
+        let raw;
+        try {
+            raw = await fs.readFile(file, 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return empty();
+            throw error;
+        }
+        try {
+            const value = JSON.parse(raw);
+            if (value?.v !== 1 || !Number.isSafeInteger(value.nextSequence) || value.nextSequence < 0 ||
+                !value.threads || typeof value.threads !== 'object')
+                return empty();
+            const result = empty();
+            result.nextSequence = value.nextSequence;
+            for (const [id, boundary] of Object.entries(value.threads)) {
+                const item = boundary;
+                if (item && Number.isSafeInteger(item.lastStop) && item.lastStop >= 0 &&
+                    Number.isSafeInteger(item.lastNonStop) && item.lastNonStop >= 0)
+                    result.threads[id] = item;
+            }
+            return result;
+        }
+        catch {
+            return empty();
+        }
+    };
+    const update = (change, signal) => withFileLock(`${file}.lock`, { retryMs: 10, signal }, async () => {
+        const state = await load();
+        change(state);
+        signal?.throwIfAborted();
+        const temporary = `${file}.${randomUUID()}.tmp`;
+        try {
+            await fs.writeFile(temporary, JSON.stringify(state), { mode: 0o600 });
+            await fs.rename(temporary, file);
+        }
+        finally {
+            await fs.unlink(temporary).catch(() => { });
+        }
+    });
+    const read = async (id) => id ? (await load()).threads[id] : undefined;
+    return {
+        read,
+        async queueEligible(id) {
+            const boundary = await read(id);
+            return boundary !== undefined && boundary.ended !== true && boundary.lastStop > boundary.lastNonStop;
+        },
+        async record(id, event, signal) {
+            if (!id)
+                return;
+            await update((state) => {
+                const previous = state.threads[id] ?? { lastStop: 0, lastNonStop: 0 };
+                // A late Stop/tool callback must not reopen an ended session.
+                if (previous.ended && event !== 'start')
+                    return;
+                state.nextSequence += 1;
+                state.threads[id] = event === 'start'
+                    ? { lastStop: 0, lastNonStop: state.nextSequence }
+                    : event === 'end' ? { ...previous, lastNonStop: state.nextSequence, ended: true }
+                        : event === 'Stop' ? { ...previous, lastStop: state.nextSequence }
+                            : { ...previous, lastNonStop: state.nextSequence };
+            }, signal);
+        },
+        async clear(id, signal) { if (id)
+            await update((state) => { delete state.threads[id]; }, signal); },
+    };
+}

package/dist/packages/agent-delivery/src/codex-cli.d.ts

@@ -0,0 +1,10 @@
+import type { CodexCliConnectOptions, CodexSendTextOptions } from './types.js';
+/** Bind once; no subprocess or lifecycle read until queue(). The receiver's
+ * hooks and this client share one lifecycle source, never a Square default. */
+export declare function connectCodexCli(options: CodexCliConnectOptions): Promise<{
+    coordinate: string;
+    send(text: string, value: CodexSendTextOptions): Promise<{
+        state: string;
+        inputId: `${string}-${string}-${string}-${string}-${string}`;
+    }>;
+}>;

package/dist/packages/agent-delivery/src/codex-cli.js

@@ -0,0 +1,69 @@
+import { randomUUID } from 'node:crypto';
+import { resolveCodexHome } from './codex-endpoint.js';
+import { sendCodexQueue, CodexQueueSendError } from './codex-queue.js';
+import { deadline, DEFAULT_TIMEOUT_MS, validSignal, validTimeout } from './deadline.js';
+import { ConnectionError, DeliveryError } from './errors.js';
+import { isIdentity, isRecord } from './guards.js';
+/** Bind once; no subprocess or lifecycle read until queue(). The receiver's
+ * hooks and this client share one lifecycle source, never a Square default. */
+export async function connectCodexCli(options) {
+    const text = (value) => isIdentity(value) && !value.includes('\0');
+    if (!isRecord(options) || options.harness !== 'codex' || options.transport !== 'cli' ||
+        !text(options.sessionId) || !isRecord(options.boundaries) || typeof options.boundaries.queueEligible !== 'function' ||
+        !validTimeout(options.timeoutMs) || !validSignal(options.signal) ||
+        (options.codexHome !== undefined && !text(options.codexHome)) ||
+        (options.endpoint !== undefined && !text(options.endpoint)) || (options.bin !== undefined && !text(options.bin)) ||
+        (options.args !== undefined && (!Array.isArray(options.args) || options.args.some((arg) => typeof arg !== 'string' || arg.includes('\0')))) ||
+        (options.env !== undefined && (!isRecord(options.env) || Object.entries(options.env).some(([key, v]) => key.includes('\0') || (v !== undefined && (typeof v !== 'string' || v.includes('\0'))))))) {
+        throw new ConnectionError('invalid_arguments');
+    }
+    if (options.signal?.aborted)
+        throw new ConnectionError('aborted');
+    const env = { ...(options.env ?? process.env) };
+    try {
+        env.CODEX_HOME = resolveCodexHome(options.codexHome === undefined ? env : { ...env, CODEX_HOME: options.codexHome });
+    }
+    catch {
+        throw new ConnectionError('invalid_arguments');
+    }
+    const sessionId = options.sessionId;
+    const eligible = options.boundaries.queueEligible.bind(options.boundaries);
+    const cli = { env, bin: options.bin, args: options.args === undefined ? undefined : [...options.args], endpoint: options.endpoint };
+    return {
+        coordinate: sessionId,
+        async send(text, value) {
+            if (typeof text !== 'string' || !text.trim() || text.includes('\0') || !isRecord(value) ||
+                value.delivery !== 'queue' || value.inputId !== undefined || !validTimeout(value.timeoutMs) || !validSignal(value.signal)) {
+                throw new TypeError('Invalid Codex queue arguments.');
+            }
+            const inputId = randomUUID(); // Local attempt correlation; the CLI does not accept a client message id.
+            const scope = deadline(value.timeoutMs, value.signal);
+            const until = Date.now() + (value.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+            let launched = false;
+            try {
+                scope.check();
+                // One check, immediately before launching the CLI. SessionEnd/late Stop
+                // suppression belongs to the bound source, not every sending caller.
+                if (!await scope.wait(eligible(sessionId)))
+                    throw new DeliveryError('session_inactive', false, inputId);
+                scope.check();
+                const remaining = until - Date.now();
+                if (remaining <= 0)
+                    throw new DeliveryError('timeout', false, inputId);
+                launched = true;
+                await sendCodexQueue({ threadId: sessionId, message: text }, { ...cli, timeoutMs: remaining, signal: scope.signal });
+                return { state: 'admitted', inputId };
+            }
+            catch (error) {
+                if (error instanceof DeliveryError)
+                    throw error;
+                if (error instanceof CodexQueueSendError)
+                    throw new DeliveryError(scope.code ?? error.code, error.maybeDelivered, inputId);
+                throw new DeliveryError(scope.code ?? (launched ? 'transport' : 'unavailable'), launched, inputId);
+            }
+            finally {
+                scope.close();
+            }
+        },
+    };
+}

package/dist/packages/agent-delivery/src/codex-endpoint.d.ts

@@ -0,0 +1,3 @@
+/** Capture the recipient's home before another process delivers. No service discovery I/O. */
+export declare function resolveCodexHome(env?: NodeJS.ProcessEnv): string;
+export declare function codexQueueEndpoint(env?: NodeJS.ProcessEnv): string;

package/dist/packages/agent-delivery/src/codex-endpoint.js

@@ -0,0 +1,14 @@
+import os from 'node:os';
+import path from 'node:path';
+/** Capture the recipient's home before another process delivers. No service discovery I/O. */
+export function resolveCodexHome(env = process.env) {
+    const userHome = env.HOME || os.homedir();
+    const raw = env.CODEX_HOME || path.join(userHome, '.codex');
+    const home = raw === '~' ? userHome : raw.startsWith('~/') ? path.join(userHome, raw.slice(2)) : raw;
+    if (!path.isAbsolute(home) || home.includes('\0'))
+        throw new TypeError('Invalid Codex home.');
+    return home;
+}
+export function codexQueueEndpoint(env = process.env) {
+    return `unix://${path.join(resolveCodexHome(env), 'app-server-control', 'app-server-control.sock')}`;
+}

package/dist/packages/agent-delivery/src/codex-hook.d.ts

@@ -0,0 +1,26 @@
+import type { CodexBoundaryStore } from './codex-boundary.js';
+export { createCodexBoundaryStore } from './codex-boundary.js';
+export type { CodexBoundary, CodexBoundaryStore } from './codex-boundary.js';
+export interface CodexHookResponse {
+    readonly hookSpecificOutput: {
+        readonly hookEventName: 'PostToolUse';
+        readonly additionalContext: string;
+    };
+}
+export interface CodexHookOptions {
+    readonly boundaries: CodexBoundaryStore;
+    /** The host owns pending text, claims and cancellation. Honor signal before presenting;
+     * if cancelled before an effect, release custody and resolve undefined or reject.
+     * After presenting, finish any cancellation-independent settlement and return its text,
+     * even if signal aborts meanwhile. This callback is awaited, never raced or abandoned. */
+    readonly pull?: (sessionId: string, signal: AbortSignal) => Promise<string | undefined>;
+    /** Dispatch the host's pending work; Stop merely makes queue eligible. */
+    readonly sweep?: (cwd: string | undefined, deadline: number, signal: AbortSignal) => Promise<void>;
+    readonly end?: (sessionId: string, signal: AbortSignal) => Promise<void>;
+    readonly trace?: (stage: string, detail?: string) => void;
+    readonly timeoutMs?: number;
+    readonly sweepTimeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+/** Stateless hook protocol. No message source, session identity or service is invented here. */
+export declare function handleCodexHook(input: unknown, options: CodexHookOptions): Promise<CodexHookResponse | undefined>;

package/dist/packages/agent-delivery/src/codex-hook.js

@@ -0,0 +1,58 @@
+import { deadline, validSignal, validTimeout } from './deadline.js';
+import { isRecord } from './guards.js';
+export { createCodexBoundaryStore } from './codex-boundary.js';
+/** Stateless hook protocol. No message source, session identity or service is invented here. */
+export async function handleCodexHook(input, options) {
+    if (!isRecord(input) || typeof input.session_id !== 'string' || !input.session_id.trim())
+        return;
+    const event = input.hook_event_name;
+    if (!['SessionStart', 'SessionResume', 'UserPromptSubmit', 'SessionEnd', 'PostToolUse', 'Stop'].includes(event))
+        return;
+    if (!validTimeout(options.timeoutMs) || !validTimeout(options.sweepTimeoutMs) || !validSignal(options.signal)) {
+        throw new TypeError('Invalid hook control.');
+    }
+    const scope = deadline(options.timeoutMs ?? 4500, options.signal);
+    const sweepDeadline = Date.now() + Math.min(options.sweepTimeoutMs ?? 3000, options.timeoutMs ?? 4500);
+    const id = input.session_id;
+    try {
+        scope.check();
+        if (event === 'SessionEnd') {
+            await scope.wait(options.boundaries.record(id, 'end', scope.signal));
+            await scope.wait(options.end?.(id, scope.signal) ?? Promise.resolve()).catch(() => { });
+            return;
+        }
+        await scope.wait(options.boundaries.record(id, event === 'SessionStart' || event === 'SessionResume' ? 'start' : event === 'Stop' ? 'Stop' : 'non-stop', scope.signal));
+        options.trace?.('boundary-record');
+        if (event !== 'Stop' && event !== 'PostToolUse')
+            return;
+        let context;
+        if (event === 'PostToolUse') {
+            try {
+                // A host's successful presentation settlement may outlive this signal. Retain
+                // its output instead of leaving background work to consume it without a response.
+                context = await options.pull?.(id, scope.signal);
+                options.trace?.('presentation');
+            }
+            catch (error) {
+                options.trace?.('presentation', `error=${error instanceof Error ? error.name : 'Error'}`);
+            }
+        }
+        if (!scope.signal.aborted && Date.now() < sweepDeadline) {
+            await scope.wait(options.sweep?.(typeof input.cwd === 'string' ? input.cwd : undefined, sweepDeadline, scope.signal) ?? Promise.resolve()).catch(() => { });
+        }
+        options.trace?.('sweep', scope.signal.aborted ? 'aborted=true' : '');
+        // A successful pull may already have committed host presentation evidence.
+        // A later, unrelated sweep timeout must not discard its completed output.
+        if (context !== undefined) {
+            return { hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: context } };
+        }
+    }
+    catch (error) {
+        if (scope.signal.aborted)
+            throw scope.signal.reason;
+        throw error;
+    }
+    finally {
+        scope.close();
+    }
+}

package/dist/packages/agent-delivery/src/codex-queue.d.ts

@@ -0,0 +1,24 @@
+export { codexQueueEndpoint } from './codex-endpoint.js';
+import type { DeliveryErrorCode } from './errors.js';
+export interface CodexQueueRequest {
+    readonly threadId: string;
+    readonly message: string;
+}
+export interface CodexQueueOptions {
+    readonly bin?: string;
+    readonly args?: readonly string[];
+    readonly env?: NodeJS.ProcessEnv;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+    readonly endpoint?: string;
+}
+export type CodexQueueFailureKind = 'transient' | 'rejected' | 'unknown';
+/** Once the child starts, a timeout or unexplained exit does not establish non-delivery. */
+export declare class CodexQueueSendError extends Error {
+    readonly kind: CodexQueueFailureKind;
+    readonly code: DeliveryErrorCode;
+    constructor(kind: CodexQueueFailureKind, code: DeliveryErrorCode);
+    get maybeDelivered(): boolean;
+}
+/** Internal CLI transport. Lifecycle checking belongs to the bound CLI client. */
+export declare function sendCodexQueue(request: CodexQueueRequest, options?: CodexQueueOptions): Promise<void>;