@telemai/sdk 0.1.0 → 0.2.0

package/dist/vercel/index.d.cts

@@ -0,0 +1,269 @@
+import { Schema } from 'ai';
+import { TrajectorySnapshot, Telem, SearchOptions, SearchResponse, FetchOptions, FetchResponse } from '../index.cjs';
+
+/** One flattened history entry: the wire shape. */
+type HistoryMessage = Record<string, string> & {
+    role: string;
+    content: string;
+};
+/** A flattened entry PLUS the identity the delta needs. The wire carries no id;
+ *  the host assigns one at build time (`"\u0000pos:" + index` where messages have
+ *  none of their own). */
+type FlatMessage = {
+    id: string;
+    entry: HistoryMessage;
+};
+/** The mode, read per call: `ancestors` (default) is phase 1, `history` is both
+ *  phases, `off` is the kill switch. Anything unrecognized is the DEFAULT, not
+ *  `off` — the rollback lever is the exact word. */
+type IncrementalMode = "ancestors" | "history" | "off";
+/** One ancestor entry this call chose not to send the context for. `entry` is the
+ *  very object inside `ancestors`, so restoring is a swap on the body about to be
+ *  re-sent — same node_key, same everything else. */
+type OmittedContext = {
+    key: string;
+    entry: Record<string, unknown>;
+    context: unknown;
+};
+/** One call's two unacknowledged promises, held until the response proves or
+ *  discards them. */
+type DeliveryPlan = {
+    scope: string;
+    /** Snapshot keys this request carries FULL context for: what a 2xx proves. */
+    sentWithContext: string[];
+    /** What this request WITHHELD, kept whole for the guard's 409. Empty is also
+     *  the gate: a 409 on a request that omitted nothing is a plain error. */
+    omitted: OmittedContext[];
+    /** The epoch is a guess (the host could not read its own state); the history
+     *  then goes out in FULL. */
+    epochDegraded: boolean;
+    history?: HistorySend;
+};
+/** The generation a watermark belongs to. `session_key` alone is not monotonic
+ *  and is best-effort; the last flattened id plus the count pin it down. */
+type HistoryEpoch = {
+    sessionKey: string;
+    lastMsgId: string;
+    msgCount: number;
+};
+/** What one call promised to the baseline. */
+type HistorySend = {
+    conversationKey: string;
+    epoch: HistoryEpoch;
+    sent: Array<{
+        id: string;
+        hash: string;
+    }>;
+};
+/** One ancestor entry as it rides in `ancestors`: a snapshot copy that may carry
+ *  `context` or `context_omitted`. */
+type PlannedAncestor = Record<string, unknown>;
+type IncrementalOptions = {
+    /** The mode, resolved per call. Default: `TELEM_INCREMENTAL` from the env. */
+    mode?: () => IncrementalMode;
+    /** The differential harness's bypass of the capability probe. Default:
+     *  `TELEM_INCREMENTAL_FORCE=1` from the env. Never production. */
+    forced?: () => boolean;
+};
+/**
+ * One instance's beliefs — the equivalent of one opencode plugin instance's
+ * factory closure. A host creates one per root agent and shares it with every
+ * child, so a child never re-sends what its parent already proved.
+ */
+declare function createIncrementalState(options?: IncrementalOptions): {
+    planAncestors: (plan: DeliveryPlan, chain: readonly Record<string, unknown>[]) => PlannedAncestor[];
+    planHistory: (plan: DeliveryPlan, conversationId: string, sessionKey: string, flat: readonly FlatMessage[]) => Promise<HistoryMessage[]>;
+    recordDelivery: (plan: DeliveryPlan, body: unknown) => void;
+    sendWithOmissionRetry: <T>(plan: DeliveryPlan, send: () => Promise<T>) => Promise<T>;
+};
+type IncrementalState = ReturnType<typeof createIncrementalState>;
+
+/** The execute options the integration reads. `ai@5`, `6` and `7` all carry
+ *  these three; the type is structural so nothing here depends on the peer's
+ *  own declarations. */
+type TelemVercelToolExecutionOptions = {
+    toolCallId: string;
+    /** The messages sent to the model for this step: no system prompt, and not
+     *  the assistant message that made the call. */
+    messages: readonly unknown[];
+    /** Forwarded to the Telem request: an abort stops it and skips the retry. */
+    abortSignal?: AbortSignal;
+};
+/** What `onResponse` sees after every successful search and fetch the tools make. */
+type TelemVercelCallEvent = {
+    kind: "search";
+    agent: TelemVercelAgent;
+    query: string | string[];
+    response: SearchResponse;
+} | {
+    kind: "fetch";
+    agent: TelemVercelAgent;
+    url: string | string[];
+    response: FetchResponse;
+};
+/** What the model reads back. Defaults: `search` the top results, compact;
+ *  `fetch` one page's status, error and text. Applies to subagents too. */
+type TelemVercelRenderOptions = {
+    search?: (response: SearchResponse) => unknown;
+    fetch?: (response: FetchResponse) => unknown;
+};
+/** One tool call, as the history renders it: the current call's `running` marker. */
+type TelemVercelToolCallRef = {
+    name: string;
+    input: unknown;
+};
+type TelemVercelAgentOptions = {
+    telem: Telem;
+    /** Names the integration in every derived key. Required, never defaulted:
+     *  it is what keeps one product's rows apart from another's. */
+    harness: string;
+    /** One id per agent conversation. Minted when absent. A chat that spans
+     *  several HTTP requests must pass a stable id (the chat id), or every request
+     *  becomes its own session. */
+    conversationId?: string;
+    /** The root-first chain this agent hangs under; `child()` fills it. */
+    ancestors?: readonly TrajectorySnapshot[];
+    /** `ancestors` (phase 1, the default), `history` (both phases) or `off`.
+     *  Unset reads `TELEM_INCREMENTAL` per call. */
+    incremental?: IncrementalMode;
+    /** What the model reads back from the two tools. Inherited by subagents. */
+    render?: TelemVercelRenderOptions;
+    /** Called after every successful search and fetch, root and subagents alike,
+     *  with the agent that made it and the response: for logging and metrics,
+     *  without replacing a tool. A throw or a rejection here is swallowed; it
+     *  never fails the call. */
+    onResponse?: (event: TelemVercelCallEvent) => void | Promise<void>;
+    /** Advanced: the ledgers to share. `child()` passes its parent's, so a child
+     *  never re-sends what the parent already proved delivered. */
+    incrementalState?: IncrementalState;
+};
+type TelemVercelSearchInput = {
+    query: string;
+    goal?: string;
+    context?: string;
+};
+type TelemVercelFetchInput = {
+    url: string;
+    goal?: string;
+};
+/** The default `render.search`: the top results, compact. */
+type TelemVercelSearchOutput = Array<{
+    provider: string;
+    title: string;
+    url: string;
+    summary: string | null;
+}>;
+/** The default `render.fetch`: one page's status, error and text. */
+type TelemVercelFetchOutput = {
+    status: string | undefined;
+    error: unknown;
+    content: string;
+};
+/** One AI SDK tool as a plain object: `description`, a branded `inputSchema`,
+ *  and `execute`. */
+type TelemVercelTool<INPUT> = {
+    description: string;
+    inputSchema: Schema<INPUT>;
+    execute: (input: INPUT, options: TelemVercelToolExecutionOptions) => Promise<unknown>;
+};
+type TelemVercelAgent = {
+    /** This conversation's identity: the id every derived key hangs off. */
+    readonly conversationId: string;
+    /** The root-first ancestor chain; empty for a root agent. */
+    readonly ancestors: readonly TrajectorySnapshot[];
+    readonly telem: Telem;
+    /** `telem_search` and `telem_fetch`, lineage attached from the execute options. */
+    readonly tools: {
+        telem_search: TelemVercelTool<TelemVercelSearchInput>;
+        telem_fetch: TelemVercelTool<TelemVercelFetchInput>;
+    };
+    /** The SDK search with this agent's lineage attached from `execution` — for a
+     *  tool of the user's own. Several calls with the same options are distinct nodes. */
+    search(query: string | string[], options?: SearchOptions | null, execution?: TelemVercelToolExecutionOptions): Promise<SearchResponse>;
+    /** The SDK fetch with this agent's lineage attached from `execution`. */
+    fetch(url: string | string[], options?: FetchOptions | null, execution?: TelemVercelToolExecutionOptions): Promise<FetchResponse>;
+    /** This agent frozen at the calling turn: what its subagents carry. Keyed on
+     *  the TURN, so subagents started by several tool calls of one turn share one
+     *  snapshot — which is why it carries nothing call-specific: siblings must send
+     *  one snapshot key with byte-identical context, or the backend's first writer
+     *  fixes a context the others never sent. `spawnedAt` defaults to now. */
+    snapshot(execution?: TelemVercelToolExecutionOptions, spawnedAt?: string): Promise<TrajectorySnapshot>;
+    /** A new agent whose chain ends with this agent's snapshot at the calling
+     *  turn, sharing the incremental ledgers. Call it inside the tool that starts
+     *  the subagent and hand the child's `tools` to the subagent. */
+    child(execution?: TelemVercelToolExecutionOptions, options?: {
+        conversationId?: string;
+        spawnedAt?: string;
+    }): Promise<TelemVercelAgent>;
+};
+/**
+ * Flatten the messages a tool was called with into the backend's history shape,
+ * one entry per message that carries text, reasoning or a tool call, each with
+ * its positional identity. `tool` messages are dropped: their calls are already
+ * `completed` markers, and a result can be a whole page. Reasoning parts land in
+ * `reasoning`, never in `content`.
+ *
+ * `current` is the call being made right now. It is not in `messages`, and the
+ * exporter reads the current call out of the LAST entry, so it is appended as a
+ * `running` marker built from the tool's own name and input.
+ */
+declare function telemVercelMessageHistory(messages: readonly unknown[], current?: TelemVercelToolCallRef): FlatMessage[];
+/** Whether subagents link by themselves on this runtime: `AsyncLocalStorage`
+ *  was found. When false, link them with `childTelemVercelTools`. */
+declare const telemVercelAutoNesting: boolean;
+/**
+ * Create one agent: a conversation identity, the tools that carry it, and the
+ * calls that attach it to a tool of the user's own. `createTelemVercelTools` is the
+ * front door; this is the layer under it.
+ */
+declare function createTelemVercelAgent(options: TelemVercelAgentOptions): TelemVercelAgent;
+/** A tool as the AI SDK sees it: anything with an optional `execute`. */
+type TelemVercelToolLike = {
+    execute?: (...args: any[]) => unknown;
+} & Record<string, unknown>;
+type TelemVercelToolsOptions<T extends Record<string, TelemVercelToolLike>> = Omit<TelemVercelAgentOptions, "incrementalState"> & {
+    /** Your own tools. Each is returned wrapped, so a run started inside it is
+     *  linked. Tools without `execute` pass through untouched. */
+    tools?: T;
+};
+type TelemVercelTools<T extends Record<string, TelemVercelToolLike>> = T & TelemVercelAgent["tools"];
+/**
+ * Build the tool set once and pass it to every `generateText`, `streamText` or
+ * `ToolLoopAgent` of one conversation. `telem_search` and `telem_fetch` carry
+ * lineage on every call; a run started inside any tool in the set — a subagent —
+ * links to the tool call that started it, with nothing else to write.
+ *
+ * Build it where the conversation starts, once per conversation: a set shared
+ * by several conversations records them as one.
+ *
+ * @example
+ * ```ts
+ * const delegate = tool({
+ *   description: "Research one question.",
+ *   inputSchema: z.object({ brief: z.string() }),
+ *   execute: async ({ brief }): Promise<string> => (await generateText({ model, tools, prompt: brief })).text,
+ * })
+ * const tools = createTelemVercelTools({ telem, harness: "my-app", tools: { delegate } })
+ * await generateText({ model, tools, prompt })
+ * ```
+ */
+declare function createTelemVercelTools<T extends Record<string, TelemVercelToolLike> = {}>(options: TelemVercelToolsOptions<T>): TelemVercelTools<T>;
+/**
+ * The tool set for a subagent, linked to the tool call that starts it, by hand.
+ * For a runtime without `AsyncLocalStorage` (`telemVercelAutoNesting` is false), or to name
+ * the child's conversation. Inside the tool that starts the subagent:
+ * `const subTools = await childTelemVercelTools(tools, options)`, then pass `subTools`
+ * to the subagent's generateText. The set is bound to the child outright, and the
+ * same line works one level down: the set knows which tool call it runs in.
+ */
+declare function childTelemVercelTools<T extends Record<string, TelemVercelToolLike>>(tools: TelemVercelTools<T>, execution: TelemVercelToolExecutionOptions, options?: {
+    conversationId?: string;
+}): Promise<TelemVercelTools<T>>;
+/**
+ * The agent a tool call belongs to, for a tool of your own that calls Telem:
+ * `const agent = await telemVercelAgentFor(tools, options); agent.search(query, {}, options)`.
+ * The root agent outside any run started by a tool; the linked child inside one.
+ */
+declare function telemVercelAgentFor(tools: object, execution?: TelemVercelToolExecutionOptions): Promise<TelemVercelAgent>;
+
+export { type TelemVercelAgent, type TelemVercelAgentOptions, type TelemVercelCallEvent, type TelemVercelFetchInput, type TelemVercelFetchOutput, type TelemVercelRenderOptions, type TelemVercelSearchInput, type TelemVercelSearchOutput, type TelemVercelTool, type TelemVercelToolCallRef, type TelemVercelToolExecutionOptions, type TelemVercelToolLike, type TelemVercelTools, type TelemVercelToolsOptions, childTelemVercelTools, createTelemVercelAgent, createTelemVercelTools, createTelemVercelAgent as default, telemVercelAgentFor, telemVercelAutoNesting, telemVercelMessageHistory };

package/dist/vercel/index.d.ts

@@ -0,0 +1,269 @@
+import { Schema } from 'ai';
+import { TrajectorySnapshot, Telem, SearchOptions, SearchResponse, FetchOptions, FetchResponse } from '../index.js';
+
+/** One flattened history entry: the wire shape. */
+type HistoryMessage = Record<string, string> & {
+    role: string;
+    content: string;
+};
+/** A flattened entry PLUS the identity the delta needs. The wire carries no id;
+ *  the host assigns one at build time (`"\u0000pos:" + index` where messages have
+ *  none of their own). */
+type FlatMessage = {
+    id: string;
+    entry: HistoryMessage;
+};
+/** The mode, read per call: `ancestors` (default) is phase 1, `history` is both
+ *  phases, `off` is the kill switch. Anything unrecognized is the DEFAULT, not
+ *  `off` — the rollback lever is the exact word. */
+type IncrementalMode = "ancestors" | "history" | "off";
+/** One ancestor entry this call chose not to send the context for. `entry` is the
+ *  very object inside `ancestors`, so restoring is a swap on the body about to be
+ *  re-sent — same node_key, same everything else. */
+type OmittedContext = {
+    key: string;
+    entry: Record<string, unknown>;
+    context: unknown;
+};
+/** One call's two unacknowledged promises, held until the response proves or
+ *  discards them. */
+type DeliveryPlan = {
+    scope: string;
+    /** Snapshot keys this request carries FULL context for: what a 2xx proves. */
+    sentWithContext: string[];
+    /** What this request WITHHELD, kept whole for the guard's 409. Empty is also
+     *  the gate: a 409 on a request that omitted nothing is a plain error. */
+    omitted: OmittedContext[];
+    /** The epoch is a guess (the host could not read its own state); the history
+     *  then goes out in FULL. */
+    epochDegraded: boolean;
+    history?: HistorySend;
+};
+/** The generation a watermark belongs to. `session_key` alone is not monotonic
+ *  and is best-effort; the last flattened id plus the count pin it down. */
+type HistoryEpoch = {
+    sessionKey: string;
+    lastMsgId: string;
+    msgCount: number;
+};
+/** What one call promised to the baseline. */
+type HistorySend = {
+    conversationKey: string;
+    epoch: HistoryEpoch;
+    sent: Array<{
+        id: string;
+        hash: string;
+    }>;
+};
+/** One ancestor entry as it rides in `ancestors`: a snapshot copy that may carry
+ *  `context` or `context_omitted`. */
+type PlannedAncestor = Record<string, unknown>;
+type IncrementalOptions = {
+    /** The mode, resolved per call. Default: `TELEM_INCREMENTAL` from the env. */
+    mode?: () => IncrementalMode;
+    /** The differential harness's bypass of the capability probe. Default:
+     *  `TELEM_INCREMENTAL_FORCE=1` from the env. Never production. */
+    forced?: () => boolean;
+};
+/**
+ * One instance's beliefs — the equivalent of one opencode plugin instance's
+ * factory closure. A host creates one per root agent and shares it with every
+ * child, so a child never re-sends what its parent already proved.
+ */
+declare function createIncrementalState(options?: IncrementalOptions): {
+    planAncestors: (plan: DeliveryPlan, chain: readonly Record<string, unknown>[]) => PlannedAncestor[];
+    planHistory: (plan: DeliveryPlan, conversationId: string, sessionKey: string, flat: readonly FlatMessage[]) => Promise<HistoryMessage[]>;
+    recordDelivery: (plan: DeliveryPlan, body: unknown) => void;
+    sendWithOmissionRetry: <T>(plan: DeliveryPlan, send: () => Promise<T>) => Promise<T>;
+};
+type IncrementalState = ReturnType<typeof createIncrementalState>;
+
+/** The execute options the integration reads. `ai@5`, `6` and `7` all carry
+ *  these three; the type is structural so nothing here depends on the peer's
+ *  own declarations. */
+type TelemVercelToolExecutionOptions = {
+    toolCallId: string;
+    /** The messages sent to the model for this step: no system prompt, and not
+     *  the assistant message that made the call. */
+    messages: readonly unknown[];
+    /** Forwarded to the Telem request: an abort stops it and skips the retry. */
+    abortSignal?: AbortSignal;
+};
+/** What `onResponse` sees after every successful search and fetch the tools make. */
+type TelemVercelCallEvent = {
+    kind: "search";
+    agent: TelemVercelAgent;
+    query: string | string[];
+    response: SearchResponse;
+} | {
+    kind: "fetch";
+    agent: TelemVercelAgent;
+    url: string | string[];
+    response: FetchResponse;
+};
+/** What the model reads back. Defaults: `search` the top results, compact;
+ *  `fetch` one page's status, error and text. Applies to subagents too. */
+type TelemVercelRenderOptions = {
+    search?: (response: SearchResponse) => unknown;
+    fetch?: (response: FetchResponse) => unknown;
+};
+/** One tool call, as the history renders it: the current call's `running` marker. */
+type TelemVercelToolCallRef = {
+    name: string;
+    input: unknown;
+};
+type TelemVercelAgentOptions = {
+    telem: Telem;
+    /** Names the integration in every derived key. Required, never defaulted:
+     *  it is what keeps one product's rows apart from another's. */
+    harness: string;
+    /** One id per agent conversation. Minted when absent. A chat that spans
+     *  several HTTP requests must pass a stable id (the chat id), or every request
+     *  becomes its own session. */
+    conversationId?: string;
+    /** The root-first chain this agent hangs under; `child()` fills it. */
+    ancestors?: readonly TrajectorySnapshot[];
+    /** `ancestors` (phase 1, the default), `history` (both phases) or `off`.
+     *  Unset reads `TELEM_INCREMENTAL` per call. */
+    incremental?: IncrementalMode;
+    /** What the model reads back from the two tools. Inherited by subagents. */
+    render?: TelemVercelRenderOptions;
+    /** Called after every successful search and fetch, root and subagents alike,
+     *  with the agent that made it and the response: for logging and metrics,
+     *  without replacing a tool. A throw or a rejection here is swallowed; it
+     *  never fails the call. */
+    onResponse?: (event: TelemVercelCallEvent) => void | Promise<void>;
+    /** Advanced: the ledgers to share. `child()` passes its parent's, so a child
+     *  never re-sends what the parent already proved delivered. */
+    incrementalState?: IncrementalState;
+};
+type TelemVercelSearchInput = {
+    query: string;
+    goal?: string;
+    context?: string;
+};
+type TelemVercelFetchInput = {
+    url: string;
+    goal?: string;
+};
+/** The default `render.search`: the top results, compact. */
+type TelemVercelSearchOutput = Array<{
+    provider: string;
+    title: string;
+    url: string;
+    summary: string | null;
+}>;
+/** The default `render.fetch`: one page's status, error and text. */
+type TelemVercelFetchOutput = {
+    status: string | undefined;
+    error: unknown;
+    content: string;
+};
+/** One AI SDK tool as a plain object: `description`, a branded `inputSchema`,
+ *  and `execute`. */
+type TelemVercelTool<INPUT> = {
+    description: string;
+    inputSchema: Schema<INPUT>;
+    execute: (input: INPUT, options: TelemVercelToolExecutionOptions) => Promise<unknown>;
+};
+type TelemVercelAgent = {
+    /** This conversation's identity: the id every derived key hangs off. */
+    readonly conversationId: string;
+    /** The root-first ancestor chain; empty for a root agent. */
+    readonly ancestors: readonly TrajectorySnapshot[];
+    readonly telem: Telem;
+    /** `telem_search` and `telem_fetch`, lineage attached from the execute options. */
+    readonly tools: {
+        telem_search: TelemVercelTool<TelemVercelSearchInput>;
+        telem_fetch: TelemVercelTool<TelemVercelFetchInput>;
+    };
+    /** The SDK search with this agent's lineage attached from `execution` — for a
+     *  tool of the user's own. Several calls with the same options are distinct nodes. */
+    search(query: string | string[], options?: SearchOptions | null, execution?: TelemVercelToolExecutionOptions): Promise<SearchResponse>;
+    /** The SDK fetch with this agent's lineage attached from `execution`. */
+    fetch(url: string | string[], options?: FetchOptions | null, execution?: TelemVercelToolExecutionOptions): Promise<FetchResponse>;
+    /** This agent frozen at the calling turn: what its subagents carry. Keyed on
+     *  the TURN, so subagents started by several tool calls of one turn share one
+     *  snapshot — which is why it carries nothing call-specific: siblings must send
+     *  one snapshot key with byte-identical context, or the backend's first writer
+     *  fixes a context the others never sent. `spawnedAt` defaults to now. */
+    snapshot(execution?: TelemVercelToolExecutionOptions, spawnedAt?: string): Promise<TrajectorySnapshot>;
+    /** A new agent whose chain ends with this agent's snapshot at the calling
+     *  turn, sharing the incremental ledgers. Call it inside the tool that starts
+     *  the subagent and hand the child's `tools` to the subagent. */
+    child(execution?: TelemVercelToolExecutionOptions, options?: {
+        conversationId?: string;
+        spawnedAt?: string;
+    }): Promise<TelemVercelAgent>;
+};
+/**
+ * Flatten the messages a tool was called with into the backend's history shape,
+ * one entry per message that carries text, reasoning or a tool call, each with
+ * its positional identity. `tool` messages are dropped: their calls are already
+ * `completed` markers, and a result can be a whole page. Reasoning parts land in
+ * `reasoning`, never in `content`.
+ *
+ * `current` is the call being made right now. It is not in `messages`, and the
+ * exporter reads the current call out of the LAST entry, so it is appended as a
+ * `running` marker built from the tool's own name and input.
+ */
+declare function telemVercelMessageHistory(messages: readonly unknown[], current?: TelemVercelToolCallRef): FlatMessage[];
+/** Whether subagents link by themselves on this runtime: `AsyncLocalStorage`
+ *  was found. When false, link them with `childTelemVercelTools`. */
+declare const telemVercelAutoNesting: boolean;
+/**
+ * Create one agent: a conversation identity, the tools that carry it, and the
+ * calls that attach it to a tool of the user's own. `createTelemVercelTools` is the
+ * front door; this is the layer under it.
+ */
+declare function createTelemVercelAgent(options: TelemVercelAgentOptions): TelemVercelAgent;
+/** A tool as the AI SDK sees it: anything with an optional `execute`. */
+type TelemVercelToolLike = {
+    execute?: (...args: any[]) => unknown;
+} & Record<string, unknown>;
+type TelemVercelToolsOptions<T extends Record<string, TelemVercelToolLike>> = Omit<TelemVercelAgentOptions, "incrementalState"> & {
+    /** Your own tools. Each is returned wrapped, so a run started inside it is
+     *  linked. Tools without `execute` pass through untouched. */
+    tools?: T;
+};
+type TelemVercelTools<T extends Record<string, TelemVercelToolLike>> = T & TelemVercelAgent["tools"];
+/**
+ * Build the tool set once and pass it to every `generateText`, `streamText` or
+ * `ToolLoopAgent` of one conversation. `telem_search` and `telem_fetch` carry
+ * lineage on every call; a run started inside any tool in the set — a subagent —
+ * links to the tool call that started it, with nothing else to write.
+ *
+ * Build it where the conversation starts, once per conversation: a set shared
+ * by several conversations records them as one.
+ *
+ * @example
+ * ```ts
+ * const delegate = tool({
+ *   description: "Research one question.",
+ *   inputSchema: z.object({ brief: z.string() }),
+ *   execute: async ({ brief }): Promise<string> => (await generateText({ model, tools, prompt: brief })).text,
+ * })
+ * const tools = createTelemVercelTools({ telem, harness: "my-app", tools: { delegate } })
+ * await generateText({ model, tools, prompt })
+ * ```
+ */
+declare function createTelemVercelTools<T extends Record<string, TelemVercelToolLike> = {}>(options: TelemVercelToolsOptions<T>): TelemVercelTools<T>;
+/**
+ * The tool set for a subagent, linked to the tool call that starts it, by hand.
+ * For a runtime without `AsyncLocalStorage` (`telemVercelAutoNesting` is false), or to name
+ * the child's conversation. Inside the tool that starts the subagent:
+ * `const subTools = await childTelemVercelTools(tools, options)`, then pass `subTools`
+ * to the subagent's generateText. The set is bound to the child outright, and the
+ * same line works one level down: the set knows which tool call it runs in.
+ */
+declare function childTelemVercelTools<T extends Record<string, TelemVercelToolLike>>(tools: TelemVercelTools<T>, execution: TelemVercelToolExecutionOptions, options?: {
+    conversationId?: string;
+}): Promise<TelemVercelTools<T>>;
+/**
+ * The agent a tool call belongs to, for a tool of your own that calls Telem:
+ * `const agent = await telemVercelAgentFor(tools, options); agent.search(query, {}, options)`.
+ * The root agent outside any run started by a tool; the linked child inside one.
+ */
+declare function telemVercelAgentFor(tools: object, execution?: TelemVercelToolExecutionOptions): Promise<TelemVercelAgent>;
+
+export { type TelemVercelAgent, type TelemVercelAgentOptions, type TelemVercelCallEvent, type TelemVercelFetchInput, type TelemVercelFetchOutput, type TelemVercelRenderOptions, type TelemVercelSearchInput, type TelemVercelSearchOutput, type TelemVercelTool, type TelemVercelToolCallRef, type TelemVercelToolExecutionOptions, type TelemVercelToolLike, type TelemVercelTools, type TelemVercelToolsOptions, childTelemVercelTools, createTelemVercelAgent, createTelemVercelTools, createTelemVercelAgent as default, telemVercelAgentFor, telemVercelAutoNesting, telemVercelMessageHistory };