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

package/lib/types/list-children.js

@@ -0,0 +1,166 @@
+/**
+ * Direct-child and recursive descendant discovery from parent-owned catalogs.
+ * Each catalog read releases its Session observation before the next branch.
+ * @module @deepseek-ai/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 { SubagentError } from "./error.js";
+/**
+ * Read one parent's durable catalog through a live-preferred Session observation.
+ * @param ctx - context carrying the Session query service.
+ * @param parentSessionId - parent whose direct children are requested.
+ * @param signal - cancellation forwarded to the Session observation.
+ * @returns direct-child rows in parent catalog event order.
+ * @throws {@link SubagentError} when query or catalog projection is unavailable.
+ */
+export async function listChildren(ctx, parentSessionId, signal) {
+    const env_1 = { stack: [], error: void 0, hasError: false };
+    try {
+        const query = ctx.get('sessionQuery');
+        if (query === undefined) {
+            throw new SubagentError('listing subagents requires the sessionQuery service (load @deepseek-ai/dsh-session-query)', 'SUBAGENT_CONTROL_QUERY_UNAVAILABLE');
+        }
+        const parent = __addDisposableResource(env_1, await query.observeSession(parentSessionId, {
+            ...signal === undefined ? {} : { signal },
+        }), false);
+        const entries = parent.projections?.values.subagentCatalog;
+        if (entries === undefined) {
+            throw new SubagentError('listing subagents requires the registered subagentCatalog projection', 'SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE');
+        }
+        return entries;
+    }
+    catch (e_1) {
+        env_1.error = e_1;
+        env_1.hasError = true;
+    }
+    finally {
+        __disposeResources(env_1);
+    }
+}
+/**
+ * Walk reachable parent catalogs in stable pre-order without loading Agents.
+ * @see SubagentRuntime.listDescendants for failure and cancellation semantics.
+ * @param ctx - context carrying the Session store and query service.
+ * @param rootSessionId - parent whose catalog starts the traversal.
+ * @param signal - cancellation checked around each catalog read.
+ * @returns children and branch diagnostics with catalog parent and depth.
+ */
+export async function listDescendants(ctx, rootSessionId, signal) {
+    const sessions = ctx.get('sessions');
+    if (sessions === undefined) {
+        throw new SubagentError('listing subagents requires the session store (load @deepseek-ai/dsh-session)', 'SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE');
+    }
+    const readChildren = async (id) => {
+        assertListingNotCancelled(signal);
+        let children;
+        try {
+            children = await listChildren(ctx, id, signal);
+        }
+        catch (error) {
+            assertListingNotCancelled(signal);
+            throw error;
+        }
+        assertListingNotCancelled(signal);
+        return children;
+    };
+    const stack = (await readChildren(rootSessionId))
+        .map(entry => ({ entry, parentId: rootSessionId, depth: 1 }))
+        .reverse();
+    const visited = new Set([rootSessionId]);
+    const result = [];
+    for (let position = stack.pop(); position !== undefined; position = stack.pop()) {
+        const { entry, parentId, depth } = position;
+        if (visited.has(entry.id))
+            continue;
+        visited.add(entry.id);
+        let children;
+        try {
+            children = entry.mode === 'external' ? [] : await readChildren(entry.id);
+        }
+        catch (error) {
+            if (error instanceof SubagentError)
+                throw error;
+            const code = error instanceof Error && 'code' in error ? error.code : undefined;
+            result.push({
+                kind: 'diagnostic', id: entry.id, parentId, depth,
+                reason: code === 'SESSION_QUERY_CORRUPT_SESSION' || code === 'SESSION_QUERY_SOURCE_CONFLICT'
+                    ? 'corrupt' : 'unavailable',
+            });
+            continue;
+        }
+        if (entry.mode === 'unknown') {
+            result.push({ kind: 'diagnostic', id: entry.id, parentId, depth, reason: 'unsupported' });
+        }
+        else {
+            const { createdAt: _createdAt, ...identity } = entry;
+            result.push({
+                ...identity, kind: 'child', parentId, depth,
+                activity: sessions.get(entry.id) === undefined ? 'inactive' : 'running',
+                hasChildren: children.length > 0,
+            });
+        }
+        // Catalog event order defines siblings; the stack visits the first one next.
+        for (const child of [...children].reverse()) {
+            stack.push({ entry: child, parentId: entry.id, depth: depth + 1 });
+        }
+    }
+    return result;
+}
+/** Stop the complete traversal when its caller cancels. */
+function assertListingNotCancelled(signal) {
+    if (signal?.aborted) {
+        throw new SubagentError('subagent listing was cancelled', 'CANCELLED');
+    }
+}
+//# sourceMappingURL=list-children.js.map

package/lib/types/manager.d.ts

@@ -0,0 +1,215 @@
+/**
+ * Owns subagent startup, message admission, cold resume, and execution lifetimes.
+ * One child lock orders input acceptance and closure; one activation map owns
+ * capacity, runtime ownership, and resource release across all providers.
+ *
+ * @module @deepseek-ai/dsh-subagent/manager
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { ContentBlock, MessageId, MessageSource } from '@deepseek-ai/dsh-llm';
+import type { Session, SessionId } from '@deepseek-ai/dsh-session';
+import type { DelegatedApprovalPolicy } from './child-agent.ts';
+import type { LifecycleEmitter } from './lifecycle.ts';
+import type { SubagentIdentityProjection } from './projection-types.ts';
+import type { ContinuableCreateRequest, ContinuableCreateSpec, SubagentInterruptAuthority, SubagentActivationSpec, SubagentActivation, SubagentRun, SubagentSendMessageOptions, ResolvedSubagentStartRequest } from './types.ts';
+import type { SubagentDelivery } from './control-types.ts';
+/** Inputs shared by model steering and human prompt delivery. */
+type ChildDeliveryOptions = {
+    readonly delivery: SubagentDelivery;
+    readonly source: MessageSource;
+    readonly signal: AbortSignal;
+    /** Recheck the original model caller at final inbox admission. */
+    readonly authorize?: () => void;
+    /** Record successful inbox admission before another asynchronous operation can intervene. */
+    readonly onAccepted?: () => void;
+};
+/** Package-private hooks supplied by the owning service. */
+interface SubagentHost {
+    /** Read the current descriptor identity through the service-owned projection. */
+    identityOf(session: Session): SubagentIdentityProjection | undefined;
+    /** Publish lifecycle events through the owning service's scoped dispatcher. */
+    readonly emitLifecycle: LifecycleEmitter;
+}
+/** Own subagent requests and the resources of every live activation. */
+export declare class SubagentManager {
+    private readonly ctx;
+    private readonly host;
+    private readonly maxActiveSubagents;
+    private readonly delegatedApproval;
+    /** Child session id → its live Activation. Process-local, never durable. */
+    private readonly resident;
+    /** Root identities retain their pool across child settlement without retaining dead roots. */
+    private readonly rootPools;
+    /** Materializations admitted before drain, tracked through publication or rollback. */
+    private readonly materializations;
+    /** Per-child serializer shared by delivery, release, and disposal. */
+    private readonly locks;
+    /** Structural Cordis owner of every Activation handle. */
+    private readonly ownerCtx;
+    /** Exact subagent tree roots whose host teardown has closed admission. */
+    private readonly closingRoots;
+    private draining;
+    /**
+     * Build one manager inside the service's Agent-injected context.
+     * @param ctx - context providing Agents, Sessions, and teardown ownership.
+     * @param host - descriptor reads and lifecycle publication owned by the service.
+     * @param maxActiveSubagents - the current configured child capacity.
+     * @param delegatedApproval - the configured approval policy seed for each local child.
+     */
+    constructor(ctx: Context, host: SubagentHost, maxActiveSubagents: () => number, delegatedApproval: () => DelegatedApprovalPolicy);
+    /**
+     * Interrupt one live continuable child's current turn under the supplied authority.
+     * @param targetSessionId - the durable child session id to interrupt.
+     * @param authority - a trusted user operation or exact live ancestor Agent.
+     */
+    interrupt(targetSessionId: SessionId, authority: SubagentInterruptAuthority): void;
+    /**
+     * Close admission, await every already-admitted materialization through
+     * publication or rollback, then dispose every agent in the subagent tree.
+     */
+    drain(): Promise<void>;
+    /**
+     * Join progressing subagent tree work for its root, leaving idle parked inboxes resident.
+     * @param root - exact live subagent tree root; ordinary members return false.
+     * @returns whether work was joined and the host must recheck root completion.
+     */
+    waitForTreeWork(root: Agent): Promise<boolean>;
+    /**
+     * Stop every member of the selected subagent trees; ordinary members do not close a subagent tree.
+     * @param parents - exact live subagent tree roots whose instances must stop.
+     */
+    drainDescendants(parents: readonly Agent[]): Promise<void>;
+    /**
+     * Start one continuable background child and resolve at initial inbox acceptance.
+     * Every earlier failure disposes any created handle and rolls back Activation
+     * and its capacity slot without returning either id.
+     * @param spec - provider, delegation request, and caller cancellation.
+     * @param prepare - creation contribution bound to the checked provider.
+     * @returns the durable child id and accepted initial prompt message id.
+     */
+    startLocal(spec: SubagentActivationSpec, prepare: (request: ContinuableCreateRequest) => Promise<ContinuableCreateSpec>): Promise<SubagentActivation & {
+        messageId: MessageId;
+    }>;
+    /**
+     * Start an external backend under activation ownership.
+     * @param spec - task, provider, cancellation, and delivery policy.
+     * @param start - execution bound to the checked provider.
+     * @returns the accepted activation and its result/disposal capabilities.
+     */
+    startExternal(spec: SubagentActivationSpec, start: (request: ResolvedSubagentStartRequest) => Promise<SubagentRun>): Promise<SubagentActivation>;
+    /** Capture the explicit or inherited directory while the parent still owns startup. */
+    private resolveDirectory;
+    /**
+     * Resolve the live subagent tree root from runtime ownership, independent of creator residency.
+     * @param caller - exact live Agent selecting the subagent tree.
+     * @returns the live subagent tree root.
+     * @throws when the caller has no active runtime owner.
+     */
+    rootOf(caller: Agent): Agent;
+    /** Capture creation ancestry separately from the root that owns the new instance. */
+    private ancestryForChild;
+    /**
+     * Deliver to another agent in the subagent tree, restoring only the target when absent.
+     * @param sender - exact live root or resident continuable Agent.
+     * @param targetId - another member's durable Session id.
+     * @param content - model-authored message blocks.
+     * @param options - cancellation before inbox acceptance.
+     * @returns the accepted inbox message id.
+     */
+    sendMessage(sender: Agent, targetId: SessionId, content: ContentBlock[], options: SubagentSendMessageOptions): Promise<MessageId>;
+    /** Resolve the live owner through verified creation edges without activating ancestors. */
+    private resolveCreationAncestry;
+    /**
+     * Deliver one host-authored prompt through the target's live subagent tree root.
+     * Remote callers must be authorized for the target Session before invoking this operation.
+     * @param childId - durable continuable subagent session id.
+     * @param content - model-visible prompt blocks.
+     * @param options - inbox destination, durable attribution, and cancellation before acceptance.
+     * @returns the accepted durable message id.
+     */
+    deliverPrompt(childId: SessionId, content: ContentBlock[], options: Pick<ChildDeliveryOptions, 'delivery' | 'source' | 'signal'>): Promise<MessageId>;
+    /** Admit local input synchronously before any teardown can begin. */
+    private deliver;
+    /**
+     * Reject one child identity already owned by a live Agent or Session.
+     * @param childId - proposed durable child session id.
+     */
+    private assertChildIdAvailable;
+    /**
+     * Apply activation admission to a resident parent before delivering input.
+     * @param parent - exact live Agent receiving the message.
+     * @param message - durable user message to deliver.
+     * @param delivery - receiving inbox destination.
+     */
+    private sendWaking;
+    /**
+     * Reject new work from closing members or subagent trees.
+     * @param agent - exact live caller whose instance and subagent tree must admit work.
+     */
+    private assertAdmitting;
+    /**
+     * Create or resume one child Agent and publish its Activation.
+     * @param inputs - reconstruction and admission inputs for the residency epoch.
+     * @returns the published process-local Activation.
+     */
+    private materialize;
+    /** Keep subagent tree shutdown and host waits joined to preparation, publication, and rollback. */
+    private trackStartup;
+    /**
+     * Stop and release one Activation through its memoized close transaction.
+     * @param activation - exact residency epoch to close.
+     * @returns the shared close transaction.
+     */
+    private dispose;
+    /** Close admission synchronously and share one release, including startup rollback. */
+    private close;
+    /** Dispose independent roots and report every branch failure after all settle. */
+    private disposeRoots;
+    /** Return the subagent tree teardown that closed admission for this exact Agent. */
+    private closingTeardownFor;
+    /** Share one capacity pool across every instance in a subagent tree. */
+    private rootPool;
+    /** Perform one tracked materialization through publication or rollback. */
+    private materializeTracked;
+    /** Identity shared by one residency epoch's start/end pair, including cold resumes. */
+    private runInfo;
+    /** Record acceptance and begin settlement observation before returning the receipt. */
+    private accept;
+    /** Release an Activation whose start edge was not published. */
+    private rollbackUnpublished;
+    /** Let a settlement watcher re-check residency after relevant state changes. */
+    private wake;
+    /** Follow one Activation to natural settlement. */
+    private watchLocalSettlement;
+    /** Report disposal failure once after the natural settlement observer finishes. */
+    private reportTeardownFailure;
+    /** Check pending input before closing admission. */
+    private settlementState;
+    /** Stop and release one instance without affecting its creation descendants. */
+    private finishDisposal;
+    /** Deliver the captured execution result to the durable direct parent after cleanup. */
+    private notifySettlement;
+    /** Request a best-effort final session flush before closing natural-settlement admission. */
+    private flushFinalState;
+    /** Return capabilities bound to an exact activation instead of a future same-id instance. */
+    private receipt;
+    /** Serialize target restoration and inbox admission; closure is awaited outside the lock. */
+    private deliverToMember;
+    /** Read continuation history, preserving cancellation and reporting unavailable storage. */
+    private observeContinuation;
+    /** Reconstruct only the target under its subagent tree root; the caller owns acceptance or rollback. */
+    private restoreTarget;
+    /** Admit a materialized child, commit its creation fact, and release it on failure. */
+    private submitMaterialized;
+    /** Build and submit one message across the final synchronous admission cutoff. */
+    private submitAdmitted;
+    /** Refuse image content for a child whose fixed model accepts text only. */
+    private assertImageCapable;
+    /** Resolve the persistence service continuable children require, or fail loud. */
+    private requirePersistence;
+    /** Resolve the Session query service used for cold child observations. */
+    private requireSessionQuery;
+}
+export default SubagentManager;
+//# sourceMappingURL=manager.d.ts.map