@tangle-network/agent-app 0.45.54 → 0.45.56

package/dist/tools/gating.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Capability gating — compose an agent session's tool surface from a
+ * product-defined capability registry.
+ *
+ * Products that let users pick what an agent can do (a "Studio" agent with the
+ * full build toolset vs a clean "Assistant" with none) all need the same
+ * mechanics: a registry of named capabilities, each unlocking proposal types
+ * and/or named tool groups, resolved against the product's
+ * {@link AppToolTaxonomy} into the concrete tools to expose. The mechanics are
+ * generic and live here; the capability VOCABULARY (ids, labels, which
+ * proposal types, which tool groups) is the product's.
+ */
+import type { AppToolTaxonomy } from './types';
+/** One toggleable tool group in a product's capability registry. */
+export interface ToolCapability {
+    id: string;
+    label: string;
+    description: string;
+    /** Proposal types this capability unlocks (intersected with the taxonomy,
+     *  so a capability can never widen the product's proposal surface). */
+    proposalTypes?: readonly string[];
+    /** Unlocks every taxonomy proposal type beyond the base set — the domain's
+     *  specialized long tail (risk_assessment, vuln_report, …). */
+    domainActions?: boolean;
+    /** Named product tool groups (e.g. 'sandbox', 'integrations') this
+     *  capability unlocks. The vocabulary is the product's; the resolver only
+     *  unions them. */
+    toolGroups?: readonly string[];
+}
+/** Resolve options for determining tool capabilities based on taxonomy, capabilities, and enabled IDs */
+export interface ResolveToolCapabilitiesOptions {
+    taxonomy: AppToolTaxonomy;
+    /** The product's full capability registry. */
+    capabilities: readonly ToolCapability[];
+    /** Enabled capability ids. `undefined` means full access (legacy callers
+     *  that don't send a capability set); an explicit `[]` means a pure chat
+     *  agent with no tools. Unknown ids are ignored. */
+    enabled: readonly string[] | undefined;
+    /** The shared base proposal types `domainActions` excludes. Defaults to
+     *  every type some capability names explicitly via `proposalTypes` — i.e.
+     *  "domain actions" are the taxonomy types no capability claims. */
+    baseProposalTypes?: readonly string[];
+}
+/** Describe resolved capabilities including proposal types and product tool groups to expose */
+export interface ResolvedToolCapabilities {
+    /** Proposal types to keep — feed to {@link restrictTaxonomy}. */
+    proposalTypes: string[];
+    /** Product tool groups to expose (deduped union across enabled caps). */
+    toolGroups: string[];
+}
+/**
+ * Resolve an enabled capability-id set against a taxonomy into the concrete
+ * tool surface. Fail-closed: only types present in the taxonomy survive, and
+ * an empty `enabled` set yields no tools at all.
+ */
+export declare function resolveToolCapabilities(opts: ResolveToolCapabilitiesOptions): ResolvedToolCapabilities;
+/**
+ * Restrict a taxonomy to a subset of proposal types, intersecting the
+ * regulated subset too — the regulated label survives restriction, so a
+ * narrowed agent can never launder a regulated type into an unregulated one.
+ */
+export declare function restrictTaxonomy(taxonomy: AppToolTaxonomy, allowed: readonly string[]): AppToolTaxonomy;

package/dist/tools/http.d.ts

@@ -0,0 +1,27 @@
+import { type ToolHeaderNames } from './auth';
+import { type DispatchOptions } from './dispatch';
+import { type AppToolName } from './openai';
+import type { AppToolDefinition } from './registry';
+/** Define options for handling tool requests including tool identification and token verification */
+export interface HandleToolRequestOptions extends DispatchOptions {
+    /** Which app tool this route serves — a built-in name or a product-registered
+     *  {@link AppToolDefinition} (auto-added to `customTools` for dispatch). */
+    tool: AppToolName | AppToolDefinition;
+    /** Verify the bearer capability token belongs to the header user. */
+    verifyToken: (userId: string, bearer: string) => Promise<boolean>;
+    headerNames?: ToolHeaderNames;
+    /** Optional model-facing description used by the MCP tools/list response. */
+    description?: string;
+    /** Product-specific values for the schedule_followup.priority schema. */
+    priorityValues?: readonly string[];
+    /** Optional success-message builder for a friendlier tool result. */
+    message?: (result: unknown) => string;
+}
+/**
+ * Handle one app-tool HTTP request end to end — the sandbox MCP path. The
+ * agent's per-turn HTTP MCP server POSTs here; this authenticates (header user
+ * + capability token), reads the args (MCP-alias tolerant), dispatches to the
+ * product handler, and returns a JSON Response. A product's route file becomes
+ * a one-liner: `export const action = ({ request }) => handleAppToolRequest(request, cfg)`.
+ */
+export declare function handleAppToolRequest(request: Request, opts: HandleToolRequestOptions): Promise<Response>;

package/dist/tools/index.d.ts

@@ -1,217 +1,12 @@
-import { T as ToolHeaderNames } from '../auth-BYtiazA4.js';
-export { A as AuthenticateOptions, C as CapabilitySubject, D as DEFAULT_HEADER_NAMES, a as ToolAuthResult, b as authenticateToolRequest, r as readToolArgs } from '../auth-BYtiazA4.js';
-import { e as AppToolTaxonomy, d as AppToolHandlers, b as AppToolDefinition, A as AppToolContext, c as AppToolProducedEvent, f as AppToolOutcome, a as AppToolName } from '../types-B25Mib1r.js';
-export { g as APP_TOOL_NAMES, h as AddCitationArgs, i as AddCitationResult, B as BuildAppToolsOptions, O as OpenAIFunctionTool, R as RenderUiArgs, j as RenderUiResult, S as ScheduleFollowupArgs, k as ScheduleFollowupResult, l as SubmitProposalArgs, m as SubmitProposalResult, n as buildAppToolOpenAITools, o as customToolToOpenAI, p as defineAppTool, q as findCustomTool, r as isAppToolName } from '../types-B25Mib1r.js';
-export { A as AppToolMcpServer, B as BuildHttpMcpServerOptions, a as BuildMcpServerOptions, D as DEFAULT_APP_TOOL_PATHS, S as ScopedMcpServerEntryOptions, b as buildAppToolMcpServer, c as buildHttpMcpServer, d as buildScopedMcpServerEntry, u as unresolvableSurfaceCredential } from '../mcp-xxoZZfor.js';
-export { C as CreateMcpToolHandlerOptions, M as MCP_PROTOCOL_VERSIONS, b as McpProtocolVersion, c as McpServerInfo, d as McpToolCallContent, a as McpToolDefinition, e as createMcpToolHandler } from '../mcp-rpc-DYwPlYbZ.js';
-import '@tangle-network/agent-interface';
-
-/** A correctable bad-input error a tool handler throws; the HTTP layer maps it
- *  to a 4xx with the code, the runtime layer to a failed tool_result. So the
- *  agent learns the call failed and can correct, instead of a silent success. */
-declare class ToolInputError extends Error {
-    code: string;
-    status: number;
-    constructor(code: string, message: string, status?: number);
-}
-
-/**
- * Per-user capability token — the sandbox→app auth primitive behind the
- * `verifyToken` seam in {@link authenticateToolRequest}.
- *
- * An app-agent runs inside the sandbox and reaches the host app back over HTTP
- * (the app tools, the integration-invoke bridge). The route must act AS the
- * connecting user without trusting any model-supplied identity, so the turn
- * mints a short HMAC token bound to the user id and bakes it into the per-turn
- * MCP server header; the route verifies it to recover the user.
- *
- * `HMAC-SHA256(secret, "user:<userId>")`, base64url, with an app-chosen prefix.
- * The token encodes no scopes — the hub's policy engine authorizes per action.
- * Fail-closed: with no secret, no token is minted (the caller MUST omit the MCP
- * server rather than fake an authorized call). WebCrypto only — runs on
- * Workers, Node, and the browser with no Node `crypto` dependency.
- */
-/** Define options for creating and verifying capability tokens including secret and prefix */
-interface CapabilityTokenOptions {
-    /** Shared HMAC secret. When absent, mint returns undefined / verify returns false. */
-    secret?: string;
-    /** Token prefix (namespaces the credential; lets verify reject foreign tokens
-     *  cheaply). Default `cap_`. */
-    prefix?: string;
-}
-/** Mint a capability token for `userId`, or `undefined` when no secret is
- *  configured (fail-closed — the caller omits the MCP server rather than fake it). */
-declare function createCapabilityToken(userId: string, opts: CapabilityTokenOptions): Promise<string | undefined>;
-/** Verify a capability token against `userId`. Returns false (never throws) for
- *  an unconfigured secret, a wrong prefix, a malformed token, or a mismatch. */
-declare function verifyCapabilityToken(userId: string, token: string, opts: CapabilityTokenOptions): Promise<boolean>;
-/** Define options for capability tokens that expire after a specified lifetime in milliseconds */
-interface ExpiringCapabilityTokenOptions extends CapabilityTokenOptions {
-    /** Token lifetime. Expired tokens verify false regardless of signature. */
-    expiresInMs: number;
-    /** Clock injection for tests; defaults to Date.now. */
-    now?: () => number;
-}
-/**
- * Mint an EXPIRING capability token: `<prefix><base64url(payload)>.<sig>` where
- * the payload carries `{ sub, exp, n }` (subject, epoch-ms expiry, random
- * nonce) and the signature is HMAC-SHA256 over the encoded payload. Use this
- * for user-initiated scoped channels (e.g. a per-sequence MCP endpoint) where
- * a captured token must not stay valid past its window; the bare
- * {@link createCapabilityToken} remains for turn-scoped tool bridges whose
- * mint+verify happen inside one request cycle. Fail-closed like the bare
- * variant: no secret → no token.
- */
-declare function createExpiringCapabilityToken(subject: string, opts: ExpiringCapabilityTokenOptions): Promise<string | undefined>;
-/** Verify an expiring token against `subject`: prefix, payload integrity,
- *  subject match, and expiry all checked; returns false (never throws) on any
- *  failure including a malformed payload. */
-declare function verifyExpiringCapabilityToken(subject: string, token: string, opts: CapabilityTokenOptions & {
-    now?: () => number;
-}): Promise<boolean>;
-
-/**
- * Capability gating — compose an agent session's tool surface from a
- * product-defined capability registry.
- *
- * Products that let users pick what an agent can do (a "Studio" agent with the
- * full build toolset vs a clean "Assistant" with none) all need the same
- * mechanics: a registry of named capabilities, each unlocking proposal types
- * and/or named tool groups, resolved against the product's
- * {@link AppToolTaxonomy} into the concrete tools to expose. The mechanics are
- * generic and live here; the capability VOCABULARY (ids, labels, which
- * proposal types, which tool groups) is the product's.
- */
-
-/** One toggleable tool group in a product's capability registry. */
-interface ToolCapability {
-    id: string;
-    label: string;
-    description: string;
-    /** Proposal types this capability unlocks (intersected with the taxonomy,
-     *  so a capability can never widen the product's proposal surface). */
-    proposalTypes?: readonly string[];
-    /** Unlocks every taxonomy proposal type beyond the base set — the domain's
-     *  specialized long tail (risk_assessment, vuln_report, …). */
-    domainActions?: boolean;
-    /** Named product tool groups (e.g. 'sandbox', 'integrations') this
-     *  capability unlocks. The vocabulary is the product's; the resolver only
-     *  unions them. */
-    toolGroups?: readonly string[];
-}
-/** Resolve options for determining tool capabilities based on taxonomy, capabilities, and enabled IDs */
-interface ResolveToolCapabilitiesOptions {
-    taxonomy: AppToolTaxonomy;
-    /** The product's full capability registry. */
-    capabilities: readonly ToolCapability[];
-    /** Enabled capability ids. `undefined` means full access (legacy callers
-     *  that don't send a capability set); an explicit `[]` means a pure chat
-     *  agent with no tools. Unknown ids are ignored. */
-    enabled: readonly string[] | undefined;
-    /** The shared base proposal types `domainActions` excludes. Defaults to
-     *  every type some capability names explicitly via `proposalTypes` — i.e.
-     *  "domain actions" are the taxonomy types no capability claims. */
-    baseProposalTypes?: readonly string[];
-}
-/** Describe resolved capabilities including proposal types and product tool groups to expose */
-interface ResolvedToolCapabilities {
-    /** Proposal types to keep — feed to {@link restrictTaxonomy}. */
-    proposalTypes: string[];
-    /** Product tool groups to expose (deduped union across enabled caps). */
-    toolGroups: string[];
-}
-/**
- * Resolve an enabled capability-id set against a taxonomy into the concrete
- * tool surface. Fail-closed: only types present in the taxonomy survive, and
- * an empty `enabled` set yields no tools at all.
- */
-declare function resolveToolCapabilities(opts: ResolveToolCapabilitiesOptions): ResolvedToolCapabilities;
-/**
- * Restrict a taxonomy to a subset of proposal types, intersecting the
- * regulated subset too — the regulated label survives restriction, so a
- * narrowed agent can never launder a regulated type into an unregulated one.
- */
-declare function restrictTaxonomy(taxonomy: AppToolTaxonomy, allowed: readonly string[]): AppToolTaxonomy;
-
-/** Define options for dispatching tools including handlers, taxonomy, custom tools, and approval policies */
-interface DispatchOptions {
-    handlers: AppToolHandlers;
-    taxonomy: AppToolTaxonomy;
-    /** Product-registered tools beyond the four built-ins. A called name that is
-     *  not a built-in is dispatched to the matching {@link AppToolDefinition.execute}
-     *  through this same validation/outcome path. */
-    customTools?: readonly AppToolDefinition[];
-    /** Per-call approval policy. When provided it OVERRIDES the static
-     *  `taxonomy.regulatedTypes` membership check, so products can gate by
-     *  cost threshold, environment, or first-use instead of always/never.
-     *  Fail-closed: a predicate that throws counts as "approval required". */
-    needsApproval?: (type: string, args: {
-        title: string;
-        description: string | null;
-    }, ctx: AppToolContext) => boolean | Promise<boolean>;
-    /** Called at the real side-effect site for proposals (proposal_created) and
-     *  generated views (artifact) so a consumer's completion oracle credits
-     *  persisted state. Omit when produced state isn't tracked. */
-    onProduced?: (event: AppToolProducedEvent) => void;
-}
-/**
- * The ONE place an app-tool call is validated, dispatched to the product's
- * handler, and turned into an {@link AppToolOutcome} + produced events. Shared
- * by the HTTP route layer and the agent-runtime executor so both paths apply
- * identical validation and identical side effects. A {@link ToolInputError}
- * (bad input the agent can correct) and any other throw both become
- * `{ ok: false }` — a tool call never silently "succeeds" without its effect.
- */
-declare function dispatchAppTool(toolName: string, rawArgs: Record<string, unknown>, ctx: AppToolContext, opts: DispatchOptions): Promise<AppToolOutcome>;
-/** HTTP status for a failed outcome — the handler's `ToolInputError.status`
- *  when present, else 400 for a validation reject. */
-declare function outcomeStatus(outcome: Extract<AppToolOutcome, {
-    ok: false;
-}>): number;
-
-/** Executes an app-tool call the model emits on the agent-runtime chat path.
- *  Plug into `runChatThroughRuntime({ appToolExecutor })` (or any loop that
- *  dispatches function tool_calls). */
-type AppToolRuntimeExecutor = (call: {
-    toolName: string;
-    args: Record<string, unknown>;
-}) => Promise<AppToolOutcome>;
-/** Define options for executing runtime tasks with a trusted per-turn context */
-interface RuntimeExecutorOptions extends DispatchOptions {
-    /** The trusted per-turn context — supplied directly (not from headers), since
-     *  the runtime path has no HTTP request. */
-    ctx: AppToolContext;
-}
-/**
- * Build the runtime executor for one turn. The agent-runtime backend must also
- * advertise the tools (`buildAppToolOpenAITools(taxonomy)` on the backend's
- * `tools`) for the model to call them; this executor fulfils each call against
- * the product's handlers and emits produced events via `opts.onProduced`.
- */
-declare function createAppToolRuntimeExecutor(opts: RuntimeExecutorOptions): AppToolRuntimeExecutor;
-
-/** Define options for handling tool requests including tool identification and token verification */
-interface HandleToolRequestOptions extends DispatchOptions {
-    /** Which app tool this route serves — a built-in name or a product-registered
-     *  {@link AppToolDefinition} (auto-added to `customTools` for dispatch). */
-    tool: AppToolName | AppToolDefinition;
-    /** Verify the bearer capability token belongs to the header user. */
-    verifyToken: (userId: string, bearer: string) => Promise<boolean>;
-    headerNames?: ToolHeaderNames;
-    /** Optional model-facing description used by the MCP tools/list response. */
-    description?: string;
-    /** Product-specific values for the schedule_followup.priority schema. */
-    priorityValues?: readonly string[];
-    /** Optional success-message builder for a friendlier tool result. */
-    message?: (result: unknown) => string;
-}
-/**
- * Handle one app-tool HTTP request end to end — the sandbox MCP path. The
- * agent's per-turn HTTP MCP server POSTs here; this authenticates (header user
- * + capability token), reads the args (MCP-alias tolerant), dispatches to the
- * product handler, and returns a JSON Response. A product's route file becomes
- * a one-liner: `export const action = ({ request }) => handleAppToolRequest(request, cfg)`.
- */
-declare function handleAppToolRequest(request: Request, opts: HandleToolRequestOptions): Promise<Response>;
-
-export { AppToolContext, AppToolDefinition, AppToolHandlers, AppToolName, AppToolOutcome, AppToolProducedEvent, type AppToolRuntimeExecutor, AppToolTaxonomy, type CapabilityTokenOptions, type DispatchOptions, type ExpiringCapabilityTokenOptions, type HandleToolRequestOptions, type ResolveToolCapabilitiesOptions, type ResolvedToolCapabilities, type RuntimeExecutorOptions, type ToolCapability, ToolHeaderNames, ToolInputError, createAppToolRuntimeExecutor, createCapabilityToken, createExpiringCapabilityToken, dispatchAppTool, handleAppToolRequest, outcomeStatus, resolveToolCapabilities, restrictTaxonomy, verifyCapabilityToken, verifyExpiringCapabilityToken };
+export { ToolInputError } from './errors';
+export { createCapabilityToken, verifyCapabilityToken, createExpiringCapabilityToken, verifyExpiringCapabilityToken, type CapabilityTokenOptions, type ExpiringCapabilityTokenOptions, } from './capability';
+export { authenticateToolRequest, readToolArgs, DEFAULT_HEADER_NAMES, type ToolHeaderNames, type AuthenticateOptions, type CapabilitySubject, type ToolAuthResult, } from './auth';
+export { APP_TOOL_NAMES, isAppToolName, buildAppToolOpenAITools, type AppToolName, type OpenAIFunctionTool, } from './openai';
+export { resolveToolCapabilities, restrictTaxonomy, type ToolCapability, type ResolveToolCapabilitiesOptions, type ResolvedToolCapabilities, } from './gating';
+export { defineAppTool, customToolToOpenAI, findCustomTool, type AppToolDefinition, } from './registry';
+export { dispatchAppTool, outcomeStatus, type DispatchOptions } from './dispatch';
+export { createAppToolRuntimeExecutor, type AppToolRuntimeExecutor, type RuntimeExecutorOptions } from './runtime';
+export { handleAppToolRequest, type HandleToolRequestOptions } from './http';
+export { buildHttpMcpServer, buildAppToolMcpServer, buildScopedMcpServerEntry, unresolvableSurfaceCredential, DEFAULT_APP_TOOL_PATHS, type AppToolMcpServer, type BuildHttpMcpServerOptions, type BuildMcpServerOptions, type ScopedMcpServerEntryOptions, } from './mcp';
+export { createMcpToolHandler, MCP_PROTOCOL_VERSIONS, type McpProtocolVersion, type McpServerInfo, type McpToolCallContent, type McpToolDefinition, type CreateMcpToolHandlerOptions, } from './mcp-rpc';
+export type { AppToolContext, AppToolTaxonomy, BuildAppToolsOptions, AppToolHandlers, AppToolProducedEvent, AppToolOutcome, SubmitProposalArgs, SubmitProposalResult, ScheduleFollowupArgs, ScheduleFollowupResult, RenderUiArgs, RenderUiResult, AddCitationArgs, AddCitationResult, } from './types';

package/dist/{mcp-rpc-DYwPlYbZ.d.ts → tools/mcp-rpc.d.ts}

@@ -16,16 +16,16 @@
  * tool results carrying the thrown message verbatim — the model reads WHY and
  * retries. Protocol misuse becomes a JSON-RPC error object.
  */
-declare const MCP_PROTOCOL_VERSIONS: readonly ["2025-06-18", "2025-03-26", "2024-11-05"];
+export declare const MCP_PROTOCOL_VERSIONS: readonly ["2025-06-18", "2025-03-26", "2024-11-05"];
 /** Resolve a valid protocol version from the predefined MCP_PROTOCOL_VERSIONS array */
-type McpProtocolVersion = (typeof MCP_PROTOCOL_VERSIONS)[number];
+export type McpProtocolVersion = (typeof MCP_PROTOCOL_VERSIONS)[number];
 /** Describe the structure of server information including name and version */
-interface McpServerInfo {
+export interface McpServerInfo {
     name: string;
     version: string;
 }
 /** One tool entry in the registry the handler owns. */
-interface McpToolDefinition<TEnv = Record<string, never>> {
+export interface McpToolDefinition<TEnv = Record<string, never>> {
     name: string;
     description: string;
     /** JSON Schema for the `params.arguments` object. */
@@ -35,7 +35,7 @@ interface McpToolDefinition<TEnv = Record<string, never>> {
     run(args: Record<string, unknown>, env: TEnv): Promise<unknown>;
 }
 /** Define options for creating a handler that manages MCP tools with environment support */
-interface CreateMcpToolHandlerOptions<TEnv = Record<string, never>> {
+export interface CreateMcpToolHandlerOptions<TEnv = Record<string, never>> {
     serverInfo: McpServerInfo;
     /** Full tool list; order IS the tools/list order. */
     tools: McpToolDefinition<TEnv>[];
@@ -46,7 +46,7 @@ interface CreateMcpToolHandlerOptions<TEnv = Record<string, never>> {
     /** Optional result formatter for callers that need structured tool errors. */
     formatResult?: (result: unknown, tool: McpToolDefinition<TEnv>) => McpToolCallContent;
 }
-interface McpToolCallContent {
+export interface McpToolCallContent {
     content: Array<{
         type: 'text';
         text: string;
@@ -62,6 +62,4 @@ interface McpToolCallContent {
  * the tool is found, before `run`) — non-`tools/call` paths skip it entirely
  * so metadata requests do not pay env-build cost.
  */
-declare function createMcpToolHandler<TEnv = Record<string, never>>(opts: CreateMcpToolHandlerOptions<TEnv>): (request: Request) => Promise<Response>;
-
-export { type CreateMcpToolHandlerOptions as C, MCP_PROTOCOL_VERSIONS as M, type McpToolDefinition as a, type McpProtocolVersion as b, type McpServerInfo as c, type McpToolCallContent as d, createMcpToolHandler as e };
+export declare function createMcpToolHandler<TEnv = Record<string, never>>(opts: CreateMcpToolHandlerOptions<TEnv>): (request: Request) => Promise<Response>;

package/dist/{mcp-xxoZZfor.d.ts → tools/mcp.d.ts}

@@ -1,7 +1,3 @@
-import { AgentProfileConfigValue } from '@tangle-network/agent-interface';
-import { A as AppToolContext, a as AppToolName, b as AppToolDefinition } from './types-B25Mib1r.js';
-import { T as ToolHeaderNames } from './auth-BYtiazA4.js';
-
 /**
  * The tagged-configuration contract for every MCP server this package emits.
  *
@@ -38,14 +34,18 @@ import { T as ToolHeaderNames } from './auth-BYtiazA4.js';
  * at all; {@link unresolvableSurfaceCredential} names that blocker instead of
  * emitting a reference that resolves to nothing.
  */
-
+import { type AgentProfileConfigValue } from '@tangle-network/agent-interface';
+import type { AppToolContext } from './types';
+import type { AppToolName } from './openai';
+import type { AppToolDefinition } from './registry';
+import type { ToolHeaderNames } from './auth';
 /** Default route path each app tool is served at. A product mounts its routes
  *  at these paths (or supplies its own via {@link BuildMcpServerOptions.paths}). */
-declare const DEFAULT_APP_TOOL_PATHS: Record<AppToolName, string>;
+export declare const DEFAULT_APP_TOOL_PATHS: Record<AppToolName, string>;
 /** The portable MCP server entry the sandbox SDK accepts (transport + url +
  *  tagged headers). Assignable to `AgentProfileMcpServer` without a cast —
  *  products spread it into their profile's `mcp` map. */
-interface AppToolMcpServer {
+export interface AppToolMcpServer {
     transport: 'http';
     url: string;
     headers: Record<string, AgentProfileConfigValue>;
@@ -70,9 +70,9 @@ interface AppToolMcpServer {
  * every product with per-document MCP surfaces hits it and was writing this
  * message itself.
  */
-declare function unresolvableSurfaceCredential(surface: string): never;
+export declare function unresolvableSurfaceCredential(surface: string): never;
 /** Define configuration options for building an HTTP MCP server including path, baseUrl, token env key, context, and description */
-interface BuildHttpMcpServerOptions {
+export interface BuildHttpMcpServerOptions {
     /** Route path on the app the sandbox POSTs to (e.g. `/api/tools/propose`). */
     path: string;
     /** App base URL the sandbox reaches back to (no trailing slash required). */
@@ -107,11 +107,11 @@ interface BuildHttpMcpServerOptions {
  * (integration_invoke) and via {@link buildAppToolMcpServer} for the four app
  * tools.
  */
-declare function buildHttpMcpServer(opts: BuildHttpMcpServerOptions): AppToolMcpServer;
+export declare function buildHttpMcpServer(opts: BuildHttpMcpServerOptions): AppToolMcpServer;
 /** Options for a per-document/scoped MCP channel entry (design-canvas,
  *  sequences, …). The capability token + path scope ONE resource; the document
  *  id lives in the path, never a tool argument. */
-interface ScopedMcpServerEntryOptions {
+export interface ScopedMcpServerEntryOptions {
     /** App base URL the sandbox reaches back to (trailing slash tolerated). */
     baseUrl: string;
     /** Product route serving the resource's MCP handler — id is part of the path. */
@@ -147,12 +147,12 @@ interface ScopedMcpServerEntryOptions {
  * Routing it through {@link buildHttpMcpServer} would unconditionally write a
  * `userId` identity header (here `undefined`), so it stays a distinct branch.
  */
-declare function buildScopedMcpServerEntry(opts: ScopedMcpServerEntryOptions & {
+export declare function buildScopedMcpServerEntry(opts: ScopedMcpServerEntryOptions & {
     label: string;
     defaultDescription: string;
 }): AppToolMcpServer;
 /** Define configuration options required to build an MCP server including tool, baseUrl, token, and context */
-interface BuildMcpServerOptions {
+export interface BuildMcpServerOptions {
     /** A built-in app tool name, or a product-registered {@link AppToolDefinition}.
      *  A custom tool supplies its route via `AppToolDefinition.path` (or `paths`). */
     tool: AppToolName | AppToolDefinition;
@@ -169,6 +169,4 @@ interface BuildMcpServerOptions {
  *  {@link buildHttpMcpServer} that resolves the tool's route path. Built-ins map
  *  through {@link DEFAULT_APP_TOOL_PATHS}; a custom tool uses its own `path`
  *  (or a `paths` override). */
-declare function buildAppToolMcpServer(opts: BuildMcpServerOptions): AppToolMcpServer;
-
-export { type AppToolMcpServer as A, type BuildHttpMcpServerOptions as B, DEFAULT_APP_TOOL_PATHS as D, type ScopedMcpServerEntryOptions as S, type BuildMcpServerOptions as a, buildAppToolMcpServer as b, buildHttpMcpServer as c, buildScopedMcpServerEntry as d, unresolvableSurfaceCredential as u };
+export declare function buildAppToolMcpServer(opts: BuildMcpServerOptions): AppToolMcpServer;

package/dist/tools/openai.d.ts

@@ -0,0 +1,28 @@
+import type { AppToolTaxonomy, BuildAppToolsOptions } from './types';
+/** The four canonical app-tool names. Stable identifiers the model calls in
+ *  both the sandbox (MCP server name) and runtime (function-tool name) paths. */
+export declare const APP_TOOL_NAMES: readonly ["submit_proposal", "schedule_followup", "render_ui", "add_citation"];
+/** Resolve a valid application tool name from the predefined list of tool names */
+export type AppToolName = (typeof APP_TOOL_NAMES)[number];
+/** Determine if a string matches a valid application tool name */
+export declare function isAppToolName(name: string): name is AppToolName;
+/** A minimal OpenAI Chat Completions function-tool shape — structurally
+ *  compatible with `@tangle-network/agent-runtime`'s `OpenAIChatTool` without
+ *  importing it (keeps this package runtime-free). */
+export interface OpenAIFunctionTool {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+/**
+ * Build the four app tools in OpenAI function-tool shape. `submit_proposal`'s
+ * `type` enum is the product's {@link AppToolTaxonomy.proposalTypes}; the
+ * model-facing descriptions and the follow-up priority enum default to the
+ * Tangle reference vocabulary and can be retuned via {@link BuildAppToolsOptions}
+ * (the tool names + JSON-Schema shapes stay fixed — they are mechanism). Pass
+ * the result to the agent-runtime backend's `tools`.
+ */
+export declare function buildAppToolOpenAITools(taxonomy: AppToolTaxonomy, opts?: BuildAppToolsOptions): OpenAIFunctionTool[];

package/dist/tools/registry.d.ts

@@ -0,0 +1,39 @@
+import type { AppToolContext } from './types';
+import type { OpenAIFunctionTool } from './openai';
+/**
+ * A product-defined app tool — the open registration seam.
+ *
+ * The four built-ins (`submit_proposal`/`schedule_followup`/`render_ui`/
+ * `add_citation`) are mechanism and stay hard-typed. This is how a product adds
+ * a fifth+ tool (e.g. gtm-agent's `set_config`) WITHOUT forking the shell: the
+ * `name` + JSON-Schema `parameters` are what the model sees, and `execute` is
+ * dispatched through the SAME validation/outcome path as the built-ins — a
+ * thrown {@link ToolInputError} becomes a correctable 4xx, any other throw an
+ * internal error, and a tool call never silently "succeeds" without its effect.
+ */
+export interface AppToolDefinition<Args = Record<string, unknown>> {
+    /** Stable identifier the model calls (and the MCP server name). Must not
+     *  collide with a built-in app tool. */
+    name: string;
+    /** Model-facing description. */
+    description: string;
+    /** JSON-Schema for the parameters (the OpenAI `function.parameters` object). */
+    parameters: Record<string, unknown>;
+    /** Default route path the per-turn MCP server / HTTP handler is mounted at.
+     *  Overridable per call via `paths`/`buildHttpMcpServer`. */
+    path?: string;
+    /** Fulfil the call; the return value is the tool result the model sees.
+     *  `ctx` is the trusted per-turn identity (never from tool args). */
+    execute: (args: Args, ctx: AppToolContext) => Promise<unknown> | unknown;
+}
+/**
+ * Validate + brand a product tool definition. Throws when the name is empty or
+ * collides with a built-in (those are reserved mechanism). Identity otherwise —
+ * call it at module scope so a bad definition fails at boot, not first use.
+ */
+export declare function defineAppTool<Args = Record<string, unknown>>(def: AppToolDefinition<Args>): AppToolDefinition<Args>;
+/** The OpenAI function-tool def for a custom tool — appended to the built-ins by
+ *  `buildAppToolOpenAITools`. */
+export declare function customToolToOpenAI(def: AppToolDefinition): OpenAIFunctionTool;
+/** Find a registered custom tool by the name the model called. */
+export declare function findCustomTool(name: string, tools: readonly AppToolDefinition[] | undefined): AppToolDefinition | undefined;

package/dist/tools/runtime.d.ts

@@ -0,0 +1,22 @@
+import { type DispatchOptions } from './dispatch';
+import type { AppToolContext, AppToolOutcome } from './types';
+/** Executes an app-tool call the model emits on the agent-runtime chat path.
+ *  Plug into `runChatThroughRuntime({ appToolExecutor })` (or any loop that
+ *  dispatches function tool_calls). */
+export type AppToolRuntimeExecutor = (call: {
+    toolName: string;
+    args: Record<string, unknown>;
+}) => Promise<AppToolOutcome>;
+/** Define options for executing runtime tasks with a trusted per-turn context */
+export interface RuntimeExecutorOptions extends DispatchOptions {
+    /** The trusted per-turn context — supplied directly (not from headers), since
+     *  the runtime path has no HTTP request. */
+    ctx: AppToolContext;
+}
+/**
+ * Build the runtime executor for one turn. The agent-runtime backend must also
+ * advertise the tools (`buildAppToolOpenAITools(taxonomy)` on the backend's
+ * `tools`) for the model to call them; this executor fulfils each call against
+ * the product's handlers and emits produced events via `opts.onProduced`.
+ */
+export declare function createAppToolRuntimeExecutor(opts: RuntimeExecutorOptions): AppToolRuntimeExecutor;