@cuylabs/agent-core 4.9.0 → 4.10.0

package/dist/team/mailbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mailbox.d.ts","sourceRoot":"","sources":["../../src/team/mailbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAM3E;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,WAAW,GAAG,WAAW,EAAE,CAAC;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,8CAA8C;IAC9C,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE/E;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,IAAI,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,MAAM,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IACnD,IAAI,CAAC,MAAM,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;CAC1D;AA6BD;;GAEG;AACH,qBAAa,oBAAqB,YAAW,YAAY;IACvD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAExC,MAAM,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IAMlD,IAAI,CAAC,MAAM,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;CAmB/D;AAMD;;GAEG;AACH,qBAAa,OAAO;IAClB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAgC;IAC5D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;gBAE5B,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,YAAY,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,MAAM,CAAA;KAAE;IAKjE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B;;OAEG;IACG,IAAI,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IA2BrD;;OAEG;IACG,IAAI,CAAC,MAAM,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAI9D;;OAEG;IACH,SAAS,CAAC,UAAU,EAAE,iBAAiB,GAAG,MAAM,IAAI;CAMrD"}

package/dist/team/notifications.d.ts

@@ -0,0 +1,23 @@
+import type { TeamTask } from "./types.js";
+import type { TeamEvent } from "./events.js";
+export type NotificationPriority = "immediate" | "deferred";
+export type CoordinatorNotificationKind = "worker-report" | "task-result" | "permission-forwarded" | "permission-resolved" | "shutdown-requested" | "shutdown-resolved";
+export interface CoordinatorNotification {
+    id: string;
+    teamId: string;
+    memberId: string;
+    kind: CoordinatorNotificationKind;
+    priority: NotificationPriority;
+    title: string;
+    body: string;
+    createdAt: string;
+    taskId?: string;
+    status?: TeamTask["status"];
+}
+export interface TeamNotificationEvent {
+    type: "team-notification";
+    teamId: string;
+    notification: CoordinatorNotification;
+}
+export declare function buildCoordinatorNotificationEvent(event: TeamEvent, resolveTask: (taskId: string) => Promise<TeamTask | undefined>): Promise<TeamNotificationEvent | null>;
+//# sourceMappingURL=notifications.d.ts.map

package/dist/team/notifications.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notifications.d.ts","sourceRoot":"","sources":["../../src/team/notifications.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EASV,SAAS,EACV,MAAM,aAAa,CAAC;AAErB,MAAM,MAAM,oBAAoB,GAAG,WAAW,GAAG,UAAU,CAAC;AAE5D,MAAM,MAAM,2BAA2B,GACnC,eAAe,GACf,aAAa,GACb,sBAAsB,GACtB,qBAAqB,GACrB,oBAAoB,GACpB,mBAAmB,CAAC;AAExB,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,2BAA2B,CAAC;IAClC,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC;CAC7B;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,mBAAmB,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,uBAAuB,CAAC;CACvC;AA4KD,wBAAsB,iCAAiC,CACrD,KAAK,EAAE,SAAS,EAChB,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,GAC7D,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAmBvC"}

package/dist/team/permissions.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Team Permission Policy
+ *
+ * Extends the existing approval middleware to support team-wide
+ * permission delegation. When a coordinator creates team members,
+ * it can install a `teamPermissionPolicy` middleware that:
+ *
+ * 1. Applies team-wide allow/deny rules to all member tool calls
+ * 2. Forwards unresolved approvals to the coordinator (lead agent)
+ * 3. Propagates "remember" decisions to all team members
+ *
+ * This is layered ON TOP of the existing `approvalMiddleware` —
+ * it doesn't replace it. Members inherit the lead's approval rules
+ * via fork(), and the team policy adds team-specific delegation.
+ *
+ * Design choices vs ccsource:
+ * - No filesystem polling for permission responses — uses callbacks
+ * - No separate sandbox permission path — uses standard approval pipeline
+ * - Team rules are typed objects, not mailbox message payloads
+ * - Integrates with existing `beforeToolCall` middleware contract
+ */
+import type { AgentMiddleware, ToolCallDecision } from "../middleware/types.js";
+/**
+ * A team-wide permission rule.
+ *
+ * Rules are evaluated in order — first match wins.
+ */
+export interface TeamPermissionRule {
+    /** Tool name to match (exact or glob-style with `*`) */
+    tool: string;
+    /** Optional approval pattern to match against the tool input */
+    pattern?: string;
+    /** Member IDs this rule applies to (undefined = all members) */
+    members?: string[];
+    /** Whether to allow or deny */
+    action: "allow" | "deny";
+    /** Optional reason (shown to model on deny) */
+    reason?: string;
+}
+/**
+ * Callback for forwarding approval requests to the coordinator.
+ * Returns the coordinator's decision.
+ */
+export type ApprovalForwarder = (memberId: string, tool: string, args: unknown, ctx: Parameters<NonNullable<AgentMiddleware["beforeToolCall"]>>[2]) => Promise<ToolCallDecision>;
+/**
+ * Configuration for the team permission policy middleware.
+ */
+export interface TeamPermissionPolicyConfig {
+    /** The member ID this middleware is installed on */
+    memberId: string;
+    /** Team-wide rules (evaluated first, before forwarding) */
+    rules?: TeamPermissionRule[];
+    /**
+     * Forward unresolved approvals to this callback.
+     * If not provided, unresolved tools are allowed (fall through
+     * to the member's own approval middleware).
+     */
+    forwardApproval?: ApprovalForwarder;
+    /**
+     * Callback when a "remember" decision is made — the coordinator
+     * can propagate it to all members by updating their rule sets.
+     */
+    onRemember?: (rule: TeamPermissionRule) => void | Promise<void>;
+}
+/**
+ * Create a team permission policy middleware.
+ *
+ * Install this on forked member agents to enforce team-wide
+ * permission rules and optionally forward approvals to the
+ * coordinator.
+ *
+ * ```typescript
+ * const memberAgent = lead.fork({
+ *   name: "explorer",
+ *   additionalMiddleware: [
+ *     teamPermissionPolicy({
+ *       memberId: "explorer",
+ *       rules: [
+ *         { tool: "read_*", action: "allow" },
+ *         { tool: "write_*", action: "deny", reason: "Explorer is read-only" },
+ *       ],
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+export declare function teamPermissionPolicy(config: TeamPermissionPolicyConfig): AgentMiddleware;
+//# sourceMappingURL=permissions.d.ts.map

package/dist/team/permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../../src/team/permissions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAWhF;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,+BAA+B;IAC/B,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC;IACzB,+CAA+C;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAC9B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,EACb,GAAG,EAAE,UAAU,CAAC,WAAW,CAAC,eAAe,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAC/D,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAE/B;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAC7B;;;;OAIG;IACH,eAAe,CAAC,EAAE,iBAAiB,CAAC;IACpC;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,kBAAkB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjE;AA6BD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,0BAA0B,GACjC,eAAe,CAqCjB"}

package/dist/team/shutdown.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Shutdown Protocol
+ *
+ * Two-phase graceful shutdown for team members:
+ *
+ * 1. **Request** — coordinator sends a shutdown request via mailbox.
+ *    If the member is idle, it goes offline immediately. If busy,
+ *    it's marked "shutting-down" and finishes its current task first.
+ *
+ * 2. **Resolve** — once the member reaches "offline", the coordinator
+ *    emits a shutdown-resolved event.
+ *
+ * The `shutdown()` function applies this to all active members in parallel.
+ */
+import type { CoordinatorCtx, MemberRuntime } from "./coordinator/types.js";
+/**
+ * Request graceful shutdown of a specific member.
+ *
+ * - If member is idle, auto-accepts and goes offline immediately
+ * - If member is busy, marks as shutting-down and waits for current
+ *   task to finish before going offline
+ * - Returns true if shutdown succeeded within the timeout
+ */
+export declare function requestShutdown(ctx: CoordinatorCtx, memberId: string, reason?: string, timeoutMs?: number): Promise<boolean>;
+/**
+ * Gracefully shut down all active members.
+ */
+export declare function shutdownAll(ctx: CoordinatorCtx, reason?: string, timeoutMs?: number): Promise<void>;
+/**
+ * Poll until a member reaches "offline" status.
+ * Returns false if the timeout expires first.
+ */
+export declare function waitForOffline(runtime: MemberRuntime, timeoutMs?: number): Promise<boolean>;
+/**
+ * Emit a shutdown-resolved event.
+ */
+export declare function emitShutdownResolved(ctx: CoordinatorCtx, memberId: string, requestId: string, accepted: boolean): Promise<void>;
+//# sourceMappingURL=shutdown.d.ts.map

package/dist/team/shutdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shutdown.d.ts","sourceRoot":"","sources":["../../src/team/shutdown.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAO5E;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,cAAc,EACnB,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,OAAO,CAAC,CA2DlB;AAED;;GAEG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,cAAc,EACnB,MAAM,CAAC,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CASf;AAMD;;;GAGG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,aAAa,EACtB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,OAAO,CAAC,CAOlB;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,cAAc,EACnB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,OAAO,GAChB,OAAO,CAAC,IAAI,CAAC,CAQf"}

package/dist/team/task-board.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Task Board
+ *
+ * Manages team members and tasks with a dependency-aware lifecycle.
+ *
+ * The `TaskBoardStore` interface is the persistence contract — hosts
+ * swap in whatever backing store they need (in-memory, Redis, etc.).
+ * `TaskBoard` wraps the store and adds the behavioral logic: creation
+ * with dependency resolution, claiming, status transitions, and
+ * cascading unblock / cancel when dependencies complete or fail.
+ *
+ * Design choices vs the CLI version:
+ * - Added explicit `"claimed"` status (CLI jumped straight from pending → running)
+ * - `refreshDependents()` is recursive — cascading failures propagate fully
+ * - All mutations return `TaskTransition[]` so the coordinator can publish events
+ * - Store interface is minimal (CRUD); board owns all business rules
+ */
+import type { TaskStatus, TaskResult, TaskTransition, TeamMember, TeamTask } from "./types.js";
+export declare class TaskConflictError extends Error {
+    readonly taskId?: string | undefined;
+    constructor(message: string, taskId?: string | undefined);
+}
+/**
+ * Filter options for listing tasks.
+ */
+export interface TaskListFilter {
+    memberId?: string;
+    status?: TaskStatus | TaskStatus[];
+    limit?: number;
+}
+/**
+ * Persistence contract for task board data.
+ *
+ * Implementations must be safe for concurrent calls from the
+ * coordinator (which may dispatch multiple tasks in parallel).
+ * The in-memory implementation is inherently single-threaded;
+ * a Redis or database implementation should use optimistic
+ * locking or transactions.
+ */
+export interface TaskBoardStore {
+    /** Optional startup hook (open connections, etc.) */
+    start?(): Promise<void>;
+    /** Optional shutdown hook (close connections, etc.) */
+    stop?(): Promise<void>;
+    listMembers(): Promise<TeamMember[]>;
+    getMember(memberId: string): Promise<TeamMember | undefined>;
+    putMember(member: TeamMember): Promise<TeamMember>;
+    listTasks(filter?: TaskListFilter): Promise<TeamTask[]>;
+    getTask(taskId: string): Promise<TeamTask | undefined>;
+    putTask(task: TeamTask): Promise<TeamTask>;
+}
+/**
+ * Input for creating a new task.
+ */
+export interface TaskCreateInput {
+    id: string;
+    title: string;
+    prompt: string;
+    memberId?: string;
+    dependsOn?: string[];
+}
+/**
+ * Simple in-memory store — suitable for single-process teams.
+ */
+export declare class InMemoryTaskBoardStore implements TaskBoardStore {
+    private readonly members;
+    private readonly tasks;
+    listMembers(): Promise<TeamMember[]>;
+    getMember(memberId: string): Promise<TeamMember | undefined>;
+    putMember(member: TeamMember): Promise<TeamMember>;
+    listTasks(filter?: TaskListFilter): Promise<TeamTask[]>;
+    getTask(taskId: string): Promise<TeamTask | undefined>;
+    putTask(task: TeamTask): Promise<TeamTask>;
+}
+/**
+ * Task board — manages task lifecycle with dependency tracking.
+ *
+ * All mutating methods return the affected task(s) plus any
+ * `TaskTransition` records triggered by the change (cascading
+ * unblocks, cancellations, etc.).
+ */
+export declare class TaskBoard {
+    private readonly store;
+    constructor(store: TaskBoardStore);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    listMembers(): Promise<TeamMember[]>;
+    getMember(id: string): Promise<TeamMember | undefined>;
+    listTasks(filter?: TaskListFilter): Promise<TeamTask[]>;
+    getTask(id: string): Promise<TeamTask | undefined>;
+    snapshot(): Promise<{
+        members: TeamMember[];
+        tasks: TeamTask[];
+    }>;
+    putMember(member: TeamMember): Promise<TeamMember>;
+    /**
+     * Create a new task. Its initial status is computed from dependencies:
+     * `"pending"` if all deps are met, `"blocked"` otherwise, or
+     * `"cancelled"` if a dependency already failed.
+     */
+    createTask(input: TaskCreateInput): Promise<{
+        task: TeamTask;
+        transitions: TaskTransition[];
+    }>;
+    /**
+     * Claim a pending task for a member. Moves status to `"claimed"`.
+     */
+    claimTask(taskId: string, memberId: string): Promise<TeamTask>;
+    /**
+     * Claim the next available pending task for a member.
+     * Prefers tasks already assigned to this member, then unassigned tasks.
+     */
+    claimNextTask(memberId: string): Promise<TeamTask | undefined>;
+    /**
+     * Mark a claimed task as running with a run reference.
+     */
+    startTask(taskId: string, runId: string): Promise<TeamTask>;
+    /**
+     * Complete a running task with a result.
+     * Cascades: blocked dependents may become pending or cancelled.
+     */
+    completeTask(taskId: string, result: TaskResult): Promise<{
+        task: TeamTask;
+        transitions: TaskTransition[];
+    }>;
+    /**
+     * Fail a running task.
+     * Cascades: blocked dependents may be cancelled.
+     */
+    failTask(taskId: string, error: string): Promise<{
+        task: TeamTask;
+        transitions: TaskTransition[];
+    }>;
+    /**
+     * Abort a claimed or running task without cascading dependency failure.
+     *
+     * Downstream tasks remain blocked so the host can retry or replace the
+     * aborted prerequisite explicitly.
+     */
+    abortTask(taskId: string, reason?: string): Promise<{
+        task: TeamTask;
+        transitions: TaskTransition[];
+    }>;
+    /**
+     * Cancel a task (at any non-terminal status).
+     * Cascades: blocked dependents may be cancelled.
+     */
+    cancelTask(taskId: string, reason?: string): Promise<{
+        task: TeamTask;
+        transitions: TaskTransition[];
+    }>;
+    /**
+     * Re-evaluate all blocked tasks against current dependency state.
+     * Called automatically after complete/fail/cancel, but can also
+     * be called manually for batch operations.
+     */
+    refreshDependents(): Promise<TaskTransition[]>;
+    private requireTask;
+    private retryOnConflict;
+}
+//# sourceMappingURL=task-board.d.ts.map

package/dist/team/task-board.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-board.d.ts","sourceRoot":"","sources":["../../src/team/task-board.ts"],"names":[],"mappings":"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"}

package/dist/team/types.d.ts

@@ -0,0 +1,233 @@
+/**
+ * Team Types
+ *
+ * Shared vocabulary for multi-agent team coordination.
+ *
+ * A team is a group of agents working toward a shared goal
+ * under a coordinator. Each member is a forked agent with a
+ * role, and work is tracked as structured tasks with
+ * dependencies.
+ *
+ * These types are deliberately framework-agnostic — no React,
+ * no CLI, no filesystem. Hosts wire concrete stores.
+ */
+import type { TokenUsage } from "../types/messages.js";
+/**
+ * Possible member lifecycle states.
+ *
+ * ```
+ * idle ──→ busy ──→ idle (task completed)
+ *  │                  │
+ *  ├──→ shutting-down ├──→ shutting-down ──→ offline
+ *  │                  │
+ *  └──→ offline       └──→ offline
+ * ```
+ */
+export type MemberStatus = "idle" | "busy" | "shutting-down" | "offline";
+/**
+ * A registered team member.
+ *
+ * Each member maps 1:1 to a forked agent instance. The coordinator
+ * creates and owns the record; the member agent is unaware of it.
+ */
+export interface TeamMember {
+    /** Stable identifier — usually matches the role name */
+    id: string;
+    /** Name of the role this member was created from */
+    role: string;
+    /** Human-readable description of the member's specialty */
+    description: string;
+    /** Session ID used for this member's agent conversations */
+    sessionId: string;
+    /** Current lifecycle state */
+    status: MemberStatus;
+    /** Task currently assigned to this member (if busy) */
+    activeTaskId?: string;
+    /** ISO timestamp of registration */
+    createdAt: string;
+    /** ISO timestamp of last status change */
+    updatedAt: string;
+}
+/**
+ * Task lifecycle states.
+ *
+ * ```
+ * ┌───────────┐
+ * │  blocked   │ ← has unfinished dependencies
+ * └─────┬─────┘
+ *       │ deps complete
+ *       ▼
+ * ┌───────────┐     ┌───────────┐
+ * │  pending   │────→│  claimed   │
+ * └─────┬─────┘     └─────┬─────┘
+ *       │                  │ member starts work
+ *       ▼                  ▼
+ * ┌───────────┐     ┌───────────┐
+ * │ cancelled  │     │  running   │
+ * └───────────┘     └─────┬─────┘
+ *                         │
+ *                    ┌────┴────┐
+ *                    ▼         ▼
+ *              ┌──────────┐ ┌──────────┐
+ *              │ completed │ │  failed   │
+ *              └──────────┘ └──────────┘
+ * ```
+ */
+export type TaskStatus = "blocked" | "pending" | "claimed" | "running" | "completed" | "aborted" | "failed" | "cancelled";
+/** Status values that indicate a terminal state (no further transitions). */
+export declare const TERMINAL_STATUSES: readonly TaskStatus[];
+/**
+ * Result of a completed task.
+ */
+export interface TaskResult {
+    /** The agent's final response text */
+    response: string;
+    /** Token usage for the entire task run */
+    usage?: TokenUsage;
+    /** Tool calls the agent made during the run */
+    toolCalls?: Array<{
+        name: string;
+        result: unknown;
+    }>;
+}
+/**
+ * A unit of work assigned to a team member.
+ */
+export interface TeamTask {
+    /** Unique task identifier */
+    id: string;
+    /** Member assigned to this task (undefined = unassigned) */
+    memberId?: string;
+    /** Short label for display */
+    title: string;
+    /** Full task description / prompt given to the member agent */
+    prompt: string;
+    /** Current lifecycle status */
+    status: TaskStatus;
+    /** Task IDs that must complete before this task can start */
+    dependsOn?: string[];
+    /** ISO timestamp when a member claimed this task */
+    claimedAt?: string;
+    /** Execution/run identifier for the active attempt */
+    runId?: string;
+    /** ISO timestamp of creation */
+    createdAt: string;
+    /** ISO timestamp of last status change */
+    updatedAt: string;
+    /** Result (only present when status is "completed") */
+    result?: TaskResult;
+    /** Error message (only present when status is "failed" or "cancelled") */
+    error?: string;
+}
+/**
+ * Message routing kind.
+ *
+ * - `direct`    — one sender to one recipient
+ * - `broadcast` — one sender to all members
+ * - `system`    — generated by the coordinator (task transitions, etc.)
+ */
+export type MessageKind = "direct" | "broadcast" | "system";
+/**
+ * Structured message payloads — typed alternatives to plain text.
+ *
+ * Messages with a `payload` carry machine-readable data that the
+ * coordinator and member work loops can act on programmatically.
+ * The `body` field still contains a human-readable summary.
+ */
+export type MessagePayload = ShutdownRequestPayload | ShutdownResponsePayload | PermissionRequestPayload | PermissionResponsePayload | IdleNotificationPayload | GuidancePayload | WorkerReportPayload;
+/** Coordinator asks a member to shut down. */
+export interface ShutdownRequestPayload {
+    kind: "shutdown-request";
+    requestId: string;
+    reason?: string;
+}
+/** Member responds to a shutdown request. */
+export interface ShutdownResponsePayload {
+    kind: "shutdown-response";
+    requestId: string;
+    accepted: boolean;
+    /** Why the member rejected (e.g. "mid-task") */
+    reason?: string;
+}
+/** Member asks coordinator for tool permission. */
+export interface PermissionRequestPayload {
+    kind: "permission-request";
+    requestId: string;
+    tool: string;
+    args: unknown;
+    memberId: string;
+}
+/** Coordinator responds to a permission request. */
+export interface PermissionResponsePayload {
+    kind: "permission-response";
+    requestId: string;
+    decision: "allow" | "deny";
+    reason?: string;
+}
+/** Member notifies coordinator it's idle and available for work. */
+export interface IdleNotificationPayload {
+    kind: "idle-notification";
+    reason: "available" | "task-completed" | "task-failed" | "interrupted";
+    taskId?: string;
+}
+/** Coordinator sends guidance to a member. */
+export interface GuidancePayload {
+    kind: "guidance";
+    taskId?: string;
+}
+/** Worker sends a mid-task report to the coordinator. */
+export interface WorkerReportPayload {
+    kind: "worker-report";
+    taskId?: string;
+}
+/**
+ * A message exchanged within the team.
+ */
+export interface TeamMessage {
+    /** Unique message identifier */
+    id: string;
+    /** Team this message belongs to */
+    teamId: string;
+    /** Sender (member ID, "coordinator", or "system") */
+    from: string;
+    /** Recipient member ID (undefined for broadcast/system) */
+    to?: string;
+    /** Routing kind */
+    kind: MessageKind;
+    /** Message body (human-readable summary) */
+    body: string;
+    /**
+     * Structured payload for machine-readable messages.
+     * When present, the `body` is a human-readable summary and
+     * the payload carries the typed data.
+     */
+    payload?: MessagePayload;
+    /** Related task ID (if contextual) */
+    taskId?: string;
+    /** ISO timestamp */
+    createdAt: string;
+    /** Arbitrary metadata */
+    metadata?: Record<string, string>;
+}
+/**
+ * Point-in-time view of the full team state.
+ */
+export interface TeamSnapshot {
+    members: TeamMember[];
+    tasks: TeamTask[];
+    messages: TeamMessage[];
+}
+/**
+ * Why a task changed status — used by the coordinator to publish
+ * lifecycle events after mutations.
+ */
+export type TaskTransitionReason = "created" | "claimed" | "started" | "completed" | "aborted" | "failed" | "cancelled" | "unblocked" | "blocked-dependency-failed";
+/**
+ * Record of a single task status change.
+ */
+export interface TaskTransition {
+    task: TeamTask;
+    reason: TaskTransitionReason;
+    previous?: TaskStatus;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/team/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/team/types.ts"],"names":[],"mappings":"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"}

package/dist/team/work-loop.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Work Loop
+ *
+ * Persistent idle loop for team members. When enabled, members
+ * automatically poll the task board for new work instead of
+ * waiting for the coordinator to dispatch tasks manually.
+ *
+ * The work loop enables self-dispatch: tasks added to the board
+ * are picked up by idle members without coordinator involvement.
+ */
+import type { TeamTask } from "./types.js";
+import type { CoordinatorCtx, MemberRuntime } from "./coordinator/types.js";
+/**
+ * Persistent work loop for a member. Runs until stopRequested.
+ *
+ * Each iteration:
+ * 1. Check if stop requested → exit
+ * 2. Try to claim and execute next available task
+ * 3. Sleep for pollIntervalMs
+ *
+ * When the loop exits (stop requested or coordinator stopped),
+ * the member is set to offline if not already.
+ */
+export declare function runWorkLoop(ctx: CoordinatorCtx, runtime: MemberRuntime): Promise<void>;
+/**
+ * Try to claim the next available task for a member and start executing it.
+ * Returns the task if one was claimed, undefined if nothing available.
+ */
+export declare function tryClaimAndExecute(ctx: CoordinatorCtx, runtime: MemberRuntime): Promise<TeamTask | undefined>;
+//# sourceMappingURL=work-loop.d.ts.map

package/dist/team/work-loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"work-loop.d.ts","sourceRoot":"","sources":["../../src/team/work-loop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAQ5E;;;;;;;;;;GAUG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,cAAc,EACnB,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,IAAI,CAAC,CAsEf;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,cAAc,EACnB,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAE/B"}