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

package/lib/types/index.d.ts

@@ -4,10 +4,8 @@
  * child before returning its run, so fulfillment is the single publication and
  * ownership-transfer boundary.
  *
- * Unlike the bash seam (one executor per context, second load throws), MULTIPLE
- * providers coexist here: each registers under a unique name and a caller picks
- * one by name. The shape mirrors the LLM adapter registry
- * (`LlmRuntime.registerAdapter`), not the single-service bash executor.
+ * Multiple providers coexist: each registers under a unique name and callers
+ * select one by name.
  *
  * This package owns the Service Definition role of the capability seam. Service Providers
  * (`@xneog/dsh-subagent-spawn-in-process`, `-fork`, `-acp`) and the model-facing
@@ -15,8 +13,8 @@
  *
  * Public operations express caller intent: `start` returns one published owned
  * one-shot run, `startContinuable` establishes a durable continuable child, and
- * `followup` delivers later content without exposing whether the child is
- * resident. Continuable children never become a {@link SubagentRun}: the
+ * `sendMessage` steers between adjacent Agents without exposing whether a child
+ * 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
@@ -30,30 +28,31 @@
  *
  * @module @xneog/dsh-subagent
  */
-import { Context, Service } from '@xneog/cordis';
+import { Context } from '@xneog/cordis';
 import type { Scoped } from '@xneog/dsh-scope';
 import type { ContentBlock, MessageId } from '@xneog/dsh-llm';
 import type { Agent } from '@xneog/dsh-agent';
 import type { SessionId } from '@xneog/dsh-session';
+import { TypertRemoteService } from '@xneog/dsh-typert-protocol';
+import type { SubagentCatalog, SubagentInterruptReceipt, SubagentPromptReceipt, SubagentPromptRequest } from './control-types.ts';
 import type { SubagentProvider, SubagentRun, SubagentRunEndInfo, SubagentRunInfo, SubagentStartRequest } from './types.ts';
-import type { ContinuableStart, ContinuableStartSpec, SubagentFollowupOptions, SubagentInterruptAuthority, SubagentReportOptions } from './continuation.ts';
-import type { ContinuableSetupContribution } from './activation-setup-registry.ts';
+import type { ContinuableStart, ContinuableStartSpec, SubagentInterruptAuthority, SubagentSendMessageOptions } from './continuation.ts';
 import type { SubagentDescendantListEntry, SubagentListEntry } from './list-children.ts';
+import { deliverSubagentPrompt } from './internal.ts';
 export * from './out-of-process.ts';
 export { AssistantOutputFold, finalAssistantOutput } from './assistant-output.ts';
 export { SubagentRunId } from './types.ts';
 export type { ContinuableCreateRequest, ContinuableCreateSpec, ResolvedSubagentStartRequest, SubagentCapabilities, SubagentProvider, SubagentResult, SubagentRun, 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 { seedDescriptorTurn } from './descriptor-seed.ts';
 export { SubagentError } from './error.ts';
 export { settleRun } from './run-settlement.ts';
 export { assertSubagentMaxDepth, delegationDepthOf } from './depth.ts';
-export { appendDelegatedPolicyOverrides, applyChildComposition, captureDelegatedPolicyOverrides, childSessionMeta, resolveChildAgentOptions, resolveChildDepth, SubagentDepthError, } from './child-agent.ts';
+export { appendDelegatedPolicyOverrides, applyChildComposition, captureDelegatedPolicyOverrides, childSessionMeta, parentAgentOptionsForDelegation, resolveChildAgentOptions, resolveChildDepth, SubagentDepthError, } from './child-agent.ts';
 export type { ChildComposition, DelegatedPolicyOverrides } from './child-agent.ts';
-export type { ContinuableStart, ContinuableStartSpec, CoordinatorMessageSource, SubagentFollowupOptions, SubagentInterruptAuthority, SubagentReportDelivery, SubagentReportMessageSource, SubagentReportOptions, SubagentSettledMessageSource, } from './continuation.ts';
-export type { ContinuableSetupContribution } from './activation-setup-registry.ts';
-export type { SubagentDescendantListEntry, SubagentListEntry } from './list-children.ts';
+export type { AgentMessageSource, ContinuableStart, ContinuableStartSpec, SubagentInterruptAuthority, SubagentSendMessageOptions, SubagentSettledMessageSource, } from './continuation.ts';
+export type * from './control-types.ts';
+export type { SubagentDescendantListEntry } from './list-children.ts';
 export type { SubagentRunEndInfo, SubagentRunInfo } from './types.ts';
 export type { SubagentIdentityProjection, SubagentTimingProjection } from './projection-types.ts';
 declare module '@xneog/cordis' {
@@ -96,11 +95,9 @@ declare module '@xneog/cordis' {
     }
 }
 /** Named provider registry with one-shot runs, durable discovery, and continuable-child operations. */
-export declare class SubagentRuntime extends Service {
+export declare class SubagentRuntime extends TypertRemoteService {
     private providers;
     private continuations;
-    /** Deployment contributions composed into unpublished continuable children. */
-    private readonly setupRegistry;
     /**
      * The contained lifecycle-edge publisher. Built here because scoped dispatch
      * keys its carrier by this exact service instance, whose own context filter
@@ -119,21 +116,33 @@ export declare class SubagentRuntime extends Service {
      */
     startContinuable(spec: ContinuableStartSpec): Promise<ContinuableStart>;
     /**
-     * Deliver one later message to a continuable child as its next FIFO turn. A
-     * resident child's Agent inbox accepts it directly (waking a `waiting`
-     * Activation), while an absent one is cold-resumed from its persisted
-     * Session. The Agent inbox is the only queue, so every accepted message has
-     * one observable order.
-     * @param parent - the exact live direct parent authorizing this delivery.
-     * @param childId - durable child session id.
-     * @param content - user-role content to deliver.
-     * @param options - the message source fields and caller cancellation, which stops the
-     *   operation only before inbox acceptance.
+     * Steer one model-authored message to the sender's direct parent or direct
+     * continuable child. A running target admits it at the nearest step boundary;
+     * an idle target starts a turn, and an absent direct child cold-resumes from
+     * persistence. The service derives durable sender attribution from the exact
+     * live sender. Caller cancellation stops only pre-acceptance work.
+     * @param sender - exact live Agent authorizing and originating the message.
+     * @param targetId - durable direct-parent or direct-child session id.
+     * @param content - model-authored content to deliver.
+     * @param options - caller cancellation before inbox acceptance.
      * @returns the accepted message's inbox id.
-     * @throws when continuation services are unavailable, parent authority is
-     *   rejected, or the message was not admitted.
+     * @throws when continuation services are unavailable, adjacency is rejected,
+     *   or the message was not admitted.
      */
-    followup(parent: Agent, childId: SessionId, content: ContentBlock[], options: SubagentFollowupOptions): Promise<MessageId>;
+    sendMessage(sender: Agent, targetId: SessionId, content: ContentBlock[], options: SubagentSendMessageOptions): Promise<MessageId>;
+    /**
+     * Deliver one host-protocol message to a direct continuable child.
+     * Symbol-keyed so host adapters can preserve their own provenance without
+     * widening the public Service Definition or impersonating an Agent sender.
+     * @param parent - exact live direct parent authorizing delivery.
+     * @param childId - durable direct-child session id.
+     * @param content - host-authored content to deliver.
+     * @param source - durable host-protocol provenance.
+     * @param signal - caller cancellation before inbox acceptance.
+     * @param delivery - Queue as a distinct turn or Steer at the nearest step.
+     * @returns the accepted message's inbox id.
+     */
+    private [deliverSubagentPrompt];
     /**
      * Interrupt one live continuable child's current turn under a human parent
      * address or an exact live ancestor Agent. Fire-and-return: the cancel
@@ -150,27 +159,6 @@ export declare class SubagentRuntime extends Service {
      *   live target.
      */
     interrupt(targetSessionId: SessionId, authority: SubagentInterruptAuthority): void;
-    /**
-     * Deliver selected content from one live continuable child to its durable
-     * direct parent. The child is the authority credential; callers cannot name a
-     * recipient. Reporting does not conclude the child's turn or Activation.
-     * @param child - exact live reporting child.
-     * @param content - selected model-facing content.
-     * @param options - parent scheduling and pre-acceptance cancellation.
-     * @returns the stable identity of the parent-accepted message.
-     * @throws when continuation services are unavailable, sender authorization
-     *   fails, or the direct parent is not live.
-     */
-    reportFrom(child: Agent, content: ContentBlock[], options: SubagentReportOptions): Promise<MessageId>;
-    /**
-     * Compose one deployment capability into every continuable child's
-     * unpublished creation context on fresh creation and cold resume. Grants wait
-     * for the next Activation; removing the contribution revokes every resident
-     * installation immediately.
-     * @param contribution - synchronous child-scope installer.
-     * @returns the exact Cordis effect disposer.
-     */
-    registerContinuableSetup(contribution: ContinuableSetupContribution): () => void;
     /**
      * Close continuable admission below exact live parent Agents, stop only their
      * visible descendant Activations synchronously, then await admitted scoped
@@ -182,29 +170,29 @@ export declare class SubagentRuntime extends Service {
      * @throws an aggregate error after all branches settle when any failed.
      */
     drainContinuableDescendants(parents: readonly Agent[]): Promise<void>;
+    /**
+     * Release selected resident continuable direct children of one exact live
+     * parent. Other children of the same parent remain admitted and resident.
+     * Absent targets and a manager-less composition are accepted no-ops.
+     * @param parent - exact live direct parent authorizing the selected release.
+     * @param childIds - durable direct-child ids to release when resident.
+     * @returns once every selected Activation released its `AgentHandle`.
+     * @throws {SubagentError} `UNAUTHORIZED` when a resident target belongs to a
+     *   different parent or the supplied parent identity is stale.
+     */
+    drainContinuableChildren(parent: Agent, childIds: readonly SessionId[]): Promise<void>;
     /**
      * Enumerate the parent's direct session-backed subagents without loading or
-     * resuming an Agent and without any query service: the listing merges the live
-     * session store with optional session persistence (live-preferred) and
-     * serves each child's durable mode/label from the registered `subagent`
-     * projection unit down a three-rung ladder — the registry's watermark
-     * snapshot for a live child; for a cold one, a durable projection-cache
-     * row when the optional cache serves an own-suffix identity (its `seq`
-     * gate proves the value postdates the fork seed, where a child's own
-     * descriptor is immutable once appended), else one persistence inspection
-     * folded through the registry. The
-     * projection fold is the single classification authority; per-child
-     * diagnostics relay a fold that served no identity or a failed inspection,
-     * never a list-time descriptor parse. Absent persistence, enumeration is
-     * live-only (a cold child cannot be resumed then either, so its absence is
-     * capability absence, not an error). This service consults no Agent
-     * registrations, Activations, or providers.
+     * 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 persistence read receives `signal`, and the listing rechecks
-     * cancellation around each of those awaits. Read rejections that settle
+     * 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 persistence reads
+     * @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
@@ -227,6 +215,52 @@ export declare class SubagentRuntime extends Service {
      * @throws {@link SubagentError} under the same conditions as {@link listChildren}.
      */
     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
+     * validated browser zone on the accepted message. Success identifies the
+     * message the child's FIFO inbox accepted; later execution is independent of
+     * this call.
+     * Image parts are admitted and persisted through the attachment store
+     * before delivery, and the child's model must accept image input.
+     * @param request - durable address, minted identity, content, and optional browser zone.
+     * @param signal - carrier cancellation, owning the call until inbox acceptance.
+     * @returns the accepted message's inbox identity.
+     * @throws {RemoteError} `gateway/bad-request`, `subagent/attachment-invalid`,
+     *   `subagent/invalid-time-zone`, `subagent/parent-unavailable`,
+     *   `subagent/not-resumable`, `subagent/unauthorized`,
+     *   `subagent/delivery-unavailable`, `gateway/cancelled`, or `gateway/internal`.
+     */
+    prompt(request: SubagentPromptRequest, signal: AbortSignal): Promise<SubagentPromptReceipt>;
+    /**
+     * Remote face of {@link interrupt} under one durable parent address. No
+     * catalog, history, persistence, or parent Agent lookup runs: the core
+     * primitive alone authorizes the address against the live Activation, which
+     * is what keeps a live child interruptible while its parent Agent is offline.
+     * Absent, idle, and already-completed targets are accepted no-ops there.
+     * @param childSessionId - durable child session id to interrupt.
+     * @param parentSessionId - durable direct parent whose authority is claimed.
+     * @param mode - required continuable-address discriminator.
+     * @returns acknowledgement that the cancel signal was admitted, not that the target is quiescent.
+     * @throws {RemoteError} `gateway/bad-request` for an empty id,
+     *   `subagent/unauthorized` when the address does not own the live target,
+     *   otherwise `gateway/internal`.
+     */
+    interruptByParent(childSessionId: SessionId, parentSessionId: SessionId, mode: 'continuable'): SubagentInterruptReceipt;
     /**
      * Register a provider under its name. Registration is effect-scoped and HMR
      * safe; removing a provider blocks new starts but does not revoke runs that