@fishwithcat/dsh-subagent 0.0.0-stage → 0.2.2-alpha.3

package/lib/typert.remote-client.d.ts

@@ -0,0 +1,29 @@
+/* Generated by @deepseek-ai/dsh-typert-generator from the Host FaceModel — do not edit. */
+import type {
+  RemoteResult,
+  TypertRemoteInfo,
+  TypertRemoteMethod,
+} from '@deepseek-ai/dsh-typert-protocol'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { SubagentInterruptReceipt, SubagentPromptReceipt, SubagentPromptRequest } from '@deepseek-ai/dsh-subagent/client'
+
+declare module '@deepseek-ai/dsh-typert-protocol' {
+  interface TypertRemoteNamespace$7375626167656e7473 {
+    interruptByUser: (childSessionId: SessionId) => Promise<RemoteResult<SubagentInterruptReceipt>>
+    prompt: (request: SubagentPromptRequest, signal?: AbortSignal) => Promise<RemoteResult<SubagentPromptReceipt>>
+  }
+  interface TypertRemoteMap {
+    'subagents/interruptByUser': (childSessionId: SessionId) => Promise<RemoteResult<SubagentInterruptReceipt>>
+    'subagents/prompt': (request: SubagentPromptRequest, signal?: AbortSignal) => Promise<RemoteResult<SubagentPromptReceipt>>
+  }
+  interface TypertRemoteNamespaceMap {
+    'subagents': TypertRemoteNamespace$7375626167656e7473
+  }
+}
+
+export declare const TYPERT_REMOTE: TypertRemoteInfo<{
+  readonly 'subagents/interruptByUser': TypertRemoteMethod<{ readonly 'childSessionId': SessionId }, SubagentInterruptReceipt>
+  readonly 'subagents/prompt': TypertRemoteMethod<{ readonly 'request': SubagentPromptRequest }, SubagentPromptReceipt>
+}>
+export default TYPERT_REMOTE
+//# sourceMappingURL=typert.remote-client.d.ts.map

package/lib/typert.remote-client.js

@@ -0,0 +1,122 @@
+/* Generated by @deepseek-ai/dsh-typert-generator from the Host FaceModel — do not edit. */
+import { z } from 'zod'
+
+import { createTypertRemoteInfo } from '@deepseek-ai/dsh-typert-protocol/remote-info'
+
+let _deepseek_ai_dsh_subagent_subagents_interruptByUser_parameter_0$schema$value
+const _deepseek_ai_dsh_subagent_subagents_interruptByUser_parameter_0$schema = () => (_deepseek_ai_dsh_subagent_subagents_interruptByUser_parameter_0$schema$value ??= z.string())
+let _deepseek_ai_dsh_subagent_subagents_interruptByUser_result$schema$value
+const _deepseek_ai_dsh_subagent_subagents_interruptByUser_result$schema = () => (_deepseek_ai_dsh_subagent_subagents_interruptByUser_result$schema$value ??= z.object({
+  'accepted': z.literal(true).readonly(),
+}))
+let _deepseek_ai_dsh_subagent_subagents_prompt_parameter_0$schema$value
+const _deepseek_ai_dsh_subagent_subagents_prompt_parameter_0$schema = () => (_deepseek_ai_dsh_subagent_subagents_prompt_parameter_0$schema$value ??= z.object({
+  'requestId': z.string().readonly().describe('Identity persisted on the accepted message, minted before the call.'),
+  'childSessionId': z.string().readonly(),
+  'delivery': z.union([z.literal("queue"), z.literal("steer")]).readonly().describe('Whether this message queues a later turn or targets the nearest step.'),
+  'content': z.array(z.union([z.object({
+  'type': z.literal("text").readonly(),
+  'text': z.string().readonly(),
+}), z.object({
+  'type': z.literal("image").readonly(),
+  'mediaType': z.union([z.literal("image/png"), z.literal("image/jpeg"), z.literal("image/webp"), z.literal("image/gif")]).readonly(),
+  'data': z.string().readonly(),
+  'name': z.string().readonly().optional(),
+})])).readonly().describe('Browser prompt parts delivered as the child\'s user message. The Host admits and persists image parts before delivery, so the wire never carries a durable attachment reference the caller could fabricate.'),
+  'clientTimeZone': z.string().readonly().optional().describe('Optional browser zone sampled for this exact human prompt.'),
+}))
+let _deepseek_ai_dsh_subagent_subagents_prompt_result$schema$value
+const _deepseek_ai_dsh_subagent_subagents_prompt_result$schema = () => (_deepseek_ai_dsh_subagent_subagents_prompt_result$schema$value ??= z.object({
+  'messageId': z.string().readonly(),
+}))
+let _deepseek_ai_dsh_subagent_subagents_interruptByUser_parameter_0_strict$schema$value
+const _deepseek_ai_dsh_subagent_subagents_interruptByUser_parameter_0_strict$schema = () => (_deepseek_ai_dsh_subagent_subagents_interruptByUser_parameter_0_strict$schema$value ??= z.string())
+let _deepseek_ai_dsh_subagent_subagents_prompt_parameter_0_strict$schema$value
+const _deepseek_ai_dsh_subagent_subagents_prompt_parameter_0_strict$schema = () => (_deepseek_ai_dsh_subagent_subagents_prompt_parameter_0_strict$schema$value ??= z.strictObject({
+  'requestId': z.string().readonly().describe('Identity persisted on the accepted message, minted before the call.'),
+  'childSessionId': z.string().readonly(),
+  'delivery': z.union([z.literal("queue"), z.literal("steer")]).readonly().describe('Whether this message queues a later turn or targets the nearest step.'),
+  'content': z.array(z.union([z.strictObject({
+  'type': z.literal("text").readonly(),
+  'text': z.string().readonly(),
+}), z.strictObject({
+  'type': z.literal("image").readonly(),
+  'mediaType': z.union([z.literal("image/png"), z.literal("image/jpeg"), z.literal("image/webp"), z.literal("image/gif")]).readonly(),
+  'data': z.string().readonly(),
+  'name': z.string().readonly().optional(),
+})])).readonly().describe('Browser prompt parts delivered as the child\'s user message. The Host admits and persists image parts before delivery, so the wire never carries a durable attachment reference the caller could fabricate.'),
+  'clientTimeZone': z.string().readonly().optional().describe('Optional browser zone sampled for this exact human prompt.'),
+}))
+
+export const TYPERT_REMOTE = createTypertRemoteInfo({
+  package: '@fishwithcat/dsh-subagent',
+  methods: {
+    'subagents/interruptByUser': {
+      service: 'subagents',
+      description: 'Remote face of {@link interrupt}, authorized on the target Session by the Gateway. No catalog, history, persistence, or parent Agent lookup runs. Absent, idle, and already-completed targets are accepted no-ops there.',
+      invocation: { kind: 'direct' },
+      parameters: [
+        {
+          name: 'childSessionId',
+          description: 'durable child session id to interrupt.',
+          source: 'json',
+          codec: {
+            mode: 'strict',
+            typeSymbol: '@deepseek-ai/dsh-session/types#SessionId',
+            create: _deepseek_ai_dsh_subagent_subagents_interruptByUser_parameter_0$schema,
+            jsonSchema: {"type":"string"},
+          },
+          strictCodec: {
+            mode: 'strict',
+            typeSymbol: '@deepseek-ai/dsh-session/types#SessionId',
+            create: _deepseek_ai_dsh_subagent_subagents_interruptByUser_parameter_0_strict$schema,
+            jsonSchema: {"type":"string"},
+          },
+        },
+      ],
+      result: {
+        mode: 'strict',
+        typeSymbol: '@deepseek-ai/dsh-subagent/client#SubagentInterruptReceipt',
+        create: _deepseek_ai_dsh_subagent_subagents_interruptByUser_result$schema,
+        description: 'acknowledgement that the cancel signal was admitted, not that the target is quiescent.',
+        jsonSchema: {"type":"object","properties":{"accepted":{"type":"boolean","const":true}},"required":["accepted"],"additionalProperties":true},
+      },
+      sourceLocation: {"file":"packages/subagent/subagent/src/index.ts","line":467,"column":3},
+    },
+    'subagents/prompt': {
+      service: 'subagents',
+      description: 'Deliver one browser-authored message to a continuable child through its live subagent tree root, retaining the caller-minted request identity and validated browser zone on the accepted message. Success identifies the message the child\'s inbox accepted; later execution is independent of this call. Queue delivery targets a later turn; steer delivery targets the nearest step and retains the Agent loop\'s best-effort fallback semantics. Image parts are admitted and persisted through the attachment store before delivery, and the child\'s model must accept image input. Cold resume at capacity rejects with `subagent/delivery-unavailable`. Access is checked on the target Session before attachment admission or restoration.',
+      invocation: { kind: 'direct' },
+      parameters: [
+        {
+          name: 'request',
+          description: 'target id, delivery, minted identity, content, and optional browser zone.',
+          source: 'json',
+          codec: {
+            mode: 'strict',
+            typeSymbol: '@deepseek-ai/dsh-subagent/client#SubagentPromptRequest',
+            create: _deepseek_ai_dsh_subagent_subagents_prompt_parameter_0$schema,
+            jsonSchema: {"type":"object","properties":{"requestId":{"type":"string","description":"Identity persisted on the accepted message, minted before the call."},"childSessionId":{"type":"string"},"delivery":{"type":"string","enum":["queue","steer"],"description":"Whether this message queues a later turn or targets the nearest step."},"content":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string"}},"required":["type","text"],"additionalProperties":true},{"type":"object","properties":{"type":{"type":"string","const":"image"},"mediaType":{"type":"string","enum":["image/png","image/jpeg","image/webp","image/gif"]},"data":{"type":"string"},"name":{"type":"string"}},"required":["type","mediaType","data"],"additionalProperties":true}]},"description":"Browser prompt parts delivered as the child's user message. The Host admits and persists image parts before delivery, so the wire never carries a durable attachment reference the caller could fabricate."},"clientTimeZone":{"type":"string","description":"Optional browser zone sampled for this exact human prompt."}},"required":["requestId","childSessionId","delivery","content"],"additionalProperties":true},
+          },
+          strictCodec: {
+            mode: 'strict',
+            typeSymbol: '@deepseek-ai/dsh-subagent/client#SubagentPromptRequest',
+            create: _deepseek_ai_dsh_subagent_subagents_prompt_parameter_0_strict$schema,
+            jsonSchema: {"type":"object","properties":{"requestId":{"type":"string","description":"Identity persisted on the accepted message, minted before the call."},"childSessionId":{"type":"string"},"delivery":{"type":"string","enum":["queue","steer"],"description":"Whether this message queues a later turn or targets the nearest step."},"content":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string"}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"image"},"mediaType":{"type":"string","enum":["image/png","image/jpeg","image/webp","image/gif"]},"data":{"type":"string"},"name":{"type":"string"}},"required":["type","mediaType","data"],"additionalProperties":false}]},"description":"Browser prompt parts delivered as the child's user message. The Host admits and persists image parts before delivery, so the wire never carries a durable attachment reference the caller could fabricate."},"clientTimeZone":{"type":"string","description":"Optional browser zone sampled for this exact human prompt."}},"required":["requestId","childSessionId","delivery","content"],"additionalProperties":false},
+          },
+        },
+      ],
+      cancellation: { parameter: 'signal' },
+      result: {
+        mode: 'strict',
+        typeSymbol: '@deepseek-ai/dsh-subagent/client#SubagentPromptReceipt',
+        create: _deepseek_ai_dsh_subagent_subagents_prompt_result$schema,
+        description: 'the accepted message\'s inbox identity.',
+        jsonSchema: {"type":"object","properties":{"messageId":{"type":"string"}},"required":["messageId"],"additionalProperties":true},
+      },
+      sourceLocation: {"file":"packages/subagent/subagent/src/index.ts","line":414,"column":9},
+    },
+  },
+}, z)
+
+export default TYPERT_REMOTE

package/lib/types/activation.d.ts

@@ -0,0 +1,110 @@
+/** Execution-period records, capacity slots, child serialization, and local output capture.
+ * @module @deepseek-ai/dsh-subagent/activation
+ */
+import type { Agent, AgentHandle } from '@deepseek-ai/dsh-agent';
+import type { SessionId, SessionLogOffset } from '@deepseek-ai/dsh-session';
+import type { StructuredAttachment } from './structured.ts';
+import type { SubagentResult, SubagentRun, SubagentRunId } from './types.ts';
+/** Process-local capacity shared by every member of a subagent tree. */
+export declare class ActivationPool {
+    private readonly slots;
+    /**
+     * Reserve before reconstruction; release also tolerates unpublished rollback.
+     * @param capacity - the maximum simultaneous activations in this pool.
+     * @returns an idempotent slot release.
+     */
+    reserve(capacity: number): () => void;
+}
+/**
+ * One residency epoch for a local child or an external execution.
+ * The manager owns admission, execution handles, and resource release.
+ */
+interface ActivationBase {
+    /** Return this epoch's slot after its handle has finished disposal. */
+    readonly releaseSlot: () => void;
+    /** The durable child this Activation is an epoch of. */
+    readonly childId: SessionId;
+    /** Unique identity shared by this residency epoch's start/end event pair. */
+    readonly runId: SubagentRunId;
+    /** Provider recorded at creation, retained across cold resumes. */
+    readonly provider: string;
+    /** Exact live subagent tree root owning this instance and its shared capacity. */
+    readonly root: Agent;
+    /** Verified creation ancestors, from subagent tree root to direct creator. */
+    readonly ancestors: readonly SessionId[];
+    readonly delivery: 'parent' | 'caller';
+    readonly result: PromiseWithResolvers<SubagentResult>;
+    /** Published synchronously before teardown; subsequent callers share this transaction. */
+    closing: Promise<void> | undefined;
+    /**
+     * Whether local input was accepted or external startup completed, including
+     * any required catalog publication. Until then, teardown owes the parent no
+     * settlement notice, even if this epoch's start event was already published.
+     */
+    accepted: boolean;
+}
+/** Resources retained only for the selected execution kind. */
+export type ActivationResource = {
+    readonly kind: 'local';
+    readonly handle: AgentHandle;
+    readonly outputStart: SessionLogOffset;
+    readonly structured: StructuredAttachment | undefined;
+    /** Latest live failure not superseded by a later committed turn ending. */
+    failureAt: SessionLogOffset | undefined;
+    /** Renewed when local settlement must recheck input. */
+    poke: PromiseWithResolvers<void>;
+    /**
+     * Whether this child's settlement notice omits its closing text: true while
+     * the child's last logged tool call was a message to its direct parent and
+     * no input was claimed since.
+     */
+    omitClosingText: boolean;
+} | {
+    readonly kind: 'external';
+    readonly run: SubagentRun;
+    readonly controller: AbortController;
+};
+/** One managed execution period with its provider-specific resources. */
+export type Activation = ActivationBase & ActivationResource;
+/** Local residency with input admission and Session-backed result capture. */
+export type LocalActivation = Extract<Activation, {
+    kind: 'local';
+}>;
+/**
+ * Read the live Agent retained by local execution.
+ * @param activation - the managed local or external execution.
+ * @returns the local Agent, absent for an external run.
+ */
+export declare function activationAgent(activation: Activation): Agent | undefined;
+/**
+ * Require local residency before accepting further input.
+ * @param activation - execution targeted by message delivery.
+ * @returns the local activation.
+ * @throws when the external backend cannot accept another message.
+ */
+export declare function requireLocalActivation(activation: Activation): LocalActivation;
+/**
+ * Retain local failures whose turn ending could not be committed.
+ * @param activation - exact local Agent and epoch receiving the scoped observers.
+ * @param wake - notify its settlement watcher when failure changes readiness.
+ */
+export declare function observeLocalFailure(activation: LocalActivation, wake: () => void): void;
+/**
+ * Capture local output and retain failures without a later committed turn ending.
+ * @param activation - the settled local execution and any structured result.
+ * @returns final output, stop reason, and committed structured value.
+ */
+export declare function captureLocalResult(activation: LocalActivation): SubagentResult;
+/** Serialize each durable child's delivery, release, and disposal. */
+export declare class ChildLock {
+    private tails;
+    /**
+     * Run `operation` after every previously queued operation for `childId`.
+     * @param childId - the durable child whose operations are linearized.
+     * @param operation - the critical section to run in order.
+     * @returns the operation's own settlement.
+     */
+    run<T>(childId: SessionId, operation: () => Promise<T>): Promise<T>;
+}
+export {};
+//# sourceMappingURL=activation.d.ts.map

package/lib/types/activation.js

@@ -0,0 +1,112 @@
+/** Execution-period records, capacity slots, child serialization, and local output capture.
+ * @module @deepseek-ai/dsh-subagent/activation
+ */
+import { assertNever } from '@deepseek-ai/dsh-util-values';
+import { finalAssistantOutput } from "./assistant-output.js";
+import { epochStopReason } from "./lifecycle.js";
+import { SubagentError } from "./error.js";
+/** Process-local capacity shared by every member of a subagent tree. */
+export class ActivationPool {
+    slots = new Set();
+    /**
+     * Reserve before reconstruction; release also tolerates unpublished rollback.
+     * @param capacity - the maximum simultaneous activations in this pool.
+     * @returns an idempotent slot release.
+     */
+    reserve(capacity) {
+        if (this.slots.size >= capacity) {
+            throw new SubagentError(`subagent limit reached (active child limit: ${capacity}); wait for an existing child to finish `
+                + 'or complete this work with the current agents', 'ACTIVATION_LIMIT_REACHED');
+        }
+        const slot = Symbol();
+        this.slots.add(slot);
+        return () => { this.slots.delete(slot); };
+    }
+}
+/**
+ * Read the live Agent retained by local execution.
+ * @param activation - the managed local or external execution.
+ * @returns the local Agent, absent for an external run.
+ */
+export function activationAgent(activation) {
+    return activation.kind === 'local' ? activation.handle.agent : undefined;
+}
+/**
+ * Require local residency before accepting further input.
+ * @param activation - execution targeted by message delivery.
+ * @returns the local activation.
+ * @throws when the external backend cannot accept another message.
+ */
+export function requireLocalActivation(activation) {
+    switch (activation.kind) {
+        case 'local': return activation;
+        case 'external':
+            throw new SubagentError(`subagent "${activation.childId}" does not accept follow-up input`, 'NOT_CONTINUABLE');
+        /* v8 ignore next 2 -- Both execution kinds are handled above. */
+        default: return assertNever(activation);
+    }
+}
+/**
+ * Retain local failures whose turn ending could not be committed.
+ * @param activation - exact local Agent and epoch receiving the scoped observers.
+ * @param wake - notify its settlement watcher when failure changes readiness.
+ */
+export function observeLocalFailure(activation, wake) {
+    const child = activation.handle.agent;
+    child.ctx.on('agent/error', ({ agent }) => {
+        if (agent !== child)
+            return;
+        activation.failureAt = child.session.seq;
+        wake();
+    });
+    child.ctx.on('session/event', (session, event) => {
+        if (session === child.session && event.type === 'turn/end'
+            && activation.failureAt !== undefined && event.seq >= activation.failureAt) {
+            activation.failureAt = undefined;
+        }
+    });
+}
+/**
+ * Capture local output and retain failures without a later committed turn ending.
+ * @param activation - the settled local execution and any structured result.
+ * @returns final output, stop reason, and committed structured value.
+ */
+export function captureLocalResult(activation) {
+    // oxlint-disable-next-line typescript/no-deprecated -- Existing Session history read; migration deferred.
+    const events = activation.handle.agent.session.snapshotEvents(activation.outputStart);
+    const output = finalAssistantOutput(events) ?? [];
+    const stopReason = activation.failureAt === undefined ? epochStopReason(events) : 'error';
+    const structured = activation.structured;
+    if (structured !== undefined) {
+        const captured = structured.captured();
+        if (captured !== undefined)
+            return { output, stopReason, structured: captured.value };
+        if (stopReason === 'completed')
+            return { output, stopReason: 'error' };
+    }
+    return { output, stopReason };
+}
+/** Serialize each durable child's delivery, release, and disposal. */
+export class ChildLock {
+    tails = new Map();
+    /**
+     * Run `operation` after every previously queued operation for `childId`.
+     * @param childId - the durable child whose operations are linearized.
+     * @param operation - the critical section to run in order.
+     * @returns the operation's own settlement.
+     */
+    run(childId, operation) {
+        const previous = this.tails.get(childId) ?? Promise.resolve();
+        const result = previous.then(operation, operation);
+        // Absorb rejections in the chaining tail so one failed critical section
+        // cannot reject an unrelated later caller.
+        const tail = result.then(() => undefined, () => undefined);
+        this.tails.set(childId, tail);
+        void tail.then(() => {
+            if (this.tails.get(childId) === tail)
+                this.tails.delete(childId);
+        });
+        return result;
+    }
+}
+//# sourceMappingURL=activation.js.map

package/lib/types/archive-admission.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The `subagent` family of the Workspace registry's archive admission: which
+ * subagent descendants of a Session are still inside a turn, and how they
+ * stop when the Session is archived with its work. Archived ancestors also
+ * block later model steps, including when their Sessions have been released.
+ *
+ * @module @deepseek-ai/dsh-subagent
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { Session, SessionId } from '@deepseek-ai/dsh-session';
+import type { SubagentIdentityProjection } from './projection-types.ts';
+/**
+ * Answer `workspace/session-activity` with the running subagent descendants of
+ * the asked Session, and `workspace/session-stop` by cancelling each of them
+ * as their parent would. Reject subsequent steps beneath archived ancestors.
+ * All listeners live as long as `ctx`'s fiber.
+ * @param ctx - context carrying the Agent registry.
+ * @param residentAncestors - verified creation ancestors for an exact managed Agent, absent before publication or for unmanaged Agents.
+ * @param identityOf - ready service-owned descriptor identity reader; absent or invalid descriptors yield no identity.
+ */
+export declare function installSubagentArchiveAdmission(ctx: Context, residentAncestors: (agent: Agent) => readonly SessionId[] | undefined, identityOf: (session: Session) => SubagentIdentityProjection | undefined): void;
+//# sourceMappingURL=archive-admission.d.ts.map

package/lib/types/archive-admission.js

@@ -0,0 +1,75 @@
+/**
+ * The `subagent` family of the Workspace registry's archive admission: which
+ * subagent descendants of a Session are still inside a turn, and how they
+ * stop when the Session is archived with its work. Archived ancestors also
+ * block later model steps, including when their Sessions have been released.
+ *
+ * @module @deepseek-ai/dsh-subagent
+ */
+/**
+ * Answer `workspace/session-activity` with the running subagent descendants of
+ * the asked Session, and `workspace/session-stop` by cancelling each of them
+ * as their parent would. Reject subsequent steps beneath archived ancestors.
+ * All listeners live as long as `ctx`'s fiber.
+ * @param ctx - context carrying the Agent registry.
+ * @param residentAncestors - verified creation ancestors for an exact managed Agent, absent before publication or for unmanaged Agents.
+ * @param identityOf - ready service-owned descriptor identity reader; absent or invalid descriptors yield no identity.
+ */
+export function installSubagentArchiveAdmission(ctx, residentAncestors, identityOf) {
+    const ancestorsOf = (agent) => residentAncestors(agent) ?? headerAncestors(ctx, agent);
+    const runningDescendants = (sessionId) => ctx.agents.list()
+        .filter(agent => agent.status === 'running' && ancestorsOf(agent).includes(sessionId));
+    ctx.on('workspace/session-activity', async ({ sessionId }, next) => {
+        const running = runningDescendants(sessionId);
+        const rest = await next();
+        if (running.length === 0)
+            return rest;
+        const own = { kind: 'subagent', items: running.map(child => describe(child, identityOf(child.session))) };
+        return [own, ...rest];
+    });
+    ctx.on('workspace/session-stop', ({ sessionId }) => {
+        for (const child of runningDescendants(sessionId)) {
+            try {
+                child.cancel({ kind: 'parent' });
+            }
+            catch (error) {
+                // One child refusing its cancel must not keep its siblings running for an archived parent.
+                ctx.logger.warn(`subagent: cancelling "${child.id}" for an archived Session failed: ${String(error)}`);
+            }
+        }
+    });
+    ctx.on('agent/pre-step', ({ agent }, next) => {
+        const archived = ctx.get('workspaceRegistry')?.archivedSessionIds;
+        return archived !== undefined && ancestorsOf(agent).some(id => archived.includes(id))
+            ? Promise.resolve({ kind: 'reject' })
+            : next();
+    });
+}
+/**
+ * Header-only ancestry for Agents without a published Activation. Include an
+ * offline direct creator; ordinary forks stop the chain and cycles terminate.
+ */
+function headerAncestors(ctx, agent) {
+    const ancestors = [];
+    const visited = new Set([agent.id]);
+    let header = agent.session.header;
+    while (header.origin === 'subagent' && header.parentSession !== undefined && !visited.has(header.parentSession)) {
+        const parentId = header.parentSession;
+        ancestors.push(parentId);
+        visited.add(parentId);
+        const parent = ctx.agents.get(parentId)?.session;
+        if (parent === undefined)
+            break;
+        header = parent.header;
+    }
+    return ancestors;
+}
+/**
+ * Report the child's current projected label only when its descriptor belongs
+ * to the child's own log; inherited, absent, or invalid identities yield the id alone.
+ */
+function describe(child, identity) {
+    const label = identity !== undefined && child.session.isOwnSeq(identity.seq) ? identity.label : undefined;
+    return label === undefined ? { id: child.id } : { id: child.id, label };
+}
+//# sourceMappingURL=archive-admission.js.map

package/lib/types/assistant-output.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Canonical selection of a child's final assistant output. Backend run results
+ * and `subagent/end.lastAssistantMessage` apply the same rule: select the last
+ * non-empty assistant message. An empty-content message records usage only
+ * when the loop appends it after a max-tokens step with no executable blocks,
+ * so it does not replace earlier output. If no non-empty message exists,
+ * select the accumulated assistant text. Selection is independent of the
+ * run's stop reason.
+ *
+ * @module @deepseek-ai/dsh-subagent/assistant-output
+ */
+import { type ContentBlock } from '@deepseek-ai/dsh-llm';
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+/**
+ * Incremental fold of the selection rule, for backends that observe a child's
+ * output as it streams: session-event backends {@link push} each event, and
+ * transports without session events (ACP content chunks) {@link pushText} raw
+ * text into the same streamed fallback.
+ */
+export declare class AssistantOutputFold {
+    private message;
+    private partial;
+    /**
+     * Fold one session event: a non-empty assistant message becomes the
+     * candidate final answer, while its embedded stream and any log-only attempt
+     * extend the streamed fallback; every other event contributes nothing.
+     * @param event - the next observed session event.
+     */
+    push(event: SessionEvent): void;
+    /**
+     * Extend the streamed fallback with text observed outside session events.
+     * @param text - the next streamed text piece (an empty piece is a no-op).
+     */
+    pushText(text: string): void;
+    /**
+     * Select the final output folded so far.
+     * @returns the last non-empty assistant message, else the accumulated
+     *   streamed text, or `undefined` when the child produced neither.
+     */
+    collect(): readonly ContentBlock[] | undefined;
+}
+/**
+ * Apply the selection rule to one complete child-owned event suffix.
+ * @param events - the child-owned events (after any seed or epoch boundary).
+ * @returns the selected output, or `undefined` when the child produced none.
+ */
+export declare function finalAssistantOutput(events: readonly SessionEvent[]): readonly ContentBlock[] | undefined;
+//# sourceMappingURL=assistant-output.d.ts.map

package/lib/types/assistant-output.js

@@ -0,0 +1,73 @@
+/**
+ * Canonical selection of a child's final assistant output. Backend run results
+ * and `subagent/end.lastAssistantMessage` apply the same rule: select the last
+ * non-empty assistant message. An empty-content message records usage only
+ * when the loop appends it after a max-tokens step with no executable blocks,
+ * so it does not replace earlier output. If no non-empty message exists,
+ * select the accumulated assistant text. Selection is independent of the
+ * run's stop reason.
+ *
+ * @module @deepseek-ai/dsh-subagent/assistant-output
+ */
+import { joinAssistantStreamText } from '@deepseek-ai/dsh-llm';
+/**
+ * Incremental fold of the selection rule, for backends that observe a child's
+ * output as it streams: session-event backends {@link push} each event, and
+ * transports without session events (ACP content chunks) {@link pushText} raw
+ * text into the same streamed fallback.
+ */
+export class AssistantOutputFold {
+    message;
+    partial = [];
+    /**
+     * Fold one session event: a non-empty assistant message becomes the
+     * candidate final answer, while its embedded stream and any log-only attempt
+     * extend the streamed fallback; every other event contributes nothing.
+     * @param event - the next observed session event.
+     */
+    push(event) {
+        if (event.type === 'assistant/message') {
+            const content = event.data.message.content;
+            if (content.length > 0)
+                this.message = content;
+        }
+        if (event.type === 'assistant/message' || event.type === 'assistant/attempt') {
+            this.pushText(joinAssistantStreamText(event.data.stream));
+        }
+    }
+    /**
+     * Extend the streamed fallback with text observed outside session events.
+     * @param text - the next streamed text piece (an empty piece is a no-op).
+     */
+    pushText(text) {
+        if (text.length > 0)
+            this.partial.push(text);
+    }
+    /**
+     * Select the final output folded so far.
+     * @returns the last non-empty assistant message, else the accumulated
+     *   streamed text, or `undefined` when the child produced neither.
+     */
+    collect() {
+        if (this.message !== undefined)
+            return this.message;
+        const text = this.partial.join('');
+        return text.length > 0 ? [{ type: 'text', text }] : undefined;
+    }
+}
+/**
+ * Apply the selection rule to one complete child-owned event suffix.
+ * @param events - the child-owned events (after any seed or epoch boundary).
+ * @returns the selected output, or `undefined` when the child produced none.
+ */
+export function finalAssistantOutput(events) {
+    // TODO: this folds the complete suffix once per run/epoch settlement. If a
+    // long continuable epoch ever profiles hot here, scan backward with early
+    // exit for the last non-empty message and fold text deltas only on the
+    // no-message fallback.
+    const fold = new AssistantOutputFold();
+    for (const event of events)
+        fold.push(event);
+    return fold.collect();
+}
+//# sourceMappingURL=assistant-output.js.map