@khorsheed/dsh-local-agent-dsh-headless 0.1.0-rc.6

package/lib/types/serve.js

@@ -0,0 +1,249 @@
+/**
+ * Serve mode: the resident sub-dsh loop behind the family-internal live-driver
+ * wire (see `./wire.ts`). Where the one-shot runner drives a single task and
+ * exits, serve mode keeps the tree alive on stdin: each `turn/start` request
+ * feeds one followup into the caller-named session's Agent, every session
+ * event streams back as a `session/event` notification while it happens, and
+ * `session/idle` closes the turn after the log flush. `turn/interrupt`
+ * delivers the runtime-level graceful cancel (`Agent.cancel`) that the
+ * process boundary cannot express — the process survives and the session
+ * stays continuable, which is the live driver's reason to exist.
+ * @module @khorsheed/dsh-local-agent-dsh-headless/serve
+ */
+import { StringDecoder } from 'node:string_decoder';
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { resolveSubDshSelection, loadSubDshAgent, summarizeTurn } from './agent-loader.js';
+import { LIVE_SERVER_NAME, LIVE_WIRE_ERROR_INTERNAL, LIVE_WIRE_ERROR_METHOD_NOT_FOUND, LIVE_WIRE_PROTOCOL_VERSION, } from './wire.js';
+/** Flatten an unknown thrown value for a wire error or stderr line. */
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Run the resident loop until stdin closes or a `shutdown` request arrives.
+ * @param ctx - plugin context carrying the loader settle, core services, and
+ *   the session/event feed.
+ * @param io - process-facing effects.
+ */
+export async function runServe(ctx, io, model, effort) {
+    // Loader siblings mount concurrently; await the complete application before
+    // driving Agents so scoped tools and adapters are not half-composed.
+    await ctx.get('loader')?.await();
+    const agents = ctx.get('agents');
+    const sessions = ctx.get('sessions');
+    if (agents === undefined || sessions === undefined || ctx.get('agentDefaultModel') === undefined) {
+        io.stderr.write('dsh: serve mode requires the agents, sessions, and agentDefaultModel services\n');
+        io.exit(1);
+        return;
+    }
+    /** Loaded agents by caller session id; one member per process in practice. */
+    const managed = new Map();
+    /** Per-session turn serialization: one in-flight turn per session, FIFO. */
+    const queues = new Map();
+    /**
+     * The in-flight round's parent-supplied turn number per session, set while
+     * a turn body runs and echoed on its notifications — the parent drops a
+     * cancelled round's late unwind instead of mis-settling the next round.
+     */
+    const activeTurns = new Map();
+    let shuttingDown = false;
+    let buffer = '';
+    const decoder = new StringDecoder('utf8');
+    const send = (message) => {
+        io.stdout.write(JSON.stringify(message) + '\n');
+    };
+    const respond = (id, result) => {
+        send({ jsonrpc: '2.0', id, result });
+    };
+    const respondError = (id, message, code = LIVE_WIRE_ERROR_INTERNAL) => {
+        send({ jsonrpc: '2.0', id, error: { code, message } });
+    };
+    const notify = (method, params) => {
+        send({ jsonrpc: '2.0', method, params });
+    };
+    // Push every session event of a managed session the moment it lands; the
+    // parent mirrors event-by-event instead of polling the log file. Events
+    // outside a round (agent maintenance, load-time scaffolding) carry a null
+    // turn tag and the parent ignores them.
+    ctx.on('session/event', (session, event) => {
+        if (shuttingDown || !managed.has(String(session.id)))
+            return;
+        const id = String(session.id);
+        notify('session/event', {
+            sessionId: id,
+            turn: activeTurns.get(id) ?? null,
+            event: event,
+        });
+    });
+    // This process owns real Agents, so the public scoped stream bus is valid
+    // here. The parent presents these frames through the plugin's own channel.
+    ctx.on('agent/assistant-stream', ({ agent, frame }) => {
+        const sessionId = String(agent.session.id);
+        const turn = activeTurns.get(sessionId);
+        if (shuttingDown || !managed.has(sessionId) || turn === undefined)
+            return;
+        notify('session/assistant-stream', { sessionId, turn, frame });
+    }, { global: true });
+    const debug = process.env['DSH_SERVE_DEBUG'] === '1'
+        ? (message) => { io.stderr.write(`dsh-serve: ${message}\n`); }
+        : () => { };
+    const shutdown = async () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        debug('shutdown requested');
+        for (const handle of managed.values()) {
+            await handle.dispose().catch(() => { });
+        }
+        debug('managed agents disposed; requesting exit');
+        io.exit(0);
+        // The launcher's bounded shutdown completes with `process.exitCode`, which
+        // only takes effect once the event loop drains — our flowing stdin pipe
+        // would hold it open forever (a one-shot never listens on stdin, so only
+        // serve mode hits this). Detach our stdin handle and arm a bounded
+        // self-exit fallback for anything else still holding the loop.
+        const stdin = io.stdin;
+        stdin.removeAllListeners?.('data');
+        stdin.removeAllListeners?.('end');
+        stdin.unref?.();
+        setTimeout(() => {
+            debug('exit fallback fired');
+            process.exit(0);
+        }, 2_000).unref();
+    };
+    /** Accept one turn: followup now, outcome later as `session/idle`. */
+    const startTurn = (sessionId, text, turn, agent) => {
+        const previous = queues.get(sessionId) ?? Promise.resolve();
+        const run = previous.then(async () => {
+            activeTurns.set(sessionId, turn);
+            let reason;
+            try {
+                const firstSeq = agent.session.seq;
+                agent.followup(createUserMessage({
+                    content: [{ type: 'text', text }],
+                    source: { kind: 'user' },
+                }));
+                await agent.whenIdle();
+                // Flush BEFORE the idle notification so the parent's file-based
+                // reconciliation pass sees the complete round on disk.
+                await sessions.flush(agent.session);
+                reason = summarizeTurn(agent.session.snapshotEvents(), firstSeq).reason ?? null;
+            }
+            catch (error) {
+                // A turn-level failure must still close the parent's wait.
+                reason = { kind: 'error', error: { message: messageOf(error), code: 'UNKNOWN' } };
+            }
+            const params = { sessionId, turn, reason };
+            try {
+                notify('session/idle', params);
+            }
+            finally {
+                activeTurns.delete(sessionId);
+            }
+        });
+        queues.set(sessionId, run);
+    };
+    const handleRequest = async (id, method, params) => {
+        switch (method) {
+            case 'initialize':
+                respond(id, { serverInfo: { name: LIVE_SERVER_NAME }, protocolVersion: LIVE_WIRE_PROTOCOL_VERSION });
+                return;
+            case 'session/prepare': {
+                try {
+                    await resolveSubDshSelection(ctx, model, effort, true);
+                    respond(id, { prepared: true });
+                }
+                catch (error) {
+                    respondError(id, messageOf(error));
+                }
+                return;
+            }
+            case 'turn/start': {
+                const sessionId = params['sessionId'];
+                const text = params['text'];
+                const turn = params['turn'];
+                const resume = params['resume'] === true;
+                if (typeof sessionId !== 'string' || sessionId === '' || typeof text !== 'string'
+                    || typeof turn !== 'number' || !Number.isSafeInteger(turn) || turn < 1) {
+                    respondError(id, 'turn/start requires a sessionId, a text, and a positive integer turn');
+                    return;
+                }
+                let handle = managed.get(sessionId);
+                if (handle === undefined) {
+                    try {
+                        // The launch's `--model` binds every session this resident
+                        // process hosts: a runtime's model is a process fact, which is
+                        // exactly why the parent refuses a per-delegation model on the
+                        // live path.
+                        handle = await loadSubDshAgent(ctx, {
+                            ...resume ? { resumeSessionId: sessionId } : { sessionId },
+                            ...model === undefined ? {} : { model },
+                            ...effort === undefined ? {} : { effort },
+                        });
+                    }
+                    catch (error) {
+                        respondError(id, messageOf(error));
+                        return;
+                    }
+                    managed.set(sessionId, handle);
+                }
+                startTurn(sessionId, text, turn, handle.agent);
+                respond(id, { accepted: true });
+                return;
+            }
+            case 'turn/interrupt': {
+                const sessionId = params['sessionId'];
+                if (typeof sessionId !== 'string') {
+                    respondError(id, 'turn/interrupt requires a sessionId');
+                    return;
+                }
+                const handle = managed.get(sessionId);
+                // The official Agent cancel: the active turn aborts, un-started inbox
+                // work survives, and the process/session stay continuable.
+                handle?.agent.cancel({ kind: 'parent' });
+                respond(id, { interrupted: handle !== undefined });
+                return;
+            }
+            case 'shutdown':
+                respond(id, {});
+                void shutdown();
+                return;
+            default:
+                respondError(id, `unknown method: ${method}`, LIVE_WIRE_ERROR_METHOD_NOT_FOUND);
+        }
+    };
+    io.stdin.on('data', (chunk) => {
+        if (shuttingDown)
+            return;
+        // A multi-byte UTF-8 sequence can straddle two chunks; the StringDecoder
+        // holds the partial tail instead of corrupting it into U+FFFD.
+        const text = typeof chunk === 'string'
+            ? chunk
+            : decoder.write(chunk);
+        buffer += text;
+        let index = buffer.indexOf('\n');
+        while (index >= 0) {
+            const line = buffer.slice(0, index);
+            buffer = buffer.slice(index + 1);
+            index = buffer.indexOf('\n');
+            if (line.trim() === '')
+                continue;
+            let message;
+            try {
+                message = JSON.parse(line);
+            }
+            catch {
+                io.stderr.write('dsh: serve ignored a malformed wire line\n');
+                continue;
+            }
+            // Only requests carry an id; the parent sends no notifications.
+            if ((typeof message.id === 'number' || typeof message.id === 'string') && typeof message.method === 'string') {
+                const id = Number(message.id);
+                void handleRequest(id, message.method, (message.params ?? {})).catch((error) => {
+                    respondError(id, messageOf(error));
+                });
+            }
+        }
+    });
+    // The parent closing the pipe IS the shutdown request (reclaim path).
+    io.stdin.on('end', () => { void shutdown(); });
+}

package/lib/types/startup.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The sub-dsh one-shot app's command-line provider: it parses the task
+ * positional, the caller-supplied `--session-id` (fresh delegation) and
+ * `--resume` (continuation) flags, and `--help`, then publishes
+ * {@link LOCAL_AGENT_DSH_HEADLESS_STARTUP_SERVICE}. The runner is an ordinary
+ * consumer whose lazy config waits for that service. The session id is
+ * caller-supplied — the parent provider generates one uuid and passes the same
+ * value to `agents.create`/`agents.resume` on the sub-dsh side, so stdout
+ * never carries a parseable session marker.
+ * @module @khorsheed/dsh-local-agent-dsh-headless/startup
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Stable Cordis plugin name. */
+export declare const name = "local-agent-dsh-headless-startup";
+/** Services required before the invocation can be resolved. */
+export declare const inject: string[];
+/** Service provided by this plugin and injected by the one-shot runner. */
+export declare const LOCAL_AGENT_DSH_HEADLESS_STARTUP_SERVICE = "localAgentDshHeadlessStartup";
+/** What the runner row reads from {@link LOCAL_AGENT_DSH_HEADLESS_STARTUP_SERVICE}. */
+export interface LocalAgentDshHeadlessStartupValues {
+    /** The task text this invocation asked for; empty in serve mode. */
+    task: string;
+    /** Fresh delegation: create a session with this exact id. */
+    sessionId?: string;
+    /** Continuation: resume the existing session with this id. */
+    resumeSessionId?: string;
+    /** Resident mode: drive turns over the stdio wire, never exiting on idle. */
+    serve?: boolean;
+    /**
+     * The model this launch runs, spelled `provider/model` (a bare id names the
+     * model and keeps the instance's provider). Absent means the instance's own
+     * default model selection, unchanged. Under `--serve` it applies to every
+     * session the resident process hosts — a resident runtime binds its model
+     * at spawn, which is why the parent refuses a per-delegation model there.
+     */
+    model?: string;
+    effort?: string;
+}
+/**
+ * Parse and provide the one-shot invocation as an ordinary Cordis service.
+ * The command's action publishes the invocation; a missing or whitespace-only
+ * task, or both session flags together, is a usage error, so on rejection (and
+ * on `--help`) nothing is provided.
+ * @param ctx - plugin context carrying the command line.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=startup.d.ts.map

package/lib/types/startup.js

@@ -0,0 +1,96 @@
+/**
+ * The sub-dsh one-shot app's command-line provider: it parses the task
+ * positional, the caller-supplied `--session-id` (fresh delegation) and
+ * `--resume` (continuation) flags, and `--help`, then publishes
+ * {@link LOCAL_AGENT_DSH_HEADLESS_STARTUP_SERVICE}. The runner is an ordinary
+ * consumer whose lazy config waits for that service. The session id is
+ * caller-supplied — the parent provider generates one uuid and passes the same
+ * value to `agents.create`/`agents.resume` on the sub-dsh side, so stdout
+ * never carries a parseable session marker.
+ * @module @khorsheed/dsh-local-agent-dsh-headless/startup
+ */
+import { Command } from 'commander';
+import { parseCmdline } from '@deepseek-ai/dsh-cmdline';
+/** Stable Cordis plugin name. */
+export const name = 'local-agent-dsh-headless-startup';
+/** Services required before the invocation can be resolved. */
+export const inject = ['cmdlineArgs'];
+/** Service provided by this plugin and injected by the one-shot runner. */
+export const LOCAL_AGENT_DSH_HEADLESS_STARTUP_SERVICE = 'localAgentDshHeadlessStartup';
+/**
+ * This app's command: the session flags, the task positional, and help text.
+ * @returns a fresh program, so one process can parse more than once (tests).
+ */
+function headlessCommand() {
+    return new Command()
+        .name('dsh --profile headless-local-agent-dsh')
+        .description('Answer one task in a caller-named session, print the final assistant message, and exit.')
+        .helpOption('-h, --help', 'show this help')
+        .option('--session-id <id>', 'create a fresh session with exactly this id')
+        .option('--resume <id>', 'continue the existing session with this id')
+        .option('--serve', 'stay resident and drive turns over the stdio wire (no task)')
+        .option('--model <provider/model>', 'run this model instead of the instance default (a bare id keeps the provider)')
+        .option('--effort <value>', 'native reasoning effort for this launch')
+        .argument('[task...]', 'the task text; multiple words are joined by spaces')
+        .addHelpText('after', `
+Examples:
+  dsh --profile headless-local-agent-dsh --session-id 6ba7... "run the tests"   create one session and answer
+  dsh --profile headless-local-agent-dsh --resume 6ba7... "run the rest"       continue the same session
+  dsh --profile headless-local-agent-dsh --serve                              resident live-driver mode (stdio wire)
+  dsh --profile headless-local-agent-dsh --model deepseek-official/deepseek-v4-pro --session-id 6ba7... "run the tests"
+`);
+}
+/**
+ * Parse and provide the one-shot invocation as an ordinary Cordis service.
+ * The command's action publishes the invocation; a missing or whitespace-only
+ * task, or both session flags together, is a usage error, so on rejection (and
+ * on `--help`) nothing is provided.
+ * @param ctx - plugin context carrying the command line.
+ */
+export function apply(ctx) {
+    const program = headlessCommand();
+    program.action(() => {
+        const task = program.args.join(' ');
+        // Commander camelizes `--session-id` to `sessionId` but keeps `--resume`
+        // as `resume`; map both onto the service's explicit field names.
+        const options = program.opts();
+        // `--model` is orthogonal to the session flags: it names WHICH model runs,
+        // not which session, so it rides both modes.
+        const effort = options.effort?.trim();
+        if (effort === '')
+            program.error('error: --effort needs a native reasoning value');
+        const model = options.model?.trim();
+        if (model !== undefined && model === '') {
+            program.error('error: --model needs a model identifier, for example deepseek-official/deepseek-v4-pro');
+        }
+        if (options.serve === true) {
+            if (options.sessionId !== undefined || options.resume !== undefined) {
+                program.error('error: --serve drives sessions over the wire; --session-id/--resume do not apply');
+            }
+            if (task.trim() !== '') {
+                program.error('error: --serve takes no task; turns arrive over the wire');
+            }
+            ctx.provide(LOCAL_AGENT_DSH_HEADLESS_STARTUP_SERVICE, {
+                task: '',
+                serve: true,
+                ...(model === undefined ? {} : { model }),
+                ...(effort === undefined ? {} : { effort }),
+            });
+            return;
+        }
+        if (task.trim() === '') {
+            program.error('error: a task is required, for example: dsh --profile headless-local-agent-dsh --session-id <id> "run the tests"');
+        }
+        if (options.sessionId !== undefined && options.resume !== undefined) {
+            program.error('error: --session-id and --resume are mutually exclusive');
+        }
+        ctx.provide(LOCAL_AGENT_DSH_HEADLESS_STARTUP_SERVICE, {
+            task,
+            ...(options.sessionId !== undefined ? { sessionId: options.sessionId } : {}),
+            ...(options.resume !== undefined ? { resumeSessionId: options.resume } : {}),
+            ...(model === undefined ? {} : { model }),
+            ...(effort === undefined ? {} : { effort }),
+        });
+    });
+    parseCmdline(ctx, program);
+}

package/lib/types/wire.d.ts

@@ -0,0 +1,116 @@
+/**
+ * The family-internal live-driver wire between the `local-agent-dsh` provider
+ * (parent side) and this bundle's serve mode (the resident sub-dsh). Newline-
+ * delimited JSON-RPC 2.0 over the sub-dsh's stdio, framed exactly like the
+ * official `JsonRpcLineTransport` (`@deepseek-ai/dsh-sdk-protocol`) so a
+ * future swap to the official SDK server stays mechanical. The official
+ * server is NOT usable today: its wire has no turn-level interrupt
+ * (`initialize` / `session/prompt` / `shutdown` only), and graceful interrupt
+ * is the live driver's core win — serve mode drives the in-process
+ * `Agent.cancel` instead (upstream seam registry, SDK-wire-interrupt entry).
+ *
+ * One resident process serves one member (one session). All requests are
+ * quick acknowledgements; the turn's events and terminal outcome flow back as
+ * notifications, never as the request response, so a long turn never holds a
+ * request open.
+ * @module @khorsheed/dsh-local-agent-dsh-headless/wire
+ */
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+import type { AssistantStreamFrame } from '@deepseek-ai/dsh-agent';
+/** Additive transient notification; old clients safely ignore unknown methods. */
+export interface LiveAssistantStreamParams {
+    readonly sessionId: string;
+    readonly turn: number;
+    readonly frame: AssistantStreamFrame;
+}
+/** Wire contract version; bumped on any incompatible shape change. */
+export declare const LIVE_WIRE_PROTOCOL_VERSION = 1;
+/** The serve mode's identity, reported by the `initialize` handshake. */
+export declare const LIVE_SERVER_NAME = "@khorsheed/dsh-local-agent-dsh-headless/serve";
+/** A wire request (parent → sub-dsh). */
+export interface LiveWireRequest {
+    readonly jsonrpc: '2.0';
+    readonly id: number;
+    readonly method: string;
+    readonly params?: Record<string, unknown>;
+}
+/** A wire response (sub-dsh → parent): exactly one of result/error. */
+export interface LiveWireResponse {
+    readonly jsonrpc: '2.0';
+    readonly id: number;
+    readonly result?: unknown;
+    readonly error?: {
+        readonly code: number;
+        readonly message: string;
+    };
+}
+/** A wire notification (sub-dsh → parent). */
+export interface LiveWireNotification {
+    readonly jsonrpc: '2.0';
+    readonly method: string;
+    readonly params?: Record<string, unknown>;
+}
+/** `initialize` result: the handshake proving the channel speaks this wire. */
+export interface LiveInitializeResult {
+    readonly serverInfo: {
+        readonly name: string;
+    };
+    readonly protocolVersion: number;
+}
+/** `turn/start` params: drive one turn of the named session. */
+export interface LiveTurnStartParams {
+    /** Caller-supplied session id (the parent-side child session id). */
+    readonly sessionId: string;
+    /** The turn's prompt text (the family's text-only task contract). */
+    readonly text: string;
+    /** True on a resume round: load the existing session, never create it. */
+    readonly resume: boolean;
+    /**
+     * The parent's delegation-round number (fresh = 1, each resume +1). The
+     * serve side echoes it on every `session/event` / `session/idle` of this
+     * turn, so the parent can drop a cancelled round's late unwind
+     * notifications instead of letting them mis-settle the next round.
+     */
+    readonly turn: number;
+}
+/** `turn/start` result: the turn was accepted; its outcome arrives as `session/idle`. */
+export interface LiveTurnStartResult {
+    readonly accepted: true;
+}
+/** `turn/interrupt` params: gracefully cancel the named session's active turn. */
+export interface LiveTurnInterruptParams {
+    readonly sessionId: string;
+}
+/** `turn/interrupt` result: whether the session is loaded in this runtime. */
+export interface LiveTurnInterruptResult {
+    readonly interrupted: boolean;
+}
+/** The sub-dsh turn's terminal reason, mirrored from its `turn/end` event. */
+export type LiveTurnReason = SessionEvent<'turn/end'>['data']['reason'];
+/** `session/event` notification params: one live session event, in order. */
+export interface LiveSessionEventParams {
+    readonly sessionId: string;
+    /**
+     * The round this event belongs to (the echo of `turn/start`'s `turn`), or
+     * null when the event landed outside any round — the parent mirrors only
+     * its own round's events.
+     */
+    readonly turn: number | null;
+    readonly event: SessionEvent;
+}
+/**
+ * `session/idle` notification params: the session's active turn settled and
+ * its session log was flushed to disk, so a file-based reconciliation pass
+ * right after this notification sees the complete round.
+ */
+export interface LiveSessionIdleParams {
+    readonly sessionId: string;
+    /** The round this idle closes (the echo of `turn/start`'s `turn`). */
+    readonly turn: number;
+    /** Null when the owned interval recorded no turn (a broken turn). */
+    readonly reason: LiveTurnReason | null;
+}
+/** JSON-RPC error codes this wire uses. */
+export declare const LIVE_WIRE_ERROR_METHOD_NOT_FOUND = -32601;
+export declare const LIVE_WIRE_ERROR_INTERNAL = -32603;
+//# sourceMappingURL=wire.d.ts.map

package/lib/types/wire.js

@@ -0,0 +1,24 @@
+/**
+ * The family-internal live-driver wire between the `local-agent-dsh` provider
+ * (parent side) and this bundle's serve mode (the resident sub-dsh). Newline-
+ * delimited JSON-RPC 2.0 over the sub-dsh's stdio, framed exactly like the
+ * official `JsonRpcLineTransport` (`@deepseek-ai/dsh-sdk-protocol`) so a
+ * future swap to the official SDK server stays mechanical. The official
+ * server is NOT usable today: its wire has no turn-level interrupt
+ * (`initialize` / `session/prompt` / `shutdown` only), and graceful interrupt
+ * is the live driver's core win — serve mode drives the in-process
+ * `Agent.cancel` instead (upstream seam registry, SDK-wire-interrupt entry).
+ *
+ * One resident process serves one member (one session). All requests are
+ * quick acknowledgements; the turn's events and terminal outcome flow back as
+ * notifications, never as the request response, so a long turn never holds a
+ * request open.
+ * @module @khorsheed/dsh-local-agent-dsh-headless/wire
+ */
+/** Wire contract version; bumped on any incompatible shape change. */
+export const LIVE_WIRE_PROTOCOL_VERSION = 1;
+/** The serve mode's identity, reported by the `initialize` handshake. */
+export const LIVE_SERVER_NAME = '@khorsheed/dsh-local-agent-dsh-headless/serve';
+/** JSON-RPC error codes this wire uses. */
+export const LIVE_WIRE_ERROR_METHOD_NOT_FOUND = -32601;
+export const LIVE_WIRE_ERROR_INTERNAL = -32603;

package/lib/wire.js

@@ -0,0 +1,27 @@
+//#region lib/types/wire.js
+/**
+* The family-internal live-driver wire between the `local-agent-dsh` provider
+* (parent side) and this bundle's serve mode (the resident sub-dsh). Newline-
+* delimited JSON-RPC 2.0 over the sub-dsh's stdio, framed exactly like the
+* official `JsonRpcLineTransport` (`@deepseek-ai/dsh-sdk-protocol`) so a
+* future swap to the official SDK server stays mechanical. The official
+* server is NOT usable today: its wire has no turn-level interrupt
+* (`initialize` / `session/prompt` / `shutdown` only), and graceful interrupt
+* is the live driver's core win — serve mode drives the in-process
+* `Agent.cancel` instead (upstream seam registry, SDK-wire-interrupt entry).
+*
+* One resident process serves one member (one session). All requests are
+* quick acknowledgements; the turn's events and terminal outcome flow back as
+* notifications, never as the request response, so a long turn never holds a
+* request open.
+* @module @khorsheed/dsh-local-agent-dsh-headless/wire
+*/
+/** Wire contract version; bumped on any incompatible shape change. */
+const LIVE_WIRE_PROTOCOL_VERSION = 1;
+/** The serve mode's identity, reported by the `initialize` handshake. */
+const LIVE_SERVER_NAME = "@khorsheed/dsh-local-agent-dsh-headless/serve";
+/** JSON-RPC error codes this wire uses. */
+const LIVE_WIRE_ERROR_METHOD_NOT_FOUND = -32601;
+const LIVE_WIRE_ERROR_INTERNAL = -32603;
+//#endregion
+export { LIVE_SERVER_NAME, LIVE_WIRE_ERROR_INTERNAL, LIVE_WIRE_ERROR_METHOD_NOT_FOUND, LIVE_WIRE_PROTOCOL_VERSION };

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@khorsheed/dsh-local-agent-dsh-headless",
+  "description": "Sub-dsh headless bundle for the local-agent-dsh harness: a direct Agent/Session runner over dsh-base — one-shot (caller-supplied --session-id/--resume, prints the final assistant text, exits) or resident (--serve) driving turns over the family stdio wire",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "cordis",
+    "local-agent",
+    "headless"
+  ],
+  "version": "0.1.0-rc.6",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./startup": {
+      "types": "./lib/types/startup.d.ts",
+      "default": "./lib/startup.js"
+    },
+    "./wire": {
+      "types": "./lib/types/wire.d.ts",
+      "default": "./lib/wire.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "composition": {
+      "component": "sub-profile-patch"
+    },
+    "compat": {
+      "minHost": "0.1.5-rc.1",
+      "verifiedHost": "0.1.5-rc.1"
+    }
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.2",
+    "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-agent-default-model": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-mcp-client": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.6"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-mcp-client": {
+      "optional": true
+    }
+  }
+}