@fgv/ts-extras 5.1.0-33 → 5.1.0-34

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. package/dist/packlets/ai-assist/apiClient.js +4 -4
  2. package/dist/packlets/ai-assist/apiClient.js.map +1 -1
  3. package/dist/packlets/ai-assist/chatRequestBuilders.js +86 -3
  4. package/dist/packlets/ai-assist/chatRequestBuilders.js.map +1 -1
  5. package/dist/packlets/ai-assist/converters.js +31 -1
  6. package/dist/packlets/ai-assist/converters.js.map +1 -1
  7. package/dist/packlets/ai-assist/index.js +3 -2
  8. package/dist/packlets/ai-assist/index.js.map +1 -1
  9. package/dist/packlets/ai-assist/model.js.map +1 -1
  10. package/dist/packlets/ai-assist/streamingAdapters/anthropic.js +176 -32
  11. package/dist/packlets/ai-assist/streamingAdapters/anthropic.js.map +1 -1
  12. package/dist/packlets/ai-assist/streamingAdapters/clientToolContinuationBuilder.js +511 -0
  13. package/dist/packlets/ai-assist/streamingAdapters/clientToolContinuationBuilder.js.map +1 -0
  14. package/dist/packlets/ai-assist/streamingAdapters/common.js +95 -0
  15. package/dist/packlets/ai-assist/streamingAdapters/common.js.map +1 -1
  16. package/dist/packlets/ai-assist/streamingAdapters/gemini.js +34 -10
  17. package/dist/packlets/ai-assist/streamingAdapters/gemini.js.map +1 -1
  18. package/dist/packlets/ai-assist/streamingAdapters/openaiResponses.js +215 -15
  19. package/dist/packlets/ai-assist/streamingAdapters/openaiResponses.js.map +1 -1
  20. package/dist/packlets/ai-assist/streamingClient.js +18 -0
  21. package/dist/packlets/ai-assist/streamingClient.js.map +1 -1
  22. package/dist/packlets/ai-assist/thinkingOptionsResolver.js +23 -0
  23. package/dist/packlets/ai-assist/thinkingOptionsResolver.js.map +1 -1
  24. package/dist/packlets/ai-assist/toolFormats.js +106 -10
  25. package/dist/packlets/ai-assist/toolFormats.js.map +1 -1
  26. package/dist/ts-extras.d.ts +339 -3
  27. package/lib/packlets/ai-assist/apiClient.d.ts.map +1 -1
  28. package/lib/packlets/ai-assist/apiClient.js +3 -3
  29. package/lib/packlets/ai-assist/apiClient.js.map +1 -1
  30. package/lib/packlets/ai-assist/chatRequestBuilders.d.ts +29 -5
  31. package/lib/packlets/ai-assist/chatRequestBuilders.d.ts.map +1 -1
  32. package/lib/packlets/ai-assist/chatRequestBuilders.js +86 -3
  33. package/lib/packlets/ai-assist/chatRequestBuilders.js.map +1 -1
  34. package/lib/packlets/ai-assist/converters.d.ts +9 -1
  35. package/lib/packlets/ai-assist/converters.d.ts.map +1 -1
  36. package/lib/packlets/ai-assist/converters.js +31 -1
  37. package/lib/packlets/ai-assist/converters.js.map +1 -1
  38. package/lib/packlets/ai-assist/index.d.ts +4 -3
  39. package/lib/packlets/ai-assist/index.d.ts.map +1 -1
  40. package/lib/packlets/ai-assist/index.js +5 -1
  41. package/lib/packlets/ai-assist/index.js.map +1 -1
  42. package/lib/packlets/ai-assist/model.d.ts +183 -3
  43. package/lib/packlets/ai-assist/model.d.ts.map +1 -1
  44. package/lib/packlets/ai-assist/model.js.map +1 -1
  45. package/lib/packlets/ai-assist/streamingAdapters/anthropic.d.ts +58 -5
  46. package/lib/packlets/ai-assist/streamingAdapters/anthropic.d.ts.map +1 -1
  47. package/lib/packlets/ai-assist/streamingAdapters/anthropic.js +175 -31
  48. package/lib/packlets/ai-assist/streamingAdapters/anthropic.js.map +1 -1
  49. package/lib/packlets/ai-assist/streamingAdapters/clientToolContinuationBuilder.d.ts +158 -0
  50. package/lib/packlets/ai-assist/streamingAdapters/clientToolContinuationBuilder.d.ts.map +1 -0
  51. package/lib/packlets/ai-assist/streamingAdapters/clientToolContinuationBuilder.js +517 -0
  52. package/lib/packlets/ai-assist/streamingAdapters/clientToolContinuationBuilder.js.map +1 -0
  53. package/lib/packlets/ai-assist/streamingAdapters/common.d.ts +51 -0
  54. package/lib/packlets/ai-assist/streamingAdapters/common.d.ts.map +1 -1
  55. package/lib/packlets/ai-assist/streamingAdapters/common.js +97 -0
  56. package/lib/packlets/ai-assist/streamingAdapters/common.js.map +1 -1
  57. package/lib/packlets/ai-assist/streamingAdapters/gemini.d.ts +16 -2
  58. package/lib/packlets/ai-assist/streamingAdapters/gemini.d.ts.map +1 -1
  59. package/lib/packlets/ai-assist/streamingAdapters/gemini.js +34 -10
  60. package/lib/packlets/ai-assist/streamingAdapters/gemini.js.map +1 -1
  61. package/lib/packlets/ai-assist/streamingAdapters/openaiResponses.d.ts +15 -2
  62. package/lib/packlets/ai-assist/streamingAdapters/openaiResponses.d.ts.map +1 -1
  63. package/lib/packlets/ai-assist/streamingAdapters/openaiResponses.js +214 -14
  64. package/lib/packlets/ai-assist/streamingAdapters/openaiResponses.js.map +1 -1
  65. package/lib/packlets/ai-assist/streamingClient.d.ts +17 -0
  66. package/lib/packlets/ai-assist/streamingClient.d.ts.map +1 -1
  67. package/lib/packlets/ai-assist/streamingClient.js +20 -1
  68. package/lib/packlets/ai-assist/streamingClient.js.map +1 -1
  69. package/lib/packlets/ai-assist/thinkingOptionsResolver.d.ts +18 -2
  70. package/lib/packlets/ai-assist/thinkingOptionsResolver.d.ts.map +1 -1
  71. package/lib/packlets/ai-assist/thinkingOptionsResolver.js +24 -0
  72. package/lib/packlets/ai-assist/thinkingOptionsResolver.js.map +1 -1
  73. package/lib/packlets/ai-assist/toolFormats.d.ts +40 -9
  74. package/lib/packlets/ai-assist/toolFormats.d.ts.map +1 -1
  75. package/lib/packlets/ai-assist/toolFormats.js +107 -10
  76. package/lib/packlets/ai-assist/toolFormats.js.map +1 -1
  77. package/package.json +7 -7
@@ -4,6 +4,7 @@ import { DateTime } from 'luxon';
4
4
  import { FileTree } from '@fgv/ts-json-base';
5
5
  import { Hash as Hash_2 } from '@fgv/ts-utils';
6
6
  import { JsonObject } from '@fgv/ts-json-base';
7
+ import { JsonSchema } from '@fgv/ts-json-base';
7
8
  import { JsonValue } from '@fgv/ts-json-base';
8
9
  import { Logging } from '@fgv/ts-utils';
9
10
  import { Result } from '@fgv/ts-utils';
@@ -29,7 +30,13 @@ declare namespace AiAssist {
29
30
  AiProviderId,
30
31
  AiServerToolType,
31
32
  AiServerToolConfig,
33
+ AiToolConfig,
32
34
  IAiWebSearchToolConfig,
35
+ IAiClientToolConfig,
36
+ IAiClientTool,
37
+ IAiClientToolCallSummary,
38
+ IAiClientToolContinuation,
39
+ IAiClientToolTurnResult,
33
40
  IAiToolEnablement,
34
41
  IAiCompletionResponse,
35
42
  IChatMessage,
@@ -77,6 +84,9 @@ declare namespace AiAssist {
77
84
  IAiStreamEvent,
78
85
  IAiStreamTextDelta,
79
86
  IAiStreamToolEvent,
87
+ IAiStreamToolUseStart,
88
+ IAiStreamToolUseDelta,
89
+ IAiStreamToolUseComplete,
80
90
  IAiStreamDone,
81
91
  IAiStreamError,
82
92
  ModelSpec,
@@ -123,10 +133,14 @@ declare namespace AiAssist {
123
133
  callProviderCompletionStream,
124
134
  callProxiedCompletionStream,
125
135
  IProviderCompletionStreamParams,
136
+ executeClientToolTurn,
137
+ IExecuteClientToolTurnParams,
138
+ IExecuteClientToolTurnResult,
126
139
  aiProviderId,
127
140
  aiServerToolType,
128
141
  aiWebSearchToolConfig,
129
142
  aiServerToolConfig,
143
+ aiClientToolConfig,
130
144
  aiToolEnablement,
131
145
  aiAssistProviderConfig,
132
146
  aiAssistSettings,
@@ -142,7 +156,9 @@ declare namespace AiAssist {
142
156
  SMART_JSON_PROMPT_HINT,
143
157
  IGenerateJsonCompletionParams,
144
158
  IGenerateJsonCompletionResult,
145
- JsonPromptHint
159
+ JsonPromptHint,
160
+ anthropicEffortToBudgetTokens,
161
+ IResolvedThinkingConfig
146
162
  }
147
163
  }
148
164
  export { AiAssist }
@@ -159,6 +175,15 @@ declare const aiAssistProviderConfig: Converter<IAiAssistProviderConfig>;
159
175
  */
160
176
  declare const aiAssistSettings: Converter<IAiAssistSettings>;
161
177
 
178
+ /**
179
+ * Converter for {@link AiAssist.IAiClientToolConfig}. Validates the wrapper shape: `type`,
180
+ * `name`, `description`, and the presence of a usable `parametersSchema`.
181
+ * Does not inspect the inner JSON Schema structure — `JsonSchema.object(...)` already
182
+ * guarantees the schema is valid.
183
+ * @public
184
+ */
185
+ declare const aiClientToolConfig: Converter<IAiClientToolConfig>;
186
+
162
187
  /**
163
188
  * API format categories for image-generation provider routing.
164
189
  *
@@ -263,6 +288,13 @@ declare const aiServerToolType: Converter<AiServerToolType>;
263
288
  */
264
289
  declare type AiThinkingMode = 'optional' | 'required' | 'unsupported';
265
290
 
291
+ /**
292
+ * Union of all tool configurations: server-side or client-defined.
293
+ * Discriminated on `type`.
294
+ * @public
295
+ */
296
+ declare type AiToolConfig = AiServerToolConfig | IAiClientToolConfig;
297
+
266
298
  /**
267
299
  * Converter for {@link IAiToolEnablement}.
268
300
  * @public
@@ -311,6 +343,19 @@ declare const allModelSpecKeys: ReadonlyArray<ModelSpecKey>;
311
343
  */
312
344
  declare const allProviderIds: ReadonlyArray<AiProviderId>;
313
345
 
346
+ /**
347
+ * Maps Anthropic effort level to the `thinking.budget_tokens` integer that the
348
+ * Anthropic API requires when `thinking.type === 'enabled'`.
349
+ *
350
+ * Policy: low = 2048, medium = 8192, high = 24000, max = 32000. The lower three
351
+ * align with the Anthropic-published minimum-meaningful budget, a mid-range
352
+ * default, and a "deep thinking" allotment respectively. `max` targets Opus 4.6's
353
+ * deepest budget and stays within typical model limits.
354
+ *
355
+ * @public
356
+ */
357
+ declare function anthropicEffortToBudgetTokens(effort: NonNullable<IAnthropicThinkingConfig['effort']>): number;
358
+
314
359
  /**
315
360
  * Model IDs for Anthropic thinking-capable models.
316
361
  * @public
@@ -872,6 +917,29 @@ declare type EncryptionAlgorithm = typeof Constants.DEFAULT_ALGORITHM;
872
917
  */
873
918
  declare const encryptionAlgorithm: Converter<EncryptionAlgorithm>;
874
919
 
920
+ /**
921
+ * Orchestrates a single client-tool streaming turn for any supported provider.
922
+ *
923
+ * Starts a streaming request, iterates the underlying provider stream, and:
924
+ * - Forwards `text-delta`, `tool-event`, `client-tool-call-start`, and
925
+ * `client-tool-call-done` events through to the consumer.
926
+ * - For each `client-tool-call-done` event: validates the raw args against the
927
+ * tool's `parametersSchema`, invokes `execute(typedArgs)`, and emits a
928
+ * `client-tool-result` event.
929
+ * - After stream completion: builds the per-provider continuation (or
930
+ * `{ continuation: undefined }` when no tool calls occurred) and resolves
931
+ * `nextTurn`.
932
+ *
933
+ * **Anthropic constraint (E3):** The continuation for Anthropic does not set
934
+ * a forced `tool_choice`. Only `tool_choice: 'auto'` (the default, i.e.
935
+ * omitted) is compatible with extended thinking.
936
+ *
937
+ * @param params - Turn parameters
938
+ * @returns `{ events, nextTurn }` — stream iterable + completion promise
939
+ * @public
940
+ */
941
+ declare function executeClientToolTurn(params: IExecuteClientToolTurnParams): Result<IExecuteClientToolTurnResult>;
942
+
875
943
  declare namespace Experimental {
876
944
  export {
877
945
  ExtendedArray,
@@ -1475,6 +1543,117 @@ declare interface IAiAssistSettings {
1475
1543
  readonly proxyAllProviders?: boolean;
1476
1544
  }
1477
1545
 
1546
+ /**
1547
+ * A client-defined tool: configuration + execution callback pair.
1548
+ *
1549
+ * @remarks
1550
+ * The `execute` callback receives typed `TParams` (already validated by
1551
+ * `config.parametersSchema.validate()`) and returns a `Promise<Result<unknown>>`.
1552
+ * Thrown errors are caught via `captureAsyncResult` in the round-trip helper.
1553
+ *
1554
+ * @public
1555
+ */
1556
+ declare interface IAiClientTool<TParams = unknown> {
1557
+ /** The tool's configuration (name, description, parameters schema). */
1558
+ readonly config: IAiClientToolConfig<TParams>;
1559
+ /**
1560
+ * Execute the tool with validated parameters.
1561
+ * @param args - Typed arguments, already validated against `config.parametersSchema`.
1562
+ * @returns A `Promise<Result<unknown>>` — the result is stringified and sent back to the model.
1563
+ */
1564
+ readonly execute: (args: TParams) => Promise<Result<unknown>>;
1565
+ }
1566
+
1567
+ /**
1568
+ * Summary of a single client tool call within a turn: the tool name, call ID,
1569
+ * raw arguments, execution result, and whether the execution was an error.
1570
+ * @public
1571
+ */
1572
+ declare interface IAiClientToolCallSummary {
1573
+ /** The name of the tool that was called. */
1574
+ readonly toolName: string;
1575
+ /** Provider-assigned call identifier (absent for Gemini). */
1576
+ readonly callId?: string;
1577
+ /** The fully accumulated raw arguments object as parsed JSON. */
1578
+ readonly args: JsonObject;
1579
+ /** The stringified result (success value or error message). */
1580
+ readonly result: string;
1581
+ /** Whether execution failed (schema validation failure, execute error, or unknown tool). */
1582
+ readonly isError: boolean;
1583
+ }
1584
+
1585
+ /**
1586
+ * Configuration for a client-defined (harness-supplied) tool.
1587
+ *
1588
+ * @remarks
1589
+ * The `parametersSchema` is the single source of truth for both the wire-format
1590
+ * JSON Schema sent to the provider (via `.toJson()`) and the runtime argument
1591
+ * validation (via `.validate(rawArgs)`). Use `JsonSchema.object(...)` from
1592
+ * `@fgv/ts-json-base` to author the schema as a const (e.g. `const mySchema = JsonSchema.object({...})`);
1593
+ * the static type `TParams` is then derived via `JsonSchema.Static<typeof mySchema>` —
1594
+ * no drift between wire schema and runtime validation.
1595
+ *
1596
+ * @public
1597
+ */
1598
+ declare interface IAiClientToolConfig<TParams = unknown> {
1599
+ /** Discriminator — always `'client_tool'`. */
1600
+ readonly type: 'client_tool';
1601
+ /** Tool name sent to the model (must be unique within a call). */
1602
+ readonly name: string;
1603
+ /** Human-readable description of what the tool does, shown to the model. */
1604
+ readonly description: string;
1605
+ /**
1606
+ * JSON Schema validator for the tool's parameters. Emits wire format via
1607
+ * `.toJson()` and validates model-returned args via `.validate(rawArgs)`.
1608
+ */
1609
+ readonly parametersSchema: JsonSchema.ISchemaValidator<TParams>;
1610
+ }
1611
+
1612
+ /**
1613
+ * The provider-specific continuation data needed to build the follow-up request
1614
+ * for the next round of the conversation.
1615
+ *
1616
+ * @remarks
1617
+ * `messages` are provider-native request objects (Anthropic: content-block arrays,
1618
+ * OpenAI Responses API: input items, Gemini: content parts). The continuation
1619
+ * builder in `clientToolContinuationBuilder.ts` populates this.
1620
+ *
1621
+ * @public
1622
+ */
1623
+ declare interface IAiClientToolContinuation {
1624
+ /**
1625
+ * Provider-native wire-format message objects to supply back on the next
1626
+ * streaming call via `IExecuteClientToolTurnParams.continuationMessages`
1627
+ * (which is forwarded as `rawTail` to the underlying call). The exact
1628
+ * shape depends on the provider format and may contain provider-specific
1629
+ * blocks (e.g. Anthropic thinking/redacted_thinking/tool_use). These are
1630
+ * NOT `IChatMessage[]` and must not be prepended via `messagesBefore` —
1631
+ * the normalized-message path would strip the provider-native fields
1632
+ * (signatures, redacted thinking) that the server requires for
1633
+ * continuation validation.
1634
+ */
1635
+ readonly messages: ReadonlyArray<JsonObject>;
1636
+ /** Summary of each tool call that was executed in this turn. */
1637
+ readonly toolCallsSummary: ReadonlyArray<IAiClientToolCallSummary>;
1638
+ }
1639
+
1640
+ /**
1641
+ * The result of a single client-tool turn: the optional continuation for the next
1642
+ * call (absent when no tool calls occurred) and whether the stream was truncated.
1643
+ * @public
1644
+ */
1645
+ declare interface IAiClientToolTurnResult {
1646
+ /**
1647
+ * The continuation data for the next round-trip. `undefined` when the model
1648
+ * completed without invoking any client tools.
1649
+ */
1650
+ readonly continuation: IAiClientToolContinuation | undefined;
1651
+ /** Whether the stream was truncated (token limit or stop reason). */
1652
+ readonly truncated: boolean;
1653
+ /** The full concatenated text from all `text-delta` events in this turn. */
1654
+ readonly fullText: string;
1655
+ }
1656
+
1478
1657
  /**
1479
1658
  * Result of an AI provider completion call.
1480
1659
  * @public
@@ -1783,6 +1962,15 @@ declare interface IAiStreamDone {
1783
1962
  readonly truncated: boolean;
1784
1963
  /** The full concatenated text from all `text-delta` events. */
1785
1964
  readonly fullText: string;
1965
+ /**
1966
+ * Provider-reported reason a truncated response was cut short (e.g.
1967
+ * `'max_output_tokens'`, `'content_filter'`), when the provider supplies one.
1968
+ * Currently populated only by the OpenAI / xAI Responses adapter, from the
1969
+ * completed payload's `incomplete_details.reason`. Meaningful only when
1970
+ * `truncated === true`; `undefined` otherwise (and whenever the provider
1971
+ * reports truncation without a reason).
1972
+ */
1973
+ readonly incompleteReason?: string;
1786
1974
  }
1787
1975
 
1788
1976
  /**
@@ -1804,9 +1992,15 @@ declare interface IAiStreamError {
1804
1992
 
1805
1993
  /**
1806
1994
  * Discriminated union of events emitted by a streaming completion.
1995
+ *
1996
+ * @remarks
1997
+ * **Exhaustive-switch consumers must handle all variants.** The three
1998
+ * `client-tool-*` variants were added when client-tool support shipped;
1999
+ * update every exhaustive switch over this union in lockstep.
2000
+ *
1807
2001
  * @public
1808
2002
  */
1809
- declare type IAiStreamEvent = IAiStreamTextDelta | IAiStreamToolEvent | IAiStreamDone | IAiStreamError;
2003
+ declare type IAiStreamEvent = IAiStreamTextDelta | IAiStreamToolEvent | IAiStreamToolUseStart | IAiStreamToolUseDelta | IAiStreamToolUseComplete | IAiStreamDone | IAiStreamError;
1810
2004
 
1811
2005
  /**
1812
2006
  * A text-content delta arriving during a streaming completion.
@@ -1837,6 +2031,60 @@ declare interface IAiStreamToolEvent {
1837
2031
  readonly detail?: string;
1838
2032
  }
1839
2033
 
2034
+ /**
2035
+ * Emitted after a client-defined tool has been executed and the result is ready
2036
+ * to be fed back to the model in the round-trip continuation.
2037
+ * @public
2038
+ */
2039
+ declare interface IAiStreamToolUseComplete {
2040
+ readonly type: 'client-tool-result';
2041
+ /** The name of the client tool that was executed. */
2042
+ readonly toolName: string;
2043
+ /**
2044
+ * Provider-assigned call identifier. Absent for Gemini.
2045
+ */
2046
+ readonly callId?: string;
2047
+ /** The stringified result returned by the tool's execute callback. */
2048
+ readonly result: string;
2049
+ /** Whether the tool execution failed (schema validation failure, execute error, or unknown tool). */
2050
+ readonly isError: boolean;
2051
+ }
2052
+
2053
+ /**
2054
+ * Emitted when a client-defined tool call is complete and its arguments are fully
2055
+ * accumulated. The `args` object is the fully parsed JSON object — no further
2056
+ * streaming deltas follow for this call.
2057
+ * @public
2058
+ */
2059
+ declare interface IAiStreamToolUseDelta {
2060
+ readonly type: 'client-tool-call-done';
2061
+ /** The name of the client tool being called. */
2062
+ readonly toolName: string;
2063
+ /**
2064
+ * Provider-assigned call identifier. Absent for Gemini.
2065
+ */
2066
+ readonly callId?: string;
2067
+ /** The fully accumulated and parsed tool arguments. */
2068
+ readonly args: JsonObject;
2069
+ }
2070
+
2071
+ /**
2072
+ * Emitted when a client-defined tool call begins streaming. Carries the tool name
2073
+ * and optional provider-assigned call ID (Anthropic / OpenAI Responses API; absent
2074
+ * for Gemini which does not assign call IDs).
2075
+ * @public
2076
+ */
2077
+ declare interface IAiStreamToolUseStart {
2078
+ readonly type: 'client-tool-call-start';
2079
+ /** The name of the client tool being called. */
2080
+ readonly toolName: string;
2081
+ /**
2082
+ * Provider-assigned call identifier (Anthropic: `toolu_*`; OpenAI: `call_*`).
2083
+ * Absent for Gemini (correlation by name).
2084
+ */
2085
+ readonly callId?: string;
2086
+ }
2087
+
1840
2088
  /**
1841
2089
  * Declares a tool as enabled/disabled in provider settings.
1842
2090
  * Tools are disabled by default — consuming apps must opt in explicitly.
@@ -1877,7 +2125,9 @@ declare interface IAiWebSearchToolConfig {
1877
2125
  */
1878
2126
  declare interface IAnthropicThinkingConfig {
1879
2127
  /**
1880
- * Anthropic effort level. Maps 1:1 to `output_config.effort` on the wire.
2128
+ * Anthropic effort level. The emit-site converts to `thinking.budget_tokens`
2129
+ * (the integer budget the Anthropic API requires). Mapping policy: low = 2048,
2130
+ * medium = 8192, high = 24000, max = 32000.
1881
2131
  * - 'low' | 'medium' | 'high': all thinking-capable models
1882
2132
  * - 'max': Opus 4.6 only
1883
2133
  */
@@ -2477,6 +2727,70 @@ declare interface IEncryptionResult {
2477
2727
  readonly encryptedData: Uint8Array;
2478
2728
  }
2479
2729
 
2730
+ /**
2731
+ * Parameters for {@link AiAssist.executeClientToolTurn}.
2732
+ * @public
2733
+ */
2734
+ declare interface IExecuteClientToolTurnParams {
2735
+ /** The provider descriptor for routing (Anthropic / OpenAI / Gemini). */
2736
+ readonly descriptor: IAiProviderDescriptor;
2737
+ /** API key for authentication. */
2738
+ readonly apiKey: string;
2739
+ /** The structured prompt. */
2740
+ readonly prompt: AiPrompt;
2741
+ /** Prior conversation history (excluding the current turn). */
2742
+ readonly messagesBefore?: ReadonlyArray<IChatMessage>;
2743
+ /**
2744
+ * Provider-specific continuation messages to append after the prompt's user
2745
+ * message. Used to supply the output of {@link AiAssist.IAiClientToolContinuation}'s
2746
+ * `messages` field from a prior turn back to the provider in the follow-up request.
2747
+ *
2748
+ * Each provider applies its own shape guard to the supplied wire objects:
2749
+ * - Anthropic: projects each entry to `{ role, content }` (sufficient for
2750
+ * thinking blocks and `tool_result` arrays).
2751
+ * - OpenAI / xAI Responses: passes each item verbatim (`function_call` /
2752
+ * `function_call_output` items carry distinct fields per `type`); only guards
2753
+ * that each entry is a JSON object.
2754
+ * - Gemini: projects each entry to `{ role, parts }`.
2755
+ *
2756
+ * Entries that fail their provider's shape check are silently skipped.
2757
+ */
2758
+ readonly continuationMessages?: ReadonlyArray<JsonObject>;
2759
+ /** Temperature (default: 0.7). */
2760
+ readonly temperature?: number;
2761
+ /** Server-side tools to include. */
2762
+ readonly tools?: ReadonlyArray<AiServerToolConfig>;
2763
+ /** Client-defined tools available for the model to call. */
2764
+ readonly clientTools: ReadonlyArray<IAiClientTool>;
2765
+ /** Optional abort signal. */
2766
+ readonly signal?: AbortSignal;
2767
+ /** Optional logger for diagnostics. */
2768
+ readonly logger?: Logging.ILogger;
2769
+ /** Optional resolved thinking config (pre-resolved by the caller). */
2770
+ readonly resolvedThinking?: IResolvedThinkingConfig;
2771
+ /** Resolved model string (pre-resolved by the caller). When omitted, uses the descriptor's default model. */
2772
+ readonly model?: string;
2773
+ }
2774
+
2775
+ /**
2776
+ * Return value of {@link AiAssist.executeClientToolTurn}.
2777
+ * @public
2778
+ */
2779
+ declare interface IExecuteClientToolTurnResult {
2780
+ /**
2781
+ * The unified-event iterable. Callers iterate this to drive the streaming UI.
2782
+ * The iterable forwards `text-delta`, `tool-event`, `client-tool-call-start`,
2783
+ * `client-tool-call-done`, and `client-tool-result` events through.
2784
+ */
2785
+ readonly events: AsyncIterable<IAiStreamEvent>;
2786
+ /**
2787
+ * Resolves when the stream terminates. On success, carries the
2788
+ * {@link AiAssist.IAiClientToolTurnResult} with the optional continuation for the
2789
+ * next round. On failure, carries the error message.
2790
+ */
2791
+ readonly nextTurn: Promise<Result<IAiClientToolTurnResult>>;
2792
+ }
2793
+
2480
2794
  /**
2481
2795
  * Options shared by every {@link AiAssist.fencedStringifiedJson} call.
2482
2796
  * @public
@@ -3481,6 +3795,28 @@ declare interface IResolvedImageOptions {
3481
3795
  readonly otherParams?: JsonObject;
3482
3796
  }
3483
3797
 
3798
+ /**
3799
+ * Resolved thinking wire parameters for a specific provider, after merging
3800
+ * all applicable config blocks. Ready for provider-specific wire encoding.
3801
+ *
3802
+ * Callers that pre-resolve thinking config outside of the standard streaming
3803
+ * helpers (e.g. `executeClientToolTurn`) accept this type via the
3804
+ * `resolvedThinking` parameter and pass it directly to the adapter layer.
3805
+ * @public
3806
+ */
3807
+ declare interface IResolvedThinkingConfig {
3808
+ /** Anthropic: effort level; emit-site converts to `thinking.budget_tokens` via `anthropicEffortToBudgetTokens`. */
3809
+ readonly anthropicEffort?: IAnthropicThinkingConfig['effort'];
3810
+ /** OpenAI Chat: reasoning_effort value; OpenAI Responses: reasoning.effort */
3811
+ readonly openAiEffort?: IOpenAiThinkingConfig['effort'];
3812
+ /** Gemini: generationConfig.thinkingConfig.thinkingBudget */
3813
+ readonly geminiThinkingBudget?: number;
3814
+ /** xAI: reasoning_effort value (omit for grok-4) */
3815
+ readonly xaiEffort?: IXAiThinkingConfig['effort'];
3816
+ /** Other/passthrough: merged verbatim into wire request */
3817
+ readonly otherParams?: JsonObject;
3818
+ }
3819
+
3484
3820
  /**
3485
3821
  * Checks if a JSON object appears to be an encrypted file.
3486
3822
  * Uses the format field as a discriminator.
@@ -1 +1 @@
1
- {"version":3,"file":"apiClient.d.ts","sourceRoot":"","sources":["../../../src/packlets/ai-assist/apiClient.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"apiClient.d.ts","sourceRoot":"","sources":["../../../src/packlets/ai-assist/apiClient.ts"],"names":[],"mappings":"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"}
@@ -388,9 +388,9 @@ async function callAnthropicCompletion(config, prompt, additionalMessages, tempe
388
388
  const url = `${config.baseUrl}/messages`;
389
389
  const messages = (0, chatRequestBuilders_1.buildAnthropicMessages)(prompt, { tail: additionalMessages });
390
390
  const body = Object.assign({ model: config.model, system: prompt.system, messages, max_tokens: 4096 }, ((resolvedThinking === null || resolvedThinking === void 0 ? void 0 : resolvedThinking.anthropicEffort) === undefined ? { temperature } : {}));
391
- if ((resolvedThinking === null || resolvedThinking === void 0 ? void 0 : resolvedThinking.anthropicEffort) !== undefined) {
392
- body.thinking = { type: 'enabled' };
393
- body.output_config = { effort: resolvedThinking.anthropicEffort };
391
+ const effort = resolvedThinking === null || resolvedThinking === void 0 ? void 0 : resolvedThinking.anthropicEffort;
392
+ if (effort !== undefined) {
393
+ body.thinking = { type: 'enabled', budget_tokens: (0, thinkingOptionsResolver_1.anthropicEffortToBudgetTokens)(effort) };
394
394
  }
395
395
  if ((resolvedThinking === null || resolvedThinking === void 0 ? void 0 : resolvedThinking.otherParams) !== undefined) {
396
396
  Object.assign(body, resolvedThinking.otherParams);