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

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

package/lib/types/projection.js

@@ -0,0 +1,327 @@
+/** Team state projected incrementally from committed Session events, with a durable-only client view. */
+import { z } from 'zod';
+import { brandString } from '@qilin-agent/brand';
+import { TeamId as toTeamId, TeamMessageId as toTeamMessageId, TeamTaskId as toTeamTaskId, } from "./types.js";
+import { assertTaskGraphCandidate } from "./task-graph.js";
+import { projectTaskView } from "./task-view.js";
+const nonNegativeSafeInteger = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+const positiveSafeInteger = nonNegativeSafeInteger.min(1);
+const sessionIdSchema = z.string().min(1).transform(value => brandString(value));
+const teamIdSchema = z.string().min(1).transform(value => toTeamId(value));
+const numericTaskIdPattern = /^task-(\d+)$/u;
+const teamTaskIdSchema = z.string().min(1).refine((value) => {
+    const match = numericTaskIdPattern.exec(value);
+    return match === null || Number.isSafeInteger(Number(match[1]));
+}, { message: 'numeric task id suffix must be a safe integer' }).transform(value => toTeamTaskId(value));
+const teamMessageIdSchema = z.string().min(1).transform(value => toTeamMessageId(value));
+const coreContentBlockTypes = new Set(['text', 'reasoning', 'image', 'tool-call', 'tool-result']);
+const imageAttachmentSchema = z.object({
+    attachmentId: z.string().min(1),
+    mediaType: z.enum(['image/png', 'image/jpeg', 'image/webp', 'image/gif']),
+    bytes: nonNegativeSafeInteger,
+    width: positiveSafeInteger,
+    height: positiveSafeInteger,
+    name: z.string().optional(),
+}).strict();
+// Validate the listed variants; retired tool-result tags cannot enter the
+// merge-extensible fallback for JSON-decoded plugin content.
+const contentBlockSchema = z.lazy(() => z.union([
+    z.object({ type: z.literal('text'), text: z.string() }).strict(),
+    z.object({ type: z.literal('reasoning'), text: z.string() }).strict(),
+    z.object({ type: z.literal('image'), attachment: imageAttachmentSchema }).strict(),
+    z.object({
+        type: z.literal('tool-call'),
+        id: z.string().min(1),
+        name: z.string(),
+        arguments: z.string(),
+    }).strict(),
+    // Keep unknown JSON objects by reference; loose-object parsing drops their own __proto__ keys.
+    z.custom((value) => {
+        if (typeof value !== 'object' || value === null || Array.isArray(value))
+            return false;
+        const type = value.type;
+        return typeof type === 'string' && type.length > 0 && !coreContentBlockTypes.has(type);
+    }),
+]));
+const teamMemberSnapshotSchema = z.object({
+    id: sessionIdSchema,
+    name: z.string(),
+    description: z.string(),
+    provider: z.string(),
+    context: z.enum(['fresh', 'fork']),
+    phase: z.enum(['provisioning', 'active', 'failed']),
+    error: z.string().optional(),
+}).strict();
+const teamTaskSnapshotSchema = z.object({
+    id: teamTaskIdSchema,
+    revision: positiveSafeInteger,
+    subject: z.string(),
+    description: z.string(),
+    status: z.enum(['pending', 'in_progress', 'completed', 'deleted']),
+    ownerId: sessionIdSchema.optional(),
+    blockedBy: z.array(teamTaskIdSchema),
+    writeScopes: z.array(z.string()),
+}).strict();
+const teamMessageSnapshotSchema = z.object({
+    id: teamMessageIdSchema,
+    senderId: sessionIdSchema,
+    senderName: z.string(),
+    targetId: sessionIdSchema,
+    content: z.array(contentBlockSchema),
+}).strict();
+const teamEventSelectorSchema = z.object({
+    version: nonNegativeSafeInteger,
+    teamId: teamIdSchema,
+}).loose();
+const teamMemberEventSchema = z.object({
+    version: z.literal(2),
+    teamId: teamIdSchema,
+    member: teamMemberSnapshotSchema,
+}).strict();
+const teamTaskEventSchema = z.object({
+    version: z.literal(2),
+    teamId: teamIdSchema,
+    task: teamTaskSnapshotSchema,
+}).strict();
+const teamMessageQueuedEventSchema = z.object({
+    version: z.literal(2),
+    teamId: teamIdSchema,
+    message: teamMessageSnapshotSchema,
+}).strict();
+const teamMessageDeliveredEventSchema = z.object({
+    version: z.literal(2),
+    teamId: teamIdSchema,
+    messageId: teamMessageIdSchema,
+    targetId: sessionIdSchema,
+}).strict();
+/**
+ * Construct empty state for one Team identity.
+ * @param rootId - root Session identity.
+ * @returns empty Team state.
+ */
+export function emptyTeamState(rootId) {
+    return {
+        id: toTeamId(rootId),
+        members: [],
+        tasks: [],
+        messages: [],
+        delivered: [],
+        nextTaskNumber: 1,
+    };
+}
+const teamProjectionEntrySchema = z.object({
+    id: teamIdSchema,
+    members: z.array(teamMemberSnapshotSchema),
+    tasks: z.array(teamTaskSnapshotSchema),
+    messages: z.array(teamMessageSnapshotSchema),
+    delivered: z.array(teamMessageIdSchema),
+    nextTaskNumber: positiveSafeInteger,
+    failure: z.string().optional(),
+}).strict();
+/**
+ * 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 function isTeamEvent(event) {
+    return event.type === 'team/member'
+        || event.type === 'team/task'
+        || event.type === 'team/message/queued'
+        || event.type === 'team/message/delivered';
+}
+/** Decode one persisted Team value and retain the schema failure as its cause. */
+function parsePersisted(type, schema, value) {
+    try {
+        return schema.parse(value);
+    }
+    catch (error) {
+        throw new Error(`persisted Agent Teams ${type} payload is invalid`, { cause: error });
+    }
+}
+/** Decode the complete current-version payload selected by one Team event type. */
+function parseCurrentTeamEvent(event) {
+    switch (event.type) {
+        case 'team/member':
+            return { ...event, data: parsePersisted(event.type, teamMemberEventSchema, event.data) };
+        case 'team/task':
+            return { ...event, data: parsePersisted(event.type, teamTaskEventSchema, event.data) };
+        case 'team/message/queued':
+            return { ...event, data: parsePersisted(event.type, teamMessageQueuedEventSchema, event.data) };
+        case 'team/message/delivered':
+            return { ...event, data: parsePersisted(event.type, teamMessageDeliveredEventSchema, event.data) };
+        /* v8 ignore next 2 -- TeamEventType is closed and every member is handled above. */
+        default:
+            return event;
+    }
+}
+function applyProjectionEvent(state, event) {
+    if (state.failure !== undefined)
+        return state;
+    if (!isTeamEvent(event))
+        return state;
+    try {
+        const selector = parsePersisted(event.type, teamEventSelectorSchema, event.data);
+        if (selector.teamId !== state.id)
+            return state;
+        if (selector.version !== 2) {
+            throw new Error(`unsupported Agent Teams event version ${String(selector.version)}`);
+        }
+        return applyCurrentTeamEvent(state, parseCurrentTeamEvent(event));
+    }
+    catch (error) {
+        /* v8 ignore next -- the owned Team transition throws Error instances. */
+        return { ...state, failure: error instanceof Error ? error.message : String(error) };
+    }
+}
+function replaceAt(items, index, item) {
+    const next = [...items];
+    if (index < 0)
+        next.push(item);
+    else
+        next[index] = item;
+    return next;
+}
+function applyCurrentTeamEvent(state, event) {
+    switch (event.type) {
+        case 'team/member': {
+            const member = event.data.member;
+            const index = state.members.findIndex(candidate => candidate.id === member.id);
+            const prior = state.members[index];
+            const named = state.members.find(candidate => candidate.name === member.name);
+            if (named !== undefined && named.id !== member.id) {
+                throw new Error(`teammate name "${member.name}" is reused by another member`);
+            }
+            if (prior === undefined) {
+                if (member.phase !== 'provisioning')
+                    throw new Error(`teammate "${member.name}" must begin provisioning`);
+            }
+            else {
+                if (prior.name !== member.name || prior.provider !== member.provider || prior.context !== member.context) {
+                    throw new Error(`teammate "${member.id}" changed immutable identity fields`);
+                }
+                if (prior.phase !== 'provisioning' || member.phase === 'provisioning') {
+                    throw new Error(`teammate "${member.name}" has an invalid ${prior.phase} -> ${member.phase} transition`);
+                }
+            }
+            return { ...state, members: replaceAt(state.members, index, member) };
+        }
+        case 'team/task': {
+            const task = event.data.task;
+            const index = state.tasks.findIndex(candidate => candidate.id === task.id);
+            const prior = state.tasks[index];
+            if (prior === undefined && task.revision !== 1) {
+                throw new Error(`team task "${task.id}" must begin at revision 1`);
+            }
+            if (prior !== undefined && task.revision !== prior.revision + 1) {
+                throw new Error(`team task "${task.id}" revision is not contiguous`);
+            }
+            assertTaskGraphCandidate(state.tasks, task);
+            let nextTaskNumber = state.nextTaskNumber;
+            const match = numericTaskIdPattern.exec(task.id);
+            if (match !== null) {
+                const number = Number(match[1]);
+                nextTaskNumber = Math.max(nextTaskNumber, number === Number.MAX_SAFE_INTEGER ? number : number + 1);
+            }
+            return { ...state, tasks: replaceAt(state.tasks, index, task), nextTaskNumber };
+        }
+        case 'team/message/queued': {
+            const message = event.data.message;
+            if (state.messages.some(candidate => candidate.id === message.id)) {
+                throw new Error(`team message "${message.id}" was queued twice`);
+            }
+            return { ...state, messages: [...state.messages, message] };
+        }
+        case 'team/message/delivered': {
+            const queued = state.messages.find(message => message.id === event.data.messageId);
+            if (queued === undefined)
+                throw new Error(`team message "${event.data.messageId}" was delivered before queueing`);
+            if (queued.targetId !== event.data.targetId)
+                throw new Error(`team message "${event.data.messageId}" target changed`);
+            if (state.delivered.includes(event.data.messageId))
+                throw new Error(`team message "${event.data.messageId}" was delivered twice`);
+            return { ...state, delivered: [...state.delivered, event.data.messageId] };
+        }
+        /* v8 ignore next 2 -- TeamEventType is closed and every member is handled above. */
+        default:
+            return state;
+    }
+}
+const teamMemberProjectionSchema = z.object({
+    id: sessionIdSchema,
+    name: z.string(),
+    role: z.enum(['lead', 'teammate']),
+    phase: z.enum(['provisioning', 'active', 'failed']),
+    error: z.string().optional(),
+}).strict();
+const teamTaskViewSchema = z.object({
+    id: teamTaskIdSchema,
+    revision: positiveSafeInteger,
+    subject: z.string(),
+    description: z.string(),
+    status: z.enum(['pending', 'in_progress', 'completed', 'deleted']),
+    blockedBy: z.array(teamTaskIdSchema),
+    writeScopes: z.array(z.string()),
+    ownerName: z.string().optional(),
+    ready: z.boolean(),
+    writeScopeWarnings: z.array(z.string()),
+}).strict();
+const teamProjectionSchema = z.object({
+    members: z.array(teamMemberProjectionSchema),
+    tasks: z.array(teamTaskViewSchema),
+    failure: z.string().optional(),
+}).strict();
+/** Client views keyed by the member and task collections they were derived from. */
+const teamProjectionViews = new WeakMap();
+function buildTeamProjection(state) {
+    const rootId = brandString(state.id);
+    const members = [{ id: rootId, name: 'lead', role: 'lead', phase: 'active' }];
+    for (const member of state.members) {
+        members.push({
+            id: member.id,
+            name: member.name,
+            role: 'teammate',
+            phase: member.phase,
+            ...member.error === undefined ? {} : { error: member.error },
+        });
+    }
+    return {
+        members,
+        tasks: state.tasks
+            .filter(task => task.status !== 'deleted')
+            .map(task => projectTaskView(state, task)),
+        ...state.failure === undefined ? {} : { failure: state.failure },
+    };
+}
+/**
+ * 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 function teamProjectionView(state) {
+    if (state.failure !== undefined)
+        return buildTeamProjection(state);
+    let byTasks = teamProjectionViews.get(state.members);
+    if (byTasks === undefined) {
+        byTasks = new WeakMap();
+        teamProjectionViews.set(state.members, byTasks);
+    }
+    let view = byTasks.get(state.tasks);
+    if (view === undefined) {
+        view = buildTeamProjection(state);
+        byTasks.set(state.tasks, view);
+    }
+    return view;
+}
+/** Team projection selected by the projected Session identity; the wire view carries durable roster and task state only. */
+export const teamProjectionDefinition = {
+    key: 'agentTeam',
+    stateVersion: 4,
+    stateSchema: teamProjectionEntrySchema,
+    init: header => emptyTeamState(header.id),
+    apply: applyProjectionEvent,
+    wire: { viewSchema: teamProjectionSchema, view: teamProjectionView },
+};
+//# sourceMappingURL=projection.js.map

package/lib/types/remote.d.ts

@@ -0,0 +1,31 @@
+/** Wire failure mapping for the Team service's browser write face. */
+/** Wire details the Team domain carries on its catch-all refusal code. */
+export interface TeamRejectedFailureDetails {
+    /** The stable Team failure class, as the domain's `TeamError` code names it. */
+    readonly code: string;
+}
+declare module '@qilin-agent/typert-protocol' {
+    interface RemoteErrorDetailsMap {
+        /** The wire identity resolves to a Session that is not a Team member. */
+        'agent-team/not-a-member': {};
+        /**
+         * The compare-and-set revision no longer matches the durable task; the
+         * mutation was refused. The board projection carries the current revisions.
+         */
+        'agent-team/stale-revision': {};
+        /**
+         * The Team domain refused the request for a reason without a dedicated
+         * wire code; `code` names the stable Team failure class.
+         */
+        'agent-team/rejected': TeamRejectedFailureDetails;
+    }
+}
+/**
+ * Map one Team-domain failure onto the shared Remote failure vocabulary so the
+ * browser can branch on a stable code. Unknown values pass through unchanged
+ * and surface as `gateway/internal`.
+ * @param error - the value thrown by the Team domain operation.
+ * @returns the value to rethrow from the wire method.
+ */
+export declare function teamWireError(error: unknown): unknown;
+//# sourceMappingURL=remote.d.ts.map

package/lib/types/remote.js

@@ -0,0 +1,22 @@
+/** Wire failure mapping for the Team service's browser write face. */
+import { RemoteError } from '@qilin-agent/typert-protocol';
+import { TeamError } from "./error.js";
+/**
+ * Map one Team-domain failure onto the shared Remote failure vocabulary so the
+ * browser can branch on a stable code. Unknown values pass through unchanged
+ * and surface as `gateway/internal`.
+ * @param error - the value thrown by the Team domain operation.
+ * @returns the value to rethrow from the wire method.
+ */
+export function teamWireError(error) {
+    if (!(error instanceof TeamError))
+        return error;
+    if (error.code === 'TEAM_TASK_STALE_REVISION') {
+        return new RemoteError('agent-team/stale-revision', error.message, {});
+    }
+    if (error.code === 'TEAM_NOT_MEMBER') {
+        return new RemoteError('agent-team/not-a-member', error.message, {});
+    }
+    return new RemoteError('agent-team/rejected', error.message, { code: error.code });
+}
+//# sourceMappingURL=remote.js.map

package/lib/types/roster.d.ts

@@ -0,0 +1,107 @@
+/** Team membership, continuable-child provisioning, and roster-owned teardown. */
+import type { Context } from '@qilin-agent/kylin';
+import type { Agent } from '@qilin-agent/agent';
+import type { SessionId } from '@qilin-agent/session';
+import type { TeamJournal } from './journal.ts';
+import type { TeamRuntimeLifecycle } from './lifecycle.ts';
+import type { TeamState } from './projection.ts';
+import { TeamId } from './types.ts';
+import type { SpawnTeammateRequest, SpawnTeammateResult, TeamMemberView } from './types.ts';
+/** Caller identity inside one implicit Team. */
+export interface TeamMembership {
+    readonly root: Agent;
+    readonly id: TeamId;
+    readonly role: 'lead' | 'teammate';
+    readonly name: string;
+}
+/**
+ * Resolve one active Team member by model-facing name, including the Lead pseudo-row.
+ * @param root - exact live Team Lead.
+ * @param state - current Team state.
+ * @param rawName - candidate member name.
+ * @returns resolved durable id and normalized name.
+ */
+export declare function resolveActiveMember(root: Agent, state: TeamState, rawName: string): {
+    id: SessionId;
+    name: string;
+};
+/** Owns Team identities and the lifecycle of rostered continuable children. */
+export declare class TeamRoster {
+    private readonly ctx;
+    private readonly journal;
+    private readonly lifecycle;
+    private readonly maxMembers;
+    /**
+     * @param ctx - Team service context with Agent, Session, persistence, and subagent services.
+     * @param journal - authoritative Lead-log transaction owner.
+     * @param lifecycle - shared Team runtime admission cutoff.
+     * @param maxMembers - maximum immutable roster entries per Team.
+     */
+    constructor(ctx: Context, journal: TeamJournal, lifecycle: TeamRuntimeLifecycle, maxMembers: number);
+    /**
+     * 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: Agent): TeamMembership;
+    /**
+     * Resolve a caller without throwing for scoped installation and lifecycle observers.
+     * @param agent - candidate exact live Agent.
+     * @returns Team membership, or undefined for non-Team subagents and stale identities.
+     */
+    tryMembership(agent: Agent): TeamMembership | undefined;
+    /**
+     * List the runtime-enriched roster visible to one Team member.
+     * @param membership - exact caller membership resolved by this roster.
+     * @returns Lead and teammate rows in creation order.
+     */
+    list(membership: TeamMembership): TeamMemberView[];
+    /**
+     * 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.
+     */
+    spawn(caller: Agent, request: SpawnTeammateRequest): Promise<SpawnTeammateResult>;
+    /**
+     * Reconcile provisioning state when one Team member Session starts.
+     * @param agent - newly started exact live Agent.
+     * @param signal - shared runtime cancellation.
+     */
+    recoverFor(agent: Agent, signal: AbortSignal): Promise<void>;
+    /**
+     * 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: Agent, targetName: string): {
+        previousStatus: 'running' | 'inactive';
+    };
+    /**
+     * Group exact live roster children by their current Lead for runtime teardown.
+     * @returns each live Lead and the roster child ids currently in the Agent registry.
+     */
+    liveChildrenByRoot(): Map<Agent, SessionId[]>;
+    /**
+     * Release exact teammate Activations through the continuation lifecycle owner.
+     * @param root - exact live Team Lead authorizing release.
+     * @param childIds - selected roster child ids.
+     */
+    stopTeammates(root: Agent, childIds: readonly SessionId[]): Promise<void>;
+    /** Perform one creation admitted before the Team runtime disposal cutoff. */
+    private spawnAdmitted;
+    /** Flush the accepted initial inbox item before the Lead can commit `active`. */
+    private checkpointInitialPrompt;
+    /** Settle provisioning-only members from their independently durable child Sessions. */
+    private reconcileProvisioning;
+    /** Build one runtime member row after successful creation. */
+    private memberView;
+    /** Validate a never-reused model-facing teammate name. */
+    private memberName;
+    /** Append one terminal provisioning edge unless recovery already settled it. */
+    private settleProvisioning;
+    /** Whether a Session's own suffix identifies a provider-owned subagent child. */
+    private subagentDescriptor;
+}
+//# sourceMappingURL=roster.d.ts.map