@deepseek-ai/dsh-subagent 0.0.1-rc.1

package/lib/types/invariant.js

@@ -0,0 +1,91 @@
+/** Package-owned subagent registry and lifecycle invariants. @module @deepseek-ai/dsh-subagent/invariant */
+const PACKAGE_NAME = '@deepseek-ai/dsh-subagent';
+/** Cordis companion plugin name. */
+export const name = 'subagent-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/** Assert that a terminal lifecycle payload matches its start identity. */
+function validateRunEnd(start, end, fail) {
+    if (start.provider !== end.provider || start.id !== end.id || start.local !== end.local) {
+        fail(`subagent/end identity diverges from subagent/start for run ${JSON.stringify(end.runId)}`);
+    }
+}
+/** Install provider-registry and start/end pairing checks. */
+const install = Object.assign((ctx, fail) => {
+    const providers = new Set(ctx.subagents.list());
+    const runs = new Map();
+    const stagedProviders = new WeakSet();
+    const stagedRemovals = new Set();
+    const stagedStarts = new WeakSet();
+    const stagedEnds = new WeakSet();
+    ctx.on('internal/dispatch', (_mode, eventName, args) => {
+        if (eventName === 'subagent/provider-added') {
+            const provider = args[0];
+            if (provider.name.length === 0)
+                fail('subagent provider names must be non-empty');
+            if (providers.has(provider.name))
+                fail(`subagent/provider-added repeated ${JSON.stringify(provider.name)}`);
+            stagedProviders.add(provider);
+            return;
+        }
+        if (eventName === 'subagent/provider-removed') {
+            const providerName = args[0];
+            if (!providers.has(providerName))
+                fail(`subagent/provider-removed names unknown provider ${JSON.stringify(providerName)}`);
+            stagedRemovals.add(providerName);
+            return;
+        }
+        if (eventName === 'subagent/start') {
+            const info = args[0];
+            // Provider availability is an admission-time relationship. A published
+            // one-shot run may outlive provider removal, and a cold-resumed Activation
+            // records the initial provider name without dispatching through it.
+            if (info.provider.length === 0 || String(info.runId).length === 0 || String(info.id).length === 0) {
+                fail('subagent/start provider, runId, and child id must be non-empty');
+            }
+            if (runs.has(info.runId))
+                fail(`subagent/start repeated run id ${JSON.stringify(info.runId)}`);
+            stagedStarts.add(info);
+            return;
+        }
+        if (eventName !== 'subagent/end')
+            return;
+        const info = args[0];
+        const start = runs.get(info.runId);
+        if (start === undefined)
+            fail(`subagent/end has no matching subagent/start for run ${JSON.stringify(info.runId)}`);
+        validateRunEnd(start, info, fail);
+        stagedEnds.add(info);
+    }, { global: true });
+    ctx.on('subagent/provider-added', (provider) => {
+        /* v8 ignore next -- internal/dispatch stages the same provider object */
+        if (!stagedProviders.delete(provider))
+            return;
+        providers.add(provider.name);
+    }, { global: true });
+    ctx.on('subagent/provider-removed', (providerName) => {
+        /* v8 ignore next -- internal/dispatch stages the same provider name */
+        if (!stagedRemovals.delete(providerName))
+            return;
+        providers.delete(providerName);
+    }, { global: true });
+    ctx.on('subagent/start', (info) => {
+        /* v8 ignore next -- internal/dispatch stages the same lifecycle object */
+        if (!stagedStarts.delete(info))
+            return;
+        runs.set(info.runId, info);
+    }, { global: true });
+    ctx.on('subagent/end', (info) => {
+        /* v8 ignore next -- internal/dispatch stages the same lifecycle object */
+        if (!stagedEnds.delete(info))
+            return;
+        runs.delete(info.runId);
+    }, { global: true });
+}, { inject: ['subagents'] });
+/**
+ * Register the subagent 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));
+//# sourceMappingURL=invariant.js.map

package/lib/types/lifecycle.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Lifecycle-edge publication for both subagent shapes: the contained emitter,
+ * the one-shot run observer, and the continuable Activation observer.
+ *
+ * The public payload contracts ({@link SubagentRunInfo},
+ * {@link SubagentRunEndInfo}) live in `./types.ts` with the rest of the seam's
+ * consumer-facing types; this module owns only the implementation and the
+ * package-private {@link ActivationObserver} the continuation manager consumes.
+ * Keeping the internal control interface out of the published surface is
+ * deliberate: the observer's `start`/`capture`/`settle` ordering is a contract
+ * between this module and one in-package caller, not something a plugin may
+ * depend on.
+ *
+ * @module @deepseek-ai/dsh-subagent/lifecycle
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+import type { SubagentRun, SubagentRunEndInfo, SubagentRunInfo } from './types.ts';
+/**
+ * Lifecycle observer for one Activation's residency epoch, so continuable
+ * children emit the same start/end pair as one-shot runs. Package-private: the
+ * continuation manager is the only consumer, and its call ordering is an
+ * in-package contract rather than a published extension point.
+ */
+export interface ActivationObserver {
+    /**
+     * Publish the start edge once the epoch is resident.
+     * @param child - the resident child agent, whose log suffix bounds this epoch.
+     */
+    start(child: Agent): void;
+    /**
+     * Snapshot the child-dependent terminal facts while the child is still
+     * registered, because handle disposal unregisters it and consumers resolve it
+     * to read the child's own log and scope.
+     * @param child - the quiescent child agent about to be released.
+     */
+    capture(child: Agent): void;
+    /**
+     * Publish the terminal edge exactly once, pairing this epoch's {@link start},
+     * after the disposal outcome is known. Called only for a resident epoch: a
+     * failure before residency publishes no edge, because inventing one would
+     * report a lifecycle the child never had.
+     * @param failure - the teardown or durability failure, or `undefined` on success.
+     */
+    settle(failure: unknown): void;
+}
+/**
+ * Publish one lifecycle edge with per-listener exception containment. Run edges
+ * carry the delegating parent that keys scoped dispatch; provider removal has no
+ * parent carrier and reaches listeners unscoped.
+ *
+ * The service owns this closure because scoped dispatch keys its carrier by the
+ * exact service instance, whose own context filter composes into the carrier;
+ * a narrowed stand-in would silently change scope filtering.
+ */
+export type LifecycleEmitter = {
+    (name: 'subagent/start', info: SubagentRunInfo, parent: Agent): void;
+    (name: 'subagent/end', info: SubagentRunEndInfo, parent: Agent): void;
+    (name: 'subagent/provider-removed', info: string): void;
+};
+/**
+ * Build the contained lifecycle emitter this seam publishes every edge through.
+ * Every listener is independently contained: a synchronous throw or a rejected
+ * returned promise is logged without starving peer listeners, changing the run,
+ * or — for provider removal, which fires from a disposer — breaking teardown.
+ * @param ctx - the service's own context, owning dispatch and the logger.
+ * @param carrier - resolve the scoped dispatch carrier for one delegating parent.
+ * @returns the emitter both observers and the provider registry publish through.
+ */
+export declare function createLifecycleEmitter(ctx: Context, carrier: (parent: Agent) => object): LifecycleEmitter;
+/**
+ * Emit the start/end lifecycle pair for one accepted one-shot run.
+ * @param emit - the contained lifecycle emitter.
+ * @param provider - the provider that established the run.
+ * @param parent - the delegating parent keying scoped dispatch.
+ * @param run - the published run whose settlement closes the pair.
+ * @returns the same run, unchanged.
+ */
+export declare function observeRun(emit: LifecycleEmitter, provider: string, parent: Agent, run: SubagentRun): SubagentRun;
+/**
+ * Build the observer for one continuable Activation's residency epoch. Observers
+ * see the same vocabulary as a one-shot run, so a child's start and settlement
+ * remain observable without exposing whether the manager materialized, woke, or
+ * cold-resumed it. Creation failure before residency emits no lifecycle edge.
+ * @param emit - the contained lifecycle emitter.
+ * @param provider - the provider name recorded in the durable descriptor.
+ * @param childId - the durable child session id.
+ * @param parent - the exact live direct parent keying scoped dispatch.
+ * @returns the observer whose edges this epoch publishes.
+ */
+export declare function createActivationObserver(emit: LifecycleEmitter, provider: string, childId: SessionId, parent: Agent): ActivationObserver;
+//# sourceMappingURL=lifecycle.d.ts.map

package/lib/types/lifecycle.js

@@ -0,0 +1,169 @@
+/**
+ * Lifecycle-edge publication for both subagent shapes: the contained emitter,
+ * the one-shot run observer, and the continuable Activation observer.
+ *
+ * The public payload contracts ({@link SubagentRunInfo},
+ * {@link SubagentRunEndInfo}) live in `./types.ts` with the rest of the seam's
+ * consumer-facing types; this module owns only the implementation and the
+ * package-private {@link ActivationObserver} the continuation manager consumes.
+ * Keeping the internal control interface out of the published surface is
+ * deliberate: the observer's `start`/`capture`/`settle` ordering is a contract
+ * between this module and one in-package caller, not something a plugin may
+ * depend on.
+ *
+ * @module @deepseek-ai/dsh-subagent/lifecycle
+ */
+import { randomUUID } from 'node:crypto';
+import { findLastMessageTurnEnd } from '@deepseek-ai/dsh-session';
+import { SubagentRunId } from "./types.js";
+/**
+ * Build the contained lifecycle emitter this seam publishes every edge through.
+ * Every listener is independently contained: a synchronous throw or a rejected
+ * returned promise is logged without starving peer listeners, changing the run,
+ * or — for provider removal, which fires from a disposer — breaking teardown.
+ * @param ctx - the service's own context, owning dispatch and the logger.
+ * @param carrier - resolve the scoped dispatch carrier for one delegating parent.
+ * @returns the emitter both observers and the provider registry publish through.
+ */
+export function createLifecycleEmitter(ctx, carrier) {
+    return (name, info, parent) => {
+        const dispatchArgs = parent === undefined
+            ? [name, info]
+            : [carrier(parent), name, info];
+        for (const callback of ctx.events.dispatch('emit', dispatchArgs)) {
+            try {
+                const returned = callback(info);
+                void Promise.resolve(returned).catch((error) => {
+                    ctx.logger.warn(`subagent: ${name} listener rejected: ${renderThrown(error)}`);
+                });
+            }
+            catch (error) {
+                ctx.logger.warn(`subagent: ${name} listener threw: ${renderThrown(error)}`);
+            }
+        }
+    };
+}
+/**
+ * Emit the start/end lifecycle pair for one accepted one-shot run.
+ * @param emit - the contained lifecycle emitter.
+ * @param provider - the provider that established the run.
+ * @param parent - the delegating parent keying scoped dispatch.
+ * @param run - the published run whose settlement closes the pair.
+ * @returns the same run, unchanged.
+ */
+export function observeRun(emit, provider, parent, run) {
+    const identity = {
+        runId: SubagentRunId(randomUUID()),
+        provider,
+        id: run.id,
+        local: run.localAgent !== undefined,
+    };
+    // Attach the terminal observer before dispatching start. Promise reactions
+    // still run after this synchronous start emission, preserving start → end.
+    void run.result.then((result) => {
+        emit('subagent/end', {
+            ...identity,
+            stopReason: result.stopReason,
+            lastAssistantMessage: result.output,
+        }, parent);
+    }, () => {
+        emit('subagent/end', { ...identity, stopReason: 'error' }, parent);
+    });
+    emit('subagent/start', identity, parent);
+    return run;
+}
+/**
+ * Build the observer for one continuable Activation's residency epoch. Observers
+ * see the same vocabulary as a one-shot run, so a child's start and settlement
+ * remain observable without exposing whether the manager materialized, woke, or
+ * cold-resumed it. Creation failure before residency emits no lifecycle edge.
+ * @param emit - the contained lifecycle emitter.
+ * @param provider - the provider name recorded in the durable descriptor.
+ * @param childId - the durable child session id.
+ * @param parent - the exact live direct parent keying scoped dispatch.
+ * @returns the observer whose edges this epoch publishes.
+ */
+export function createActivationObserver(emit, provider, childId, parent) {
+    const identity = { runId: SubagentRunId(randomUUID()), provider, id: childId, local: true };
+    // A cold resume replays earlier turns, so this epoch's telemetry must come
+    // from the suffix it actually produced — never the whole session, which
+    // would report a previous epoch's answer when this one opened no turn.
+    let boundary = 0;
+    // Assigned by `capture()`, which the disposal path always runs before
+    // `settle()`; a resident epoch therefore always has its facts by then.
+    let captured = {
+        stopReason: 'completed',
+    };
+    return {
+        start: (child) => {
+            boundary = child.session.events.length;
+            emit('subagent/start', identity, parent);
+        },
+        capture: (child) => {
+            const own = child.session.events.slice(boundary);
+            const output = lastAssistantOutput(own);
+            captured = {
+                stopReason: epochStopReason(own),
+                ...output === undefined ? {} : { output },
+            };
+        },
+        settle: (failure) => {
+            const output = failure === undefined ? captured.output : undefined;
+            emit('subagent/end', {
+                ...identity,
+                stopReason: failure === undefined ? captured.stopReason : 'error',
+                ...output === undefined ? {} : { lastAssistantMessage: output },
+            }, parent);
+        },
+    };
+}
+/**
+ * Why this child's last ordinary turn ended, for the terminal lifecycle edge.
+ * The child's own `turn/end` is authoritative: teardown succeeding says nothing
+ * about whether the model errored, hit its token ceiling, or was cancelled, so
+ * deriving the reason from disposal would report failed work as completed.
+ * @param events - this epoch's own event suffix.
+ * @returns its terminal stop reason; `completed` when no ordinary turn closed.
+ */
+function epochStopReason(events) {
+    const reason = findLastMessageTurnEnd(events)?.data.reason;
+    // No ordinary turn closed, so nothing failed either.
+    if (reason === undefined)
+        return 'completed';
+    switch (reason.kind) {
+        case 'max-tokens':
+            return 'max-tokens';
+        case 'aborted':
+        case 'interrupted':
+            return 'aborted';
+        case 'error':
+            return 'error';
+        case 'completed':
+            return 'completed';
+        /* v8 ignore next 3 -- `TurnEndReason` is merge-extensible, so this arm needs a
+         * backend that adds a variant; treating an unnameable reason as success would
+         * report failed work as completed. */
+        default:
+            return 'error';
+    }
+}
+/**
+ * The child's last assistant message content, for one Activation's terminal
+ * lifecycle edge. Absent when no assistant message reached the log.
+ * @param events - this epoch's own event suffix.
+ * @returns its final assistant content, or `undefined` when it produced none.
+ */
+function lastAssistantOutput(events) {
+    const message = events.findLast((event) => event.type === 'assistant/message');
+    return message?.data.message.content;
+}
+/** Render any listener-thrown value without letting coercion escape containment. */
+function renderThrown(value) {
+    try {
+        return value instanceof Error ? `${value.name}: ${value.message}` : String(value);
+    }
+    catch {
+        return '<unrenderable thrown value>';
+    }
+}
+//# sourceMappingURL=lifecycle.js.map

package/lib/types/list-children.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Read-only enumeration of durable subagent children and descendant trees
+ * straight from the live session store and optional session persistence — no
+ * query service. Candidates come from one live-preferred corpus; each child's
+ * mode/label is the registered `subagent` projection unit's value, resolved
+ * down a three-rung ladder: the registry's watermark cache for a live child,
+ * a durable projection-cache row when it serves an own-suffix identity (the
+ * seq gate), and one persistence inspection folded through the registry
+ * otherwise, validated against the enumerated lifecycle. The projection fold
+ * is the single classification authority — this module parses no descriptor
+ * itself. Absent persistence, enumeration is live-only: a cold child is
+ * unreachable for resume anyway, so its absence is capability absence, not an
+ * error. The module owns no catalog state and does not consult Activation,
+ * Agent-registry, continuation-manager, or provider state.
+ *
+ * @module @deepseek-ai/dsh-subagent
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+/**
+ * One entry of a {@link listChildren} result, ordered by header `createdAt`
+ * with ties broken on id. Only a candidate whose durable header has
+ * `origin: 'subagent'` is interpreted. A served `subagent` projection value
+ * produces a `child`; a settled candidate whose fold served no identity
+ * produces a `diagnostic`; a running candidate without one is omitted — its
+ * descriptor may not be appended yet (the creation window). Diagnostics
+ * relay the projection fold's outcome or a failed read, never a per-child
+ * event scan, and never expose model-hidden descriptor content.
+ */
+export type SubagentListEntry = {
+    readonly kind: 'child';
+    /** The durable child session id, stable across Activations. */
+    readonly id: SessionId;
+    /**
+     * Store snapshot activity: `running` means the logical record is live in
+     * `ctx.sessions`; `inactive` means it exists only in persistence. Neither
+     * encodes a durable outcome, and a continuable child may still reject
+     * delivery as an ownership conflict.
+     */
+    readonly activity: 'running' | 'inactive';
+    /** Whether a direct descendant has durable `origin: 'subagent'`. */
+    readonly hasChildren: boolean;
+} & ({
+    /** A terminal one-shot child. */
+    readonly mode: 'one-shot';
+    /** Optional durable creation label from the child's descriptor. */
+    readonly label?: string;
+} | {
+    /** A resumable conversation. */
+    readonly mode: 'continuable';
+    /** Durable creation label from the child's descriptor. */
+    readonly label: string;
+}) | {
+    readonly kind: 'diagnostic';
+    /** The candidate's session id. */
+    readonly id: SessionId;
+    /**
+     * Why the candidate has no `child` row: `corrupt` for a settled candidate
+     * whose projection fold served no identity (a missing, malformed, or
+     * unrecognized-version descriptor — deliberately undistinguished), and
+     * for any candidate whose log makes a registered unit's fold or schema
+     * throw (deterministic data damage, contained per child); `unavailable`
+     * when the candidate's persistence inspection failed (retried on the
+     * next listing). `unsupported` is never produced; it remains in the
+     * union for consumers that route on it.
+     */
+    readonly reason: 'corrupt' | 'unsupported' | 'unavailable';
+};
+/**
+ * One entry of a descendant listing: the interpreted subagent facts plus its
+ * position in the complete session tree. `parentId` is the durable direct
+ * parent from the enumerated header, and `depth` counts edges from the root.
+ */
+export type SubagentDescendantListEntry = SubagentListEntry & {
+    /** Durable direct parent of this candidate in the enumerated tree. */
+    readonly parentId: SessionId;
+    /** Edge distance from the requested root; direct children are `1`. */
+    readonly depth: number;
+};
+/**
+ * Enumerate one parent's origin-classified direct children from the
+ * live-preferred merge of `ctx.sessions` and optional session persistence,
+ * serving each identity from the `subagent` projection unit: the registry's
+ * watermark snapshot for a live child; for a cold one, a durable
+ * projection-cache row when it serves an own-suffix identity (the seq gate),
+ * else one bounded-concurrency persistence inspection folded through the
+ * registry.
+ * @see SubagentService.listChildren for the public cancellation and failure contract.
+ * @param ctx - context carrying the session store, the projection registry,
+ *   optional persistence, and the optional projection cache.
+ * @param parentSessionId - parent session whose direct children are listed.
+ * @param signal - caller-owned cancellation observed around every persistence read.
+ * @returns children and per-child diagnostics ordered by `createdAt`, then id.
+ * @throws {@link SubagentError} when the projection registry or the session
+ *   store is not mounted, or the caller cancels the listing.
+ */
+export declare function listChildren(ctx: Context, parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentListEntry[]>;
+/**
+ * Enumerate every session-backed subagent below one root in stable pre-order.
+ * Ordinary sessions and one-shot children remain traversal nodes, so a
+ * continuable child below either is still discovered. Classification uses the
+ * same projection-backed runtime as {@link listChildren}; no Agent is loaded or
+ * resumed.
+ * @see SubagentService.listDescendants for the public cancellation and failure contract.
+ * @param ctx - context carrying the session store, projection registry, and optional persistence/cache.
+ * @param rootSessionId - session whose complete descendant tree is listed.
+ * @param signal - caller-owned cancellation observed around every persistence read.
+ * @returns interpreted subagents with durable direct-parent and root-relative depth.
+ * @throws {@link SubagentError} under the same conditions as {@link listChildren}.
+ */
+export declare function listDescendants(ctx: Context, rootSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDescendantListEntry[]>;
+//# sourceMappingURL=list-children.d.ts.map