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

package/lib/types/agent-loader.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Agent loading and turn aggregation shared by the one-shot runner and the
+ * serve loop: both drive a direct Agent over the core registry with the same
+ * model selection, the same scoped installModelSelection setup, the same
+ * preset join, and the same caller-supplied session identity, differing only
+ * in process lifetime.
+ * @module @khorsheed/dsh-local-agent-dsh-headless/agent-loader
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { AgentHandle, ModelSelection } from '@deepseek-ai/dsh-agent';
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+/** Outcome of one owned turn interval. */
+export interface TurnOutcome {
+    text: string;
+    reason: SessionEvent<'turn/end'>['data']['reason'] | undefined;
+}
+/**
+ * Aggregate the last assistant text and turn outcome in one owned interval.
+ * @param events - the agent session's full event log.
+ * @param firstSeq - the session seq at which this driver's interval opened.
+ */
+export declare function summarizeTurn(events: readonly SessionEvent[], firstSeq: number): TurnOutcome;
+/**
+ * Apply a `--model` request onto the instance's default selection.
+ *
+ * The request is spelled `provider/model` — the same shape
+ * `effectiveSettings.model` reports the configured model in — and splits at
+ * the FIRST slash, so a provider-qualified id survives a model id that
+ * contains none. A request with no slash names the MODEL only and keeps the
+ * default selection's provider, which is what a caller switching between two
+ * models of the same route means.
+ *
+ * Everything else on the selection is carried through untouched (the
+ * reasoning effort in particular): `--model` changes the model, not the rest
+ * of the instance's configuration. An absent or blank request returns the
+ * default selection unchanged — byte for byte the behavior before the flag
+ * existed.
+ * @param selection - the instance's default model selection.
+ * @param request - the `--model` value, when the launch carried one.
+ * @returns the selection this launch runs.
+ */
+export declare function applyModelRequest(selection: ModelSelection, request: string | undefined): ModelSelection;
+/**
+ * Join this agent to the sub-profile's preset, when the sub-profile composes
+ * a roster.
+ *
+ * Without a roster this is a no-op and the agent reads the model-facing rows
+ * off the global layer — byte for byte the behavior of every sub-dsh before
+ * the roster layer existed, and the right answer for a rosterless
+ * composition (`@deepseek-ai/dsh-agent-presets` README, "Composing a child
+ * agent"). With one, the preset decides the tools, prompt sections and
+ * skills of every session this process hosts, which is what makes the
+ * scope's capability face a per-condition factor instead of an instance-wide
+ * constant.
+ *
+ * A roster that REFUSES (unknown preset id, broken composition) is not
+ * degraded past: mounting rejects, the agent creation rolls back, and the
+ * launch fails naming the preset. A sub-dsh that silently ran the global
+ * layer after being told to run preset X would attribute the round to a
+ * capability face it never had.
+ * @param ctx - plugin context (where the roster service is resolved).
+ * @param agentCtx - the agent's scope context, which joins the standing mount.
+ * @returns the preset id joined, or undefined when the composition has no roster.
+ */
+export declare function joinSubDshPreset(ctx: Context, agentCtx: Context): Promise<string | undefined>;
+/**
+ * Create or resume the direct Agent for one caller-named session. The caller
+ * resolved the core services first (both call sites bail out on a disposed
+ * tree). The caller-supplied id is authoritative for both branches: the
+ * parent provider generated one uuid and passes the same value on every round
+ * of the same delegation, so resume finds exactly the sub-dsh session the
+ * fresh round created.
+ * @param ctx - plugin context carrying the Agent registry and default model.
+ * @param identity - fresh (`sessionId`) or continuation (`resumeSessionId`).
+ * @returns the owned agent handle (its disposer unwinds the agent's world).
+ */
+export declare function loadSubDshAgent(ctx: Context, identity: {
+    sessionId?: string;
+    resumeSessionId?: string;
+    model?: string;
+    effort?: string;
+}): Promise<AgentHandle>;
+/** Validate the actual sub-instance's configuration without creating a session or generating. */
+export declare function resolveSubDshSelection(ctx: Context, model?: string, effort?: string, validateModel?: boolean): Promise<ModelSelection>;
+//# sourceMappingURL=agent-loader.d.ts.map

package/lib/types/agent-loader.js

@@ -0,0 +1,173 @@
+/**
+ * Agent loading and turn aggregation shared by the one-shot runner and the
+ * serve loop: both drive a direct Agent over the core registry with the same
+ * model selection, the same scoped installModelSelection setup, the same
+ * preset join, and the same caller-supplied session identity, differing only
+ * in process lifetime.
+ * @module @khorsheed/dsh-local-agent-dsh-headless/agent-loader
+ */
+import { randomUUID } from 'node:crypto';
+import { installModelSelection } from '@deepseek-ai/dsh-agent';
+import { SessionId } from '@deepseek-ai/dsh-session';
+/**
+ * Aggregate the last assistant text and turn outcome in one owned interval.
+ * @param events - the agent session's full event log.
+ * @param firstSeq - the session seq at which this driver's interval opened.
+ */
+export function summarizeTurn(events, firstSeq) {
+    let started = false;
+    let text = '';
+    let reason;
+    for (const event of events) {
+        if (event.seq < firstSeq)
+            continue;
+        if (event.type === 'turn/start') {
+            started = true;
+            continue;
+        }
+        if (!started)
+            continue;
+        if (event.type === 'assistant/message') {
+            const joined = event.data.message.content
+                .filter(block => block.type === 'text')
+                .map(block => block.text)
+                .join('');
+            if (joined !== '')
+                text = joined;
+        }
+        if (event.type === 'turn/end')
+            reason = event.data.reason;
+    }
+    return { text, reason };
+}
+/**
+ * Apply a `--model` request onto the instance's default selection.
+ *
+ * The request is spelled `provider/model` — the same shape
+ * `effectiveSettings.model` reports the configured model in — and splits at
+ * the FIRST slash, so a provider-qualified id survives a model id that
+ * contains none. A request with no slash names the MODEL only and keeps the
+ * default selection's provider, which is what a caller switching between two
+ * models of the same route means.
+ *
+ * Everything else on the selection is carried through untouched (the
+ * reasoning effort in particular): `--model` changes the model, not the rest
+ * of the instance's configuration. An absent or blank request returns the
+ * default selection unchanged — byte for byte the behavior before the flag
+ * existed.
+ * @param selection - the instance's default model selection.
+ * @param request - the `--model` value, when the launch carried one.
+ * @returns the selection this launch runs.
+ */
+export function applyModelRequest(selection, request) {
+    const wanted = request?.trim();
+    if (wanted === undefined || wanted === '')
+        return selection;
+    const slash = wanted.indexOf('/');
+    if (slash <= 0 || slash === wanted.length - 1)
+        return { ...selection, model: wanted };
+    return { ...selection, provider: wanted.slice(0, slash), model: wanted.slice(slash + 1) };
+}
+/**
+ * Join this agent to the sub-profile's preset, when the sub-profile composes
+ * a roster.
+ *
+ * Without a roster this is a no-op and the agent reads the model-facing rows
+ * off the global layer — byte for byte the behavior of every sub-dsh before
+ * the roster layer existed, and the right answer for a rosterless
+ * composition (`@deepseek-ai/dsh-agent-presets` README, "Composing a child
+ * agent"). With one, the preset decides the tools, prompt sections and
+ * skills of every session this process hosts, which is what makes the
+ * scope's capability face a per-condition factor instead of an instance-wide
+ * constant.
+ *
+ * A roster that REFUSES (unknown preset id, broken composition) is not
+ * degraded past: mounting rejects, the agent creation rolls back, and the
+ * launch fails naming the preset. A sub-dsh that silently ran the global
+ * layer after being told to run preset X would attribute the round to a
+ * capability face it never had.
+ * @param ctx - plugin context (where the roster service is resolved).
+ * @param agentCtx - the agent's scope context, which joins the standing mount.
+ * @returns the preset id joined, or undefined when the composition has no roster.
+ */
+export async function joinSubDshPreset(ctx, agentCtx) {
+    const roster = ctx.get('agentPresets');
+    if (roster?.mount === undefined)
+        return undefined;
+    return (await roster.mount(agentCtx)).id;
+}
+/**
+ * Create or resume the direct Agent for one caller-named session. The caller
+ * resolved the core services first (both call sites bail out on a disposed
+ * tree). The caller-supplied id is authoritative for both branches: the
+ * parent provider generated one uuid and passes the same value on every round
+ * of the same delegation, so resume finds exactly the sub-dsh session the
+ * fresh round created.
+ * @param ctx - plugin context carrying the Agent registry and default model.
+ * @param identity - fresh (`sessionId`) or continuation (`resumeSessionId`).
+ * @returns the owned agent handle (its disposer unwinds the agent's world).
+ */
+export async function loadSubDshAgent(ctx, identity) {
+    const agents = ctx.get('agents');
+    if (agents === undefined)
+        throw new Error('local-agent-dsh-headless: the agents service is not mounted');
+    const selection = await resolveSubDshSelection(ctx, identity.model, identity.effort);
+    // This bundle composes no preset roster, so the model-facing rows sit in the
+    // host plane and the agent reads them from the global layer. A deployment
+    // that DOES configure one has to join it here first
+    // (@deepseek-ai/dsh-agent-presets README, "Composing a child agent").
+    const agentOptions = { provider: selection.provider, model: selection.model };
+    const setup = async (agentCtx) => {
+        const selected = { current: selection, assembled: undefined };
+        // The released installModelSelection registers the two scoped waterfall
+        // listeners and returns their disposer; the run owns the whole process
+        // lifetime, so the disposer is deliberately dropped.
+        installModelSelection(agentCtx, selected);
+        // The preset join happens INSIDE setup, before the agent is published:
+        // the roster parents this agent's scope key to the preset's standing
+        // mount, so the preset's tools and prompt sections exist before the first
+        // prompt assembly. A rejection here rolls the creation back.
+        await joinSubDshPreset(ctx, agentCtx);
+    };
+    if (identity.resumeSessionId !== undefined) {
+        return agents.resume({
+            resumeSessionId: SessionId(identity.resumeSessionId),
+            agentOptions,
+            setup,
+        });
+    }
+    return agents.create({
+        sessionId: SessionId(identity.sessionId ?? `session-${randomUUID()}`),
+        meta: { cwd: process.cwd() },
+        agentOptions,
+        setup,
+    });
+}
+/** Validate the actual sub-instance's configuration without creating a session or generating. */
+export async function resolveSubDshSelection(ctx, model, effort, validateModel = false) {
+    const defaults = ctx.get('agentDefaultModel');
+    if (defaults === undefined)
+        throw new Error('local-agent-dsh-headless: agentDefaultModel is not mounted');
+    const selection = applyModelRequest(defaults.currentSelection(), model);
+    if (effort === undefined && !validateModel)
+        return selection;
+    let timer;
+    try {
+        const info = await Promise.race([
+            ctx.get('llm')?.resolveModelInfo(selection.provider, selection.model, AbortSignal.timeout(5_000)),
+            new Promise((_resolve, reject) => { timer = setTimeout(() => reject(new Error('Sub-DSH model validation timed out')), 5_000); timer.unref(); }),
+        ]);
+        if (info === undefined)
+            throw new Error('The sub-DSH adapter cannot resolve the requested model');
+        if (effort === undefined)
+            return selection;
+        const native = info.reasoning?.efforts.find(option => String(option.id) === effort);
+        if (native === undefined)
+            throw new Error('The sub-DSH model does not advertise the requested reasoning effort');
+        return { ...selection, reasoningEffort: native.id };
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}

package/lib/types/index.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @khorsheed/dsh-local-agent-dsh-headless — sub-dsh direct Agent driver with
+ * two modes. One-shot (default): create one Agent through the core registry
+ * on a caller-supplied session id (or resume one), drive the task to
+ * quiescence, flush its Session, print the final assistant text, and exit.
+ * Serve (`--serve`): stay resident and drive turns over the family-internal
+ * live-driver wire (see `./serve.ts` / `./wire.ts`). The session id comes
+ * from the invocation (`--session-id` / `--resume`) or the wire, never from
+ * stdout — the parent provider generates one uuid and both sides use it, so
+ * stdout carries no parseable session marker.
+ *
+ * @module @khorsheed/dsh-local-agent-dsh-headless
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+/** Stable Cordis plugin name. */
+export declare const name = "local-agent-dsh-headless-runner";
+/** Core services required before the one-shot turn can start. */
+export declare const inject: string[];
+/** Plugin config: the one-shot task and caller session identity, or serve mode. */
+export interface Config {
+    /** The prompt text for the single run; unused in serve mode. */
+    task?: string;
+    /** Fresh delegation: create a session with exactly this id. */
+    sessionId?: string;
+    /** Continuation: resume the existing session with this id. */
+    resumeSessionId?: string;
+    /** Resident mode: drive turns over the stdio wire instead of one task. */
+    serve?: boolean;
+    /**
+     * The model this launch runs (`--model`), spelled `provider/model`; a bare
+     * id names the model and keeps the instance's provider. Absent means the
+     * instance's default selection, unchanged. Under `serve` it binds every
+     * session the resident process hosts.
+     */
+    model?: string;
+    effort?: string;
+}
+export declare const Config: z<Config>;
+/** Process-facing effects of one run: output streams plus the launcher's bounded exit request. */
+interface HeadlessIo {
+    stdin: {
+        on(event: 'data', listener: (chunk: unknown) => void): unknown;
+        on(event: 'end', listener: () => void): unknown;
+    };
+    stdout: {
+        write(chunk: string): unknown;
+    };
+    stderr: {
+        write(chunk: string): unknown;
+    };
+    /** Request process exit with `code` after the tree disposes. */
+    exit(code: number): void;
+}
+/** The process streams the runner writes to; tests substitute captures. */
+export declare const internals: {
+    stdin: HeadlessIo['stdin'];
+    stdout: HeadlessIo['stdout'];
+    stderr: HeadlessIo['stderr'];
+};
+/**
+ * Mount the direct driver: one-shot by default, the resident serve loop when
+ * the invocation passed `--serve`.
+ * @param ctx - plugin context carrying core services and the launcher-provided exit request.
+ * @param config - validated task/serve config.
+ */
+export declare function apply(ctx: Context, config: Config): void;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -0,0 +1,99 @@
+/**
+ * @khorsheed/dsh-local-agent-dsh-headless — sub-dsh direct Agent driver with
+ * two modes. One-shot (default): create one Agent through the core registry
+ * on a caller-supplied session id (or resume one), drive the task to
+ * quiescence, flush its Session, print the final assistant text, and exit.
+ * Serve (`--serve`): stay resident and drive turns over the family-internal
+ * live-driver wire (see `./serve.ts` / `./wire.ts`). The session id comes
+ * from the invocation (`--session-id` / `--resume`) or the wire, never from
+ * stdout — the parent provider generates one uuid and both sides use it, so
+ * stdout carries no parseable session marker.
+ *
+ * @module @khorsheed/dsh-local-agent-dsh-headless
+ */
+import z from '@deepseek-ai/schemastery';
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { loadSubDshAgent, summarizeTurn } from './agent-loader.js';
+import { runServe } from './serve.js';
+/** Stable Cordis plugin name. */
+export const name = 'local-agent-dsh-headless-runner';
+/** Core services required before the one-shot turn can start. */
+export const inject = ['agentDefaultModel', 'agents', 'sessions'];
+export const Config = z.object({
+    task: z.string(),
+    sessionId: z.string(),
+    resumeSessionId: z.string(),
+    serve: z.boolean().default(false),
+    model: z.string(),
+    effort: z.string(),
+});
+/** The process streams the runner writes to; tests substitute captures. */
+export const internals = {
+    stdin: process.stdin,
+    stdout: process.stdout,
+    stderr: process.stderr,
+};
+/** Report an unexpected direct-driver failure and request a failing exit. */
+function fail(io, error) {
+    io.stderr.write(`dsh: ${error instanceof Error ? error.message : String(error)}\n`);
+    io.exit(1);
+}
+/**
+ * Run one task through a fresh or resumed Agent and request process exit.
+ * @param ctx - plugin context carrying the Agent, default model, Session, and launcher IO services.
+ * @param config - validated one-shot config (task plus the caller session id).
+ * @param io - process-facing effects.
+ */
+async function run(ctx, config, io) {
+    // Loader siblings mount concurrently. Await the complete application before
+    // creating an Agent so its scoped tools and adapters are not half-composed.
+    await ctx.get('loader')?.await();
+    const sessions = ctx.get('sessions');
+    // Early process shutdown can dispose the tree while settlement is pending.
+    if (ctx.get('agents') === undefined || ctx.get('agentDefaultModel') === undefined || sessions === undefined)
+        return;
+    const handle = await loadSubDshAgent(ctx, {
+        ...config.sessionId === undefined ? {} : { sessionId: config.sessionId },
+        ...config.resumeSessionId === undefined ? {} : { resumeSessionId: config.resumeSessionId },
+        ...config.model === undefined ? {} : { model: config.model },
+        ...config.effort === undefined ? {} : { effort: config.effort },
+    });
+    const agent = handle.agent;
+    await agent.whenIdle();
+    const firstSeq = agent.session.seq;
+    agent.followup(createUserMessage({
+        content: [{ type: 'text', text: config.task ?? '' }],
+        source: { kind: 'user' },
+    }));
+    await agent.whenIdle();
+    await sessions.flush(agent.session);
+    const outcome = summarizeTurn(agent.session.snapshotEvents(), firstSeq);
+    io.stdout.write(outcome.text + '\n');
+    if (outcome.reason?.kind === 'error') {
+        io.stderr.write(`dsh: ${outcome.reason.error.code}: ${outcome.reason.error.message}\n`);
+    }
+    io.exit(outcome.reason?.kind === 'completed' ? 0 : 1);
+}
+/**
+ * Mount the direct driver: one-shot by default, the resident serve loop when
+ * the invocation passed `--serve`.
+ * @param ctx - plugin context carrying core services and the launcher-provided exit request.
+ * @param config - validated task/serve config.
+ */
+export function apply(ctx, config) {
+    // Read through the global service store, not the property proxy: appExit is
+    // an optional host value, never an injected dependency.
+    const exit = ctx.get('appExit');
+    if (exit === undefined) {
+        throw new Error('local-agent-dsh-headless-runner: the launcher must provide ctx.appExit before the tree mounts');
+    }
+    const io = { stdin: internals.stdin, stdout: internals.stdout, stderr: internals.stderr, exit };
+    if (config.serve === true) {
+        void runServe(ctx, io, config.model, config.effort).catch((error) => { fail(io, error); });
+        return;
+    }
+    if (config.task === undefined || config.task.trim() === '') {
+        throw new Error('local-agent-dsh-headless-runner: a task is required unless serve mode is on');
+    }
+    void run(ctx, config, io).catch((error) => { fail(io, error); });
+}

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@khorsheed/dsh-local-agent-dsh-headless`.
+ * @module @khorsheed/dsh-local-agent-dsh-headless/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "local-agent-dsh-headless-invariant";
+/** Service required before the companion can register. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/invariant.js

@@ -0,0 +1,41 @@
+/**
+ * Package-owned invariant companion for `@khorsheed/dsh-local-agent-dsh-headless`.
+ * @module @khorsheed/dsh-local-agent-dsh-headless/invariant
+ */
+const PACKAGE_NAME = '@khorsheed/dsh-local-agent-dsh-headless';
+/** Cordis companion plugin name. */
+export const name = 'local-agent-dsh-headless-invariant';
+/** Service required before the companion can register. */
+export const inject = ['invariants'];
+/**
+ * Composition guard: this bundle is sub-profile-only. Its patch rows
+ * (persona override, `hmr` off, `tools` mode, the `ptc-runtime` insert, the
+ * member-bridge MCP row) collide with or leak into any Host/web composition —
+ * 2026-08-23 P0: reconciled into the prod web profile as a direct dependency
+ * (reconcilePlugins auto-mounts every `dsh.bundle`-declaring direct dep), the
+ * `code-runtime` insert (today's `ptc-runtime` row) hit the web-app row's duplicate entry id and the
+ * whole instance failed to boot. The loader's duplicate-id failure is loud
+ * but cryptic, and only fires when the ids collide; this invariant is the
+ * CLEAR failure for the non-colliding case (e.g. an upstream row rename would
+ * otherwise leak the persona override into real user sessions). The web
+ * layer's `webStartup` service is the marker: in-box bundles mount before
+ * dependency-managed ones, so it is already provided when this companion
+ * applies.
+ */
+const install = (ctx, fail) => {
+    // Duck-typed global-store read: the web marker is not a dependency of this
+    // package, so no typed Context merge exists for it.
+    const probe = ctx;
+    if (probe.get('webStartup') !== undefined) {
+        fail('mounted into a web composition — this bundle is sub-profile-only. '
+            + 'Remove it from the profile’s direct dependencies: the parent '
+            + 'local-agent-dsh bundle installs it transitively, and the '
+            + 'sub-profile symlink resolves from that closure');
+    }
+};
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));

package/lib/types/serve.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 type { Context } from '@deepseek-ai/cordis';
+/**
+ * The process streams serve mode reads and writes; tests substitute captures.
+ * `stdin` is the minimal readable surface (`data`/`end`), `exit` is the
+ * launcher-provided bounded exit request.
+ */
+export interface ServeIo {
+    readonly stdin: {
+        on(event: 'data', listener: (chunk: unknown) => void): unknown;
+        on(event: 'end', listener: () => void): unknown;
+    };
+    readonly stdout: {
+        write(chunk: string): unknown;
+    };
+    readonly stderr: {
+        write(chunk: string): unknown;
+    };
+    readonly exit: (code: number) => void;
+}
+/**
+ * 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 declare function runServe(ctx: Context, io: ServeIo, model?: string, effort?: string): Promise<void>;
+//# sourceMappingURL=serve.d.ts.map