llmz 0.1.5 → 0.2.1

package/dist/{chunk-ZPHRTTQX.cjs → chunk-YQT5G77W.cjs}

@@ -142,6 +142,7 @@ var _MessageContentParser = (_class = class {
 }, _class);
 var _createRegex = () => new RegExp(REGEXP, "g");
 var _renderRemainingWrappers = (content) => content.replace(_createRegex(), "$2");
+var stripTruncationTags = (content) => _renderRemainingWrappers(content);
 var _countTotalTokens = (parts) => parts.reduce((acc, x) => acc + x.reduce((acc2, y) => acc2 + y.tokens, 0), 0);
 var _getTwoBiggestTruncables = (parts) => {
   var _a, _b;
@@ -168,4 +169,5 @@ var _getTwoBiggestTruncables = (parts) => {
 
 
 
-exports.wrapContent = wrapContent; exports.truncateWrappedContent = truncateWrappedContent;
+
+exports.wrapContent = wrapContent; exports.truncateWrappedContent = truncateWrappedContent; exports.stripTruncationTags = stripTruncationTags;

package/dist/{chunk-TIZWOIDF.js → chunk-ZWUWCRHG.js}

@@ -2,10 +2,10 @@ import {
   DualModePrompt,
   extractType,
   inspect
-} from "./chunk-2O3UTPVH.js";
+} from "./chunk-E5NHK3FS.js";
 import {
   Tool
-} from "./chunk-IRCB4FRM.js";
+} from "./chunk-GC5IQDGV.js";
 import {
   LoopExceededError
 } from "./chunk-WSVDMGMR.js";
@@ -14,10 +14,14 @@ import {
 } from "./chunk-XVVYNOTX.js";
 import {
   assertValidComponent
-} from "./chunk-3T5IU7OU.js";
+} from "./chunk-KWQTYXAT.js";
 import {
+  stripTruncationTags,
   wrapContent
-} from "./chunk-L74UZONX.js";
+} from "./chunk-HM5H556L.js";
+import {
+  getTokenizer
+} from "./chunk-YX27XM67.js";
 import {
   cloneDeep_default,
   isPlainObject_default,
@@ -777,6 +781,33 @@ var ExecutionResult = class {
   get iterations() {
     return this.context.iterations ?? [];
   }
+  /**
+   * Gets the total token usage of the execution, aggregated across all iterations.
+   *
+   * `input`/`output` are the provider-reported token counts of every LLM call made
+   * during the execution. Per-iteration detail (including the measured context size
+   * breakdown by prompt part) is available on each iteration's `tokens` property.
+   *
+   * @example
+   * ```typescript
+   * const result = await execute({ ... })
+   * console.log(`Execution used ${result.tokens.total} tokens`)
+   *
+   * for (const iteration of result.iterations) {
+   *   console.log(iteration.id, iteration.tokens?.context)
+   * }
+   * ```
+   */
+  get tokens() {
+    var _a, _b;
+    let input = 0;
+    let output = 0;
+    for (const iteration of this.iterations) {
+      input += ((_a = iteration.tokens) == null ? void 0 : _a.input) ?? 0;
+      output += ((_b = iteration.tokens) == null ? void 0 : _b.output) ?? 0;
+    }
+    return { input, output, total: input + output };
+  }
 };
 var SuccessExecutionResult = class extends ExecutionResult {
   result;
@@ -959,8 +990,18 @@ var Iteration = class {
   id;
   messages;
   code;
+  /** Messages (`■send` blocks) parsed from the assistant response, in order. */
+  sends;
+  /** The `■next` exit parsed from the assistant response, if any. */
+  next;
   traces;
   variables;
+  /**
+   * Token usage of this iteration's LLM call. The `context` breakdown is measured
+   * when the prompt is assembled; `input`/`output` are filled in once the LLM call
+   * completes, from the provider-reported usage.
+   */
+  tokens;
   started_ts;
   ended_ts;
   status;
@@ -994,7 +1035,7 @@ var Iteration = class {
     return this._parameters.reasoningEffort;
   }
   get exits() {
-    const exits = [...this._parameters.exits, ThinkExit];
+    const exits = [...this._parameters.exits];
     if (this.isChatEnabled) {
       exits.push(ListenExit);
     }
@@ -1048,7 +1089,7 @@ var Iteration = class {
     return null;
   }
   get isChatEnabled() {
-    return this._parameters.tools.find((x) => x.name.toLowerCase() === "message") !== void 0;
+    return this._parameters.components.length > 0;
   }
   constructor(props) {
     this.id = props.id;
@@ -1082,6 +1123,7 @@ var Iteration = class {
       status: this.status,
       mutations: [...this._mutations.values()],
       llm: this.llm,
+      tokens: this.tokens,
       transcript: [...this._parameters.transcript],
       tools: this._parameters.tools.map((tool) => tool.toJSON()),
       objects: this._parameters.objects.map((obj) => obj.toJSON()),
@@ -1107,6 +1149,16 @@ var Context = class {
   timeout = 6e4;
   // Default timeout of 60 seconds
   loop;
+  /**
+   * Optional cap on the model's context window. The effective limit is
+   * `min(maxTokens, model's max input tokens)`.
+   */
+  maxTokens;
+  /**
+   * Maximum time to wait for the first streamed token, in milliseconds,
+   * before the cognitive service falls back to the next model/provider.
+   */
+  maxTimeToFirstToken;
   metadata;
   snapshot;
   iteration = 0;
@@ -1121,13 +1173,15 @@ var Context = class {
       );
     }
     const parameters = await this._refreshIterationParameters();
-    const messages = await this._getIterationMessages(parameters);
+    const { messages, parts } = await this._getIterationMessages(parameters);
+    const contextTokens = this._measureContextTokens(messages, parts);
     const iteration = new Iteration({
       id: `${this.id}_${this.iterations.length + 1}`,
       variables: this._getIterationVariables(),
       parameters,
       messages
     });
+    iteration.tokens = { input: 0, output: 0, total: 0, context: contextTokens };
     this.iterations.push(iteration);
     this.iteration = this.iterations.length;
     this.snapshot = void 0;
@@ -1155,72 +1209,80 @@ var Context = class {
     }
     return variables;
   }
+  /**
+   * Measures the token size of each part of the prompt (pre-truncation).
+   * The named parts come from the system prompt; everything else in the system
+   * message is `framework`. Non-system messages count towards `iterations`,
+   * except the very first user message of a fresh execution (task recap),
+   * which is prompt scaffolding.
+   */
+  _measureContextTokens(messages, parts) {
+    const tokenizer = getTokenizer();
+    const countText = (text) => (text == null ? void 0 : text.length) ? tokenizer.count(stripTruncationTags(text)) : 0;
+    const countMessage = (message) => {
+      if (typeof message.content === "string") {
+        return countText(message.content);
+      }
+      if (Array.isArray(message.content)) {
+        return message.content.reduce((acc, part) => acc + (part.type === "text" ? countText(part.text) : 0), 0);
+      }
+      return 0;
+    };
+    const instructions = countText(parts.instructions);
+    const tools = countText(parts.tools);
+    const transcript = countText(parts.transcript);
+    const protocol = countText(parts.protocol);
+    const systemTokens = messages.filter((x) => x.role === "system").reduce((acc, x) => acc + countMessage(x), 0);
+    const otherTokens = messages.filter((x) => x.role !== "system").reduce((acc, x) => acc + countMessage(x), 0);
+    const isFirstIteration = this.iterations.length === 0 && !this.snapshot;
+    const framework = Math.max(0, systemTokens - (instructions + tools + transcript + protocol));
+    const iterations = isFirstIteration ? 0 : otherTokens;
+    return {
+      total: framework + instructions + tools + transcript + protocol + iterations + (isFirstIteration ? otherTokens : 0),
+      framework: framework + (isFirstIteration ? otherTokens : 0),
+      instructions,
+      tools,
+      transcript,
+      protocol,
+      iterations
+    };
+  }
   async _getIterationMessages(parameters) {
     var _a, _b, _c, _d, _e, _f;
     const lastIteration = this.iterations.at(-1);
+    const promptProps = {
+      globalTools: parameters.tools,
+      objects: parameters.objects,
+      instructions: parameters.instructions,
+      transcript: parameters.transcript,
+      // ListenExit is protocol-level in chat mode: it must be documented alongside user-defined exits
+      exits: parameters.components.length ? [...parameters.exits, ListenExit] : parameters.exits,
+      components: parameters.components
+    };
+    const { message: systemMessage, parts } = await this.version.getSystemMessage(promptProps);
+    const withParts = (messages) => ({ messages, parts });
     if (((_a = this.snapshot) == null ? void 0 : _a.status.type) === "resolved") {
-      return [
-        await this.version.getSystemMessage({
-          globalTools: parameters.tools,
-          objects: parameters.objects,
-          instructions: parameters.instructions,
-          transcript: parameters.transcript,
-          exits: parameters.exits,
-          components: parameters.components
-        }),
+      return withParts([
+        systemMessage,
         this.version.getSnapshotResolvedMessage({
           snapshot: this.snapshot
         })
-      ];
+      ]);
     }
     if (((_b = this.snapshot) == null ? void 0 : _b.status.type) === "rejected") {
-      return [
-        await this.version.getSystemMessage({
-          globalTools: parameters.tools,
-          objects: parameters.objects,
-          instructions: parameters.instructions,
-          transcript: parameters.transcript,
-          exits: parameters.exits,
-          components: parameters.components
-        }),
+      return withParts([
+        systemMessage,
         this.version.getSnapshotRejectedMessage({
           snapshot: this.snapshot
         })
-      ];
+      ]);
     }
     if (!lastIteration) {
-      return [
-        await this.version.getSystemMessage({
-          globalTools: parameters.tools,
-          objects: parameters.objects,
-          instructions: parameters.instructions,
-          transcript: parameters.transcript,
-          exits: parameters.exits,
-          components: parameters.components
-        }),
-        await this.version.getInitialUserMessage({
-          globalTools: parameters.tools,
-          objects: parameters.objects,
-          instructions: parameters.instructions,
-          transcript: parameters.transcript,
-          exits: parameters.exits,
-          components: parameters.components
-        })
-      ];
+      return withParts([systemMessage, await this.version.getInitialUserMessage(promptProps)]);
     }
-    const lastIterationMessages = [
-      await this.version.getSystemMessage({
-        globalTools: parameters.tools,
-        objects: parameters.objects,
-        instructions: parameters.instructions,
-        transcript: parameters.transcript,
-        exits: parameters.exits,
-        components: parameters.components
-      }),
-      ...lastIteration.messages.filter((x) => x.role !== "system")
-    ];
+    const lastIterationMessages = [systemMessage, ...lastIteration.messages.filter((x) => x.role !== "system")];
     if ((lastIteration == null ? void 0 : lastIteration.status.type) === "thinking_requested") {
-      return [
+      return withParts([
         ...lastIterationMessages,
         {
           role: "assistant",
@@ -1230,10 +1292,10 @@ var Context = class {
           reason: lastIteration.status.thinking_requested.reason,
           variables: lastIteration.status.thinking_requested.variables
         })
-      ];
+      ]);
     }
     if ((lastIteration == null ? void 0 : lastIteration.status.type) === "exit_error") {
-      return [
+      return withParts([
         ...lastIterationMessages,
         {
           role: "assistant",
@@ -1243,10 +1305,10 @@ var Context = class {
           code: lastIteration.code ?? "// No code generated",
           message: `Invalid return statement (action: ${lastIteration.status.exit_error.exit}): ${lastIteration.status.exit_error.message}`
         })
-      ];
+      ]);
     }
     if ((lastIteration == null ? void 0 : lastIteration.status.type) === "invalid_code_error") {
-      return [
+      return withParts([
         ...lastIterationMessages,
         {
           role: "assistant",
@@ -1256,10 +1318,10 @@ var Context = class {
           code: lastIteration.code ?? "// No code generated",
           message: lastIteration.status.invalid_code_error.message
         })
-      ];
+      ]);
     }
     if ((lastIteration == null ? void 0 : lastIteration.status.type) === "execution_error") {
-      return [
+      return withParts([
         ...lastIterationMessages,
         {
           role: "assistant",
@@ -1269,7 +1331,7 @@ var Context = class {
           message: lastIteration.status.execution_error.message,
           stacktrace: lastIteration.status.execution_error.stack
         })
-      ];
+      ]);
     }
     throw new Error(
       `Unexpected iteration status: ${lastIteration == null ? void 0 : lastIteration.status.type}. This is likely a bug, please report it.`
@@ -1312,18 +1374,6 @@ var Context = class {
       "boolean",
       "array"
     ];
-    const MessageTool = this.chat && components.length ? new Tool({
-      name: "Message",
-      description: "Send a message to the user",
-      aliases: Array.from(
-        /* @__PURE__ */ new Set(["message", ...components.flatMap((x) => [x.definition.name, ...x.definition.aliases ?? []])])
-      ),
-      handler: async (message) => {
-        var _a2, _b2;
-        return await ((_b2 = (_a2 = this.chat) == null ? void 0 : _a2.handler) == null ? void 0 : _b2.call(_a2, message));
-      }
-    }) : null;
-    const allTools = MessageTool ? [MessageTool, ...tools] : tools;
     for (const tool of tools) {
       for (let name of [...tool.aliases, tool.name]) {
         name = name.toLowerCase();
@@ -1380,7 +1430,7 @@ var Context = class {
     }
     return {
       transcript,
-      tools: allTools,
+      tools,
       objects,
       exits,
       instructions,
@@ -1405,9 +1455,17 @@ var Context = class {
     this.iterations = [];
     this.metadata = props.metadata ?? {};
     this.snapshot = props.snapshot;
+    this.maxTokens = props.maxTokens;
+    this.maxTimeToFirstToken = props.maxTimeToFirstToken;
     if (this.loop < 1 || this.loop > 100) {
       throw new Error("Invalid loop. Expected a number between 1 and 100.");
     }
+    if (this.maxTokens !== void 0 && (!Number.isFinite(this.maxTokens) || this.maxTokens < 1)) {
+      throw new Error("Invalid maxTokens. Expected a positive number.");
+    }
+    if (this.maxTimeToFirstToken !== void 0 && (!Number.isFinite(this.maxTimeToFirstToken) || this.maxTimeToFirstToken < 1)) {
+      throw new Error("Invalid maxTimeToFirstToken. Expected a positive number of milliseconds.");
+    }
   }
   toJSON() {
     var _a;

package/dist/compiler/compiler.d.ts

@@ -2,8 +2,6 @@ import { type TransformOptions } from '@babel/core';
 import { ToolCallEntry } from './plugins/track-tool-calls.js';
 export declare const DEFAULT_TRANSFORM_OPTIONS: TransformOptions;
 export declare const Identifiers: {
-    JSXFnIdentifier: string;
-    AsyncIterYieldFnIdentifier: string;
     ConsoleObjIdentifier: string;
     LineTrackingFnIdentifier: string;
     VariableTrackingFnIdentifier: string;
@@ -12,6 +10,13 @@ export declare const Identifiers: {
     CommentFnIdentifier: string;
 };
 export type CompiledCode = ReturnType<typeof compile>;
+/**
+ * Whether the code contains a top-level `return` statement (one that would
+ * return from the generated code itself, not from a nested function). Unlike a
+ * regex, this ignores `return` inside comments, strings and nested functions.
+ * Falls back to a word-boundary match if the code cannot be parsed.
+ */
+export declare function hasTopLevelReturn(code: string): boolean;
 export declare function compile(code: string): {
     code: string;
     codeWithMarkers: string;

package/dist/compiler/index.d.ts

@@ -1,2 +1,2 @@
-export { Identifiers, compile } from './compiler.js';
+export { Identifiers, compile, hasTopLevelReturn } from './compiler.js';
 export type { CompiledCode } from './compiler.js';

package/dist/compiler/plugins/async-wrapper.d.ts

@@ -0,0 +1,11 @@
+export declare const USER_CODE_START_MARKER = "/* __LLMZ_USER_CODE_START__ */";
+export declare const USER_CODE_END_MARKER = "/* __LLMZ_USER_CODE_END__ */";
+/**
+ * Wraps user code in an async function so top-level `await` and `return` parse,
+ * and so plugins can target the `__fn__` declaration. The wrapper is removed
+ * after transformation — drivers re-wrap the bare statements themselves.
+ */
+export declare const AsyncWrapper: {
+    preProcessing: (code: string) => string;
+    postProcessing: (code: string) => string;
+};

package/dist/component-2NYFY6CW.cjs

@@ -0,0 +1,14 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+
+
+
+var _chunkI56MPOVGcjs = require('./chunk-I56MPOVG.cjs');
+require('./chunk-5ZF6NTYI.cjs');
+require('./chunk-HC2QZTVT.cjs');
+
+
+
+
+
+exports.Component = _chunkI56MPOVGcjs.Component; exports.assertValidComponent = _chunkI56MPOVGcjs.assertValidComponent; exports.isAnyComponent = _chunkI56MPOVGcjs.isAnyComponent; exports.isComponent = _chunkI56MPOVGcjs.isComponent;

package/dist/{component-2Z3KLWLX.js → component-ASNZHQUR.js}

@@ -1,18 +1,14 @@
 import {
   Component,
   assertValidComponent,
-  getComponentReference,
   isAnyComponent,
-  isComponent,
-  renderToTsx
-} from "./chunk-3T5IU7OU.js";
+  isComponent
+} from "./chunk-KWQTYXAT.js";
 import "./chunk-XTEHT2TK.js";
 import "./chunk-34GJUS6U.js";
 export {
   Component,
   assertValidComponent,
-  getComponentReference,
   isAnyComponent,
-  isComponent,
-  renderToTsx
+  isComponent
 };

package/dist/component.d.ts

@@ -10,13 +10,12 @@ export type ComponentChild = {
     component: ComponentDefinition;
 };
 export declare function assertValidComponent(component: ComponentDefinition): asserts component is ComponentDefinition;
-export declare function getComponentReference(component: ComponentDefinition): string;
 export type DefaultComponentDefinition<T extends z.ZodObject<any> = z.ZodObject<any>> = {
     type: 'default';
     name: string;
     aliases: string[];
     description: string;
-    examples: ExampleUsage[];
+    examples?: ExampleUsage[];
     default: {
         props: T;
         children: Array<ComponentChild>;
@@ -27,7 +26,7 @@ export type LeafComponentDefinition<T extends z.ZodObject<any> = z.ZodObject<any
     name: string;
     description: string;
     aliases?: string[];
-    examples: ExampleUsage[];
+    examples?: ExampleUsage[];
     leaf: {
         props: T;
     };
@@ -37,7 +36,7 @@ export type ContainerComponentDefinition<T extends z.ZodObject<any> = z.ZodObjec
     name: string;
     description: string;
     aliases?: string[];
-    examples: ExampleUsage[];
+    examples?: ExampleUsage[];
     container: {
         props: T;
         children: Array<ComponentChild>;
@@ -54,10 +53,4 @@ export declare class Component<T extends ComponentDefinition = ComponentDefiniti
 }
 export declare function isComponent<T extends ComponentDefinition>(rendered: RenderedComponent<any>, component: Component<T>): rendered is RenderedComponent<ExtractComponentProps<T>>;
 export declare function isAnyComponent(message: unknown): message is RenderedComponent;
-/**
- * Converts a RenderedComponent back to TSX code
- * @param component The rendered component to convert
- * @returns A string containing the TSX representation of the component
- */
-export declare function renderToTsx(component: RenderedComponent): string;
 export {};

package/dist/context.d.ts

@@ -7,11 +7,49 @@ import { Exit } from './exit.js';
 import { ValueOrGetter } from './getter.js';
 import { HookedArray } from './handlers.js';
 import { ObjectInstance } from './objects.js';
-import { LLMzPrompts, Prompt } from './prompts/prompt.js';
+import { LLMzPrompts, ParsedNext, ParsedSend, Prompt } from './prompts/prompt.js';
 import { Snapshot } from './snapshots.js';
 import { Tool } from './tool.js';
 import { Transcript, TranscriptArray } from './transcript.js';
 import { ObjectMutation, Serializable, Trace } from './types.js';
+/**
+ * Tokenizer-measured size of each part of the prompt, before truncation.
+ * Useful to understand what is eating up the context window.
+ */
+export type ContextTokens = {
+    /** Total measured size of the prompt (sum of all the parts below). */
+    total: number;
+    /** Static prompt scaffolding: response format, VM rules, security guidelines, recap. */
+    framework: number;
+    /** The identity / instructions section. */
+    instructions: number;
+    /** tools.d.ts — tools, objects and variable typings. */
+    tools: number;
+    /** The conversation transcript. */
+    transcript: number;
+    /** The ■ protocol reference documenting components and exits. */
+    protocol: number;
+    /** Messages carried over from previous iterations (assistant responses, execution results, errors). */
+    iterations: number;
+};
+/** Token usage of a single iteration's LLM call. */
+export type TokenUsage = {
+    /** Input tokens consumed, as reported by the LLM provider. Zero until the call completes. */
+    input: number;
+    /** Output tokens produced, as reported by the LLM provider. Zero until the call completes. */
+    output: number;
+    /** Total tokens (input + output). */
+    total: number;
+    /**
+     * The effective context window limit of this call, in tokens:
+     * `min(options.maxTokens, model's max input tokens)`. Use it to compute the
+     * percentage of context used (e.g. `context.total / limit`).
+     * Undefined until the LLM call starts.
+     */
+    limit?: number;
+    /** Measured context size by part of the prompt (pre-truncation). */
+    context: ContextTokens;
+};
 export type IterationParameters = {
     transcript: TranscriptArray;
     tools: Tool[];
@@ -51,7 +89,8 @@ export declare namespace IterationStatuses {
         type: 'thinking_requested';
         thinking_requested: {
             reason?: string;
-            variables: Record<string, unknown>;
+            /** The value returned by the executed code (or the context provided by a ThinkSignal). */
+            variables: unknown;
             metadata?: Record<string, unknown>;
         };
     };
@@ -327,7 +366,10 @@ export declare namespace Iteration {
             spend: number;
             output: string;
             model: string;
+            time_to_first_token?: number;
+            time_to_last_token?: number;
         };
+        tokens?: TokenUsage;
         transcript: Transcript.Message[];
         tools: Tool.JSON[];
         objects: ObjectInstance.JSON[];
@@ -342,8 +384,18 @@ export declare class Iteration implements Serializable<Iteration.JSON> {
     id: string;
     messages: LLMzPrompts.Message[];
     code?: string;
+    /** Messages (`■send` blocks) parsed from the assistant response, in order. */
+    sends?: ParsedSend[];
+    /** The `■next` exit parsed from the assistant response, if any. */
+    next?: ParsedNext;
     traces: HookedArray<Trace>;
     variables: Record<string, any>;
+    /**
+     * Token usage of this iteration's LLM call. The `context` breakdown is measured
+     * when the prompt is assembled; `input`/`output` are filled in once the LLM call
+     * completes, from the provider-reported usage.
+     */
+    tokens?: TokenUsage;
     started_ts: number;
     ended_ts?: number;
     status: IterationStatus;
@@ -369,6 +421,10 @@ export declare class Iteration implements Serializable<Iteration.JSON> {
         spend: number;
         output: string;
         model: string;
+        /** Milliseconds between the LLM call start and the first streamed token. Only set on streaming clients. */
+        time_to_first_token?: number;
+        /** Milliseconds between the LLM call start and the last streamed token. Only set on streaming clients. */
+        time_to_last_token?: number;
         usage: {
             inputCost: number;
             outputCost: number;
@@ -420,6 +476,10 @@ export declare class Iteration implements Serializable<Iteration.JSON> {
             spend: number;
             output: string;
             model: string;
+            /** Milliseconds between the LLM call start and the first streamed token. Only set on streaming clients. */
+            time_to_first_token?: number;
+            /** Milliseconds between the LLM call start and the last streamed token. Only set on streaming clients. */
+            time_to_last_token?: number;
             usage: {
                 inputCost: number;
                 outputCost: number;
@@ -427,6 +487,7 @@ export declare class Iteration implements Serializable<Iteration.JSON> {
                 outputTokens: number;
             };
         } | undefined;
+        tokens: TokenUsage | undefined;
         transcript: Transcript.Message[];
         tools: {
             name: string;
@@ -493,12 +554,30 @@ export declare class Context implements Serializable<Context.JSON> {
     version: Prompt;
     timeout: number;
     loop: number;
+    /**
+     * Optional cap on the model's context window. The effective limit is
+     * `min(maxTokens, model's max input tokens)`.
+     */
+    maxTokens?: number;
+    /**
+     * Maximum time to wait for the first streamed token, in milliseconds,
+     * before the cognitive service falls back to the next model/provider.
+     */
+    maxTimeToFirstToken?: number;
     metadata: Record<string, any>;
     snapshot?: Snapshot;
     iteration: number;
     iterations: Iteration[];
     nextIteration(): Promise<Iteration>;
     private _getIterationVariables;
+    /**
+     * Measures the token size of each part of the prompt (pre-truncation).
+     * The named parts come from the system prompt; everything else in the system
+     * message is `framework`. Non-system messages count towards `iterations`,
+     * except the very first user message of a fresh execution (task recap),
+     * which is prompt scaffolding.
+     */
+    private _measureContextTokens;
     private _getIterationMessages;
     private _refreshIterationParameters;
     constructor(props: {
@@ -514,6 +593,8 @@ export declare class Context implements Serializable<Context.JSON> {
         metadata?: Record<string, any>;
         snapshot?: Snapshot;
         timeout?: number;
+        maxTokens?: number;
+        maxTimeToFirstToken?: number;
     });
     toJSON(): {
         id: string;
@@ -539,6 +620,10 @@ export declare class Context implements Serializable<Context.JSON> {
                 spend: number;
                 output: string;
                 model: string;
+                /** Milliseconds between the LLM call start and the first streamed token. Only set on streaming clients. */
+                time_to_first_token?: number;
+                /** Milliseconds between the LLM call start and the last streamed token. Only set on streaming clients. */
+                time_to_last_token?: number;
                 usage: {
                     inputCost: number;
                     outputCost: number;
@@ -546,6 +631,7 @@ export declare class Context implements Serializable<Context.JSON> {
                     outputTokens: number;
                 };
             } | undefined;
+            tokens: TokenUsage | undefined;
             transcript: Transcript.Message[];
             tools: {
                 name: string;