@jackchen_me/open-multi-agent 0.2.0 → 1.0.1

package/src/llm/openai-common.ts

@@ -1,255 +0,0 @@
-/**
- * @fileoverview Shared OpenAI wire-format conversion helpers.
- *
- * Both the OpenAI and Copilot adapters use the OpenAI Chat Completions API
- * format. This module contains the common conversion logic so it isn't
- * duplicated across adapters.
- */
-
-import OpenAI from 'openai'
-import type {
-  ChatCompletion,
-  ChatCompletionAssistantMessageParam,
-  ChatCompletionMessageParam,
-  ChatCompletionMessageToolCall,
-  ChatCompletionTool,
-  ChatCompletionToolMessageParam,
-  ChatCompletionUserMessageParam,
-} from 'openai/resources/chat/completions/index.js'
-
-import type {
-  ContentBlock,
-  LLMMessage,
-  LLMResponse,
-  LLMToolDef,
-  TextBlock,
-  ToolUseBlock,
-} from '../types.js'
-
-// ---------------------------------------------------------------------------
-// Framework → OpenAI
-// ---------------------------------------------------------------------------
-
-/**
- * Convert a framework {@link LLMToolDef} to an OpenAI {@link ChatCompletionTool}.
- */
-export function toOpenAITool(tool: LLMToolDef): ChatCompletionTool {
-  return {
-    type: 'function',
-    function: {
-      name: tool.name,
-      description: tool.description,
-      parameters: tool.inputSchema as Record<string, unknown>,
-    },
-  }
-}
-
-/**
- * Determine whether a framework message contains any `tool_result` content
- * blocks, which must be serialised as separate OpenAI `tool`-role messages.
- */
-function hasToolResults(msg: LLMMessage): boolean {
-  return msg.content.some((b) => b.type === 'tool_result')
-}
-
-/**
- * Convert framework {@link LLMMessage}s into OpenAI
- * {@link ChatCompletionMessageParam} entries.
- *
- * `tool_result` blocks are expanded into top-level `tool`-role messages
- * because OpenAI uses a dedicated role for tool results rather than embedding
- * them inside user-content arrays.
- */
-export function toOpenAIMessages(messages: LLMMessage[]): ChatCompletionMessageParam[] {
-  const result: ChatCompletionMessageParam[] = []
-
-  for (const msg of messages) {
-    if (msg.role === 'assistant') {
-      result.push(toOpenAIAssistantMessage(msg))
-    } else {
-      // user role
-      if (!hasToolResults(msg)) {
-        result.push(toOpenAIUserMessage(msg))
-      } else {
-        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: ChatCompletionToolMessageParam = {
-              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: LLMMessage): ChatCompletionUserMessageParam {
-  if (msg.content.length === 1 && msg.content[0]?.type === 'text') {
-    return { role: 'user', content: msg.content[0].text }
-  }
-
-  type ContentPart = OpenAI.Chat.ChatCompletionContentPartText | OpenAI.Chat.ChatCompletionContentPartImage
-  const parts: ContentPart[] = []
-
-  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.
- * `tool_use` blocks become `tool_calls`; `text` blocks become message content.
- */
-function toOpenAIAssistantMessage(msg: LLMMessage): ChatCompletionAssistantMessageParam {
-  const toolCalls: ChatCompletionMessageToolCall[] = []
-  const textParts: string[] = []
-
-  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: ChatCompletionAssistantMessageParam = {
-    role: 'assistant',
-    content: textParts.length > 0 ? textParts.join('') : null,
-  }
-
-  if (toolCalls.length > 0) {
-    assistantMsg.tool_calls = toolCalls
-  }
-
-  return assistantMsg
-}
-
-// ---------------------------------------------------------------------------
-// OpenAI → Framework
-// ---------------------------------------------------------------------------
-
-/**
- * Convert an OpenAI {@link ChatCompletion} into a framework {@link LLMResponse}.
- *
- * Takes only the first choice (index 0), consistent with how the framework
- * is designed for single-output agents.
- */
-export function fromOpenAICompletion(completion: ChatCompletion): LLMResponse {
-  const choice = completion.choices[0]
-  if (choice === undefined) {
-    throw new Error('OpenAI returned a completion with no choices')
-  }
-
-  const content: ContentBlock[] = []
-  const message = choice.message
-
-  if (message.content !== null && message.content !== undefined) {
-    const textBlock: TextBlock = { type: 'text', text: message.content }
-    content.push(textBlock)
-  }
-
-  for (const toolCall of message.tool_calls ?? []) {
-    let parsedInput: Record<string, unknown> = {}
-    try {
-      const parsed: unknown = JSON.parse(toolCall.function.arguments)
-      if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
-        parsedInput = parsed as Record<string, unknown>
-      }
-    } catch {
-      // Malformed arguments from the model — surface as empty object.
-    }
-
-    const toolUseBlock: 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.
- *
- * Mapping:
- * - `'stop'`           → `'end_turn'`
- * - `'tool_calls'`     → `'tool_use'`
- * - `'length'`         → `'max_tokens'`
- * - `'content_filter'` → `'content_filter'`
- * - anything else      → passed through unchanged
- */
-export function normalizeFinishReason(reason: string): string {
-  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
-  }
-}
-
-/**
- * Prepend a system message when `systemPrompt` is provided, then append the
- * converted conversation messages.
- */
-export function buildOpenAIMessageList(
-  messages: LLMMessage[],
-  systemPrompt: string | undefined,
-): ChatCompletionMessageParam[] {
-  const result: ChatCompletionMessageParam[] = []
-
-  if (systemPrompt !== undefined && systemPrompt.length > 0) {
-    result.push({ role: 'system', content: systemPrompt })
-  }
-
-  result.push(...toOpenAIMessages(messages))
-  return result
-}

package/src/llm/openai.ts

@@ -1,272 +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'
-
-// ---------------------------------------------------------------------------
-// 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 = '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,
-      },
-    )
-
-    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: 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)
-
-      const finalResponse: LLMResponse = {
-        id: completionId,
-        content: doneContent,
-        model: completionModel,
-        stop_reason: normalizeFinishReason(finalFinishReason),
-        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}`
-  }
-}