@tangle-network/agent-app 0.45.54 → 0.45.56

package/dist/teams-react/index.d.ts

@@ -1,145 +1,14 @@
-import { f as WorkspaceRole } from '../roles-B4nU3jDi.js';
-import { c as InvitationPermission, d as InvitationStatus, b as InvitationEmailStatus } from '../invitations-DoYMvXea.js';
-import * as react from 'react';
-
 /**
- * Seams between the teams React surface and the host app. Everything here is
- * interface-only and callback-driven: the components never import an app's
- * router, fetch client, or toast system. The host passes data in and supplies
- * the async callbacks (which it backs with `./teams/members-api` or
- * `./teams/invitations-api` over fetch), so the same panel mounts in any app.
+ * React surface for the teams module: the MembersPanel (list / invite / role /
+ * remove), the InvitationsPanel (email-invitation flow + history), and the
+ * InviteAcceptPage (`/invite/:token`), plus their seams. Everything is
+ * callback-driven — no app router, fetch client, or toast import — so any app
+ * mounts these and wires them to `./teams/members-api` or
+ * `./teams/invitations-api` over fetch.
+ *
+ * Never re-exported from the package root: `react` is an optional peer (the
+ * `web-react` precedent). DOM access begins only inside component render. A
+ * `React.lazy` code-split entry lives at `./teams-react/lazy`.
  */
-
-/** One member row as the panel renders it — the shape `members-api` returns. */
-interface MemberView {
-    id: string;
-    userId: string | null;
-    role: WorkspaceRole;
-    name: string | null;
-    email: string | null;
-    /** null/undefined = pending invite (not yet accepted). */
-    acceptedAt?: Date | number | null;
-    /** true = inherited org owner/admin access (managed at the org level). */
-    inherited?: boolean;
-}
-/** Define properties and callbacks for managing members and their roles in a workspace panel */
-interface MembersPanelProps {
-    members: MemberView[];
-    /** The viewer's effective role — gates which controls are interactive. */
-    currentRole: WorkspaceRole;
-    /** Invite a member; resolve with the shareable invite URL (or void). */
-    onInvite(input: {
-        email: string;
-        role: WorkspaceRole;
-    }): Promise<{
-        inviteUrl?: string;
-    } | void>;
-    /** Change a member's role. */
-    onChangeRole(input: {
-        memberId: string;
-        role: WorkspaceRole;
-    }): Promise<void>;
-    /** Remove a member. */
-    onRemove(input: {
-        memberId: string;
-    }): Promise<void>;
-    /** Optional toast/notice hook; defaults to a no-op (host owns its UX). */
-    onNotice?(notice: {
-        kind: 'success' | 'error';
-        message: string;
-    }): void;
-    /**
-     * Show the built-in invite form. Default `true`. An app that drives invites
-     * through `InvitationsPanel` (the rich email flow) sets this `false` so the
-     * members panel is list-only and the two don't present competing invite UIs.
-     */
-    showInviteForm?: boolean;
-}
-/** One invitation row as `InvitationsPanel` renders it — the shape `invitations-api` returns. */
-interface InvitationView {
-    id: string;
-    email: string;
-    permissions: InvitationPermission;
-    status: InvitationStatus;
-    emailStatus: InvitationEmailStatus;
-    /** Date | epoch-ms | ISO string — normalized to a Date for display. */
-    expiresAt: Date | number | string;
-    /** Shareable accept link, for copy-to-clipboard. */
-    inviteUrl: string;
-}
-/** Define properties and callbacks for managing workspace invitations and user roles */
-interface InvitationsPanelProps {
-    invitations: InvitationView[];
-    /** The viewer's effective role — gates whether the invite controls are interactive. */
-    currentRole: WorkspaceRole;
-    /** Create an invitation (sends the email); resolve with the shareable URL (or void). */
-    onInvite(input: {
-        email: string;
-        role: WorkspaceRole;
-    }): Promise<{
-        inviteUrl?: string;
-    } | void>;
-    /** Resend the invitation email. */
-    onResend(input: {
-        invitationId: string;
-    }): Promise<void>;
-    /** Revoke a pending invitation. */
-    onRevoke(input: {
-        invitationId: string;
-    }): Promise<void>;
-    /** Copy the invite link; defaults to `navigator.clipboard.writeText`. */
-    onCopy?(input: {
-        inviteUrl: string;
-    }): void | Promise<void>;
-    /** Optional toast/notice hook; defaults to a no-op (host owns its UX). */
-    onNotice?(notice: {
-        kind: 'success' | 'error';
-        message: string;
-    }): void;
-}
-/** Define possible statuses for the acceptance state of an invitation */
-type InviteAcceptStatus = 'pending' | 'invalid' | 'already-accepted' | 'expired' | 'revoked';
-/** Describe details of an accepted invite including status, workspace, inviter, role, emails, and expiration */
-interface InviteAcceptDetails {
-    status: InviteAcceptStatus;
-    /** Workspace the invite grants access to. */
-    workspaceName?: string | null;
-    /** Who sent it, if known. */
-    inviterName?: string | null;
-    /** Role the invite grants. */
-    role?: WorkspaceRole | null;
-    /** Email the invite was addressed to. */
-    inviteEmail?: string | null;
-    /** The signed-in user's email, or null if not signed in. */
-    currentUserEmail?: string | null;
-    /** When the invite expires (for display). Date | epoch-ms | ISO string. */
-    expiresAt?: Date | number | string | null;
-    /** True when the signed-in user must verify their email before they can accept. */
-    needsEmailVerification?: boolean;
-}
-/** Define properties and callbacks for handling invite acceptance and navigation actions on the invite page */
-interface InviteAcceptPageProps {
-    details: InviteAcceptDetails;
-    /** Accept the invite; resolve with the workspace to navigate to. */
-    onAccept(): Promise<{
-        workspaceId?: string;
-    } | void>;
-    /** Navigate (sign in / sign up / switch account / open app). */
-    onNavigate(target: {
-        kind: 'sign-in' | 'sign-up' | 'switch-account' | 'open-app';
-        workspaceId?: string;
-    }): void;
-    /**
-     * Resend the verification email. Only invoked on the `needsEmailVerification`
-     * branch; an app without email verification omits it and that branch never shows.
-     */
-    onResendVerification?(): Promise<void>;
-}
-
-declare function MembersPanel({ members, currentRole, onInvite, onChangeRole, onRemove, onNotice, showInviteForm, }: MembersPanelProps): react.JSX.Element;
-
-declare function InvitationsPanel({ invitations, currentRole, onInvite, onResend, onRevoke, onCopy, onNotice, }: InvitationsPanelProps): react.JSX.Element;
-
-declare function InviteAcceptPage({ details, onAccept, onNavigate, onResendVerification }: InviteAcceptPageProps): react.JSX.Element;
-
-export { type InvitationView, InvitationsPanel, type InvitationsPanelProps, type InviteAcceptDetails, InviteAcceptPage, type InviteAcceptPageProps, type InviteAcceptStatus, type MemberView, MembersPanel, type MembersPanelProps };
+export * from './contracts';
+export * from './components/index';

package/dist/teams-react/lazy.d.ts

@@ -1,14 +1,14 @@
-import * as react from 'react';
-import { InvitationsPanel, InviteAcceptPage, MembersPanel } from './index.js';
-export { InvitationsPanelProps, InviteAcceptPageProps, MembersPanelProps } from './index.js';
-import '../roles-B4nU3jDi.js';
-import '../invitations-DoYMvXea.js';
-
+/**
+ * Code-split entries for the teams React surface. Products that don't need the
+ * members UI on initial load import these `React.lazy` handles instead of the
+ * components directly, so the panel/page chunks load on first render. Mount
+ * inside a `<Suspense>` boundary; the product provides the fallback.
+ */
+import type { MembersPanelProps, InvitationsPanelProps, InviteAcceptPageProps } from './contracts';
+export type { MembersPanelProps, InvitationsPanelProps, InviteAcceptPageProps };
 /** Load MembersPanel component lazily to optimize initial rendering performance */
-declare const MembersPanelLazy: react.LazyExoticComponent<typeof MembersPanel>;
+export declare const MembersPanelLazy: import("react").LazyExoticComponent<typeof import("./components").MembersPanel>;
 /** Load InvitationsPanel component lazily to optimize initial rendering performance */
-declare const InvitationsPanelLazy: react.LazyExoticComponent<typeof InvitationsPanel>;
+export declare const InvitationsPanelLazy: import("react").LazyExoticComponent<typeof import("./components").InvitationsPanel>;
 /** Load InviteAcceptPage component lazily for optimized code splitting and performance */
-declare const InviteAcceptPageLazy: react.LazyExoticComponent<typeof InviteAcceptPage>;
-
-export { InvitationsPanelLazy, InviteAcceptPageLazy, MembersPanelLazy };
+export declare const InviteAcceptPageLazy: import("react").LazyExoticComponent<typeof import("./components").InviteAcceptPage>;

package/dist/test-setup.d.ts

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

package/dist/theme/index.d.ts

@@ -1,108 +1,10 @@
 /**
- * Typed mirror of tokens.css for runtime/JS theming. The canonical source is
- * tokens.css (`import '@tangle-network/agent-app/styles'`); this module is for
- * apps that compute theme variables in JS, or read color values where CSS
- * custom properties cannot reach — notably Konva canvas render code, which
- * paints to a bitmap and cannot resolve `var(--…)`.
+ * Design-token + theme contract for agent-app's React surfaces.
  *
- * Values are shadcn-style HSL channel triples ("H S% L%"); wrap with `color()`.
+ *   import '@tangle-network/agent-app/styles'           // tokens.css (variable values)
+ *   import preset from '@tangle-network/agent-app/tailwind-preset'  // shadcn name → var map
+ *   import { darkTheme, themeToCssVars } from '@tangle-network/agent-app/theme'  // JS/runtime
  *
- * The neutral triples are the RESOLVED form of tokens.css's `--neutral-*` ramp
- * (that file states them as `var(--neutral-NN-hsl)`; JS has no cascade to
- * resolve through, so they are inlined here). `tests/theme/tokens-contract.test.ts`
- * resolves the CSS one level and fails if this mirror has drifted.
+ * The CSS file is the canonical source; this module is the typed JS mirror.
  */
-interface AgentAppTheme {
-    background: string;
-    foreground: string;
-    card: string;
-    cardForeground: string;
-    popover: string;
-    popoverForeground: string;
-    primary: string;
-    primaryForeground: string;
-    secondary: string;
-    secondaryForeground: string;
-    muted: string;
-    mutedForeground: string;
-    accent: string;
-    accentForeground: string;
-    destructive: string;
-    destructiveForeground: string;
-    border: string;
-    input: string;
-    ring: string;
-    success: string;
-    successForeground: string;
-    warning: string;
-    warningForeground: string;
-    /**
-     * Warning as TEXT on a warning-TINTED surface, as a channel triple. Optional
-     * so a consumer's existing `AgentAppTheme` literal still type-checks;
-     * {@link themeToCssVars} falls back to `warningForeground`, which is what the
-     * surface used before this token existed.
-     */
-    warningStrong?: string;
-    /** Full CSS color (not a triple) — the canvas/scene backdrop. */
-    canvasBackdrop: string;
-    /**
-     * Border tiers as FULL CSS colors (they are `color-mix()` results, not
-     * triples). Optional so a consumer's existing `AgentAppTheme` literal still
-     * type-checks; {@link themeToCssVars} falls back to full-strength
-     * `hsl(var(--border))`, which can never erase an edge.
-     */
-    borderSoft?: string;
-    /** @see borderSoft */
-    cardEdge?: string;
-    /** Konva render palette — full hex colors the bitmap canvas paints with
-     *  (it cannot resolve `var(--…)`). NOT emitted by themeToCssVars. */
-    canvasRender: CanvasRenderPalette;
-}
-/**
- * Colors the Konva design-canvas paints directly. Konva renders to a bitmap
- * and cannot read CSS custom properties, so these are full hex strings sourced
- * from the active theme and threaded through the canvas components.
- */
-interface CanvasRenderPalette {
-    /** Grid line color (GridLayer). */
-    grid: string;
-    /** Grid-snap guide line (SnapGuidesOverlay, kind 'grid'). */
-    snapGrid: string;
-    /** Saved ruler-guide snap line (kind 'guide'). */
-    snapGuide: string;
-    /** Page edge/center snap line (kinds 'page-edge'/'page-center'). */
-    snapPage: string;
-    /** Element edge/center snap line (kinds 'element-edge'/'element-center'). */
-    snapElement: string;
-    /** Transformer border + anchor stroke (SelectionLayer). */
-    selectionStroke: string;
-    /** Transformer anchor fill (SelectionLayer). */
-    selectionAnchorFill: string;
-    /** Video placeholder fill (ElementNode VideoNode). */
-    placeholderFill: string;
-    /** Video placeholder stroke (ElementNode VideoNode). */
-    placeholderStroke: string;
-    /** Broken/loading image placeholder fill (ElementNode ImageNode). */
-    brokenFill: string;
-    /** Broken/loading image placeholder stroke (ElementNode ImageNode). */
-    brokenStroke: string;
-}
-/** Define a light color theme with specific background, foreground, and accent color values */
-declare const lightTheme: AgentAppTheme;
-/** Define a dark color scheme for the Agent app interface with specific background and foreground hues */
-declare const darkTheme: AgentAppTheme;
-/**
- * Wrap a channel triple in `hsl()`; pass through values already in a color form.
- * `oklch(…)` / `oklab(…)` / `color-mix(…)` are recognised because the ramp is
- * authored in oklch and the border tiers are colour mixes — wrapping either in
- * `hsl()` yields an invalid colour that paints as nothing.
- */
-declare function themeColor(value: string): string;
-/**
- * Map a theme to the full CSS-variable set (shadcn triples + canvas/sequences
- * aliases + canvas surface). Apply at runtime to scope a theme without loading
- * tokens.css: `Object.assign(el.style, themeToCssVars(darkTheme))`.
- */
-declare function themeToCssVars(theme: AgentAppTheme): Record<string, string>;
-
-export { type AgentAppTheme, type CanvasRenderPalette, darkTheme, lightTheme, themeColor, themeToCssVars };
+export * from './theme';

package/dist/theme/tailwind-preset.d.ts

@@ -94,5 +94,4 @@ declare const agentAppPreset: {
         };
     };
 };
-
-export { agentAppPreset as default };
+export default agentAppPreset;

package/dist/theme/theme.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Typed mirror of tokens.css for runtime/JS theming. The canonical source is
+ * tokens.css (`import '@tangle-network/agent-app/styles'`); this module is for
+ * apps that compute theme variables in JS, or read color values where CSS
+ * custom properties cannot reach — notably Konva canvas render code, which
+ * paints to a bitmap and cannot resolve `var(--…)`.
+ *
+ * Values are shadcn-style HSL channel triples ("H S% L%"); wrap with `color()`.
+ *
+ * The neutral triples are the RESOLVED form of tokens.css's `--neutral-*` ramp
+ * (that file states them as `var(--neutral-NN-hsl)`; JS has no cascade to
+ * resolve through, so they are inlined here). `tests/theme/tokens-contract.test.ts`
+ * resolves the CSS one level and fails if this mirror has drifted.
+ */
+export interface AgentAppTheme {
+    background: string;
+    foreground: string;
+    card: string;
+    cardForeground: string;
+    popover: string;
+    popoverForeground: string;
+    primary: string;
+    primaryForeground: string;
+    secondary: string;
+    secondaryForeground: string;
+    muted: string;
+    mutedForeground: string;
+    accent: string;
+    accentForeground: string;
+    destructive: string;
+    destructiveForeground: string;
+    border: string;
+    input: string;
+    ring: string;
+    success: string;
+    successForeground: string;
+    warning: string;
+    warningForeground: string;
+    /**
+     * Warning as TEXT on a warning-TINTED surface, as a channel triple. Optional
+     * so a consumer's existing `AgentAppTheme` literal still type-checks;
+     * {@link themeToCssVars} falls back to `warningForeground`, which is what the
+     * surface used before this token existed.
+     */
+    warningStrong?: string;
+    /** Full CSS color (not a triple) — the canvas/scene backdrop. */
+    canvasBackdrop: string;
+    /**
+     * Border tiers as FULL CSS colors (they are `color-mix()` results, not
+     * triples). Optional so a consumer's existing `AgentAppTheme` literal still
+     * type-checks; {@link themeToCssVars} falls back to full-strength
+     * `hsl(var(--border))`, which can never erase an edge.
+     */
+    borderSoft?: string;
+    /** @see borderSoft */
+    cardEdge?: string;
+    /** Konva render palette — full hex colors the bitmap canvas paints with
+     *  (it cannot resolve `var(--…)`). NOT emitted by themeToCssVars. */
+    canvasRender: CanvasRenderPalette;
+}
+/**
+ * Colors the Konva design-canvas paints directly. Konva renders to a bitmap
+ * and cannot read CSS custom properties, so these are full hex strings sourced
+ * from the active theme and threaded through the canvas components.
+ */
+export interface CanvasRenderPalette {
+    /** Grid line color (GridLayer). */
+    grid: string;
+    /** Grid-snap guide line (SnapGuidesOverlay, kind 'grid'). */
+    snapGrid: string;
+    /** Saved ruler-guide snap line (kind 'guide'). */
+    snapGuide: string;
+    /** Page edge/center snap line (kinds 'page-edge'/'page-center'). */
+    snapPage: string;
+    /** Element edge/center snap line (kinds 'element-edge'/'element-center'). */
+    snapElement: string;
+    /** Transformer border + anchor stroke (SelectionLayer). */
+    selectionStroke: string;
+    /** Transformer anchor fill (SelectionLayer). */
+    selectionAnchorFill: string;
+    /** Video placeholder fill (ElementNode VideoNode). */
+    placeholderFill: string;
+    /** Video placeholder stroke (ElementNode VideoNode). */
+    placeholderStroke: string;
+    /** Broken/loading image placeholder fill (ElementNode ImageNode). */
+    brokenFill: string;
+    /** Broken/loading image placeholder stroke (ElementNode ImageNode). */
+    brokenStroke: string;
+}
+/** Define a light color theme with specific background, foreground, and accent color values */
+export declare const lightTheme: AgentAppTheme;
+/** Define a dark color scheme for the Agent app interface with specific background and foreground hues */
+export declare const darkTheme: AgentAppTheme;
+/**
+ * Wrap a channel triple in `hsl()`; pass through values already in a color form.
+ * `oklch(…)` / `oklab(…)` / `color-mix(…)` are recognised because the ramp is
+ * authored in oklch and the border tiers are colour mixes — wrapping either in
+ * `hsl()` yields an invalid colour that paints as nothing.
+ */
+export declare function themeColor(value: string): string;
+/**
+ * Map a theme to the full CSS-variable set (shadcn triples + canvas/sequences
+ * aliases + canvas surface). Apply at runtime to scope a theme without loading
+ * tokens.css: `Object.assign(el.style, themeToCssVars(darkTheme))`.
+ */
+export declare function themeToCssVars(theme: AgentAppTheme): Record<string, string>;

package/dist/theme-contract/cli.d.ts

@@ -1 +1,22 @@
 #!/usr/bin/env node
+/**
+ * agent-app-theme-check — CI guard against the invisible-surface incident class.
+ *
+ * A consumer app runs this over its own source; it fails (exit 1) when a
+ * component references a theme token — `var(--popover)` or a preset-mapped
+ * utility like `bg-surface-container-high` — that the app's shipped CSS never
+ * defines, which would paint that surface transparent with no error at runtime.
+ *
+ *   agent-app-theme-check --src src --src packages/ui/src \
+ *     --extra-css src/app-tokens.css
+ *
+ * Flags (all repeatable except --tokens):
+ *   --src <dir>         source dir to scan for token references (required, 1+)
+ *   --extra-css <file>  extra CSS whose --name: definitions also count as defined
+ *   --tokens <file>     override the base tokens.css (defaults to the one
+ *                       agent-app ships as `@tangle-network/agent-app/styles`)
+ *   --allow <--var>     suppress a token name from the missing report
+ *
+ * Wire it as a CI step: `"theme-check": "agent-app-theme-check --src src"`.
+ */
+export {};

package/dist/theme-contract/index.d.ts

@@ -46,7 +46,7 @@
  * browser-safe manifest test).
  */
 /** Define options for scanning source directories and CSS token files in a theme contract */
-interface ThemeContractOptions {
+export interface ThemeContractOptions {
     /** Consumer source directories to scan for token references (recursively). */
     srcDirs: string[];
     /**
@@ -68,7 +68,7 @@ interface ThemeContractOptions {
     allowlist?: string[];
 }
 /** Describe a missing theme contract variable and where it was referenced */
-interface ThemeContractMiss {
+export interface ThemeContractMiss {
     /** The undefined custom property, e.g. `--popover`. */
     varName: string;
     /**
@@ -79,7 +79,7 @@ interface ThemeContractMiss {
     referencedIn: string;
 }
 /** Describe the result of validating a theme contract including success status and missing items */
-interface ThemeContractResult {
+export interface ThemeContractResult {
     ok: boolean;
     missing: ThemeContractMiss[];
 }
@@ -88,6 +88,4 @@ interface ThemeContractResult {
  * defined in the CSS that consumer ships. Returns the full missing set; the
  * caller decides how to fail (the bin exits non-zero on any miss).
  */
-declare function checkThemeContract(opts: ThemeContractOptions): ThemeContractResult;
-
-export { type ThemeContractMiss, type ThemeContractOptions, type ThemeContractResult, checkThemeContract };
+export declare function checkThemeContract(opts: ThemeContractOptions): ThemeContractResult;

package/dist/{auth-BYtiazA4.d.ts → tools/auth.d.ts}

@@ -1,17 +1,16 @@
-import { A as AppToolContext } from './types-B25Mib1r.js';
-
+import type { AppToolContext } from './types';
 /**
  * Header names carrying the server-set per-turn context + the capability token.
  * Defaults are product-neutral (`X-Agent-App-*`); a product that already ships
  * a header convention (e.g. `X-Acme-User-Id`) passes its own.
  */
-interface ToolHeaderNames {
+export interface ToolHeaderNames {
     userId: string;
     workspaceId: string;
     threadId: string;
 }
 /** Provide default HTTP header names for user, workspace, and thread identification */
-declare const DEFAULT_HEADER_NAMES: ToolHeaderNames;
+export declare const DEFAULT_HEADER_NAMES: ToolHeaderNames;
 /**
  * Which identity the bearer is bound to.
  *
@@ -32,9 +31,9 @@ declare const DEFAULT_HEADER_NAMES: ToolHeaderNames;
  * caller act at all" moves from the user to the workspace — which is what the
  * shared box already implies.
  */
-type CapabilitySubject = 'userId' | 'workspaceId';
+export type CapabilitySubject = 'userId' | 'workspaceId';
 /** Define options to verify bearer tokens and customize authentication header names */
-interface AuthenticateOptions {
+export interface AuthenticateOptions {
     /** Verify the bearer capability token belongs to the subject named by
      *  {@link AuthenticateOptions.subject}. The product's HMAC/JWT impl — the
      *  seam that keeps token crypto out of this package. */
@@ -45,7 +44,7 @@ interface AuthenticateOptions {
     subject?: CapabilitySubject;
 }
 /** Represent the result of tool authentication with success context or failure response */
-type ToolAuthResult = {
+export type ToolAuthResult = {
     ok: true;
     ctx: AppToolContext;
 } | {
@@ -65,10 +64,8 @@ type ToolAuthResult = {
  * subject is the workspace, its header is required BEFORE verification rather
  * than after — verifying against an absent subject is not a check at all.
  */
-declare function authenticateToolRequest(request: Request, opts: AuthenticateOptions): Promise<ToolAuthResult>;
+export declare function authenticateToolRequest(request: Request, opts: AuthenticateOptions): Promise<ToolAuthResult>;
 /** Read a tool's argument object from the request body, tolerant of direct
  *  aliases (`args` / `arguments`), Streamable HTTP MCP (`params.arguments`),
  *  or a bare body. Returns null on non-JSON. */
-declare function readToolArgs<T>(request: Request): Promise<T | null>;
-
-export { type AuthenticateOptions as A, type CapabilitySubject as C, DEFAULT_HEADER_NAMES as D, type ToolHeaderNames as T, type ToolAuthResult as a, authenticateToolRequest as b, readToolArgs as r };
+export declare function readToolArgs<T>(request: Request): Promise<T | null>;

package/dist/tools/capability.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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 */
+export 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). */
+export 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. */
+export declare function verifyCapabilityToken(userId: string, token: string, opts: CapabilityTokenOptions): Promise<boolean>;
+/** Define options for capability tokens that expire after a specified lifetime in milliseconds */
+export 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.
+ */
+export 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. */
+export declare function verifyExpiringCapabilityToken(subject: string, token: string, opts: CapabilityTokenOptions & {
+    now?: () => number;
+}): Promise<boolean>;

package/dist/tools/dispatch.d.ts

@@ -0,0 +1,37 @@
+import { type AppToolDefinition } from './registry';
+import type { AppToolContext, AppToolHandlers, AppToolOutcome, AppToolProducedEvent, AppToolTaxonomy } from './types';
+/** Define options for dispatching tools including handlers, taxonomy, custom tools, and approval policies */
+export 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.
+ */
+export 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. */
+export declare function outcomeStatus(outcome: Extract<AppToolOutcome, {
+    ok: false;
+}>): number;

package/dist/tools/errors.d.ts

@@ -0,0 +1,8 @@
+/** 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. */
+export declare class ToolInputError extends Error {
+    code: string;
+    status: number;
+    constructor(code: string, message: string, status?: number);
+}