@nxisai/agent-harness 0.2.4 → 0.3.0

package/dist/harness/tools/action-tools.d.ts

@@ -0,0 +1,213 @@
+import type { ModelContext, ModelContextTool, ModelContextToolInfo } from '../../types.js';
+import type { NxisAction } from '../../webmcp-contract.js';
+/** Marks a tool this module registered. */
+export declare const SITE_ACTION_HINT = "ai.nxis/siteAction";
+/** The `@id`s a site tool covers. */
+export declare const ACTION_IDS_HINT = "ai.nxis/actionIds";
+/** The pages those actions live on. */
+export declare const PAGE_URLS_HINT = "ai.nxis/pageUrls";
+/** What the page's own script names the same actions. */
+export declare const PAGE_TOOL_NAMES_HINT = "ai.nxis/pageToolNames";
+/**
+ * Marks a response that started a page change instead of submitting.
+ *
+ * Carried in `structuredContent`, where a renderer can find it without
+ * parsing prose.
+ */
+export declare const HANDOFF_RESULT = "ai.nxis/handoff";
+/** The field whose value says which of the covered actions a call means. */
+export declare const CHOOSER_HINT = "ai.nxis/chooser";
+/** That field's values, one per covered action, in the same order. */
+export declare const CHOICES_HINT = "ai.nxis/choices";
+/** The `@id` of the action a page tool came from, where the page records it. */
+export declare const ACTION_ID_HINT = "ai.nxis/actionId";
+/** One tool: the actions it covers, and how the caller picks between them. */
+export interface SiteActionTool {
+    /** The registered tool name. */
+    name: string;
+    /** The actions this tool can run, in a stable order. */
+    actions: NxisAction[];
+    /**
+     * The field that says which action to run.
+     *
+     * A real field of the form when one tells the actions apart, otherwise the
+     * added `target` field. Absent when the tool covers a single action.
+     */
+    discriminator?: string;
+    /** The value of {@link discriminator} for each action, in the same order. */
+    choices?: string[];
+    /** The tool as registered. */
+    definition: ModelContextTool;
+}
+/**
+ * An action name as a tool name.
+ *
+ * Mirrors the page script's own sanitiser, so the two agree on what a given
+ * action is called.
+ */
+export declare function sanitizeToolName(name: string): string;
+/**
+ * The name a site-wide tool is registered under.
+ *
+ * The stem is the action's own name, so the model still reads what the form is
+ * called and matches it to what the visitor asked for; the suffix says this is
+ * the one that reaches the form from any page, and keeps it clear of the
+ * page's own tool of the same name.
+ *
+ * @param actionName - The action's name, as the record gives it.
+ * @returns The tool name, within the length a registry accepts.
+ */
+export declare function siteToolName(actionName: string): string;
+/**
+ * A tool's name without the site-wide suffix, for showing to a person.
+ *
+ * `quote_form_anywhere` exists to be told apart from the page's `quote_form`
+ * in a registry; to the visitor both are the quote form.
+ */
+export declare function withoutSiteSuffix(toolName: string): string;
+/**
+ * Which field distinguishes the members of a group.
+ *
+ * The crawler records what a form already says about itself: on a per-business
+ * quote form, the `business` field carries that business's name as its default.
+ * A field every member fills with a different value is therefore the site's own
+ * way of naming the target, and is used in preference to anything invented.
+ *
+ * @param actions - The group's actions, in order.
+ * @returns The field name and each action's value, or null when no field
+ * separates them.
+ */
+export declare function findDiscriminator(actions: NxisAction[]): {
+    field: string;
+    values: string[];
+} | null;
+/** Where the agent currently is, so a tool can default to this page's action. */
+export interface BuildOptions {
+    /** The current page URL. Defaults to the browser's. */
+    href?: string;
+    /** Where a confirmed call waits while the browser moves. Defaults to `sessionStorage`. */
+    storage?: Storage | null;
+    /** How to go to another page. Defaults to assigning `location`. */
+    navigate?: (url: string) => void;
+    /** The conversation a travelling call should report back to. */
+    conversationId?: string;
+}
+/**
+ * Group the site's actions and build one tool definition for each group.
+ *
+ * Names are derived from the whole set rather than the order actions arrive
+ * in, so a tool is called the same thing on every page of the site.
+ *
+ * @param actions - The site's actions.
+ * @param mc - The registry the tools will run against, used to find the page's
+ * own tool when the agent is already on the right page.
+ * @param opts - The current page.
+ * @returns One entry per group, ordered by tool name.
+ */
+export declare function buildSiteActionTools(actions: NxisAction[], mc: ModelContext, opts?: BuildOptions): SiteActionTool[];
+/**
+ * Whether a tool is a site-wide one, reaching a form from any page.
+ *
+ * Checked against what this page built, then the tool's annotations, so it
+ * holds even where a native registry has stripped them.
+ */
+export declare function isSiteTool(tool: ModelContextToolInfo): boolean;
+/** Which page tool to look for: the action's id, and the name it would have. */
+export interface PageToolRef {
+    /** The action's `@id`. */
+    id: string;
+    /** The name the page's script derives from the action's name. */
+    name: string;
+}
+/** The reference for an action. */
+export declare const pageToolRef: (action: NxisAction) => PageToolRef;
+/** The page's own tool for an action: by recorded `@id`, else by name. */
+export declare function findPageTool(mc: ModelContext, ref: PageToolRef): Promise<ModelContextToolInfo | null>;
+/**
+ * Wait for the page's own tool to register.
+ *
+ * After a page change the agent is running before the page's script has read
+ * its JSON-LD, so the tool a resumed call needs does not exist yet.
+ *
+ * @param mc - The page's registry.
+ * @param ref - The tool to wait for.
+ * @param timeoutMs - How long to wait before giving up.
+ * @returns The tool, or null if it never appears.
+ */
+export declare function awaitPageTool(mc: ModelContext, ref: PageToolRef, timeoutMs?: number): Promise<ModelContextToolInfo | null>;
+/** Where a call is bound for, when that is not the page the agent is on. */
+export interface Handoff {
+    /** The action that will run. */
+    actionId: string;
+    /** The page it will run on. */
+    pageUrl: string;
+    /** What to call that destination in a sentence. */
+    label: string;
+    /** The name the page's own tool is expected to have. */
+    pageToolName: string;
+}
+/**
+ * Where a call to a site tool will have to go, if not here.
+ *
+ * Needs nothing but the tool, so a caller holding only what the registry
+ * reported — the harness, labelling a confirmation — can tell that pressing
+ * submit also means a page change.
+ *
+ * @param tool - The tool about to be called.
+ * @param values - The arguments resolved so far.
+ * @param href - The current page. Defaults to the browser's.
+ * @returns The destination, or null when the call runs here, when the tool is
+ * not one of these, or when the values do not yet say which action is meant.
+ */
+export declare function handoffFor(tool: ModelContextToolInfo, values: Record<string, unknown>, href?: string): Handoff | null;
+/**
+ * Register a tool for each of the site's actions.
+ *
+ * @param mc - The registry to register into.
+ * @param actions - The site's actions.
+ * @param opts - The current page.
+ * @returns The names registered. A name the registry already holds is left
+ * alone, and a registration it refuses is warned about rather than thrown.
+ */
+export declare function registerSiteActionTools(mc: ModelContext, actions: NxisAction[], opts?: BuildOptions): Promise<string[]>;
+/** How many site-wide tools a turn may carry, before relevance decides. */
+export declare const DEFAULT_SITE_TOOL_LIMIT = 8;
+/** Options for {@link selectSiteTools}. */
+export interface SelectOptions {
+    /** How many site-wide tools to keep. Defaults to {@link DEFAULT_SITE_TOOL_LIMIT}. */
+    limit?: number;
+    /** The current page. Defaults to the browser's. */
+    href?: string;
+}
+/**
+ * Narrow the site-wide tools to those this turn could plausibly need.
+ *
+ * Every registered tool's schema is written into every prompt, and a site
+ * with many distinct forms would fill the context with forms nobody asked
+ * about. Tools belonging to the page the agent is on are always kept — they
+ * are what "this form" means — and the rest compete on how well they answer
+ * what was asked.
+ *
+ * Only site-wide tools are ever dropped. The page's own tools and the
+ * retrieval tools are few, and losing one of those loses a capability rather
+ * than trimming a list.
+ *
+ * @param tools - The tools on offer this turn.
+ * @param goal - What the user asked for.
+ * @param opts - The budget and the current page.
+ * @returns The tools to show, in the order they arrived.
+ */
+export declare function selectSiteTools(tools: ModelContextToolInfo[], goal: string, opts?: SelectOptions): ModelContextToolInfo[];
+/**
+ * Drop page tools that a site tool already covers.
+ *
+ * On the page an action belongs to, the page's script registers its own tool
+ * and the site tool delegates to it. Both in the prompt would offer the model
+ * two ways to do one thing, and the second is chosen half the time.
+ *
+ * @param tools - Every tool the registry reported.
+ * @param href - The current page. Defaults to the browser's.
+ * @returns The tools to show the model.
+ */
+export declare function withoutShadowedTools(tools: ModelContextToolInfo[], href?: string): ModelContextToolInfo[];
+//# sourceMappingURL=action-tools.d.ts.map

package/dist/harness/tools/action-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-tools.d.ts","sourceRoot":"","sources":["../../../src/harness/tools/action-tools.ts"],"names":[],"mappings":"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"}