minimal-agent 0.13.0 → 0.15.0

package/src/llm/gatewayClient.js

@@ -0,0 +1,201 @@
+import { randomUUID } from 'node:crypto';
+import { onlineToolCategory } from '../team/toolPolicy.js';
+import { prepareMessagesForProvider } from './messageProvenance.js';
+const IDLE_TIMEOUT_MS = Number(process.env.MINIMAL_AGENT_GATEWAY_IDLE_TIMEOUT_MS) > 0
+    ? Number(process.env.MINIMAL_AGENT_GATEWAY_IDLE_TIMEOUT_MS)
+    : 120_000;
+const DEADLINE_MS = Number(process.env.MINIMAL_AGENT_GATEWAY_DEADLINE_MS) > 0
+    ? Number(process.env.MINIMAL_AGENT_GATEWAY_DEADLINE_MS)
+    : 15 * 60_000;
+function gatewayTools(tools, allowedCategories) {
+    const allowed = allowedCategories ? new Set(allowedCategories) : null;
+    return tools.flatMap((tool) => {
+        const category = onlineToolCategory(tool.name);
+        if (!category || (allowed && !allowed.has(category)))
+            return [];
+        return [
+            {
+                type: 'function',
+                category,
+                function: {
+                    name: tool.name,
+                    ...(typeof tool.description === 'string'
+                        ? { description: tool.description }
+                        : {}),
+                    parameters: tool.parameters,
+                },
+            },
+        ];
+    });
+}
+function safeMessages(messages) {
+    return messages.map((message) => {
+        const { id: _id, timestamp: _timestamp, attachments: _attachments, browserReferences: _browserReferences, provenance: _provenance, display_metadata: _displayMetadata, tool_result_policy: _toolResultPolicy, _ephemeral, ...safe } = message;
+        return safe;
+    });
+}
+export class GatewayClientError extends Error {
+    code;
+    retryable;
+    constructor(code, retryable, message) {
+        // ⚠️ code 必须烘进 message 文本，不能只存在 .code 属性上：这个错误穿过
+        // loop.ts（只取 `.message`）→ 引擎 runner（转成纯字符串 blocker）→
+        // workflowController 的 isUsageLimitError 文本兜底，每一层都只剩字符串。
+        // 不烘进去，`isUsageLimitError` 的「同时认 code 与文本」这句注释就是一句空话——
+        // 之前正是这样：message 是纯人话（如「设备授权不存在或已过期」），从不包含
+        // DEVICE_REVOKED 之类的码，文本兜底恒为 false，usage_limited 在真实调用链上
+        // 从未被触发过。
+        super(`[${code}] ${message}`);
+        this.code = code;
+        this.retryable = retryable;
+        this.name = 'GatewayClientError';
+    }
+}
+/**
+ * 服务端「配额/授权不给了」的错误码 —— **唯一真值**。
+ *
+ * 与 Goal 的 `usage_limited` 状态一一对应，也正是它与 `budget_limited` 的分界：
+ *  · `budget_limited` = **用户自己设的** token 额度用完 → 加预算即可继续。
+ *  · `usage_limited`  = **服务端配额/授权**不给了 → 加预算没用，要去解决授权或等周期重置。
+ * 两者都可 resume，但恢复动作完全不同，所以不能合并成一个状态。
+ *
+ * 服务端侧的产出点：`minimal-server/src/core/gatewayInference.ts`。
+ */
+const USAGE_LIMIT_CODES = new Set([
+    'REQUEST_QUOTA_EXHAUSTED',
+    'TOKEN_QUOTA_EXHAUSTED',
+    'CONCURRENCY_EXCEEDED',
+    'GRANT_REVOKED',
+    'DEVICE_REVOKED',
+]);
+/**
+ * 判断一个错误是不是「服务端配额/授权不给了」。
+ *
+ * ⚠️ 同时认 `GatewayClientError.code` 与错误文本：错误穿过 loop → 引擎 → 工作流
+ * 这几层之后往往只剩一个字符串（`llm_error` 事件带的是 message），
+ * 只认 code 会在真实链路上恒为 false。
+ */
+export function isUsageLimitError(error) {
+    if (error instanceof GatewayClientError)
+        return USAGE_LIMIT_CODES.has(error.code);
+    const text = error instanceof Error ? error.message : String(error ?? '');
+    return [...USAGE_LIMIT_CODES].some((code) => text.includes(code));
+}
+function combinedSignal(signal) {
+    const timeout = AbortSignal.timeout(DEADLINE_MS);
+    return signal ? AbortSignal.any([signal, timeout]) : timeout;
+}
+async function readWithIdleTimeout(promise, signal) {
+    let timer;
+    let onAbort;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new GatewayClientError('PROVIDER_TIMEOUT', true, '在线模型流式响应超时')), IDLE_TIMEOUT_MS);
+                onAbort = () => reject(new DOMException('aborted', 'AbortError'));
+                signal.addEventListener('abort', onAbort, { once: true });
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        if (onAbort)
+            signal.removeEventListener('abort', onAbort);
+    }
+}
+/** Gateway transport only. The caller retains the existing Agent/tool loop. */
+export async function* chatGateway(args) {
+    const { provider, messages, tools, signal: parentSignal, conversationMode, responseFormat, } = args;
+    if (!provider.gatewayUrl || !provider.gatewayToken || !provider.remoteModelId)
+        throw new GatewayClientError('DEVICE_REVOKED', false, '在线模型设备授权不存在或已过期');
+    const url = `${provider.gatewayUrl.replace(/\/$/, '')}/api/inference/chat/stream`;
+    const payload = JSON.stringify({
+        requestId: randomUUID(),
+        modelId: provider.remoteModelId,
+        // Keep the gateway payload limited to provider-facing protocol content.
+        // Session IDs, provenance metadata, display metadata, and local-only
+        // fields must never cross the remote inference boundary.
+        messages: safeMessages(prepareMessagesForProvider(messages, conversationMode ?? 'private')),
+        tools: gatewayTools(tools, provider.gatewayToolCategories ??
+            provider.gatewayDefaultToolCategories ??
+            provider.gatewayMaxToolCategories),
+        toolCategories: provider.gatewayToolCategories ?? provider.gatewayMaxToolCategories ?? [],
+        ...(responseFormat ? { responseFormat } : {}),
+    });
+    let activeReader;
+    const signal = combinedSignal(parentSignal);
+    try {
+        const response = await fetch(url, {
+            method: 'POST',
+            signal,
+            headers: {
+                'content-type': 'application/json',
+                authorization: `Bearer ${provider.gatewayToken}`,
+            },
+            body: payload,
+        });
+        if (!response.ok) {
+            const body = (await response.json().catch(() => ({})));
+            // ⚠️ 服务端**明确表态**优先，状态码只是它没表态时的推断。
+            // 曾经写成 `body.retryable === true || status === 429 || …`：服务端发
+            // `{code:'TOKEN_QUOTA_EXHAUSTED', retryable:false}` 配 HTTP 429 时，
+            // `retryable:false` 被 `|| 429` 直接覆盖 —— 于是「额度用完了，别重试」
+            // 被当成限流反复重试，既拖慢失败反馈，也把真正的原因埋掉。
+            // 配额耗尽与限流是两回事：前者要去加额度，后者等一会儿就好。
+            const retryable = typeof body.retryable === 'boolean'
+                ? body.retryable
+                : response.status === 408 ||
+                    response.status === 425 ||
+                    response.status === 429 ||
+                    response.status >= 500;
+            throw new GatewayClientError(body.code ?? `HTTP_${response.status}`, retryable, body.error ?? `在线模型请求失败（${response.status}）`);
+        }
+        if (!response.body)
+            throw new GatewayClientError('PROVIDER_UNAVAILABLE', true, '在线模型未返回流式响应');
+        const reader = response.body.getReader();
+        activeReader = reader;
+        const decoder = new TextDecoder();
+        let buffer = '';
+        while (true) {
+            const next = await readWithIdleTimeout(reader.read(), signal);
+            if (next.done)
+                break;
+            buffer += decoder.decode(next.value, { stream: true });
+            const frames = buffer.split(/\n\n/);
+            buffer = frames.pop() ?? '';
+            for (const frame of frames) {
+                const line = frame
+                    .split(/\r?\n/)
+                    .find((item) => item.startsWith('data:'));
+                if (!line)
+                    continue;
+                let event;
+                try {
+                    event = JSON.parse(line.slice(5).trim());
+                }
+                catch {
+                    continue;
+                }
+                if (event.type === 'error')
+                    throw new GatewayClientError(event.code ?? 'PROVIDER_UNAVAILABLE', event.retryable === true, event.message ?? '在线模型流式调用失败');
+                if (event.type === 'usage') {
+                    yield event;
+                    continue;
+                }
+                if (event.type === 'done')
+                    return;
+                yield event;
+            }
+        }
+        return;
+    }
+    finally {
+        // Release the response body on both normal `done` and error/abort paths.
+        // Without this, a completed stream can keep an HTTP connection/socket
+        // alive until the runtime's garbage collector notices it.
+        await activeReader?.cancel().catch(() => { });
+        activeReader = undefined;
+    }
+}

package/src/llm/gatewayClient.ts

@@ -0,0 +1,299 @@
+import { randomUUID } from 'node:crypto';
+import type { ConversationMode } from '../runtime/agentRuntimeContext.js';
+import { onlineToolCategory } from '../team/toolPolicy.js';
+import type {
+  GatewayProvider,
+  LlmStreamEvent,
+  Message,
+  Tool,
+} from '../types.js';
+import { prepareMessagesForProvider } from './messageProvenance.js';
+
+const IDLE_TIMEOUT_MS =
+  Number(process.env.MINIMAL_AGENT_GATEWAY_IDLE_TIMEOUT_MS) > 0
+    ? Number(process.env.MINIMAL_AGENT_GATEWAY_IDLE_TIMEOUT_MS)
+    : 120_000;
+const DEADLINE_MS =
+  Number(process.env.MINIMAL_AGENT_GATEWAY_DEADLINE_MS) > 0
+    ? Number(process.env.MINIMAL_AGENT_GATEWAY_DEADLINE_MS)
+    : 15 * 60_000;
+
+function gatewayTools(
+  tools: Tool[],
+  allowedCategories?: readonly string[],
+): Array<{
+  type: 'function';
+  category: NonNullable<ReturnType<typeof onlineToolCategory>>;
+  function: {
+    name: string;
+    description?: string;
+    parameters: Record<string, unknown>;
+  };
+}> {
+  const allowed = allowedCategories ? new Set(allowedCategories) : null;
+  return tools.flatMap((tool) => {
+    const category = onlineToolCategory(tool.name);
+    if (!category || (allowed && !allowed.has(category))) return [];
+    return [
+      {
+        type: 'function' as const,
+        category,
+        function: {
+          name: tool.name,
+          ...(typeof tool.description === 'string'
+            ? { description: tool.description }
+            : {}),
+          parameters: tool.parameters as Record<string, unknown>,
+        },
+      },
+    ];
+  });
+}
+
+function safeMessages(messages: Message[]): unknown[] {
+  return messages.map((message) => {
+    const {
+      id: _id,
+      timestamp: _timestamp,
+      attachments: _attachments,
+      browserReferences: _browserReferences,
+      provenance: _provenance,
+      display_metadata: _displayMetadata,
+      tool_result_policy: _toolResultPolicy,
+      _ephemeral,
+      ...safe
+    } = message as Message & Record<string, unknown>;
+    return safe;
+  });
+}
+
+type GatewayEvent = {
+  type?: string;
+  code?: string;
+  retryable?: boolean;
+  message?: string;
+};
+
+export class GatewayClientError extends Error {
+  constructor(
+    public readonly code: string,
+    public readonly retryable: boolean,
+    message: string,
+  ) {
+    // ⚠️ code 必须烘进 message 文本，不能只存在 .code 属性上：这个错误穿过
+    // loop.ts（只取 `.message`）→ 引擎 runner（转成纯字符串 blocker）→
+    // workflowController 的 isUsageLimitError 文本兜底，每一层都只剩字符串。
+    // 不烘进去，`isUsageLimitError` 的「同时认 code 与文本」这句注释就是一句空话——
+    // 之前正是这样：message 是纯人话（如「设备授权不存在或已过期」），从不包含
+    // DEVICE_REVOKED 之类的码，文本兜底恒为 false，usage_limited 在真实调用链上
+    // 从未被触发过。
+    super(`[${code}] ${message}`);
+    this.name = 'GatewayClientError';
+  }
+}
+
+/**
+ * 服务端「配额/授权不给了」的错误码 —— **唯一真值**。
+ *
+ * 与 Goal 的 `usage_limited` 状态一一对应，也正是它与 `budget_limited` 的分界：
+ *  · `budget_limited` = **用户自己设的** token 额度用完 → 加预算即可继续。
+ *  · `usage_limited`  = **服务端配额/授权**不给了 → 加预算没用，要去解决授权或等周期重置。
+ * 两者都可 resume，但恢复动作完全不同，所以不能合并成一个状态。
+ *
+ * 服务端侧的产出点：`minimal-server/src/core/gatewayInference.ts`。
+ */
+const USAGE_LIMIT_CODES = new Set([
+  'REQUEST_QUOTA_EXHAUSTED',
+  'TOKEN_QUOTA_EXHAUSTED',
+  'CONCURRENCY_EXCEEDED',
+  'GRANT_REVOKED',
+  'DEVICE_REVOKED',
+]);
+
+/**
+ * 判断一个错误是不是「服务端配额/授权不给了」。
+ *
+ * ⚠️ 同时认 `GatewayClientError.code` 与错误文本：错误穿过 loop → 引擎 → 工作流
+ * 这几层之后往往只剩一个字符串（`llm_error` 事件带的是 message），
+ * 只认 code 会在真实链路上恒为 false。
+ */
+export function isUsageLimitError(error: unknown): boolean {
+  if (error instanceof GatewayClientError)
+    return USAGE_LIMIT_CODES.has(error.code);
+  const text = error instanceof Error ? error.message : String(error ?? '');
+  return [...USAGE_LIMIT_CODES].some((code) => text.includes(code));
+}
+
+function combinedSignal(signal?: AbortSignal): AbortSignal {
+  const timeout = AbortSignal.timeout(DEADLINE_MS);
+  return signal ? AbortSignal.any([signal, timeout]) : timeout;
+}
+
+async function readWithIdleTimeout<T>(
+  promise: Promise<T>,
+  signal: AbortSignal,
+): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let onAbort: (() => void) | undefined;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise<T>((_, reject) => {
+        timer = setTimeout(
+          () =>
+            reject(
+              new GatewayClientError(
+                'PROVIDER_TIMEOUT',
+                true,
+                '在线模型流式响应超时',
+              ),
+            ),
+          IDLE_TIMEOUT_MS,
+        );
+        onAbort = () => reject(new DOMException('aborted', 'AbortError'));
+        signal.addEventListener('abort', onAbort, { once: true });
+      }),
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+    if (onAbort) signal.removeEventListener('abort', onAbort);
+  }
+}
+
+/** Gateway transport only. The caller retains the existing Agent/tool loop. */
+export async function* chatGateway(args: {
+  provider: GatewayProvider;
+  messages: Message[];
+  tools: Tool[];
+  signal?: AbortSignal;
+  conversationMode?: ConversationMode;
+  responseFormat?: {
+    type: 'json_schema';
+    json_schema: {
+      name: string;
+      schema: Record<string, unknown>;
+      strict?: boolean;
+    };
+  };
+}): AsyncGenerator<LlmStreamEvent> {
+  const {
+    provider,
+    messages,
+    tools,
+    signal: parentSignal,
+    conversationMode,
+    responseFormat,
+  } = args;
+  if (!provider.gatewayUrl || !provider.gatewayToken || !provider.remoteModelId)
+    throw new GatewayClientError(
+      'DEVICE_REVOKED',
+      false,
+      '在线模型设备授权不存在或已过期',
+    );
+  const url = `${provider.gatewayUrl.replace(/\/$/, '')}/api/inference/chat/stream`;
+  const payload = JSON.stringify({
+    requestId: randomUUID(),
+    modelId: provider.remoteModelId,
+    // Keep the gateway payload limited to provider-facing protocol content.
+    // Session IDs, provenance metadata, display metadata, and local-only
+    // fields must never cross the remote inference boundary.
+    messages: safeMessages(
+      prepareMessagesForProvider(messages, conversationMode ?? 'private'),
+    ),
+    tools: gatewayTools(
+      tools,
+      provider.gatewayToolCategories ??
+        provider.gatewayDefaultToolCategories ??
+        provider.gatewayMaxToolCategories,
+    ),
+    toolCategories:
+      provider.gatewayToolCategories ?? provider.gatewayMaxToolCategories ?? [],
+    ...(responseFormat ? { responseFormat } : {}),
+  });
+  let activeReader: { cancel(): Promise<void> } | undefined;
+  const signal = combinedSignal(parentSignal);
+  try {
+    const response = await fetch(url, {
+      method: 'POST',
+      signal,
+      headers: {
+        'content-type': 'application/json',
+        authorization: `Bearer ${provider.gatewayToken}`,
+      },
+      body: payload,
+    });
+    if (!response.ok) {
+      const body = (await response.json().catch(() => ({}))) as {
+        error?: string;
+        code?: string;
+        retryable?: boolean;
+      };
+      // ⚠️ 服务端**明确表态**优先，状态码只是它没表态时的推断。
+      // 曾经写成 `body.retryable === true || status === 429 || …`：服务端发
+      // `{code:'TOKEN_QUOTA_EXHAUSTED', retryable:false}` 配 HTTP 429 时，
+      // `retryable:false` 被 `|| 429` 直接覆盖 —— 于是「额度用完了，别重试」
+      // 被当成限流反复重试，既拖慢失败反馈，也把真正的原因埋掉。
+      // 配额耗尽与限流是两回事：前者要去加额度，后者等一会儿就好。
+      const retryable =
+        typeof body.retryable === 'boolean'
+          ? body.retryable
+          : response.status === 408 ||
+            response.status === 425 ||
+            response.status === 429 ||
+            response.status >= 500;
+      throw new GatewayClientError(
+        body.code ?? `HTTP_${response.status}`,
+        retryable,
+        body.error ?? `在线模型请求失败（${response.status}）`,
+      );
+    }
+    if (!response.body)
+      throw new GatewayClientError(
+        'PROVIDER_UNAVAILABLE',
+        true,
+        '在线模型未返回流式响应',
+      );
+    const reader = response.body.getReader();
+    activeReader = reader;
+    const decoder = new TextDecoder();
+    let buffer = '';
+    while (true) {
+      const next = await readWithIdleTimeout(reader.read(), signal);
+      if (next.done) break;
+      buffer += decoder.decode(next.value, { stream: true });
+      const frames = buffer.split(/\n\n/);
+      buffer = frames.pop() ?? '';
+      for (const frame of frames) {
+        const line = frame
+          .split(/\r?\n/)
+          .find((item) => item.startsWith('data:'));
+        if (!line) continue;
+        let event: GatewayEvent;
+        try {
+          event = JSON.parse(line.slice(5).trim());
+        } catch {
+          continue;
+        }
+        if (event.type === 'error')
+          throw new GatewayClientError(
+            event.code ?? 'PROVIDER_UNAVAILABLE',
+            event.retryable === true,
+            event.message ?? '在线模型流式调用失败',
+          );
+        if (event.type === 'usage') {
+          yield event as LlmStreamEvent;
+          continue;
+        }
+        if (event.type === 'done') return;
+        yield event as LlmStreamEvent;
+      }
+    }
+    return;
+  } finally {
+    // Release the response body on both normal `done` and error/abort paths.
+    // Without this, a completed stream can keep an HTTP connection/socket
+    // alive until the runtime's garbage collector notices it.
+    await activeReader?.cancel().catch(() => {});
+    activeReader = undefined;
+  }
+}

package/src/llm/messageProvenance.js

@@ -0,0 +1,46 @@
+function provenanceLabel(provenance) {
+    if (provenance.mode === 'private') {
+        return '[历史来源：主人私聊，仅限内部使用；群聊中不得复述或公开]';
+    }
+    const fields = [
+        '历史来源：群聊公开消息',
+        provenance.groupId ? `群=${provenance.groupId}` : '',
+        provenance.senderName ? `发送者=${provenance.senderName}` : '',
+        provenance.senderId ? `发送者ID=${provenance.senderId}` : '',
+        provenance.taskId ? `父任务=${provenance.taskId}` : '',
+    ].filter(Boolean);
+    return `[${fields.join('；')}]`;
+}
+function decorateContent(content, provenance) {
+    if (!provenance || content === null)
+        return content;
+    const label = provenanceLabel(provenance);
+    if (typeof content === 'string')
+        return `${label}\n${content}`;
+    const firstText = content.findIndex((part) => part.type === 'text');
+    if (firstText < 0)
+        return [{ type: 'text', text: label }, ...content];
+    return content.map((part, index) => index === firstText && part.type === 'text'
+        ? { ...part, text: `${label}\n${part.text}` }
+        : part);
+}
+/** Clone messages for a provider request without leaking local UI/provenance fields. */
+export function prepareMessagesForProvider(messages, conversationMode = 'private') {
+    return messages
+        .filter((message) => !(message.role === 'system' && message._ephemeral === true))
+        .map((message) => {
+        const { id, timestamp, attachments, browserReferences, display_metadata, tool_result_policy, provenance, ...rest } = message;
+        if (rest.role === 'user' || rest.role === 'assistant') {
+            // 旧 Session 在引入 provenance 之前没有来源元数据。进入群聊时必须保守地
+            // 把这些历史当作主人私聊，而不是让模型误以为它们已经公开。
+            const effectiveProvenance = provenance ?? (conversationMode === 'group'
+                ? { mode: 'private', visibility: 'owner-private' }
+                : undefined);
+            return {
+                ...rest,
+                content: decorateContent(rest.content, effectiveProvenance),
+            };
+        }
+        return rest;
+    });
+}

package/src/llm/messageProvenance.ts

@@ -0,0 +1,58 @@
+import type { ChatContentPart, ConversationProvenance, Message } from '../types.js';
+
+function provenanceLabel(provenance: ConversationProvenance): string {
+  if (provenance.mode === 'private') {
+    return '[历史来源：主人私聊，仅限内部使用；群聊中不得复述或公开]';
+  }
+  const fields = [
+    '历史来源：群聊公开消息',
+    provenance.groupId ? `群=${provenance.groupId}` : '',
+    provenance.senderName ? `发送者=${provenance.senderName}` : '',
+    provenance.senderId ? `发送者ID=${provenance.senderId}` : '',
+    provenance.taskId ? `父任务=${provenance.taskId}` : '',
+  ].filter(Boolean);
+  return `[${fields.join('；')}]`;
+}
+
+function decorateContent(
+  content: string | ChatContentPart[] | null,
+  provenance: ConversationProvenance | undefined,
+): string | ChatContentPart[] | null {
+  if (!provenance || content === null) return content;
+  const label = provenanceLabel(provenance);
+  if (typeof content === 'string') return `${label}\n${content}`;
+  const firstText = content.findIndex((part) => part.type === 'text');
+  if (firstText < 0) return [{ type: 'text', text: label }, ...content];
+  return content.map((part, index) => index === firstText && part.type === 'text'
+    ? { ...part, text: `${label}\n${part.text}` }
+    : part);
+}
+
+/** Clone messages for a provider request without leaking local UI/provenance fields. */
+export function prepareMessagesForProvider(
+  messages: readonly Message[],
+  conversationMode: 'private' | 'group' = 'private',
+): Message[] {
+  return messages
+    .filter((message) => !(message.role === 'system' && message._ephemeral === true))
+    .map((message) => {
+      const {
+        id, timestamp, attachments, browserReferences, display_metadata, tool_result_policy, provenance, ...rest
+      } = message as Message & Record<string, unknown>;
+      if (rest.role === 'user' || rest.role === 'assistant') {
+        // 旧 Session 在引入 provenance 之前没有来源元数据。进入群聊时必须保守地
+        // 把这些历史当作主人私聊，而不是让模型误以为它们已经公开。
+        const effectiveProvenance = provenance ?? (conversationMode === 'group'
+          ? { mode: 'private' as const, visibility: 'owner-private' as const }
+          : undefined);
+        return {
+          ...rest,
+          content: decorateContent(
+            rest.content as string | ChatContentPart[] | null,
+            effectiveProvenance,
+          ),
+        } as Message;
+      }
+      return rest as Message;
+    });
+}

package/src/llm/modelProvider.js

@@ -0,0 +1 @@
+export {};

package/src/llm/modelProvider.ts

@@ -0,0 +1,22 @@
+import type { ConversationMode } from '../runtime/agentRuntimeContext.js';
+import type { CacheEditsState, LlmStreamEvent, Message, Provider, PromptCacheContext, Tool } from '../types.js';
+
+export interface NormalizedModelRequest {
+  provider: Provider;
+  messages: Message[];
+  tools: Tool[];
+  signal?: AbortSignal;
+  responseFormat?: { type: 'json_schema'; json_schema: { name: string; schema: Record<string, unknown>; strict?: boolean } };
+  promptCache?: PromptCacheContext;
+  conversationMode?: ConversationMode;
+  cacheEdits?: CacheEditsState;
+  /** Current-turn images must not be silently removed when they are required. */
+  visionPolicy?: 'required' | 'optional-history';
+}
+
+/** Both local and gateway transports consume the same normalized request. */
+export interface ModelProvider {
+  readonly source: 'local' | 'gateway';
+  readonly descriptor: Provider;
+  stream(request: NormalizedModelRequest): AsyncGenerator<LlmStreamEvent, void, void>;
+}