@modelprofile.com/flexharness 10.12.0 → 10.14.0

package/dist_ts/classes.toolcatalog.d.ts

@@ -0,0 +1,90 @@
+import * as plugins from './plugins.js';
+import { type IFlexCatalogProposal, type IFlexCatalogProposalContext, type IFlexCodeModeLimits, type TFlexCatalogCallDecision, type IFlexCatalogDescribeInput, type IFlexCatalogDescribeResult, type IFlexCatalogMethod, type IFlexCatalogRunContext, type IFlexCatalogSearchInput, type IFlexCatalogToolDefinition, type IFlexToolCatalog, type IFlexToolCatalogOptions, type TFlexCatalogCallError } from './interfaces.js';
+interface IPreparedCall {
+    readonly success: true;
+    readonly method: string;
+    readonly params: unknown;
+    /** The method's `onCall` decision for the call; `run` without the hook. */
+    decide(context: IFlexCatalogRunContext<any>): Promise<TFlexCatalogCallDecision>;
+    run(context: IFlexCatalogRunContext<any>): ReturnType<IFlexCatalogMethod['run']>;
+}
+interface IFailedCall {
+    readonly success: false;
+    readonly error: TFlexCatalogCallError;
+}
+/**
+ * A tool catalog prepared for the model: search, TypeScript declarations, parameter validation and
+ * dispatch. FlexHarness builds one for every catalog a tool provider returns; it is public so a
+ * host can check what its catalog shows the model, and measure it, without running a session.
+ */
+export declare class FlexToolCatalog<TScope = unknown> {
+    private readonly core;
+    private readonly admitted;
+    /** The limits of `run_code`; absent while code mode is off. */
+    readonly codeMode: Readonly<IFlexCodeModeLimits> | undefined;
+    private namespaceTree?;
+    private constructor();
+    /**
+     * Prepares `catalog`. Preparing the same object again returns the cached preparation, so a host
+     * that returns one catalog object for every run pays for it once.
+     */
+    static create<TScope = unknown>(catalog: IFlexToolCatalog<TScope>, options?: IFlexToolCatalogOptions): Promise<FlexToolCatalog<TScope>>;
+    /** Every method path this catalog offers, sorted. */
+    get methods(): string[];
+    /** Every named type, sorted. */
+    get types(): string[];
+    /** The same catalog offering only `paths`. */
+    restrict(paths: Iterable<string>): FlexToolCatalog<TScope>;
+    has(path: string): boolean;
+    /**
+     * The built-in tools as the model sees them: the three catalog tools, and `run_code` in code
+     * mode. Their text depends only on the catalog and its options.
+     */
+    toolDefinitions(): Record<string, IFlexCatalogToolDefinition>;
+    private codeToolDefinition;
+    /** Hands proposed calls to the catalog's `onProposals` and returns what the model sees for them. */
+    propose(proposals: readonly IFlexCatalogProposal[], context: IFlexCatalogProposalContext<TScope>): Promise<unknown>;
+    /** Search results or a namespace listing as text. */
+    search(input?: IFlexCatalogSearchInput): string;
+    /**
+     * The declarations of `input.methods` and `input.types`. Method declarations bring the named
+     * types they use, minus `declaredTypes`, which a session already has.
+     */
+    describe(input: IFlexCatalogDescribeInput, options?: {
+        declaredTypes?: Iterable<string>;
+        maxBytes?: number;
+    }): IFlexCatalogDescribeResult;
+    /** The named types `describe_tools` results in `messages` declared. */
+    declaredTypesIn(messages: readonly plugins.ModelMessage[] | undefined): Set<string>;
+    /**
+     * Resolves and validates a call. A failure is the error `execute` reports to the model; success
+     * returns the run with the validated parameters. A schema validator that throws rejects.
+     */
+    prepareCall(method: unknown, params: unknown): Promise<IPreparedCall | IFailedCall>;
+    /** The real method and params of an `execute` input, when it names a method of this catalog. */
+    callTarget(input: unknown): {
+        method: string;
+        params: unknown;
+    } | undefined;
+    private isAdmitted;
+    private tree;
+    private topLevelLine;
+    private page;
+    private describeTypescript;
+    private describeJson;
+    /** Issues the method's JSON Schema finds in `value`. */
+    private validateStructure;
+    /** Issues reported by a zod, Standard Schema or AI SDK validator. */
+    private foreignIssues;
+}
+/**
+ * While a run has a catalog, its tool names are reserved (`run_code` in code mode too), and a
+ * method path must differ from every tool name.
+ */
+export declare const assertNoCatalogCollisions: (catalog: FlexToolCatalog<unknown>, tools: Readonly<Record<string, unknown>>) => void;
+/**
+ * The AI SDK schema of a built-in catalog tool: the definition's JSON Schema, validated with it, so a
+ * malformed call goes back to the model like any other invalid tool input.
+ */
+export declare const catalogToolInputSchema: <TInput>(definition: IFlexCatalogToolDefinition) => plugins.Schema<TInput>;
+export {};