@sema-agent/core/dist/brain/tool-call-id.d.ts

Stateless, task-oriented AI agent core

import type { Message } from "../internal/llm.js";
/** The character every folded id carries and no admitted id may: what keeps the two arms' outputs apart. */
export declare const TOOL_CALL_ID_FOLD_SEPARATOR = "~";
/**
 * Mint a placeholder tool-call id under `prefix`. Uniqueness is per-process and probabilistic
 * (`Math.random`), which is what every call site already relied on — the id never crosses a trust boundary
 * and is never a capability; it only has to not collide inside one response.
 */
export declare function mintFallbackToolCallId(prefix: string): string;
/** The two ids of one admitted tool call (see the module header). Equal unless the admission folded. */
export interface AdmittedToolCallId {
    readonly engineId: string;
    readonly wireId: string;
}
/** Why a call's id was folded: `"charset"` — the raw holds a character outside the admitted alphabet (a control byte,
 *  a space, a non-ASCII unit, or the fold separator); `"length"` — every character is admitted and it is longer than
 *  128; `"duplicate"` — an earlier call in the same response carried the same raw id, so this one was renamed. */
export declare const TOOL_CALL_ID_FOLD_REASONS: readonly ["charset", "length", "duplicate"];
export type ToolCallIdFoldReason = (typeof TOOL_CALL_ID_FOLD_REASONS)[number];
/** The fold reading of one non-empty raw id on its own: `undefined` ⇒ admitted verbatim; otherwise why its shape is
 *  folded (`"duplicate"` is a reading of the response, never of one id). */
export declare function toolCallIdFoldReason(raw: string): Exclude<ToolCallIdFoldReason, "duplicate"> | undefined;
/** Why a call carries two ids, read off the call itself (a built-in brain's call and a host brain's alike):
 *  `undefined` ⇒ one id, or an in-shape pair the admission did not mint (a host brain's own spelling); a provider id
 *  outside the admitted shape ⇒ its shape reason; an in-shape provider id beside an engine id of the rename arm's
 *  form ⇒ `"duplicate"`. */
export declare function toolCallFoldReason(call: {
    readonly id: string;
    readonly wireId?: unknown;
}): ToolCallIdFoldReason | undefined;
/** What ONE provider response has admitted so far — the state the rename arm reads: every provider id handed out
 *  (`handedOut`) and how many calls each raw id arrived on (`arrivals`). A brain holds one per response attempt
 *  ({@link responseToolCallIds}; a retried response starts a new one). */
export interface ResponseToolCallIds {
    readonly handedOut: Set<string>;
    readonly arrivals: Map<string, number>;
}
/** A fresh {@link ResponseToolCallIds} for one response attempt. */
export declare function responseToolCallIds(): ResponseToolCallIds;
/** Admit a provider-minted tool-call id (see the module header for the four arms). `response` = the response's
 *  {@link ResponseToolCallIds}; absent ⇒ the single-call reading (no rename). Pure apart from recording the call in
 *  `response`: announcing a fold is the run's job, read off the call ({@link toolCallFoldReason}). */
export declare function admitToolCallId(raw: unknown, prefix: string, response?: ResponseToolCallIds): AdmittedToolCallId;
/** The id a provider is handed for this call: its `wireId` when it carries one (a non-empty string), else its `id`. */
export declare function providerToolCallId(call: {
    readonly id: string;
    readonly wireId?: unknown;
}): string;
/**
 * The id a provider is handed for the tool RESULT of `engineId`, read off the calls in the same request's messages:
 * a result carries only the engine id, and the call it answers carries the provider's. A result whose call is not
 * in the messages is handed on under its engine id.
 */
export declare function providerResultIds(messages: readonly Message[]): (engineId: string) => string;