@intentface/latch-core 0.9.1 → 0.11.0

package/dist/extensions/extension.d.ts

@@ -0,0 +1,322 @@
+/**
+ * extension.ts — the extension model.
+ *
+ * An extension attaches handlers to MOMENTS of a turn. A handler returns an
+ * EFFECT, never a rewritten world; `undefined` means no effect. The effect type
+ * for each moment says exactly what is possible there, so you cannot do
+ * everything everywhere, and several extensions on one moment compose by a
+ * rule declared once per moment (see `compose.ts`).
+ *
+ * WHAT PERSISTS. The stored `UIMessage[]` is the only durable thing; everything
+ * else is recomputed each step. Three moments change it:
+ *
+ *   before_agent_start   injects or replaces messages
+ *   step_end             appends parts (append-only; never rewrites)
+ *   tool_result          the override IS the stored result, and what the model reads
+ *
+ * The rest are lenses and vanish after the step:
+ *
+ *   instructions, context   what the MODEL sees
+ *   render                  what the CUSTOMER sees, live AND on load
+ *
+ * So: mask a secret in `tool_result` and it is gone everywhere (usually right).
+ * Use `render` only for the rarer case where the model should keep the truth
+ * and the person should not see it.
+ *
+ * Ported from `experiment/agents-sdk`, where the same model ran 118/119 of its
+ * suite over a plain `streamText` loop — the moments do not depend on who owns
+ * the loop, which is why they can sit over `ToolLoopAgent` here.
+ */
+import type { Instructions, LanguageModel, ModelMessage, ToolSet, UIMessage, UIMessagePart } from "ai";
+/**
+ * Who a run is for, as an extension sees it. EMPTY on purpose, and augmented by
+ * the application:
+ *
+ *   declare module "@intentface/latch-core" {
+ *     interface Principal { orgId: string; userId: string }
+ *   }
+ *
+ * Augmentation rather than a `<P>` type parameter, because a parameter has to
+ * be repeated at every declaration that touches it — the runtime's own `<P>`
+ * already rides on twenty-odd exported symbols, and every moment type would
+ * inherit the noise. One `declare module` gives the same type safety with no
+ * generics in any handler signature. The trade is one principal shape per
+ * process, which is what an application has anyway. The runtime hands its `P`
+ * through as this type; the two describe the same object.
+ *
+ * The framework never reads a field of this. Isolation is enforced wherever
+ * the principal is USED — the storage owner key, a connection lookup.
+ *
+ * CONTRACT: principals are persisted with a run and replayed on resume or a
+ * scheduled fire, possibly months later. Durable identifiers only: no secrets
+ * or tokens, no PII beyond ids, nothing volatile like roles or flags.
+ */
+export interface Principal {
+}
+/** What is known before the first step: no step number yet, no messages of its own. */
+export interface RunContext {
+    runId: string;
+    principal: Principal;
+}
+export interface StepContext extends RunContext {
+    stepNumber: number;
+    /** The stored messages at this step. */
+    messages: UIMessage[];
+}
+/**
+ * Token counts for one step. The cache split is carried separately because
+ * cached input is billed at a fraction of the normal rate, so a cost extension
+ * that only sees `inputTokens` overcharges every cached turn.
+ */
+export interface StepUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    /** Cached input tokens read. Billed at a discount by most providers. */
+    cacheReadTokens?: number;
+    /** Input tokens written to the cache. Usually billed at a premium. */
+    cacheWriteTokens?: number;
+    reasoningTokens?: number;
+}
+/** What a completed step cost and how it ended. The basis for evals and budgets. */
+export interface StepInfo extends StepContext {
+    usage: StepUsage;
+    finishReason: string;
+    model: {
+        provider: string;
+        modelId: string;
+    };
+    durationMs: number;
+    toolCalls: Array<{
+        toolName: string;
+        toolCallId: string;
+    }>;
+}
+export type Part = UIMessagePart<any, any>;
+/**
+ * `replace` is how a store says "ignore what the client sent, this is the
+ * truth". `inject` adds a message WITHOUT disturbing the response anchor: it
+ * lands immediately before the final message, so a synthetic message can never
+ * become the assistant message the run streams into. See `compose.messagesIn`.
+ */
+export type StartEffect = {
+    inject?: UIMessage;
+} | {
+    replace?: UIMessage[];
+} | undefined | void;
+/** Append-only: nothing can rewrite the past. History only grows. */
+export type StepEffect = {
+    append?: Part[];
+} | undefined | void;
+/**
+ * `append` adds a paragraph of text. `replace` hands over the whole
+ * `Instructions` value, which may be a `SystemModelMessage[]` carrying
+ * `providerOptions` — that is how prompt-cache breakpoints are set on the
+ * system prompt, so this deliberately is NOT narrowed to `string`.
+ */
+export type InstructionsEffect = {
+    append?: string;
+} | {
+    replace?: Instructions;
+} | undefined | void;
+export type ContextEffect = {
+    messages?: ModelMessage[];
+} | undefined | void;
+/** One rule over a part, applied to the live stream AND to stored messages on load. */
+export type ViewEffect = {
+    hide?: true;
+} | {
+    replace?: Part;
+} | undefined | void;
+export type ToolCallEffect = {
+    block?: true;
+    reason?: string;
+} | undefined | void;
+export type ToolResultEffect = {
+    output?: unknown;
+    isError?: boolean;
+} | undefined | void;
+/**
+ * `transform` rewrites the text before the run starts. `handled` skips the
+ * model entirely — `reply` becomes the assistant's answer, so the conversation
+ * still reads normally.
+ *
+ * `replace` exists because a command that answers directly may also need to
+ * rewrite what came before (`/compact` is the case); deciding the reply and
+ * the rewrite in one place keeps them from disagreeing about whether anything
+ * happened.
+ */
+export type InputEffect = {
+    transform?: string;
+} | {
+    handled: true;
+    reply?: string | Part[];
+    replace?: UIMessage[];
+} | undefined | void;
+/**
+ * Before each model call. `stop` ends the run before this step; `model` and
+ * `activeTools` apply to this step only.
+ */
+export type StepControlEffect = {
+    stop?: true;
+    model?: LanguageModel;
+    activeTools?: string[];
+} | undefined | void;
+/**
+ * EVERY moment receives identity. That is the point of carrying the principal
+ * on the turn rather than letting each extension close over one: a per-tenant
+ * toolset, a per-tenant veto, a per-tenant redaction rule and per-tenant error
+ * reporting all read the SAME principal, so two extensions cannot disagree
+ * about who a run is for.
+ *
+ * It arrives as a trailing `run` argument, which existing handlers may ignore:
+ * a function with fewer parameters stays assignable.
+ */
+export interface Hooks {
+    /** User text arrived, before anything runs. Earliest per-message moment. */
+    input?: Array<(info: {
+        text: string;
+        source: "user" | "extension";
+        messages: UIMessage[];
+    }, run: RunContext) => InputEffect | Promise<InputEffect>>;
+    /** First run of a conversation (no assistant message yet). Before before_agent_start. */
+    session_start?: Array<(messages: UIMessage[], run: RunContext) => StartEffect | Promise<StartEffect>>;
+    /**
+     * Every run, before the first step. Receives identity as well as messages: a
+     * store has to know who a chat belongs to at CLAIM time, not at the first
+     * step, or a scheduled run has nothing to rebuild the principal from.
+     */
+    before_agent_start?: Array<(messages: UIMessage[], run: RunContext) => StartEffect | Promise<StartEffect>>;
+    step_end?: Array<(messages: UIMessage[], info: StepInfo) => StepEffect | Promise<StepEffect>>;
+    instructions?: Array<(current: Instructions | undefined, ctx: StepContext) => InstructionsEffect | Promise<InstructionsEffect>>;
+    context?: Array<(messages: ModelMessage[], ctx: StepContext) => ContextEffect | Promise<ContextEffect>>;
+    /**
+     * Identity is OPTIONAL here alone, because `renderTranscript` runs on a load
+     * route where no run exists. Pass it when the caller knows it, which an
+     * authenticated route does.
+     */
+    render?: Array<(part: Part, ctx: {
+        stored: boolean;
+    } & Partial<RunContext>) => ViewEffect>;
+    register_tools?: Array<(tools: ToolSet, run: RunContext) => ToolSet>;
+    tool_call?: Array<(info: {
+        toolName: string;
+        toolCallId: string;
+        input: unknown;
+    }, run: RunContext) => ToolCallEffect | Promise<ToolCallEffect>>;
+    tool_result?: Array<(info: {
+        toolName: string;
+        toolCallId: string;
+        input: unknown;
+        output: unknown;
+        isError: boolean;
+        source: "server" | "client";
+    }, run: RunContext) => ToolResultEffect | Promise<ToolResultEffect>>;
+    step_start?: Array<(ctx: StepContext) => StepControlEffect | Promise<StepControlEffect>>;
+    /** The run failed. Fires before agent_end, which still fires. */
+    error?: Array<(info: {
+        error: unknown;
+        stepNumber: number;
+        messages: UIMessage[];
+    }, run: RunContext) => void | Promise<void>>;
+    agent_end?: Array<(info: {
+        runId: string;
+        principal: Principal;
+        messages: UIMessage[];
+        stepCount: number;
+        isAborted: boolean;
+        error?: unknown;
+        usage: StepUsage;
+    }) => void | Promise<void>>;
+}
+export type Moment = keyof Hooks;
+/** What a command answers with: text, parts, or parts plus a rewritten history. */
+export type CommandReply = string | Part[] | {
+    reply?: string | Part[];
+    replace?: UIMessage[];
+};
+export interface CommandOptions {
+    description: string;
+    /**
+     * Answer directly, no model call.
+     *
+     * `ctx.messages` is the FULL stored conversation, because commands run after
+     * the start moments — a client that posts only its newest turn does not
+     * shrink what a command can see.
+     */
+    handler?: (args: string, ctx: {
+        messages: UIMessage[];
+    }) => CommandReply | Promise<CommandReply>;
+    /** Or rewrite the user's text and let the run proceed. */
+    expand?: (args: string) => string | Promise<string>;
+}
+export interface RegisteredCommand extends CommandOptions {
+    name: string;
+    extension: string;
+}
+export interface Extension {
+    name: string;
+    hooks: Hooks;
+    commands: RegisteredCommand[];
+    /**
+     * Fail CLOSED. A throwing handler on a critical extension fails the run
+     * instead of being reported and skipped.
+     *
+     * Default is false, because one broken feature must never break the loop.
+     * But that rule is wrong for anything the run's correctness depends on: a
+     * persistence extension whose database is down has NOT "produced no effect",
+     * it has lost the step. Mark those critical.
+     */
+    critical?: boolean;
+}
+/** What the client needs to render a command palette. */
+export declare const listCommands: (extensions: Extension[]) => Array<{
+    name: string;
+    description: string;
+    extension: string;
+}>;
+export interface ContextOptions {
+    /** 'step' every call · 'run' once per request (default) · 'session' once per conversation, stored */
+    scope?: "step" | "run" | "session";
+    /** 'before-user' (default) prepends to the latest user message · 'system' appends to instructions */
+    position?: "before-user" | "system";
+}
+type Handler<K extends Moment> = NonNullable<Hooks[K]>[number];
+export interface ExtensionAPI {
+    /** Attach a handler to a moment. Several handlers on one moment run in order. */
+    on<K extends Moment>(moment: K, handler: Handler<K>): void;
+    /** Add a tool the model can call. */
+    registerTool(name: string, definition: ToolSet[string]): void;
+    /**
+     * A slash command. Sugar over `on('input', …)`: matches `/name …` and passes
+     * the rest as args. Return text from `handler` to answer without calling the
+     * model, or a string from `expand` to rewrite the prompt and let it run.
+     */
+    registerCommand(name: string, options: CommandOptions): void;
+    /**
+     * Change what the CUSTOMER sees, live and on load, without touching storage
+     * or the model's view. To hide a value from everyone, use `tool_result`.
+     */
+    registerRenderer(fn: Handler<"render">): void;
+    /**
+     * Intent: give the model information. Assembles the moments for you. The
+     * provider sees the transcript and the run — `run.principal` is how a
+     * per-tenant context is derived.
+     */
+    context(provider: (ctx: {
+        messages: UIMessage[];
+        run: RunContext;
+    }) => string | undefined | Promise<string | undefined>, options?: ContextOptions): void;
+    /** Intent: tell the customer something. The model never sees it. */
+    notify(provider: (info: StepInfo) => string | undefined | Promise<string | undefined>): void;
+}
+/** A conversation has not started while nothing has been said back. */
+export declare const isNewSession: (messages: UIMessage[]) => boolean;
+export interface DefineExtensionOptions {
+    /** See `Extension.critical`. */
+    critical?: boolean;
+}
+export declare function defineExtension(name: string, setup: (ext: ExtensionAPI) => void, options?: DefineExtensionOptions): Extension;
+export declare function defineExtension(name: string, setup: (ext: ExtensionAPI) => Promise<void>, options?: DefineExtensionOptions): Promise<Extension>;
+export {};
+//# sourceMappingURL=extension.d.ts.map

package/dist/extensions/extension.d.ts.map

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

package/dist/extensions/extension.js

@@ -0,0 +1,171 @@
+/**
+ * extension.ts — the extension model.
+ *
+ * An extension attaches handlers to MOMENTS of a turn. A handler returns an
+ * EFFECT, never a rewritten world; `undefined` means no effect. The effect type
+ * for each moment says exactly what is possible there, so you cannot do
+ * everything everywhere, and several extensions on one moment compose by a
+ * rule declared once per moment (see `compose.ts`).
+ *
+ * WHAT PERSISTS. The stored `UIMessage[]` is the only durable thing; everything
+ * else is recomputed each step. Three moments change it:
+ *
+ *   before_agent_start   injects or replaces messages
+ *   step_end             appends parts (append-only; never rewrites)
+ *   tool_result          the override IS the stored result, and what the model reads
+ *
+ * The rest are lenses and vanish after the step:
+ *
+ *   instructions, context   what the MODEL sees
+ *   render                  what the CUSTOMER sees, live AND on load
+ *
+ * So: mask a secret in `tool_result` and it is gone everywhere (usually right).
+ * Use `render` only for the rarer case where the model should keep the truth
+ * and the person should not see it.
+ *
+ * Ported from `experiment/agents-sdk`, where the same model ran 118/119 of its
+ * suite over a plain `streamText` loop — the moments do not depend on who owns
+ * the loop, which is why they can sit over `ToolLoopAgent` here.
+ */
+/** What the client needs to render a command palette. */
+export const listCommands = (extensions) => extensions.flatMap((e) => e.commands.map((c) => ({ name: c.name, description: c.description, extension: c.extension })));
+/** A conversation has not started while nothing has been said back. */
+export const isNewSession = (messages) => !messages.some((m) => m.role === "assistant");
+export function defineExtension(name, setup, options = {}) {
+    const hooks = {};
+    const on = (k, fn) => {
+        (hooks[k] ??= []).push(fn);
+    };
+    const registered = {};
+    const commands = [];
+    const api = {
+        on,
+        registerTool: (n, d) => {
+            registered[n] = d;
+        },
+        registerCommand: (cmdName, opts) => {
+            // Caught here, at registration, rather than as a throw the moment a user
+            // types the command — which a non-critical extension would swallow,
+            // sending the raw `/name` to the model as if nothing had matched.
+            if (!opts.handler && !opts.expand)
+                throw new Error(`Command "/${cmdName}" on extension "${name}" needs a handler or an expand.`);
+            commands.push({ ...opts, name: cmdName, extension: name });
+            on("input", async ({ text, messages }) => {
+                if (text !== `/${cmdName}` && !text.startsWith(`/${cmdName} `))
+                    return;
+                const args = text.slice(cmdName.length + 1).trim();
+                if (opts.expand)
+                    return { transform: await opts.expand(args) };
+                const answer = await opts.handler(args, { messages });
+                if (typeof answer === "string" || Array.isArray(answer))
+                    return { handled: true, reply: answer };
+                return { handled: true, reply: answer.reply, replace: answer.replace };
+            });
+        },
+        registerRenderer: (fn) => on("render", fn),
+        context(provider, { scope = "run", position = "before-user" } = {}) {
+            const type = `data-ctx-${name}`;
+            const place = (m, text) => {
+                const i = m.map((x) => x.role).lastIndexOf("user");
+                if (i < 0)
+                    return;
+                const u = m[i];
+                const content = typeof u.content === "string" ? [{ type: "text", text: u.content }] : u.content;
+                return {
+                    messages: [
+                        ...m.slice(0, i),
+                        { ...u, content: [{ type: "text", text }, ...content] },
+                        ...m.slice(i + 1),
+                    ],
+                };
+            };
+            const find = (msgs) => {
+                for (const m of msgs)
+                    for (const p of m.parts)
+                        if (p.type === type)
+                            return String(p.data);
+                return undefined;
+            };
+            if (scope === "session") {
+                on("before_agent_start", async (msgs, run) => {
+                    if (find(msgs))
+                        return;
+                    const text = await provider({ messages: msgs, run });
+                    if (text == null)
+                        return;
+                    // Injected BEFORE the final message by `compose.messagesIn`, so this
+                    // never becomes the assistant message the run streams into.
+                    return {
+                        inject: {
+                            id: crypto.randomUUID(),
+                            role: "assistant",
+                            parts: [{ type, data: text }],
+                        },
+                    };
+                });
+                on("render", (p) => (p.type === type ? { hide: true } : undefined));
+                if (position === "system")
+                    on("instructions", (_, ctx) => {
+                        const t = find(ctx.messages);
+                        return t ? { append: t } : undefined;
+                    });
+                else
+                    on("context", (m, ctx) => {
+                        const t = find(ctx.messages);
+                        return t ? place(m, t) : undefined;
+                    });
+                return;
+            }
+            // One extension object serves every turn of a runtime, concurrently. A
+            // run-scoped value is therefore keyed by run id — a single variable would
+            // let an overlapping turn's context reach the wrong model call. Populated
+            // at the start moment when there is one; a continuation (resume, decision)
+            // skips those and fills its entry on first use. Released at the end.
+            const perRun = new Map();
+            const valueFor = (msgs, run) => {
+                let p = perRun.get(run.runId);
+                if (!p) {
+                    p = Promise.resolve(provider({ messages: msgs, run }));
+                    perRun.set(run.runId, p);
+                }
+                return p;
+            };
+            if (scope === "run") {
+                on("before_agent_start", (msgs, run) => {
+                    perRun.set(run.runId, Promise.resolve(provider({ messages: msgs, run })));
+                });
+                on("agent_end", ({ runId }) => {
+                    perRun.delete(runId);
+                });
+            }
+            const get = (msgs, run) => scope === "run" ? valueFor(msgs, run) : provider({ messages: msgs, run });
+            if (position === "system")
+                on("instructions", async (_, ctx) => {
+                    const t = await get(ctx.messages, ctx);
+                    return t ? { append: t } : undefined;
+                });
+            else
+                on("context", async (m, ctx) => {
+                    const t = await get(ctx.messages, ctx);
+                    return t ? place(m, t) : undefined;
+                });
+        },
+        notify(provider) {
+            const type = `data-notice-${name}`;
+            on("step_end", async (_msgs, info) => {
+                const text = await provider(info);
+                return text == null ? undefined : { append: [{ type, data: text }] };
+            });
+        },
+    };
+    const finish = () => {
+        if (Object.keys(registered).length)
+            on("register_tools", (t) => ({ ...t, ...registered }));
+        return { name, hooks, commands, critical: options.critical ?? false };
+    };
+    // An async factory is awaited once, before anything runs — the pattern for
+    // one-time startup work (load config, open a client, discover models).
+    const result = setup(api);
+    return result instanceof Promise ? result.then(finish) : finish();
+}
+//# sourceMappingURL=extension.js.map

package/dist/extensions/extension.js.map

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

package/dist/extensions/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The extension seam: moments, effects, the composer, and the tool wiring.
+ *
+ * `RuntimeConfig.extensions` and `AgentConfig.extensions` take `Extension[]`.
+ * Omit both and the runtime behaves exactly as before — every moment is a
+ * no-op with no handlers attached.
+ */
+export * from "./extension.js";
+export * from "./compose.js";
+export * from "./tools.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/extensions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/extensions/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC"}

package/dist/extensions/index.js

@@ -0,0 +1,11 @@
+/**
+ * The extension seam: moments, effects, the composer, and the tool wiring.
+ *
+ * `RuntimeConfig.extensions` and `AgentConfig.extensions` take `Extension[]`.
+ * Omit both and the runtime behaves exactly as before — every moment is a
+ * no-op with no handlers attached.
+ */
+export * from "./extension.js";
+export * from "./compose.js";
+export * from "./tools.js";
+//# sourceMappingURL=index.js.map

package/dist/extensions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/extensions/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC"}

package/dist/extensions/tools.d.ts

@@ -0,0 +1,60 @@
+/**
+ * tools.ts — the tool-side wiring: `tool_call` vetoes and `tool_result`
+ * rewrites over a toolset, plus the small transcript helpers the runtime uses
+ * to apply start-moment and step-end effects.
+ */
+import type { ToolSet, UIMessage } from "ai";
+import type { Composed } from "./compose.js";
+import type { Part, RunContext } from "./extension.js";
+/** What a blocked tool call returns to the model. A result, not a throw, so the reason survives. */
+export interface BlockedToolOutput {
+    blocked: true;
+    reason: string;
+}
+/**
+ * Wrap every executable tool so `tool_call` can veto and `tool_result` can
+ * rewrite what gets stored. With no listener on either moment the toolset is
+ * returned untouched — the identity of every tool object is preserved.
+ *
+ * The AI SDK's `executeTool` sniffs synchronously for `Symbol.asyncIterator`,
+ * so a wrapper that returns a promise turns a streaming tool into a
+ * non-streaming one: no progress chunks, and a generator object as the output.
+ * Two paths follow from that, chosen once per run:
+ *
+ *   no `tool_call` listener   call `execute` synchronously, pass the iterable
+ *                             through, hold one value back so the FINAL yield
+ *                             is the hooked one. Streaming preserved.
+ *   a `tool_call` listener    the veto is async and must resolve before
+ *                             `execute` runs, so the result is a promise and
+ *                             progress chunks are collapsed. A gated tool
+ *                             cannot also stream; that is the trade.
+ */
+export declare function wrapTools(tools: ToolSet, hooks: Composed, run: RunContext): ToolSet;
+/**
+ * Fire `tool_result` for outputs a CLIENT produced.
+ *
+ * A client tool has no server `execute`, so the wrapper above never sees it:
+ * its output arrives in a later request, already in the transcript. Without
+ * this, an extension that inspects or redacts tool results silently covers
+ * server tools only, while the type promises both.
+ *
+ * Only parts after the last `step-start` are considered — the same slice the
+ * SDK's own auto-resubmit uses — so outputs an earlier run already handled are
+ * not fired again.
+ */
+export declare function fireClientToolResults(messages: UIMessage[], tools: ToolSet, hooks: Composed, run: RunContext): Promise<UIMessage[]>;
+/** Append parts onto the run's assistant message (or start one). */
+export declare function appendParts(messages: UIMessage[], parts: Part[]): UIMessage[];
+/**
+ * Fold `step_end` parts into an assistant message the SDK assembled without
+ * them: each step's appended parts go before the NEXT `step-start`, the last
+ * step's at the end — exactly where an append at that step boundary would have
+ * landed. `priorSteps` skips step-start parts the message already carried
+ * before this run (a continuation reuses the assistant message).
+ */
+export declare function insertStepParts(message: UIMessage, appendedByStep: Map<number, Part[]>, priorSteps?: number): UIMessage;
+/** The text of the newest user message, if any. */
+export declare const lastUserTextOf: (messages: UIMessage[]) => string | undefined;
+/** Rewrite the first text part of the newest user message (an `input` transform). */
+export declare const replaceLastUserText: (messages: UIMessage[], text: string) => UIMessage[];
+//# sourceMappingURL=tools.d.ts.map

package/dist/extensions/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/extensions/tools.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAC7C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAMvD,oGAAoG;AACpG,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,IAAI,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,UAAU,GAAG,OAAO,CAuFnF;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,SAAS,EAAE,EACrB,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,QAAQ,EACf,GAAG,EAAE,UAAU,GACd,OAAO,CAAC,SAAS,EAAE,CAAC,CA+CtB;AAED,oEAAoE;AACpE,wBAAgB,WAAW,CAAC,QAAQ,EAAE,SAAS,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,SAAS,EAAE,CAO7E;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,SAAS,EAClB,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,EACnC,UAAU,SAAI,GACb,SAAS,CAiBX;AAED,mDAAmD;AACnD,eAAO,MAAM,cAAc,GAAI,UAAU,SAAS,EAAE,KAAG,MAAM,GAAG,SAQ/D,CAAC;AAEF,qFAAqF;AACrF,eAAO,MAAM,mBAAmB,GAAI,UAAU,SAAS,EAAE,EAAE,MAAM,MAAM,KAAG,SAAS,EAalF,CAAC"}