octoflow-core 1.0.0

package/dist/adapters/agents/custom-api-client.js

@@ -0,0 +1,308 @@
+import { withRetry } from "../../utils/retry.js";
+import { buildFetchWithTimeout } from "../../utils/timeout.js";
+import { APPROVAL_POSTURE_CUSTOM_API } from "./approval-posture.js";
+import { toBackendInfo } from "./backends/shared.js";
+import {
+  buildAuthHeader,
+  buildCustomApiPayload,
+  createOpenAiCompatUsage,
+  customApiRunResult,
+  parseCustomApiSseLine,
+  warnMissingApiProtocol
+} from "./custom-api-chat-helpers.js";
+class CustomApiClient {
+  opts;
+  _protocol;
+  _provider;
+  _history = [];
+  constructor(opts) {
+    this.opts = opts;
+    if (opts.protocol) {
+      this._protocol = opts.protocol;
+    } else {
+      this._protocol = "openai-chat";
+      warnMissingApiProtocol(opts.url);
+    }
+    this._provider = opts.provider ?? "custom";
+  }
+  /**
+   * : pure, synchronous snapshot of this client's declared protocol,
+   * provider, resolved endpoint, and capabilities. No I/O.
+   */
+  info() {
+    return toBackendInfo({
+      backend: "custom-api",
+      type: "api",
+      protocol: this._protocol,
+      provider: this._provider,
+      model: this.opts.model,
+      host: this.opts.url,
+      version: null,
+      capabilities: {
+        streaming: true,
+        sessionPersistence: false,
+        workingDirectory: false,
+        forceMode: false,
+        systemPrompt: true,
+        planning: false,
+        tools: false,
+        mcp: false,
+        structuredHistory: true,
+        approvalCallback: APPROVAL_POSTURE_CUSTOM_API
+      }
+    });
+  }
+  async run(prompt, opts) {
+    const retries = opts?.retries ?? this.opts.retries ?? 0;
+    return this._withRetry(() => this._run(prompt, opts), retries, {
+      phase: "run",
+      onError: opts?.onError,
+      onRetry: opts?.onRetry
+    });
+  }
+  async _run(prompt, opts) {
+    const explicitHistory = opts?.structuredHistory !== void 0;
+    const response = await this.chat(
+      prompt,
+      explicitHistory ? [] : this._history,
+      void 0,
+      opts
+    );
+    if (!explicitHistory) {
+      this._history.push(
+        { role: "user", content: prompt },
+        { role: "assistant", content: response.text }
+      );
+    }
+    return customApiRunResult(
+      response.text,
+      response.usage,
+      this._modelForOptions(opts)
+    );
+  }
+  async stream(prompt, onEvent, opts) {
+    const retries = opts?.retries ?? this.opts.retries ?? 0;
+    return this._withRetry(() => this._stream(prompt, onEvent, opts), retries, {
+      phase: "stream",
+      onError: opts?.onError,
+      onRetry: opts?.onRetry
+    });
+  }
+  async _stream(prompt, onEvent, opts) {
+    const explicitHistory = opts?.structuredHistory !== void 0;
+    const response = await this.chat(
+      prompt,
+      explicitHistory ? [] : this._history,
+      onEvent,
+      opts
+    );
+    if (!explicitHistory) {
+      this._history.push(
+        { role: "user", content: prompt },
+        { role: "assistant", content: response.text }
+      );
+    }
+    return customApiRunResult(
+      response.text,
+      response.usage,
+      this._modelForOptions(opts)
+    );
+  }
+  session(opts) {
+    return new CustomApiSession(this, opts);
+  }
+  async isReady() {
+    try {
+      const fetchImpl = this.opts.fetch ?? globalThis.fetch;
+      const headers = this.buildHeaders();
+      const response = await fetchImpl(this.opts.url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          model: this.opts.model,
+          messages: [{ role: "user", content: "ping" }],
+          max_tokens: 1
+        }),
+        signal: this.opts.timeoutMs ? AbortSignal.timeout(Math.min(this.opts.timeoutMs, 1e4)) : AbortSignal.timeout(1e4)
+      });
+      return response.ok || response.status === 401 || response.status === 403;
+    } catch {
+      return false;
+    }
+  }
+  /** @internal */
+  async _runTurn(prompt, history, onEvent, opts) {
+    return this.chat(prompt, history, onEvent, opts);
+  }
+  /** @internal */
+  _modelForOptions(opts) {
+    return opts?.model ?? this.opts.model;
+  }
+  async chat(prompt, history, onEvent, opts) {
+    const timeoutMs = opts?.timeoutMs ?? this.opts.timeoutMs;
+    const fetchImpl = buildFetchWithTimeout(
+      this.opts.fetch ?? globalThis.fetch,
+      timeoutMs,
+      opts?.signal
+    );
+    const headers = this.buildHeaders();
+    const mergedOptions = this.mergeRunOptions(opts);
+    const payload = buildCustomApiPayload(
+      prompt,
+      history,
+      opts?.systemPrompt ?? this.opts.systemPrompt,
+      mergedOptions
+    );
+    const model = opts?.model ?? this.opts.model;
+    const stream = Boolean(onEvent);
+    const body = {
+      model,
+      messages: payload.messages,
+      stream,
+      ...stream ? { stream_options: { include_usage: true } } : {}
+    };
+    const promptCacheKey = this.shouldEmitPromptCacheKey(
+      mergedOptions,
+      payload.promptCacheKey
+    ) ? payload.promptCacheKey : void 0;
+    if (promptCacheKey) {
+      body.prompt_cache_key = promptCacheKey;
+    }
+    const response = await fetchImpl(this.opts.url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body)
+    });
+    if (!response.ok) {
+      const body2 = await response.text().catch(() => "");
+      throw new Error(`API returned ${response.status}: ${body2.slice(0, 500)}`);
+    }
+    if (stream && onEvent) {
+      return this.consumeStream(response, onEvent, promptCacheKey);
+    }
+    const json = await response.json();
+    const text = json.choices?.[0]?.message?.content ?? "";
+    const usage = json.usage ? createOpenAiCompatUsage(json.usage, promptCacheKey) : null;
+    return { text, usage };
+  }
+  mergeRunOptions(opts) {
+    return {
+      ...opts ?? {},
+      cache: opts?.cache ?? this.opts.cache,
+      cacheControl: opts?.cacheControl ?? this.opts.cacheControl,
+      systemPromptParts: opts?.systemPromptParts ?? this.opts.systemPromptParts
+    };
+  }
+  shouldEmitPromptCacheKey(opts, promptCacheKey) {
+    if (!promptCacheKey) return false;
+    if (this._protocol !== "openai-chat" && this._protocol !== "openai-responses") {
+      return false;
+    }
+    if (opts.cache?.enabled === false) return false;
+    if (opts.cacheControl?.system === "static") return false;
+    const policy = this.opts.promptCacheKey ?? "auto";
+    if (policy === true) return true;
+    if (policy === false) return false;
+    return this._provider === "openai";
+  }
+  async consumeStream(response, onEvent, promptCacheKey) {
+    const reader = response.body?.getReader();
+    if (!reader) throw new Error("Response body is not readable");
+    const decoder = new TextDecoder();
+    let fullText = "";
+    let lastUsage = null;
+    let buffer = "";
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? "";
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (!trimmed) continue;
+          const parsed = parseCustomApiSseLine(trimmed);
+          if (!parsed) continue;
+          const delta = parsed.choices?.[0]?.delta?.content ?? "";
+          if (delta) {
+            fullText += delta;
+            await onEvent({ type: "text", text: delta });
+          }
+          if (parsed.usage) {
+            lastUsage = createOpenAiCompatUsage(parsed.usage, promptCacheKey);
+          }
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+    await onEvent({ type: "result", text: fullText, usage: lastUsage });
+    return { text: fullText, usage: lastUsage };
+  }
+  buildHeaders() {
+    return {
+      "Content-Type": "application/json",
+      ...buildAuthHeader(this.opts.apiKey, this.opts.authScheme ?? "bearer"),
+      ...this.opts.headers ?? {}
+    };
+  }
+  _withRetry(fn, retries, options) {
+    return withRetry(fn, {
+      retries,
+      backend: "custom-api",
+      phase: options.phase,
+      onError: options.onError,
+      onRetry: options.onRetry
+    });
+  }
+}
+class CustomApiSession {
+  constructor(client, defaultOpts) {
+    this.client = client;
+    this.defaultOpts = defaultOpts;
+    this.maxHistory = defaultOpts?.maxHistory;
+  }
+  client;
+  defaultOpts;
+  _history = [];
+  _turnCount = 0;
+  maxHistory;
+  async send(prompt, opts) {
+    const merged = { ...this.defaultOpts, ...opts };
+    const retries = merged.retries ?? 0;
+    const { text, usage } = await this.client._withRetry(
+      () => this.client._runTurn(prompt, this._history, opts?.onEvent, merged),
+      retries,
+      {
+        phase: "session",
+        onError: merged.onError,
+        onRetry: merged.onRetry
+      }
+    );
+    this._history.push(
+      { role: "user", content: prompt },
+      { role: "assistant", content: text }
+    );
+    this._turnCount++;
+    if (this.maxHistory != null && this._history.length > this.maxHistory * 2) {
+      this._history = this._history.slice(-this.maxHistory * 2);
+    }
+    return customApiRunResult(text, usage, this.client._modelForOptions(merged));
+  }
+  async stream(prompt, onEvent, opts) {
+    return this.send(prompt, { ...opts, onEvent });
+  }
+  get turns() {
+    return this._turnCount;
+  }
+  reset() {
+    this._history = [];
+    this._turnCount = 0;
+  }
+}
+export {
+  CustomApiClient,
+  CustomApiSession
+};
+//# sourceMappingURL=custom-api-client.js.map

package/dist/adapters/agents/custom-api-client.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/adapters/agents/custom-api-client.ts"],
+  "sourcesContent": ["/**\n * CustomApiClient \u2014 connect to any OpenAI-compatible chat completions API.\n *\n * Works with self-hosted LLMs (vLLM, text-generation-inference, LocalAI),\n * proxy services (LiteLLM, OpenRouter), or any custom endpoint that accepts\n * the standard chat completions request format.\n *\n * @example\n * const client = new CustomApiClient({\n *   url: 'https://my-llm.internal/v1/chat/completions',\n *   apiKey: process.env.MY_LLM_KEY!,\n *   model: 'llama-3.1-70b',\n * });\n * const { text } = await client.run('Explain TypeScript generics');\n *\n * @example\n * // Self-hosted vLLM \u2014 no auth required\n * const client = new CustomApiClient({\n *   url: 'http://gpu-box:8000/v1/chat/completions',\n *   model: 'meta-llama/Llama-3.1-70B-Instruct',\n * });\n */\n\nimport type { AssistantUserTurn as ConversationTurn } from '../../domain/conversation.js';\nimport type {\n  Client,\n  ClientSession,\n  RunOptions,\n  RunResult,\n  StreamCallback,\n  UsageStats,\n} from '../../domain/core-client.js';\nimport type {\n  BridgeCacheControl,\n  BridgeCacheOptions,\n  Part,\n} from '../../domain/core-task.js';\nimport type { BackendInfo, BridgeProtocol } from '../../domain/protocol.js';\nimport { withRetry } from '../../utils/retry.js';\nimport { buildFetchWithTimeout } from '../../utils/timeout.js';\nimport { APPROVAL_POSTURE_CUSTOM_API } from './approval-posture.js';\nimport { toBackendInfo } from './backends/shared.js';\nimport {\n  buildAuthHeader,\n  buildCustomApiPayload,\n  createOpenAiCompatUsage,\n  type CustomApiChatCompletionsResponse,\n  customApiRunResult,\n  parseCustomApiSseLine,\n  warnMissingApiProtocol,\n} from './custom-api-chat-helpers.js';\n\nexport type CustomApiPromptCacheKeyPolicy = boolean | 'auto';\n\nexport interface CustomApiClientOptions {\n  /** Full URL of the chat completions endpoint. */\n  url: string;\n  /** API key or password for the endpoint. Sent as `Authorization: Bearer <apiKey>` by default. */\n  apiKey?: string;\n  /**\n   * Authorization scheme. Default: `'bearer'`.\n   * - `'bearer'` \u2014 `Authorization: Bearer <apiKey>`\n   * - `'basic'` \u2014 `Authorization: Basic <base64(apiKey)>`\n   * - `'custom'` \u2014 no automatic auth header; use `headers` for full control\n   */\n  authScheme?: 'bearer' | 'basic' | 'custom';\n  /** Extra headers merged into every request. Use for custom auth or routing. */\n  headers?: Record<string, string>;\n  /** Model identifier sent in the request body. */\n  model: string;\n  systemPrompt?: string;\n  /** Structured system prompt parts merged into the OpenAI-compatible system message. */\n  systemPromptParts?: Part[];\n  /** Client-level prompt-cache defaults. Per-run options override these values. */\n  cache?: BridgeCacheOptions;\n  /** Client-level cache scope defaults. Per-run options override these values. */\n  cacheControl?: BridgeCacheControl;\n  /**\n   * Controls OpenAI `prompt_cache_key` emission for cache-marked system parts.\n   * Default `'auto'` emits only when `provider: 'openai'`; custom gateways can\n   * opt in with `true` when they accept the OpenAI cache-key extension.\n   */\n  promptCacheKey?: CustomApiPromptCacheKeyPolicy;\n  timeoutMs?: number;\n  retries?: number;\n  /** Custom `fetch` implementation for environments without global fetch. */\n  fetch?: typeof globalThis.fetch;\n  /**\n   * : declared wire protocol. Defaults to `'openai-chat'` because\n   * `CustomApiClient` targets OpenAI-compatible endpoints. Set to another\n   * value (e.g. `'custom'`) when the endpoint diverges from chat-completions\n   * semantics. A one-time warning is emitted when this is omitted.\n   */\n  protocol?: BridgeProtocol;\n  /** RFC-16: free-form provider label (e.g. `'nebius'`, `'groq'`, `'vllm'`). */\n  provider?: string;\n}\n\nexport class CustomApiClient implements Client {\n  private readonly opts: CustomApiClientOptions;\n  private readonly _protocol: BridgeProtocol;\n  private readonly _provider: string;\n  private _history: ConversationTurn[] = [];\n\n  constructor(opts: CustomApiClientOptions) {\n    this.opts = opts;\n    if (opts.protocol) {\n      this._protocol = opts.protocol;\n    } else {\n      this._protocol = 'openai-chat';\n      warnMissingApiProtocol(opts.url);\n    }\n    this._provider = opts.provider ?? 'custom';\n  }\n\n  /**\n   * : pure, synchronous snapshot of this client's declared protocol,\n   * provider, resolved endpoint, and capabilities. No I/O.\n   */\n  info(): BackendInfo {\n    return toBackendInfo({\n      backend: 'custom-api',\n      type: 'api',\n      protocol: this._protocol,\n      provider: this._provider,\n      model: this.opts.model,\n      host: this.opts.url,\n      version: null,\n      capabilities: {\n        streaming: true,\n        sessionPersistence: false,\n        workingDirectory: false,\n        forceMode: false,\n        systemPrompt: true,\n        planning: false,\n        tools: false,\n        mcp: false,\n        structuredHistory: true,\n        approvalCallback: APPROVAL_POSTURE_CUSTOM_API,\n      },\n    });\n  }\n  async run(prompt: string, opts?: RunOptions): Promise<RunResult> {\n    const retries = opts?.retries ?? this.opts.retries ?? 0;\n    return this._withRetry(() => this._run(prompt, opts), retries, {\n      phase: 'run',\n      onError: opts?.onError,\n      onRetry: opts?.onRetry,\n    });\n  }\n\n  private async _run(prompt: string, opts?: RunOptions): Promise<RunResult> {\n    const explicitHistory = opts?.structuredHistory !== undefined;\n    const response = await this.chat(\n      prompt,\n      explicitHistory ? [] : this._history,\n      undefined,\n      opts\n    );\n    if (!explicitHistory) {\n      this._history.push(\n        { role: 'user', content: prompt },\n        { role: 'assistant', content: response.text }\n      );\n    }\n    return customApiRunResult(\n      response.text,\n      response.usage,\n      this._modelForOptions(opts)\n    );\n  }\n  async stream(\n    prompt: string,\n    onEvent: StreamCallback,\n    opts?: RunOptions\n  ): Promise<RunResult> {\n    const retries = opts?.retries ?? this.opts.retries ?? 0;\n    return this._withRetry(() => this._stream(prompt, onEvent, opts), retries, {\n      phase: 'stream',\n      onError: opts?.onError,\n      onRetry: opts?.onRetry,\n    });\n  }\n\n  private async _stream(\n    prompt: string,\n    onEvent: StreamCallback,\n    opts?: RunOptions\n  ): Promise<RunResult> {\n    const explicitHistory = opts?.structuredHistory !== undefined;\n    const response = await this.chat(\n      prompt,\n      explicitHistory ? [] : this._history,\n      onEvent,\n      opts\n    );\n    if (!explicitHistory) {\n      this._history.push(\n        { role: 'user', content: prompt },\n        { role: 'assistant', content: response.text }\n      );\n    }\n    return customApiRunResult(\n      response.text,\n      response.usage,\n      this._modelForOptions(opts)\n    );\n  }\n  session(opts?: RunOptions): CustomApiSession {\n    return new CustomApiSession(this, opts);\n  }\n\n  async isReady(): Promise<boolean> {\n    try {\n      const fetchImpl = this.opts.fetch ?? globalThis.fetch;\n      const headers = this.buildHeaders();\n      const response = await fetchImpl(this.opts.url, {\n        method: 'POST',\n        headers,\n        body: JSON.stringify({\n          model: this.opts.model,\n          messages: [{ role: 'user', content: 'ping' }],\n          max_tokens: 1,\n        }),\n        signal: this.opts.timeoutMs\n          ? AbortSignal.timeout(Math.min(this.opts.timeoutMs, 10_000))\n          : AbortSignal.timeout(10_000),\n      });\n      return response.ok || response.status === 401 || response.status === 403;\n    } catch {\n      return false;\n    }\n  }\n  /** @internal */\n  async _runTurn(\n    prompt: string,\n    history: ConversationTurn[],\n    onEvent?: StreamCallback,\n    opts?: RunOptions\n  ): Promise<{ text: string; usage: UsageStats | null }> {\n    return this.chat(prompt, history, onEvent, opts);\n  }\n\n  /** @internal */\n  _modelForOptions(opts: RunOptions | undefined): string {\n    return opts?.model ?? this.opts.model;\n  }\n\n  private async chat(\n    prompt: string,\n    history: ConversationTurn[],\n    onEvent: StreamCallback | undefined,\n    opts: RunOptions | undefined\n  ): Promise<{ text: string; usage: UsageStats | null }> {\n    const timeoutMs = opts?.timeoutMs ?? this.opts.timeoutMs;\n    const fetchImpl = buildFetchWithTimeout(\n      this.opts.fetch ?? globalThis.fetch,\n      timeoutMs,\n      opts?.signal\n    );\n    const headers = this.buildHeaders();\n    const mergedOptions = this.mergeRunOptions(opts);\n    const payload = buildCustomApiPayload(\n      prompt,\n      history,\n      opts?.systemPrompt ?? this.opts.systemPrompt,\n      mergedOptions\n    );\n    const model = opts?.model ?? this.opts.model;\n    const stream = Boolean(onEvent);\n    const body: Record<string, unknown> = {\n      model,\n      messages: payload.messages,\n      stream,\n      ...(stream ? { stream_options: { include_usage: true } } : {}),\n    };\n    const promptCacheKey = this.shouldEmitPromptCacheKey(\n      mergedOptions,\n      payload.promptCacheKey\n    )\n      ? payload.promptCacheKey\n      : undefined;\n    if (promptCacheKey) {\n      body.prompt_cache_key = promptCacheKey;\n    }\n\n    const response = await fetchImpl(this.opts.url, {\n      method: 'POST',\n      headers,\n      body: JSON.stringify(body),\n    });\n\n    if (!response.ok) {\n      const body = await response.text().catch(() => '');\n      throw new Error(`API returned ${response.status}: ${body.slice(0, 500)}`);\n    }\n\n    if (stream && onEvent) {\n      return this.consumeStream(response, onEvent, promptCacheKey);\n    }\n\n    const json = (await response.json()) as CustomApiChatCompletionsResponse;\n    const text = json.choices?.[0]?.message?.content ?? '';\n    const usage = json.usage\n      ? createOpenAiCompatUsage(json.usage, promptCacheKey)\n      : null;\n    return { text, usage };\n  }\n\n  private mergeRunOptions(opts: RunOptions | undefined): RunOptions {\n    return {\n      ...(opts ?? {}),\n      cache: opts?.cache ?? this.opts.cache,\n      cacheControl: opts?.cacheControl ?? this.opts.cacheControl,\n      systemPromptParts: opts?.systemPromptParts ?? this.opts.systemPromptParts,\n    };\n  }\n\n  private shouldEmitPromptCacheKey(\n    opts: RunOptions,\n    promptCacheKey: string | undefined\n  ): boolean {\n    if (!promptCacheKey) return false;\n    if (\n      this._protocol !== 'openai-chat' &&\n      this._protocol !== 'openai-responses'\n    ) {\n      return false;\n    }\n    if (opts.cache?.enabled === false) return false;\n    if (opts.cacheControl?.system === 'static') return false;\n\n    const policy = this.opts.promptCacheKey ?? 'auto';\n    if (policy === true) return true;\n    if (policy === false) return false;\n    return this._provider === 'openai';\n  }\n\n  private async consumeStream(\n    response: Response,\n    onEvent: StreamCallback,\n    promptCacheKey: string | undefined\n  ): Promise<{ text: string; usage: UsageStats | null }> {\n    const reader = response.body?.getReader();\n    if (!reader) throw new Error('Response body is not readable');\n\n    const decoder = new TextDecoder();\n    let fullText = '';\n    let lastUsage: UsageStats | null = null;\n    let buffer = '';\n\n    try {\n      while (true) {\n        const { done, value } = await reader.read();\n        if (done) break;\n\n        buffer += decoder.decode(value, { stream: true });\n        const lines = buffer.split('\\n');\n        buffer = lines.pop() ?? '';\n\n        for (const line of lines) {\n          const trimmed = line.trim();\n          if (!trimmed) continue;\n\n          const parsed = parseCustomApiSseLine(trimmed);\n          if (!parsed) continue;\n\n          const delta = parsed.choices?.[0]?.delta?.content ?? '';\n          if (delta) {\n            fullText += delta;\n            await onEvent({ type: 'text', text: delta });\n          }\n\n          if (parsed.usage) {\n            lastUsage = createOpenAiCompatUsage(parsed.usage, promptCacheKey);\n          }\n        }\n      }\n    } finally {\n      reader.releaseLock();\n    }\n\n    await onEvent({ type: 'result', text: fullText, usage: lastUsage });\n    return { text: fullText, usage: lastUsage };\n  }\n\n  private buildHeaders(): Record<string, string> {\n    return {\n      'Content-Type': 'application/json',\n      ...buildAuthHeader(this.opts.apiKey, this.opts.authScheme ?? 'bearer'),\n      ...(this.opts.headers ?? {}),\n    };\n  }\n\n  _withRetry<T>(\n    fn: () => Promise<T>,\n    retries: number,\n    options: {\n      onError?: RunOptions['onError'];\n      onRetry?: RunOptions['onRetry'];\n      phase: 'run' | 'stream' | 'session';\n    }\n  ): Promise<T> {\n    return withRetry(fn, {\n      retries,\n      backend: 'custom-api',\n      phase: options.phase,\n      onError: options.onError,\n      onRetry: options.onRetry,\n    });\n  }\n}\nexport interface CustomApiSessionOptions extends RunOptions {\n  /** Maximum number of conversation turns (pairs) to keep in memory. Oldest pairs are dropped first. */\n  maxHistory?: number;\n}\n\nexport class CustomApiSession implements ClientSession {\n  _history: ConversationTurn[] = [];\n  private _turnCount = 0;\n  private readonly maxHistory: number | undefined;\n\n  constructor(\n    private readonly client: CustomApiClient,\n    private readonly defaultOpts?: CustomApiSessionOptions\n  ) {\n    this.maxHistory = defaultOpts?.maxHistory;\n  }\n\n  async send(\n    prompt: string,\n    opts?: RunOptions & { onEvent?: StreamCallback }\n  ): Promise<RunResult> {\n    const merged = { ...this.defaultOpts, ...opts };\n    const retries = merged.retries ?? 0;\n    const { text, usage } = await this.client._withRetry(\n      () => this.client._runTurn(prompt, this._history, opts?.onEvent, merged),\n      retries,\n      {\n        phase: 'session',\n        onError: merged.onError,\n        onRetry: merged.onRetry,\n      }\n    );\n\n    this._history.push(\n      { role: 'user', content: prompt },\n      { role: 'assistant', content: text }\n    );\n    this._turnCount++;\n\n    if (this.maxHistory != null && this._history.length > this.maxHistory * 2) {\n      this._history = this._history.slice(-this.maxHistory * 2);\n    }\n\n    return customApiRunResult(text, usage, this.client._modelForOptions(merged));\n  }\n\n  async stream(\n    prompt: string,\n    onEvent: StreamCallback,\n    opts?: RunOptions\n  ): Promise<RunResult> {\n    return this.send(prompt, { ...opts, onEvent });\n  }\n\n  get turns(): number {\n    return this._turnCount;\n  }\n\n  reset(): void {\n    this._history = [];\n    this._turnCount = 0;\n  }\n}\n"],
+  "mappings": "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",
+  "names": ["body"]
+}

package/dist/adapters/agents/custom-cli-client.d.ts

@@ -0,0 +1,84 @@
+/**
+ * CustomCliClient — wrap any CLI that outputs in a known stream format.
+ *
+ * Supported output parsers: 'claude', 'openai', 'anthropic', 'codex', 'cursor', 'gemini', 'ollama'.
+ *
+ * @example
+ * const ai = new CustomCliClient({
+ *   command: 'my-ai-tool',
+ *   args: ['--json'],
+ *   parser: 'openai',
+ *   promptMode: 'stdin',
+ * });
+ * const { text } = await ai.run('Explain TypeScript generics');
+ */
+import type { BridgeProtocol } from '../../domain/protocol.js';
+import { AgentClient } from './agent-client.js';
+export type CustomCliParser = 'claude' | 'openai' | 'anthropic' | 'codex' | 'cursor' | 'gemini' | 'ollama';
+export interface CustomCliOptions {
+    /**
+     * @example 'my-ai-tool', '/usr/local/bin/ai-cli'
+     */
+    command: string;
+    /**
+     * Static CLI arguments always passed to the command.
+     * @example ['--json', '--no-color']
+     */
+    args?: string[];
+    /**
+     * How the prompt is delivered to the CLI.
+     * - `'stdin'` (default) — prompt written to stdin; `args` are the CLI flags
+     * - `'arg'` — prompt appended as the last positional argument
+     */
+    promptMode?: 'stdin' | 'arg';
+    /**
+     * Which output parser to use for decoding the CLI's stdout.
+     * Must match the format the CLI actually emits.
+     * Default: `'claude'` (Claude Code stream-json format).
+     */
+    parser?: CustomCliParser;
+    /** Extra environment variables injected into the CLI process. */
+    env?: Record<string, string>;
+    /** Model name (informational; passed through to the execution plan). */
+    model?: string;
+    systemPrompt?: string;
+    cwd?: string;
+    timeoutMs?: number;
+    retries?: number;
+    skipInstallCheck?: boolean;
+    /**
+     * : declared wire protocol for this CLI's native-messages dispatch,
+     * cache-marker strategy, and telemetry. When omitted, the protocol is
+     * inferred from `parser` and a one-time warning is emitted. Prefer setting
+     * this explicitly when the CLI wraps a known vendor API.
+     */
+    protocol?: BridgeProtocol;
+    /** RFC-16: free-form provider label (e.g. `'acme'`, `'my-team'`). */
+    provider?: string;
+}
+/**
+ * Wrap any CLI tool that emits output in a supported stream format.
+ *
+ * Supported parsers: `'claude'`, `'openai'`, `'anthropic'`, `'codex'`, `'cursor'`, `'gemini'`, `'ollama'`.
+ *
+ * @example
+ * // A CLI that outputs Claude Code stream-json on stdout
+ * const ai = new CustomCliClient({
+ *   command: 'my-claude-wrapper',
+ *   args: ['--verbose'],
+ *   parser: 'claude',
+ * });
+ *
+ * @example
+ * // A CLI that reads the prompt as a positional arg
+ * const ai = new CustomCliClient({
+ *   command: 'gpt-cli',
+ *   promptMode: 'arg',
+ *   parser: 'openai',
+ *   env: { OPENAI_API_KEY: process.env.OPENAI_API_KEY! },
+ * });
+ */
+export declare class CustomCliClient extends AgentClient {
+    constructor(opts: CustomCliOptions);
+}
+//# sourceMappingURL=custom-cli-client.d.ts.map

package/dist/adapters/agents/custom-cli-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-cli-client.d.ts","sourceRoot":"","sources":["../../../src/adapters/agents/custom-cli-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAYH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAK/D,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAMhD,MAAM,MAAM,eAAe,GACvB,QAAQ,GACR,QAAQ,GACR,WAAW,GACX,OAAO,GACP,QAAQ,GACR,QAAQ,GACR,QAAQ,CAAC;AAEb,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhB;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,GAAG,KAAK,CAAC;IAE7B;;;;OAIG;IACH,MAAM,CAAC,EAAE,eAAe,CAAC;IAEzB,iEAAiE;IACjE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE7B,wEAAwE;IACxE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAC;IAE1B,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAiJD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,eAAgB,SAAQ,WAAW;gBAClC,IAAI,EAAE,gBAAgB;CAanC"}

package/dist/adapters/agents/custom-cli-client.js

@@ -0,0 +1,151 @@
+import { execFile } from "node:child_process";
+import crypto from "node:crypto";
+import { promisify } from "node:util";
+import {
+  buildPromptEnvelope,
+  buildPromptUserMessage
+} from "../../prompts/envelope.js";
+import { AgentClient } from "./agent-client.js";
+import { APPROVAL_POSTURE_CUSTOM_CLI } from "./approval-posture.js";
+import { DEFAULT_MAX_CONTEXT_TOKENS } from "./backends/model-matrix.js";
+import { toBackendInfo } from "./backends/shared.js";
+const execFileAsync = promisify(execFile);
+const PARSER_TO_PROTOCOL = {
+  claude: "anthropic",
+  anthropic: "anthropic",
+  openai: "openai-chat",
+  codex: "openai-chat",
+  cursor: "custom",
+  gemini: "gemini",
+  ollama: "ollama"
+};
+const _customProtocolWarnedFor = /* @__PURE__ */ new Set();
+function warnMissingProtocol(command, parser, inferred) {
+  if (_customProtocolWarnedFor.has(command)) return;
+  _customProtocolWarnedFor.add(command);
+  process.stderr.write(
+    `[octoflow] CustomCliClient(${command}): 'protocol' not set; inferred '${inferred}' from parser '${parser}'. Set 'protocol' explicitly to silence this warning.
+`
+  );
+}
+function createCustomBackend(opts) {
+  const parser = opts.parser ?? "claude";
+  const promptMode = opts.promptMode ?? "stdin";
+  const capabilities = {
+    streaming: true,
+    sessionPersistence: false,
+    workingDirectory: true,
+    forceMode: false,
+    systemPrompt: false,
+    planning: false,
+    tools: false,
+    mcp: false,
+    approvalCallback: APPROVAL_POSTURE_CUSTOM_CLI
+  };
+  let protocol;
+  if (opts.protocol) {
+    protocol = opts.protocol;
+  } else {
+    protocol = PARSER_TO_PROTOCOL[parser];
+    warnMissingProtocol(opts.command, parser, protocol);
+  }
+  const provider = opts.provider ?? "custom";
+  let cachedVersion = null;
+  return {
+    name: "custom",
+    displayName: `Custom CLI (${opts.command})`,
+    protocol,
+    provider,
+    info() {
+      return toBackendInfo({
+        backend: "custom",
+        type: "cli",
+        protocol,
+        provider,
+        model: opts.model ?? null,
+        host: opts.command,
+        version: cachedVersion,
+        capabilities
+      });
+    },
+    models: opts.model ? [opts.model] : [],
+    defaultModel: opts.model ?? "",
+    contextWindow: DEFAULT_MAX_CONTEXT_TOKENS,
+    maxOutputTokens: 4096,
+    canResume: false,
+    streamParserName: parser,
+    capabilities,
+    async isInstalled() {
+      try {
+        await execFileAsync(opts.command, ["--version"], { timeout: 5e3 });
+        return true;
+      } catch {
+        try {
+          await execFileAsync(opts.command, [], { timeout: 5e3 });
+          return true;
+        } catch (err) {
+          return err.code !== "ENOENT";
+        }
+      }
+    },
+    async getVersion() {
+      try {
+        const { stdout } = await execFileAsync(opts.command, ["--version"], {
+          timeout: 5e3
+        });
+        const v = stdout.trim() || null;
+        cachedVersion = v;
+        return v;
+      } catch {
+        return null;
+      }
+    },
+    validateModel(_model) {
+      return true;
+    },
+    generateSessionId() {
+      return crypto.randomUUID();
+    },
+    buildExecutionPlan(request) {
+      const prompt = buildPromptEnvelope({
+        systemPrompt: request.systemPrompt,
+        userMessage: buildPromptUserMessage({
+          userMessage: request.prompt,
+          structuredHistory: request.structuredHistory
+        })
+      });
+      const staticArgs = opts.args ?? [];
+      const cliArgs = promptMode === "arg" ? [...staticArgs, prompt] : [...staticArgs];
+      return {
+        command: opts.command,
+        args: cliArgs,
+        env: opts.env ?? {},
+        stdin: promptMode === "stdin" ? prompt : "",
+        cwd: request.cwd ?? opts.cwd ?? void 0,
+        parser,
+        timeoutMs: opts.timeoutMs
+      };
+    },
+    extractSessionId(_output) {
+      return null;
+    }
+  };
+}
+class CustomCliClient extends AgentClient {
+  constructor(opts) {
+    super({
+      backend: "custom",
+      model: opts.model,
+      systemPrompt: opts.systemPrompt,
+      cwd: opts.cwd,
+      timeoutMs: opts.timeoutMs,
+      retries: opts.retries,
+      skipInstallCheck: opts.skipInstallCheck
+    });
+    this._backend = createCustomBackend(opts);
+  }
+}
+export {
+  CustomCliClient
+};
+//# sourceMappingURL=custom-cli-client.js.map

package/dist/adapters/agents/custom-cli-client.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/adapters/agents/custom-cli-client.ts"],
+  "sourcesContent": ["/**\n * CustomCliClient \u2014 wrap any CLI that outputs in a known stream format.\n *\n * Supported output parsers: 'claude', 'openai', 'anthropic', 'codex', 'cursor', 'gemini', 'ollama'.\n *\n * @example\n * const ai = new CustomCliClient({\n *   command: 'my-ai-tool',\n *   args: ['--json'],\n *   parser: 'openai',\n *   promptMode: 'stdin',\n * });\n * const { text } = await ai.run('Explain TypeScript generics');\n */\n\nimport { execFile } from 'node:child_process';\nimport crypto from 'node:crypto';\nimport { promisify } from 'node:util';\n\nimport type {\n  Backend,\n  BackendCapabilities,\n  BackendExecutionPlan,\n  BackendRunRequest,\n} from '../../domain/contracts/backends.js';\nimport type { BridgeProtocol } from '../../domain/protocol.js';\nimport {\n  buildPromptEnvelope,\n  buildPromptUserMessage,\n} from '../../prompts/envelope.js';\nimport { AgentClient } from './agent-client.js';\nimport { APPROVAL_POSTURE_CUSTOM_CLI } from './approval-posture.js';\nimport { DEFAULT_MAX_CONTEXT_TOKENS } from './backends/model-matrix.js';\nimport { toBackendInfo } from './backends/shared.js';\n\nconst execFileAsync = promisify(execFile);\nexport type CustomCliParser =\n  | 'claude'\n  | 'openai'\n  | 'anthropic'\n  | 'codex'\n  | 'cursor'\n  | 'gemini'\n  | 'ollama';\n\nexport interface CustomCliOptions {\n  /**\n   * @example 'my-ai-tool', '/usr/local/bin/ai-cli'\n   */\n  command: string;\n\n  /**\n   * Static CLI arguments always passed to the command.\n   * @example ['--json', '--no-color']\n   */\n  args?: string[];\n\n  /**\n   * How the prompt is delivered to the CLI.\n   * - `'stdin'` (default) \u2014 prompt written to stdin; `args` are the CLI flags\n   * - `'arg'` \u2014 prompt appended as the last positional argument\n   */\n  promptMode?: 'stdin' | 'arg';\n\n  /**\n   * Which output parser to use for decoding the CLI's stdout.\n   * Must match the format the CLI actually emits.\n   * Default: `'claude'` (Claude Code stream-json format).\n   */\n  parser?: CustomCliParser;\n\n  /** Extra environment variables injected into the CLI process. */\n  env?: Record<string, string>;\n\n  /** Model name (informational; passed through to the execution plan). */\n  model?: string;\n  systemPrompt?: string;\n  cwd?: string;\n  timeoutMs?: number;\n  retries?: number;\n  skipInstallCheck?: boolean;\n\n  /**\n   * : declared wire protocol for this CLI's native-messages dispatch,\n   * cache-marker strategy, and telemetry. When omitted, the protocol is\n   * inferred from `parser` and a one-time warning is emitted. Prefer setting\n   * this explicitly when the CLI wraps a known vendor API.\n   */\n  protocol?: BridgeProtocol;\n\n  /** RFC-16: free-form provider label (e.g. `'acme'`, `'my-team'`). */\n  provider?: string;\n}\n\n/** Inferred default protocol when `opts.protocol` is omitted. */\nconst PARSER_TO_PROTOCOL: Record<CustomCliParser, BridgeProtocol> = {\n  claude: 'anthropic',\n  anthropic: 'anthropic',\n  openai: 'openai-chat',\n  codex: 'openai-chat',\n  cursor: 'custom',\n  gemini: 'gemini',\n  ollama: 'ollama',\n};\n\nconst _customProtocolWarnedFor = new Set<string>();\n\nfunction warnMissingProtocol(\n  command: string,\n  parser: CustomCliParser,\n  inferred: BridgeProtocol\n): void {\n  if (_customProtocolWarnedFor.has(command)) return;\n  _customProtocolWarnedFor.add(command);\n  process.stderr.write(\n    `[octoflow] CustomCliClient(${command}): 'protocol' not set; inferred '${inferred}' from parser '${parser}'. ` +\n      `Set 'protocol' explicitly to silence this warning.\\n`\n  );\n}\n\nfunction createCustomBackend(opts: CustomCliOptions): Backend {\n  const parser = opts.parser ?? 'claude';\n  const promptMode = opts.promptMode ?? 'stdin';\n\n  const capabilities: BackendCapabilities = {\n    streaming: true,\n    sessionPersistence: false,\n    workingDirectory: true,\n    forceMode: false,\n    systemPrompt: false,\n    planning: false,\n    tools: false,\n    mcp: false,\n    approvalCallback: APPROVAL_POSTURE_CUSTOM_CLI,\n  };\n\n  let protocol: BridgeProtocol;\n  if (opts.protocol) {\n    protocol = opts.protocol;\n  } else {\n    protocol = PARSER_TO_PROTOCOL[parser];\n    warnMissingProtocol(opts.command, parser, protocol);\n  }\n  const provider = opts.provider ?? 'custom';\n\n  let cachedVersion: string | null = null;\n\n  return {\n    name: 'custom',\n    displayName: `Custom CLI (${opts.command})`,\n    protocol,\n    provider,\n    info() {\n      return toBackendInfo({\n        backend: 'custom',\n        type: 'cli',\n        protocol,\n        provider,\n        model: opts.model ?? null,\n        host: opts.command,\n        version: cachedVersion,\n        capabilities,\n      });\n    },\n    models: opts.model ? [opts.model] : [],\n    defaultModel: opts.model ?? '',\n    contextWindow: DEFAULT_MAX_CONTEXT_TOKENS,\n    maxOutputTokens: 4_096,\n    canResume: false,\n    streamParserName: parser,\n    capabilities,\n\n    async isInstalled(): Promise<boolean> {\n      try {\n        await execFileAsync(opts.command, ['--version'], { timeout: 5_000 });\n        return true;\n      } catch {\n        // '--version' may not be supported; try running with no args\n        try {\n          await execFileAsync(opts.command, [], { timeout: 5_000 });\n          return true;\n        } catch (err: unknown) {\n          // ENOENT means binary not found; anything else means it IS on PATH\n          return (err as NodeJS.ErrnoException).code !== 'ENOENT';\n        }\n      }\n    },\n\n    async getVersion(): Promise<string | null> {\n      try {\n        const { stdout } = await execFileAsync(opts.command, ['--version'], {\n          timeout: 5_000,\n        });\n        const v = stdout.trim() || null;\n        cachedVersion = v;\n        return v;\n      } catch {\n        return null;\n      }\n    },\n\n    validateModel(_model: string): boolean {\n      return true; // custom CLIs accept whatever the user says\n    },\n\n    generateSessionId(): string {\n      return crypto.randomUUID();\n    },\n\n    buildExecutionPlan(request: BackendRunRequest): BackendExecutionPlan {\n      const prompt = buildPromptEnvelope({\n        systemPrompt: request.systemPrompt,\n        userMessage: buildPromptUserMessage({\n          userMessage: request.prompt,\n          structuredHistory: request.structuredHistory,\n        }),\n      });\n      const staticArgs = opts.args ?? [];\n      const cliArgs =\n        promptMode === 'arg' ? [...staticArgs, prompt] : [...staticArgs];\n\n      return {\n        command: opts.command,\n        args: cliArgs,\n        env: opts.env ?? {},\n        stdin: promptMode === 'stdin' ? prompt : '',\n        cwd: request.cwd ?? opts.cwd ?? undefined,\n        parser,\n        timeoutMs: opts.timeoutMs,\n      };\n    },\n\n    extractSessionId(_output: string): string | null {\n      return null;\n    },\n  };\n}\n/**\n * Wrap any CLI tool that emits output in a supported stream format.\n *\n * Supported parsers: `'claude'`, `'openai'`, `'anthropic'`, `'codex'`, `'cursor'`, `'gemini'`, `'ollama'`.\n *\n * @example\n * // A CLI that outputs Claude Code stream-json on stdout\n * const ai = new CustomCliClient({\n *   command: 'my-claude-wrapper',\n *   args: ['--verbose'],\n *   parser: 'claude',\n * });\n *\n * @example\n * // A CLI that reads the prompt as a positional arg\n * const ai = new CustomCliClient({\n *   command: 'gpt-cli',\n *   promptMode: 'arg',\n *   parser: 'openai',\n *   env: { OPENAI_API_KEY: process.env.OPENAI_API_KEY! },\n * });\n */\nexport class CustomCliClient extends AgentClient {\n  constructor(opts: CustomCliOptions) {\n    super({\n      backend: 'custom',\n      model: opts.model,\n      systemPrompt: opts.systemPrompt,\n      cwd: opts.cwd,\n      timeoutMs: opts.timeoutMs,\n      retries: opts.retries,\n      skipInstallCheck: opts.skipInstallCheck,\n    });\n    // Pre-seed the backend so resolveBackend() skips the registry lookup\n    this._backend = createCustomBackend(opts);\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}