@jackchen_me/open-multi-agent 0.1.0

package/dist/memory/shared.js

@@ -0,0 +1,155 @@
+/**
+ * @fileoverview Shared memory layer for teams of cooperating agents.
+ *
+ * Each agent writes under its own namespace (`<agentName>/<key>`) so entries
+ * remain attributable, while any agent may read any entry. The
+ * {@link SharedMemory.getSummary} method produces a human-readable digest
+ * suitable for injecting into an agent's context window.
+ */
+import { InMemoryStore } from './store.js';
+// ---------------------------------------------------------------------------
+// SharedMemory
+// ---------------------------------------------------------------------------
+/**
+ * Namespaced shared memory for a team of agents.
+ *
+ * Writes are namespaced as `<agentName>/<key>` so that entries from different
+ * agents never collide and are always attributable. Reads are namespace-aware
+ * but also accept fully-qualified keys, making cross-agent reads straightforward.
+ *
+ * @example
+ * ```ts
+ * const mem = new SharedMemory()
+ *
+ * await mem.write('researcher', 'findings', 'TypeScript 5.5 ships const type params')
+ * await mem.write('coder', 'plan', 'Implement feature X using const type params')
+ *
+ * const entry = await mem.read('researcher/findings')
+ * const all = await mem.listByAgent('researcher')
+ * const summary = await mem.getSummary()
+ * ```
+ */
+export class SharedMemory {
+    store;
+    constructor() {
+        this.store = new InMemoryStore();
+    }
+    // ---------------------------------------------------------------------------
+    // Write
+    // ---------------------------------------------------------------------------
+    /**
+     * Write `value` under the namespaced key `<agentName>/<key>`.
+     *
+     * Metadata is merged with a `{ agent: agentName }` marker so consumers can
+     * identify provenance when iterating all entries.
+     *
+     * @param agentName - The writing agent's name (used as a namespace prefix).
+     * @param key       - Logical key within the agent's namespace.
+     * @param value     - String value to store (serialise objects before writing).
+     * @param metadata  - Optional extra metadata stored alongside the entry.
+     */
+    async write(agentName, key, value, metadata) {
+        const namespacedKey = SharedMemory.namespaceKey(agentName, key);
+        await this.store.set(namespacedKey, value, {
+            ...metadata,
+            agent: agentName,
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // Read
+    // ---------------------------------------------------------------------------
+    /**
+     * Read an entry by its fully-qualified key (`<agentName>/<key>`).
+     *
+     * Returns `null` when the key is absent.
+     */
+    async read(key) {
+        return this.store.get(key);
+    }
+    // ---------------------------------------------------------------------------
+    // List
+    // ---------------------------------------------------------------------------
+    /** Returns every entry in the shared store, regardless of agent. */
+    async listAll() {
+        return this.store.list();
+    }
+    /**
+     * Returns all entries written by `agentName` (i.e. those whose key starts
+     * with `<agentName>/`).
+     */
+    async listByAgent(agentName) {
+        const prefix = SharedMemory.namespaceKey(agentName, '');
+        const all = await this.store.list();
+        return all.filter((entry) => entry.key.startsWith(prefix));
+    }
+    // ---------------------------------------------------------------------------
+    // Summary
+    // ---------------------------------------------------------------------------
+    /**
+     * Produces a human-readable summary of all entries in the store.
+     *
+     * The output is structured as a markdown-style block, grouped by agent, and
+     * is designed to be prepended to an agent's system prompt or injected as a
+     * user turn so the agent has context about what its teammates know.
+     *
+     * Returns an empty string when the store is empty.
+     *
+     * @example
+     * ```
+     * ## Shared Team Memory
+     *
+     * ### researcher
+     * - findings: TypeScript 5.5 ships const type params
+     *
+     * ### coder
+     * - plan: Implement feature X using const type params
+     * ```
+     */
+    async getSummary() {
+        const all = await this.store.list();
+        if (all.length === 0)
+            return '';
+        // Group entries by agent name.
+        const byAgent = new Map();
+        for (const entry of all) {
+            const slashIdx = entry.key.indexOf('/');
+            const agent = slashIdx === -1 ? '_unknown' : entry.key.slice(0, slashIdx);
+            const localKey = slashIdx === -1 ? entry.key : entry.key.slice(slashIdx + 1);
+            let group = byAgent.get(agent);
+            if (!group) {
+                group = [];
+                byAgent.set(agent, group);
+            }
+            group.push({ localKey, value: entry.value });
+        }
+        const lines = ['## Shared Team Memory', ''];
+        for (const [agent, entries] of byAgent) {
+            lines.push(`### ${agent}`);
+            for (const { localKey, value } of entries) {
+                // Truncate long values so the summary stays readable in a context window.
+                const displayValue = value.length > 200 ? `${value.slice(0, 197)}…` : value;
+                lines.push(`- ${localKey}: ${displayValue}`);
+            }
+            lines.push('');
+        }
+        return lines.join('\n').trimEnd();
+    }
+    // ---------------------------------------------------------------------------
+    // Store access
+    // ---------------------------------------------------------------------------
+    /**
+     * Returns the underlying {@link MemoryStore} so callers that only need the
+     * raw key-value interface can receive a properly typed reference without
+     * accessing private fields via bracket notation.
+     */
+    getStore() {
+        return this.store;
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    static namespaceKey(agentName, key) {
+        return `${agentName}/${key}`;
+    }
+}
+//# sourceMappingURL=shared.js.map

package/dist/memory/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../src/memory/shared.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE1C,8EAA8E;AAC9E,eAAe;AACf,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAO,YAAY;IACN,KAAK,CAAe;IAErC;QACE,IAAI,CAAC,KAAK,GAAG,IAAI,aAAa,EAAE,CAAA;IAClC,CAAC;IAED,8EAA8E;IAC9E,QAAQ;IACR,8EAA8E;IAE9E;;;;;;;;;;OAUG;IACH,KAAK,CAAC,KAAK,CACT,SAAiB,EACjB,GAAW,EACX,KAAa,EACb,QAAkC;QAElC,MAAM,aAAa,GAAG,YAAY,CAAC,YAAY,CAAC,SAAS,EAAE,GAAG,CAAC,CAAA;QAC/D,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,aAAa,EAAE,KAAK,EAAE;YACzC,GAAG,QAAQ;YACX,KAAK,EAAE,SAAS;SACjB,CAAC,CAAA;IACJ,CAAC;IAED,8EAA8E;IAC9E,OAAO;IACP,8EAA8E;IAE9E;;;;OAIG;IACH,KAAK,CAAC,IAAI,CAAC,GAAW;QACpB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IAC5B,CAAC;IAED,8EAA8E;IAC9E,OAAO;IACP,8EAA8E;IAE9E,oEAAoE;IACpE,KAAK,CAAC,OAAO;QACX,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAA;IAC1B,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,WAAW,CAAC,SAAiB;QACjC,MAAM,MAAM,GAAG,YAAY,CAAC,YAAY,CAAC,SAAS,EAAE,EAAE,CAAC,CAAA;QACvD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAA;QACnC,OAAO,GAAG,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAA;IAC5D,CAAC;IAED,8EAA8E;IAC9E,UAAU;IACV,8EAA8E;IAE9E;;;;;;;;;;;;;;;;;;;OAmBG;IACH,KAAK,CAAC,UAAU;QACd,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAA;QACnC,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,CAAA;QAE/B,+BAA+B;QAC/B,MAAM,OAAO,GAAG,IAAI,GAAG,EAAsD,CAAA;QAC7E,KAAK,MAAM,KAAK,IAAI,GAAG,EAAE,CAAC;YACxB,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;YACvC,MAAM,KAAK,GAAG,QAAQ,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAA;YACzE,MAAM,QAAQ,GAAG,QAAQ,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAA;YAE5E,IAAI,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;YAC9B,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,KAAK,GAAG,EAAE,CAAA;gBACV,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAA;YAC3B,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAA;QAC9C,CAAC;QAED,MAAM,KAAK,GAAa,CAAC,uBAAuB,EAAE,EAAE,CAAC,CAAA;QACrD,KAAK,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,OAAO,EAAE,CAAC;YACvC,KAAK,CAAC,IAAI,CAAC,OAAO,KAAK,EAAE,CAAC,CAAA;YAC1B,KAAK,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,OAAO,EAAE,CAAC;gBAC1C,0EAA0E;gBAC1E,MAAM,YAAY,GAChB,KAAK,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAA;gBACxD,KAAK,CAAC,IAAI,CAAC,KAAK,QAAQ,KAAK,YAAY,EAAE,CAAC,CAAA;YAC9C,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;QAChB,CAAC;QAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,CAAA;IACnC,CAAC;IAED,8EAA8E;IAC9E,eAAe;IACf,8EAA8E;IAE9E;;;;OAIG;IACH,QAAQ;QACN,OAAO,IAAI,CAAC,KAAK,CAAA;IACnB,CAAC;IAED,8EAA8E;IAC9E,kBAAkB;IAClB,8EAA8E;IAEtE,MAAM,CAAC,YAAY,CAAC,SAAiB,EAAE,GAAW;QACxD,OAAO,GAAG,SAAS,IAAI,GAAG,EAAE,CAAA;IAC9B,CAAC;CACF"}

package/dist/memory/store.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @fileoverview In-memory implementation of {@link MemoryStore}.
+ *
+ * All data lives in a plain `Map` and is never persisted to disk. This is the
+ * default store used by {@link SharedMemory} and is suitable for testing and
+ * single-process use-cases. Swap it for a Redis or SQLite-backed implementation
+ * in production by satisfying the same {@link MemoryStore} interface.
+ */
+import type { MemoryEntry, MemoryStore } from '../types.js';
+/**
+ * Synchronous-under-the-hood key/value store that exposes an `async` surface
+ * so implementations can be swapped for async-native backends without changing
+ * callers.
+ *
+ * All keys are treated as opaque strings. Values are always strings; structured
+ * data must be serialised by the caller (e.g. `JSON.stringify`).
+ *
+ * @example
+ * ```ts
+ * const store = new InMemoryStore()
+ * await store.set('config', JSON.stringify({ model: 'claude-opus-4-6' }))
+ * const entry = await store.get('config')
+ * ```
+ */
+export declare class InMemoryStore implements MemoryStore {
+    private readonly data;
+    /** Returns the entry for `key`, or `null` if not present. */
+    get(key: string): Promise<MemoryEntry | null>;
+    /**
+     * Upserts `key` with `value` and optional `metadata`.
+     *
+     * If the key already exists its `createdAt` is **preserved** so callers can
+     * detect when a value was first written.
+     */
+    set(key: string, value: string, metadata?: Record<string, unknown>): Promise<void>;
+    /** Returns a snapshot of all entries in insertion order. */
+    list(): Promise<MemoryEntry[]>;
+    /**
+     * Removes the entry for `key`.
+     * Deleting a non-existent key is a no-op.
+     */
+    delete(key: string): Promise<void>;
+    /** Removes **all** entries from the store. */
+    clear(): Promise<void>;
+    /**
+     * Returns entries whose `key` starts with `query` **or** whose `value`
+     * contains `query` (case-insensitive substring match).
+     *
+     * This is a simple linear scan; it is not suitable for very large stores
+     * without an index layer on top.
+     *
+     * @example
+     * ```ts
+     * // Find all entries related to "research"
+     * const hits = await store.search('research')
+     * ```
+     */
+    search(query: string): Promise<MemoryEntry[]>;
+    /** Returns the number of entries currently held in the store. */
+    get size(): number;
+    /** Returns `true` if `key` exists in the store. */
+    has(key: string): boolean;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/memory/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/memory/store.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAM3D;;;;;;;;;;;;;;GAcG;AACH,qBAAa,aAAc,YAAW,WAAW;IAC/C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAiC;IAMtD,6DAA6D;IACvD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAInD;;;;;OAKG;IACG,GAAG,CACP,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,OAAO,CAAC,IAAI,CAAC;IAWhB,4DAA4D;IACtD,IAAI,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAIpC;;;OAGG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxC,8CAA8C;IACxC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ5B;;;;;;;;;;;;OAYG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAgBnD,iEAAiE;IACjE,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,mDAAmD;IACnD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;CAG1B"}

package/dist/memory/store.js

@@ -0,0 +1,103 @@
+/**
+ * @fileoverview In-memory implementation of {@link MemoryStore}.
+ *
+ * All data lives in a plain `Map` and is never persisted to disk. This is the
+ * default store used by {@link SharedMemory} and is suitable for testing and
+ * single-process use-cases. Swap it for a Redis or SQLite-backed implementation
+ * in production by satisfying the same {@link MemoryStore} interface.
+ */
+// ---------------------------------------------------------------------------
+// InMemoryStore
+// ---------------------------------------------------------------------------
+/**
+ * Synchronous-under-the-hood key/value store that exposes an `async` surface
+ * so implementations can be swapped for async-native backends without changing
+ * callers.
+ *
+ * All keys are treated as opaque strings. Values are always strings; structured
+ * data must be serialised by the caller (e.g. `JSON.stringify`).
+ *
+ * @example
+ * ```ts
+ * const store = new InMemoryStore()
+ * await store.set('config', JSON.stringify({ model: 'claude-opus-4-6' }))
+ * const entry = await store.get('config')
+ * ```
+ */
+export class InMemoryStore {
+    data = new Map();
+    // ---------------------------------------------------------------------------
+    // MemoryStore interface
+    // ---------------------------------------------------------------------------
+    /** Returns the entry for `key`, or `null` if not present. */
+    async get(key) {
+        return this.data.get(key) ?? null;
+    }
+    /**
+     * Upserts `key` with `value` and optional `metadata`.
+     *
+     * If the key already exists its `createdAt` is **preserved** so callers can
+     * detect when a value was first written.
+     */
+    async set(key, value, metadata) {
+        const existing = this.data.get(key);
+        const entry = {
+            key,
+            value,
+            metadata: metadata !== undefined ? { ...metadata } : undefined,
+            createdAt: existing?.createdAt ?? new Date(),
+        };
+        this.data.set(key, entry);
+    }
+    /** Returns a snapshot of all entries in insertion order. */
+    async list() {
+        return Array.from(this.data.values());
+    }
+    /**
+     * Removes the entry for `key`.
+     * Deleting a non-existent key is a no-op.
+     */
+    async delete(key) {
+        this.data.delete(key);
+    }
+    /** Removes **all** entries from the store. */
+    async clear() {
+        this.data.clear();
+    }
+    // ---------------------------------------------------------------------------
+    // Extensions beyond the base MemoryStore interface
+    // ---------------------------------------------------------------------------
+    /**
+     * Returns entries whose `key` starts with `query` **or** whose `value`
+     * contains `query` (case-insensitive substring match).
+     *
+     * This is a simple linear scan; it is not suitable for very large stores
+     * without an index layer on top.
+     *
+     * @example
+     * ```ts
+     * // Find all entries related to "research"
+     * const hits = await store.search('research')
+     * ```
+     */
+    async search(query) {
+        if (query.length === 0) {
+            return this.list();
+        }
+        const lower = query.toLowerCase();
+        return Array.from(this.data.values()).filter((entry) => entry.key.toLowerCase().includes(lower) ||
+            entry.value.toLowerCase().includes(lower));
+    }
+    // ---------------------------------------------------------------------------
+    // Convenience helpers (not part of MemoryStore)
+    // ---------------------------------------------------------------------------
+    /** Returns the number of entries currently held in the store. */
+    get size() {
+        return this.data.size;
+    }
+    /** Returns `true` if `key` exists in the store. */
+    has(key) {
+        return this.data.has(key);
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/memory/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/memory/store.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,8EAA8E;AAC9E,gBAAgB;AAChB,8EAA8E;AAE9E;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,aAAa;IACP,IAAI,GAAG,IAAI,GAAG,EAAuB,CAAA;IAEtD,8EAA8E;IAC9E,wBAAwB;IACxB,8EAA8E;IAE9E,6DAA6D;IAC7D,KAAK,CAAC,GAAG,CAAC,GAAW;QACnB,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,CAAA;IACnC,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,GAAG,CACP,GAAW,EACX,KAAa,EACb,QAAkC;QAElC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACnC,MAAM,KAAK,GAAgB;YACzB,GAAG;YACH,KAAK;YACL,QAAQ,EAAE,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,QAAQ,EAAE,CAAC,CAAC,CAAC,SAAS;YAC9D,SAAS,EAAE,QAAQ,EAAE,SAAS,IAAI,IAAI,IAAI,EAAE;SAC7C,CAAA;QACD,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;IAC3B,CAAC;IAED,4DAA4D;IAC5D,KAAK,CAAC,IAAI;QACR,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAA;IACvC,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;IACvB,CAAC;IAED,8CAA8C;IAC9C,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAA;IACnB,CAAC;IAED,8EAA8E;IAC9E,mDAAmD;IACnD,8EAA8E;IAE9E;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,MAAM,CAAC,KAAa;QACxB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,OAAO,IAAI,CAAC,IAAI,EAAE,CAAA;QACpB,CAAC;QACD,MAAM,KAAK,GAAG,KAAK,CAAC,WAAW,EAAE,CAAA;QACjC,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAC1C,CAAC,KAAK,EAAE,EAAE,CACR,KAAK,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC;YACvC,KAAK,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,CAC5C,CAAA;IACH,CAAC;IAED,8EAA8E;IAC9E,gDAAgD;IAChD,8EAA8E;IAE9E,iEAAiE;IACjE,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAA;IACvB,CAAC;IAED,mDAAmD;IACnD,GAAG,CAAC,GAAW;QACb,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IAC3B,CAAC;CACF"}

package/dist/orchestrator/orchestrator.d.ts

@@ -0,0 +1,173 @@
+/**
+ * @fileoverview OpenMultiAgent — the top-level multi-agent orchestration class.
+ *
+ * {@link OpenMultiAgent} is the primary public API of the open-multi-agent framework.
+ * It ties together every subsystem:
+ *
+ *  - {@link Team}       — Agent roster, shared memory, inter-agent messaging
+ *  - {@link TaskQueue}  — Dependency-aware work queue
+ *  - {@link Scheduler}  — Task-to-agent assignment strategies
+ *  - {@link AgentPool}  — Concurrency-controlled execution pool
+ *  - {@link Agent}      — Conversation + tool-execution loop
+ *
+ * ## Quick start
+ *
+ * ```ts
+ * const orchestrator = new OpenMultiAgent({ defaultModel: 'claude-opus-4-6' })
+ *
+ * const team = orchestrator.createTeam('research', {
+ *   name: 'research',
+ *   agents: [
+ *     { name: 'researcher', model: 'claude-opus-4-6', systemPrompt: 'You are a researcher.' },
+ *     { name: 'writer',     model: 'claude-opus-4-6', systemPrompt: 'You are a technical writer.' },
+ *   ],
+ *   sharedMemory: true,
+ * })
+ *
+ * const result = await orchestrator.runTeam(team, 'Produce a report on TypeScript 5.5.')
+ * console.log(result.agentResults.get('coordinator')?.output)
+ * ```
+ *
+ * ## Key design decisions
+ *
+ * - **Coordinator pattern** — `runTeam()` spins up a temporary "coordinator" agent
+ *   that breaks the high-level goal into tasks, assigns them, and synthesises the
+ *   final answer. This is the framework's killer feature.
+ * - **Parallel-by-default** — Independent tasks (no shared dependency) run in
+ *   parallel up to `maxConcurrency`.
+ * - **Graceful failure** — A failed task marks itself `'failed'` and its direct
+ *   dependents remain `'blocked'` indefinitely; all non-dependent tasks continue.
+ * - **Progress callbacks** — Callers can pass `onProgress` in the config to receive
+ *   structured {@link OrchestratorEvent}s without polling.
+ */
+import type { AgentConfig, AgentRunResult, OrchestratorConfig, TeamConfig, TeamRunResult } from '../types.js';
+import { Team } from '../team/team.js';
+/**
+ * Top-level orchestrator for the open-multi-agent framework.
+ *
+ * Manages teams, coordinates task execution, and surfaces progress events.
+ * Most users will interact with this class exclusively.
+ */
+export declare class OpenMultiAgent {
+    private readonly config;
+    private readonly teams;
+    private completedTaskCount;
+    /**
+     * @param config - Optional top-level configuration.
+     *
+     * Sensible defaults:
+     *   - `maxConcurrency`: 5
+     *   - `defaultModel`:   `'claude-opus-4-6'`
+     *   - `defaultProvider`: `'anthropic'`
+     */
+    constructor(config?: OrchestratorConfig);
+    /**
+     * Create and register a {@link Team} with the orchestrator.
+     *
+     * The team is stored internally so {@link getStatus} can report aggregate
+     * agent counts. Returns the new {@link Team} for further configuration.
+     *
+     * @param name   - Unique team identifier. Throws if already registered.
+     * @param config - Team configuration (agents, shared memory, concurrency).
+     */
+    createTeam(name: string, config: TeamConfig): Team;
+    /**
+     * Run a single prompt with a one-off agent.
+     *
+     * Constructs a fresh agent from `config`, runs `prompt` in a single turn,
+     * and returns the result. The agent is not registered with any pool or team.
+     *
+     * Useful for simple one-shot queries that do not need team orchestration.
+     *
+     * @param config - Agent configuration.
+     * @param prompt - The user prompt to send.
+     */
+    runAgent(config: AgentConfig, prompt: string): Promise<AgentRunResult>;
+    /**
+     * Run a team on a high-level goal with full automatic orchestration.
+     *
+     * This is the flagship method of the framework. It works as follows:
+     *
+     * 1. A temporary "coordinator" agent receives the goal and the team's agent
+     *    roster, and is asked to decompose it into an ordered list of tasks with
+     *    JSON output.
+     * 2. The tasks are loaded into a {@link TaskQueue}. Title-based dependency
+     *    tokens in the coordinator's output are resolved to task IDs.
+     * 3. The {@link Scheduler} assigns unassigned tasks to team agents.
+     * 4. Tasks are executed in dependency order, with independent tasks running
+     *    in parallel up to `maxConcurrency`.
+     * 5. Results are persisted to shared memory after each task so subsequent
+     *    agents can read them.
+     * 6. The coordinator synthesises a final answer from all task outputs.
+     * 7. A {@link TeamRunResult} is returned.
+     *
+     * @param team - A team created via {@link createTeam} (or `new Team(...)`).
+     * @param goal - High-level natural-language goal for the team.
+     */
+    runTeam(team: Team, goal: string): Promise<TeamRunResult>;
+    /**
+     * Run a team with an explicitly provided task list.
+     *
+     * Simpler than {@link runTeam}: no coordinator agent is involved. Tasks are
+     * loaded directly into the queue, unassigned tasks are auto-assigned via the
+     * {@link Scheduler}, and execution proceeds in dependency order.
+     *
+     * @param team  - A team created via {@link createTeam}.
+     * @param tasks - Array of task descriptors.
+     */
+    runTasks(team: Team, tasks: ReadonlyArray<{
+        title: string;
+        description: string;
+        assignee?: string;
+        dependsOn?: string[];
+    }>): Promise<TeamRunResult>;
+    /**
+     * Returns a lightweight status snapshot.
+     *
+     * - `teams`          — Number of teams registered with this orchestrator.
+     * - `activeAgents`   — Total agents currently in `running` state.
+     * - `completedTasks` — Cumulative count of successfully completed tasks
+     *                      (coordinator meta-steps excluded).
+     */
+    getStatus(): {
+        teams: number;
+        activeAgents: number;
+        completedTasks: number;
+    };
+    /**
+     * Deregister all teams and reset internal counters.
+     *
+     * Does not cancel in-flight runs. Call this when you want to reuse the
+     * orchestrator instance for a fresh set of teams.
+     *
+     * Async for forward compatibility — shutdown may need to perform async
+     * cleanup (e.g. graceful agent drain) in future versions.
+     */
+    shutdown(): Promise<void>;
+    /** Build the system prompt given to the coordinator agent. */
+    private buildCoordinatorSystemPrompt;
+    /** Build the decomposition prompt for the coordinator. */
+    private buildDecompositionPrompt;
+    /** Build the synthesis prompt shown to the coordinator after all tasks complete. */
+    private buildSynthesisPrompt;
+    /**
+     * Load a list of task specs into a queue.
+     *
+     * Handles title-based `dependsOn` references by building a title→id map first,
+     * then resolving them to real IDs before adding tasks to the queue.
+     */
+    private loadSpecsIntoQueue;
+    /** Build an {@link AgentPool} from a list of agent configurations. */
+    private buildPool;
+    /**
+     * Aggregate the per-run `agentResults` map into a {@link TeamRunResult}.
+     *
+     * Merges results keyed as `agentName:taskId` back into a per-agent map
+     * by agent name for the public result surface.
+     *
+     * Only non-coordinator entries are counted toward `completedTaskCount` to
+     * avoid double-counting the coordinator's internal decompose/synthesis steps.
+     */
+    private buildTeamRunResult;
+}
+//# sourceMappingURL=orchestrator.d.ts.map

package/dist/orchestrator/orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../src/orchestrator/orchestrator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,cAAc,EACd,kBAAkB,EAIlB,UAAU,EACV,aAAa,EAEd,MAAM,aAAa,CAAA;AAMpB,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAA;AAoRtC;;;;;GAKG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAEmB;IAE1C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA+B;IACrD,OAAO,CAAC,kBAAkB,CAAI;IAE9B;;;;;;;OAOG;gBACS,MAAM,GAAE,kBAAuB;IAa3C;;;;;;;;OAQG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI;IAgBlD;;;;;;;;;;OAUG;IACG,QAAQ,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IA2B5E;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IA+F/D;;;;;;;;;OASG;IACG,QAAQ,CACZ,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,aAAa,CAAC;QACnB,KAAK,EAAE,MAAM,CAAA;QACb,WAAW,EAAE,MAAM,CAAA;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAA;QACjB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;KACrB,CAAC,GACD,OAAO,CAAC,aAAa,CAAC;IAqCzB;;;;;;;OAOG;IACH,SAAS,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE;IAY5E;;;;;;;;OAQG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAS/B,8DAA8D;IAC9D,OAAO,CAAC,4BAA4B;IAgCpC,0DAA0D;IAC1D,OAAO,CAAC,wBAAwB;IAYhC,oFAAoF;YACtE,oBAAoB;IAuClC;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IAoD1B,sEAAsE;IACtE,OAAO,CAAC,SAAS;IAajB;;;;;;;;OAQG;IACH,OAAO,CAAC,kBAAkB;CAyC3B"}