@deepseek-ai/dsh-experimental-agent-team 0.1.5-alpha.2

package/lib/types/index.js

@@ -0,0 +1,313 @@
+/** Agent Teams service façade over roster, mailbox, task, and runtime lifecycle owners. */
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+import z from '@deepseek-ai/schemastery';
+import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import { TeamActivity } from "./activity.js";
+import { errorMessage, TeamError } from "./error.js";
+import { TeamJournal } from "./journal.js";
+import { TeamRuntimeLifecycle } from "./lifecycle.js";
+import { TeamMailbox } from "./mailbox.js";
+import { teamProjectionDefinition } from "./projection.js";
+import { TeamRoster } from "./roster.js";
+import { TeamTaskBoard } from "./task-board.js";
+import { TeamId } from "./types.js";
+export { TeamId, TeamMessageId, TeamTaskId } from "./types.js";
+export { TeamError } from "./error.js";
+const DEFAULT_MAX_MEMBERS = 8;
+const DEFAULT_MAX_TASKS = 256;
+const DEFAULT_MAX_PENDING_MESSAGES = 64;
+const DEFAULT_MAX_MESSAGE_BYTES = 65_536;
+const DEFAULT_DISPOSAL_TIMEOUT_MS = 5_000;
+/** Validate one positive safe-integer deployment limit. */
+function positiveLimit(name, value) {
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw new TeamError(`${name} must be a positive safe integer`, 'TEAM_INVALID_CONFIG');
+    }
+    return value;
+}
+/** Agent Teams service backed by the exact live Lead Session log. */
+let TeamService = (() => {
+    let _classSuper = TypertRemoteService;
+    let _instanceExtraInitializers = [];
+    let _remoteView_decorators;
+    let _remoteCreateTask_decorators;
+    let _remoteUpdateTask_decorators;
+    return class TeamService extends _classSuper {
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+            _remoteView_decorators = [Remote('view')];
+            _remoteCreateTask_decorators = [Remote('createTask')];
+            _remoteUpdateTask_decorators = [Remote('updateTask')];
+            __esDecorate(this, null, _remoteView_decorators, { kind: "method", name: "remoteView", static: false, private: false, access: { has: obj => "remoteView" in obj, get: obj => obj.remoteView }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _remoteCreateTask_decorators, { kind: "method", name: "remoteCreateTask", static: false, private: false, access: { has: obj => "remoteCreateTask" in obj, get: obj => obj.remoteCreateTask }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _remoteUpdateTask_decorators, { kind: "method", name: "remoteUpdateTask", static: false, private: false, access: { has: obj => "remoteUpdateTask" in obj, get: obj => obj.remoteUpdateTask }, metadata: _metadata }, null, _instanceExtraInitializers);
+            if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        }
+        static inject = ['agents', 'sessions', 'sessionPersistence', 'sessionProjections', 'subagents'];
+        static Config = z.object({
+            maxMembers: z.number().step(1).min(1).default(DEFAULT_MAX_MEMBERS),
+            maxTasks: z.number().step(1).min(1).default(DEFAULT_MAX_TASKS),
+            maxPendingMessagesPerMember: z.number().step(1).min(1).default(DEFAULT_MAX_PENDING_MESSAGES),
+            maxMessageBytes: z.number().step(1).min(1).default(DEFAULT_MAX_MESSAGE_BYTES),
+            disposalTimeoutMs: z.number().step(1).min(1).default(DEFAULT_DISPOSAL_TIMEOUT_MS),
+        });
+        /** Validated deployment limits used by every Team operation. */
+        config = __runInitializers(this, _instanceExtraInitializers);
+        activity;
+        lifecycle;
+        journal;
+        roster;
+        mailbox;
+        tasks;
+        constructor(ctx, config = {}) {
+            super(ctx, 'agentTeams');
+            this.config = {
+                maxMembers: positiveLimit('maxMembers', config.maxMembers ?? DEFAULT_MAX_MEMBERS),
+                maxTasks: positiveLimit('maxTasks', config.maxTasks ?? DEFAULT_MAX_TASKS),
+                maxPendingMessagesPerMember: positiveLimit('maxPendingMessagesPerMember', config.maxPendingMessagesPerMember ?? DEFAULT_MAX_PENDING_MESSAGES),
+                maxMessageBytes: positiveLimit('maxMessageBytes', config.maxMessageBytes ?? DEFAULT_MAX_MESSAGE_BYTES),
+                disposalTimeoutMs: positiveLimit('disposalTimeoutMs', config.disposalTimeoutMs ?? DEFAULT_DISPOSAL_TIMEOUT_MS),
+            };
+            this.activity = new TeamActivity();
+            this.lifecycle = new TeamRuntimeLifecycle(this.config.disposalTimeoutMs);
+            this.journal = new TeamJournal(ctx, (root) => { this.activity.notify(TeamId(root.id)); });
+            this.roster = new TeamRoster(ctx, this.journal, this.lifecycle, this.config.maxMembers);
+            this.mailbox = new TeamMailbox(ctx, this.journal, this.roster, this.lifecycle, this.config.maxPendingMessagesPerMember, this.config.maxMessageBytes);
+            this.tasks = new TeamTaskBoard(this.journal, this.config.maxTasks);
+            ctx.on('session/event', (session, event) => { this.mailbox.observeSessionEvent(session, event); });
+            ctx.on('agent/session-start', ({ agent }) => { this.scheduleRecovery(agent); });
+            ctx.on('agent/status', ({ agent }) => {
+                const membership = this.roster.tryMembership(agent);
+                if (membership !== undefined)
+                    this.activity.notify(membership.id);
+            });
+            ctx.effect(() => {
+                const disposeProjection = ctx.root.sessionProjections.register(teamProjectionDefinition);
+                return async () => {
+                    try {
+                        await this.disposeRuntime();
+                    }
+                    finally {
+                        disposeProjection();
+                    }
+                };
+            }, 'agentTeams.runtimeLifecycle()');
+            for (const agent of ctx.agents.list())
+                this.scheduleRecovery(agent);
+        }
+        /**
+         * Resolve one exact live Agent's Team role.
+         * @param agent - exact live Agent used as the authority credential.
+         * @returns its root, Team identity, role, and model-facing name.
+         */
+        membership(agent) {
+            return this.roster.membership(agent);
+        }
+        /**
+         * List the runtime-enriched roster visible to one Team member.
+         * @param agent - exact live Team member.
+         * @returns Lead and teammate rows in creation order.
+         */
+        listMembers(agent) {
+            return this.roster.list(this.roster.membership(agent));
+        }
+        /**
+         * Create one named, continuable direct child of the Team Lead.
+         * @param caller - exact live Lead Agent.
+         * @param request - immutable name, description, prompt, context mode, provider, and cancellation.
+         * @returns the active roster row.
+         */
+        async spawnTeammate(caller, request) {
+            return await this.roster.spawn(caller, request);
+        }
+        /**
+         * Queue one durable peer message, then attempt immediate delivery.
+         * @param caller - exact live sending Team member.
+         * @param request - target name, content, and pre-queue cancellation.
+         * @returns durable message identity and immediate-delivery observation.
+         */
+        async sendMessage(caller, request) {
+            return await this.mailbox.send(caller, request);
+        }
+        /**
+         * Create one unowned pending task in the Team Lead log.
+         * @param caller - exact live Team member creating the task.
+         * @param request - task text, blockers, and advisory write scopes.
+         * @returns the revision-one task view.
+         */
+        async createTask(caller, request) {
+            return await this.tasks.create(this.roster.membership(caller), request);
+        }
+        /**
+         * Return one task, including a deleted tombstone.
+         * @param caller - exact live Team member reading the task.
+         * @param id - Team-local task identity.
+         * @returns the latest task value and derived readiness diagnostics.
+         */
+        getTask(caller, id) {
+            return this.tasks.get(this.roster.membership(caller), id);
+        }
+        /**
+         * List current non-deleted tasks in numeric creation order.
+         * @param caller - exact live Team member reading the board.
+         * @returns detached current task views.
+         */
+        listTasks(caller) {
+            return this.tasks.list(this.roster.membership(caller));
+        }
+        /**
+         * Compare-and-set one authorized task transition.
+         * @param caller - exact live Team member authorizing the mutation.
+         * @param request - task identity, expected revision, action, and action fields.
+         * @returns the committed next task revision.
+         */
+        async updateTask(caller, request) {
+            return await this.tasks.update(caller, this.roster.membership(caller), request);
+        }
+        /**
+         * Wait for the next Team-domain or member-status change.
+         * @param caller - exact live Team member waiting for activity.
+         * @param timeoutMs - bounded wait duration from ten seconds through one hour.
+         * @param signal - caller cancellation for the wait only.
+         * @returns one observed change or a timeout result.
+         */
+        async waitForChange(caller, timeoutMs, signal) {
+            const membership = this.roster.membership(caller);
+            return await this.activity.wait(membership.id, timeoutMs, signal);
+        }
+        /**
+         * Interrupt one live teammate turn without clearing its pending inbox.
+         * @param caller - exact live Lead Agent.
+         * @param targetName - durable teammate name.
+         * @returns the target status sampled before cancellation.
+         */
+        interrupt(caller, targetName) {
+            return this.roster.interrupt(caller, targetName);
+        }
+        /**
+         * Resolve a caller without throwing, used by scoped-tool installation and observers.
+         * @param agent - candidate exact live Agent.
+         * @returns Team membership, or undefined for non-Team subagents and stale identities.
+         */
+        tryMembership(agent) {
+            return this.roster.tryMembership(agent);
+        }
+        /**
+         * Read the current roster and non-deleted task board through the generated Remote API.
+         * @param agent - exact live Team member used as the authority credential.
+         * @returns detached current roster and task views.
+         */
+        remoteView(agent) {
+            return {
+                members: this.listMembers(agent),
+                tasks: this.listTasks(agent),
+            };
+        }
+        /**
+         * Create one shared task through the generated Remote API.
+         * @param agent - exact live Team member creating the task.
+         * @param request - task text, blockers, and advisory write scopes.
+         * @returns the revision-one task or a typed Team rejection.
+         */
+        remoteCreateTask(agent, request) {
+            return this.taskMutationResult(this.createTask(agent, request));
+        }
+        /**
+         * Apply one task mutation and preserve Team rejections as business results.
+         * @param agent - exact live Team member authorizing the mutation.
+         * @param request - task identity, expected revision, action, and action fields.
+         * @returns the committed task or a typed Team rejection.
+         */
+        remoteUpdateTask(agent, request) {
+            return this.taskMutationResult(this.updateTask(agent, request));
+        }
+        /** Preserve Team task rejections while allowing unexpected failures to reject the Remote call. */
+        async taskMutationResult(operation) {
+            try {
+                return { ok: true, value: await operation };
+            }
+            catch (error) {
+                if (!(error instanceof TeamError))
+                    throw error;
+                return {
+                    ok: false,
+                    error: {
+                        code: error.code === 'TEAM_TASK_STALE_REVISION' ? 'team-task-conflict' : 'team-rejected',
+                        message: error.message,
+                    },
+                };
+            }
+        }
+        /** Queue one contained recovery pass after publication has unwound. */
+        scheduleRecovery(agent) {
+            queueMicrotask(() => {
+                if (this.lifecycle.disposed)
+                    return;
+                void this.recoverFor(agent).catch((error) => {
+                    if (this.lifecycle.disposed)
+                        return;
+                    this.ctx.logger.warn(`Agent Teams recovery for "${agent.id}" failed: ${errorMessage(error)}`);
+                });
+            });
+        }
+        /** Reconcile roster provisioning before retrying that member's pending mailbox. */
+        async recoverFor(agent) {
+            await this.roster.recoverFor(agent, this.lifecycle.signal);
+            await this.mailbox.recoverFor(agent, this.lifecycle.signal);
+        }
+        /** Stop Team-owned live branches and release every waiter before service disposal completes. */
+        async disposeRuntime() {
+            this.lifecycle.close();
+            this.activity.close();
+            const failures = [];
+            await this.lifecycle.settle(this.roster.pendingCreations(), failures);
+            await this.lifecycle.settle(this.mailbox.pendingDispatches(), failures);
+            for (const [root, childIds] of this.roster.liveChildrenByRoot()) {
+                try {
+                    await this.roster.stopTeammates(root, childIds);
+                }
+                catch (error) {
+                    failures.push(error);
+                }
+            }
+            if (failures.length > 0)
+                throw new AggregateError(failures, 'Agent Teams runtime disposal failed');
+        }
+    };
+})();
+export { TeamService };
+export default TeamService;
+//# sourceMappingURL=index.js.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,9 @@
+/** Agent Teams runtime invariant companion. */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "team-invariant";
+/** Invariant registry required by the companion. */
+export declare const inject: string[];
+/** Register the package invariant companion. */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/invariant.js

@@ -0,0 +1,26 @@
+/** Agent Teams runtime invariant companion. */
+import { isTeamEvent, teamProjectionDefinition, } from "./projection.js";
+const PACKAGE_NAME = '@deepseek-ai/dsh-experimental-agent-team';
+/** Cordis companion plugin name. */
+export const name = 'team-invariant';
+/** Invariant registry required by the companion. */
+export const inject = ['invariants'];
+/** Validate candidate Team events against the projected committed prefix. */
+const install = Object.assign((ctx, fail) => {
+    ctx.on('internal/dispatch', (_mode, eventName, args) => {
+        if (eventName !== 'session/event')
+            return;
+        const [session, event] = args;
+        /* v8 ignore next -- non-Team Session events have no Agent Teams invariant. */
+        if (!isTeamEvent(event))
+            return;
+        const state = ctx.sessionProjections.stateOf(session, 'agentTeam');
+        const candidate = teamProjectionDefinition.apply(structuredClone(state), event);
+        if (candidate.failure !== undefined) {
+            fail(`session event ${event.seq} violates the Agent Teams stream: ${candidate.failure}`);
+        }
+    }, { global: true });
+}, { inject: ['sessionProjections'] });
+/** Register the package invariant companion. */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//# sourceMappingURL=invariant.js.map

package/lib/types/journal.d.ts

@@ -0,0 +1,39 @@
+/** Serialized Team transactions over the exact live Lead Session log. */
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionEventMap, SessionId } from '@deepseek-ai/dsh-session';
+import type { TeamState } from './projection.ts';
+type MutableTeamEventType = 'team/member' | 'team/task' | 'team/message/queued' | 'team/message/delivered';
+/** Owns per-Lead transaction order and committed Team event publication. */
+export declare class TeamJournal {
+    private readonly ctx;
+    private readonly onCommit;
+    private readonly tails;
+    /**
+     * @param ctx - Team service context with the injected Session service.
+     * @param onCommit - synchronous notification after the Team event flush succeeds.
+     */
+    constructor(ctx: Context, onCommit: (root: Agent) => void);
+    /**
+     * Read authoritative Team state for one exact live Lead.
+     * @param root - exact live Team Lead.
+     * @returns current projected state selected by the Lead Team id.
+     */
+    state(root: Agent): TeamState;
+    /**
+     * Serialize one Lead's asynchronous mutation operation.
+     * @param rootId - Lead Session identity selecting the transaction queue.
+     * @param operation - complete read-check-append operation.
+     * @returns the operation result.
+     */
+    transact<T>(rootId: SessionId, operation: () => Promise<T>): Promise<T>;
+    /**
+     * Append and checkpoint one root-owned Team event before publication.
+     * @param root - exact live Lead whose Session owns the event.
+     * @param type - Team event discriminant.
+     * @param data - payload correlated with the event type.
+     */
+    appendAndFlush<T extends MutableTeamEventType>(root: Agent, type: T, data: SessionEventMap[T]): Promise<void>;
+}
+export {};
+//# sourceMappingURL=journal.d.ts.map

package/lib/types/journal.js

@@ -0,0 +1,63 @@
+/** Serialized Team transactions over the exact live Lead Session log. */
+/** Owns per-Lead transaction order and committed Team event publication. */
+export class TeamJournal {
+    ctx;
+    onCommit;
+    tails = new Map();
+    /**
+     * @param ctx - Team service context with the injected Session service.
+     * @param onCommit - synchronous notification after the Team event flush succeeds.
+     */
+    constructor(ctx, onCommit) {
+        this.ctx = ctx;
+        this.onCommit = onCommit;
+    }
+    /**
+     * Read authoritative Team state for one exact live Lead.
+     * @param root - exact live Team Lead.
+     * @returns current projected state selected by the Lead Team id.
+     */
+    state(root) {
+        const projection = this.ctx.sessionProjections.stateOf(root.session, 'agentTeam');
+        if (projection === undefined)
+            throw new Error('Agent Teams projection is not registered');
+        if (projection.failure !== undefined)
+            throw new Error(projection.failure);
+        return projection;
+    }
+    /**
+     * Serialize one Lead's asynchronous mutation operation.
+     * @param rootId - Lead Session identity selecting the transaction queue.
+     * @param operation - complete read-check-append operation.
+     * @returns the operation result.
+     */
+    async transact(rootId, operation) {
+        const prior = this.tails.get(rootId) ?? Promise.resolve();
+        const run = prior.then(operation, operation);
+        const tail = run.then(() => undefined, () => undefined);
+        this.tails.set(rootId, tail);
+        try {
+            return await run;
+        }
+        finally {
+            if (this.tails.get(rootId) === tail)
+                this.tails.delete(rootId);
+        }
+    }
+    /**
+     * Append and checkpoint one root-owned Team event before publication.
+     * @param root - exact live Lead whose Session owns the event.
+     * @param type - Team event discriminant.
+     * @param data - payload correlated with the event type.
+     */
+    async appendAndFlush(root, type, data) {
+        // Team events never enter the conversation surface. This narrower local
+        // capability removes Session.append's conditional surface argument while
+        // preserving the event-key/payload correlation.
+        const append = root.session.append.bind(root.session);
+        append(type, data);
+        await this.ctx.sessions.flush(root.session);
+        this.onCommit(root);
+    }
+}
+//# sourceMappingURL=journal.js.map

package/lib/types/lifecycle.d.ts

@@ -0,0 +1,33 @@
+/** Shared admission cutoff and bounded settlement for the Team runtime. */
+/** Owns the single Team runtime cancellation fact and disposal timeout. */
+export declare class TeamRuntimeLifecycle {
+    private readonly disposalTimeoutMs;
+    private readonly controller;
+    /**
+     * @param disposalTimeoutMs - maximum wait for one disposal settlement operation.
+     */
+    constructor(disposalTimeoutMs: number);
+    /** Signal aborted exactly when Team runtime admission closes. */
+    get signal(): AbortSignal;
+    /** Whether Team runtime admission is closed. */
+    get disposed(): boolean;
+    /** The exact cancellation reason used to distinguish expected disposal rejection. */
+    get reason(): unknown;
+    /** Whether a rejection is the runtime cancellation, directly or through an Error cause chain. */
+    private isCancellation;
+    /** Close Team runtime admission and cancel admitted interruptible work. */
+    close(): void;
+    /**
+     * Await admitted operations and retain failures other than runtime cancellation.
+     * @param operations - admitted operations captured after the admission cutoff.
+     * @param failures - aggregate destination for unexpected rejection or timeout.
+     */
+    settle(operations: readonly Promise<unknown>[], failures: unknown[]): Promise<void>;
+    /**
+     * Bound one runtime settlement operation.
+     * @param operation - settlement that may otherwise block HMR or process shutdown.
+     * @returns the operation result.
+     */
+    withTimeout<T>(operation: Promise<T>): Promise<T>;
+}
+//# sourceMappingURL=lifecycle.d.ts.map

package/lib/types/lifecycle.js

@@ -0,0 +1,85 @@
+/** Shared admission cutoff and bounded settlement for the Team runtime. */
+import { TeamError } from "./error.js";
+/** Owns the single Team runtime cancellation fact and disposal timeout. */
+export class TeamRuntimeLifecycle {
+    disposalTimeoutMs;
+    controller = new AbortController();
+    /**
+     * @param disposalTimeoutMs - maximum wait for one disposal settlement operation.
+     */
+    constructor(disposalTimeoutMs) {
+        this.disposalTimeoutMs = disposalTimeoutMs;
+    }
+    /** Signal aborted exactly when Team runtime admission closes. */
+    get signal() {
+        return this.controller.signal;
+    }
+    /** Whether Team runtime admission is closed. */
+    get disposed() {
+        return this.signal.aborted;
+    }
+    /** The exact cancellation reason used to distinguish expected disposal rejection. */
+    get reason() {
+        const reason = this.signal.reason;
+        return reason;
+    }
+    /** Whether a rejection is the runtime cancellation, directly or through an Error cause chain. */
+    isCancellation(reason) {
+        const seen = new Set();
+        let current = reason;
+        while (!seen.has(current)) {
+            if (this.disposed && current === this.reason)
+                return true;
+            if (this.disposed && current instanceof TeamError && current.code === 'TEAM_DISPOSED')
+                return true;
+            if (!(current instanceof Error))
+                return false;
+            seen.add(current);
+            current = current.cause;
+        }
+        return false;
+    }
+    /** Close Team runtime admission and cancel admitted interruptible work. */
+    close() {
+        this.controller.abort(new TeamError('Agent Teams service disposed', 'TEAM_DISPOSED'));
+    }
+    /**
+     * Await admitted operations and retain failures other than runtime cancellation.
+     * @param operations - admitted operations captured after the admission cutoff.
+     * @param failures - aggregate destination for unexpected rejection or timeout.
+     */
+    async settle(operations, failures) {
+        if (operations.length === 0)
+            return;
+        try {
+            const outcomes = await this.withTimeout(Promise.allSettled(operations));
+            for (const outcome of outcomes) {
+                if (outcome.status === 'rejected' && !this.isCancellation(outcome.reason))
+                    failures.push(outcome.reason);
+            }
+        }
+        catch (error) {
+            failures.push(error);
+        }
+    }
+    /**
+     * Bound one runtime settlement operation.
+     * @param operation - settlement that may otherwise block HMR or process shutdown.
+     * @returns the operation result.
+     */
+    async withTimeout(operation) {
+        let timer;
+        const timeout = new Promise((_resolve, reject) => {
+            timer = setTimeout(() => {
+                reject(new TeamError(`Agent Teams runtime disposal exceeded ${this.disposalTimeoutMs}ms`, 'TEAM_DISPOSAL_TIMEOUT'));
+            }, this.disposalTimeoutMs);
+        });
+        try {
+            return await Promise.race([operation, timeout]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+//# sourceMappingURL=lifecycle.js.map

package/lib/types/mailbox.d.ts

@@ -0,0 +1,78 @@
+/** Durable Team mailbox admission, target-local dispatch, acknowledgement, and recovery. */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session';
+import type { TeamJournal } from './journal.ts';
+import type { TeamRuntimeLifecycle } from './lifecycle.ts';
+import type { TeamRoster } from './roster.ts';
+import type { SendTeamMessageRequest, SendTeamMessageResult } from './types.ts';
+/** Owns every process-local state transition for the durable Team mailbox. */
+export declare class TeamMailbox {
+    private readonly ctx;
+    private readonly journal;
+    private readonly roster;
+    private readonly lifecycle;
+    private readonly maxPendingMessagesPerMember;
+    private readonly maxMessageBytes;
+    private readonly dispatchTails;
+    private readonly inFlightMessages;
+    private readonly inFlightDispatches;
+    /**
+     * @param ctx - Team service context with Agent, Session, persistence, and subagent services.
+     * @param journal - authoritative Lead-log transaction owner.
+     * @param roster - Team membership and member-name resolver.
+     * @param lifecycle - shared Team runtime admission cutoff.
+     * @param maxPendingMessagesPerMember - per-target queued-minus-delivered limit.
+     * @param maxMessageBytes - maximum complete sender-framed delivery size.
+     */
+    constructor(ctx: Context, journal: TeamJournal, roster: TeamRoster, lifecycle: TeamRuntimeLifecycle, maxPendingMessagesPerMember: number, maxMessageBytes: number);
+    /**
+     * Queue one durable peer message, then attempt immediate delivery.
+     * @param caller - exact live sending Team member.
+     * @param request - target name, content, and pre-queue cancellation.
+     * @returns durable message identity and immediate-delivery observation.
+     */
+    send(caller: Agent, request: SendTeamMessageRequest): Promise<SendTeamMessageResult>;
+    /**
+     * Observe target-side durable receipts and checkpoint their Lead-log acknowledgement.
+     * @param session - exact target Session receiving the event.
+     * @param event - newly appended Session event.
+     */
+    observeSessionEvent(session: Session, event: SessionEvent): void;
+    /**
+     * Retry durable pending messages relevant to one started Team member.
+     * @param agent - newly started exact live Agent.
+     * @param signal - shared runtime cancellation.
+     */
+    recoverFor(agent: Agent, signal: AbortSignal): Promise<void>;
+    /**
+     * Return admitted dispatch and acknowledgement operations captured for disposal.
+     * @returns detached snapshot ordered only by Set insertion.
+     */
+    pendingDispatches(): readonly Promise<unknown>[];
+    /** Queue and dispatch one mailbox item admitted before the disposal cutoff. */
+    private sendAdmitted;
+    /** Attempt one queued message exactly once in this process at a time. */
+    private tryDispatch;
+    /** Track one dispatch transaction through delivery admission or contained failure. */
+    private trackDispatch;
+    /** Attempt one queued message admitted before the service lifecycle cutoff. */
+    private tryDispatchAdmitted;
+    /** Serialize delivery admission for one durable target in queued order. */
+    private serializeDispatch;
+    /** Deliver every pending target message through `message` in durable queue order. */
+    private dispatchThrough;
+    /** Attempt one queued delivery after target-local ordering admits it. */
+    private dispatchOnce;
+    /** Flush one live target receipt before the Lead records its delivered edge. */
+    private checkpointDelivered;
+    /** Record delivery unless the acknowledgement already exists. */
+    private markDelivered;
+    /** Whether a target Session already contains the durable message identity. */
+    private targetRecorded;
+    /** Frame peer content with stable sender and message identity for the receiving model. */
+    private deliveryContent;
+    /** Read an inactive target's durable log before cold resume; uncertainty keeps the mailbox queued. */
+    private persistedTargetRecorded;
+}
+//# sourceMappingURL=mailbox.d.ts.map