@framers/agentos 0.12.13 → 0.12.14

package/dist/api/runtime/gmiPersona.js

@@ -0,0 +1,91 @@
+/**
+ * @file gmiPersona.ts
+ * The persona of a GMI built from agent options (`agent({ runtime: 'gmi' })`).
+ *
+ * The base system prompt is the text the legacy path sends: `buildSystemPrompt(opts)`
+ * (or the joined `systemBlocks`), with the chain-of-thought instruction first when
+ * the agent has tools, as `generateText` puts it. The completion options are the
+ * ones `agent()` forwards on every call. Sentiment presets are expanded into
+ * metaprompts, as the persona loaders expand them, because the GMI runs only the
+ * persona's `metaPrompts`.
+ */
+import { createHash, randomUUID } from 'node:crypto';
+import { buildSystemPrompt } from '../agent.js';
+import { resolveChainOfThought } from '../generateText.js';
+import { resolveModelOption } from '../model.js';
+import { normalizeHexacoTraits } from '../../cognition/substrate/personas/hexaco.js';
+import { normalizePersonaDefinition } from '../../cognition/substrate/personas/personaNormalization.js';
+/** The session store bounds history (spec D10), so the GMI's own count window stays out of the way. */
+export const GMI_SESSION_MAX_HISTORY_MESSAGES = 100000;
+/**
+ * A stable persona id from the agent's name: a lowercase ASCII slug, or, for a
+ * name with no Latin letters or digits, `agent-` and a hash of the name.
+ */
+function personaIdFor(name) {
+    const slug = name
+        .normalize('NFKD')
+        .replace(/[̀-ͯ]/g, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    return slug || `agent-${createHash('sha256').update(name).digest('hex').slice(0, 12)}`;
+}
+/** The completion options `agent()` forwards on every call (its `baseOpts`), unset ones left out. */
+function completionOptionsOf(opts) {
+    const out = {};
+    const maxTokens = opts.maxTokens ?? opts.controls?.maxTotalTokens;
+    if (maxTokens !== undefined)
+        out.maxTokens = maxTokens;
+    if (opts.controls?.maxDurationMs !== undefined)
+        out.requestTimeout = opts.controls.maxDurationMs;
+    if (opts.thinking !== undefined)
+        out.thinking = opts.thinking;
+    if (opts.effort !== undefined)
+        out.effort = opts.effort;
+    if (opts.customModelParams !== undefined)
+        out.customModelParams = opts.customModelParams;
+    if (opts.cache !== undefined)
+        out.cache = opts.cache;
+    return out;
+}
+function basePrompt(opts, hasTools) {
+    const system = opts.systemBlocks
+        ? opts.systemBlocks.map((block) => block.text).filter(Boolean).join('\n\n')
+        : buildSystemPrompt(opts) ?? '';
+    const cot = hasTools ? resolveChainOfThought(opts.chainOfThought ?? true) : undefined;
+    if (!cot)
+        return system;
+    return system ? `${cot}\n\n${system}` : cot;
+}
+/**
+ * Builds the persona of a GMI from agent options (spec D6).
+ *
+ * @param opts - The agent's options.
+ * @param cognition - The resolved profile ({@link resolveCognition}): sentiment tracking and metaprompts.
+ * @param tools - The agent's tools, adapted: they decide the chain-of-thought text and the persona's capabilities.
+ * @throws {Error} When no provider or model can be resolved, as `generateText` throws.
+ */
+export function personaFromAgentOptions(opts, cognition, tools) {
+    const { providerId, modelId } = resolveModelOption({ provider: opts.provider, model: opts.model, baseUrl: opts.baseUrl }, 'text');
+    const name = opts.name?.trim() || 'Agent';
+    const firstLine = opts.instructions?.split('\n').map((line) => line.trim()).find(Boolean);
+    const completion = completionOptionsOf(opts);
+    const presets = cognition.metaprompts === 'all' ? ['all'] : cognition.metaprompts || [];
+    const persona = {
+        id: opts.name?.trim() ? personaIdFor(opts.name.trim()) : `agent-${randomUUID()}`,
+        name,
+        description: firstLine ?? name,
+        version: '1.0.0',
+        baseSystemPrompt: basePrompt(opts, tools.length > 0),
+        ...(opts.personality ? { personalityTraits: normalizeHexacoTraits(opts.personality) } : {}),
+        defaultProviderId: providerId,
+        defaultModelId: modelId,
+        ...(Object.keys(completion).length > 0 ? { defaultModelCompletionOptions: completion } : {}),
+        allowedCapabilities: [...new Set(tools.flatMap((tool) => tool.requiredCapabilities ?? []))],
+        conversationContextConfig: { maxMessages: GMI_SESSION_MAX_HISTORY_MESSAGES },
+        sentimentTracking: cognition.sentiment ? { enabled: true, presets } : { enabled: false },
+        ...(cognition.metaprompts === false ? { metaPrompts: [] } : {}),
+    };
+    return normalizePersonaDefinition(persona);
+}
+//# sourceMappingURL=gmiPersona.js.map

package/dist/api/runtime/gmiPersona.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gmiPersona.js","sourceRoot":"","sources":["../../../src/api/runtime/gmiPersona.ts"],"names":[],"mappings":"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"}

package/dist/api/runtime/gmiResults.d.ts

@@ -0,0 +1,98 @@
+/**
+ * @file gmiResults.ts
+ * Folds a GMI turn's output chunks into the result shapes of `generateText`
+ * (`session.send()`) and `streamText` (`session.stream()`) on the GMI path
+ * (`agent({ runtime: 'gmi' })`).
+ *
+ * The rules are streamText's: the turn's text is the latest step that produced
+ * text; usage adds each step's STEP_FINISHED usage once (USAGE_UPDATE carries a
+ * request's running total) plus the billed usage of attempts that failed before
+ * any output; a run that called tools and produced no text ends as
+ * `'tool-calls'`; an ERROR chunk ends it as `'error'` with the GMI's code.
+ */
+import { GMIError } from '../../core/utils/errors.js';
+import { type GMIOutputChunk, type StepFinishedChunkPayload, type ToolResultChunkPayload } from '../../cognition/substrate/IGMI.js';
+import { type GenerateTextResult, type TokenUsage, type ToolCallRecord } from '../generateText.js';
+import { type StreamTextResult } from '../streamText.js';
+import type { SessionTranscriptMessage } from '../sessionTranscript.js';
+/** The error a turn ended with, as the GMI reported it. */
+export interface GmiTurnError {
+    code?: string;
+    message: string;
+    details?: unknown;
+}
+/** An attempt that failed before any output and was billed (reported on a USAGE_UPDATE with `metadata.attemptFailed`). */
+export interface GmiFailedAttempt {
+    providerId?: string;
+    modelId?: string;
+    usage: TokenUsage;
+}
+/** The message a failed tool result carries. */
+export declare function toolErrorMessage(result: ToolResultChunkPayload): string;
+/**
+ * Accumulates one turn's chunks. `push` every chunk in order; read the result
+ * once the turn has ended (or at any point for a partial view).
+ */
+export declare class GmiTurnFolder {
+    /** The STEP_FINISHED payloads, in order. */
+    readonly steps: StepFinishedChunkPayload[];
+    /** Every requested call in order, with its result once the TOOL_RESULT arrived. */
+    private readonly calls;
+    private readonly overrides;
+    private readonly failed;
+    private failure;
+    push(chunk: GMIOutputChunk): void;
+    /** Marks the turn failed by a thrown error (the turn's generator itself threw). An ERROR chunk already seen wins. */
+    fail(error: unknown): void;
+    /** Replaces a step's text (`onAfterGeneration`), in the result and in what the session stores. */
+    overrideStepText(stepIndex: number, text: string): void;
+    /** A step's text as the result reports it: a schema answer as its JSON string, else the hook's replacement, else the step's own text. */
+    stepText(step: StepFinishedChunkPayload): string;
+    /** The latest step that produced text, streamText's rule. */
+    text(): string;
+    /** Each step's usage once, plus every billed failed attempt. */
+    usage(): TokenUsage;
+    /** The billed attempts that failed before any output, in order. */
+    failedAttempts(): GmiFailedAttempt[];
+    /** Every call the model requested, with its result or error. */
+    toolCalls(): ToolCallRecord[];
+    /** The latest schema answer a step carried, if any. */
+    structuredOutput(): unknown;
+    error(): GmiTurnError | undefined;
+    finishReason(): GenerateTextResult['finishReason'];
+    /** The error the turn ended with, as a GMIError keeping the GMI's code. */
+    toError(): GMIError | undefined;
+    /**
+     * The turn as `generateText` reports a run: provider, model and response
+     * metadata from the last step, the text, the usage, the tool calls and the
+     * finish reason.
+     *
+     * @param transcriptDelta - The messages the turn added to the session store.
+     */
+    toGenerateTextResult(transcriptDelta?: SessionTranscriptMessage[]): GenerateTextResult;
+}
+/** Options for {@link streamFromGmiTurn}. */
+export interface GmiStreamOptions {
+    /**
+     * A folder the turn already pushes every chunk into (the session's, which
+     * carries the `onAfterGeneration` replacements). Without one, the stream
+     * folds the chunks itself.
+     */
+    folder?: GmiTurnFolder;
+}
+/**
+ * A `StreamTextResult` over a GMI turn. The turn is drained eagerly, so every
+ * promise settles whether the caller iterates, stops iterating early, or never
+ * iterates; `textStream` and `fullStream` replay what arrived and wait for more.
+ *
+ * `textStream` yields every TEXT_DELTA as it arrives. `fullStream` maps
+ * TEXT_DELTA to `text`, TOOL_CALL_REQUEST to `tool-call`, TOOL_RESULT to
+ * `tool-result` and ERROR (or a thrown error) to a final `error` part. `text`
+ * is the latest step's text; after an error it is the text the failed step
+ * delivered, as streamText resolves it.
+ *
+ * @param turn - The turn's chunks.
+ * @param options - A caller-owned folder; see {@link GmiStreamOptions}.
+ */
+export declare function streamFromGmiTurn(turn: AsyncIterable<GMIOutputChunk>, options?: GmiStreamOptions): StreamTextResult;
+//# sourceMappingURL=gmiResults.d.ts.map

package/dist/api/runtime/gmiResults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gmiResults.d.ts","sourceRoot":"","sources":["../../../src/api/runtime/gmiResults.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,QAAQ,EAAgB,MAAM,4BAA4B,CAAC;AACpE,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,wBAAwB,EAE7B,KAAK,sBAAsB,EAC5B,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAiB,KAAK,kBAAkB,EAAE,KAAK,UAAU,EAAE,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAClH,OAAO,EAAgD,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACvG,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AAExE,2DAA2D;AAC3D,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,0HAA0H;AAC1H,MAAM,WAAW,gBAAgB;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,UAAU,CAAC;CACnB;AAiBD,gDAAgD;AAChD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,MAAM,CAGvE;AAED;;;GAGG;AACH,qBAAa,aAAa;IACxB,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,EAAE,wBAAwB,EAAE,CAAM;IAChD,mFAAmF;IACnF,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAyE;IAC/F,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA6B;IACvD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;IACjD,OAAO,CAAC,OAAO,CAA2B;IAE1C,IAAI,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI;IA0CjC,qHAAqH;IACrH,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAQ1B,kGAAkG;IAClG,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAIvD,yIAAyI;IACzI,QAAQ,CAAC,IAAI,EAAE,wBAAwB,GAAG,MAAM;IAKhD,6DAA6D;IAC7D,IAAI,IAAI,MAAM;IAQd,gEAAgE;IAChE,KAAK,IAAI,UAAU;IAOnB,mEAAmE;IACnE,cAAc,IAAI,gBAAgB,EAAE;IAIpC,gEAAgE;IAChE,SAAS,IAAI,cAAc,EAAE;IAS7B,uDAAuD;IACvD,gBAAgB,IAAI,OAAO;IAO3B,KAAK,IAAI,YAAY,GAAG,SAAS;IAIjC,YAAY,IAAI,kBAAkB,CAAC,cAAc,CAAC;IAQlD,2EAA2E;IAC3E,OAAO,IAAI,QAAQ,GAAG,SAAS;IAK/B;;;;;;OAMG;IACH,oBAAoB,CAAC,eAAe,CAAC,EAAE,wBAAwB,EAAE,GAAG,kBAAkB;CAgBvF;AAeD,6CAA6C;AAC7C,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,aAAa,CAAC,cAAc,CAAC,EAAE,OAAO,GAAE,gBAAqB,GAAG,gBAAgB,CAiHvH"}

package/dist/api/runtime/gmiResults.js

@@ -0,0 +1,333 @@
+/**
+ * @file gmiResults.ts
+ * Folds a GMI turn's output chunks into the result shapes of `generateText`
+ * (`session.send()`) and `streamText` (`session.stream()`) on the GMI path
+ * (`agent({ runtime: 'gmi' })`).
+ *
+ * The rules are streamText's: the turn's text is the latest step that produced
+ * text; usage adds each step's STEP_FINISHED usage once (USAGE_UPDATE carries a
+ * request's running total) plus the billed usage of attempts that failed before
+ * any output; a run that called tools and produced no text ends as
+ * `'tool-calls'`; an ERROR chunk ends it as `'error'` with the GMI's code.
+ */
+import { GMIError, GMIErrorCode } from '../../core/utils/errors.js';
+import { GMIOutputChunkType, } from '../../cognition/substrate/IGMI.js';
+import { addModelUsage } from '../generateText.js';
+import { normalizeStreamFinishReason } from '../streamText.js';
+function emptyUsage() {
+    return { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+}
+/** Adds one TokenUsage to another; an optional counter is added only when present. */
+function addTokenUsage(target, add) {
+    target.promptTokens += add.promptTokens;
+    target.completionTokens += add.completionTokens;
+    target.totalTokens += add.totalTokens;
+    if (add.costUSD !== undefined)
+        target.costUSD = (target.costUSD ?? 0) + add.costUSD;
+    if (add.cacheReadTokens !== undefined)
+        target.cacheReadTokens = (target.cacheReadTokens ?? 0) + add.cacheReadTokens;
+    if (add.cacheCreationTokens !== undefined)
+        target.cacheCreationTokens = (target.cacheCreationTokens ?? 0) + add.cacheCreationTokens;
+    if (add.inclusiveInputTokens !== undefined)
+        target.inclusiveInputTokens = (target.inclusiveInputTokens ?? 0) + add.inclusiveInputTokens;
+}
+/** The message a failed tool result carries. */
+export function toolErrorMessage(result) {
+    const details = result.errorDetails;
+    return typeof details?.message === 'string' && details.message ? details.message : 'Tool failed.';
+}
+/**
+ * Accumulates one turn's chunks. `push` every chunk in order; read the result
+ * once the turn has ended (or at any point for a partial view).
+ */
+export class GmiTurnFolder {
+    constructor() {
+        /** The STEP_FINISHED payloads, in order. */
+        this.steps = [];
+        /** Every requested call in order, with its result once the TOOL_RESULT arrived. */
+        this.calls = [];
+        this.overrides = new Map();
+        this.failed = [];
+    }
+    push(chunk) {
+        switch (chunk.type) {
+            case GMIOutputChunkType.STEP_FINISHED:
+                this.steps.push(chunk.content);
+                break;
+            case GMIOutputChunkType.TOOL_CALL_REQUEST:
+                for (const call of chunk.content ?? [])
+                    this.calls.push({ call });
+                break;
+            case GMIOutputChunkType.TOOL_RESULT: {
+                const result = chunk.content;
+                // The latest unanswered call with this id: providers may reuse ids across steps.
+                for (let i = this.calls.length - 1; i >= 0; i--) {
+                    if (this.calls[i].call.id === result.toolCallId && !this.calls[i].result) {
+                        this.calls[i].result = result;
+                        break;
+                    }
+                }
+                break;
+            }
+            case GMIOutputChunkType.USAGE_UPDATE: {
+                const meta = chunk.metadata;
+                if (meta?.attemptFailed) {
+                    const usage = emptyUsage();
+                    addModelUsage(usage, chunk.content);
+                    this.failed.push({ providerId: meta.providerId, modelId: meta.modelId, usage });
+                }
+                break;
+            }
+            case GMIOutputChunkType.ERROR: {
+                const details = chunk.errorDetails;
+                this.failure = {
+                    code: typeof details?.code === 'string' ? details.code : undefined,
+                    message: String(chunk.content),
+                    details: details?.details,
+                };
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    /** Marks the turn failed by a thrown error (the turn's generator itself threw). An ERROR chunk already seen wins. */
+    fail(error) {
+        this.failure ?? (this.failure = {
+            code: error instanceof GMIError ? String(error.code) : undefined,
+            message: error instanceof Error ? error.message : String(error),
+            details: error instanceof GMIError ? error.details : undefined,
+        });
+    }
+    /** Replaces a step's text (`onAfterGeneration`), in the result and in what the session stores. */
+    overrideStepText(stepIndex, text) {
+        this.overrides.set(stepIndex, text);
+    }
+    /** A step's text as the result reports it: a schema answer as its JSON string, else the hook's replacement, else the step's own text. */
+    stepText(step) {
+        if (step.structuredOutput !== undefined)
+            return JSON.stringify(step.structuredOutput);
+        return this.overrides.get(step.stepIndex) ?? step.text;
+    }
+    /** The latest step that produced text, streamText's rule. */
+    text() {
+        for (let i = this.steps.length - 1; i >= 0; i--) {
+            const t = this.stepText(this.steps[i]);
+            if (t)
+                return t;
+        }
+        return '';
+    }
+    /** Each step's usage once, plus every billed failed attempt. */
+    usage() {
+        const total = emptyUsage();
+        for (const step of this.steps)
+            addModelUsage(total, step.usage);
+        for (const attempt of this.failed)
+            addTokenUsage(total, attempt.usage);
+        return total;
+    }
+    /** The billed attempts that failed before any output, in order. */
+    failedAttempts() {
+        return this.failed.map((a) => ({ ...a, usage: { ...a.usage } }));
+    }
+    /** Every call the model requested, with its result or error. */
+    toolCalls() {
+        return this.calls.map(({ call, result }) => {
+            const record = { name: call.name, args: call.arguments };
+            if (result?.isError)
+                record.error = toolErrorMessage(result);
+            else if (result)
+                record.result = result.result;
+            return record;
+        });
+    }
+    /** The latest schema answer a step carried, if any. */
+    structuredOutput() {
+        for (let i = this.steps.length - 1; i >= 0; i--) {
+            if (this.steps[i].structuredOutput !== undefined)
+                return this.steps[i].structuredOutput;
+        }
+        return undefined;
+    }
+    error() {
+        return this.failure;
+    }
+    finishReason() {
+        if (this.failure)
+            return 'error';
+        const last = this.steps.at(-1);
+        // The schema answer is the turn's reply, whatever stop reason carried it.
+        if (last?.structuredOutput !== undefined)
+            return 'stop';
+        return this.calls.length > 0 && !this.text() ? 'tool-calls' : normalizeStreamFinishReason(last?.finishReason ?? null);
+    }
+    /** The error the turn ended with, as a GMIError keeping the GMI's code. */
+    toError() {
+        if (!this.failure)
+            return undefined;
+        return new GMIError(this.failure.message, this.failure.code ?? GMIErrorCode.GMI_PROCESSING_ERROR, this.failure.details);
+    }
+    /**
+     * The turn as `generateText` reports a run: provider, model and response
+     * metadata from the last step, the text, the usage, the tool calls and the
+     * finish reason.
+     *
+     * @param transcriptDelta - The messages the turn added to the session store.
+     */
+    toGenerateTextResult(transcriptDelta) {
+        const last = this.steps.at(-1);
+        return {
+            provider: last?.providerId ?? '',
+            model: last?.modelId ?? '',
+            ...(last?.responseModel ? { responseModel: last.responseModel } : {}),
+            ...(last?.serviceTier ? { serviceTier: last.serviceTier } : {}),
+            ...(last?.providerMessageId ? { providerMessageId: last.providerMessageId } : {}),
+            ...(last?.cacheDiagnostics !== undefined ? { cacheDiagnostics: last.cacheDiagnostics } : {}),
+            text: this.text(),
+            usage: this.usage(),
+            toolCalls: this.toolCalls(),
+            finishReason: this.finishReason(),
+            ...(transcriptDelta ? { transcriptDelta } : {}),
+        };
+    }
+}
+function deferred() {
+    let resolve;
+    const promise = new Promise((r) => {
+        resolve = r;
+    });
+    return { promise, resolve };
+}
+/**
+ * A `StreamTextResult` over a GMI turn. The turn is drained eagerly, so every
+ * promise settles whether the caller iterates, stops iterating early, or never
+ * iterates; `textStream` and `fullStream` replay what arrived and wait for more.
+ *
+ * `textStream` yields every TEXT_DELTA as it arrives. `fullStream` maps
+ * TEXT_DELTA to `text`, TOOL_CALL_REQUEST to `tool-call`, TOOL_RESULT to
+ * `tool-result` and ERROR (or a thrown error) to a final `error` part. `text`
+ * is the latest step's text; after an error it is the text the failed step
+ * delivered, as streamText resolves it.
+ *
+ * @param turn - The turn's chunks.
+ * @param options - A caller-owned folder; see {@link GmiStreamOptions}.
+ */
+export function streamFromGmiTurn(turn, options = {}) {
+    const folder = options.folder ?? new GmiTurnFolder();
+    const foldHere = !options.folder;
+    const texts = [];
+    const parts = [];
+    let done = false;
+    let waiters = [];
+    const wake = () => {
+        const pending = waiters;
+        waiters = [];
+        pending.forEach((w) => w());
+    };
+    const p = {
+        text: deferred(),
+        usage: deferred(),
+        toolCalls: deferred(),
+        provider: deferred(),
+        model: deferred(),
+        finishReason: deferred(),
+        responseModel: deferred(),
+        serviceTier: deferred(),
+        cacheDiagnostics: deferred(),
+        providerMessageId: deferred(),
+    };
+    void (async () => {
+        // The text the step in progress has delivered; reset at each step boundary.
+        let stepDelivered = '';
+        try {
+            for await (const chunk of turn) {
+                if (foldHere)
+                    folder.push(chunk);
+                switch (chunk.type) {
+                    case GMIOutputChunkType.TEXT_DELTA: {
+                        const text = String(chunk.content ?? '');
+                        stepDelivered += text;
+                        texts.push(text);
+                        parts.push({ type: 'text', text });
+                        break;
+                    }
+                    case GMIOutputChunkType.STEP_FINISHED:
+                        stepDelivered = '';
+                        break;
+                    case GMIOutputChunkType.TOOL_CALL_REQUEST:
+                        for (const call of chunk.content ?? [])
+                            parts.push({ type: 'tool-call', toolName: call.name, args: call.arguments });
+                        break;
+                    case GMIOutputChunkType.TOOL_RESULT: {
+                        const r = chunk.content;
+                        parts.push({ type: 'tool-result', toolName: r.name, result: r.isError ? { error: toolErrorMessage(r) } : r.result });
+                        break;
+                    }
+                    case GMIOutputChunkType.ERROR:
+                        parts.push({ type: 'error', error: folder.toError() ?? new Error(String(chunk.content)) });
+                        break;
+                    default:
+                        break;
+                }
+                wake();
+            }
+        }
+        catch (error) {
+            folder.fail(error);
+            parts.push({ type: 'error', error: error instanceof Error ? error : new Error(String(error)) });
+        }
+        finally {
+            const last = folder.steps.at(-1);
+            p.text.resolve(folder.error() && stepDelivered ? stepDelivered : folder.text());
+            p.usage.resolve(folder.usage());
+            p.toolCalls.resolve(folder.toolCalls());
+            p.provider.resolve(last?.providerId ?? '');
+            p.model.resolve(last?.modelId ?? '');
+            p.finishReason.resolve(folder.finishReason());
+            p.responseModel.resolve(last?.responseModel);
+            p.serviceTier.resolve(last?.serviceTier);
+            p.cacheDiagnostics.resolve(last?.cacheDiagnostics ?? null);
+            p.providerMessageId.resolve(last?.providerMessageId ?? null);
+            done = true;
+            wake();
+        }
+    })();
+    function replay(buffer) {
+        return {
+            [Symbol.asyncIterator]() {
+                let i = 0;
+                return {
+                    async next() {
+                        for (;;) {
+                            if (i < buffer.length)
+                                return { value: buffer[i++], done: false };
+                            if (done)
+                                return { value: undefined, done: true };
+                            await new Promise((resolve) => waiters.push(resolve));
+                        }
+                    },
+                    async return() {
+                        i = Number.MAX_SAFE_INTEGER;
+                        return { value: undefined, done: true };
+                    },
+                };
+            },
+        };
+    }
+    return {
+        textStream: replay(texts),
+        fullStream: replay(parts),
+        text: p.text.promise,
+        usage: p.usage.promise,
+        toolCalls: p.toolCalls.promise,
+        provider: p.provider.promise,
+        model: p.model.promise,
+        finishReason: p.finishReason.promise,
+        responseModel: p.responseModel.promise,
+        serviceTier: p.serviceTier.promise,
+        cacheDiagnostics: p.cacheDiagnostics.promise,
+        providerMessageId: p.providerMessageId.promise,
+    };
+}
+//# sourceMappingURL=gmiResults.js.map

package/dist/api/runtime/gmiResults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gmiResults.js","sourceRoot":"","sources":["../../../src/api/runtime/gmiResults.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,EACL,kBAAkB,GAKnB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAiE,MAAM,oBAAoB,CAAC;AAClH,OAAO,EAAE,2BAA2B,EAA0C,MAAM,kBAAkB,CAAC;AAiBvG,SAAS,UAAU;IACjB,OAAO,EAAE,YAAY,EAAE,CAAC,EAAE,gBAAgB,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC;AAClE,CAAC;AAED,sFAAsF;AACtF,SAAS,aAAa,CAAC,MAAkB,EAAE,GAAe;IACxD,MAAM,CAAC,YAAY,IAAI,GAAG,CAAC,YAAY,CAAC;IACxC,MAAM,CAAC,gBAAgB,IAAI,GAAG,CAAC,gBAAgB,CAAC;IAChD,MAAM,CAAC,WAAW,IAAI,GAAG,CAAC,WAAW,CAAC;IACtC,IAAI,GAAG,CAAC,OAAO,KAAK,SAAS;QAAE,MAAM,CAAC,OAAO,GAAG,CAAC,MAAM,CAAC,OAAO,IAAI,CAAC,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC;IACpF,IAAI,GAAG,CAAC,eAAe,KAAK,SAAS;QAAE,MAAM,CAAC,eAAe,GAAG,CAAC,MAAM,CAAC,eAAe,IAAI,CAAC,CAAC,GAAG,GAAG,CAAC,eAAe,CAAC;IACpH,IAAI,GAAG,CAAC,mBAAmB,KAAK,SAAS;QAAE,MAAM,CAAC,mBAAmB,GAAG,CAAC,MAAM,CAAC,mBAAmB,IAAI,CAAC,CAAC,GAAG,GAAG,CAAC,mBAAmB,CAAC;IACpI,IAAI,GAAG,CAAC,oBAAoB,KAAK,SAAS;QAAE,MAAM,CAAC,oBAAoB,GAAG,CAAC,MAAM,CAAC,oBAAoB,IAAI,CAAC,CAAC,GAAG,GAAG,CAAC,oBAAoB,CAAC;AAC1I,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,gBAAgB,CAAC,MAA8B;IAC7D,MAAM,OAAO,GAAG,MAAM,CAAC,YAAiD,CAAC;IACzE,OAAO,OAAO,OAAO,EAAE,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,cAAc,CAAC;AACpG,CAAC;AAED;;;GAGG;AACH,MAAM,OAAO,aAAa;IAA1B;QACE,4CAA4C;QACnC,UAAK,GAA+B,EAAE,CAAC;QAChD,mFAAmF;QAClE,UAAK,GAAsE,EAAE,CAAC;QAC9E,cAAS,GAAG,IAAI,GAAG,EAAkB,CAAC;QACtC,WAAM,GAAuB,EAAE,CAAC;IAkJnD,CAAC;IA/IC,IAAI,CAAC,KAAqB;QACxB,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;YACnB,KAAK,kBAAkB,CAAC,aAAa;gBACnC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAmC,CAAC,CAAC;gBAC3D,MAAM;YACR,KAAK,kBAAkB,CAAC,iBAAiB;gBACvC,KAAK,MAAM,IAAI,IAAK,KAAK,CAAC,OAA6B,IAAI,EAAE;oBAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;gBACzF,MAAM;YACR,KAAK,kBAAkB,CAAC,WAAW,CAAC,CAAC,CAAC;gBACpC,MAAM,MAAM,GAAG,KAAK,CAAC,OAAiC,CAAC;gBACvD,iFAAiF;gBACjF,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;oBAChD,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,MAAM,CAAC,UAAU,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;wBACzE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,MAAM,CAAC;wBAC9B,MAAM;oBACR,CAAC;gBACH,CAAC;gBACD,MAAM;YACR,CAAC;YACD,KAAK,kBAAkB,CAAC,YAAY,CAAC,CAAC,CAAC;gBACrC,MAAM,IAAI,GAAG,KAAK,CAAC,QAA0F,CAAC;gBAC9G,IAAI,IAAI,EAAE,aAAa,EAAE,CAAC;oBACxB,MAAM,KAAK,GAAG,UAAU,EAAE,CAAC;oBAC3B,aAAa,CAAC,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;oBACpC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;gBAClF,CAAC;gBACD,MAAM;YACR,CAAC;YACD,KAAK,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC;gBAC9B,MAAM,OAAO,GAAG,KAAK,CAAC,YAAiE,CAAC;gBACxF,IAAI,CAAC,OAAO,GAAG;oBACb,IAAI,EAAE,OAAO,OAAO,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;oBAClE,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC;oBAC9B,OAAO,EAAE,OAAO,EAAE,OAAO;iBAC1B,CAAC;gBACF,MAAM;YACR,CAAC;YACD;gBACE,MAAM;QACV,CAAC;IACH,CAAC;IAED,qHAAqH;IACrH,IAAI,CAAC,KAAc;QACjB,IAAI,CAAC,OAAO,KAAZ,IAAI,CAAC,OAAO,GAAK;YACf,IAAI,EAAE,KAAK,YAAY,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;YAChE,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;YAC/D,OAAO,EAAE,KAAK,YAAY,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS;SAC/D,EAAC;IACJ,CAAC;IAED,kGAAkG;IAClG,gBAAgB,CAAC,SAAiB,EAAE,IAAY;QAC9C,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IACtC,CAAC;IAED,yIAAyI;IACzI,QAAQ,CAAC,IAA8B;QACrC,IAAI,IAAI,CAAC,gBAAgB,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;QACtF,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC;IACzD,CAAC;IAED,6DAA6D;IAC7D,IAAI;QACF,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAChD,MAAM,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;YACvC,IAAI,CAAC;gBAAE,OAAO,CAAC,CAAC;QAClB,CAAC;QACD,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,gEAAgE;IAChE,KAAK;QACH,MAAM,KAAK,GAAG,UAAU,EAAE,CAAC;QAC3B,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK;YAAE,aAAa,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;QAChE,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,MAAM;YAAE,aAAa,CAAC,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QACvE,OAAO,KAAK,CAAC;IACf,CAAC;IAED,mEAAmE;IACnE,cAAc;QACZ,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,EAAE,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC;IACnE,CAAC;IAED,gEAAgE;IAChE,SAAS;QACP,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE;YACzC,MAAM,MAAM,GAAmB,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC;YACzE,IAAI,MAAM,EAAE,OAAO;gBAAE,MAAM,CAAC,KAAK,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;iBACxD,IAAI,MAAM;gBAAE,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;YAC/C,OAAO,MAAM,CAAC;QAChB,CAAC,CAAC,CAAC;IACL,CAAC;IAED,uDAAuD;IACvD,gBAAgB;QACd,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAChD,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,gBAAgB,KAAK,SAAS;gBAAE,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC;QAC1F,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,KAAK;QACH,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,YAAY;QACV,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO,OAAO,CAAC;QACjC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/B,0EAA0E;QAC1E,IAAI,IAAI,EAAE,gBAAgB,KAAK,SAAS;YAAE,OAAO,MAAM,CAAC;QACxD,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,2BAA2B,CAAC,IAAI,EAAE,YAAY,IAAI,IAAI,CAAC,CAAC;IACxH,CAAC;IAED,2EAA2E;IAC3E,OAAO;QACL,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO,SAAS,CAAC;QACpC,OAAO,IAAI,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,YAAY,CAAC,oBAAoB,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1H,CAAC;IAED;;;;;;OAMG;IACH,oBAAoB,CAAC,eAA4C;QAC/D,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/B,OAAO;YACL,QAAQ,EAAE,IAAI,EAAE,UAAU,IAAI,EAAE;YAChC,KAAK,EAAE,IAAI,EAAE,OAAO,IAAI,EAAE;YAC1B,GAAG,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,IAAI,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACrE,GAAG,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/D,GAAG,CAAC,IAAI,EAAE,iBAAiB,CAAC,CAAC,CAAC,EAAE,iBAAiB,EAAE,IAAI,CAAC,iBAAiB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACjF,GAAG,CAAC,IAAI,EAAE,gBAAgB,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,gBAAgB,EAAE,IAAI,CAAC,gBAA0D,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACtI,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE;YACjB,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE;YACnB,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE;YAC3B,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE;YACjC,GAAG,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAChD,CAAC;IACJ,CAAC;CACF;AAOD,SAAS,QAAQ;IACf,IAAI,OAA4B,CAAC;IACjC,MAAM,OAAO,GAAG,IAAI,OAAO,CAAI,CAAC,CAAC,EAAE,EAAE;QACnC,OAAO,GAAG,CAAC,CAAC;IACd,CAAC,CAAC,CAAC;IACH,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AAC9B,CAAC;AAYD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAmC,EAAE,UAA4B,EAAE;IACnG,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,IAAI,aAAa,EAAE,CAAC;IACrD,MAAM,QAAQ,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC;IACjC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,KAAK,GAAiB,EAAE,CAAC;IAC/B,IAAI,IAAI,GAAG,KAAK,CAAC;IACjB,IAAI,OAAO,GAAsB,EAAE,CAAC;IACpC,MAAM,IAAI,GAAG,GAAS,EAAE;QACtB,MAAM,OAAO,GAAG,OAAO,CAAC;QACxB,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;IAC9B,CAAC,CAAC;IACF,MAAM,CAAC,GAAG;QACR,IAAI,EAAE,QAAQ,EAAU;QACxB,KAAK,EAAE,QAAQ,EAAc;QAC7B,SAAS,EAAE,QAAQ,EAAoB;QACvC,QAAQ,EAAE,QAAQ,EAAU;QAC5B,KAAK,EAAE,QAAQ,EAAU;QACzB,YAAY,EAAE,QAAQ,EAAsC;QAC5D,aAAa,EAAE,QAAQ,EAAsB;QAC7C,WAAW,EAAE,QAAQ,EAAsB;QAC3C,gBAAgB,EAAE,QAAQ,EAAiD;QAC3E,iBAAiB,EAAE,QAAQ,EAAiB;KAC7C,CAAC;IAEF,KAAK,CAAC,KAAK,IAAI,EAAE;QACf,4EAA4E;QAC5E,IAAI,aAAa,GAAG,EAAE,CAAC;QACvB,IAAI,CAAC;YACH,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,IAAI,EAAE,CAAC;gBAC/B,IAAI,QAAQ;oBAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;gBACjC,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;oBACnB,KAAK,kBAAkB,CAAC,UAAU,CAAC,CAAC,CAAC;wBACnC,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;wBACzC,aAAa,IAAI,IAAI,CAAC;wBACtB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;wBACjB,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;wBACnC,MAAM;oBACR,CAAC;oBACD,KAAK,kBAAkB,CAAC,aAAa;wBACnC,aAAa,GAAG,EAAE,CAAC;wBACnB,MAAM;oBACR,KAAK,kBAAkB,CAAC,iBAAiB;wBACvC,KAAK,MAAM,IAAI,IAAK,KAAK,CAAC,OAA6B,IAAI,EAAE;4BAAE,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;wBAC5I,MAAM;oBACR,KAAK,kBAAkB,CAAC,WAAW,CAAC,CAAC,CAAC;wBACpC,MAAM,CAAC,GAAG,KAAK,CAAC,OAAiC,CAAC;wBAClD,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,QAAQ,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;wBACrH,MAAM;oBACR,CAAC;oBACD,KAAK,kBAAkB,CAAC,KAAK;wBAC3B,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,OAAO,EAAE,IAAI,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;wBAC3F,MAAM;oBACR;wBACE,MAAM;gBACV,CAAC;gBACD,IAAI,EAAE,CAAC;YACT,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACnB,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;QAClG,CAAC;gBAAS,CAAC;YACT,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;YACjC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,aAAa,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;YAChF,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;YAChC,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC;YACxC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,UAAU,IAAI,EAAE,CAAC,CAAC;YAC3C,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,IAAI,EAAE,CAAC,CAAC;YACrC,CAAC,CAAC,YAAY,CAAC,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC;YAC9C,CAAC,CAAC,aAAa,CAAC,OAAO,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;YAC7C,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;YACzC,CAAC,CAAC,gBAAgB,CAAC,OAAO,CAAE,IAAI,EAAE,gBAA8E,IAAI,IAAI,CAAC,CAAC;YAC1H,CAAC,CAAC,iBAAiB,CAAC,OAAO,CAAC,IAAI,EAAE,iBAAiB,IAAI,IAAI,CAAC,CAAC;YAC7D,IAAI,GAAG,IAAI,CAAC;YACZ,IAAI,EAAE,CAAC;QACT,CAAC;IACH,CAAC,CAAC,EAAE,CAAC;IAEL,SAAS,MAAM,CAAI,MAAW;QAC5B,OAAO;YACL,CAAC,MAAM,CAAC,aAAa,CAAC;gBACpB,IAAI,CAAC,GAAG,CAAC,CAAC;gBACV,OAAO;oBACL,KAAK,CAAC,IAAI;wBACR,SAAS,CAAC;4BACR,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM;gCAAE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;4BAClE,IAAI,IAAI;gCAAE,OAAO,EAAE,KAAK,EAAE,SAAkB,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;4BAC3D,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;wBAC9D,CAAC;oBACH,CAAC;oBACD,KAAK,CAAC,MAAM;wBACV,CAAC,GAAG,MAAM,CAAC,gBAAgB,CAAC;wBAC5B,OAAO,EAAE,KAAK,EAAE,SAAkB,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;oBACnD,CAAC;iBACF,CAAC;YACJ,CAAC;SACF,CAAC;IACJ,CAAC;IAED,OAAO;QACL,UAAU,EAAE,MAAM,CAAC,KAAK,CAAC;QACzB,UAAU,EAAE,MAAM,CAAC,KAAK,CAAC;QACzB,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,OAAO;QACpB,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO;QACtB,SAAS,EAAE,CAAC,CAAC,SAAS,CAAC,OAAO;QAC9B,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,OAAO;QAC5B,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO;QACtB,YAAY,EAAE,CAAC,CAAC,YAAY,CAAC,OAAO;QACpC,aAAa,EAAE,CAAC,CAAC,aAAa,CAAC,OAAO;QACtC,WAAW,EAAE,CAAC,CAAC,WAAW,CAAC,OAAO;QAClC,gBAAgB,EAAE,CAAC,CAAC,gBAAgB,CAAC,OAAO;QAC5C,iBAAiB,EAAE,CAAC,CAAC,iBAAiB,CAAC,OAAO;KAC/C,CAAC;AACJ,CAAC"}

package/dist/api/runtime/gmiSession.d.ts

@@ -0,0 +1,85 @@
+import type { ZodType } from 'zod';
+import { type GMIOutputChunk, type IGMI } from '../../cognition/substrate/IGMI.js';
+import { type GenerateTextResult, type MessageContent, type TokenUsage } from '../generateText.js';
+import type { StreamTextResult } from '../streamText.js';
+import type { SessionHistoryBuffer } from '../sessionHistory.js';
+import type { SessionTranscriptMessage } from '../sessionTranscript.js';
+import type { AgentOptions } from '../agent.js';
+import type { AgentOSUsageLedgerOptions } from './usageLedger.js';
+import { GmiTurnFolder } from './gmiResults.js';
+/** Serialises turns: `acquire()` resolves with a release function once every earlier holder released. */
+export declare class TurnLock {
+    private tail;
+    acquire(): Promise<() => void>;
+}
+/** What one turn asks for beyond its input. */
+export interface GmiTurnOptions {
+    /** Completion options for this turn (`metadata.options`): temperature, maxTokens, toolChoice, cacheDiagnostics, … */
+    options?: Record<string, unknown>;
+    /** Structured output: the gateway lowers it for each hop and suppresses tools. */
+    responseSchema?: ZodType;
+    schemaName?: string;
+    /** Label of the turn's block in the session store. */
+    blockLabel?: string;
+}
+/** What the GMI's hooks need to know about the turn about to run. */
+export interface GmiTurnContext {
+    /** The turn's text input, for `onBeforeGeneration`'s `prompt` (undefined for multimodal input). */
+    prompt: string | undefined;
+    /** The `memoryProvider.getContext` block for this turn, inserted as a system message on every model call. */
+    memoryContext: string | undefined;
+}
+/** The GMI that serves one turn. */
+export interface GmiForTurn {
+    gmi: IGMI;
+    /** Hands the turn's prompt and memory context to the GMI's hooks; called after the turn holds the lock, before it runs. */
+    prepare?(context: GmiTurnContext): void;
+    /** Releases a GMI made for this turn alone; called once the turn has ended. */
+    release?(): Promise<void>;
+}
+/** What a session hands the turn runner. */
+export interface GmiSessionDeps {
+    sessionId: string;
+    opts: AgentOptions;
+    /** The GMI that serves the next turn: the session's own, or one made for the turn when the session keeps no history. */
+    gmiFor(): Promise<GmiForTurn>;
+    /** The user the GMI runs the turn as: it scopes cognitive memory, and the GMI passes it to the provider as its user field. */
+    userId: string;
+    /** False when cognitive memory supplies the memory context: `memoryProvider.getContext` is then skipped. */
+    useMemoryProviderContext: boolean;
+    /** The session store, or null when the turn keeps no history. */
+    history: SessionHistoryBuffer | null;
+    /** Usage ledger options for this turn's events (session id and source included). */
+    ledger?: AgentOSUsageLedgerOptions;
+    /** Receives the turn's usage once it ends, failed or not. */
+    onUsage(usage: TokenUsage): void;
+    lock: TurnLock;
+}
+/**
+ * Runs one GMI turn and yields its chunks, pushing each into `folder`, writing
+ * each finished step to the session store and each step's usage to the ledger.
+ * The caller folds the chunks (send) or streams them (stream).
+ *
+ * The turn reads the store's epoch and messages the moment it holds the lock,
+ * before it waits for its GMI or its memory context, so a clear or reseed during
+ * those waits makes the turn's writes no-ops, as an in-flight legacy send's are.
+ *
+ * @returns The messages the turn added to the store (or would have, with no history).
+ */
+export declare function runGmiTurn(deps: GmiSessionDeps, input: MessageContent, turn: GmiTurnOptions, folder: GmiTurnFolder): AsyncGenerator<GMIOutputChunk, SessionTranscriptMessage[], undefined>;
+/**
+ * `send()`: the whole turn, folded into a `GenerateTextResult` (with `object`
+ * when a schema was given). Rejects with the GMI's error, its code kept, when
+ * the turn failed; an error thrown before the turn ran (no provider or model
+ * resolves, the memory cannot be built) is rethrown as it was thrown.
+ */
+export declare function sendGmiTurn(deps: GmiSessionDeps, input: MessageContent, turn: GmiTurnOptions): Promise<GenerateTextResult & {
+    object?: unknown;
+}>;
+/**
+ * `stream()`: the turn's chunks as a `StreamTextResult`. The promises settle
+ * after the turn is written to the session store, so a caller that awaits
+ * `text` and sends again finds the turn in the history.
+ */
+export declare function streamGmiTurn(deps: GmiSessionDeps, input: MessageContent, turn: GmiTurnOptions): StreamTextResult;
+//# sourceMappingURL=gmiSession.d.ts.map

package/dist/api/runtime/gmiSession.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gmiSession.d.ts","sourceRoot":"","sources":["../../../src/api/runtime/gmiSession.ts"],"names":[],"mappings":"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"}