@theoremjs/agents 0.0.0-stage → 0.3.1

package/esm/src/kernel/tools/execute.d.ts

@@ -0,0 +1,100 @@
+import { type ToolBoundary } from '../../guardrails/boundaries.js';
+import { type DetectScope } from '../../guardrails/detect-at.js';
+import { type LabelOverrides } from '../../guardrails/labels.js';
+import type { SpanHandle, TraceAttributes } from '../../observability/trace-span.js';
+import { type ToolCallEnd } from '../engine/tool-trace.js';
+import type { InjectUnit } from '../stages.js';
+import type { InteractionPart, Profile, TurnEvent } from '../types.js';
+import { type AgentCaller } from './agent.js';
+import { startToolExecution, type ToolCallBase } from './events.js';
+import type { ToolExecutionCoordinator, ToolOperationClaim, ToolOperationOutcome } from './operation.js';
+import type { ToolRegistry } from './registry.js';
+import { type ToolStageSupport } from './stage-run.js';
+import type { FunctionToolDef, ModelToolResult, RegisteredAgentTool, ToolContext, ToolFailure, ToolGate, TurnToolSnapshot } from './types.js';
+export { checkPermission, isGateResumeGranted, isResumeContinuation, permissionGranted, } from './permission.js';
+/**
+ * The boundary a call of `name` is read at before its tool gets it: none for a provider builtin,
+ * whose text the kernel never reads. A call no tool takes is read as a function tool's.
+ */
+export declare function toolArgumentsBoundary(tools: ToolRegistry, name: string): ToolBoundary | undefined;
+/** Invalid entries are dropped. */
+export declare function coerceToolResultParts(raw: unknown): InteractionPart[] | undefined;
+/** A tool's output without its `parts` key, which carries media the model receives separately; any other value is returned as it is. */
+export declare function leanToolResultData(output: unknown): unknown;
+/** What the model is told of a function tool's output: a fixed finding for a hidden tool, a finding plus the output for an awaiting-user result, otherwise the tool's own summary or finding and its data. */
+export declare function projectForModel(tool: FunctionToolDef, output: unknown, labels?: LabelOverrides): ModelToolResult;
+export type ToolExecuteSettlement = {
+    modelResult?: ModelToolResult;
+    gated?: ToolGate;
+    /** A sign-in gate's note to the model; the gate event carries it as `readBack`. */
+    gateReadBack?: string;
+    aborted?: boolean | {
+        reason?: string;
+    };
+    callNotStarted?: boolean;
+    awaiting?: boolean;
+    failure?: ToolFailure;
+    /** Set when the body completed, including awaiting. */
+    outputRaw?: unknown;
+    denied?: true;
+    /** Landed after the provider tool result is recorded: the Interactions continuation must exist first. */
+    pendingInject?: InjectUnit[];
+};
+export declare function executeFunction(tools: ToolRegistry, tool: FunctionToolDef, rawInput: unknown, ctx: ToolContext, base: ToolCallBase, snapshot?: TurnToolSnapshot, stages?: ToolStageSupport, 
+/** Set when `tool` runs an agent tool: its trust, and its handler's failures and faults. */
+agent?: RegisteredAgentTool, beginBody?: (preparedInput: unknown) => Promise<ToolOperationClaim | undefined>): AsyncGenerator<TurnEvent, ToolExecuteSettlement>;
+/** Names the profile's loader when it can load the tool, so the model knows which call comes first. */
+export declare function notLoadedMessage(tool: {
+    name: string;
+    loadTier?: string;
+}, profile: Profile): string;
+export declare function executeBuiltin(tool: {
+    name: string;
+}, ctx: ToolContext, base: ToolCallBase, snapshot: TurnToolSnapshot): AsyncGenerator<TurnEvent, ToolExecuteSettlement>;
+export declare function authorizeToolReplay(args: {
+    tools: ToolRegistry;
+    profile: Profile;
+    name: string;
+    resume: ToolContext['resume'];
+    snapshot?: TurnToolSnapshot;
+    outcome?: ToolOperationOutcome;
+}): void;
+interface RegisteredToolCall {
+    execution?: ToolExecutionCoordinator;
+    invocation?: unknown;
+    onDispatch?: () => void;
+    beginBody?: (preparedInput: unknown) => Promise<ToolOperationClaim | undefined>;
+    tools: ToolRegistry;
+    profile: Profile;
+    name: string;
+    input: unknown;
+    callId: string;
+    ctx: Omit<ToolContext, 'callId' | 'profile' | 'operationId'> & {
+        operationId?: string;
+    };
+    snapshot?: TurnToolSnapshot;
+    stages?: ToolStageSupport;
+    /** Omitted: the call is not traced. The span is handed to the tool as `ctx.traceparent`. */
+    openSpan?: (name: string, attributes: TraceAttributes) => SpanHandle;
+    /** Defaults to `turnReadBack`; a transport that sends something else (Live's `functionResponse`) passes its own. */
+    readBack?: (settlement: ToolExecuteSettlement) => ToolCallEnd['result'];
+    /** Runs agent tool calls; without it an agent tool fails as a type the transport can't run. */
+    agents?: AgentCaller;
+    /** The canary and system instruction of the turn the model called from, read for in the arguments. */
+    scope?: DetectScope;
+}
+/**
+ * A gate nobody answered: a sign-in for `expiredService` whose link expired, or any other gate
+ * left behind. Both settle as `cancelled`.
+ */
+export declare function lapsedGateFailure(toolName: string, expiredService: string | undefined, labels: LabelOverrides | undefined): ToolFailure;
+/** Runs one registered tool call as a stream of turn events and returns how it settled; when `openSpan` is given the call is recorded as a tool span that ends with the outcome. */
+/**
+ * A call's arguments as its tool gets them, which is what the call's first
+ * event shows the host: a detector's placeholder where it redacts, and none
+ * when the call is stopped. A call no tool takes is read as a function tool's.
+ */
+export declare function shownToolArguments(call: Pick<RegisteredToolCall, 'tools' | 'profile' | 'name' | 'input' | 'scope'>): Record<string, unknown>;
+export declare function executeRegisteredTool(args: RegisteredToolCall): AsyncGenerator<TurnEvent, ToolExecuteSettlement>;
+export type { RegisteredToolCall, ToolStageSupport };
+export { startToolExecution };