@mate-academy/llm-gateway 8.9.0 → 8.11.0

package/README.md

@@ -338,6 +338,60 @@ if (turn.stopReason === LLMToolLoopStopReasons.TerminalTool) {
   events — so parallel tool calls and repeated delegations reconstruct into an
   unambiguous run tree. Listeners may be async; a throw or rejection is logged
   and never affects the run.
+- **Full-fidelity history.** `history` restores the conversation as it happened,
+  not a prose retelling of it. An entry is a plain message
+  (`{ role, text }`), a past tool round
+  (`{ type: LLMHistoryEntryTypes.ToolCall, calls, text? }`), the result that
+  answered one of its calls
+  (`{ type: LLMHistoryEntryTypes.ToolResult, toolCallId, result }`), or
+  mid-conversation context (`{ type: LLMHistoryEntryTypes.Context, text }`).
+  Each maps to the provider's own representation, so a resumed run reads its
+  own past calls as calls. The union is additive — an existing
+  `LLMPlainMessage[]` is already a valid history and maps exactly as before.
+
+  ```typescript
+  await llm.runAgent(agent, {
+    variables,
+    input: userMessage,
+    history: [
+      { role: 'user', text: 'Rewrite the flaky-selectors theory' },
+      { type: LLMHistoryEntryTypes.Context, text: carriedPlan },
+      {
+        type: LLMHistoryEntryTypes.ToolCall,
+        text: 'Looking it up.',
+        calls: [{
+          id: 'call-1',
+          name: 'find_content',
+          arguments: { query: 'flaky selectors' },
+        }],
+      },
+      {
+        type: LLMHistoryEntryTypes.ToolResult,
+        toolCallId: 'call-1',
+        result: 'theory-1',
+      },
+    ],
+  });
+  ```
+
+  Per provider: LLMAPI replays a round as an assistant message carrying
+  `tool_calls` plus `tool`-role results and context as a mid-conversation
+  `system` message; OpenAI replays `function_call` / `function_call_output`
+  items and context as a `developer` item; Gemini replays a `model` turn of
+  `functionCall` parts answered by a `user` turn of `functionResponse` parts,
+  and — having no mid-conversation system role — carries context as a user
+  turn. On Gemini a restored call carries no `thought_signature`, so it replays
+  under the documented validator-bypass marker, and a multi-call round is split
+  into sequential single-call turns exactly as the live loop records one; a
+  call that kept its signature passes it in `signature` and it is echoed
+  verbatim.
+
+  A call the history leaves unanswered is answered by the package with a real
+  tool result carrying `LLM_UNANSWERED_TOOL_CALL_RESULT` — every provider
+  rejects an unanswered call, so the repair is native rather than left to the
+  caller to fake in prose. A result naming no preceding call, a second result
+  for an already-answered call, and a round that called nothing are dropped.
+  Same-role entries need no merging: the contract carries the structure.
 - **Intermediate narration.** When the model returns visible assistant text
   alongside tool calls in a round that will continue, that text is emitted as
   `agent_message` (attributed to the emitting run, so a subagent's narration
@@ -1404,7 +1458,10 @@ Interface for chat/assistance services with file handling capabilities.
 - `createChat(options)`: Create a new chat/conversation
   - `model`: The LLM model to use
   - `instructions`: Optional initial instructions for the conversation
-  - `history`: Optional conversation history
+  - `history`: Optional conversation history — an `LLMHistoryEntry[]` of plain
+    messages, past tool calls (`LLMHistoryToolCallEntry`), their results
+    (`LLMHistoryToolResultEntry`) and mid-conversation context
+    (`LLMHistoryContextEntry`), each mapped to the provider's native shape
   - `files`: Optional array of uploaded files
   - `storageId`: Optional storage ID to use
 - `deleteChat(chatId)`: Delete a chat
@@ -2113,8 +2170,8 @@ describe('Custom LLM Integration Test', () => {
 The `LLMAPIModelNames` enum and `LLMAPI_AVAILABLE_MODELS` map drift as
 LLMAPI adds/renames models. The pipeline in
 [`scripts/sync-llmapi-models/`](scripts/sync-llmapi-models/README.md)
-reconciles them against `GET https://api.llmapi.ai/v1/models` under these
-rules:
+reconciles them against `GET https://api.llmapi.ai/v1/models` and the audio
+catalog at `GET https://api.llmapi.ai/audio-models` under these rules:
 
 - Unscoped aliases are always present; scoped aliases (`openai/…`, `azure/…`,
   `nebius/…`) only when LLMAPI advertises 2+ providers for that model.
@@ -2123,6 +2180,10 @@ rules:
   existing and new route, including provider-specific overrides.
 - `maxOutputTokens` and any missing `maxInputTokens` are researched from
   provider docs via web-search sub-agents.
+- TTS/STT limits and pricing, batch/streaming STT classification,
+  purpose-specific model maps, and default voice mappings are refreshed from
+  the audio catalog. Streaming-only STT models are exported separately and are
+  not exposed through the file-based `SpeechToText` service.
 
 See the linked README for the full classify → research → apply workflow.