@xneog/dsh-subagent 0.1.0 → 0.1.3-alpha.1

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

@@ -0,0 +1,144 @@
+/**
+ * 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.
+ *
+ * @module @xneog/dsh-subagent/control-types
+ */
+import type { PromptContentPart } from '@xneog/dsh-attachment/types';
+import type { Branded } from '@xneog/dsh-brand';
+import type { MessageId } from '@xneog/dsh-llm/brand';
+import type { SessionId } from '@xneog/dsh-session/types';
+/**
+ * Client-minted identity of one browser prompt, persisted on the exact accepted
+ * message. It carries the Session Controller's `session-request-id` brand so a
+ * subagent prompt and an ordinary Session prompt share one identity
+ * vocabulary; that package depends on this one, so the brand is spelled here
+ * 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';
+    /** 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.
+     */
+    readonly activity: 'running' | 'inactive';
+    /** Whether a direct descendant has durable `origin: 'subagent'`. */
+    readonly hasChildren: boolean;
+} & ({
+    /** A terminal one-shot child. */
+    readonly mode: 'one-shot';
+    /** Optional durable creation label from the child's descriptor. */
+    readonly label?: string;
+} | {
+    /** A resumable conversation. */
+    readonly mode: 'continuable';
+    /** Durable creation label from the child's descriptor. */
+    readonly label: string;
+}) | {
+    readonly kind: 'diagnostic';
+    /** The candidate's session id. */
+    readonly id: SessionId;
+    /**
+     * Why the candidate has no `child` row: `corrupt` for a settled candidate
+     * whose projection fold served no identity (a missing, malformed, or
+     * unrecognized-version descriptor — deliberately undistinguished), and
+     * for any candidate whose log makes a registered unit's fold or schema
+     * throw (deterministic data damage, contained per child); `unavailable`
+     * when the candidate's Session observation was absent or transiently
+     * unreadable (retried on the next listing). `unsupported` is never produced; it remains in the
+     * union for consumers that route on it.
+     */
+    readonly reason: 'corrupt' | 'unsupported' | 'unavailable';
+};
+/** 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. */
+export type SubagentAddress = {
+    readonly parentSessionId: SessionId;
+    readonly childSessionId: SessionId;
+} & ({
+    readonly mode: 'one-shot';
+} | {
+    readonly mode: 'continuable';
+});
+/** One human message addressed to a continuable direct child. */
+export interface SubagentPromptRequest {
+    /** Identity persisted on the accepted message, minted before the call. */
+    readonly requestId: SubagentPromptRequestId;
+    readonly parentSessionId: SessionId;
+    readonly childSessionId: SessionId;
+    /** Required discriminator retained from the browser control address. */
+    readonly mode: 'continuable';
+    /**
+     * 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.
+     */
+    readonly content: readonly PromptContentPart[];
+    /** Optional browser zone sampled for this exact human prompt. */
+    readonly clientTimeZone?: string;
+}
+/** Inbox identity returned once the continuation accepts one human message. */
+export interface SubagentPromptReceipt {
+    readonly messageId: MessageId;
+}
+/** Uniform acknowledgement that one interrupt request was admitted. */
+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.
+ */
+declare module '@xneog/dsh-typert-protocol' {
+    interface RemoteErrorDetailsMap {
+        /** A browser-supplied zone is neither UTC nor a canonical IANA name. */
+        'subagent/invalid-time-zone': {
+            readonly value: string;
+        };
+        /** No live Agent carries the addressed parent session. */
+        'subagent/parent-unavailable': {
+            readonly parentSessionId: SessionId;
+        };
+        /** The addressed child cannot take a continuation. */
+        'subagent/not-resumable': {
+            readonly childSessionId: SessionId;
+        };
+        /** The claimed parent does not own the addressed child. */
+        'subagent/unauthorized': {
+            readonly childSessionId: SessionId;
+        };
+        /** Image admission or model image-capability refusal. */
+        'subagent/attachment-invalid': {
+            readonly reason: string;
+        };
+        /** The child exists but its inbox cannot admit the message now. */
+        '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

@@ -0,0 +1,9 @@
+/**
+ * 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.
+ *
+ * @module @xneog/dsh-subagent/control-types
+ */
+export {};
+//# sourceMappingURL=control-types.js.map

package/lib/types/control.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 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.
+ *
+ * @module @xneog/dsh-subagent
+ */
+import type { Context } from '@xneog/cordis';
+import type { SessionId } from '@xneog/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;
+        mode: z.ZodLiteral<"continuable">;
+    }, z.core.$strip>;
+    readonly 'subagent.interrupt': z.ZodObject<{
+        parentSessionId: z.ZodString;
+        childSessionId: z.ZodString;
+        mode: z.ZodLiteral<"continuable">;
+    }, z.core.$strip>;
+};
+/**
+ * Apply the subagent payload checks that are stricter than generated
+ * branded-string codecs.
+ * @param method - method name carried in the failure message.
+ * @param payload - decoded control fields to validate.
+ * @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
+ * internal.
+ * @param error - the thrown value.
+ * @param childSessionId - the addressed child.
+ * @param signal - the caller's cancellation.
+ * @returns Never — the refusal is thrown.
+ * @throws {RemoteError} always.
+ */
+export declare function rejectPrompt(error: unknown, childSessionId: SessionId, signal: AbortSignal): never;
+export {};
+//# sourceMappingURL=control.d.ts.map

package/lib/types/control.js

@@ -0,0 +1,115 @@
+/**
+ * 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.
+ *
+ * @module @xneog/dsh-subagent
+ */
+import { AttachmentError } from '@xneog/dsh-attachment';
+import { RemoteError } from '@xneog/dsh-typert-protocol';
+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,
+        mode: z.literal('continuable'),
+    }),
+    'subagent.interrupt': z.object({
+        parentSessionId: SESSION_ID_SCHEMA,
+        childSessionId: SESSION_ID_SCHEMA,
+        mode: z.literal('continuable'),
+    }),
+};
+/**
+ * Apply the subagent payload checks that are stricter than generated
+ * branded-string codecs.
+ * @param method - method name carried in the failure message.
+ * @param payload - decoded control fields to validate.
+ * @throws {RemoteError} `gateway/bad-request` with the original Zod issues.
+ */
+export function validateControlRequest(method, payload) {
+    const parsed = CONTROL_ID_SCHEMAS[method].safeParse(payload);
+    if (!parsed.success) {
+        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 @xneog/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
+ * internal.
+ * @param error - the thrown value.
+ * @param childSessionId - the addressed child.
+ * @param signal - the caller's cancellation.
+ * @returns Never — the refusal is thrown.
+ * @throws {RemoteError} always.
+ */
+export function rejectPrompt(error, childSessionId, signal) {
+    if (isCancellation(error, signal)) {
+        throw new RemoteError('gateway/cancelled', 'subagent prompt was cancelled', {}, { cause: error });
+    }
+    if (error instanceof AttachmentError) {
+        throw new RemoteError('subagent/attachment-invalid', error.message, { reason: error.code }, { cause: error });
+    }
+    if (error instanceof SubagentError) {
+        switch (error.code) {
+            case 'MODEL_DOES_NOT_SUPPORT_IMAGES':
+                throw new RemoteError('subagent/attachment-invalid', error.message, { reason: error.code }, { cause: error });
+            case 'NOT_RESUMABLE':
+                throw new RemoteError('subagent/not-resumable', 'subagent cannot be resumed', { childSessionId }, { cause: error });
+            case 'UNAUTHORIZED':
+                throw new RemoteError('subagent/unauthorized', 'subagent does not belong to this parent', { childSessionId }, { cause: error });
+            case 'DRAINING':
+            case 'ACTIVATION_CLOSING':
+            case 'CONTINUATION_UNAVAILABLE':
+            case 'PERSISTENCE_UNAVAILABLE':
+                throw new RemoteError('subagent/delivery-unavailable', 'subagent follow-up is temporarily unavailable', { childSessionId }, { cause: error });
+            // A code outside the admission vocabulary is not the caller's move to make.
+            default:
+                break;
+        }
+    }
+    throw new RemoteError('gateway/internal', 'subagent prompt failed', {}, { cause: error });
+}
+function isCancellation(error, signal) {
+    return signal.aborted || (error instanceof SubagentError && error.code === 'CANCELLED');
+}
+//# sourceMappingURL=control.js.map

package/lib/types/descriptor-seed.d.ts

@@ -17,5 +17,5 @@ import type { SubagentDescriptorData } from './descriptor.ts';
  * @param descriptor - the snapshotted composition record to persist.
  * @returns the complete seed events, contiguous from sequence zero.
  */
-export declare function seedDescriptorTurn(childId: SessionId, seed: readonly SessionEvent[] | undefined, descriptor: SubagentDescriptorData): SessionEvent[];
+export declare function seedDescriptorTurn(childId: SessionId, seed: readonly SessionEvent[] | undefined, descriptor: SubagentDescriptorData): readonly SessionEvent[];
 //# sourceMappingURL=descriptor-seed.d.ts.map

package/lib/types/descriptor-seed.js

@@ -19,6 +19,6 @@ import { Session } from '@xneog/dsh-session';
 export function seedDescriptorTurn(childId, seed, descriptor) {
     const staged = Session.create(childId, seed);
     staged.append('subagent/descriptor', descriptor);
-    return [...staged.events];
+    return staged.snapshotEvents();
 }
 //# sourceMappingURL=descriptor-seed.js.map

package/lib/types/descriptor.d.ts

@@ -21,6 +21,7 @@
  * @module @xneog/dsh-subagent/descriptor
  */
 import type { SessionEvent } from '@xneog/dsh-session';
+import type { ReasoningEffortId } from '@xneog/dsh-llm';
 import type { ToolRestriction } from '@xneog/dsh-tools';
 declare module '@xneog/dsh-session/types' {
     interface SessionEventMap {
@@ -40,7 +41,7 @@ declare module '@xneog/dsh-session/types' {
  * Supporting another composition input is a deliberate version change, never
  * an implicit extra field.
  */
-export declare const SUBAGENT_DESCRIPTOR_VERSION = 2;
+export declare const SUBAGENT_DESCRIPTOR_VERSION = 3;
 /** Fields shared by every supported `subagent/descriptor` payload. */
 interface SubagentDescriptorBase {
     /** Descriptor format version ({@link SUBAGENT_DESCRIPTOR_VERSION}). */
@@ -69,6 +70,8 @@ export interface ContinuableSubagentDescriptorData extends SubagentDescriptorBas
     readonly agentProvider?: string;
     /** Resolved child `agentOptions.model`, when one was declared. */
     readonly agentModel?: string;
+    /** Resolved child `agentOptions.reasoningEffort`, when one was declared. */
+    readonly agentReasoningEffort?: ReasoningEffortId;
     /** Per-child persona that shadows the deployment persona on resume. */
     readonly persona?: string;
     /** Child tool scoping reapplied on resume. */
@@ -98,6 +101,8 @@ export interface ContinuableSubagentDescriptorInput extends SubagentDescriptorIn
     readonly agentProvider?: string;
     /** Requested child `agentOptions.model`. */
     readonly agentModel?: string;
+    /** Requested child `agentOptions.reasoningEffort`. */
+    readonly agentReasoningEffort?: ReasoningEffortId;
     /** Requested per-child persona. */
     readonly persona?: string;
     /** Requested child tool scoping. */

package/lib/types/descriptor.js

@@ -20,14 +20,14 @@
  *
  * @module @xneog/dsh-subagent/descriptor
  */
-import { snapshotJsonValue } from '@xneog/dsh-session';
+import { snapshotJsonValue } from '@xneog/dsh-util-values';
 /**
  * The current descriptor format version, stamped into every appended
  * `subagent/descriptor` event and required verbatim by {@link foldSubagentDescriptor}.
  * Supporting another composition input is a deliberate version change, never
  * an implicit extra field.
  */
-export const SUBAGENT_DESCRIPTOR_VERSION = 2;
+export const SUBAGENT_DESCRIPTOR_VERSION = 3;
 const DESCRIPTOR_BASE_KEYS = [
     'version',
     'mode',
@@ -39,6 +39,7 @@ const CONTINUABLE_DESCRIPTOR_KEYS = new Set([
     ...DESCRIPTOR_BASE_KEYS,
     'agentProvider',
     'agentModel',
+    'agentReasoningEffort',
     'persona',
     'toolFilter',
 ]);
@@ -129,6 +130,7 @@ function parseSubagentDescriptor(value) {
     }
     const agentProvider = optionalString(value, 'agentProvider');
     const agentModel = optionalString(value, 'agentModel');
+    const agentReasoningEffort = optionalString(value, 'agentReasoningEffort');
     const persona = optionalString(value, 'persona');
     const toolFilter = Object.hasOwn(value, 'toolFilter')
         ? parseToolFilter(value['toolFilter'])
@@ -140,6 +142,7 @@ function parseSubagentDescriptor(value) {
         label,
         ...agentProvider !== undefined ? { agentProvider } : {},
         ...agentModel !== undefined ? { agentModel } : {},
+        ...agentReasoningEffort !== undefined ? { agentReasoningEffort } : {},
         ...persona !== undefined ? { persona } : {},
         ...toolFilter !== undefined ? { toolFilter } : {},
     };
@@ -159,6 +162,7 @@ export function snapshotSubagentDescriptor(input) {
             label: input.label,
             ...input.agentProvider !== undefined ? { agentProvider: input.agentProvider } : {},
             ...input.agentModel !== undefined ? { agentModel: input.agentModel } : {},
+            ...input.agentReasoningEffort !== undefined ? { agentReasoningEffort: input.agentReasoningEffort } : {},
             ...input.persona !== undefined ? { persona: input.persona } : {},
             ...input.toolFilter !== undefined ? { toolFilter: input.toolFilter } : {},
         };