@theoremjs/agents 0.0.0-stage → 0.3.1

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

@@ -0,0 +1,497 @@
+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, 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?: LabelTemplate;
+    activityPast?: LabelTemplate;
+    activityFailed?: LabelTemplate;
+    request?: LabelTemplate;
+    hiddenFromSettings?: boolean;
+}
+export interface ToolBase {
+    name: string;
+    description: string;
+    category: string;
+    access: ToolAccess;
+    paths: string[];
+    loadTier: ToolLoadTier;
+    permission: ToolPermission;
+    labels?: ToolLabels;
+}
+/**
+ * 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';
+    conflictsWith?: string[];
+}
+/** How a held tool call resumes: approved, refused, or retried after sign-in. */
+export interface InvokeToolResume {
+    gateKind?: ToolGateKind;
+    /**
+     * `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;
+    /**
+     * For `granted: false`: `declined` (default) fails as `declined`; `abandoned` and `expired`
+     * as `cancelled`.
+     */
+    cause?: ToolResumeCause;
+    /**
+     * 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. */
+    edited?: {
+        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. */
+    signedInFetch?: SignedInFetch;
+}
+/** A request body is text; the method defaults to GET. */
+export type SignedInRequest = {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+};
+/**
+ * A guarded fetch that carries the call's credential to the URL's own origin and
+ * nowhere else (not across a redirect, not to a host the OAuth token was not issued
+ * for). A response that refuses the credential (401, or 403 `insufficient_scope`)
+ * throws; the kernel turns it into a new sign-in or `sign_in.out_of_scope`.
+ */
+export type SignedInFetch = (url: string | URL, request?: SignedInRequest) => Promise<Response>;
+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;
+} | {
+    kind: 'artifact';
+    artifact: unknown;
+} | {
+    kind: 'warning';
+    warning: ToolWarning;
+} | {
+    kind: 'complete';
+    output: 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>;
+/**
+ * `input` and `output` stay on each concrete tool so `TOut` is inferred from `output`, not
+ * the handler's return type; moving them here silently breaks inference for stream handlers.
+ */
+export interface ToolHostHooks<TIn = unknown> {
+    inputSchema: Record<string, unknown>;
+    outputSchema: Record<string, unknown>;
+    /** Runs before the host's `pre_tool` `onStage`. */
+    preTool?: (input: TIn, ctx: ToolContext) => import('../stages.js').StageResult | undefined | Promise<import('../stages.js').StageResult | undefined>;
+    exposeToModel?: boolean;
+}
+export interface ToolOutputHooks<TOut = unknown> {
+    /** A source that fails `sourceSchema`, or a throw, is a `sources_invalid` warning and is not cited. */
+    sources?: (output: TOut) => Source[];
+}
+export interface FunctionToolDef<TIn = unknown, TOut = unknown> extends ToolBase, ToolHostHooks<TIn>, ToolOutputHooks<TOut> {
+    type: 'function';
+    input: z.ZodType<TIn>;
+    output: z.ZodType<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
+     * says) and hands the handler `ctx.signedInFetch`; the handler never sees the credential.
+     */
+    auth?: ToolAuthConfig;
+}
+/** 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;
+    /** The service the person signs in to, as they know it (e.g. "GitHub"); never blank. */
+    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 & {
+        resource: string;
+    }>;
+    scopes?: string[];
+    clientId?: string;
+    redirectUri?: string;
+}
+export interface HttpToolDef<TIn = unknown, TOut = unknown> extends ToolBase, ToolHostHooks<TIn>, ToolOutputHooks<TOut> {
+    type: 'http';
+    input: z.ZodType<TIn>;
+    output: z.ZodType<TOut>;
+    endpoint: string;
+    method: HttpMethod;
+    headers?: Record<string, string>;
+    auth?: ToolAuthConfig;
+    mapping?: {
+        pathParams?: string[];
+        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';
+    input: z.ZodType<TIn>;
+    output: z.ZodType<TOut>;
+    serverUrl: string;
+    mcpToolName: string;
+    headers?: Record<string, string>;
+    auth?: ToolAuthConfig;
+}
+/**
+ * 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>;
+} & ({
+    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;
+    path?: string;
+    sessionPermissions?: string[];
+    /** Tool ids eligible this turn. */
+    gated: ToolId[];
+    /** Opaque application context from `TurnRequest.host`; the kernel never reads it. */
+    host?: unknown;
+}
+/** 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;
+    /**
+     * The model call this invoke resumes; its events join the call its turn already announced.
+     * Absent for the host's own call, which gets a fresh id and is announced first.
+     */
+    callId?: string;
+    input: unknown;
+    /** Input for `profile.tools.t1Policy` selection. */
+    turnInput?: TurnInput;
+    /** T2 tools already promoted, e.g. restored from pause metadata; the host must have run the loader. */
+    promoted?: ToolId[];
+    /** Builtins resolve from this model. */
+    model?: string;
+    /** Cloned before use so concurrent invokes do not share mutable visibility state. */
+    snapshot?: TurnToolSnapshot;
+    resume?: InvokeToolResume;
+    sessionPermissions?: string[];
+    credentials?: ToolCredentialSource;
+    resolveHost?: ResolveHost;
+    path?: string;
+    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`. */
+    conversationId?: string;
+    /** Preserved on the trace record; the kernel does not interpret it. */
+    metadata?: Record<string, unknown>;
+    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 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'`.
+     * 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`. */
+export type ToolBodyOutcome = {
+    kind: 'ok';
+    outputRaw: unknown;
+    modelResult: ModelToolResult;
+} | {
+    kind: 'gated';
+    gate: ToolGate;
+} | {
+    kind: 'aborted';
+    aborted: true | {
+        reason?: string;
+    };
+} | {
+    kind: 'failed';
+    failure: ToolFailure;
+    callNotStarted: boolean;
+    /** The host refused the call (`deny`), rather than it failing. */
+    denied?: true;
+};
+export interface ModelToolResult {
+    finding: string;
+    /** Lean JSON for model reasoning — must not carry media bytes. */
+    data?: unknown;
+    /** Adapters wire these with the same fidelity as user input parts. */
+    parts?: InteractionPart[];
+    /**
+     * Already fenced and redacted by `executeRegisteredTool`. When absent (a recorded result
+     * formatted outside execution), `formatToolResult` guards the text itself under full detection.
+     */
+    modelText?: string;
+    provenance?: Provenance;
+    /** Directive signals found in the content; raises the turn's taint. */
+    suspicious?: GuardrailHit[];
+}

package/esm/src/kernel/tools/types.js

@@ -0,0 +1 @@
+export {};

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);
+}