@theoremjs/agents 0.3.0 → 0.3.2

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

@@ -1,15 +1,21 @@
 import type { z } from 'zod';
+import type { TurnDestinations } from '../../guardrails/destinations.js';
 import type { ResolveHost } from '../../guardrails/network.js';
 import type { GuardrailHit, Provenance, TurnTaint } from '../../guardrails/types.js';
 import type { ToolCredentialSource } from '../auth/credential-source.js';
 import type { OAuthEndpoints } from '../auth/types.js';
-import type { AuthUnauthenticatedPolicy, HttpMethod, ToolAccess, ToolAuthType, ToolLoadTier, ToolPermission, ToolResumeCause } from '../schema.js';
-import type { Source, ToolCallEdit, ToolCallEvent, ToolCallRequest, ToolFailure, ToolGate, ToolPhaseEvent, ToolTraceStep, ToolWarning, TurnToolSnapshot, WireFunctionTool } from '../turn-events.js';
-import type { InteractionPart, Profile, ToolId, TurnInput, TurnTraceLink } from '../types.js';
+import type { AuthUnauthenticatedPolicy, HttpMethod, ToolAccess, ToolAuthType, ToolGateKind, ToolLoadTier, ToolPermission, ToolResumeCause } from '../schema.js';
+import type { RemovedItem, Source, ToolCallEdit, ToolCallEvent, ToolCallRequest, ToolFailure, ToolGate, ToolPhaseEvent, ToolTraceStep, ToolWarning, TurnToolSnapshot, WireFunctionTool } from '../turn-events.js';
+import type { InteractionPart, ModelId, Profile, ProfileId, ToolId, TurnInput, TurnRequest, TurnSpeech, TurnTraceLink } from '../types.js';
+import type { LabelTemplate } from './activity-label.js';
+import type { PageToolExecution, ToolExecutionCoordinator } from './operation.js';
+import type { UncheckedOutput } from './unchecked-output.js';
 export type { AuthUnauthenticatedPolicy, HttpMethod, ToolAccess, ToolAuthType, ToolCallEdit, ToolCallEvent, ToolCallRequest, ToolFailure, ToolGate, ToolPermission, ToolPhaseEvent, ToolTraceStep, ToolWarning, TurnToolSnapshot, WireFunctionTool, };
 export interface ToolLabels {
-    activity?: string;
-    activityPast?: string;
+    activity?: LabelTemplate;
+    activityPast?: LabelTemplate;
+    activityFailed?: LabelTemplate;
+    request?: LabelTemplate;
     hiddenFromSettings?: boolean;
 }
 export interface ToolBase {
@@ -22,19 +28,20 @@ export interface ToolBase {
     permission: ToolPermission;
     labels?: ToolLabels;
 }
-export interface BuiltinWire {
-    interactions?: string;
-    openRouter?: string;
-    live?: string;
-}
+/**
+ * A tool the provider runs. This is its entry in the tool list; the provider's
+ * adapter declares it (`ProviderAdapter.builtins`) and owns how it is sent.
+ */
 export interface BuiltinToolDef extends ToolBase {
     type: 'builtin';
-    wire: BuiltinWire;
     conflictsWith?: string[];
 }
+/** How a held tool call resumes: approved, refused, or retried after sign-in. */
 export interface InvokeToolResume {
+    gateKind?: ToolGateKind;
     /**
-     * `true` skips the confirm / permission / `preTool` re-ask (an `edited` call runs `preTool` in full);
+     * `true` approves this call. An unchanged confirmation skips the tool's completed `preTool` check.
+     * Permission and auth gates run `preTool` on resumption; edited arguments run it again.
      * `false` settles as a refusal with no body; omitted is a first attempt or an auth retry.
      */
     granted?: boolean;
@@ -44,8 +51,8 @@ export interface InvokeToolResume {
      */
     cause?: ToolResumeCause;
     /**
-     * For `granted: false`: the refused gate was a sign-in, so the model reads the `sign_in.*`
-     * note for its cause, naming the tool's `auth.service`.
+     * The gate answered was a sign-in. Granted, the model reads `sign_in.done` before the call's
+     * result; refused, the `sign_in.*` note for its cause. Both name the tool's `auth.service`.
      */
     signIn?: boolean;
     /** The user edited the arguments before approving; `from` is the model's proposed input. */
@@ -53,21 +60,46 @@ export interface InvokeToolResume {
         from: Record<string, unknown>;
     };
 }
+/**
+ * What the page did for a call to a tool it answers: its `output`, `timedOut` when the relay
+ * stopped waiting for it, or `unanswered` when the page has nothing that answers the tool.
+ */
+export type PageAnswer = {
+    output: unknown;
+    timedOut?: undefined;
+    unanswered?: undefined;
+} | {
+    timedOut: true;
+    unanswered?: undefined;
+} | {
+    unanswered: true;
+    timedOut?: undefined;
+};
 export interface ToolContext {
     profile: Profile;
     callId: string;
+    readonly operationId: string;
     sessionPermissions?: string[];
     path?: string;
     signal?: AbortSignal;
+    /**
+     * The turn as it stood when the step began. `visible`: the tools a call in this step may use;
+     * a tool loaded during the step is callable from the next one.
+     */
     turn?: {
         step: number;
         taint?: TurnTaint;
+        destinations?: TurnDestinations;
+        visible?: readonly ToolId[];
     };
     resume?: InvokeToolResume;
     credentials?: ToolCredentialSource;
     resolveHost?: ResolveHost;
     /** Opaque application context from `TurnRequest.host` / `InvokeToolRequest.host`; the kernel never reads it. */
     host?: unknown;
+    /** The page's answer to this call, for a tool with `answeredBy: 'page'`. */
+    page?: PageAnswer;
+    pageExecution?: PageToolExecution;
     /** W3C `traceparent` of this call's `execute_tool` span; parent a tool's own outbound spans on it. */
     traceparent?: string;
     /** Set for a function tool with `auth` once its credential resolved: requests carrying it. */
@@ -89,6 +121,14 @@ export type SignedInFetch = (url: string | URL, request?: SignedInRequest) => Pr
 export type ToolStreamEvent<TOut = unknown> = {
     kind: 'progress';
     data: unknown;
+}
+/**
+ * The next piece of what the tool is writing, for the host to preview. Each is read at the
+ * tool's `tool_output` boundary first; the model never reads it, only `complete`'s output.
+ */
+ | {
+    kind: 'draft';
+    text: string;
 } | {
     kind: 'trace';
     step: ToolTraceStep;
@@ -102,7 +142,7 @@ export type ToolStreamEvent<TOut = unknown> = {
     kind: 'complete';
     output: TOut;
 };
-export type SyncToolHandler<TIn, TOut> = (input: TIn, ctx: ToolContext) => TOut | Promise<TOut>;
+export type SyncToolHandler<TIn, TOut> = (input: TIn, ctx: ToolContext) => TOut | UncheckedOutput | Promise<TOut | UncheckedOutput>;
 export type StreamToolHandler<TIn, TOut> = (input: TIn, ctx: ToolContext) => AsyncGenerator<ToolStreamEvent<TOut>>;
 export type ToolHandler<TIn, TOut> = SyncToolHandler<TIn, TOut> | StreamToolHandler<TIn, TOut>;
 /**
@@ -124,7 +164,13 @@ export interface FunctionToolDef<TIn = unknown, TOut = unknown> extends ToolBase
     type: 'function';
     input: z.ZodType<TIn>;
     output: z.ZodType<TOut>;
-    handler: ToolHandler<TIn, TOut>;
+    /** Returns `output`'s type, or `uncheckedOutput(value)` for a value it cannot type. */
+    handler: ToolHandler<TIn, NoInfer<TOut>>;
+    /**
+     * `'page'`: the page the person is on answers the call, and the kernel supplies the handler.
+     * `output` checks what the page sent.
+     */
+    answeredBy?: 'page';
     /**
      * The service the handler acts on for the person. The kernel resolves the slot
      * before the handler runs (gating, refreshing, or telling the model as the policy
@@ -132,7 +178,7 @@ export interface FunctionToolDef<TIn = unknown, TOut = unknown> extends ToolBase
      */
     auth?: ToolAuthConfig;
 }
-/** How a tool that acts for the person signs in to the service; http, mcp and function tools share it. */
+/** How a tool that acts for the person signs in to the service; http, mcp, and function tools share it. */
 export interface ToolAuthConfig {
     slot: string;
     type: ToolAuthType;
@@ -140,6 +186,12 @@ export interface ToolAuthConfig {
     service: string;
     headerName?: string;
     headerPrefix?: string;
+    /**
+     * For a service that takes its API key in the URL (`?key=…`): the query parameter the key
+     * goes in, in place of a header. Only an `api_key` tool sets it, with no `headerName` or
+     * `headerPrefix`.
+     */
+    queryParam?: string;
     onUnauthenticated?: AuthUnauthenticatedPolicy;
     /** Named on the auth gate for the host's OAuth flow. */
     preResolved?: Partial<OAuthEndpoints & {
@@ -162,6 +214,19 @@ export interface HttpToolDef<TIn = unknown, TOut = unknown> extends ToolBase, To
         queryParams?: string[];
         bodyParam?: string;
     };
+    /** The service's own limit for one key; the kernel keeps this tool's requests within it. */
+    limit?: HttpToolLimit;
+    /**
+     * How long the service may take to answer, its body read included. Past it the call
+     * fails `timeout` and frees its place in the limit. Left out, a call waits as long as
+     * the caller's signal lets it.
+     */
+    timeoutMs?: number;
+}
+/** The most requests a service takes from one key in a window. */
+export interface HttpToolLimit {
+    requests: number;
+    windowMs: number;
 }
 export interface McpToolDef<TIn = unknown, TOut = unknown> extends ToolBase, ToolHostHooks<TIn>, ToolOutputHooks<TOut> {
     type: 'mcp';
@@ -172,21 +237,115 @@ export interface McpToolDef<TIn = unknown, TOut = unknown> extends ToolBase, Too
     headers?: Record<string, string>;
     auth?: ToolAuthConfig;
 }
-export type RegisteredTool<TIn = unknown, TOut = unknown> = BuiltinToolDef | FunctionToolDef<TIn, TOut> | HttpToolDef<TIn, TOut> | McpToolDef<TIn, TOut>;
-export type ToolDefinitionInput<TIn = unknown, TOut = unknown> = BuiltinToolDef | (Omit<FunctionToolDef<TIn, TOut>, 'inputSchema' | 'outputSchema'> & {
+/**
+ * What an agent tool call carries: the text, and whatever else the called
+ * profile's `inputs` declares. `speech` is for a speech profile.
+ */
+export interface AgentToolInput extends Pick<TurnInput, 'slots' | 'attachments' | 'voice'> {
+    text: string;
+    speech?: TurnSpeech;
+}
+/** What an agent tool returns: the called agent's reply. Media rides as `parts`, citations as `sources`. */
+export interface AgentToolOutput {
+    /** The reply's text; absent when the reply is `structured`, whose text is the same JSON. */
+    text?: string;
+    structured?: unknown;
+    /** Items the called profile's item rules removed from `structured`, each with why. */
+    removed?: RemovedItem[];
+    parts?: InteractionPart[];
+    /** What the called agent cited; the caller's turn cites them too. */
+    sources?: Source[];
+}
+/** A channel of an agent tool's input that the called profile's `inputs` declares. */
+export type AgentToolChannel = 'attachments' | 'voice' | 'slots';
+/**
+ * A tool whose call runs one turn of another registered agent. That agent is a
+ * standalone profile; the tool is how another agent's model calls it. Its input
+ * is what that profile's `inputs` declares; the host can reshape a call (`onAgentCall`).
+ */
+export interface AgentToolDef extends ToolBase {
+    type: 'agent';
+    /** A text, image, or speech profile, registered before this tool. Nothing it can call may gate. */
+    profile: ProfileId;
+    /** Calls to this tool in one turn of its caller. Omit: only `maxSteps` bounds them. */
+    maxCallsPerTurn?: number;
+    /** What the calling model reads on a field of the tool's input, by field. A field the profile does not take is refused. */
+    fieldText?: Partial<Record<keyof AgentToolInput, string>>;
+    /**
+     * Fields the calling model fills that only the host reads. `onAgentCall` gets them as
+     * `hostInput` and turns them into the agent's input; they are never sent to the agent.
+     * A name the input already has is refused, and a call without the hook is a config error.
+     */
+    hostFields?: Record<string, z.ZodType>;
+    /** Channels the profile takes that the calling model can't fill; only `onAgentCall` sends them. */
+    hostOnly?: AgentToolChannel[];
+    preTool?: ToolHostHooks<AgentToolInput>['preTool'];
+    exposeToModel?: boolean;
+}
+export interface RegisteredAgentTool extends AgentToolDef, ToolHostHooks<AgentToolInput>, ToolOutputHooks<AgentToolOutput> {
+    input: z.ZodType<AgentToolInput>;
+    output: z.ZodType<AgentToolOutput>;
+}
+/** An agent tool call, as the host's `onAgentCall` sees it before the agent runs. */
+export interface AgentCall {
+    /** The agent tool's name. */
+    tool: string;
+    callId: string;
+    /** The agent the tool runs. */
+    profile: ProfileId;
+    input: AgentToolInput;
+    /** What the model sent in the tool's `hostFields`; absent when the tool declares none. */
+    hostInput?: Record<string, unknown>;
+    /** The agent whose model made the call. */
+    caller: ProfileId;
+    /** 1 for a call from the host's own turn; one more for each agent tool it came through. */
+    depth: number;
+    /** The outermost request's `metadata`. */
+    metadata?: Record<string, unknown>;
+    signal?: AbortSignal;
+}
+/**
+ * What the host sets on the called agent's turn. The kernel fixes its profile,
+ * signal, trace parent, and hook. `provider` runs the turn; omit it to use the
+ * caller's, which works only when both are on the same provider and protocol.
+ * `host` is what the called agent's tools read as `ctx.host`; omit it and they
+ * read none, because the caller's is not passed down.
+ */
+export interface AgentCallRequest extends Partial<Pick<TurnRequest, 'input' | 'speech' | 'effort' | 'builtInArgs' | 'metadata' | 'onStage' | 'conversationId' | 'host'>> {
+    model?: ModelId;
+    provider?: import('../protocols/runtime.js').ProviderHostOptions;
+}
+/** Return nothing to run the agent on what the model sent; `refuse` is read back to the model. */
+export type AgentCallHook = (call: AgentCall) => AgentCallRequest | {
+    refuse: string;
+} | undefined | Promise<AgentCallRequest | {
+    refuse: string;
+} | undefined>;
+/** A tool in a registry: builtin, function, HTTP, MCP, or agent. */
+export type RegisteredTool<TIn = unknown, TOut = unknown> = BuiltinToolDef | FunctionToolDef<TIn, TOut> | HttpToolDef<TIn, TOut> | McpToolDef<TIn, TOut> | RegisteredAgentTool;
+/** A function tool as registered: it has a `handler`, or the page answers it. */
+export type FunctionToolInput<TIn = unknown, TOut = unknown> = Omit<FunctionToolDef<TIn, TOut>, 'inputSchema' | 'outputSchema' | 'handler' | 'answeredBy'> & {
     input: z.ZodType<TIn>;
     output: z.ZodType<TOut>;
-}) | (Omit<HttpToolDef<TIn, TOut>, 'inputSchema' | 'outputSchema'> & {
+} & ({
+    handler: ToolHandler<TIn, NoInfer<TOut>>;
+    answeredBy?: 'page';
+} | {
+    answeredBy: 'page';
+    handler?: undefined;
+});
+export type ToolDefinitionInput<TIn = unknown, TOut = unknown> = BuiltinToolDef | FunctionToolInput<TIn, TOut> | (Omit<HttpToolDef<TIn, TOut>, 'inputSchema' | 'outputSchema'> & {
     input: z.ZodType<TIn>;
     output: z.ZodType<TOut>;
 }) | (Omit<McpToolDef<TIn, TOut>, 'inputSchema' | 'outputSchema'> & {
     input: z.ZodType<TIn>;
     output: z.ZodType<TOut>;
-});
+}) | AgentToolDef;
 export interface PromoteLoadedResult {
     promoted: ToolId[];
     failure?: ToolFailure;
 }
+/** What a tool's loader is told: the profile, the input, and the path. */
 export interface ToolLoadContext {
     profile: Profile;
     input?: TurnInput;
@@ -197,9 +356,13 @@ export interface ToolLoadContext {
     /** Opaque application context from `TurnRequest.host`; the kernel never reads it. */
     host?: unknown;
 }
-/** Picks which eligible T1 tools to wire at turn start. */
+/** Picks which allowed T2 tools to load at turn start. */
 export type ToolPolicy = (ctx: ToolLoadContext) => ToolId[] | Promise<ToolId[]>;
+/** A request to run a held tool call outside a turn. */
 export interface InvokeToolRequest {
+    execution?: ToolExecutionCoordinator;
+    /** invariant: Only the trusted host restores the kernel-issued identity from saved authority. */
+    operationId?: string;
     profile: string;
     name: string;
     /**
@@ -224,6 +387,9 @@ export interface InvokeToolRequest {
     signal?: AbortSignal;
     /** Handed to the tool as `ctx.host`; the kernel never reads it. */
     host?: unknown;
+    /** The page's answer, when this invoke answers a `page` gate. */
+    page?: PageAnswer;
+    pageExecution?: PageToolExecution;
     /** W3C `traceparent` of the host span this invoke runs under. */
     traceparent?: string;
     /** Recorded as `gen_ai.conversation.id`. */
@@ -233,24 +399,68 @@ export interface InvokeToolRequest {
     links?: TurnTraceLink[];
     /** Receives `pre_tool` / `post_tool` only. */
     onStage?: import('../stages.js').StageHandler;
+    /** Runs an agent tool's turn; an agent tool needs it, or `onAgentCall` returning one. */
+    provider?: import('../protocols/runtime.js').ProviderHostOptions;
+    /** As `TurnRequest.onAgentCall`, for an agent tool this invoke runs. */
+    onAgentCall?: AgentCallHook;
 }
+/** One of the host's calls in a step. */
+export interface InvokeToolStepCall {
+    name: string;
+    /**
+     * The model's call this runs, already announced by its turn; absent for the host's own
+     * call, which gets a fresh id and is announced by the step.
+     */
+    callId?: string;
+    /** invariant: Only the trusted host restores the kernel-issued identity from saved authority. */
+    operationId?: string;
+    input: unknown;
+}
+/**
+ * A request to run several calls outside a turn, as one step. Everything but the calls is
+ * shared by all of them. A call that answers an approval or a page resumes on its own,
+ * through `InvokeToolRequest`.
+ */
+export interface InvokeToolStepRequest extends Omit<InvokeToolRequest, 'name' | 'callId' | 'operationId' | 'input' | 'resume' | 'page'> {
+    calls: InvokeToolStepCall[];
+}
+/** The tools a profile may use and how they load. */
 export interface ProfileToolsSpec {
     /** Custom tools only; builtins live on `models.*.builtInTools`. */
     allow: ToolId[];
-    /** Returns only ids already allowed with `loadTier: 'T1'`. Not supported on `type: 'live'`. */
+    /** Returns ids already allowed with `loadTier: 'T2'` to load at turn start. Not supported on `type: 'live'`. */
     t1Policy?: ToolPolicy;
-    /** Must be in `allow`; completing with `{ loaded: string[] }` promotes those T2 ids. Not on `type: 'live'`. */
+    /**
+     * Must be in `allow`; completing with `{ loaded: string[] }` promotes those T2 ids. Not on `type: 'live'`.
+     * The tools it loads can be called from the next step.
+     */
     t2Loader?: ToolId;
+    /**
+     * `true`: a step's calls run side by side, each body starting once the calls its `pre_tool`
+     * `waitFor` names have settled. Left out or `false`: one at a time, in the order the model made them.
+     */
+    parallel?: boolean;
 }
 /** Live declarations cannot be added mid-session, so every allowed tool is wired at setup as if T0. */
 export interface LiveProfileToolsSpec {
     allow: ToolId[];
+    /**
+     * `true`: the calls of one model message, run as a step through `invokeToolStep`, run side by
+     * side, each body starting once the calls its `pre_tool` `waitFor` names have settled. Left out
+     * or `false`: one at a time, in the order the model made them.
+     */
+    parallel?: boolean;
 }
 /** Every id in `allow` is invokable with no visibility tiers and no path gating. */
 export interface HostProfileToolsSpec {
     allow: ToolId[];
+    /**
+     * `true`: the calls of one `invokeToolStep` run side by side, each body starting once the calls
+     * its `pre_tool` `waitFor` names have settled. Left out or `false`: one at a time, in the order given.
+     */
+    parallel?: boolean;
 }
-/** Every transport returns this; one settlement projects, guards and runs `post_tool`. */
+/** Every transport returns this; one settlement projects, guards, and runs `post_tool`. */
 export type ToolBodyOutcome = {
     kind: 'ok';
     outputRaw: unknown;

package/esm/src/kernel/tools/unchecked-output.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A handler result with no type until the call runs, such as what a client
+ * sent back. The tool's `output` schema checks the value when the call
+ * settles, and a mismatch fails the call as `invalid_output`.
+ */
+export declare class UncheckedOutput {
+    readonly value: unknown;
+    constructor(value: unknown);
+}
+/**
+ * Return a value the handler cannot type as the tool's `output`. A handler
+ * that returns anything else must return `output`'s type, or it does not compile.
+ */
+export declare function uncheckedOutput(value: unknown): UncheckedOutput;

package/esm/src/kernel/tools/unchecked-output.js

@@ -0,0 +1,18 @@
+/**
+ * A handler result with no type until the call runs, such as what a client
+ * sent back. The tool's `output` schema checks the value when the call
+ * settles, and a mismatch fails the call as `invalid_output`.
+ */
+export class UncheckedOutput {
+    value;
+    constructor(value) {
+        this.value = value;
+    }
+}
+/**
+ * Return a value the handler cannot type as the tool's `output`. A handler
+ * that returns anything else must return `output`'s type, or it does not compile.
+ */
+export function uncheckedOutput(value) {
+    return new UncheckedOutput(value);
+}