@jackchen_me/open-multi-agent 1.0.0 → 1.0.1

package/src/llm/openai.ts

@@ -1,292 +0,0 @@
-/**
- * @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'
-import type {
-  ChatCompletionChunk,
-} from 'openai/resources/chat/completions/index.js'
-
-import type {
-  ContentBlock,
-  LLMAdapter,
-  LLMChatOptions,
-  LLMMessage,
-  LLMResponse,
-  LLMStreamOptions,
-  LLMToolDef,
-  StreamEvent,
-  TextBlock,
-  ToolUseBlock,
-} from '../types.js'
-
-import {
-  toOpenAITool,
-  fromOpenAICompletion,
-  normalizeFinishReason,
-  buildOpenAIMessageList,
-} from './openai-common.js'
-import { extractToolCallsFromText } from '../tool/text-tool-extractor.js'
-
-// ---------------------------------------------------------------------------
-// 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 implements LLMAdapter {
-  readonly name: string = 'openai'
-
-  readonly #client: OpenAI
-
-  constructor(apiKey?: string, baseURL?: string) {
-    this.#client = new OpenAI({
-      apiKey: apiKey ?? process.env['OPENAI_API_KEY'],
-      baseURL,
-    })
-  }
-
-  // -------------------------------------------------------------------------
-  // 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: LLMMessage[], options: LLMChatOptions): Promise<LLMResponse> {
-    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,
-      },
-    )
-
-    const toolNames = options.tools?.map(t => t.name)
-    return fromOpenAICompletion(completion, toolNames)
-  }
-
-  // -------------------------------------------------------------------------
-  // 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: LLMMessage[],
-    options: LLMStreamOptions,
-  ): AsyncIterable<StreamEvent> {
-    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: string = 'stop'
-    let inputTokens = 0
-    let outputTokens = 0
-
-    // tool_calls are streamed piecemeal; key = tool call index
-    const toolCallBuffers = new Map<
-      number,
-      { id: string; name: string; argsJson: string }
-    >()
-
-    // 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: ChatCompletionChunk.Choice | undefined = 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: StreamEvent = { 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: ToolUseBlock[] = []
-      for (const buf of toolCallBuffers.values()) {
-        let parsedInput: Record<string, unknown> = {}
-        try {
-          const parsed: unknown = JSON.parse(buf.argsJson)
-          if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
-            parsedInput = parsed as Record<string, unknown>
-          }
-        } catch {
-          // Malformed JSON — surface as empty object.
-        }
-
-        const toolUseBlock: ToolUseBlock = {
-          type: 'tool_use',
-          id: buf.id,
-          name: buf.name,
-          input: parsedInput,
-        }
-        finalToolUseBlocks.push(toolUseBlock)
-        const toolUseEvent: StreamEvent = { type: 'tool_use', data: toolUseBlock }
-        yield toolUseEvent
-      }
-
-      // Build the complete content array for the done response.
-      const doneContent: ContentBlock[] = []
-      if (fullText.length > 0) {
-        const textBlock: TextBlock = { type: 'text', text: fullText }
-        doneContent.push(textBlock)
-      }
-      doneContent.push(...finalToolUseBlocks)
-
-      // Fallback: extract tool calls from text when streaming produced no
-      // native tool_calls (same logic as fromOpenAICompletion).
-      if (finalToolUseBlocks.length === 0 && fullText.length > 0 && options.tools) {
-        const toolNames = options.tools.map(t => t.name)
-        const extracted = extractToolCallsFromText(fullText, toolNames)
-        if (extracted.length > 0) {
-          doneContent.push(...extracted)
-          for (const block of extracted) {
-            yield { type: 'tool_use', data: block } satisfies StreamEvent
-          }
-        }
-      }
-
-      const hasToolUseBlocks = doneContent.some(b => b.type === 'tool_use')
-      const resolvedStopReason = hasToolUseBlocks && finalFinishReason === 'stop'
-        ? 'tool_use'
-        : normalizeFinishReason(finalFinishReason)
-
-      const finalResponse: LLMResponse = {
-        id: completionId,
-        content: doneContent,
-        model: completionModel,
-        stop_reason: resolvedStopReason,
-        usage: { input_tokens: inputTokens, output_tokens: outputTokens },
-      }
-
-      const doneEvent: StreamEvent = { type: 'done', data: finalResponse }
-      yield doneEvent
-    } catch (err) {
-      const error = err instanceof Error ? err : new Error(String(err))
-      const errorEvent: StreamEvent = { type: 'error', data: error }
-      yield errorEvent
-    }
-  }
-}
-
-// Re-export types that consumers of this module commonly need alongside the adapter.
-export type {
-  ContentBlock,
-  LLMAdapter,
-  LLMChatOptions,
-  LLMMessage,
-  LLMResponse,
-  LLMStreamOptions,
-  LLMToolDef,
-  StreamEvent,
-}

package/src/memory/shared.ts

@@ -1,181 +0,0 @@
-/**
- * @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'
-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 {
-  private readonly store: InMemoryStore
-
-  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: string,
-    key: string,
-    value: string,
-    metadata?: Record<string, unknown>,
-  ): Promise<void> {
-    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: string): Promise<MemoryEntry | null> {
-    return this.store.get(key)
-  }
-
-  // ---------------------------------------------------------------------------
-  // List
-  // ---------------------------------------------------------------------------
-
-  /** Returns every entry in the shared store, regardless of agent. */
-  async listAll(): Promise<MemoryEntry[]> {
-    return this.store.list()
-  }
-
-  /**
-   * Returns all entries written by `agentName` (i.e. those whose key starts
-   * with `<agentName>/`).
-   */
-  async listByAgent(agentName: string): Promise<MemoryEntry[]> {
-    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(): Promise<string> {
-    const all = await this.store.list()
-    if (all.length === 0) return ''
-
-    // Group entries by agent name.
-    const byAgent = new Map<string, Array<{ localKey: string; value: string }>>()
-    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: string[] = ['## 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(): MemoryStore {
-    return this.store
-  }
-
-  // ---------------------------------------------------------------------------
-  // Private helpers
-  // ---------------------------------------------------------------------------
-
-  private static namespaceKey(agentName: string, key: string): string {
-    return `${agentName}/${key}`
-  }
-}

package/src/memory/store.ts

@@ -1,124 +0,0 @@
-/**
- * @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'
-
-// ---------------------------------------------------------------------------
-// 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 implements MemoryStore {
-  private readonly data = new Map<string, MemoryEntry>()
-
-  // ---------------------------------------------------------------------------
-  // MemoryStore interface
-  // ---------------------------------------------------------------------------
-
-  /** Returns the entry for `key`, or `null` if not present. */
-  async get(key: string): Promise<MemoryEntry | null> {
-    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: string,
-    value: string,
-    metadata?: Record<string, unknown>,
-  ): Promise<void> {
-    const existing = this.data.get(key)
-    const entry: MemoryEntry = {
-      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(): Promise<MemoryEntry[]> {
-    return Array.from(this.data.values())
-  }
-
-  /**
-   * Removes the entry for `key`.
-   * Deleting a non-existent key is a no-op.
-   */
-  async delete(key: string): Promise<void> {
-    this.data.delete(key)
-  }
-
-  /** Removes **all** entries from the store. */
-  async clear(): Promise<void> {
-    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: string): Promise<MemoryEntry[]> {
-    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(): number {
-    return this.data.size
-  }
-
-  /** Returns `true` if `key` exists in the store. */
-  has(key: string): boolean {
-    return this.data.has(key)
-  }
-}