@jackchen_me/open-multi-agent 0.1.0

package/dist/llm/openai.js

@@ -0,0 +1,424 @@
+/**
+ * @fileoverview OpenAI adapter implementing {@link LLMAdapter}.
+ *
+ * Converts between the framework's internal {@link ContentBlock} types and the
+ * OpenAI Chat Completions wire format. Key mapping decisions:
+ *
+ * - Framework `tool_use` blocks in assistant messages → OpenAI `tool_calls`
+ * - Framework `tool_result` blocks in user messages  → OpenAI `tool` role messages
+ * - Framework `image` blocks in user messages        → OpenAI image content parts
+ * - System prompt in {@link LLMChatOptions}           → prepended `system` message
+ *
+ * Because OpenAI and Anthropic use fundamentally different role-based structures
+ * for tool calling (Anthropic embeds tool results in user-role content arrays;
+ * OpenAI uses a dedicated `tool` role), the conversion necessarily splits
+ * `tool_result` blocks out into separate top-level messages.
+ *
+ * API key resolution order:
+ *   1. `apiKey` constructor argument
+ *   2. `OPENAI_API_KEY` environment variable
+ *
+ * @example
+ * ```ts
+ * import { OpenAIAdapter } from './openai.js'
+ *
+ * const adapter = new OpenAIAdapter()
+ * const response = await adapter.chat(messages, {
+ *   model: 'gpt-5.4',
+ *   maxTokens: 1024,
+ * })
+ * ```
+ */
+import OpenAI from 'openai';
+// ---------------------------------------------------------------------------
+// Internal helpers — framework → OpenAI
+// ---------------------------------------------------------------------------
+/**
+ * Convert a framework {@link LLMToolDef} to an OpenAI {@link ChatCompletionTool}.
+ *
+ * OpenAI wraps the function definition inside a `function` key and a `type`
+ * discriminant. The `inputSchema` is already a JSON Schema object.
+ */
+function toOpenAITool(tool) {
+    return {
+        type: 'function',
+        function: {
+            name: tool.name,
+            description: tool.description,
+            parameters: tool.inputSchema,
+        },
+    };
+}
+/**
+ * Determine whether a framework message contains any `tool_result` content
+ * blocks, which must be serialised as separate OpenAI `tool`-role messages.
+ */
+function hasToolResults(msg) {
+    return msg.content.some((b) => b.type === 'tool_result');
+}
+/**
+ * Convert a single framework {@link LLMMessage} into one or more OpenAI
+ * {@link ChatCompletionMessageParam} entries.
+ *
+ * The expansion is necessary because OpenAI represents tool results as
+ * top-level messages with role `tool`, whereas in our model they are content
+ * blocks inside a `user` message.
+ *
+ * Expansion rules:
+ * - A `user` message containing only text/image blocks → single user message
+ * - A `user` message containing `tool_result` blocks → one `tool` message per
+ *   tool_result block; any remaining text/image blocks are folded into an
+ *   additional user message prepended to the group
+ * - An `assistant` message → single assistant message with optional tool_calls
+ */
+function toOpenAIMessages(messages) {
+    const result = [];
+    for (const msg of messages) {
+        if (msg.role === 'assistant') {
+            result.push(toOpenAIAssistantMessage(msg));
+        }
+        else {
+            // user role
+            if (!hasToolResults(msg)) {
+                result.push(toOpenAIUserMessage(msg));
+            }
+            else {
+                // Split: text/image blocks become a user message (if any exist), then
+                // each tool_result block becomes an independent tool message.
+                const nonToolBlocks = msg.content.filter((b) => b.type !== 'tool_result');
+                if (nonToolBlocks.length > 0) {
+                    result.push(toOpenAIUserMessage({ role: 'user', content: nonToolBlocks }));
+                }
+                for (const block of msg.content) {
+                    if (block.type === 'tool_result') {
+                        const toolMsg = {
+                            role: 'tool',
+                            tool_call_id: block.tool_use_id,
+                            content: block.content,
+                        };
+                        result.push(toolMsg);
+                    }
+                }
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Convert a `user`-role framework message into an OpenAI user message.
+ * Image blocks are converted to the OpenAI image_url content part format.
+ */
+function toOpenAIUserMessage(msg) {
+    // If the entire content is a single text block, use the compact string form
+    // to keep the request payload smaller.
+    if (msg.content.length === 1 && msg.content[0]?.type === 'text') {
+        return { role: 'user', content: msg.content[0].text };
+    }
+    const parts = [];
+    for (const block of msg.content) {
+        if (block.type === 'text') {
+            parts.push({ type: 'text', text: block.text });
+        }
+        else if (block.type === 'image') {
+            parts.push({
+                type: 'image_url',
+                image_url: {
+                    url: `data:${block.source.media_type};base64,${block.source.data}`,
+                },
+            });
+        }
+        // tool_result blocks are handled by the caller (toOpenAIMessages); skip here.
+    }
+    return { role: 'user', content: parts };
+}
+/**
+ * Convert an `assistant`-role framework message into an OpenAI assistant message.
+ *
+ * Any `tool_use` blocks become `tool_calls`; `text` blocks become the message content.
+ */
+function toOpenAIAssistantMessage(msg) {
+    const toolCalls = [];
+    const textParts = [];
+    for (const block of msg.content) {
+        if (block.type === 'tool_use') {
+            toolCalls.push({
+                id: block.id,
+                type: 'function',
+                function: {
+                    name: block.name,
+                    arguments: JSON.stringify(block.input),
+                },
+            });
+        }
+        else if (block.type === 'text') {
+            textParts.push(block.text);
+        }
+    }
+    const assistantMsg = {
+        role: 'assistant',
+        content: textParts.length > 0 ? textParts.join('') : null,
+    };
+    if (toolCalls.length > 0) {
+        assistantMsg.tool_calls = toolCalls;
+    }
+    return assistantMsg;
+}
+// ---------------------------------------------------------------------------
+// Internal helpers — OpenAI → framework
+// ---------------------------------------------------------------------------
+/**
+ * Convert an OpenAI {@link ChatCompletion} into a framework {@link LLMResponse}.
+ *
+ * We take only the first choice (index 0), consistent with how the framework
+ * is designed for single-output agents.
+ */
+function fromOpenAICompletion(completion) {
+    const choice = completion.choices[0];
+    if (choice === undefined) {
+        throw new Error('OpenAI returned a completion with no choices');
+    }
+    const content = [];
+    const message = choice.message;
+    if (message.content !== null && message.content !== undefined) {
+        const textBlock = { type: 'text', text: message.content };
+        content.push(textBlock);
+    }
+    for (const toolCall of message.tool_calls ?? []) {
+        let parsedInput = {};
+        try {
+            const parsed = JSON.parse(toolCall.function.arguments);
+            if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                parsedInput = parsed;
+            }
+        }
+        catch {
+            // Malformed arguments from the model — surface as empty object.
+        }
+        const toolUseBlock = {
+            type: 'tool_use',
+            id: toolCall.id,
+            name: toolCall.function.name,
+            input: parsedInput,
+        };
+        content.push(toolUseBlock);
+    }
+    const stopReason = normalizeFinishReason(choice.finish_reason ?? 'stop');
+    return {
+        id: completion.id,
+        content,
+        model: completion.model,
+        stop_reason: stopReason,
+        usage: {
+            input_tokens: completion.usage?.prompt_tokens ?? 0,
+            output_tokens: completion.usage?.completion_tokens ?? 0,
+        },
+    };
+}
+/**
+ * Normalize an OpenAI `finish_reason` string to the framework's canonical
+ * stop-reason vocabulary so consumers never need to branch on provider-specific
+ * strings.
+ *
+ * Mapping:
+ * - `'stop'`           → `'end_turn'`
+ * - `'tool_calls'`     → `'tool_use'`
+ * - `'length'`         → `'max_tokens'`
+ * - `'content_filter'` → `'content_filter'`
+ * - anything else      → passed through unchanged
+ */
+function normalizeFinishReason(reason) {
+    switch (reason) {
+        case 'stop': return 'end_turn';
+        case 'tool_calls': return 'tool_use';
+        case 'length': return 'max_tokens';
+        case 'content_filter': return 'content_filter';
+        default: return reason;
+    }
+}
+// ---------------------------------------------------------------------------
+// Adapter implementation
+// ---------------------------------------------------------------------------
+/**
+ * LLM adapter backed by the OpenAI Chat Completions API.
+ *
+ * Thread-safe — a single instance may be shared across concurrent agent runs.
+ */
+export class OpenAIAdapter {
+    name = 'openai';
+    #client;
+    constructor(apiKey) {
+        this.#client = new OpenAI({
+            apiKey: apiKey ?? process.env['OPENAI_API_KEY'],
+        });
+    }
+    // -------------------------------------------------------------------------
+    // chat()
+    // -------------------------------------------------------------------------
+    /**
+     * Send a synchronous (non-streaming) chat request and return the complete
+     * {@link LLMResponse}.
+     *
+     * Throws an `OpenAI.APIError` on non-2xx responses. Callers should catch and
+     * handle these (e.g. rate limits, context length exceeded).
+     */
+    async chat(messages, options) {
+        const openAIMessages = buildOpenAIMessageList(messages, options.systemPrompt);
+        const completion = await this.#client.chat.completions.create({
+            model: options.model,
+            messages: openAIMessages,
+            max_tokens: options.maxTokens,
+            temperature: options.temperature,
+            tools: options.tools ? options.tools.map(toOpenAITool) : undefined,
+            stream: false,
+        }, {
+            signal: options.abortSignal,
+        });
+        return fromOpenAICompletion(completion);
+    }
+    // -------------------------------------------------------------------------
+    // stream()
+    // -------------------------------------------------------------------------
+    /**
+     * Send a streaming chat request and yield {@link StreamEvent}s incrementally.
+     *
+     * Sequence guarantees match {@link AnthropicAdapter.stream}:
+     * - Zero or more `text` events
+     * - Zero or more `tool_use` events (emitted once per tool call, after
+     *   arguments have been fully assembled)
+     * - Exactly one terminal event: `done` or `error`
+     */
+    async *stream(messages, options) {
+        const openAIMessages = buildOpenAIMessageList(messages, options.systemPrompt);
+        // We request usage in the final chunk so we can include it in the `done` event.
+        const streamResponse = await this.#client.chat.completions.create({
+            model: options.model,
+            messages: openAIMessages,
+            max_tokens: options.maxTokens,
+            temperature: options.temperature,
+            tools: options.tools ? options.tools.map(toOpenAITool) : undefined,
+            stream: true,
+            stream_options: { include_usage: true },
+        }, {
+            signal: options.abortSignal,
+        });
+        // Accumulate state across chunks.
+        let completionId = '';
+        let completionModel = '';
+        let finalFinishReason = 'stop';
+        let inputTokens = 0;
+        let outputTokens = 0;
+        // tool_calls are streamed piecemeal; key = tool call index
+        const toolCallBuffers = new Map();
+        // Full text accumulator for the `done` response.
+        let fullText = '';
+        try {
+            for await (const chunk of streamResponse) {
+                completionId = chunk.id;
+                completionModel = chunk.model;
+                // Usage is only populated in the final chunk when stream_options.include_usage is set.
+                if (chunk.usage !== null && chunk.usage !== undefined) {
+                    inputTokens = chunk.usage.prompt_tokens;
+                    outputTokens = chunk.usage.completion_tokens;
+                }
+                const choice = chunk.choices[0];
+                if (choice === undefined)
+                    continue;
+                const delta = choice.delta;
+                // --- text delta ---
+                if (delta.content !== null && delta.content !== undefined) {
+                    fullText += delta.content;
+                    const textEvent = { type: 'text', data: delta.content };
+                    yield textEvent;
+                }
+                // --- tool call delta ---
+                for (const toolCallDelta of delta.tool_calls ?? []) {
+                    const idx = toolCallDelta.index;
+                    if (!toolCallBuffers.has(idx)) {
+                        toolCallBuffers.set(idx, {
+                            id: toolCallDelta.id ?? '',
+                            name: toolCallDelta.function?.name ?? '',
+                            argsJson: '',
+                        });
+                    }
+                    const buf = toolCallBuffers.get(idx);
+                    // buf is guaranteed to exist: we just set it above.
+                    if (buf !== undefined) {
+                        if (toolCallDelta.id)
+                            buf.id = toolCallDelta.id;
+                        if (toolCallDelta.function?.name)
+                            buf.name = toolCallDelta.function.name;
+                        if (toolCallDelta.function?.arguments) {
+                            buf.argsJson += toolCallDelta.function.arguments;
+                        }
+                    }
+                }
+                if (choice.finish_reason !== null && choice.finish_reason !== undefined) {
+                    finalFinishReason = choice.finish_reason;
+                }
+            }
+            // Emit accumulated tool_use events after the stream ends.
+            const finalToolUseBlocks = [];
+            for (const buf of toolCallBuffers.values()) {
+                let parsedInput = {};
+                try {
+                    const parsed = JSON.parse(buf.argsJson);
+                    if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                        parsedInput = parsed;
+                    }
+                }
+                catch {
+                    // Malformed JSON — surface as empty object.
+                }
+                const toolUseBlock = {
+                    type: 'tool_use',
+                    id: buf.id,
+                    name: buf.name,
+                    input: parsedInput,
+                };
+                finalToolUseBlocks.push(toolUseBlock);
+                const toolUseEvent = { type: 'tool_use', data: toolUseBlock };
+                yield toolUseEvent;
+            }
+            // Build the complete content array for the done response.
+            const doneContent = [];
+            if (fullText.length > 0) {
+                const textBlock = { type: 'text', text: fullText };
+                doneContent.push(textBlock);
+            }
+            doneContent.push(...finalToolUseBlocks);
+            const finalResponse = {
+                id: completionId,
+                content: doneContent,
+                model: completionModel,
+                stop_reason: normalizeFinishReason(finalFinishReason),
+                usage: { input_tokens: inputTokens, output_tokens: outputTokens },
+            };
+            const doneEvent = { type: 'done', data: finalResponse };
+            yield doneEvent;
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            const errorEvent = { type: 'error', data: error };
+            yield errorEvent;
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Private utility
+// ---------------------------------------------------------------------------
+/**
+ * Prepend a system message when `systemPrompt` is provided, then append the
+ * converted conversation messages.
+ *
+ * OpenAI represents system instructions as a message with `role: 'system'`
+ * at the top of the array, not as a separate API parameter.
+ */
+function buildOpenAIMessageList(messages, systemPrompt) {
+    const result = [];
+    if (systemPrompt !== undefined && systemPrompt.length > 0) {
+        result.push({ role: 'system', content: systemPrompt });
+    }
+    result.push(...toOpenAIMessages(messages));
+    return result;
+}
+//# sourceMappingURL=openai.js.map

package/dist/llm/openai.js.map

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

package/dist/memory/shared.d.ts

@@ -0,0 +1,86 @@
+/**
+ * @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 type { MemoryEntry, MemoryStore } from '../types.js';
+/**
+ * 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 declare class SharedMemory {
+    private readonly store;
+    constructor();
+    /**
+     * 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.
+     */
+    write(agentName: string, key: string, value: string, metadata?: Record<string, unknown>): Promise<void>;
+    /**
+     * Read an entry by its fully-qualified key (`<agentName>/<key>`).
+     *
+     * Returns `null` when the key is absent.
+     */
+    read(key: string): Promise<MemoryEntry | null>;
+    /** Returns every entry in the shared store, regardless of agent. */
+    listAll(): Promise<MemoryEntry[]>;
+    /**
+     * Returns all entries written by `agentName` (i.e. those whose key starts
+     * with `<agentName>/`).
+     */
+    listByAgent(agentName: string): Promise<MemoryEntry[]>;
+    /**
+     * 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
+     * ```
+     */
+    getSummary(): Promise<string>;
+    /**
+     * 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(): MemoryStore;
+    private static namespaceKey;
+}
+//# sourceMappingURL=shared.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/memory/shared.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAO3D;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;;IAUrC;;;;;;;;;;OAUG;IACG,KAAK,CACT,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,OAAO,CAAC,IAAI,CAAC;IAYhB;;;;OAIG;IACG,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAQpD,oEAAoE;IAC9D,OAAO,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAIvC;;;OAGG;IACG,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAU5D;;;;;;;;;;;;;;;;;;;OAmBG;IACG,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IAsCnC;;;;OAIG;IACH,QAAQ,IAAI,WAAW;IAQvB,OAAO,CAAC,MAAM,CAAC,YAAY;CAG5B"}