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

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

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

package/lib/typert.remote-client.js

@@ -0,0 +1,114 @@
+/* Generated by @qlzt/dsh-typert-generator from the Host FaceModel — do not edit. */
+import { z } from 'zod'
+
+let _deepseek_ai_dsh_subagent_subagents_interruptByParent_parameter_0$schema$value
+const _deepseek_ai_dsh_subagent_subagents_interruptByParent_parameter_0$schema = () => (_deepseek_ai_dsh_subagent_subagents_interruptByParent_parameter_0$schema$value ??= z.intersection(z.string(), z.unknown()))
+let _deepseek_ai_dsh_subagent_subagents_interruptByParent_parameter_1$schema$value
+const _deepseek_ai_dsh_subagent_subagents_interruptByParent_parameter_1$schema = () => (_deepseek_ai_dsh_subagent_subagents_interruptByParent_parameter_1$schema$value ??= z.intersection(z.string(), z.unknown()))
+let _deepseek_ai_dsh_subagent_subagents_interruptByParent_parameter_2$schema$value
+const _deepseek_ai_dsh_subagent_subagents_interruptByParent_parameter_2$schema = () => (_deepseek_ai_dsh_subagent_subagents_interruptByParent_parameter_2$schema$value ??= z.literal("continuable"))
+let _deepseek_ai_dsh_subagent_subagents_interruptByParent_result$schema$value
+const _deepseek_ai_dsh_subagent_subagents_interruptByParent_result$schema = () => (_deepseek_ai_dsh_subagent_subagents_interruptByParent_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.intersection(z.string(), z.unknown()).readonly(),
+  'parentSessionId': z.intersection(z.string(), z.unknown()).readonly(),
+  'childSessionId': z.intersection(z.string(), z.unknown()).readonly(),
+  'mode': z.literal("continuable").readonly(),
+  'delivery': z.union([z.literal("queue"), z.literal("steer")]).readonly(),
+  '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(),
+  'clientTimeZone': z.string().readonly().optional(),
+}))
+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.intersection(z.string(), z.unknown()).readonly(),
+}))
+
+export const TYPERT_REMOTE = {
+  package: '@qlzt/dsh-subagent',
+  descriptors: [
+    {
+      id: '@qlzt/dsh-subagent#subagents/interruptByParent',
+      service: 'subagents',
+      namespace: 'subagents',
+      method: 'interruptByParent',
+      invocation: { kind: 'direct' },
+      parameters: [
+        {
+          name: 'childSessionId',
+          wire: 'childSessionId',
+          source: 'json',
+          codec: {
+            mode: 'strict',
+            typeSymbol: '@qlzt/dsh-session/types#SessionId',
+            create: _deepseek_ai_dsh_subagent_subagents_interruptByParent_parameter_0$schema,
+          },
+        },
+        {
+          name: 'parentSessionId',
+          wire: 'parentSessionId',
+          source: 'json',
+          codec: {
+            mode: 'strict',
+            typeSymbol: '@qlzt/dsh-session/types#SessionId',
+            create: _deepseek_ai_dsh_subagent_subagents_interruptByParent_parameter_1$schema,
+          },
+        },
+        {
+          name: 'mode',
+          wire: 'mode',
+          source: 'json',
+          codec: {
+            mode: 'strict',
+            typeSymbol: '@qlzt/dsh-subagent#subagents/interruptByParent:mode',
+            create: _deepseek_ai_dsh_subagent_subagents_interruptByParent_parameter_2$schema,
+          },
+        },
+      ],
+      result: {
+        mode: 'strict',
+        typeSymbol: '@qlzt/dsh-subagent/client#SubagentInterruptReceipt',
+        create: _deepseek_ai_dsh_subagent_subagents_interruptByParent_result$schema,
+      },
+      sourceLocation: {"file":"packages/subagent/subagent/src/index.ts","line":513,"column":3},
+    },
+    {
+      id: '@qlzt/dsh-subagent#subagents/prompt',
+      service: 'subagents',
+      namespace: 'subagents',
+      method: 'prompt',
+      invocation: { kind: 'direct' },
+      parameters: [
+        {
+          name: 'request',
+          wire: 'request',
+          source: 'json',
+          codec: {
+            mode: 'strict',
+            typeSymbol: '@qlzt/dsh-subagent/client#SubagentPromptRequest',
+            create: _deepseek_ai_dsh_subagent_subagents_prompt_parameter_0$schema,
+          },
+        },
+      ],
+      cancellation: { parameter: 'signal' },
+      result: {
+        mode: 'strict',
+        typeSymbol: '@qlzt/dsh-subagent/client#SubagentPromptReceipt',
+        create: _deepseek_ai_dsh_subagent_subagents_prompt_result$schema,
+      },
+      sourceLocation: {"file":"packages/subagent/subagent/src/index.ts","line":446,"column":9},
+    },
+  ],
+}
+
+export default TYPERT_REMOTE

package/lib/types/activation.d.ts

@@ -0,0 +1,114 @@
+/** Execution-period records, capacity slots, child serialization, and local output capture.
+ * @module @qlzt/dsh-subagent/activation
+ */
+import type { Agent, AgentHandle } from '@qlzt/dsh-agent';
+import type { SessionId, SessionLogOffset } from '@qlzt/dsh-session';
+import type { ActivationObserver } from './lifecycle.ts';
+import type { StructuredAttachment } from './structured.ts';
+import type { SubagentResult, SubagentRun } from './types.ts';
+/** Process-local slots shared through uninterrupted continuable parent links. */
+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 {
+    /** Shared capacity for this Activation and all its managed descendants. */
+    readonly pool: ActivationPool;
+    /** 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;
+    readonly parent: Agent;
+    readonly delivery: 'parent' | 'caller';
+    readonly result: PromiseWithResolvers<SubagentResult>;
+    /** Published synchronously before teardown; subsequent callers share this transaction. */
+    closing: Promise<void> | undefined;
+    /**
+     * Exact live Agent ancestry observed when this Activation materialized.
+     * Weak membership preserves host-scope identity across an intermediate
+     * ancestor leaving the registry without retaining that ancestor's runtime.
+     */
+    readonly ancestry: WeakSet<Agent>;
+    /**
+     * Session ids of the child Activations this one owns. Because one Session has
+     * at most one live Activation, the id identifies the live child without
+     * another runtime-incarnation reference. Non-empty blocks settlement.
+     */
+    readonly ownedChildren: Set<SessionId>;
+    /** The lifecycle observer that emits this epoch's start and terminal edges. */
+    readonly observer: ActivationObserver;
+    /**
+     * Whether any delivery to this child was ever accepted. A materialization
+     * rolled back before its first acceptance is a child the caller was told does
+     * not exist, so its teardown owes the parent no settlement account.
+     */
+    announced: 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 or owned children. */
+    poke: PromiseWithResolvers<void>;
+} | {
+    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 @qlzt/dsh-subagent/activation
+ */
+import { assertNever } from '@qlzt/dsh-util-values';
+import { finalAssistantOutput } from "./assistant-output.js";
+import { epochStopReason } from "./lifecycle.js";
+import { SubagentError } from "./error.js";
+/** Process-local slots shared through uninterrupted continuable parent links. */
+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,16 @@
+/**
+ * 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.
+ *
+ * @module @qlzt/dsh-subagent
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/**
+ * 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. Both listeners live as long as `ctx`'s fiber.
+ * @param ctx - context carrying the Agent registry; the Session query service is optional and only supplies labels.
+ */
+export declare function installSubagentArchiveAdmission(ctx: Context): void;
+//# sourceMappingURL=archive-admission.d.ts.map

package/lib/types/archive-admission.js

@@ -0,0 +1,151 @@
+/**
+ * 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.
+ *
+ * @module @qlzt/dsh-subagent
+ */
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { foldSubagentDescriptor } from "./descriptor.js";
+/**
+ * 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. Both listeners live as long as `ctx`'s fiber.
+ * @param ctx - context carrying the Agent registry; the Session query service is optional and only supplies labels.
+ */
+export function installSubagentArchiveAdmission(ctx) {
+    ctx.on('workspace/session-activity', async ({ sessionId }, next) => {
+        const running = runningDescendants(ctx, sessionId);
+        const rest = await next();
+        if (running.length === 0)
+            return rest;
+        const own = { kind: 'subagent', items: await Promise.all(running.map(child => describe(ctx, child))) };
+        return [own, ...rest];
+    });
+    ctx.on('workspace/session-stop', ({ sessionId }) => {
+        for (const child of runningDescendants(ctx, 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)}`);
+            }
+        }
+    });
+}
+/**
+ * Live subagent descendants inside a turn, by durable lineage: a child whose
+ * header names its parent and carries the subagent origin this package
+ * records, at any depth. A fork shares the lineage field without the origin
+ * and is an independent conversation, so it never holds its source. Lineage
+ * is read as data, so a damaged header chain that loops is visited once.
+ */
+function runningDescendants(ctx, rootId) {
+    const childrenOf = new Map();
+    for (const agent of ctx.agents.list()) {
+        const { parentSession, origin } = agent.session.header;
+        if (parentSession === undefined || origin !== 'subagent')
+            continue;
+        const siblings = childrenOf.get(parentSession) ?? [];
+        siblings.push(agent);
+        childrenOf.set(parentSession, siblings);
+    }
+    const running = [];
+    const pending = [rootId];
+    const visited = new Set();
+    while (pending.length > 0) {
+        const parentId = pending.shift();
+        if (visited.has(parentId))
+            continue;
+        visited.add(parentId);
+        for (const child of childrenOf.get(parentId) ?? []) {
+            if (child.status === 'running')
+                running.push(child);
+            pending.push(child.id);
+        }
+    }
+    return running;
+}
+/**
+ * The child's activity item: its id, plus the durable creation label its
+ * descriptor carries, read through a live Session observation. Without the
+ * Session query service, or with a descriptor that is absent or unreadable,
+ * the item names the child by id alone.
+ */
+async function describe(ctx, child) {
+    const query = ctx.get('sessionQuery');
+    if (query === undefined)
+        return { id: child.id };
+    try {
+        const env_1 = { stack: [], error: void 0, hasError: false };
+        try {
+            const observation = __addDisposableResource(env_1, await query.observeSession(child.id, { projectionMode: 'none' }), false);
+            const label = foldSubagentDescriptor(observation.events.slice(observation.inheritedEventCount))?.label;
+            return label === undefined ? { id: child.id } : { id: child.id, label };
+        }
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
+        }
+        finally {
+            __disposeResources(env_1);
+        }
+    }
+    catch {
+        // A damaged descriptor is data damage in the child; the report still names the child.
+        return { id: child.id };
+    }
+}
+//# 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 @qlzt/dsh-subagent/assistant-output
+ */
+import { type ContentBlock } from '@qlzt/dsh-llm';
+import type { SessionEvent } from '@qlzt/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 @qlzt/dsh-subagent/assistant-output
+ */
+import { joinAssistantStreamText } from '@qlzt/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