@open-multi-agent/core 1.4.0

package/dist/memory/shared.js

@@ -0,0 +1,294 @@
+/**
+ * @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';
+// ---------------------------------------------------------------------------
+// Runtime shape check
+// ---------------------------------------------------------------------------
+const STORE_METHODS = ['get', 'set', 'list', 'delete', 'clear'];
+/**
+ * Returns true when `v` structurally implements {@link MemoryStore}.
+ *
+ * Used to defend against malformed `sharedMemoryStore` values reaching
+ * {@link SharedMemory} (e.g. a plain object deserialized from JSON that
+ * cannot actually satisfy the interface at runtime).
+ */
+function isMemoryStore(v) {
+    if (v === null || typeof v !== 'object')
+        return false;
+    const obj = v;
+    return STORE_METHODS.every((m) => typeof obj[m] === 'function');
+}
+// ---------------------------------------------------------------------------
+// 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;
+    /**
+     * Monotonic turn counter used to evaluate per-entry `expiresAtTurn`.
+     * Advanced explicitly via {@link advanceTurn}; not bound to any specific
+     * unit (the orchestrator drives it once per completed task in `runTeam` /
+     * `runTasks`).
+     */
+    turnCount = 0;
+    /**
+     * @param store - Optional custom {@link MemoryStore} backing this shared memory.
+     *                Defaults to an in-process {@link InMemoryStore}. Custom stores
+     *                receive namespaced keys (`<agentName>/<key>`) opaque to them.
+     *                Stores that don't implement {@link MemoryStore.setWithExpiry}
+     *                still work — `writeExpiring` falls back to plain `set` on
+     *                them and the entry never expires.
+     *
+     * @throws {TypeError} when `store` is provided but does not structurally
+     *                     implement {@link MemoryStore} (fails fast on malformed
+     *                     values, e.g. plain objects from untrusted JSON config).
+     */
+    constructor(store) {
+        if (store !== undefined && !isMemoryStore(store)) {
+            throw new TypeError('SharedMemory: `store` must implement the MemoryStore interface ' +
+                `(methods: ${STORE_METHODS.join(', ')}).`);
+        }
+        this.store = store ?? new InMemoryStore();
+    }
+    // ---------------------------------------------------------------------------
+    // Turn counter
+    // ---------------------------------------------------------------------------
+    /**
+     * Advance the turn counter by one. Entries previously written via
+     * {@link writeExpiring} with `ttlTurns: N` expire once the counter reaches
+     * `(write-time count) + N`.
+     *
+     * Called by the orchestrator after each completed task in `runTeam` and
+     * `runTasks`. Standalone `runAgent` does not advance the counter — there
+     * is no team turn boundary in single-agent runs.
+     */
+    advanceTurn() {
+        this.turnCount++;
+    }
+    /** Current turn count. Useful for tests and observability. */
+    getTurnCount() {
+        return this.turnCount;
+    }
+    // ---------------------------------------------------------------------------
+    // 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,
+        });
+    }
+    /**
+     * Like {@link write}, but tags the entry with a turn-count expiry so it is
+     * automatically dropped from reads once the {@link advanceTurn} counter has
+     * advanced `ttlTurns` steps.
+     *
+     * Backends that don't implement {@link MemoryStore.setWithExpiry} fall back
+     * to a plain write — the entry persists indefinitely and `ttlTurns` is
+     * effectively ignored. Custom store authors who need TTL must implement
+     * the optional method.
+     *
+     * @param ttlTurns - Number of turns the entry should remain readable for.
+     *                   Must be an integer ≥ 1; throws {@link RangeError}
+     *                   otherwise.
+     *
+     * @throws {RangeError} when `ttlTurns` is not an integer or is less than 1.
+     *
+     * @remarks
+     * In parallel batch execution (`runTasks` / `runTeam` running multiple
+     * tasks in one batch) the turn counter advances per *completed* task, not
+     * per *invoked* task. So if task A writes a TTL entry while task B is
+     * still running, B completing first will advance the counter and may
+     * expire A's entry sooner than wall-clock intuition suggests. For
+     * cross-task hand-off semantics that need stricter ordering, write the
+     * entry without TTL and delete explicitly.
+     */
+    async writeExpiring(agentName, key, value, ttlTurns, metadata) {
+        if (!Number.isInteger(ttlTurns) || ttlTurns < 1) {
+            throw new RangeError(`SharedMemory.writeExpiring: ttlTurns must be an integer ≥ 1 (got ${ttlTurns}). ` +
+                'Use write() for entries that should never expire.');
+        }
+        const namespacedKey = SharedMemory.namespaceKey(agentName, key);
+        const fullMetadata = { ...metadata, agent: agentName };
+        if (typeof this.store.setWithExpiry === 'function') {
+            const expiresAtTurn = this.turnCount + ttlTurns;
+            await this.store.setWithExpiry(namespacedKey, value, expiresAtTurn, fullMetadata);
+        }
+        else {
+            // Custom store doesn't support TTL — degrade to plain set.
+            await this.store.set(namespacedKey, value, fullMetadata);
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Read
+    // ---------------------------------------------------------------------------
+    /**
+     * Read an entry by its fully-qualified key (`<agentName>/<key>`).
+     *
+     * Returns `null` when the key is absent **or** when the entry has expired
+     * (per its `expiresAtTurn` against the current turn counter). Expired
+     * entries are filtered out but **not** deleted from the underlying store —
+     * deletion is left to the store impl (Redis has native TTL, Postgres a
+     * cron, etc.). Reading is therefore safe to call from concurrent processes
+     * without the risk of stomping on a fresh write to the same key.
+     */
+    async read(key) {
+        const entry = await this.store.get(key);
+        if (entry === null)
+            return null;
+        if (this.isExpired(entry))
+            return null;
+        return entry;
+    }
+    // ---------------------------------------------------------------------------
+    // List
+    // ---------------------------------------------------------------------------
+    /** Returns every non-expired entry in the shared store, regardless of agent. */
+    async listAll() {
+        return this.filterExpired(await this.store.list());
+    }
+    /**
+     * Returns all non-expired 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();
+        const live = this.filterExpired(all);
+        return live.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(filter) {
+        let all = await this.store.list();
+        all = this.filterExpired(all);
+        if (filter?.taskIds && filter.taskIds.length > 0) {
+            const taskIds = new Set(filter.taskIds);
+            all = all.filter((entry) => {
+                const slashIdx = entry.key.indexOf('/');
+                const localKey = slashIdx === -1 ? entry.key : entry.key.slice(slashIdx + 1);
+                if (!localKey.startsWith('task:') || !localKey.endsWith(':result'))
+                    return false;
+                const taskId = localKey.slice('task:'.length, localKey.length - ':result'.length);
+                return taskIds.has(taskId);
+            });
+        }
+        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}`;
+    }
+    /** True when `entry.expiresAtTurn` is set and has been reached. */
+    isExpired(entry) {
+        return entry.expiresAtTurn !== undefined && this.turnCount >= entry.expiresAtTurn;
+    }
+    /**
+     * Drops expired entries from `entries`. **Does not delete from the
+     * underlying store** — that would race with concurrent writers in
+     * distributed backends (the entry being deleted may have been
+     * overwritten with a fresh value between our read and our delete).
+     * Stores that want active cleanup should implement their own TTL sweep
+     * (Redis: native EXPIRE; Postgres: a cron). Entries without
+     * `expiresAtTurn` are always kept.
+     */
+    filterExpired(entries) {
+        return entries.filter((entry) => !this.isExpired(entry));
+    }
+}
+//# 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":"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"}

package/dist/memory/store.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @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>;
+    /**
+     * Like {@link set}, but also records a turn-count expiry. The entry is
+     * stored as-is — expiry filtering is the caller's responsibility (typically
+     * {@link SharedMemory}, which owns the turn counter).
+     *
+     * `createdAt` is preserved on update, matching {@link set}.
+     */
+    setWithExpiry(key: string, value: string, expiresAtTurn: number, 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;;;;;;OAMG;IACG,aAAa,CACjB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,EACrB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,OAAO,CAAC,IAAI,CAAC;IAYhB,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,121 @@
+/**
+ * @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);
+    }
+    /**
+     * Like {@link set}, but also records a turn-count expiry. The entry is
+     * stored as-is — expiry filtering is the caller's responsibility (typically
+     * {@link SharedMemory}, which owns the turn counter).
+     *
+     * `createdAt` is preserved on update, matching {@link set}.
+     */
+    async setWithExpiry(key, value, expiresAtTurn, metadata) {
+        const existing = this.data.get(key);
+        const entry = {
+            key,
+            value,
+            metadata: metadata !== undefined ? { ...metadata } : undefined,
+            createdAt: existing?.createdAt ?? new Date(),
+            expiresAtTurn,
+        };
+        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":"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"}