@qilin-agent/experimental-agent-team 0.0.0-stage → 3.1.4

package/lib/types/index.js

@@ -0,0 +1,340 @@
+/** Agent Teams service façade over roster, messaging, 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 { randomUUID } from 'node:crypto';
+import z from '@qilin-agent/schemastery';
+import { createUserMessage } from '@qilin-agent/llm';
+import { steerHostSubagentPrompt } from '@qilin-agent/subagent/internal';
+import { Remote, TypertRemoteService } from '@qilin-agent/typert-protocol';
+import { TeamActivity } from "./activity.js";
+import { errorMessage, TeamError } from "./error.js";
+import { TeamJournal } from "./journal.js";
+import { TeamRuntimeLifecycle } from "./lifecycle.js";
+import { teamProjectionDefinition } from "./projection.js";
+import { teamWireError } from "./remote.js";
+import { resolveActiveMember, TeamRoster } from "./roster.js";
+import { TeamTaskBoard } from "./task-board.js";
+import { TeamId, TeamMessageId } from "./types.js";
+export { TeamId, TeamMessageId, TeamTaskId } from "./types.js";
+export { TeamError } from "./error.js";
+const DEFAULT_MAX_MEMBERS = 16;
+const DEFAULT_MAX_TASKS = 256;
+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. `createTask`
+ * and `updateTask` also carry the browser write bridge through the `agentTeams`
+ * Typert Remote namespace; the wire faces map domain failures onto the shared
+ * Remote failure vocabulary without changing the domain methods' contracts.
+ */
+let TeamService = (() => {
+    let _classSuper = TypertRemoteService;
+    let _instanceExtraInitializers = [];
+    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;
+            _remoteCreateTask_decorators = [Remote('createTask')];
+            _remoteUpdateTask_decorators = [Remote('updateTask')];
+            __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),
+            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;
+        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),
+                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.tasks = new TeamTaskBoard(this.journal, this.config.maxTasks);
+            ctx.on('agent/created', ({ 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);
+        }
+        /**
+         * Steer one peer message into the target inbox or reject the attempt.
+         * @param caller - exact live sending Team member.
+         * @param request - target name, content, and cancellation before acceptance.
+         * @returns accepted inbox identity; acceptance follows normal Agent persistence and does not await model processing.
+         */
+        async sendMessage(caller, request) {
+            if (this.lifecycle.disposed)
+                throw new TeamError('Agent Teams service is disposing', 'TEAM_DISPOSED');
+            return await this.lifecycle.track(this.sendAdmitted(caller, {
+                ...request,
+                signal: AbortSignal.any([request.signal, this.lifecycle.signal]),
+            }));
+        }
+        /**
+         * Admit one peer message and steer it into the target's inbox.
+         * @param caller - exact live sending Team member.
+         * @param request - target name, content, and signal already joined with runtime cancellation.
+         * @returns the durable message identity carried by the delivered source.
+         */
+        async sendAdmitted(caller, request) {
+            const membership = this.roster.membership(caller);
+            request.signal.throwIfAborted();
+            const { root } = membership;
+            const target = resolveActiveMember(root, this.journal.state(root), request.target);
+            if (target.id === caller.id)
+                throw new TeamError('a Team member cannot message itself', 'TEAM_SELF_MESSAGE');
+            const messageId = TeamMessageId(`team-message-${randomUUID()}`);
+            const source = {
+                kind: 'team-message',
+                teamId: TeamId(root.id),
+                messageId,
+                senderId: caller.id,
+                senderName: membership.name,
+            };
+            const content = [
+                { type: 'text', text: `Team message ${messageId} from ${membership.name}:` },
+                ...structuredClone(request.content),
+            ];
+            if (Buffer.byteLength(JSON.stringify(content), 'utf8') > this.config.maxMessageBytes) {
+                throw new TeamError(`team message exceeds ${this.config.maxMessageBytes} bytes`, 'TEAM_MESSAGE_TOO_LARGE');
+            }
+            if (target.id === root.id)
+                root.steer(createUserMessage({ content, source }));
+            else
+                await steerHostSubagentPrompt(this.ctx.subagents, root, target.id, content, source, request.signal);
+            this.activity.notify(membership.id);
+            return { messageId };
+        }
+        /**
+         * 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);
+        }
+        /**
+         * Wire face of {@link TeamService.createTask}: create one shared task on a
+         * person's behalf through the browser write bridge.
+         * @param agent - exact live Team member resolved from the wire identity.
+         * @param request - subject, description, optional blockers, and optional write scopes.
+         * @returns the revision-one task view.
+         * @throws {RemoteError} `agent-team/not-a-member` when the identity is not a Team member, and
+         *   `agent-team/rejected` when the domain refuses the request.
+         */
+        async remoteCreateTask(agent, request) {
+            try {
+                return await this.createTask(agent, request);
+            }
+            catch (error) {
+                throw teamWireError(error);
+            }
+        }
+        /**
+         * Wire face of {@link TeamService.updateTask}: commit one compare-and-set
+         * task transition on a person's behalf. A committed mutation is durable and
+         * never undone by a later wire cancellation.
+         * @param agent - exact live Team member resolved from the wire identity.
+         * @param request - task identity, expected revision, action, and action fields.
+         * @returns the committed next task view.
+         * @throws {RemoteError} `agent-team/not-a-member` when the identity is not a Team member,
+         *   `agent-team/stale-revision` when the expected revision no longer matches, and
+         *   `agent-team/rejected` when the domain refuses the transition.
+         */
+        async remoteUpdateTask(agent, request) {
+            try {
+                return await this.updateTask(agent, request);
+            }
+            catch (error) {
+                throw teamWireError(error);
+            }
+        }
+        /**
+         * 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);
+        }
+        /** 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 when one Team member Session starts. */
+        async recoverFor(agent) {
+            await this.roster.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.lifecycle.pending(), 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/journal.d.ts

@@ -0,0 +1,39 @@
+/** Serialized Team transactions over the exact live Lead Session log. */
+import type { Agent } from '@qilin-agent/agent';
+import type { Context } from '@qilin-agent/kylin';
+import type { SessionEventMap, SessionId } from '@qilin-agent/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,45 @@
+/** 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 operations;
+    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;
+    /**
+     * Track an admitted send or complete creation transaction until it settles.
+     * @param operation - asynchronous work owned by this runtime.
+     * @returns the same operation.
+     */
+    track<T>(operation: Promise<T>): Promise<T>;
+    /**
+     * Capture outstanding operations after closing admission.
+     * @returns admitted work still awaiting settlement.
+     */
+    pending(): readonly Promise<unknown>[];
+    /**
+     * 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,103 @@
+/** 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;
+    operations = new Set();
+    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'));
+    }
+    /**
+     * Track an admitted send or complete creation transaction until it settles.
+     * @param operation - asynchronous work owned by this runtime.
+     * @returns the same operation.
+     */
+    track(operation) {
+        this.operations.add(operation);
+        void operation.then(() => { this.operations.delete(operation); }, () => { this.operations.delete(operation); });
+        return operation;
+    }
+    /**
+     * Capture outstanding operations after closing admission.
+     * @returns admitted work still awaiting settlement.
+     */
+    pending() {
+        return [...this.operations];
+    }
+    /**
+     * 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/persisted.d.ts

@@ -0,0 +1,20 @@
+/** Short-lived read-handle access to persisted Team member Sessions. */
+import type { SessionEvent, SessionHeader, SessionId, SessionLogOffset } from '@qilin-agent/session';
+import type { SessionPersistence } from '@qilin-agent/session-persistence';
+/** One persisted Session's detached header and complete committed event log. */
+export interface PersistedSessionView {
+    /** Exact fork-inherited event count paired with `header`. */
+    readonly inheritedEventCount: SessionLogOffset;
+    readonly header: SessionHeader;
+    readonly events: readonly SessionEvent[];
+}
+/**
+ * Read one stored session's header and complete event log through a
+ * short-lived read handle, closing the handle before returning.
+ * @param persistence - the durable session store.
+ * @param id - the stored session to read.
+ * @param signal - cancellation observed by open and read.
+ * @returns the stored header and every committed event.
+ */
+export declare function readPersistedSession(persistence: SessionPersistence, id: SessionId, signal: AbortSignal): Promise<PersistedSessionView>;
+//# sourceMappingURL=persisted.d.ts.map

package/lib/types/persisted.js

@@ -0,0 +1,20 @@
+/** Short-lived read-handle access to persisted Team member Sessions. */
+/**
+ * Read one stored session's header and complete event log through a
+ * short-lived read handle, closing the handle before returning.
+ * @param persistence - the durable session store.
+ * @param id - the stored session to read.
+ * @param signal - cancellation observed by open and read.
+ * @returns the stored header and every committed event.
+ */
+export async function readPersistedSession(persistence, id, signal) {
+    const handle = await persistence.open(id, 'read', { signal });
+    try {
+        const { events } = await handle.read(0, undefined, { signal });
+        return { header: handle.header, inheritedEventCount: handle.inheritedEventCount, events };
+    }
+    finally {
+        await handle.close();
+    }
+}
+//# sourceMappingURL=persisted.js.map