@toddzheng024/dscode-bundle 0.3.0 → 0.5.0

package/vendor/subagent-core/types/continuation-messages.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Model-visible messages owned by continuable-subagent orchestration.
+ *
+ * @module @deepseek-ai/dsh-subagent/continuation-messages
+ */
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import type { ContentBlock } from '@deepseek-ai/dsh-llm';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+import type { ActivationTerminal } from './lifecycle.ts';
+/** Durable attribution for one model-authored message between adjacent Agents. */
+export interface AgentMessageSource {
+    readonly kind: 'agent-message';
+    /** A message another agent addressed to this one (`relay` context form). */
+    readonly form: 'relay';
+    /** Session id of the Agent whose tool call produced the message. */
+    readonly senderSessionId: SessionId;
+}
+/**
+ * Durable attribution for the runtime's own account of a continuable child
+ * settling. Deliberately a different kind from
+ * {@link AgentMessageSource}: an Agent message is content the sender chose,
+ * while this message is the manager stating what became of the child, and a
+ * transcript that merged them would credit the child with words it never wrote.
+ */
+export interface SubagentSettledMessageSource {
+    readonly kind: 'subagent-settled';
+    /** A runtime account shown without expanding the row (`notice` context form). */
+    readonly form: 'notice';
+    /** One-line account of how the child ended. */
+    readonly summary: string;
+    /** Session id of the child that settled. */
+    readonly senderSessionId: SessionId;
+}
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        'agent-message': AgentMessageSource;
+        'subagent-settled': SubagentSettledMessageSource;
+    }
+}
+/**
+ * Build the model-visible and durable representation of one adjacent-Agent message.
+ * @param sender - exact live Agent that authored the message.
+ * @param content - model-visible message blocks supplied by the sender.
+ * @returns the durable user-message representation delivered to the recipient.
+ */
+export declare function createAgentMessage(sender: Agent, content: ContentBlock[]): ReturnType<typeof createUserMessage>;
+/**
+ * Append adjacent-Agent return guidance to a continuable child's initial task.
+ * @param parentId - durable parent session id named in the guidance.
+ * @param prompt - initial model-visible task blocks.
+ * @returns task blocks followed by the continuable return guidance.
+ */
+export declare function withContinuableReturnGuidance(parentId: SessionId, prompt: ContentBlock[]): ContentBlock[];
+/**
+ * Build the runtime-owned settlement notice delivered to a child's parent.
+ * @param childId - durable child session id named in the notice.
+ * @param terminal - recorded terminal state for the settled Activation.
+ * @returns the durable user-message representation delivered to the parent.
+ */
+export declare function createSettlementMessage(childId: SessionId, terminal: ActivationTerminal): ReturnType<typeof createUserMessage>;
+//# sourceMappingURL=continuation-messages.d.ts.map

package/vendor/subagent-core/types/continuation-messages.js

@@ -0,0 +1,102 @@
+/**
+ * Model-visible messages owned by continuable-subagent orchestration.
+ *
+ * @module @deepseek-ai/dsh-subagent/continuation-messages
+ */
+import { boundContextSummary, createUserMessage } from '@deepseek-ai/dsh-llm';
+/** Build durable attribution for one adjacent-Agent message. */
+function agentMessageSource(sender) {
+    return {
+        kind: 'agent-message',
+        form: 'relay',
+        senderSessionId: sender.id,
+    };
+}
+/**
+ * Build the model-visible and durable representation of one adjacent-Agent message.
+ * @param sender - exact live Agent that authored the message.
+ * @param content - model-visible message blocks supplied by the sender.
+ * @returns the durable user-message representation delivered to the recipient.
+ */
+export function createAgentMessage(sender, content) {
+    return createUserMessage({
+        content: [
+            { type: 'text', text: `Agent ${sender.id} sent a message: ` },
+            ...content,
+        ],
+        source: agentMessageSource(sender),
+    });
+}
+/**
+ * Append adjacent-Agent return guidance to a continuable child's initial task.
+ * @param parentId - durable parent session id named in the guidance.
+ * @param prompt - initial model-visible task blocks.
+ * @returns task blocks followed by the continuable return guidance.
+ */
+export function withContinuableReturnGuidance(parentId, prompt) {
+    const encodedParentId = JSON.stringify(parentId);
+    return [
+        ...prompt,
+        {
+            type: 'text',
+            text: `Your parent agent id is ${encodedParentId}. Before you finish, send your result to that agent with `
+                + `send_message({ agent_id: ${encodedParentId}, message: "<self-contained result>" }). The parent shares `
+                + 'your workspace but does not automatically receive your transcript, tool output, or reasoning. Send '
+                + 'earlier messages as well when a finding changes what the parent should do next; sending a message '
+                + 'does not end your turn.',
+        },
+    ];
+}
+/**
+ * One line telling a parent that a background child is finished and why, in
+ * the parent's own task vocabulary.
+ * @param childId - the durable child the parent knows by id.
+ * @param stopReason - how the child's last ordinary turn ended.
+ * @returns the model-facing opening line of the settlement notice.
+ */
+function settlementSummary(childId, stopReason) {
+    const subject = `Background subagent ${childId}`;
+    switch (stopReason) {
+        case 'completed':
+            return `${subject} finished and will do no further work unless you send it more.`;
+        case 'aborted':
+            return `${subject} was stopped before it finished.`;
+        case 'max-tokens':
+            return `${subject} ran out of room before it finished.`;
+        // A pre-step rejection — a hook deny, a policy plugin — discarded input
+        // the child had claimed, so the parent must not treat the task as done.
+        case 'refusal':
+            return `${subject} declined the task.`;
+        case 'error':
+            return `${subject} failed before it finished.`;
+        /* v8 ignore next 4 -- `SubagentResult['stopReason']` is merge-extensible, so this arm
+         * needs a backend that adds a variant; an unnameable ending is reported as unfinished
+         * rather than silently as success. */
+        default:
+            return `${subject} ended abnormally (${String(stopReason)}) before it finished.`;
+    }
+}
+/**
+ * Build the runtime-owned settlement notice delivered to a child's parent.
+ * @param childId - durable child session id named in the notice.
+ * @param terminal - recorded terminal state for the settled Activation.
+ * @returns the durable user-message representation delivered to the parent.
+ */
+export function createSettlementMessage(childId, terminal) {
+    const summary = settlementSummary(childId, terminal.stopReason);
+    return createUserMessage({
+        content: [
+            { type: 'text', text: summary },
+            ...terminal.output === undefined
+                ? [{ type: 'text', text: 'It left no closing message.' }]
+                : [{ type: 'text', text: 'Its closing message:' }, ...terminal.output],
+        ],
+        source: {
+            kind: 'subagent-settled',
+            form: 'notice',
+            summary: boundContextSummary(summary),
+            senderSessionId: childId,
+        },
+    });
+}
+//# sourceMappingURL=continuation-messages.js.map

package/vendor/subagent-core/types/continuation.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Continuable-subagent orchestration behind `ctx.subagents`: stable child ids,
+ * descriptor persistence, provider preparation, cold resume, authorization,
+ * and message routing. {@link ContinuableActivationRegistry} owns the mutable
+ * process-local Activation graph and its settlement and disposal lifecycle.
+ *
+ * A continuable child has one durable Session and at most one process-local
+ * Activation. The Agent inbox is the only turn queue, so this manager owns
+ * durable orchestration while the Agent loop owns all turn ordering and
+ * execution. No continuable path creates a Task or an intermediate
+ * result-bearing wrapper.
+ *
+ * @module @deepseek-ai/dsh-subagent
+ */
+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 { SessionId } from '@deepseek-ai/dsh-session';
+import type { ActivationObserver } from './lifecycle.ts';
+import type { ContinuableCreateRequest, ContinuableCreateSpec, ContinuableStart, ContinuableStartSpec, SubagentInterruptAuthority, SubagentSendMessageOptions } from './types.ts';
+/** Package-private hooks supplied by the owning service. */
+interface ContinuationHost {
+    /** Resolve one provider's detached continuable-creation contribution. */
+    prepareContinuable(name: string, request: ContinuableCreateRequest): Promise<ContinuableCreateSpec>;
+    /** Build the lifecycle observer for one Activation residency epoch. */
+    observeActivation(provider: string, childId: SessionId, parent: Agent): ActivationObserver;
+}
+/**
+ * The continuable-subagent orchestration service behind `ctx.subagents`. Tool
+ * schema and host adapters are consumers of this one contract; foreground
+ * one-shot delegation keeps calling `ctx.subagents.start()` and never enters
+ * this lifecycle.
+ */
+export declare class SubagentContinuationManager {
+    private readonly ctx;
+    private readonly host;
+    private readonly activations;
+    constructor(ctx: Context, host: ContinuationHost);
+    /**
+     * Start one continuable background child and resolve at initial inbox acceptance.
+     * Every earlier failure disposes any created handle and rolls back Activation
+     * and parent ownership without returning either id.
+     * @param spec - provider, delegation request, and caller cancellation.
+     * @returns the durable child id and accepted initial prompt message id.
+     */
+    startContinuable(spec: ContinuableStartSpec): Promise<ContinuableStart>;
+    /**
+     * Deliver one model-authored message to a direct continuable child or to the
+     * sender's direct parent. A missing direct child cold-resumes through the
+     * ordinary continuation lifecycle.
+     * @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 acceptance.
+     * @returns the accepted message's inbox id.
+     */
+    sendMessage(sender: Agent, targetId: SessionId, content: ContentBlock[], options: SubagentSendMessageOptions): Promise<MessageId>;
+    /**
+     * Queue one human-authored prompt as a distinct direct-child turn.
+     * @param parent - exact live direct parent authorizing delivery.
+     * @param childId - durable direct-child session id.
+     * @param content - model-visible prompt blocks.
+     * @param source - durable attribution for the human prompt.
+     * @param signal - caller cancellation before inbox acceptance.
+     * @returns the accepted durable message id.
+     */
+    queuePrompt(parent: Agent, childId: SessionId, content: ContentBlock[], source: MessageSource, signal: AbortSignal): Promise<MessageId>;
+    /**
+     * Steer one host-authored prompt to a direct continuable child.
+     * @param parent - exact live direct parent authorizing delivery.
+     * @param childId - durable direct-child session id.
+     * @param content - model-visible prompt blocks.
+     * @param source - durable attribution for the host prompt.
+     * @param signal - caller cancellation before inbox acceptance.
+     * @returns the accepted durable message id.
+     */
+    steerPrompt(parent: Agent, childId: SessionId, content: ContentBlock[], source: MessageSource, signal: AbortSignal): Promise<MessageId>;
+    /** Route one parent-originated delivery through residency and cold resume. */
+    private deliverToChild;
+    /** The delivery loop behind {@link deliverToChild}, run under the parent hold. */
+    private deliverFollowup;
+    /**
+     * Interrupt one live continuable child's current turn. Admission is
+     * synchronous and the cancellation effect is asynchronous. An absent or
+     * already-closing target is an accepted no-op after authority checks.
+     * @param targetSessionId - the durable child session id to interrupt.
+     * @param authority - the human parent address or exact live ancestor Agent.
+     */
+    interrupt(targetSessionId: SessionId, authority: SubagentInterruptAuthority): void;
+    /** Deliver one resident continuable child's message to its live direct parent. */
+    private sendToParent;
+    /** Send one Agent message while translating only the target's own rejection. */
+    private sendAgentMessage;
+    /** Close manager-wide admission and release every live Activation. */
+    drain(): Promise<void>;
+    /**
+     * Stop only the continuable descendants of exact live host-owned parents.
+     * @param parents - exact live roots whose continuable descendants must stop.
+     */
+    drainDescendants(parents: readonly Agent[]): Promise<void>;
+    /**
+     * Release selected resident direct children of one exact live parent.
+     * @param parent - exact live direct parent authorizing the selected release.
+     * @param childIds - durable direct-child ids to release when resident.
+     */
+    drainChildren(parent: Agent, childIds: readonly SessionId[]): Promise<void>;
+    /**
+     * Cold-resume a persisted child and submit the waiting turn. The descriptor
+     * supplies every reconstruction input; no subagent provider is dispatched.
+     */
+    private coldResume;
+    /** 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 SubagentContinuationManager;
+//# sourceMappingURL=continuation.d.ts.map