@sema-agent/core/dist/agents/extra-tool-names.d.ts

Stateless, task-oriented AI agent core

/**
 * The roster a host declares for a delegation tool's `extraTools` factory (`SubagentToolOptions.extraToolNames`): every tool
 * the factory may inject at a spawn, by the names it answers to and its content class. Declared, the delegation tool's pool can
 * be listed again — the judgment of a denied-tools list and the memory content-origin reader read it exactly as they read the
 * static pool. Each spawn then checks the factory's products against it: a product the roster does not declare (a name or an
 * alias no entry carries), or declares nearer to home than the product says it is (its content class further out than the
 * entry's), refuses that spawn. The roster is an upper bound: a declared tool the factory did not inject this time is fine.
 *
 * One code for every way the declaration fails, `config.extra_tool_names`, with the arm on `detail.reason`: `shape` (the value
 * is not a roster — refused where the delegation tool is built), `undeclared_name` / `undeclared_origin` (a product the roster
 * does not cover — refused at the spawn). A host value is never printed or converted: a sentence names an entry's place and
 * the TYPE of what it found there.
 */
import type { ToolContentOrigin, ToolSpec } from "../core/types.js";
export declare const EXTRA_TOOL_NAMES_CODE = "config.extra_tool_names";
/** Which way a declaration failed (`detail.reason`). */
export type ExtraToolNamesReason = "shape" | "undeclared_name" | "undeclared_origin";
/** One declared tool, as the delegation tool keeps it (a frozen copy of the host's entry). */
export interface ExtraToolDeclaration {
    readonly name: string;
    readonly aliases?: readonly string[];
    readonly contentOrigin?: ToolContentOrigin;
}
/** The error a failed declaration is refused with: the code, and the arm on `detail.reason`. */
export declare function extraToolNamesError(message: string, reason: ExtraToolNamesReason): Error & {
    code: string;
    detail: {
        reason: ExtraToolNamesReason;
    };
};
/**
 * The host's declaration, read ONCE into frozen copies (a later change to the host's array does not reach the pool), or a
 * refusal (`shape`): a roster on a delegation tool with no factory, a value that is not a list, an entry that is not an object, a
 * name that is not a non-empty string, aliases that are not a list of non-empty strings, a content class outside the vocabulary,
 * or one spelling in two entries.
 */
export declare function readExtraToolNames(value: unknown, hasFactory: boolean): readonly ExtraToolDeclaration[];
/**
 * Whether one factory product is a tool the roster declares, as declared — answering to exactly one entry's names, its class no
 * further out than the entry's: undefined when it is, else the arm and the sentence (the delegation tool's name, the product's
 * offending name or class, the roster). A product's content class is its own
 * declaration when that is a vocabulary member, else external — the class an undeclared host tool reads as; an entry that
 * states no class allows any.
 */
export declare function undeclaredExtraTool(roster: readonly ExtraToolDeclaration[], product: ToolSpec, toolName: string): {
    reason: Exclude<ExtraToolNamesReason, "shape">;
    sentence: string;
} | undefined;
/** One row of a delegation tool's pool face (`ToolSpec.agentToolPool`): a tool's names and its declared content class. */
export interface DelegationPoolRow {
    name: string;
    aliases?: readonly string[];
    contentOrigin?: ToolContentOrigin;
}
/**
 * The pool a delegation tool's agent faces narrow FROM (`ToolSpec.agentToolPool`, read by the judgment of a denied-tools list and
 * by the memory content-origin reader): what the tool hands its children — its own captured set, not the parent's roster (the two
 * may differ, and a parent mounting only the delegation tool can still offer children a network tool) — plus the tools its factory
 * is declared to inject. Absent when a factory has no declared roster: that pool does not exist until the call happens, and the
 * readers take an absent pool as unknowable (the memory reader: external). Without an explicit pool the inherited surface is the
 * face — its spawn-time narrowing only removes entries.
 */
export declare function delegationPoolFace(staticPool: readonly ToolSpec[], hasFactory: boolean, roster: readonly ExtraToolDeclaration[] | undefined): DelegationPoolRow[] | undefined;
/** The first factory product the roster does not declare (see {@link undeclaredExtraTool}), or undefined when every one is declared. */
export declare function firstUndeclaredExtraTool(roster: readonly ExtraToolDeclaration[], products: readonly ToolSpec[], toolName: string): ReturnType<typeof undeclaredExtraTool>;