@genesislcap/ai-assistant 15.11.0 → 15.12.0

package/dist/ai-assistant.api.json

@@ -17859,6 +17859,74 @@
                 "endIndex": 6
               }
             },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/ai-assistant!StatefulAgentInit#thinkingPolicy:member",
+              "docComment": "/**\n * Extended-thinking posture. Either a static `ChatThinkingPolicy` or a function resolved with the current `state` **once per user turn** — the function form is the point of this option on a machine agent: `'auto'` in the state that makes a real decision, `'off'` in the states that only step a known sequence, where reasoning is billed at the full output rate to re-derive what the machine already knows. Omit, or return `undefined` from the function, to keep the model's own default for that turn.\n *\n * Resolved once per turn rather than per tool-loop iteration (unlike `temperature` and `toolChoice`): a tool-use loop is one assistant turn and its thinking mode must hold for the whole of it. A state transition part-way through a loop therefore takes effect on the next user turn, not immediately.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "thinkingPolicy?: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "ChatThinkingPolicy",
+                  "canonicalReference": "@genesislcap/foundation-ai!ChatThinkingPolicy:type"
+                },
+                {
+                  "kind": "Content",
+                  "text": " | ((ctx: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "StatefulAgentContext",
+                  "canonicalReference": "@genesislcap/ai-assistant!StatefulAgentContext:type"
+                },
+                {
+                  "kind": "Content",
+                  "text": "<S>) => "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "ChatThinkingPolicy",
+                  "canonicalReference": "@genesislcap/foundation-ai!ChatThinkingPolicy:type"
+                },
+                {
+                  "kind": "Content",
+                  "text": " | undefined | "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "Promise",
+                  "canonicalReference": "!Promise:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": "<"
+                },
+                {
+                  "kind": "Reference",
+                  "text": "ChatThinkingPolicy",
+                  "canonicalReference": "@genesislcap/foundation-ai!ChatThinkingPolicy:type"
+                },
+                {
+                  "kind": "Content",
+                  "text": " | undefined>)"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "thinkingPolicy",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 11
+              }
+            },
             {
               "kind": "PropertySignature",
               "canonicalReference": "@genesislcap/ai-assistant!StatefulAgentInit#toolChoice:member",
@@ -18500,6 +18568,73 @@
             "endIndex": 6
           }
         },
+        {
+          "kind": "TypeAlias",
+          "canonicalReference": "@genesislcap/ai-assistant!ThinkingPolicyInput:type",
+          "docComment": "/**\n * Extended-thinking posture for an agent — whether the model reasons before answering. Either a static `ChatThinkingPolicy` or a function resolved **once per user turn**, at the start of the tool loop. Pick the function form to vary it by current state: reason in the state that makes a real decision, and drop it in states that only step a known sequence, where reasoning bills at the full output rate to re-derive what the state machine already knows.\n *\n * Note the resolution point, which differs from every other per-turn input here: a tool-use loop is a single assistant turn and its thinking mode must hold for the whole of it, so this resolver is consulted on the first model call of a turn and its answer reused for the rest. A resolver that returns a different value part-way through a loop will not see it applied until the next user turn.\n *\n * **Omit — or return `undefined` from the function — to keep the model's own default**, which is a distinct third state rather than a synonym for either value: Sonnet 5 and Fable 5 think by default, the rest do not. So an agent that leaves this unset, or a resolver that answers `undefined` on some turns, behaves and prices exactly as it did before this option existed.\n *\n * A request, not a guarantee — transports clamp what a model cannot honour (Fable 5 and Gemini 2.5 Pro always think) and warn once instead of failing the turn. Resolved and applied the same way as {@link TemperatureInput}. See `ChatThinkingPolicy`.\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export type ThinkingPolicyInput = "
+            },
+            {
+              "kind": "Reference",
+              "text": "ChatThinkingPolicy",
+              "canonicalReference": "@genesislcap/foundation-ai!ChatThinkingPolicy:type"
+            },
+            {
+              "kind": "Content",
+              "text": " | ((ctx: "
+            },
+            {
+              "kind": "Reference",
+              "text": "SystemPromptContext",
+              "canonicalReference": "@genesislcap/ai-assistant!SystemPromptContext:interface"
+            },
+            {
+              "kind": "Content",
+              "text": ") => "
+            },
+            {
+              "kind": "Reference",
+              "text": "ChatThinkingPolicy",
+              "canonicalReference": "@genesislcap/foundation-ai!ChatThinkingPolicy:type"
+            },
+            {
+              "kind": "Content",
+              "text": " | undefined | "
+            },
+            {
+              "kind": "Reference",
+              "text": "Promise",
+              "canonicalReference": "!Promise:interface"
+            },
+            {
+              "kind": "Content",
+              "text": "<"
+            },
+            {
+              "kind": "Reference",
+              "text": "ChatThinkingPolicy",
+              "canonicalReference": "@genesislcap/foundation-ai!ChatThinkingPolicy:type"
+            },
+            {
+              "kind": "Content",
+              "text": " | undefined>)"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/config/config.ts",
+          "releaseTag": "Beta",
+          "name": "ThinkingPolicyInput",
+          "typeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 11
+          }
+        },
         {
           "kind": "TypeAlias",
           "canonicalReference": "@genesislcap/ai-assistant!TimelineMessage:type",

package/dist/ai-assistant.d.ts

@@ -11,6 +11,7 @@ import type { ChatDriverResult } from '@genesislcap/foundation-ai';
 import type { ChatFallback } from '@genesislcap/foundation-ai';
 import type { ChatInputDuringExecutionMode } from '@genesislcap/foundation-ai';
 import type { ChatMessage } from '@genesislcap/foundation-ai';
+import type { ChatThinkingPolicy } from '@genesislcap/foundation-ai';
 import type { ChatToolChoice } from '@genesislcap/foundation-ai';
 import type { ChatToolDefinition } from '@genesislcap/foundation-ai';
 import type { ChatToolHandlers } from '@genesislcap/foundation-ai';
@@ -969,6 +970,18 @@ declare interface BaseAgentConfig {
      * @beta
      */
     cachePolicy?: CachePolicyInput;
+    /**
+     * Extended-thinking posture for this agent — whether the model reasons before answering. Either
+     * a static value or a function resolved **once per user turn** and held for that turn's whole
+     * tool loop (vary by state: `'auto'` where the turn is a genuine decision, `'off'` where it only
+     * steps a known sequence and reasoning is billed at the full output rate for no benefit). Omit —
+     * or return `undefined` — to keep the model's own default, which is neither `'auto'` nor `'off'`
+     * uniformly. Provider-neutral; transports clamp models that cannot honour it.
+     * See {@link ThinkingPolicyInput}.
+     *
+     * @beta
+     */
+    thinkingPolicy?: ThinkingPolicyInput;
     /**
      * Volatile per-turn context injected at the tail of every model-call (after the history and any
      * cache breakpoint), so it is seen each turn without busting the cached prefix — the place to put
@@ -1425,6 +1438,12 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * `undefined` requests no caching (equivalent to `{ scope: 'default' }`).
      */
     private activeCachePolicyInput?;
+    /**
+     * Active agent's extended-thinking selector (static value or per-turn resolver). `undefined` —
+     * unset, or returned by the resolver — leaves the model on its own default posture, which is
+     * neither uniformly on nor off, so an agent that never sets this is unaffected by the option.
+     */
+    private activeThinkingPolicyInput?;
     /**
      * Active agent's tail-context selector (static value or per-turn resolver). The driver frames
      * the resolved string in a `<system-reminder>` marker and injects it at the message tail.
@@ -1826,9 +1845,20 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      *   `condenseWhen` can register against the right call (it stamps the clocks
      *   straight off the driver). Absent for dispatch paths with no addressable tool
      *   call (e.g. the fold-close handler), where `condenseWhen` is a no-op.
-     * @param traceCapture - Optional per-invocation slot. When provided, the trace
-     *   from any sub-agent call is written here rather than to shared instance state,
-     *   so parallel tool calls each capture their own trace independently.
+     * @param traceCapture - Optional per-tool-call accumulator. When provided, every
+     *   sub-agent call's trace is **appended** here rather than written to shared
+     *   instance state, so parallel tool calls each capture their own traces
+     *   independently.
+     *
+     *   Deliberately a list of traces, not one slot. A single handler may call
+     *   `requestSubAgent` more than once — a code-driven scheduler dispatching a
+     *   dependency graph, a retry of a timed-out child, any fan-out helper — and a
+     *   single slot kept only the last, so every other child ran, was billed by the
+     *   provider, and then vanished from history. The loss was silent in the worst
+     *   way: `sumUsage` and `usageRows` both recurse into the trace, so they summed a
+     *   truncated input and still agreed with each other. Measured at 1 of 7 traces
+     *   kept on a seven-way fan-out, reporting ~2.3x under the real cost, with the
+     *   error growing as the fan-out widens.
      */
     private buildHandlerContext;
     /**
@@ -1968,6 +1998,8 @@ declare type ChatInteractionEventsMap = {
     };
 };
 
+export { ChatThinkingPolicy }
+
 export { ChatToolChoice }
 
 /**
@@ -4714,6 +4746,20 @@ export declare interface StatefulAgentInit<S> {
      * request no caching.
      */
     cachePolicy?: CachePolicy | ((ctx: StatefulAgentContext<S>) => CachePolicy | Promise<CachePolicy>);
+    /**
+     * Extended-thinking posture. Either a static `ChatThinkingPolicy` or a function resolved with
+     * the current `state` **once per user turn** — the function form is the point of this option on
+     * a machine agent: `'auto'` in the state that makes a real decision, `'off'` in the states that
+     * only step a known sequence, where reasoning is billed at the full output rate to re-derive
+     * what the machine already knows. Omit, or return `undefined` from the function, to keep the
+     * model's own default for that turn.
+     *
+     * Resolved once per turn rather than per tool-loop iteration (unlike `temperature` and
+     * `toolChoice`): a tool-use loop is one assistant turn and its thinking mode must hold for the
+     * whole of it. A state transition part-way through a loop therefore takes effect on the next
+     * user turn, not immediately.
+     */
+    thinkingPolicy?: ChatThinkingPolicy | ((ctx: StatefulAgentContext<S>) => ChatThinkingPolicy | undefined | Promise<ChatThinkingPolicy | undefined>);
     /**
      * Volatile per-turn tail context (current file/spec, diagnostics, live state). Either a static
      * string or a function resolved each tool-loop iteration with the current `state`. Provide raw
@@ -4876,6 +4922,32 @@ export declare type TailContextInput = string | ((ctx: SystemPromptContext) => s
  */
 export declare type TemperatureInput = number | ((ctx: SystemPromptContext) => number | Promise<number>);
 
+/**
+ * Extended-thinking posture for an agent — whether the model reasons before answering. Either a
+ * static `ChatThinkingPolicy` or a function resolved **once per user turn**, at the start of the
+ * tool loop. Pick the function form to vary it by current state: reason in the state that makes a
+ * real decision, and drop it in states that only step a known sequence, where reasoning bills at
+ * the full output rate to re-derive what the state machine already knows.
+ *
+ * Note the resolution point, which differs from every other per-turn input here: a tool-use loop
+ * is a single assistant turn and its thinking mode must hold for the whole of it, so this resolver
+ * is consulted on the first model call of a turn and its answer reused for the rest. A resolver
+ * that returns a different value part-way through a loop will not see it applied until the next
+ * user turn.
+ *
+ * **Omit — or return `undefined` from the function — to keep the model's own default**, which is
+ * a distinct third state rather than a synonym for either value: Sonnet 5 and Fable 5 think by
+ * default, the rest do not. So an agent that leaves this unset, or a resolver that answers
+ * `undefined` on some turns, behaves and prices exactly as it did before this option existed.
+ *
+ * A request, not a guarantee — transports clamp what a model cannot honour (Fable 5 and Gemini
+ * 2.5 Pro always think) and warn once instead of failing the turn. Resolved and applied the same
+ * way as {@link TemperatureInput}. See `ChatThinkingPolicy`.
+ *
+ * @beta
+ */
+export declare type ThinkingPolicyInput = ChatThinkingPolicy | ((ctx: SystemPromptContext) => ChatThinkingPolicy | undefined | Promise<ChatThinkingPolicy | undefined>);
+
 /**
  * A chat message lifted into the debug-log timeline as a `kind: 'message'` entry.
  *