@open-multi-agent/core 1.4.0

package/dist/task/task.js

@@ -0,0 +1,206 @@
+/**
+ * @fileoverview Pure task utility functions.
+ *
+ * These helpers operate on plain {@link Task} values without any mutable
+ * state, making them safe to use in reducers, tests, and reactive pipelines.
+ * Stateful orchestration belongs in {@link TaskQueue}.
+ */
+import { randomUUID } from 'node:crypto';
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Creates a new {@link Task} with a generated UUID, `'pending'` status, and
+ * `createdAt`/`updatedAt` timestamps set to the current instant.
+ *
+ * @example
+ * ```ts
+ * const task = createTask({
+ *   title: 'Research competitors',
+ *   description: 'Identify the top 5 competitors and their pricing',
+ *   assignee: 'researcher',
+ * })
+ * ```
+ */
+export function createTask(input) {
+    const now = new Date();
+    return {
+        id: randomUUID(),
+        title: input.title,
+        description: input.description,
+        status: 'pending',
+        assignee: input.assignee,
+        dependsOn: input.dependsOn ? [...input.dependsOn] : undefined,
+        memoryScope: input.memoryScope,
+        result: undefined,
+        createdAt: now,
+        updatedAt: now,
+        maxRetries: input.maxRetries,
+        retryDelayMs: input.retryDelayMs,
+        retryBackoff: input.retryBackoff,
+    };
+}
+// ---------------------------------------------------------------------------
+// Readiness
+// ---------------------------------------------------------------------------
+/**
+ * Returns `true` when `task` can be started immediately.
+ *
+ * A task is considered ready when:
+ * 1. Its status is `'pending'`.
+ * 2. Every task listed in `task.dependsOn` has status `'completed'`.
+ *
+ * Tasks whose dependencies are missing from `allTasks` are treated as
+ * unresolvable and therefore **not** ready.
+ *
+ * @param task      - The task to evaluate.
+ * @param allTasks  - The full collection of tasks in the current queue/plan.
+ * @param taskById  - Optional pre-built id→task map. When provided the function
+ *                    skips rebuilding the map, reducing the complexity of
+ *                    call-sites that invoke `isTaskReady` inside a loop from
+ *                    O(n²) to O(n).
+ */
+export function isTaskReady(task, allTasks, taskById) {
+    if (task.status !== 'pending')
+        return false;
+    if (!task.dependsOn || task.dependsOn.length === 0)
+        return true;
+    const map = taskById ?? new Map(allTasks.map((t) => [t.id, t]));
+    for (const depId of task.dependsOn) {
+        const dep = map.get(depId);
+        if (!dep || dep.status !== 'completed')
+            return false;
+    }
+    return true;
+}
+// ---------------------------------------------------------------------------
+// Topological sort
+// ---------------------------------------------------------------------------
+/**
+ * Returns `tasks` sorted so that each task appears after all of its
+ * dependencies — a standard topological (Kahn's algorithm) ordering.
+ *
+ * Tasks with no dependencies come first. If the graph contains a cycle the
+ * function returns a partial result containing only the tasks that could be
+ * ordered; use {@link validateTaskDependencies} to detect cycles before calling
+ * this function in production paths.
+ *
+ * @example
+ * ```ts
+ * const ordered = getTaskDependencyOrder(tasks)
+ * for (const task of ordered) {
+ *   await run(task)
+ * }
+ * ```
+ */
+export function getTaskDependencyOrder(tasks) {
+    if (tasks.length === 0)
+        return [];
+    const taskById = new Map(tasks.map((t) => [t.id, t]));
+    // Build adjacency: dependsOn edges become "predecessors" for in-degree count.
+    const inDegree = new Map();
+    // successors[id] = list of task IDs that depend on `id`
+    const successors = new Map();
+    for (const task of tasks) {
+        if (!inDegree.has(task.id))
+            inDegree.set(task.id, 0);
+        if (!successors.has(task.id))
+            successors.set(task.id, []);
+        for (const depId of task.dependsOn ?? []) {
+            // Only count dependencies that exist in this task set.
+            if (taskById.has(depId)) {
+                inDegree.set(task.id, (inDegree.get(task.id) ?? 0) + 1);
+                const deps = successors.get(depId) ?? [];
+                deps.push(task.id);
+                successors.set(depId, deps);
+            }
+        }
+    }
+    // Kahn's algorithm: start with all nodes of in-degree 0.
+    const queue = [];
+    for (const [id, degree] of inDegree) {
+        if (degree === 0)
+            queue.push(id);
+    }
+    const ordered = [];
+    while (queue.length > 0) {
+        const id = queue.shift();
+        const task = taskById.get(id);
+        if (task)
+            ordered.push(task);
+        for (const successorId of successors.get(id) ?? []) {
+            const newDegree = (inDegree.get(successorId) ?? 0) - 1;
+            inDegree.set(successorId, newDegree);
+            if (newDegree === 0)
+                queue.push(successorId);
+        }
+    }
+    return ordered;
+}
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+/**
+ * Validates the dependency graph of a task collection.
+ *
+ * Checks for:
+ * - References to unknown task IDs in `dependsOn`.
+ * - Cycles (a task depending on itself, directly or transitively).
+ * - Self-dependencies (`task.dependsOn` includes its own `id`).
+ *
+ * @returns An object with `valid: true` when no issues were found, or
+ *          `valid: false` with a non-empty `errors` array describing each
+ *          problem.
+ *
+ * @example
+ * ```ts
+ * const { valid, errors } = validateTaskDependencies(tasks)
+ * if (!valid) throw new Error(errors.join('\n'))
+ * ```
+ */
+export function validateTaskDependencies(tasks) {
+    const errors = [];
+    const taskById = new Map(tasks.map((t) => [t.id, t]));
+    // Pass 1: check for unknown references and self-dependencies.
+    for (const task of tasks) {
+        for (const depId of task.dependsOn ?? []) {
+            if (depId === task.id) {
+                errors.push(`Task "${task.title}" (${task.id}) depends on itself.`);
+                continue;
+            }
+            if (!taskById.has(depId)) {
+                errors.push(`Task "${task.title}" (${task.id}) references unknown dependency "${depId}".`);
+            }
+        }
+    }
+    // Pass 2: cycle detection via DFS colouring (white=0, grey=1, black=2).
+    const colour = new Map();
+    for (const task of tasks)
+        colour.set(task.id, 0);
+    const visit = (id, path) => {
+        if (colour.get(id) === 2)
+            return; // Already fully explored.
+        if (colour.get(id) === 1) {
+            // Found a back-edge — cycle.
+            const cycleStart = path.indexOf(id);
+            const cycle = path.slice(cycleStart).concat(id);
+            errors.push(`Cyclic dependency detected: ${cycle.join(' -> ')}`);
+            return;
+        }
+        colour.set(id, 1);
+        const task = taskById.get(id);
+        for (const depId of task?.dependsOn ?? []) {
+            if (taskById.has(depId)) {
+                visit(depId, [...path, id]);
+            }
+        }
+        colour.set(id, 2);
+    };
+    for (const task of tasks) {
+        if (colour.get(task.id) === 0) {
+            visit(task.id, []);
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}
+//# sourceMappingURL=task.js.map

package/dist/task/task.js.map

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

package/dist/team/messaging.d.ts

@@ -0,0 +1,106 @@
+/**
+ * @fileoverview Inter-agent message bus.
+ *
+ * Provides a lightweight pub/sub system so agents can exchange typed messages
+ * without direct references to each other. All messages are retained in memory
+ * for replay and audit; read-state is tracked per recipient.
+ */
+/** A single message exchanged between agents (or broadcast to all). */
+export interface Message {
+    /** Stable UUID for this message. */
+    readonly id: string;
+    /** Name of the sending agent. */
+    readonly from: string;
+    /**
+     * Recipient agent name, or `'*'` when the message is a broadcast intended
+     * for every agent except the sender.
+     */
+    readonly to: string;
+    readonly content: string;
+    readonly timestamp: Date;
+}
+/**
+ * In-memory message bus for inter-agent communication.
+ *
+ * Agents can send point-to-point messages or broadcasts. Subscribers are
+ * notified synchronously (within the same microtask) when a new message
+ * arrives addressed to them.
+ *
+ * @example
+ * ```ts
+ * const bus = new MessageBus()
+ *
+ * const unsubscribe = bus.subscribe('worker', (msg) => {
+ *   console.log(`worker received: ${msg.content}`)
+ * })
+ *
+ * bus.send('coordinator', 'worker', 'Start task A')
+ * bus.broadcast('coordinator', 'All agents: stand by')
+ *
+ * unsubscribe()
+ * ```
+ */
+export declare class MessageBus {
+    /** All messages ever sent, in insertion order. */
+    private readonly messages;
+    /**
+     * Per-agent set of message IDs that have already been marked as read.
+     * A message absent from this set is considered unread.
+     */
+    private readonly readState;
+    /**
+     * Active subscribers keyed by agent name. Each subscriber is a callback
+     * paired with a unique subscription ID used for unsubscription.
+     */
+    private readonly subscribers;
+    /**
+     * Send a message from `from` to `to`.
+     *
+     * @returns The persisted {@link Message} including its generated ID and timestamp.
+     */
+    send(from: string, to: string, content: string): Message;
+    /**
+     * Broadcast a message from `from` to all other agents (`to === '*'`).
+     *
+     * @returns The persisted broadcast {@link Message}.
+     */
+    broadcast(from: string, content: string): Message;
+    /**
+     * Returns messages that have not yet been marked as read by `agentName`,
+     * including both direct messages and broadcasts addressed to them.
+     */
+    getUnread(agentName: string): Message[];
+    /**
+     * Returns every message (read or unread) addressed to `agentName`,
+     * preserving insertion order.
+     */
+    getAll(agentName: string): Message[];
+    /**
+     * Mark a set of messages as read for `agentName`.
+     * Passing IDs that were already marked, or do not exist, is a no-op.
+     */
+    markRead(agentName: string, messageIds: string[]): void;
+    /**
+     * Returns all messages exchanged between `agent1` and `agent2` (in either
+     * direction), sorted chronologically.
+     */
+    getConversation(agent1: string, agent2: string): Message[];
+    /**
+     * Subscribe to new messages addressed to `agentName`.
+     *
+     * The `callback` is invoked synchronously after each matching message is
+     * persisted. Returns an unsubscribe function; calling it is idempotent.
+     *
+     * @example
+     * ```ts
+     * const off = bus.subscribe('agent-b', (msg) => handleMessage(msg))
+     * // Later…
+     * off()
+     * ```
+     */
+    subscribe(agentName: string, callback: (message: Message) => void): () => void;
+    private persist;
+    private notifySubscribers;
+    private fireCallbacks;
+}
+//# sourceMappingURL=messaging.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"messaging.d.ts","sourceRoot":"","sources":["../../src/team/messaging.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH,uEAAuE;AACvE,MAAM,WAAW,OAAO;IACtB,oCAAoC;IACpC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,iCAAiC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB;;;OAGG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAA;CACzB;AAmBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,UAAU;IACrB,kDAAkD;IAClD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgB;IAEzC;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiC;IAE3D;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,WAAW,CAGzB;IAMH;;;;OAIG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO;IAYxD;;;;OAIG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO;IAQjD;;;OAGG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,EAAE;IAOvC;;;OAGG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,EAAE;IAIpC;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,IAAI;IAYvD;;;OAGG;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,EAAE;IAY1D;;;;;;;;;;;;OAYG;IACH,SAAS,CACP,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GACnC,MAAM,IAAI;IAiBb,OAAO,CAAC,OAAO;IAKf,OAAO,CAAC,iBAAiB;IAezB,OAAO,CAAC,aAAa;CAOtB"}

package/dist/team/messaging.js

@@ -0,0 +1,183 @@
+/**
+ * @fileoverview Inter-agent message bus.
+ *
+ * Provides a lightweight pub/sub system so agents can exchange typed messages
+ * without direct references to each other. All messages are retained in memory
+ * for replay and audit; read-state is tracked per recipient.
+ */
+import { randomUUID } from 'node:crypto';
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/** Returns true when `message` is addressed to `agentName`. */
+function isAddressedTo(message, agentName) {
+    if (message.to === '*') {
+        // Broadcasts are delivered to everyone except the sender.
+        return message.from !== agentName;
+    }
+    return message.to === agentName;
+}
+// ---------------------------------------------------------------------------
+// MessageBus
+// ---------------------------------------------------------------------------
+/**
+ * In-memory message bus for inter-agent communication.
+ *
+ * Agents can send point-to-point messages or broadcasts. Subscribers are
+ * notified synchronously (within the same microtask) when a new message
+ * arrives addressed to them.
+ *
+ * @example
+ * ```ts
+ * const bus = new MessageBus()
+ *
+ * const unsubscribe = bus.subscribe('worker', (msg) => {
+ *   console.log(`worker received: ${msg.content}`)
+ * })
+ *
+ * bus.send('coordinator', 'worker', 'Start task A')
+ * bus.broadcast('coordinator', 'All agents: stand by')
+ *
+ * unsubscribe()
+ * ```
+ */
+export class MessageBus {
+    /** All messages ever sent, in insertion order. */
+    messages = [];
+    /**
+     * Per-agent set of message IDs that have already been marked as read.
+     * A message absent from this set is considered unread.
+     */
+    readState = new Map();
+    /**
+     * Active subscribers keyed by agent name. Each subscriber is a callback
+     * paired with a unique subscription ID used for unsubscription.
+     */
+    subscribers = new Map();
+    // ---------------------------------------------------------------------------
+    // Write operations
+    // ---------------------------------------------------------------------------
+    /**
+     * Send a message from `from` to `to`.
+     *
+     * @returns The persisted {@link Message} including its generated ID and timestamp.
+     */
+    send(from, to, content) {
+        const message = {
+            id: randomUUID(),
+            from,
+            to,
+            content,
+            timestamp: new Date(),
+        };
+        this.persist(message);
+        return message;
+    }
+    /**
+     * Broadcast a message from `from` to all other agents (`to === '*'`).
+     *
+     * @returns The persisted broadcast {@link Message}.
+     */
+    broadcast(from, content) {
+        return this.send(from, '*', content);
+    }
+    // ---------------------------------------------------------------------------
+    // Read operations
+    // ---------------------------------------------------------------------------
+    /**
+     * Returns messages that have not yet been marked as read by `agentName`,
+     * including both direct messages and broadcasts addressed to them.
+     */
+    getUnread(agentName) {
+        const read = this.readState.get(agentName) ?? new Set();
+        return this.messages.filter((m) => isAddressedTo(m, agentName) && !read.has(m.id));
+    }
+    /**
+     * Returns every message (read or unread) addressed to `agentName`,
+     * preserving insertion order.
+     */
+    getAll(agentName) {
+        return this.messages.filter((m) => isAddressedTo(m, agentName));
+    }
+    /**
+     * Mark a set of messages as read for `agentName`.
+     * Passing IDs that were already marked, or do not exist, is a no-op.
+     */
+    markRead(agentName, messageIds) {
+        if (messageIds.length === 0)
+            return;
+        let read = this.readState.get(agentName);
+        if (!read) {
+            read = new Set();
+            this.readState.set(agentName, read);
+        }
+        for (const id of messageIds) {
+            read.add(id);
+        }
+    }
+    /**
+     * Returns all messages exchanged between `agent1` and `agent2` (in either
+     * direction), sorted chronologically.
+     */
+    getConversation(agent1, agent2) {
+        return this.messages.filter((m) => (m.from === agent1 && m.to === agent2) ||
+            (m.from === agent2 && m.to === agent1));
+    }
+    // ---------------------------------------------------------------------------
+    // Subscriptions
+    // ---------------------------------------------------------------------------
+    /**
+     * Subscribe to new messages addressed to `agentName`.
+     *
+     * The `callback` is invoked synchronously after each matching message is
+     * persisted. Returns an unsubscribe function; calling it is idempotent.
+     *
+     * @example
+     * ```ts
+     * const off = bus.subscribe('agent-b', (msg) => handleMessage(msg))
+     * // Later…
+     * off()
+     * ```
+     */
+    subscribe(agentName, callback) {
+        let agentSubs = this.subscribers.get(agentName);
+        if (!agentSubs) {
+            agentSubs = new Map();
+            this.subscribers.set(agentName, agentSubs);
+        }
+        const id = Symbol();
+        agentSubs.set(id, callback);
+        return () => {
+            agentSubs.delete(id);
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    persist(message) {
+        this.messages.push(message);
+        this.notifySubscribers(message);
+    }
+    notifySubscribers(message) {
+        // Notify direct subscribers of `message.to` (unless broadcast).
+        if (message.to !== '*') {
+            this.fireCallbacks(message.to, message);
+            return;
+        }
+        // Broadcast: notify all subscribers except the sender.
+        for (const [agentName, subs] of this.subscribers) {
+            if (agentName !== message.from && subs.size > 0) {
+                this.fireCallbacks(agentName, message);
+            }
+        }
+    }
+    fireCallbacks(agentName, message) {
+        const subs = this.subscribers.get(agentName);
+        if (!subs)
+            return;
+        for (const callback of subs.values()) {
+            callback(message);
+        }
+    }
+}
+//# sourceMappingURL=messaging.js.map

package/dist/team/messaging.js.map

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

package/dist/team/team.d.ts

@@ -0,0 +1,141 @@
+/**
+ * @fileoverview Team — the central coordination object for a named group of agents.
+ *
+ * A {@link Team} owns the agent roster, the inter-agent {@link MessageBus},
+ * the {@link TaskQueue}, and (optionally) a {@link SharedMemory} instance.
+ * It also exposes a typed event bus so orchestrators can react to lifecycle
+ * events without polling.
+ */
+import type { AgentConfig, MemoryStore, Task, TeamConfig } from '../types.js';
+import { SharedMemory } from '../memory/shared.js';
+import type { Message } from './messaging.js';
+export type { Message };
+/**
+ * Coordinates a named group of agents with shared messaging, task queuing,
+ * and optional shared memory.
+ *
+ * @example
+ * ```ts
+ * const team = new Team({
+ *   name: 'research-team',
+ *   agents: [researcherConfig, writerConfig],
+ *   sharedMemory: true,
+ *   maxConcurrency: 2,
+ * })
+ *
+ * team.on('task:complete', (data) => {
+ *   const event = data as OrchestratorEvent
+ *   console.log(`Task done: ${event.task}`)
+ * })
+ *
+ * const task = team.addTask({
+ *   title: 'Research topic',
+ *   description: 'Gather background on quantum computing',
+ *   status: 'pending',
+ *   assignee: 'researcher',
+ * })
+ * ```
+ */
+export declare class Team {
+    readonly name: string;
+    readonly config: TeamConfig;
+    private readonly agentMap;
+    private readonly bus;
+    private readonly queue;
+    private readonly memory;
+    private readonly events;
+    constructor(config: TeamConfig);
+    /** Returns a shallow copy of the agent configs in registration order. */
+    getAgents(): AgentConfig[];
+    /**
+     * Looks up an agent by name.
+     *
+     * @returns The {@link AgentConfig} or `undefined` when the name is not known.
+     */
+    getAgent(name: string): AgentConfig | undefined;
+    /**
+     * Sends a point-to-point message from `from` to `to`.
+     *
+     * The message is persisted on the bus and any active subscribers for `to`
+     * are notified synchronously.
+     */
+    sendMessage(from: string, to: string, content: string): void;
+    /**
+     * Returns all messages (read or unread) addressed to `agentName`, in
+     * chronological order.
+     */
+    getMessages(agentName: string): Message[];
+    /**
+     * Broadcasts `content` from `from` to every other agent.
+     *
+     * The `to` field of the resulting message is `'*'`.
+     */
+    broadcast(from: string, content: string): void;
+    /**
+     * Creates a new task, adds it to the queue, and returns the persisted
+     * {@link Task} (with generated `id`, `createdAt`, and `updatedAt`).
+     *
+     * @param task - Everything except the generated fields.
+     */
+    addTask(task: Omit<Task, 'id' | 'createdAt' | 'updatedAt'>): Task;
+    /** Returns a snapshot of all tasks in the queue (any status). */
+    getTasks(): Task[];
+    /** Returns all tasks whose `assignee` is `agentName`. */
+    getTasksByAssignee(agentName: string): Task[];
+    /**
+     * Applies a partial update to the task identified by `taskId`.
+     *
+     * @throws {Error} when the task is not found.
+     */
+    updateTask(taskId: string, update: Partial<Task>): Task;
+    /**
+     * Returns the next `'pending'` task for `agentName`, respecting dependencies.
+     *
+     * Tries to find a task explicitly assigned to the agent first; falls back to
+     * the first unassigned pending task.
+     *
+     * @returns `undefined` when no ready task exists for this agent.
+     */
+    getNextTask(agentName: string): Task | undefined;
+    /**
+     * Returns the shared {@link MemoryStore} for this team, or `undefined` if
+     * `sharedMemory` was not enabled in {@link TeamConfig}.
+     *
+     * Note: the returned value satisfies the {@link MemoryStore} interface.
+     * Callers that need the full {@link SharedMemory} API can use the
+     * `as SharedMemory` cast, but depending on the concrete type is discouraged.
+     */
+    getSharedMemory(): MemoryStore | undefined;
+    /**
+     * Returns the raw {@link SharedMemory} instance (team-internal accessor).
+     * Use this when you need the namespacing / `getSummary` features.
+     *
+     * @internal
+     */
+    getSharedMemoryInstance(): SharedMemory | undefined;
+    /**
+     * Subscribes to a team event.
+     *
+     * Built-in events:
+     * - `'task:ready'`   — emitted when a task becomes runnable.
+     * - `'task:complete'` — emitted when a task completes successfully.
+     * - `'task:failed'`  — emitted when a task fails.
+     * - `'all:complete'` — emitted when every task in the queue has terminated.
+     * - `'message'`      — emitted on point-to-point messages.
+     * - `'broadcast'`    — emitted on broadcast messages.
+     *
+     * `data` is typed as `unknown`; cast to {@link OrchestratorEvent} for
+     * structured access.
+     *
+     * @returns An unsubscribe function.
+     */
+    on(event: string, handler: (data: unknown) => void): () => void;
+    /**
+     * Emits a custom event on the team's event bus.
+     *
+     * Orchestrators can use this to signal domain-specific lifecycle milestones
+     * (e.g. `'phase:research:complete'`) without modifying the Team class.
+     */
+    emit(event: string, data: unknown): void;
+}
+//# sourceMappingURL=team.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"team.d.ts","sourceRoot":"","sources":["../../src/team/team.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EAEX,IAAI,EAEJ,UAAU,EACX,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAElD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAA;AAI7C,YAAY,EAAE,OAAO,EAAE,CAAA;AAsCvB;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,IAAI;IACf,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;IAE3B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkC;IAC3D,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAY;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAW;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;IACjD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;gBAErB,MAAM,EAAE,UAAU;IA2D9B,yEAAyE;IACzE,SAAS,IAAI,WAAW,EAAE;IAI1B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAQ/C;;;;;OAKG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAU5D;;;OAGG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,EAAE;IAIzC;;;;OAIG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAc9C;;;;;OAKG;IACH,OAAO,CACL,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,GAAG,WAAW,GAAG,WAAW,CAAC,GACjD,IAAI;IAkBP,iEAAiE;IACjE,QAAQ,IAAI,IAAI,EAAE;IAIlB,yDAAyD;IACzD,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,EAAE;IAI7C;;;;OAIG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAUvD;;;;;;;OAOG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IAahD;;;;;;;OAOG;IACH,eAAe,IAAI,WAAW,GAAG,SAAS;IAI1C;;;;;OAKG;IACH,uBAAuB,IAAI,YAAY,GAAG,SAAS;IAQnD;;;;;;;;;;;;;;;OAeG;IACH,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI;IAI/D;;;;;OAKG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI;CAGzC"}