@shuind/dsh-codex-harness 0.1.7

package/lib/installer.js

@@ -0,0 +1,59 @@
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, renameSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+//#region lib/types/installer.js
+/** Install the user-visible Codex agent preset supplied by this bundle. */
+const PRESET_ID = "codex";
+const PRESET_FILES = ["agent.cordis.yml", "preset.yml"];
+const SOURCE_PRESET_DIR = fileURLToPath(new URL("../presets/codex/", import.meta.url));
+function dshHomePath(...segments) {
+	const configured = process.env.DSH_HOME?.trim();
+	const expanded = configured === void 0 || configured.length === 0 ? join(homedir(), ".dsh") : configured === "~" ? homedir() : configured.startsWith("~/") || configured.startsWith("~\\") ? join(homedir(), configured.slice(2)) : configured;
+	return join(resolve(expanded), ...segments);
+}
+/** Bundle plugin name for the preset installer. */
+const name = "codex-preset-installer";
+/**
+* Install the shipped Codex preset only when the user has not authored one.
+*
+* The directory is committed with a staging rename so a failed copy cannot
+* leave a half-written preset that hides the mode from the roster. Existing
+* directories are intentionally preserved, including user customizations.
+*
+* @param targetDir - destination preset directory.
+* @param sourceDir - directory containing the packaged preset files.
+*/
+function installCodexPreset(targetDir = dshHomePath(".agent-presets", PRESET_ID), sourceDir = SOURCE_PRESET_DIR) {
+	if (existsSync(targetDir)) return;
+	const parentDir = dirname(targetDir);
+	mkdirSync(parentDir, { recursive: true });
+	const stagingDir = mkdtempSync(join(parentDir, `.${PRESET_ID}-`));
+	try {
+		for (const file of PRESET_FILES) copyFileSync(join(sourceDir, file), join(stagingDir, file));
+		try {
+			renameSync(stagingDir, targetDir);
+		} catch (error) {
+			if (!existsSync(targetDir)) throw error;
+		}
+	} finally {
+		if (existsSync(stagingDir)) rmSync(stagingDir, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+/** Install the preset during profile boot without changing the host tool catalog. */
+function apply(ctx) {
+	try {
+		installCodexPreset();
+	} catch (error) {
+		ctx.logger.warn(`dsh-codex: could not install the Codex preset: ${String(error)}`);
+	}
+}
+var installer_default = {
+	name,
+	apply
+};
+//#endregion
+export { apply, installer_default as default, installCodexPreset, name };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@shuind/dsh-codex-harness`.
+* @module @shuind/dsh-codex-harness/invariant
+*/
+const PACKAGE_NAME = "@shuind/dsh-codex-harness";
+/** Codex companion plugin name. */
+const name = "codex-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* Codex has no independent lifecycle stream: its model-visible state is owned
+* by the tool registry and session projection services it consumes.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/exec.d.ts

@@ -0,0 +1,43 @@
+/** Codex `exec_command` and `write_stdin` execution over dsh capability seams. */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ToolExecution } from '@deepseek-ai/dsh-tools';
+/** The exact model-facing argument vocabulary of Codex's unified exec tool. */
+export interface ExecCommandArgs {
+    cmd: string;
+    workdir?: string;
+    tty?: boolean;
+    yield_time_ms?: number;
+    max_output_tokens?: number;
+    shell?: string;
+    login?: boolean;
+}
+/** The exact model-facing argument vocabulary of Codex's stdin poll tool. */
+export interface WriteStdinArgs {
+    session_id: number;
+    chars?: string;
+    yield_time_ms?: number;
+    max_output_tokens?: number;
+}
+/** Canonical result fields shared by both unified exec tools. */
+export interface ExecResult {
+    chunk_id?: string;
+    wall_time_seconds: number;
+    output: string;
+    session_id?: number;
+    exit_code?: number;
+    original_token_count?: number;
+}
+/** Render the ordinary Responses tool result text used by Codex's unified exec tools. */
+export declare function renderExecResult(result: ExecResult): string;
+/** Execute one Codex command through the configured pipe or PTY capability. */
+export declare function runExecCommand(ctx: Context, args: ExecCommandArgs, exec: ToolExecution, config: {
+    defaultYieldTimeMs: number;
+    maxOutputBytes: number;
+}): Promise<ExecResult>;
+/** Poll or write to one session returned by {@link runExecCommand}. */
+export declare function runWriteStdin(ctx: Context, args: WriteStdinArgs, exec: ToolExecution, config: {
+    pollYieldTimeMs: number;
+    writeYieldTimeMs: number;
+    maxOutputBytes: number;
+}): Promise<ExecResult>;
+//# sourceMappingURL=exec.d.ts.map

package/lib/types/exec.js

@@ -0,0 +1,251 @@
+/** Codex `exec_command` and `write_stdin` execution over dsh capability seams. */
+import { randomBytes } from 'node:crypto';
+import { resolve as resolvePath } from 'node:path';
+const STATES = new WeakMap();
+function stateFor(agent) {
+    const current = STATES.get(agent);
+    if (current !== undefined)
+        return current;
+    const created = { nextId: 0, sessions: new Map() };
+    STATES.set(agent, created);
+    return created;
+}
+function positiveFinite(name, value) {
+    if (value !== undefined && (!Number.isFinite(value) || value < 0)) {
+        throw new Error(`${name} must be a non-negative finite number`);
+    }
+}
+function waitMs(value, fallback) {
+    return Math.max(0, Math.min(30_000, Math.trunc(value ?? fallback)));
+}
+function outputLimit(maxOutputBytes, maxOutputTokens) {
+    if (maxOutputTokens === undefined)
+        return maxOutputBytes;
+    positiveFinite('max_output_tokens', maxOutputTokens);
+    return Math.max(1, Math.min(maxOutputBytes, Math.trunc(maxOutputTokens * 4)));
+}
+function limitOutput(text, maxBytes) {
+    if (Buffer.byteLength(text, 'utf8') <= maxBytes)
+        return text;
+    let end = Math.min(text.length, maxBytes);
+    while (end > 0 && Buffer.byteLength(text.slice(0, end), 'utf8') > maxBytes)
+        end--;
+    return `${text.slice(0, end)}\n[output truncated]`;
+}
+function newChunkId() {
+    return randomBytes(3).toString('hex');
+}
+function withChunkId(result) {
+    return { chunk_id: newChunkId(), ...result };
+}
+/** Render the ordinary Responses tool result text used by Codex's unified exec tools. */
+export function renderExecResult(result) {
+    const sections = [];
+    if (result.chunk_id !== undefined)
+        sections.push(`Chunk ID: ${result.chunk_id}`);
+    sections.push(`Wall time: ${result.wall_time_seconds.toFixed(4)} seconds`);
+    if (result.exit_code !== undefined)
+        sections.push(`Process exited with code ${result.exit_code}`);
+    if (result.session_id !== undefined)
+        sections.push(`Process running with session ID ${result.session_id}`);
+    if (result.original_token_count !== undefined)
+        sections.push(`Original token count: ${result.original_token_count}`);
+    sections.push('Output:', result.output);
+    return sections.join('\n');
+}
+function sessionCwd(exec, workdir) {
+    const base = exec.agent?.session.header.cwd ?? process.cwd();
+    if (workdir === undefined)
+        return exec.agent?.session.header.cwd;
+    return resolvePath(base, workdir);
+}
+function readShellOutput(read, maxBytes) {
+    return limitOutput(read.delta, maxBytes);
+}
+function terminalResult(result, maxBytes, startedAt) {
+    const output = limitOutput(result.viewport, maxBytes);
+    return withChunkId({
+        wall_time_seconds: (performance.now() - startedAt) / 1000,
+        output,
+        ...result.sessionStatus.kind === 'exited' ? {
+            ...result.sessionStatus.exitCode === null ? {} : { exit_code: result.sessionStatus.exitCode },
+        } : {},
+    });
+}
+function sleep(ms, signal) {
+    return new Promise(resolve => {
+        let timer;
+        const finish = (result) => {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            signal.removeEventListener('abort', onAbort);
+            resolve(result);
+        };
+        const onAbort = () => finish('aborted');
+        if (signal.aborted) {
+            finish('aborted');
+            return;
+        }
+        signal.addEventListener('abort', onAbort, { once: true });
+        timer = setTimeout(() => finish('elapsed'), ms);
+    });
+}
+async function waitForShell(process, ms, signal) {
+    const timer = sleep(ms, signal);
+    const completed = await Promise.race([
+        process.done.then(() => true),
+        timer.then(result => result === 'aborted' ? false : undefined),
+    ]);
+    if (signal.aborted)
+        signal.throwIfAborted();
+    return completed === true || process.status !== 'running';
+}
+function allocateSession(agent, session) {
+    const state = stateFor(agent);
+    const id = ++state.nextId;
+    state.sessions.set(id, session);
+    return id;
+}
+function storedSession(agent, id) {
+    const session = stateFor(agent).sessions.get(id);
+    if (session === undefined)
+        throw new Error(`unknown unified exec session ${id}`);
+    return session;
+}
+function forgetSession(agent, id) {
+    stateFor(agent).sessions.delete(id);
+}
+function commandFor(args) {
+    // The selected dsh shell provider owns the actual executable and login
+    // defaults. These fields remain accepted so Codex's argument contract is
+    // stable; dsh's shell capability is the deployment extension point.
+    return args.cmd;
+}
+/** Execute one Codex command through the configured pipe or PTY capability. */
+export async function runExecCommand(ctx, args, exec, config) {
+    if (args.cmd.trim().length === 0)
+        throw new Error('cmd must be a non-empty string');
+    positiveFinite('yield_time_ms', args.yield_time_ms);
+    const maxBytes = outputLimit(config.maxOutputBytes, args.max_output_tokens);
+    const workdir = sessionCwd(exec, args.workdir);
+    const startedAt = performance.now();
+    if (args.tty === true) {
+        const agent = exec.agent;
+        const terminals = ctx.get('terminals');
+        if (agent === undefined || terminals === undefined) {
+            throw new Error('exec_command with tty=true requires the dsh terminal capability and an owning agent session');
+        }
+        const spawnRequest = {
+            type: 'shell',
+            ...args.shell === undefined ? {} : { shell: args.shell },
+            login: args.login ?? true,
+            ...workdir === undefined ? {} : { cwd: workdir },
+        };
+        const spawned = await terminals.spawn(agent, spawnRequest, exec.signal);
+        const sendRequest = {
+            text: commandFor(args),
+            submit: true,
+            waitMs: waitMs(args.yield_time_ms, config.defaultYieldTimeMs),
+            signal: exec.signal,
+        };
+        const operation = terminals.startSend(agent, spawned.sessionId, sendRequest);
+        const result = await operation.done;
+        const output = terminalResult(result, maxBytes, startedAt);
+        if (result.sessionStatus.kind === 'running') {
+            output.session_id = allocateSession(agent, { kind: 'terminal', owner: agent, id: spawned.sessionId });
+        }
+        else {
+            await terminals.kill(agent, spawned.sessionId, 'Codex command exited');
+        }
+        return output;
+    }
+    const policy = ctx.get('sandboxPolicy')?.resolve(exec.agent === undefined ? {} : { session: exec.agent.session });
+    const dshEnv = ctx.get('shellEnv')?.collect(exec);
+    const shellRequest = {
+        command: commandFor(args),
+        ...args.shell === undefined ? {} : { shell: args.shell },
+        login: args.login ?? true,
+        ...workdir === undefined ? {} : { workdir },
+        stdoutMaxBytes: maxBytes,
+        ...dshEnv === undefined ? {} : { dshEnv },
+        ...policy === undefined ? {} : { sandboxPolicy: policy },
+    };
+    const process = ctx.shell.start(ctx.shell.resolve(shellRequest));
+    const completed = await waitForShell(process, waitMs(args.yield_time_ms, config.defaultYieldTimeMs), exec.signal);
+    const output = readShellOutput(process.readOutput(), maxBytes);
+    if (!completed || process.status === 'running') {
+        if (exec.agent === undefined) {
+            process.kill();
+            await process.done;
+            return withChunkId({
+                wall_time_seconds: (performance.now() - startedAt) / 1000,
+                output: readShellOutput(process.readOutput(), maxBytes),
+            });
+        }
+        return withChunkId({
+            wall_time_seconds: (performance.now() - startedAt) / 1000,
+            output,
+            session_id: allocateSession(exec.agent, { kind: 'shell', process }),
+        });
+    }
+    return withChunkId({
+        wall_time_seconds: (performance.now() - startedAt) / 1000,
+        output,
+        ...process.exitCode === null ? {} : { exit_code: process.exitCode },
+    });
+}
+/** Poll or write to one session returned by {@link runExecCommand}. */
+export async function runWriteStdin(ctx, args, exec, config) {
+    positiveFinite('yield_time_ms', args.yield_time_ms);
+    if (!Number.isSafeInteger(args.session_id) || args.session_id <= 0) {
+        throw new Error('session_id must be a positive integer');
+    }
+    const agent = exec.agent;
+    if (agent === undefined)
+        throw new Error('write_stdin requires an owning agent session');
+    const session = storedSession(agent, args.session_id);
+    const maxBytes = outputLimit(config.maxOutputBytes, args.max_output_tokens);
+    const startedAt = performance.now();
+    const chars = args.chars ?? '';
+    if (session.kind === 'shell') {
+        if (chars.length > 0) {
+            throw new Error('this unified exec session uses pipes and does not accept stdin; rerun exec_command with tty=true');
+        }
+        const completed = await waitForShell(session.process, waitMs(args.yield_time_ms, config.pollYieldTimeMs), exec.signal);
+        const output = readShellOutput(session.process.readOutput(), maxBytes);
+        if (completed && session.process.status !== 'running') {
+            forgetSession(agent, args.session_id);
+            return withChunkId({
+                wall_time_seconds: (performance.now() - startedAt) / 1000,
+                output,
+                ...session.process.exitCode === null ? {} : { exit_code: session.process.exitCode },
+            });
+        }
+        return withChunkId({
+            wall_time_seconds: (performance.now() - startedAt) / 1000,
+            output,
+            session_id: args.session_id,
+        });
+    }
+    const terminals = ctx.get('terminals');
+    if (terminals === undefined)
+        throw new Error('the dsh terminal capability is no longer available');
+    const sendRequest = {
+        text: chars,
+        submit: false,
+        waitMs: waitMs(args.yield_time_ms, chars.length > 0 ? config.writeYieldTimeMs : config.pollYieldTimeMs),
+        signal: exec.signal,
+    };
+    const operation = terminals.startSend(agent, session.id, sendRequest);
+    const result = await operation.done;
+    const output = terminalResult(result, maxBytes, startedAt);
+    if (result.sessionStatus.kind === 'running') {
+        output.session_id = args.session_id;
+    }
+    else {
+        forgetSession(agent, args.session_id);
+        await terminals.kill(agent, session.id, 'Codex command exited');
+    }
+    return output;
+}
+//# sourceMappingURL=exec.js.map

package/lib/types/index.d.ts

@@ -0,0 +1,28 @@
+/** Codex-compatible prompt overlay and core tools for a dsh agent preset. */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export declare const name = "codex";
+export declare const inject: string[];
+/** Configuration for the Codex shell result bridge. */
+export interface Config {
+    /** Default wait before a pipe-backed command yields a session id. */
+    defaultYieldTimeMs?: number;
+    /** Default wait for an empty `write_stdin` poll. */
+    pollYieldTimeMs?: number;
+    /** Default wait for a non-empty `write_stdin` send. */
+    writeYieldTimeMs?: number;
+    /** Maximum output retained in one canonical result, in UTF-8 bytes. */
+    maxOutputBytes?: number;
+}
+/** Runtime configuration schema for the Codex tool bridge. */
+export declare const Config: z<Config>;
+/** Mount the Codex prompt/tool layer inside one fixed agent preset. */
+export declare function apply(ctx: Context, config?: Config): void;
+declare const _default: {
+    name: string;
+    inject: string[];
+    Config: z<Config>;
+    apply: typeof apply;
+};
+export default _default;
+//# sourceMappingURL=index.d.ts.map