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

package/lib/types/mailbox.js

@@ -0,0 +1,293 @@
+/** Durable Team mailbox admission, target-local dispatch, acknowledgement, and recovery. */
+import { randomUUID } from 'node:crypto';
+import { brandString } from '@qilin-agent/brand';
+import { createUserMessage } from '@qilin-agent/llm';
+import { steerHostSubagentPrompt } from '@qilin-agent/subagent/internal';
+import { errorMessage, TeamError } from "./error.js";
+import { readPersistedSession } from "./persisted.js";
+import { resolveActiveMember } from "./roster.js";
+import { messageAccepted } from "./session-message.js";
+import { TeamId, TeamMessageId } from "./types.js";
+/** Owns every process-local state transition for the durable Team mailbox. */
+export class TeamMailbox {
+    ctx;
+    journal;
+    roster;
+    lifecycle;
+    maxPendingMessagesPerMember;
+    maxMessageBytes;
+    dispatchTails = new Map();
+    inFlightMessages = new Set();
+    inFlightDispatches = new Set();
+    /**
+     * @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, journal, roster, lifecycle, maxPendingMessagesPerMember, maxMessageBytes) {
+        this.ctx = ctx;
+        this.journal = journal;
+        this.roster = roster;
+        this.lifecycle = lifecycle;
+        this.maxPendingMessagesPerMember = maxPendingMessagesPerMember;
+        this.maxMessageBytes = maxMessageBytes;
+    }
+    /**
+     * 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 send(caller, request) {
+        if (this.lifecycle.disposed)
+            throw new TeamError('Agent Teams service is disposing', 'TEAM_DISPOSED');
+        const operation = this.sendAdmitted(caller, {
+            ...request,
+            signal: AbortSignal.any([request.signal, this.lifecycle.signal]),
+        });
+        return await this.trackDispatch(operation);
+    }
+    /**
+     * 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, event) {
+        if (this.lifecycle.disposed || event.type !== 'user/message' || event.data.source.kind !== 'team-message')
+            return;
+        const source = event.data.source;
+        const acknowledgement = Promise.resolve().then(async () => {
+            const root = this.ctx.agents.get(brandString(source.teamId));
+            if (root !== undefined)
+                await this.checkpointDelivered(root, session, source.messageId);
+        }).catch((error) => {
+            this.ctx.logger.warn(`Team message "${source.messageId}" acknowledgement failed: ${errorMessage(error)}`);
+        });
+        void this.trackDispatch(acknowledgement);
+    }
+    /**
+     * Retry durable pending messages relevant to one started Team member.
+     * @param agent - newly started exact live Agent.
+     * @param signal - shared runtime cancellation.
+     */
+    async recoverFor(agent, signal) {
+        signal.throwIfAborted();
+        const membership = this.roster.tryMembership(agent);
+        if (membership === undefined)
+            return;
+        const state = this.journal.state(membership.root);
+        const messages = state.messages.filter(message => !state.delivered.includes(message.id)
+            && (membership.role === 'lead' || message.targetId === agent.id));
+        for (const message of messages) {
+            signal.throwIfAborted();
+            await this.tryDispatch(membership.root, message, signal);
+        }
+    }
+    /**
+     * Return admitted dispatch and acknowledgement operations captured for disposal.
+     * @returns detached snapshot ordered only by Set insertion.
+     */
+    pendingDispatches() {
+        return [...this.inFlightDispatches];
+    }
+    /** Queue and dispatch one mailbox item admitted before the disposal cutoff. */
+    async sendAdmitted(caller, request) {
+        const membership = this.roster.membership(caller);
+        request.signal.throwIfAborted();
+        const root = membership.root;
+        const content = structuredClone(request.content);
+        const queued = await this.journal.transact(root.id, async () => {
+            request.signal.throwIfAborted();
+            const state = this.journal.state(root);
+            const target = resolveActiveMember(root, state, request.target);
+            if (target.id === caller.id)
+                throw new TeamError('a Team member cannot message itself', 'TEAM_SELF_MESSAGE');
+            const pendingForTarget = state.messages.filter(candidate => candidate.targetId === target.id && !state.delivered.includes(candidate.id)).length;
+            if (pendingForTarget >= this.maxPendingMessagesPerMember) {
+                throw new TeamError(`teammate "${target.name}" has ${pendingForTarget} pending messages`, 'TEAM_MAILBOX_FULL');
+            }
+            const queued = {
+                id: TeamMessageId(`team-message-${randomUUID()}`),
+                senderId: caller.id,
+                senderName: membership.name,
+                targetId: target.id,
+                content,
+            };
+            if (Buffer.byteLength(JSON.stringify(this.deliveryContent(queued)), 'utf8') > this.maxMessageBytes) {
+                throw new TeamError(`team message exceeds ${this.maxMessageBytes} bytes`, 'TEAM_MESSAGE_TOO_LARGE');
+            }
+            await this.journal.appendAndFlush(root, 'team/message/queued', {
+                version: 2,
+                teamId: TeamId(root.id),
+                message: queued,
+            });
+            // Register dispatch before releasing the root transaction so concurrent
+            // senders enter the target-local queue in durable mailbox order.
+            return { message: queued, dispatch: this.tryDispatch(root, queued, request.signal) };
+        });
+        const accepted = await queued.dispatch;
+        return { messageId: queued.message.id, status: accepted ? 'accepted' : 'queued' };
+    }
+    /** Attempt one queued message exactly once in this process at a time. */
+    tryDispatch(root, message, signal) {
+        if (this.lifecycle.disposed)
+            return Promise.resolve(false);
+        if (this.inFlightMessages.has(message.id))
+            return Promise.resolve(false);
+        this.inFlightMessages.add(message.id);
+        const operation = this.trackDispatch(this.tryDispatchAdmitted(root, message, AbortSignal.any([signal, this.lifecycle.signal])));
+        const forget = () => {
+            this.inFlightMessages.delete(message.id);
+        };
+        void operation.then(forget, forget);
+        return operation;
+    }
+    /** Track one dispatch transaction through delivery admission or contained failure. */
+    trackDispatch(operation) {
+        this.inFlightDispatches.add(operation);
+        void operation.then(() => {
+            this.inFlightDispatches.delete(operation);
+        }, () => {
+            this.inFlightDispatches.delete(operation);
+        });
+        return operation;
+    }
+    /** Attempt one queued message admitted before the service lifecycle cutoff. */
+    async tryDispatchAdmitted(root, message, signal) {
+        return await this.serializeDispatch(message, () => this.dispatchThrough(root, message, signal));
+    }
+    /** Serialize delivery admission for one durable target in queued order. */
+    async serializeDispatch(message, operation) {
+        const targetId = message.targetId;
+        const prior = this.dispatchTails.get(targetId) ?? Promise.resolve();
+        /* v8 ignore next -- dispatch tails absorb rejection, so the recovery callback is a fail-safe backstop. */
+        const run = prior.then(operation, operation);
+        /* v8 ignore next -- dispatchOnce contains delivery failures and serializeDispatch itself does not throw. */
+        const tail = run.then(() => undefined, () => undefined);
+        this.dispatchTails.set(targetId, tail);
+        try {
+            return await run;
+        }
+        finally {
+            if (this.dispatchTails.get(targetId) === tail)
+                this.dispatchTails.delete(targetId);
+        }
+    }
+    /** Deliver every pending target message through `message` in durable queue order. */
+    async dispatchThrough(root, message, signal) {
+        const state = this.journal.state(root);
+        const pending = state.messages.filter(candidate => candidate.targetId === message.targetId && !state.delivered.includes(candidate.id));
+        const requested = pending.findIndex(candidate => candidate.id === message.id);
+        if (requested < 0)
+            return state.delivered.includes(message.id);
+        for (const candidate of pending.slice(0, requested + 1)) {
+            const ownsInFlight = !this.inFlightMessages.has(candidate.id);
+            if (ownsInFlight)
+                this.inFlightMessages.add(candidate.id);
+            try {
+                if (!await this.dispatchOnce(root, candidate, signal))
+                    return false;
+            }
+            finally {
+                if (ownsInFlight)
+                    this.inFlightMessages.delete(candidate.id);
+            }
+        }
+        return true;
+    }
+    /** Attempt one queued delivery after target-local ordering admits it. */
+    async dispatchOnce(root, message, signal) {
+        try {
+            const target = message.targetId === root.id ? root : this.ctx.agents.get(message.targetId);
+            if (target !== undefined && this.targetRecorded(target.session, message.id)) {
+                return await this.checkpointDelivered(root, target.session, message.id);
+            }
+            const source = {
+                kind: 'team-message',
+                teamId: TeamId(root.id),
+                messageId: message.id,
+                senderId: message.senderId,
+                senderName: message.senderName,
+            };
+            const content = this.deliveryContent(message);
+            if (message.targetId === root.id) {
+                const input = createUserMessage({ content, source });
+                root.steer(input);
+                return await this.checkpointDelivered(root, root.session, message.id);
+            }
+            if (target === undefined) {
+                const recorded = await this.persistedTargetRecorded(message.targetId, message.id, signal);
+                if (recorded === undefined)
+                    return false;
+                if (recorded) {
+                    await this.markDelivered(root, message.id, message.targetId);
+                    return true;
+                }
+            }
+            await steerHostSubagentPrompt(this.ctx.subagents, root, message.targetId, content, source, signal);
+            return target === undefined
+                ? true
+                : await this.checkpointDelivered(root, target.session, message.id);
+        }
+        catch (error) {
+            this.ctx.logger.warn(`team message "${message.id}" remains queued: ${errorMessage(error)}`);
+            return false;
+        }
+    }
+    /** Flush one live target receipt before the Lead records its delivered edge. */
+    async checkpointDelivered(root, target, messageId) {
+        await this.ctx.sessions.flush(target);
+        if (!this.targetRecorded(target, messageId))
+            return false;
+        await this.markDelivered(root, messageId, target.id);
+        return true;
+    }
+    /** Record delivery unless the acknowledgement already exists. */
+    async markDelivered(root, messageId, targetId) {
+        await this.journal.transact(root.id, async () => {
+            const state = this.journal.state(root);
+            if (state.delivered.includes(messageId))
+                return;
+            const queued = state.messages.find(message => message.id === messageId);
+            if (queued === undefined || queued.targetId !== targetId)
+                return;
+            await this.journal.appendAndFlush(root, 'team/message/delivered', {
+                version: 2,
+                teamId: TeamId(root.id),
+                messageId,
+                targetId,
+            });
+        });
+    }
+    /** Whether a target Session already contains the durable message identity. */
+    targetRecorded(session, messageId) {
+        // oxlint-disable-next-line typescript/no-deprecated -- Existing Session history read; migration deferred.
+        const suffix = session.snapshotEvents(session.inheritedEventCount);
+        return messageAccepted(suffix, message => message.source.kind === 'team-message'
+            && message.source.messageId === messageId);
+    }
+    /** Frame peer content with stable sender and message identity for the receiving model. */
+    deliveryContent(message) {
+        return [
+            { type: 'text', text: `Team message ${message.id} from ${message.senderName}:` },
+            ...structuredClone(message.content),
+        ];
+    }
+    /** Read an inactive target's durable log before cold resume; uncertainty keeps the mailbox queued. */
+    async persistedTargetRecorded(targetId, messageId, signal) {
+        try {
+            const stored = await readPersistedSession(this.ctx.sessionPersistence, targetId, signal);
+            const suffix = stored.events.slice(stored.inheritedEventCount);
+            return messageAccepted(suffix, message => message.source.kind === 'team-message'
+                && message.source.messageId === messageId);
+        }
+        catch (error) {
+            this.ctx.logger.warn(`cannot read Team message target "${targetId}": ${errorMessage(error)}`);
+            return undefined;
+        }
+    }
+}
+//# sourceMappingURL=mailbox.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

package/lib/types/projection.d.ts

@@ -0,0 +1,66 @@
+/** Team state projected incrementally from committed Session events, with a durable-only client view. */
+import { z } from 'zod';
+import type { SessionEvent, SessionId } from '@qilin-agent/session';
+import type { TeamId, TeamMemberSnapshot, TeamMessageId, TeamMessageSnapshot, TeamProjection, TeamTaskSnapshot } from './types.ts';
+/**
+ * Current Team state selected by durable Team identity. Every applied Team
+ * event produces a new state object and replaces only the collection it
+ * touched; untouched collections keep their references.
+ */
+export interface TeamState {
+    readonly id: TeamId;
+    readonly members: readonly TeamMemberSnapshot[];
+    readonly tasks: readonly TeamTaskSnapshot[];
+    readonly messages: readonly TeamMessageSnapshot[];
+    readonly delivered: readonly TeamMessageId[];
+    readonly nextTaskNumber: number;
+}
+/**
+ * Construct empty state for one Team identity.
+ * @param rootId - root Session identity.
+ * @returns empty Team state.
+ */
+export declare function emptyTeamState(rootId: SessionId): TeamProjectionState;
+/** Checkpoint-safe state for the Team owned by the projected Session. */
+export interface TeamProjectionState extends TeamState {
+    readonly failure?: string;
+}
+declare module '@qilin-agent/session-projection/types' {
+    interface SessionProjectionStateMap {
+        agentTeam: TeamProjectionState;
+    }
+}
+/** Whether one event belongs to the Team domain. */
+export type TeamEventType = 'team/member' | 'team/task' | 'team/message/queued' | 'team/message/delivered';
+/** One event owned by the Team domain. */
+type TeamSessionEvent = SessionEvent<TeamEventType>;
+/**
+ * Test whether a Session event belongs to the Team domain.
+ * @param event - candidate Session event.
+ * @returns whether the event has a Team-owned type.
+ */
+export declare function isTeamEvent(event: SessionEvent): event is TeamSessionEvent;
+declare function applyProjectionEvent(state: TeamProjectionState, event: SessionEvent): TeamProjectionState;
+/**
+ * Durable client view of one Team state. Mailbox-only state changes reuse the
+ * previous view reference, so the live drive publishes nothing for them.
+ * A failure is terminal: later events retain the failed state reference and
+ * do not republish its view.
+ * @param state - current Team state.
+ * @returns the roster and non-deleted task board, plus any projection failure.
+ */
+export declare function teamProjectionView(state: TeamProjectionState): TeamProjection;
+/** Team projection selected by the projected Session identity; the wire view carries durable roster and task state only. */
+export declare const teamProjectionDefinition: {
+    key: "agentTeam";
+    stateVersion: number;
+    stateSchema: z.ZodType<TeamProjectionState, unknown, z.core.$ZodTypeInternals<TeamProjectionState, unknown>>;
+    init: (header: import("@qilin-agent/session").SessionHeader) => TeamProjectionState;
+    apply: typeof applyProjectionEvent;
+    wire: {
+        viewSchema: z.ZodType<TeamProjection, unknown, z.core.$ZodTypeInternals<TeamProjection, unknown>>;
+        view: typeof teamProjectionView;
+    };
+};
+export {};
+//# sourceMappingURL=projection.d.ts.map