@deepseek-ai/dsh-subagent 0.1.6-alpha.2 → 0.1.7-alpha.2

package/lib/types/catalog.d.ts

@@ -7,24 +7,31 @@ import { z } from 'zod';
 import type { ChunkedList } from '@deepseek-ai/dsh-chunked-list';
 import type { Session, SessionEvent, SessionHeader, SessionId, SessionLogOffset } from '@deepseek-ai/dsh-session';
 import type { SubagentCatalogEntry } from './projection-types.ts';
-/** Current payload version for `subagent/catalog` events. */
+/** Catalog payload version emitted by live child creation. */
 export declare const SUBAGENT_CATALOG_VERSION = 0;
-/** One complete parent-owned catalog fact. */
-export type SubagentCatalogEvent = {
-    readonly version: 0;
-    readonly childId: SessionId;
-    readonly childCreatedAt: number;
-} & ({
+type KnownCatalogMode = {
     readonly mode: 'one-shot';
     readonly label?: string;
 } | {
     readonly mode: 'continuable';
     readonly label: string;
-});
+};
+/** Parent catalog v0 records known modes; v1 also retains children with unknown mode. */
+export type SubagentCatalogEvent = {
+    readonly childId: SessionId;
+    readonly childCreatedAt: number;
+} & (({
+    readonly version: 0;
+} & KnownCatalogMode) | ({
+    readonly version: 1;
+} & (KnownCatalogMode | {
+    readonly mode: 'unknown';
+    readonly label?: string;
+})));
 declare module '@deepseek-ai/dsh-session/types' {
     interface SessionEventMap {
         /**
-         * A direct child's complete discovery fact.
+         * A direct child's identity and available discovery fields.
          * @param data - versioned parent-owned catalog entry.
          */
         'subagent/catalog': SubagentCatalogEvent;
@@ -41,7 +48,7 @@ declare module '@deepseek-ai/dsh-session-projection/types' {
     }
 }
 /**
- * Materialize direct children from their parent's successful creation facts.
+ * Materialize complete and unknown-mode child identities from parent catalog events.
  * @param state - parent catalog fold state.
  * @returns current direct-child rows in parent catalog event order.
  */

package/lib/types/catalog.js

@@ -5,26 +5,28 @@
  */
 import { z } from 'zod';
 import { appendChunkedList, chunkedListSchema, iterateChunkedList } from '@deepseek-ai/dsh-chunked-list';
-/** Current payload version for `subagent/catalog` events. */
+/** Catalog payload version emitted by live child creation. */
 export const SUBAGENT_CATALOG_VERSION = 0;
 const sessionIdSchema = z.string();
 const oneShotCatalogSchema = z.object({
-    version: z.literal(SUBAGENT_CATALOG_VERSION),
+    version: z.union([z.literal(0), z.literal(1)]),
     childId: sessionIdSchema,
     childCreatedAt: z.number().int().nonnegative(),
     mode: z.literal('one-shot'),
     label: z.string().optional(),
 }).strict();
 const continuableCatalogSchema = z.object({
-    version: z.literal(SUBAGENT_CATALOG_VERSION),
+    version: z.union([z.literal(0), z.literal(1)]),
     childId: sessionIdSchema,
     childCreatedAt: z.number().int().nonnegative(),
     mode: z.literal('continuable'),
     label: z.string(),
 }).strict();
+const unknownCatalogSchema = oneShotCatalogSchema.extend({ version: z.literal(1), mode: z.literal('unknown') });
 const eventDataSchema = z.union([
     oneShotCatalogSchema,
     continuableCatalogSchema,
+    unknownCatalogSchema,
 ]);
 const viewSchema = z.array(z.union([
     oneShotCatalogSchema.omit({ version: true, childId: true, childCreatedAt: true }).extend({
@@ -35,20 +37,24 @@ const viewSchema = z.array(z.union([
         id: sessionIdSchema,
         createdAt: continuableCatalogSchema.shape.childCreatedAt,
     }),
+    unknownCatalogSchema.omit({ version: true, childId: true, childCreatedAt: true }).extend({
+        id: sessionIdSchema,
+        createdAt: unknownCatalogSchema.shape.childCreatedAt,
+    }),
 ]));
 const stateSchema = z.object({
     inheritedEventCount: z.number().int().nonnegative(),
     head: chunkedListSchema(eventDataSchema).optional(),
 }).strict();
 /**
- * Materialize direct children from their parent's successful creation facts.
+ * Materialize complete and unknown-mode child identities from parent catalog events.
  * @param state - parent catalog fold state.
  * @returns current direct-child rows in parent catalog event order.
  */
 function subagentCatalogEntries(state) {
     const entries = [];
     for (const data of iterateChunkedList(state.head)) {
-        entries.push(data.mode === 'one-shot'
+        entries.push(data.mode !== 'continuable'
             ? {
                 id: data.childId,
                 createdAt: data.childCreatedAt,
@@ -74,7 +80,7 @@ export const subagentCatalogProjectionDefinition = {
             return state;
         return { ...state, head: appendChunkedList(state.head, eventDataSchema.parse(event.data)) };
     },
-    stateVersion: 2,
+    stateVersion: 3,
     wire: { viewSchema, view: subagentCatalogEntries },
 };
 /**

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

@@ -1,7 +1,6 @@
 /**
- * Client-safe subagent catalog and control vocabulary: the durable direct-child
- * row both the listing and the browser catalog answer with, plus the
- * browser-facing control surface's prompt, receipts, and failures.
+ * Client-safe complete-descendant rows and browser continuation requests,
+ * receipts, and failures.
  *
  * @module @deepseek-ai/dsh-subagent/control-types
  */
@@ -17,42 +16,35 @@ import type { SessionId } from '@deepseek-ai/dsh-session/types';
  * rather than imported.
  */
 export type SubagentPromptRequestId = Branded<'session-request-id'>;
-/**
- * One durable direct-child row, ordered by header `createdAt` with ties broken
- * on id. Only a candidate whose durable header has `origin: 'subagent'` is
- * interpreted. A served `subagent` projection value produces a `child`; a
- * settled candidate whose fold served no identity produces a `diagnostic`; a
- * running candidate without one is omitted — its descriptor may not be
- * appended yet (the creation window). Diagnostics relay the projection fold's
- * outcome or a failed read, never a per-child event scan, and never expose
- * model-hidden descriptor content.
- */
-export type SubagentListEntry = {
-    readonly kind: 'child';
+/** Shared child fields for complete-descendant listing. */
+export type SubagentCatalogRow = {
     /** The durable child session id, stable across Activations. */
     readonly id: SessionId;
     /**
-     * Whether the child is live at the moment its reader sampled it: the
-     * durable listing reads the Session store (`running` means the logical
-     * record is resident, `inactive` that it exists only in persistence),
-     * while the browser catalog re-samples the child's Agent driver. Neither
-     * encodes a durable outcome, and a continuable child may still reject
-     * delivery as an ownership conflict.
+     * Whether complete-descendant listing observed a resident Session. This
+     * does not encode a durable outcome or guarantee continuation delivery.
      */
     readonly activity: 'running' | 'inactive';
-    /** Whether a direct descendant has durable `origin: 'subagent'`. */
-    readonly hasChildren: boolean;
 } & ({
     /** A terminal one-shot child. */
     readonly mode: 'one-shot';
-    /** Optional durable creation label from the child's descriptor. */
+    /** Optional durable creation label from the owning catalog or child descriptor. */
     readonly label?: string;
 } | {
     /** A resumable conversation. */
     readonly mode: 'continuable';
-    /** Durable creation label from the child's descriptor. */
+    /** Durable creation label from the owning catalog or child descriptor. */
     readonly label: string;
-}) | {
+});
+/**
+ * One complete-descendant row. Enumeration may also return diagnostics for
+ * child identity observations from the complete Session corpus.
+ */
+export type SubagentListEntry = SubagentCatalogRow & {
+    readonly kind: 'child';
+    /** Whether complete-corpus enumeration observed a direct child. */
+    readonly hasChildren: boolean;
+} | {
     readonly kind: 'diagnostic';
     /** The candidate's session id. */
     readonly id: SessionId;
@@ -68,12 +60,7 @@ export type SubagentListEntry = {
      */
     readonly reason: 'corrupt' | 'unsupported' | 'unavailable';
 };
-/** Complete direct-child catalog plus the delivery-time parent availability hint. */
-export interface SubagentCatalog {
-    readonly entries: readonly SubagentListEntry[];
-    readonly parentAvailable: boolean;
-}
-/** Durable parent/child address that selects subagent transport in the client. */
+/** Durable parent/child browsing address; unknown mode is resolved when child history is read. */
 export type SubagentAddress = {
     readonly parentSessionId: SessionId;
     readonly childSessionId: SessionId;
@@ -81,6 +68,8 @@ export type SubagentAddress = {
     readonly mode: 'one-shot';
 } | {
     readonly mode: 'continuable';
+} | {
+    readonly mode: 'unknown';
 });
 /** One human message addressed to a continuable direct child. */
 export interface SubagentPromptRequest {
@@ -110,9 +99,15 @@ export interface SubagentInterruptReceipt {
     readonly accepted: true;
 }
 /**
- * Failure details the control surface answers with. Catalog reads, prompts,
- * and interrupts share this vocabulary with the Client Remote result.
+ * Failure details the control surface answers with. Prompts and interrupts
+ * share these failures with the Client Remote result.
  */
+declare module '@deepseek-ai/dsh-workspace/types' {
+    interface SessionActivityKindMap {
+        /** A subagent session delegated from this session (at any depth) is inside a turn. */
+        subagent: true;
+    }
+}
 declare module '@deepseek-ai/dsh-typert-protocol' {
     interface RemoteErrorDetailsMap {
         /** A browser-supplied zone is neither UTC nor a canonical IANA name. */
@@ -139,8 +134,6 @@ declare module '@deepseek-ai/dsh-typert-protocol' {
         'subagent/delivery-unavailable': {
             readonly childSessionId: SessionId;
         };
-        /** The deployment mounts no session-projection registry. */
-        'subagent/projections-unavailable': {};
     }
 }
 //# sourceMappingURL=control-types.d.ts.map

package/lib/types/control-types.js

@@ -1,7 +1,6 @@
 /**
- * Client-safe subagent catalog and control vocabulary: the durable direct-child
- * row both the listing and the browser catalog answer with, plus the
- * browser-facing control surface's prompt, receipts, and failures.
+ * Client-safe complete-descendant rows and browser continuation requests,
+ * receipts, and failures.
  *
  * @module @deepseek-ai/dsh-subagent/control-types
  */

package/lib/types/control.d.ts

@@ -1,18 +1,12 @@
 /**
- * Browser-facing subagent control assembly: the catalog view sampled against
- * the live Agent registry, one browser zone's validation, and the stable
- * failure codes the Remote surface answers with.
+ * Browser-facing subagent prompt and interrupt request validation plus the
+ * stable prompt failure codes returned by the Remote surface.
  *
  * @module @deepseek-ai/dsh-subagent
  */
-import type { Context } from '@deepseek-ai/cordis';
 import type { SessionId } from '@deepseek-ai/dsh-session';
 import { z } from 'zod';
-import type { SubagentCatalog, SubagentListEntry } from './control-types.ts';
 declare const CONTROL_ID_SCHEMAS: {
-    readonly 'subagent.list': z.ZodObject<{
-        parentSessionId: z.ZodString;
-    }, z.core.$strip>;
     readonly 'subagent.prompt': z.ZodObject<{
         parentSessionId: z.ZodString;
         childSessionId: z.ZodString;
@@ -36,26 +30,6 @@ declare const CONTROL_ID_SCHEMAS: {
  * @throws {RemoteError} `gateway/bad-request` with the original Zod issues.
  */
 export declare function validateControlRequest(method: keyof typeof CONTROL_ID_SCHEMAS, payload: unknown): void;
-/**
- * Project one durable listing onto the catalog view, replacing each row's
- * store-derived activity with the live Agent driver's status and reporting
- * whether the exact parent Agent is live. Without an Agent registry no driver
- * runs at all, so every row is inactive and the parent is unavailable.
- * @param ctx - Host context that may carry the Agent registry.
- * @param parentSessionId - the listed parent.
- * @param entries - the durable direct-child listing.
- * @returns the catalog view answered to one browser.
- */
-export declare function catalogView(ctx: Context, parentSessionId: SessionId, entries: readonly SubagentListEntry[]): SubagentCatalog;
-/**
- * Refuse one catalog read while preserving cancellation and a missing
- * projections registry as distinct failures.
- * @param error - the thrown value.
- * @param signal - the caller's cancellation.
- * @returns Never — the refusal is thrown.
- * @throws {RemoteError} always.
- */
-export declare function rejectCatalogRead(error: unknown, signal: AbortSignal): never;
 /**
  * Refuse one continuation prompt without exposing provider detail: admission
  * failures the caller can act on keep their own code, everything else is

package/lib/types/control.js

@@ -1,7 +1,6 @@
 /**
- * Browser-facing subagent control assembly: the catalog view sampled against
- * the live Agent registry, one browser zone's validation, and the stable
- * failure codes the Remote surface answers with.
+ * Browser-facing subagent prompt and interrupt request validation plus the
+ * stable prompt failure codes returned by the Remote surface.
  *
  * @module @deepseek-ai/dsh-subagent
  */
@@ -11,7 +10,6 @@ import { z } from 'zod';
 import { SubagentError } from "./error.js";
 const SESSION_ID_SCHEMA = z.string().min(1);
 const CONTROL_ID_SCHEMAS = {
-    'subagent.list': z.object({ parentSessionId: SESSION_ID_SCHEMA }),
     'subagent.prompt': z.object({
         parentSessionId: SESSION_ID_SCHEMA,
         childSessionId: SESSION_ID_SCHEMA,
@@ -37,42 +35,6 @@ export function validateControlRequest(method, payload) {
         throw new RemoteError('gateway/bad-request', `invalid payload for ${method}`, { issues: parsed.error.issues });
     }
 }
-/**
- * Project one durable listing onto the catalog view, replacing each row's
- * store-derived activity with the live Agent driver's status and reporting
- * whether the exact parent Agent is live. Without an Agent registry no driver
- * runs at all, so every row is inactive and the parent is unavailable.
- * @param ctx - Host context that may carry the Agent registry.
- * @param parentSessionId - the listed parent.
- * @param entries - the durable direct-child listing.
- * @returns the catalog view answered to one browser.
- */
-export function catalogView(ctx, parentSessionId, entries) {
-    const agents = ctx.get('agents');
-    return {
-        entries: entries.map((entry) => entry.kind === 'child'
-            ? { ...entry, activity: agents?.get(entry.id)?.status === 'running' ? 'running' : 'inactive' }
-            : entry),
-        parentAvailable: agents?.get(parentSessionId) !== undefined,
-    };
-}
-/**
- * Refuse one catalog read while preserving cancellation and a missing
- * projections registry as distinct failures.
- * @param error - the thrown value.
- * @param signal - the caller's cancellation.
- * @returns Never — the refusal is thrown.
- * @throws {RemoteError} always.
- */
-export function rejectCatalogRead(error, signal) {
-    if (isCancellation(error, signal)) {
-        throw new RemoteError('gateway/cancelled', 'subagent catalog read was cancelled', {}, { cause: error });
-    }
-    if (error instanceof SubagentError && error.code === 'SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE') {
-        throw new RemoteError('subagent/projections-unavailable', 'subagent catalog is unavailable: this deployment does not mount the sessionProjections registry (load @deepseek-ai/dsh-session-projection)', {}, { cause: error });
-    }
-    throw new RemoteError('gateway/internal', 'subagent catalog read failed', {}, { cause: error });
-}
 /**
  * Refuse one continuation prompt without exposing provider detail: admission
  * failures the caller can act on keep their own code, everything else is

package/lib/types/index.d.ts

@@ -17,9 +17,9 @@
  * is resident. Continuable children never become a {@link SubagentRun}: the
  * continuation manager holds their `AgentHandle` directly and orders every turn
  * through the child's own inbox, so providers contribute only the detached
- * creation spec and see no handle, turn, or teardown. Child and descendant
- * discovery read the live session store and optional session persistence
- * directly and do not require that continuation runtime.
+ * creation spec and see no handle, turn, or teardown. Direct-child
+ * discovery uses the parent catalog; descendant discovery uses the Session
+ * corpus. Neither read requires the continuation runtime.
  *
  * Same-process providers are trusted typed collaborators. Requests, provider
  * descriptors, results, and lifecycle payloads are borrowed immutable values;
@@ -28,6 +28,7 @@
  *
  * @module @deepseek-ai/dsh-subagent
  */
+import type { Volatile } from '@deepseek-ai/cordis';
 import { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
 import type { Scoped } from '@deepseek-ai/dsh-scope';
@@ -35,9 +36,10 @@ import type { ContentBlock, MessageId } from '@deepseek-ai/dsh-llm';
 import type { Agent } from '@deepseek-ai/dsh-agent';
 import type { SessionId } from '@deepseek-ai/dsh-session';
 import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
-import type { SubagentCatalog, SubagentInterruptReceipt, SubagentPromptReceipt, SubagentPromptRequest } from './control-types.ts';
+import type { SubagentInterruptReceipt, SubagentPromptReceipt, SubagentPromptRequest } from './control-types.ts';
 import type { ContinuableStart, ContinuableStartSpec, SubagentInterruptAuthority, SubagentProvider, SubagentRun, SubagentRunEndInfo, SubagentRunInfo, SubagentSendMessageOptions, SubagentStartRequest } from './types.ts';
-import type { SubagentDescendantListEntry, SubagentListEntry } from './list-children.ts';
+import type { SubagentDescendantListEntry } from './list-children.ts';
+import type { SubagentCatalogEntry } from './projection-types.ts';
 import { deliverSubagentPrompt } from './internal.ts';
 export type {} from './catalog.ts';
 export * from './out-of-process.ts';
@@ -46,6 +48,7 @@ export { SubagentRunId } from './types.ts';
 export type { ContinuableCreateRequest, ContinuableCreateSpec, ContinuableStart, ContinuableStartSpec, ResolvedSubagentStartRequest, SubagentCapabilities, SubagentInterruptAuthority, SubagentProvider, SubagentResult, SubagentRun, SubagentSendMessageOptions, SubagentStartRequest, SubagentStopReason, SubagentStopReasonMap, } from './types.ts';
 export { foldSubagentDescriptor, snapshotSubagentDescriptor, SUBAGENT_DESCRIPTOR_VERSION, } from './descriptor.ts';
 export type { ContinuableSubagentDescriptorData, ContinuableSubagentDescriptorInput, OneShotSubagentDescriptorData, OneShotSubagentDescriptorInput, SubagentDescriptorData, SubagentDescriptorInput, } from './descriptor.ts';
+export type { SubagentCatalogEntry } from './projection-types.ts';
 export { SubagentError } from './error.ts';
 export { settleRun } from './run-settlement.ts';
 export { assertSubagentMaxDepth, delegationDepthOf } from './depth.ts';
@@ -98,14 +101,20 @@ declare module '@deepseek-ai/cordis' {
 /** Host configuration for continuable subagent capacity. */
 export interface Config {
     /** Maximum live children sharing uninterrupted continuable parent links; defaults to 8. */
-    maxActiveSubagents?: number;
+    maxActiveSubagents: Volatile<number>;
     /** Default delegation depth for tools without an explicit limit; defaults to 1. */
-    maxDepth?: number;
+    maxDepth: Volatile<number>;
 }
 /** Named provider registry with one-shot runs, durable discovery, and continuable-child operations. */
 export declare class SubagentRuntime extends TypertRemoteService {
-    static Config: z<Config>;
-    private settingsSource;
+    private config;
+    static Config: z<Schemastery.ObjectS<NoInfer<{
+        maxDepth: z<number, number, "volatile-defined">;
+        maxActiveSubagents: z<number, number, "volatile-defined">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        maxDepth: z<number, number, "volatile-defined">;
+        maxActiveSubagents: z<number, number, "volatile-defined">;
+    }>>, "plain">;
     private providers;
     private continuations;
     /**
@@ -198,53 +207,31 @@ export declare class SubagentRuntime extends TypertRemoteService {
      */
     drainContinuableChildren(parent: Agent, childIds: readonly SessionId[]): Promise<void>;
     /**
-     * Enumerate the parent's direct session-backed subagents without loading or
-     * resuming an Agent. The Session query service supplies one live-preferred
-     * corpus and shared point observations; the projection cache supplies
-     * immutable descriptor hits without opening cold logs. The registered
-     * `subagent` projection remains the sole mode/label classifier.
-     *
-     * Every query receives `signal`, and the listing rechecks cancellation
-     * around each await. Read rejections that settle
-     * after an abort become a stable `SubagentError` with code `CANCELLED`.
-     * @param parentSessionId - parent session whose direct children are listed.
-     * @param signal - caller-owned cancellation forwarded to Session queries
-     *   and observed around every read await.
-     * @returns children and per-child diagnostics ordered by `createdAt`, then id.
-     * @throws {@link SubagentError} when the projection registry or the session
-     *   store is not mounted, or the caller cancels the listing.
+     * Read the parent's durable direct-child catalog without loading or resuming an Agent.
+     * The service owns and releases the live-preferred Session observation.
+     * @param parentSessionId - parent whose direct children are requested.
+     * @param signal - cancellation forwarded to the Session query.
+     * @returns catalog children in parent event order.
+     * @throws {@link SubagentError} when query or catalog projection is unavailable.
+     * @throws SessionQueryError when the parent cannot be read or the query is cancelled.
      */
-    listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentListEntry[]>;
+    listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentCatalogEntry[]>;
     /**
      * Enumerate the root's complete session-backed subagent tree in stable
      * pre-order from one live-preferred corpus, without loading or resuming an
      * Agent. Ordinary sessions and one-shot children remain traversal nodes so
      * continuable descendants below them are discovered; each returned entry
      * adds its durable `parentId` and root-relative `depth`. Identity resolution,
-     * diagnostics, optional persistence, and cancellation follow the same
-     * projection-backed contract as {@link listChildren}.
+     * diagnostics, optional persistence, and cancellation use the registered
+     * child identity projection and complete Session corpus.
      * @param rootSessionId - session whose complete descendant tree is listed.
      * @param signal - caller-owned cancellation forwarded to persistence reads
      *   and observed around every read await.
      * @returns children and per-candidate diagnostics with tree position, in
      *   stable pre-order.
-     * @throws {@link SubagentError} under the same conditions as {@link listChildren}.
+     * @throws {@link SubagentError} when listing dependencies are unavailable or the caller cancels.
      */
     listDescendants(rootSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDescendantListEntry[]>;
-    /**
-     * Remote face of {@link listChildren} for one browser: the durable listing
-     * plus live Agent activity and the delivery-time parent availability hint.
-     * Parent availability is a hint; {@link prompt} performs the authoritative
-     * check. Named apart from the provider-name {@link list}, which owns the
-     * member.
-     * @param parentSessionId - parent session whose direct children are listed.
-     * @param signal - carrier cancellation forwarded to Session queries.
-     * @returns the catalog view for that parent.
-     * @throws {RemoteError} `gateway/bad-request` for an empty parent id,
-     *   `gateway/cancelled` for an aborted read, `subagent/projections-unavailable` when
-     *   the deployment has no projection registry, otherwise `gateway/internal`.
-     */
-    remoteExportList(parentSessionId: SessionId, signal: AbortSignal): Promise<SubagentCatalog>;
     /**
      * Deliver one browser-authored message to a continuable child through the
      * exact live direct parent, retaining the caller-minted request identity and