@agentronics/sdk 0.5.0 → 0.7.0

package/dist/{init-only-Cwll8MGz.d.cts → init-only-s9E9bVC0.d.cts}

@@ -1,5 +1,5 @@
 import { AgentIdentity, IdentityClaim, TraceEvent, TraceEventType, VerificationResult, AgentClass, PolicyRule, PolicyEvaluation, MemoryScope, MemoryEntry, SiteMemory, SiteMemoryPageContext } from '@agentronics/protocol';
-import { D as DetectWebMcpOptions } from './webmcp-C4ikhM4g.cjs';
+import { D as DetectWebMcpOptions, T as ToolAnnotations, a as ModelContextSource, b as ModelContextLike, L as LegacyProvider } from './webmcp-BgKzHeQ3.cjs';
 
 type CrawlerCategory = 'ai' | 'search';
 interface CrawlerSignature {
@@ -45,6 +45,7 @@ interface SignalResult {
 declare const SIGNALS: {
     readonly webdriver: () => SignalResult;
     readonly chromedriver: () => SignalResult;
+    readonly automationGlobals: () => SignalResult;
     readonly headlessUa: () => SignalResult;
     readonly languages: () => SignalResult;
     readonly permissions: () => SignalResult;
@@ -86,6 +87,73 @@ interface DetectAgentOptions {
  */
 declare const detectAgent: (options?: DetectAgentOptions) => Promise<AgentIdentity | null>;
 
+/**
+ * Vision-model ("screenshot") agents — computer-use agents that look at
+ * screenshots and drive a real browser with synthetic mouse and keyboard
+ * input (ChatGPT agent, Claude computer use, Gemini computer use, …).
+ *
+ * They run in ordinary browsers, so DOM automation flags often don't fire.
+ * What gives them away is how they interact:
+ *
+ * - **teleport clicks** — a click with no pointer movement leading up to it
+ *   (the cursor jumps straight to the coordinates the model picked);
+ * - **centre clicks** — clicks landing within a pixel or two of an element's
+ *   exact centre, again and again;
+ * - **metronome typing** — key intervals with almost no variance, or text
+ *   inserted with no key events at all;
+ * - **no hover or wheel** — clicks and scroll jumps without any mousemove or
+ *   wheel activity in between;
+ * - **VM-shaped viewport** — exact sizes agent sandboxes use (1024×768, 1280×800…).
+ *
+ * Each signal is weak alone. The monitor scores them over a short window and
+ * reports a `screenshot` agent only when several agree after enough
+ * interactions. It reads event coordinates and timing only — never key values
+ * or text.
+ */
+interface VisionDetectorOptions {
+    /** Score (0–1) at which to report an agent. Default 0.6. */
+    threshold?: number;
+    /** Interactions (clicks + typing bursts) needed before scoring. Default 3. */
+    minInteractions?: number;
+    documentRef?: Document;
+    /** Called once, when the score first crosses the threshold. */
+    onDetect?: (identity: AgentIdentity) => void;
+    /** @internal Tests only: count synthetic (isTrusted=false) events. */
+    acceptUntrustedEvents?: boolean;
+}
+interface VisionSignals {
+    clicks: number;
+    teleportClicks: number;
+    centreClicks: number;
+    keyIntervals: number;
+    keyIntervalCv: number | null;
+    insertWithoutKeys: number;
+    pointerMoves: number;
+    wheelEvents: number;
+    vmViewport: boolean;
+}
+/** 0–1 score from the collected signals (exported for tests and the console's explanation). */
+declare const scoreVisionSignals: (s: VisionSignals) => number;
+/**
+ * Watch the page for vision-agent interaction patterns. Returns a handle with
+ * the live signals and score; `onDetect` fires once when the threshold is met.
+ */
+declare const createVisionDetector: (options?: VisionDetectorOptions) => {
+    signals: () => VisionSignals;
+    score: () => number;
+    detected: () => {
+        class: "webmcp" | "dom" | "screenshot" | "crawler";
+        trust: "detected" | "declared" | "verified" | "linked";
+        confidence: number;
+        vendor: string | null;
+        userAgent: string | null;
+        detectionVersion: string;
+        signals: Record<string, unknown>;
+    } | null;
+    stop: () => void;
+};
+type VisionDetector = ReturnType<typeof createVisionDetector>;
+
 interface PresentIdentityOptions extends IdentityClaim {
     /**
      * If false, accept the claim as `declared` (no remote verification).
@@ -178,8 +246,25 @@ interface AuthEngineOptions {
     methods?: AuthMethod[];
     context?: AuthContext;
     onTrace?: (input: TraceInput) => void;
+    /**
+     * `'0.6'` restores the pre-0.7 behaviour: tokens nothing has verified count
+     * as `verified` (or `linked` with a user id), and SSO / SPIFFE / mTLS are in
+     * the default methods. Insecure — for upgrading without changes; remove it
+     * once `auth.verifyToken` is wired. See the 0.7 upgrade guide.
+     */
+    compat?: '0.6';
+    /** Called once, the first time a credential arrives with no verifier configured. */
+    onUnverifiedToken?: (method: AuthMethodName) => void;
 }
-declare const createAuthEngine: ({ methods, context, onTrace, }?: AuthEngineOptions) => {
+/**
+ * Methods on by default. SSO, SPIFFE (incl. Google Agent Identity) and mTLS are
+ * kept but off until they ship — pass `methods: [...defaultAuthMethods(),
+ * ...previewAuthMethods()]` to try them.
+ */
+declare const defaultAuthMethods: () => AuthMethod[];
+/** Coming later: enterprise agent SSO, workload identity (SPIFFE) and mTLS. */
+declare const previewAuthMethods: () => AuthMethod[];
+declare const createAuthEngine: ({ compat, methods, context, onTrace, onUnverifiedToken, }?: AuthEngineOptions) => {
     authenticate(input: AuthInput): Promise<AgentIdentity | null>;
     methods(): AuthMethodName[];
 };
@@ -302,11 +387,40 @@ declare const createMemoryCache: ({ gatewayUrl, siteId, publishableKey, fetcher,
 };
 type MemoryCache = ReturnType<typeof createMemoryCache>;
 
+/** What a "review" decision asks the person on the page to approve. */
+interface ReviewRequest {
+    tool: string;
+    title?: string;
+    description?: string;
+    input: unknown;
+    identity: AgentIdentity | null;
+    reason: string;
+}
+/** Return true to let the tool run, false to refuse it. */
+type Reviewer = (request: ReviewRequest) => Promise<boolean>;
+interface ReviewPromptOptions {
+    documentRef?: Document;
+    /** Refuse automatically if nobody answers. Default 120 s. */
+    timeoutMs?: number;
+}
+/**
+ * The default browser reviewer: a small modal asking the visitor to allow or
+ * refuse the agent's action. Resolves false without a document (server), on
+ * "Not now", on Escape, or after the timeout.
+ */
+declare const createReviewPrompt: ({ documentRef, timeoutMs, }?: ReviewPromptOptions) => Reviewer;
+
 interface GovernedTool<Input = unknown, Output = unknown> {
     name: string;
+    /** Human-readable name agents and browsers may show (WebMCP `title`). */
+    title?: string;
     version?: string;
     group?: string;
     description?: string;
+    /** WebMCP hints: readOnlyHint, consequentialHint, untrustedContentHint. */
+    annotations?: ToolAnnotations;
+    /** Other origins whose agents may see this tool (WebMCP `exposedTo`). */
+    exposedTo?: string[];
     inputSchema?: Record<string, unknown>;
     outputSchema?: Record<string, unknown>;
     stage?: string;
@@ -314,6 +428,7 @@ interface GovernedTool<Input = unknown, Output = unknown> {
     rateLimit?: PolicyRule['rateLimit'];
     execute: (input: Input, context: {
         identity: AgentIdentity | null;
+        signal?: AbortSignal;
     }) => Promise<Output> | Output;
 }
 interface ToolRegistryOptions {
@@ -335,6 +450,15 @@ interface ToolRegistryOptions {
      * - `execute(name, input, identity)` → respected
      */
     identityResolver?: () => AgentIdentity | null;
+    /**
+     * Asks a person to approve a call whose policy decision is `review`. Without
+     * one, review calls are refused (never silently run).
+     */
+    reviewer?: Reviewer;
+}
+interface ExecuteOptions {
+    /** Aborted when the agent cancels the call (WebMCP passes one per call). */
+    signal?: AbortSignal;
 }
 interface ToolRegistry {
     register(tool: GovernedTool): () => void;
@@ -346,9 +470,9 @@ interface ToolRegistry {
         includeDisabled?: boolean;
     }): GovernedTool[];
     get(name: string): GovernedTool | undefined;
-    execute<Input, Output>(name: string, input: Input, identity?: AgentIdentity | null): Promise<Output>;
+    execute<Input, Output>(name: string, input: Input, identity?: AgentIdentity | null, options?: ExecuteOptions): Promise<Output>;
 }
-declare const createToolRegistry: ({ evaluate, setPolicies, listPolicies, onTrace, identityResolver, }: ToolRegistryOptions) => ToolRegistry;
+declare const createToolRegistry: ({ evaluate, setPolicies, listPolicies, onTrace, identityResolver, reviewer, }: ToolRegistryOptions) => ToolRegistry;
 
 interface ProgressionTransition {
     on: string;
@@ -417,40 +541,67 @@ interface TokenBudgetReport {
     total: number;
     perTool: ToolTokenEstimate[];
 }
+/**
+ * What an agent actually receives for a tool — the fields registered with
+ * WebMCP (`name`, `title`, `description`, `inputSchema`, `annotations`).
+ * Policy, version and grouping stay on the site and cost the agent nothing.
+ */
+declare const modelFacingDescriptor: (tool: Pick<GovernedTool, "name" | "title" | "description" | "inputSchema" | "annotations">) => {
+    annotations?: ToolAnnotations;
+    inputSchema?: Record<string, unknown>;
+    description: string;
+    title?: string;
+    name: string;
+};
+/** ≈ characters / 4 of the model-facing descriptor. */
+declare const descriptorTokens: (tool: Parameters<typeof modelFacingDescriptor>[0]) => number;
 declare const estimateToolTokens: (tool: GovernedTool) => ToolTokenEstimate;
 declare const estimateBudget: (tools: GovernedTool[]) => TokenBudgetReport;
 
+/** @deprecated The pre-2026 `provideContext()` shape; kept for old polyfills. */
+type WebMcpProvider = LegacyProvider;
 interface WebMcpToolDescriptor {
     name: string;
     description?: string;
     inputSchema?: Record<string, unknown>;
     invoke(input?: unknown): Promise<unknown>;
 }
-interface WebMcpProvider {
-    provideContext(payload: {
-        tools: WebMcpToolDescriptor[];
-    }): {
-        revoke: () => void;
-    };
-}
 interface WebMcpAdapterOptions {
-    provider?: WebMcpProvider;
-    doc?: {
-        defaultView?: WindowLike | null;
+    /** Explicit ModelContext (tests, or a host that isn't `globalThis`). */
+    modelContext?: ModelContextLike | LegacyProvider;
+    /** @deprecated use `modelContext`. */
+    provider?: LegacyProvider;
+    /** Where to look for `document.modelContext` / `navigator.modelContext`. */
+    host?: {
+        document?: {
+            modelContext?: unknown;
+        } | null;
+        navigator?: {
+            modelContext?: unknown;
+        } | null;
     } | null;
-    invoke?: (tool: GovernedTool, input: unknown) => Promise<unknown>;
+    invoke?: (tool: GovernedTool, input: unknown, signal?: AbortSignal) => Promise<unknown>;
 }
-interface WindowLike {
-    navigator?: {
-        modelContext?: WebMcpProvider;
-    };
+/** Per-tool result of the last publish — the "callable / failed" status the console shows. */
+interface WebMcpRegistration {
+    name: string;
+    status: 'callable' | 'failed';
+    error?: string;
+}
+interface WebMcpPublishResult {
+    /** True when a WebMCP surface was found and the previous registrations were withdrawn. */
+    revoked: boolean;
+    /** Resolves once every tool's registerTool() settled. Empty when WebMCP is unavailable. */
+    registrations: Promise<WebMcpRegistration[]>;
 }
 interface WebMcpAdapter {
-    publish(tools: GovernedTool[]): {
-        revoked: boolean;
-    };
+    publish(tools: GovernedTool[]): WebMcpPublishResult;
     revoke(): void;
     available(): boolean;
+    /** Which surface was used: document.modelContext, the navigator alias, or a legacy polyfill. */
+    source(): ModelContextSource | null;
+    /** Registration status from the most recent publish. */
+    status(): WebMcpRegistration[];
 }
 declare const createWebMcpAdapter: (options?: WebMcpAdapterOptions) => WebMcpAdapter;
 
@@ -458,14 +609,15 @@ interface InitOptions {
     publishableKey: string;
     siteId?: string;
     /**
-     * Override the gateway URL the SDK calls. **Reserved for local development
-     * only** — the only accepted values are `localhost` / `127.0.0.1` URLs (so
-     * `pnpm dev` against a local gateway works). Any other value throws at
-     * `init()` time.
+     * Override the Agentronics API URL the SDK calls. **Reserved for local
+     * development only** — the only accepted values are `localhost` /
+     * `127.0.0.1` URLs (so `pnpm dev` against a local API works). Any other
+     * value throws at `init()` time.
      *
-     * Production deployments must omit this option. The SDK is hard-coded to
-     * call `https://gateway.agentronics.dev`. Custom backends are not
-     * supported, by design — see the project README + LICENSE NOTICE.
+     * Production deployments must omit this option. The SDK calls
+     * `https://api.agentronics.dev` (the retired `gateway.agentronics.dev` is
+     * accepted and mapped to it). Custom backends are not supported, by
+     * design — see the project README + LICENSE NOTICE.
      *
      * @internal — kept on the public type only so dev tooling type-checks.
      */
@@ -476,6 +628,25 @@ interface InitOptions {
     auth?: AuthContext;
     progression?: ProgressionConfig;
     tools?: GovernedTool[];
+    /**
+     * Who approves tool calls whose policy decision is `review`. Default in the
+     * browser: a small "Allow / Not now" dialog for the person on the page.
+     * Pass your own function to use your UI, or `false` to refuse every review.
+     */
+    review?: Reviewer | false;
+    /**
+     * `'0.6'` keeps the pre-0.7 behaviour while you upgrade: unverified tokens
+     * count as `verified`, SSO / SPIFFE / mTLS are on, and `review` rules run
+     * without asking. Insecure and temporary — see the 0.7 upgrade guide.
+     * @deprecated Remove once you've moved to the 0.7 behaviour.
+     */
+    compat?: '0.6';
+    /**
+     * Approved tool descriptions from the console's Procedural memory page
+     * (`createDashboardSync().pullConfig().toolDescriptions`). They replace the
+     * code's description when tools are published to agents.
+     */
+    toolDescriptions?: Record<string, string>;
     /**
      * Run agent detection automatically on init and keep the resulting
      * identity in agentContext so every subsequent tools.execute() call gets
@@ -489,6 +660,12 @@ interface InitOptions {
      * `ready` promise on the returned client resolves once the cycle finishes.
      */
     autoDetect?: boolean | DetectAgentOptions;
+    /**
+     * Watch interactions for vision-model ("screenshot") agents — teleport and
+     * centre clicks, metronome typing. On by default in the browser whenever
+     * `autoDetect` is on; reads timing and coordinates only, never keystrokes.
+     */
+    visionDetection?: boolean | Omit<VisionDetectorOptions, 'onDetect'>;
     trace?: {
         enabled?: boolean;
         bufferSize?: number;
@@ -516,6 +693,8 @@ interface AgentronicsClient {
     readonly tools: ToolRegistry;
     readonly progression: ProgressionStore | null;
     readonly webmcp: WebMcpAdapter;
+    /** The vision-agent monitor, when running. */
+    readonly vision: VisionDetector | null;
     /**
      * Resolves once the initial autoDetect cycle finishes. Rejects only if the
      * autoDetect configuration itself is invalid; detection failures resolve to
@@ -535,6 +714,16 @@ interface AgentronicsClient {
     }): Promise<PolicyEvaluation>;
     syncPolicies(): Promise<PolicyRule[]>;
     syncSiteMemory(): Promise<SiteMemory | null>;
+    /**
+     * Pull everything the console manages for this site with the publishable
+     * key alone — authorization rules, approved tool descriptions and site
+     * memory — and apply it (re-publishing WebMCP tools if they changed).
+     */
+    syncConfig(): Promise<{
+        policies: PolicyRule[];
+        toolDescriptions: Record<string, string>;
+        siteMemory: SiteMemory | null;
+    }>;
     provideSiteMemory(memory: Partial<SiteMemory>): SiteMemory;
     provideForPage(input: ProvideForPageInput): void;
     installMemoryDelivery(options?: {
@@ -548,6 +737,8 @@ interface AgentronicsClient {
         uninstall: () => void;
     };
     registerTool(tool: GovernedTool): () => void;
+    /** Replace the description overrides (see `toolDescriptions`). */
+    setToolDescriptions(descriptions: Record<string, string>): void;
     /** Push the full tool registry to the gateway so the dashboard can render
      *  the page-wise view (schemas, per-tool tokens, context fullness). */
     syncTools(): Promise<number>;
@@ -563,11 +754,17 @@ interface AgentronicsClient {
     estimateTokens(options?: {
         identity?: AgentIdentity | null;
     }): TokenBudgetReport;
+    /**
+     * Register the surfaced tools with `document.modelContext`. `registrations`
+     * resolves with each tool's status (callable / failed) once the browser
+     * has accepted or rejected it.
+     */
     publishToWebMcp(options?: {
         identity?: AgentIdentity | null;
     }): {
         revoked: boolean;
         surfaced: number;
+        registrations: Promise<WebMcpRegistration[]>;
     };
     notifyToolInvoked(toolName: string): void;
     traces(): TraceEvent[];
@@ -590,4 +787,4 @@ interface AgentronicsClient {
 }
 declare const init: (options: InitOptions) => AgentronicsClient;
 
-export { createMemoryCache as $, type AgentronicsClient as A, type SurfacingContext as B, CRAWLER_SIGNATURES as C, type DetectAgentOptions as D, type SurfacingDecision as E, type TokenBudgetReport as F, type GovernedTool as G, type ToolGroupSummary as H, type InitOptions as I, type ToolRegistry as J, type ToolTokenEstimate as K, type TraceInput as L, type MemoryCache as M, type Tracer as N, type WebMcpAdapterOptions as O, type PolicyEngine as P, type WebMcpProvider as Q, type RateLimiter as R, type SiteMemoryListener as S, type TraceExporter as T, type WebMcpToolDescriptor as U, bundledDetectors as V, type WebMcpAdapter as W, createAgentContextStore as X, createAuthEngine as Y, createDetectorRegistry as Z, createIdentityStore as _, type AgentContextListener as a, createMemoryStore as a0, createPolicyCache as a1, createPolicyEngine as a2, createProgressionStore as a3, createRateLimiter as a4, createSiteMemoryStore as a5, createToolRegistry as a6, createTracer as a7, createWebMcpAdapter as a8, decideSurfacing as a9, detectAgent as aa, detectCrawler as ab, detectDom as ac, estimateBudget as ad, estimateToolTokens as ae, explainSurfacing as af, groupTools as ag, init as ah, listGroupNames as ai, surfaceTools as aj, type AgentContextSnapshot as b, type AgentContextStore as c, type AuthEngine as d, type AuthInput as e, type AuthMethod as f, type CrawlerCategory as g, type CrawlerSignature as h, DEFAULT_GROUP as i, type DetectCrawlerOptions as j, type DetectDomOptions as k, type Detector as l, type DetectorRegistry as m, type DetectorStatus as n, type DomSignalName as o, type IdentityStore as p, type MemoryStore as q, type PolicyCache as r, type PresentIdentityOptions as s, type PresentedIdentity as t, type ProgressionConfig as u, type ProgressionStage as v, type ProgressionStore as w, type ProgressionTransition as x, type ProvideForPageInput as y, type SiteMemoryStore as z };
+export { type WebMcpRegistration as $, type AgentronicsClient as A, type Reviewer as B, CRAWLER_SIGNATURES as C, type DetectAgentOptions as D, type SiteMemoryStore as E, type SurfacingContext as F, type GovernedTool as G, type SurfacingDecision as H, type InitOptions as I, type TokenBudgetReport as J, type ToolGroupSummary as K, type ToolRegistry as L, type MemoryCache as M, type ToolTokenEstimate as N, type TraceInput as O, type PolicyEngine as P, type Tracer as Q, type RateLimiter as R, type SiteMemoryListener as S, type TraceExporter as T, type VisionDetectorOptions as U, type VisionDetector as V, type VisionSignals as W, type WebMcpAdapter as X, type WebMcpAdapterOptions as Y, type WebMcpProvider as Z, type WebMcpPublishResult as _, type AgentContextListener as a, type WebMcpToolDescriptor as a0, bundledDetectors as a1, createAgentContextStore as a2, createAuthEngine as a3, createDetectorRegistry as a4, createIdentityStore as a5, createMemoryCache as a6, createMemoryStore as a7, createPolicyCache as a8, createPolicyEngine as a9, createProgressionStore as aa, createRateLimiter as ab, createReviewPrompt as ac, createSiteMemoryStore as ad, createToolRegistry as ae, createTracer as af, createVisionDetector as ag, createWebMcpAdapter as ah, decideSurfacing as ai, defaultAuthMethods as aj, descriptorTokens as ak, detectAgent as al, detectCrawler as am, detectDom as an, estimateBudget as ao, estimateToolTokens as ap, explainSurfacing as aq, groupTools as ar, init as as, listGroupNames as at, modelFacingDescriptor as au, previewAuthMethods as av, scoreVisionSignals as aw, surfaceTools as ax, type AgentContextSnapshot as b, type AgentContextStore as c, type AuthEngine as d, type AuthInput as e, type AuthMethod as f, type CrawlerCategory as g, type CrawlerSignature as h, DEFAULT_GROUP as i, type DetectCrawlerOptions as j, type DetectDomOptions as k, type Detector as l, type DetectorRegistry as m, type DetectorStatus as n, type DomSignalName as o, type IdentityStore as p, type MemoryStore as q, type PolicyCache as r, type PresentIdentityOptions as s, type PresentedIdentity as t, type ProgressionConfig as u, type ProgressionStage as v, type ProgressionStore as w, type ProgressionTransition as x, type ProvideForPageInput as y, type ReviewRequest as z };