@qlzt/dsh-subagent 0.0.0-stage → 0.2.1-alpha.3

package/lib/types/out-of-process.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Provider-side vocabulary for OUT-OF-PROCESS subagent backends — the pieces
+ * that enforce this seam's own contracts around a child in another process:
+ * the no-capabilities advertisement, timing-bound validation, child
+ * working-directory validation, the never-reject result settlement, and the standard
+ * run-handle publication. Backends compose these with their own wire drivers;
+ * the process machinery itself (spawn, env scrub, managed-range teardown)
+ * belongs to the `dsh-subprocess` seam.
+ *
+ * @module @qlzt/dsh-subagent/out-of-process
+ */
+import type { ContentBlock } from '@qlzt/dsh-llm';
+import type { SubagentCapabilities, SubagentResult, SubagentRun, SubagentStopReason } from './types.ts';
+/**
+ * The capability advertisement of an out-of-process backend: NONE. A child in
+ * another process cannot honor parent-enforced start features
+ * (`agentOptions`/`outputSchema`/`maxDepth`/`toolFilter`/`persona`), so the service rejects a
+ * request needing any of them before `start` runs — never accepted-then-ignored.
+ */
+export declare const NO_START_CAPABILITIES: SubagentCapabilities;
+/**
+ * Assert a configured timing bound is a positive finite number (it bounds a
+ * teardown or shutdown wait; zero, negative, or NaN would skip or wedge it).
+ * @param prefix - the consuming plugin's diagnostic prefix (e.g. `subagent-acp`).
+ * @param name - the config field name, for the diagnostic.
+ * @param value - the configured value.
+ */
+export declare function assertPositiveFinite(prefix: string, name: string, value: number): void;
+/**
+ * Assert `cwd` can actually host the child: absolute (it doubles as the
+ * child's workspace identity, and a relative path would be re-anchored to the
+ * server process's launch directory) and an existing directory (fail here,
+ * before the process boundary, instead of as an ambiguous spawn ENOENT).
+ * @param prefix - the consuming plugin's diagnostic prefix.
+ * @param label - which source supplied the value, for the diagnostic.
+ * @param cwd - the candidate working directory.
+ * @returns `cwd`, validated.
+ */
+export declare function assertUsableCwd(prefix: string, label: string, cwd: string): string;
+/** Inputs to {@link settleRunResult}. */
+export interface RunResultSettlement {
+    /** The turn attempt (typically racing local cancellation); returns the terminal result. */
+    attempt: () => Promise<SubagentResult>;
+    /** Snapshot the provider exposes when cancellation or failure wins settlement. */
+    collectOutput: () => readonly ContentBlock[];
+    /** Snapshot safe provider-authored detail when a failure wins settlement. */
+    collectDiagnostic?: (() => string | undefined) | undefined;
+    /** Whether local cancellation settled before the attempt's outcome is observed. */
+    cancelled: () => boolean;
+    /** Diagnostic sink for a failure flattened to a stop reason; a throw from it is contained. */
+    onError?: ((error: Error, stopReason: SubagentStopReason) => void) | undefined;
+    /** The request's cancellation signal (the listener is removed at settlement). */
+    signal: AbortSignal;
+    /** The abort listener registered on {@link signal} at start. */
+    onAbort: () => void;
+}
+/**
+ * Settle an out-of-process run result under the seam contract: `result` never
+ * rejects after publication. A normally completed or rejected attempt resolves
+ * as `aborted` when cancellation already settled locally; another rejection is
+ * flattened to `stopReason: 'error'` through the contained diagnostic sink.
+ * Provider-returned diagnostics use the same byte limit. The abort listener is
+ * removed on every path.
+ * @param parts - the attempt, output snapshot, cancellation state, sink, and signal wiring.
+ * @returns the terminal result (never a rejection).
+ */
+export declare function settleRunResult(parts: RunResultSettlement): Promise<SubagentResult>;
+/** Inputs to {@link subprocessRunHandle}. */
+export interface SubprocessRunHandleParts {
+    /** The parent-scoped run id. */
+    id: SubagentRun['id'];
+    /** The flattened, never-rejecting result (the seam contract). */
+    result: Promise<SubagentResult>;
+    /** The request's cancellation signal (the listener is removed on dispose). */
+    signal: AbortSignal;
+    /** The abort listener registered on {@link signal} at start. */
+    onAbort: () => void;
+    /** Settle local cancellation so {@link result} resolves without the child. */
+    requestCancel: () => void;
+    /** Tear the child process down to quiescence (backend-owned ladder). */
+    teardown: () => Promise<void>;
+}
+/**
+ * Publish the seam run handle for an out-of-process child. `dispose()` is
+ * idempotent (one memoized teardown): it removes the abort listener, settles
+ * local cancellation — there is no assumption the child cooperates — and then
+ * awaits the backend's teardown to actual exit.
+ * @param parts - the run identity, result, cancellation wiring, and teardown.
+ * @returns the external run handle.
+ */
+export declare function subprocessRunHandle(parts: SubprocessRunHandleParts): SubagentRun;
+//# sourceMappingURL=out-of-process.d.ts.map

package/lib/types/out-of-process.js

@@ -0,0 +1,178 @@
+/**
+ * Provider-side vocabulary for OUT-OF-PROCESS subagent backends — the pieces
+ * that enforce this seam's own contracts around a child in another process:
+ * the no-capabilities advertisement, timing-bound validation, child
+ * working-directory validation, the never-reject result settlement, and the standard
+ * run-handle publication. Backends compose these with their own wire drivers;
+ * the process machinery itself (spawn, env scrub, managed-range teardown)
+ * belongs to the `dsh-subprocess` seam.
+ *
+ * @module @qlzt/dsh-subagent/out-of-process
+ */
+import { accessSync, constants, statSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
+/** Maximum UTF-8 size of {@link SubagentResult.diagnostic}. */
+const MAX_SUBAGENT_DIAGNOSTIC_BYTES = 4_096;
+const DIAGNOSTIC_TRUNCATION_SUFFIX = '\n[diagnostic truncated]';
+const utf8Encoder = new TextEncoder();
+const utf8Decoder = new TextDecoder();
+/**
+ * Limit provider-authored failure detail without splitting a UTF-8 sequence.
+ * @param diagnostic - safe diagnostic text produced by the provider.
+ * @returns the original text, or a visibly truncated value within the limit.
+ */
+function limitSubagentDiagnostic(diagnostic) {
+    const bytes = utf8Encoder.encode(diagnostic);
+    if (bytes.byteLength <= MAX_SUBAGENT_DIAGNOSTIC_BYTES)
+        return diagnostic;
+    const suffixBytes = utf8Encoder.encode(DIAGNOSTIC_TRUNCATION_SUFFIX).byteLength;
+    let prefixBytes = MAX_SUBAGENT_DIAGNOSTIC_BYTES - suffixBytes;
+    while ((bytes[prefixBytes] & 0b1100_0000) === 0b1000_0000) {
+        prefixBytes -= 1;
+    }
+    return utf8Decoder.decode(bytes.subarray(0, prefixBytes))
+        + DIAGNOSTIC_TRUNCATION_SUFFIX;
+}
+/** Enforce the byte limit on a provider-returned diagnostic. */
+function normalizeSubagentDiagnostic(result) {
+    return result.diagnostic === undefined
+        ? result
+        : { ...result, diagnostic: limitSubagentDiagnostic(result.diagnostic) };
+}
+/**
+ * The capability advertisement of an out-of-process backend: NONE. A child in
+ * another process cannot honor parent-enforced start features
+ * (`agentOptions`/`outputSchema`/`maxDepth`/`toolFilter`/`persona`), so the service rejects a
+ * request needing any of them before `start` runs — never accepted-then-ignored.
+ */
+export const NO_START_CAPABILITIES = Object.freeze({
+    agentOptions: false,
+    outputSchema: false,
+    depthLimit: false,
+    toolFilter: false,
+    persona: false,
+});
+/**
+ * Assert a configured timing bound is a positive finite number (it bounds a
+ * teardown or shutdown wait; zero, negative, or NaN would skip or wedge it).
+ * @param prefix - the consuming plugin's diagnostic prefix (e.g. `subagent-acp`).
+ * @param name - the config field name, for the diagnostic.
+ * @param value - the configured value.
+ */
+export function assertPositiveFinite(prefix, name, value) {
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new Error(`${prefix}: ${name} must be a positive finite number`);
+    }
+}
+/**
+ * Whether `path` names an existing directory the harness can ENTER. The
+ * search-permission probe matters: `statSync().isDirectory()` is true for a
+ * mode-600 directory, but a subprocess cwd needs `X_OK` or spawn fails EACCES.
+ */
+function isEnterableDirectory(path) {
+    try {
+        if (!statSync(path).isDirectory())
+            return false;
+        accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        // statSync/accessSync throw only filesystem access errors here
+        // (ENOENT/EACCES/ENOTDIR/…), and every one of them means the path cannot
+        // serve as the child's cwd.
+        return false;
+    }
+}
+/**
+ * Assert `cwd` can actually host the child: absolute (it doubles as the
+ * child's workspace identity, and a relative path would be re-anchored to the
+ * server process's launch directory) and an existing directory (fail here,
+ * before the process boundary, instead of as an ambiguous spawn ENOENT).
+ * @param prefix - the consuming plugin's diagnostic prefix.
+ * @param label - which source supplied the value, for the diagnostic.
+ * @param cwd - the candidate working directory.
+ * @returns `cwd`, validated.
+ */
+export function assertUsableCwd(prefix, label, cwd) {
+    if (!isAbsolute(cwd)) {
+        throw new Error(`${prefix}: ${label} must be an absolute path: ${cwd}`);
+    }
+    if (!isEnterableDirectory(cwd)) {
+        throw new Error(`${prefix}: ${label} is not an accessible directory: ${cwd}`);
+    }
+    return cwd;
+}
+/** Normalize an unknown thrown value to an Error (the catch binding is `unknown`). */
+function toError(value) {
+    // The rejecting surfaces (wire clients, spawn failures) only throw
+    // `Error`s; the `String(value)` arm is a defensive fallback for a non-Error
+    // throw the typed surfaces cannot produce.
+    /* v8 ignore next */
+    return value instanceof Error ? value : new Error(String(value));
+}
+/**
+ * Settle an out-of-process run result under the seam contract: `result` never
+ * rejects after publication. A normally completed or rejected attempt resolves
+ * as `aborted` when cancellation already settled locally; another rejection is
+ * flattened to `stopReason: 'error'` through the contained diagnostic sink.
+ * Provider-returned diagnostics use the same byte limit. The abort listener is
+ * removed on every path.
+ * @param parts - the attempt, output snapshot, cancellation state, sink, and signal wiring.
+ * @returns the terminal result (never a rejection).
+ */
+export async function settleRunResult(parts) {
+    try {
+        const result = await parts.attempt();
+        return parts.cancelled()
+            ? { output: parts.collectOutput(), stopReason: 'aborted' }
+            : normalizeSubagentDiagnostic(result);
+    }
+    catch (error) {
+        // Cover a rejection already queued when cancellation arrives.
+        if (parts.cancelled())
+            return { output: parts.collectOutput(), stopReason: 'aborted' };
+        // Flatten post-publication transport failures while preserving diagnostics.
+        try {
+            parts.onError?.(toError(error), 'error');
+        }
+        catch {
+            // The diagnostic sink cannot reject the run result.
+        }
+        const collected = parts.collectDiagnostic?.();
+        const diagnostic = collected === undefined
+            ? undefined
+            : limitSubagentDiagnostic(collected);
+        return {
+            output: parts.collectOutput(),
+            ...diagnostic === undefined ? {} : { diagnostic },
+            stopReason: 'error',
+        };
+    }
+    finally {
+        parts.signal.removeEventListener('abort', parts.onAbort);
+    }
+}
+/**
+ * Publish the seam run handle for an out-of-process child. `dispose()` is
+ * idempotent (one memoized teardown): it removes the abort listener, settles
+ * local cancellation — there is no assumption the child cooperates — and then
+ * awaits the backend's teardown to actual exit.
+ * @param parts - the run identity, result, cancellation wiring, and teardown.
+ * @returns the external run handle.
+ */
+export function subprocessRunHandle(parts) {
+    let disposal;
+    return {
+        id: parts.id,
+        result: parts.result,
+        dispose() {
+            if (disposal !== undefined)
+                return disposal;
+            parts.signal.removeEventListener('abort', parts.onAbort);
+            parts.requestCancel();
+            disposal = parts.teardown();
+            return disposal;
+        },
+    };
+}
+//# sourceMappingURL=out-of-process.js.map

package/lib/types/projection-types.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Pure client-safe subagent projection vocabulary.
+ *
+ * @module @qlzt/dsh-subagent/projection-types
+ */
+import type { SessionId, SessionSeq } from '@qlzt/dsh-session/types';
+/** One current direct-child discovery row materialized from parent facts. */
+export type SubagentCatalogEntry = {
+    readonly id: SessionId;
+    readonly createdAt: number;
+} & ({
+    readonly mode: 'one-shot';
+    readonly label?: string;
+} | {
+    readonly mode: 'external';
+    readonly label?: string;
+} | {
+    readonly mode: 'continuable';
+    readonly label: string;
+} | {
+    readonly mode: 'unknown';
+    readonly label?: string;
+});
+/** Durable active-turn timing for one descriptor-backed child session. */
+export interface SubagentTimingProjection {
+    /** Milliseconds accumulated across completed turns after the child's own descriptor. */
+    settledMs: number;
+    /** Same-cut bounds of the currently open turn, when one has not reached `turn/end`. */
+    active?: {
+        /** Start of the open turn. */
+        since: number;
+        /** Latest event time folded into this projection cut. */
+        through: number;
+    };
+    /**
+     * Whether the latest closed turn after the child's own descriptor completed
+     * normally; absent while a turn is open or before one closes.
+     */
+    lastTurnCompleted?: boolean;
+}
+/**
+ * Durable identity of one descriptor-backed subagent session: lifecycle mode
+ * plus creation label, folded last-wins from `subagent/descriptor` events.
+ * Label strength follows the descriptor schema: a continuable child always
+ * carries one, a one-shot child may omit it.
+ */
+export type SubagentIdentityProjection = {
+    /** A terminal one-shot child. */
+    mode: 'one-shot';
+    /** Optional durable creation label from the child's descriptor. */
+    label?: string;
+    /**
+     * Seq of the `subagent/descriptor` event this identity was folded from.
+     * `session.isOwnSeq(seq)` proves the identity comes from the child's
+     * OWN log suffix — where a descriptor is immutable once appended — and
+     * not from a fork seed's replayed ancestor descriptor.
+     */
+    seq: SessionSeq;
+} | {
+    /** A resumable conversation. */
+    mode: 'continuable';
+    /** Durable creation label from the child's descriptor. */
+    label: string;
+    /** Seq of the folded descriptor event; see the one-shot arm for the own-suffix proof. */
+    seq: SessionSeq;
+};
+declare module '@qlzt/dsh-session-projection/types' {
+    interface SessionProjectionMap {
+        /** Direct children in parent catalog event order, excluding fork-inherited facts. */
+        subagentCatalog: SubagentCatalogEntry[];
+        /** Active-turn duration and latest closed-turn completion for a descriptor-backed subagent session. */
+        subagentTiming: SubagentTimingProjection;
+        /**
+         * Identity of a descriptor-backed subagent session. `null` ⟺ no valid
+         * descriptor (missing, malformed, or unrecognized-version — deliberately
+         * undistinguished). The sentinel is deliberately serializable: a
+         * value pushed over JSON transports must survive `JSON.stringify`
+         * losslessly, where an `undefined` field would be dropped and a stale
+         * identity would survive on the receiving side. The entry itself stays
+         * non-optional.
+         */
+        subagent: SubagentIdentityProjection | null;
+    }
+}
+//# sourceMappingURL=projection-types.d.ts.map

package/lib/types/projection-types.js

@@ -0,0 +1,7 @@
+/**
+ * Pure client-safe subagent projection vocabulary.
+ *
+ * @module @qlzt/dsh-subagent/projection-types
+ */
+export {};
+//# sourceMappingURL=projection-types.js.map

package/lib/types/projection.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Pure session projections for subagent identity (mode/label) and active-turn
+ * duration.
+ *
+ * @module @qlzt/dsh-subagent/projection
+ */
+import { z } from 'zod';
+import type { SessionEvent } from '@qlzt/dsh-session';
+import type { SubagentIdentityProjection, SubagentTimingProjection } from './projection-types.ts';
+/** Fold state for a subagent's latest timing snapshot. */
+export interface TimingState {
+    /** Milliseconds accumulated across completed post-descriptor turns. */
+    settledMs: number;
+    /** Current open interval kept paired inside the fold. */
+    active?: {
+        since: number;
+        through: number;
+    } | undefined;
+    /** Latest pre-descriptor turn start, promoted when the child's own descriptor arrives. */
+    pendingTurnStart?: number | undefined;
+    /** Whether the fold has crossed a descriptor in this logical log. */
+    descriptorSeen: boolean;
+    /** Whether the latest closed post-descriptor turn completed normally; absent while a turn is open or before one closes. */
+    lastTurnCompleted?: boolean | undefined;
+}
+declare module '@qlzt/dsh-session-projection/types' {
+    interface SessionProjectionStateMap {
+        subagentTiming: TimingState;
+        subagent: IdentityState;
+    }
+}
+/**
+ * Fold turn boundaries around the child's own durable descriptor.
+ *
+ * A fork seed may contain an ancestor descriptor and completed turns. Every
+ * descriptor therefore resets the accumulated state; the healthy catalog
+ * admits only a child with exactly one descriptor in its own suffix, making
+ * the final reset the child's authoritative timing origin.
+ */
+export declare const subagentTimingProjectionDefinition: {
+    key: "subagentTiming";
+    stateSchema: z.ZodType<TimingState, unknown, z.core.$ZodTypeInternals<TimingState, unknown>>;
+    init: () => {
+        descriptorSeen: false;
+        settledMs: number;
+    };
+    apply: (state: NoInfer<TimingState>, event: SessionEvent) => {
+        /** Milliseconds accumulated across completed post-descriptor turns. */
+        settledMs: number;
+        /** Current open interval kept paired inside the fold. */
+        active?: {
+            since: number;
+            through: number;
+        } | undefined;
+        /** Whether the fold has crossed a descriptor in this logical log. */
+        descriptorSeen: boolean;
+        /** Whether the latest closed post-descriptor turn completed normally; absent while a turn is open or before one closes. */
+        lastTurnCompleted?: boolean | undefined;
+    };
+    wire: {
+        viewSchema: z.ZodType<SubagentTimingProjection, unknown, z.core.$ZodTypeInternals<SubagentTimingProjection, unknown>>;
+        view: (state: NoInfer<TimingState>) => {
+            lastTurnCompleted?: boolean;
+            active?: {
+                since: number;
+                through: number;
+            };
+            settledMs: number;
+        };
+    };
+    stateVersion: number;
+};
+interface IdentityState {
+    /** Identity from the last valid descriptor; absent before one, and after an invalid one. */
+    identity?: SubagentIdentityProjection | undefined;
+}
+/**
+ * Fold the durable mode/label identity from `subagent/descriptor` events,
+ * last-wins: a fork seed may replay an ancestor's descriptor, and the child's
+ * own descriptor must override it — the same reset discipline as
+ * {@link subagentTimingProjectionDefinition}. A malformed or unknown-version
+ * payload resets to the `null` sentinel instead of throwing, so a fork of a
+ * healthy ancestor never inherits an identity its own descriptor failed to
+ * establish — and the reset survives every JSON push frame, so a consumer
+ * holding the earlier identity replaces it instead of keeping it stale;
+ * `null` ⟺ no valid descriptor, with the causes deliberately undistinguished.
+ */
+export declare const subagentIdentityProjectionDefinition: {
+    key: "subagent";
+    stateSchema: z.ZodType<IdentityState, unknown, z.core.$ZodTypeInternals<IdentityState, unknown>>;
+    init: () => {};
+    apply: (state: NoInfer<IdentityState>, event: SessionEvent) => IdentityState;
+    wire: {
+        viewSchema: z.ZodNullable<z.ZodType<SubagentIdentityProjection, unknown, z.core.$ZodTypeInternals<SubagentIdentityProjection, unknown>>>;
+        view: (state: NoInfer<IdentityState>) => SubagentIdentityProjection | null;
+    };
+    stateVersion: number;
+};
+export {};
+//# sourceMappingURL=projection.d.ts.map

package/lib/types/projection.js

@@ -0,0 +1,157 @@
+/**
+ * Pure session projections for subagent identity (mode/label) and active-turn
+ * duration.
+ *
+ * @module @qlzt/dsh-subagent/projection
+ */
+import { z } from 'zod';
+import { SessionSeq } from '@qlzt/dsh-session';
+import { foldSubagentDescriptor } from "./descriptor.js";
+const activeIntervalSchema = z.object({
+    since: z.number().int().nonnegative(),
+    through: z.number().int().nonnegative(),
+}).strict();
+const projectionSchema = z.object({
+    settledMs: z.number().int().nonnegative(),
+    active: activeIntervalSchema.optional(),
+    lastTurnCompleted: z.boolean().optional(),
+}).strict().transform(({ settledMs, active, lastTurnCompleted }) => ({
+    settledMs,
+    ...active === undefined ? {} : { active },
+    ...lastTurnCompleted === undefined ? {} : { lastTurnCompleted },
+}));
+const timingStateSchema = z.object({
+    settledMs: z.number().int().nonnegative(),
+    active: activeIntervalSchema.optional(),
+    pendingTurnStart: z.number().int().nonnegative().optional(),
+    descriptorSeen: z.boolean(),
+    lastTurnCompleted: z.boolean().optional(),
+}).strict();
+/**
+ * Fold turn boundaries around the child's own durable descriptor.
+ *
+ * A fork seed may contain an ancestor descriptor and completed turns. Every
+ * descriptor therefore resets the accumulated state; the healthy catalog
+ * admits only a child with exactly one descriptor in its own suffix, making
+ * the final reset the child's authoritative timing origin.
+ */
+export const subagentTimingProjectionDefinition = {
+    key: 'subagentTiming',
+    stateSchema: timingStateSchema,
+    init: () => ({ descriptorSeen: false, settledMs: 0 }),
+    apply: (state, event) => {
+        if (event.type === 'turn/start') {
+            const { lastTurnCompleted: _closed, ...openState } = state;
+            return state.descriptorSeen
+                ? { ...openState, active: { since: event.time, through: event.time } }
+                : { ...openState, pendingTurnStart: event.time };
+        }
+        if (event.type === 'subagent/descriptor') {
+            const activeSince = state.active?.since ?? state.pendingTurnStart;
+            return {
+                descriptorSeen: true,
+                settledMs: 0,
+                ...(activeSince === undefined
+                    ? {}
+                    : { active: { since: activeSince, through: event.time } }),
+            };
+        }
+        if (event.type === 'turn/end') {
+            if (!state.descriptorSeen) {
+                if (state.pendingTurnStart === undefined)
+                    return state;
+                const { pendingTurnStart: _closed, ...next } = state;
+                return next;
+            }
+            if (state.active === undefined)
+                return state;
+            const { active, ...rest } = state;
+            return {
+                ...rest,
+                settledMs: state.settledMs + Math.max(0, event.time - active.since),
+                lastTurnCompleted: event.data.reason.kind === 'completed',
+            };
+        }
+        if (state.active === undefined)
+            return state;
+        return { ...state, active: { ...state.active, through: event.time } };
+    },
+    wire: {
+        viewSchema: projectionSchema,
+        view: state => ({
+            settledMs: state.settledMs,
+            ...(state.active === undefined ? {} : { active: state.active }),
+            ...(state.lastTurnCompleted === undefined ? {} : { lastTurnCompleted: state.lastTurnCompleted }),
+        }),
+    },
+    stateVersion: 3,
+};
+// The cast bridges only the optional-label arm: Zod's optional output
+// includes explicit `undefined`, which exactOptionalPropertyTypes excludes
+// from the public interface. The no-value state itself is the serializable
+// `null` arm — never `undefined` — so every registry read and push frame
+// survives JSON.stringify losslessly.
+const identityValueSchema = z.discriminatedUnion('mode', [
+    z.object({
+        mode: z.literal('one-shot'),
+        label: z.string().optional(),
+        seq: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).transform(SessionSeq),
+    }).strict(),
+    z.object({
+        mode: z.literal('continuable'),
+        label: z.string(),
+        seq: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).transform(SessionSeq),
+    }).strict(),
+]);
+const identitySchema = identityValueSchema.nullable();
+const identityStateSchema = z.object({
+    identity: identityValueSchema.optional(),
+}).strict();
+/** Interpret one `subagent/descriptor` event's identity; no value when the payload cannot be trusted. */
+function descriptorIdentity(event) {
+    let descriptor;
+    try {
+        descriptor = foldSubagentDescriptor([event]);
+    }
+    catch {
+        // Only a malformed current-version payload throws in descriptor parsing;
+        // a projection fold must never throw, so damage folds to no value.
+        descriptor = undefined;
+    }
+    if (descriptor === undefined)
+        return undefined;
+    return descriptor.mode === 'one-shot'
+        ? {
+            mode: 'one-shot',
+            ...descriptor.label !== undefined ? { label: descriptor.label } : {},
+            seq: event.seq,
+        }
+        : { mode: 'continuable', label: descriptor.label, seq: event.seq };
+}
+/**
+ * Fold the durable mode/label identity from `subagent/descriptor` events,
+ * last-wins: a fork seed may replay an ancestor's descriptor, and the child's
+ * own descriptor must override it — the same reset discipline as
+ * {@link subagentTimingProjectionDefinition}. A malformed or unknown-version
+ * payload resets to the `null` sentinel instead of throwing, so a fork of a
+ * healthy ancestor never inherits an identity its own descriptor failed to
+ * establish — and the reset survives every JSON push frame, so a consumer
+ * holding the earlier identity replaces it instead of keeping it stale;
+ * `null` ⟺ no valid descriptor, with the causes deliberately undistinguished.
+ */
+export const subagentIdentityProjectionDefinition = {
+    key: 'subagent',
+    stateSchema: identityStateSchema,
+    init: () => ({}),
+    apply: (state, event) => {
+        if (event.type !== 'subagent/descriptor')
+            return state;
+        const identity = descriptorIdentity(event);
+        return identity === undefined ? {} : { identity };
+    },
+    wire: { viewSchema: identitySchema, view: state => state.identity ?? null },
+    // Bumped when the identity gained its `seq` field: an older checkpoint row
+    // would replay into a value the schema rejects, so it must refold instead.
+    stateVersion: 2,
+};
+//# sourceMappingURL=projection.js.map

package/lib/types/structured.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Child-scoped structured-output tool, prompt instruction, terminal guard, and authoritative
+ * result capture for in-process subagents. Each child registers its real schema on its own
+ * scope, so concurrent runs do not interact and disposal leaves no global residue. The prompt
+ * contribution is ordinary reconstructed request state.
+ *
+ * Capture commits only after the authoritative `tools/result` succeeds; PTC mode capture also
+ * waits for the enclosing `run_code` result. The terminal result marker and monotonic tool
+ * guard prevent later calls from reopening a completed structured run.
+ * @module @qlzt/dsh-subagent/structured
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type ObjectJsonSchema } from '@qlzt/dsh-tools';
+/** The model-facing tool name a structured child must call to finish. */
+export declare const STRUCTURED_OUTPUT_TOOL = "structured_output";
+/**
+ * The instruction registered as the child's trailing scoped prompt section:
+ * the demand travels with the
+ * tool, as ordinary prompt state of exactly one agent.
+ */
+export declare const STRUCTURED_OUTPUT_INSTRUCTION: string;
+/** One structured run's live handle: read the captured value once the child settles. */
+export interface StructuredAttachment {
+    /**
+     * Input stays closed from capture staging through its final result, including
+     * an enclosing PTC execution. A failed result discards its capture and reopens input.
+     * @returns whether the activation can accept another message.
+     */
+    acceptsInput(): boolean;
+    /**
+     * The captured value, once the child called the tool with valid arguments
+     * and the authoritative final tool result accepted that call.
+     * @returns the committed value, or undefined while none was accepted.
+     */
+    captured(): {
+        value: unknown;
+    } | undefined;
+}
+/**
+ * Attach the scoped capture tool, instruction, and enforcement to a child during
+ * its creation window. Child disposal removes every registration.
+ * @param childCtx - the child agent's scope context (`setup`'s argument).
+ * @param schema - the trusted, already-asserted schema subset to enforce (see
+ *   `assertObjectJsonSchema` in dsh-tools).
+ * @param canComplete - whether accepted input and owned child work have finished.
+ * @returns the attachment handle (read `captured()` after the child settles).
+ */
+export declare function attachStructuredRuntime(childCtx: Context, schema: ObjectJsonSchema, canComplete: () => boolean): StructuredAttachment;
+//# sourceMappingURL=structured.d.ts.map