@yaklabs-ai/plugin-sdk 0.15.2 → 0.26.3

package/dist/vendored-mcp.d.ts

@@ -12,23 +12,30 @@
  * It could, and V1 deliberately does not. These servers have no uniform read: several expose only
  * tools, and PostHog's is a single `exec` tool over a CLI-style DSL. There is no shape to project
  * generically, so a generic MCP read would be a guess per vendor wearing one function's clothes.
- * Instead `read` returns a reference card — what the resource is, its captured ids, the URL that
+ * Instead `read` returns a reference card - what the resource is, its captured ids, the URL that
  * opens it, and the server to call for anything deeper. When a vendor earns a real projection, it
  * attaches as a per-vendor `read` beside this one; the shared card stays the floor.
  *
  * ## Why there is no `requiresAuth`
  *
  * Linear's module declares one because its `read` calls MCP and genuinely needs a credential.
- * This module's `read` is a pure projection of the URI it was handed — no network, no credential.
+ * This module's `read` is a pure projection of the URI it was handed - no network, no credential.
  * Declaring `requiresAuth` anyway would not be a harmless formality: an auth-gated module whose
  * binding is unsatisfied has its public-web `urlPattern` claims suppressed and its `matches()`
  * wrapped to decline `http(s)` (herd-agent's `uri-catalog-projection.ts`: `suppressPublicUrlClaims`,
  * and `authSuppressedCatalogModule` for discovery). A pasted Supabase link would therefore stay
- * unbranded for every user who has not yet connected Supabase — which is exactly the user the
+ * unbranded for every user who has not yet connected Supabase - which is exactly the user the
  * branded pill is for. The vendor's MCP tools remain gated on their own, by the MCP host.
  */
 export declare function createVendoredMcpUriModule(descriptor: VendoredMcpDescriptor): UriExtensionModule;
 
+declare interface FactPattern {
+    protocol?: string;
+    hostname?: string;
+    pathname?: string;
+    search?: string;
+}
+
 declare type JsonPrimitive = string | number | boolean | null;
 
 declare type JsonSchema = Record<string, unknown>;
@@ -47,12 +54,107 @@ declare interface LineSelector {
     readonly raw: boolean;
 }
 
+/**
+ * A source-native read of one URI, shaped for downstream indexing rather than
+ * direct model consumption. A module's read returns it in
+ * `RawResource.observations`, built from the same fetch as the content, once
+ * per document it wants indexed; absence means "not indexed".
+ *
+ * Gone signal: the index retires a doc when a read throws `UriNotFoundError`
+ * or an error whose `.status === 404`. A module whose vendor signals "gone"
+ * differently (HTTP 410, a 200-body `{ok:false}`/`archived:true`, a
+ * 403/404-ambiguous lost-access response) must translate that into one of
+ * those two shapes itself; losing access to a resource counts as gone too.
+ * A read that cannot build a complete observation (a secondary fetch failed)
+ * returns none rather than a partial one.
+ *
+ * Account-qualified identity: a module whose read can resolve against more
+ * than one connected account (the account selector is stripped before route
+ * parsing, so two accounts reading the same opaque provider id would
+ * otherwise collide on one doc key) must fold `ctx.auth.credential.accountId`
+ * into `uri` - e.g. `gmail://@<accountId>/threads/<threadId>` - never the
+ * user-renamable connection/selector label. `ctx.auth.credential` is the
+ * reliable source of the resolved account at a `requiresAuth` module's
+ * `read()`: it is always populated once auth resolution runs (an
+ * `authContext`-style check already throws first when no credential
+ * resolved). `ctx.connection` may ALSO be populated by dispatch - a
+ * connection-required module receives it whenever the host has a tracked
+ * connection for the account - so do not assume it is absent; a module that
+ * wants the human-facing label rather than the account id reads
+ * `ctx.connection?.displayName`.
+ *
+ * `accountId` is guaranteed stable only for the life of the stored credential
+ * record, not necessarily across a disconnect/reconnect of the same
+ * real-world provider account. A scheme that mints an opaque id at connect
+ * time (the default for an api-key or delegated scheme, absent a
+ * provider-derived override) gets a fresh id on every connect; a scheme that
+ * instead derives the id from provider data (an oauth2-pkce scheme supplying
+ * `resolveAccountId`, e.g. reading an OIDC `sub`) keeps the same id across
+ * reconnect. A module on a scheme without a provider-stable id has two honest
+ * choices: derive its own stable identity from provider data at read time
+ * (call the provider's own account/"who am I" endpoint with the resolved
+ * credential and fold THAT into `uri` instead of `accountId`), or
+ * account-qualify with `accountId` knowing a disconnect/reconnect of the same
+ * real-world account re-keys its documents under a new id rather than
+ * updating them in place - nothing on the host side reconciles the old and
+ * new keys.
+ */
+declare interface ObservationMaterial {
+    /** Canonical URI of the observed resource - may differ from the input URI. */
+    readonly uri: string;
+    /** Scheme-prefixed content type, e.g. `"github.pr"`, `"gmail.thread"`, `"wikipedia.article"`. */
+    readonly kind: string;
+    readonly title?: string;
+    /** Source-native seams: one element per message/comment/section, in source order. */
+    readonly text?: readonly string[];
+    /** ISO-8601 creation time; provenance only - not persisted by the store yet. */
+    readonly createdAt?: string;
+    /** ISO-8601 last-update time; provenance only - not persisted by the store yet. */
+    readonly updatedAt?: string;
+    /** Source-native revision/version marker, when the source exposes one. */
+    readonly version?: string;
+    /**
+     * How long this resource stays worth semantically searching, measured from
+     * the LAST time it was observed - not from when it was first indexed. Every
+     * observation of an unchanged resource pushes the deadline out again, so a
+     * thread that keeps getting read keeps living and a quiet one ages out.
+     *
+     * Retention is opt-in per resource: absent means the index keeps the
+     * resource until its source says it is gone. A route declares this only
+     * when staleness is real for that shape - a chat thread or an inbox
+     * conversation goes cold, a durable note the user wrote does not.
+     */
+    readonly retainForMs?: number;
+}
+
 declare interface RawResource {
     readonly uri: string;
     readonly content: string | Uint8Array;
     readonly mimeType: string;
     readonly metadata?: RawResourceMetadata;
     readonly selector?: SelectorDisposition;
+    /**
+     * The indexable forms of this resource, built from the same fetch as
+     * `content`: one per document the read wants indexed (a thread read offers
+     * one per message). Absent or empty means nothing is indexed. The read tool
+     * takes them off before the cache and the model; other host reads
+     * (out-of-band host reads) return them untouched.
+     */
+    readonly observations?: readonly ObservationMaterial[];
+    /** How long the host may cache this result; see {@link UriCachePolicy.ttlMs}. */
+    readonly cachePolicy?: Pick<UriCachePolicy, "ttlMs">;
+    /**
+     * A short name for the resource this call touched, for the transcript row; absent shows the
+     * address. Render-only: the host stamps it on the tool result's `details`, never in `content`.
+     */
+    readonly label?: UriResourceLabel;
+    /**
+     * Answer to a `read` called with `ctx.knownRevision`: the module checked the source's current
+     * revision and it equals `knownRevision`, so `content` is empty and `metadata.revision` equals
+     * `knownRevision`. Set it only when that check was made and matched; a module that cannot
+     * check cheaply, or that found a different revision, returns the full resource without it.
+     */
+    readonly unchanged?: true;
 }
 
 declare interface RawResourceCacheControl {
@@ -96,7 +198,7 @@ declare interface RawResourceMetadata {
     readonly resourceIdentity?: RawResourceIdentity;
     /**
      * The resource's stable public address when `uri` reports something more
-     * specific than the address a consumer names it by — a retained revision
+     * specific than the address a consumer names it by - a retained revision
      * (`skill://<id>/@revision/<version>`) served for a `skill://<source>/<name>`
      * read. Present only when the two differ. Consumers that attribute by name
      * (the read tool's `skillName` detail, and everything keyed off it) read
@@ -105,6 +207,24 @@ declare interface RawResourceMetadata {
     readonly canonicalUri?: string;
 }
 
+/**
+ * The credential the host resolved for one call to plugin code that declares `requiresAuth`: a URI
+ * verb (`ctx.auth.credential`), a tool (`ctx.credential`) or a search provider (`ctx.credential`).
+ * Plain data, so it crosses a process boundary with the call; plugin code never asks for one.
+ */
+declare interface ResolvedCredential {
+    /** Bearer for OAuth schemes, apiKey for api-key schemes. Host-resolved and refreshed. */
+    readonly accessToken: string;
+    readonly accountId: string;
+    readonly schemeId: string;
+    readonly scopes?: readonly string[];
+    /**
+     * Every value of a multi-field api-key credential, keyed by the scheme's declared field id
+     * (`accessToken` mirrors the primary field). Absent for single-secret schemes.
+     */
+    readonly fields?: Readonly<Record<string, string>>;
+}
+
 /** One all-of arm in an ordered scope requirement. */
 declare interface ScopeAlternative {
     readonly allOf: readonly ScopeNeed[];
@@ -144,32 +264,43 @@ declare interface UriAgentHint {
     readonly triggers?: UriHintTriggers;
     /**
      * Skill invocation names (flat `localId`s, e.g. `"gmail-email-triage"`) that hold this module's
-     * deeper workflow judgment — the name a `read skill://<name>` dispatch resolves, not a display
+     * deeper workflow judgment - the name a `read skill://<name>` dispatch resolves, not a display
      * title or a path. Point here only at skills that actually exist in the composed skill roster;
      * a dangling name sends the agent to a `skill://` read for nothing.
      */
     readonly skills?: readonly string[];
 }
 
-declare type UriAuthActionClassification = {
-    readonly kind: "action";
-    readonly actionId: string;
-} | {
-    readonly kind: "public";
-};
-
 /**
- * Finite authorization actions plus the pure route classifier that selects one before dispatch.
- * An exception, an unknown action id, or `undefined` classification fails closed in the host.
+ * Finite authorization actions plus the rules that select one before dispatch. A call no rule
+ * matches, or a rule naming an action that is not in `actions`, fails closed in the host.
  */
 declare interface UriAuthActionPolicy {
     readonly actions: Readonly<Record<string, ScopeRequirement>>;
-    classifyOperation(request: {
-        readonly operation: UriOperation;
-        readonly uri: string;
-    }): UriAuthActionClassification | undefined;
+    /** Absent matches no call, so every call fails closed. */
+    readonly rules?: readonly UriAuthActionRule[];
 }
 
+/**
+ * One row of a module's sign-in action rules: which calls need which action. A row matches a call
+ * when every condition it names holds; a condition it leaves out matches anything. The first
+ * matching row decides, so a row with no conditions at the end means "everything else".
+ */
+declare type UriAuthActionRule = {
+    /** The verbs this row covers. */
+    readonly operations?: readonly UriOperation[];
+    /** The claim `route` ids this row covers, matched against the call's address. */
+    readonly routes?: readonly string[];
+    /** Query parameters the address must carry with exactly these values (`{ permanent: "true" }`). */
+    readonly query?: Readonly<Record<string, string>>;
+} & ({
+    /** The {@link UriAuthActionPolicy.actions} entry the call needs. */
+    readonly action: string;
+} | {
+    /** The call needs no credential. */
+    readonly public: true;
+});
+
 declare interface UriAuthRef {
     readonly serviceId: string;
     readonly schemeId: string;
@@ -191,7 +322,7 @@ declare interface UriAuthRequirement {
      */
     readonly requiredScopes?: readonly string[];
     /**
-     * The service id connect guidance should NAME when this module is gated — a host-composed
+     * The service id connect guidance should NAME when this module is gated - a host-composed
      * front door whose connect grants exactly this module's scopes (e.g. `gmail` expanding onto
      * the shared `google.account` credential). Guidance only; resolution keys on
      * `(serviceId, schemeId)`. Absent, guidance names `serviceId`.
@@ -237,6 +368,21 @@ declare type UriCachePolicyResolver = (operation: UriOperation, cacheUri: string
 
 declare type UriClaim = UriSchemeClaim | UriPatternClaim | UrlPatternClaim;
 
+/**
+ * A URL with `:name` placeholders for the claim's captures. Each capture is escaped for where it
+ * lands: lowercased in the host, one path segment (a `:name*` capture keeps its `/`), or a query
+ * or fragment value. `{transform(...)}` runs one named, built-in transform over the text inside
+ * it, captures pasted in unescaped, and escapes the output for where it lands:
+ *
+ * - `base64`: unpadded base64 of the UTF-8 text (`{base64(:id :calendar)}`).
+ * - `slackTimestamp`: a Slack archive message token as the API's timestamp
+ *   (`p1783350000000100` becomes `1783350000.000100`).
+ *
+ * A transform that cannot read its input fills nothing. A claim whose `normalizeTo` fills nothing
+ * does not match; a `sourceUrl` that fills nothing paints no link.
+ */
+declare type UriClaimTemplate = string;
+
 declare interface UriCommonFlow {
     readonly label: string;
     readonly when?: string;
@@ -286,41 +432,28 @@ declare interface UriExample {
     readonly operation?: UriOperation;
 }
 
-declare interface UriExtensionModule extends Omit<UriModule, "verbs"> {
+/**
+ * A plugin's URI module. Its claims route, spell and describe its addresses, so it has no
+ * `matches`, `normalize` or `describe`. It also has no `fallback` (a plugin's addresses are always
+ * claimed) and no `locate` (a plugin has no file on disk for the daemon to open).
+ */
+declare interface UriExtensionModule extends Omit<UriModule, "verbs" | "normalize" | "matches" | "describe" | "fallback" | "locate"> {
     readonly verbs: UriVerbSupport;
     /** Human-facing per-verb effect docs; see {@link UriVerbDocs}. */
     readonly verbDocs?: UriVerbDocs;
     /**
      * Plugin-declared default permission per verb group. A verb group set to `"ask"`
-     * compiles into a defaults-level ask rule — the user is prompted by default but can
+     * compiles into a defaults-level ask rule - the user is prompted by default but can
      * override with an explicit allow. Undeclared = `"allow"` (fail-open).
      * See {@link UriPermissionDefaults}.
      */
     readonly permissionDefaults?: UriPermissionDefaults;
     /** Requires a resolved URI connection before any verb handler runs. */
     readonly requiresConnection?: boolean;
-    /** Pure route-aware permission facts; see {@link UriExtensionOperationPermissionPolicy}. */
-    readonly permission?: UriExtensionOperationPermissionPolicy;
     /** False rejects generic write-tool `source` copies before source fetch. */
     readonly acceptsSourceCopy?: boolean;
 }
 
-declare interface UriExtensionOperationPermissionPolicy {
-    /**
-     * Classify one canonical route, purely. `write`/`edit`/`delete` may only be made stricter
-     * than the verb default; `help`/`read`/`list`/`search` must stay `"read"` (a `ruleKey` is
-     * allowed), because the kernel reruns a crash-interrupted read without asking again. Any
-     * other answer, or a throw, fails the call closed.
-     */
-    classifyOperation(request: {
-        readonly operation: UriOperation;
-        readonly uri: string;
-    }): {
-        readonly kind: "read" | "mutate" | "destructive" | "execute";
-        readonly ruleKey?: string;
-    } | undefined;
-}
-
 declare interface UriExternalCliRunner {
     readonly run: (request: UriExternalCliRunRequest) => Promise<UriExternalCliRunResult>;
 }
@@ -355,6 +488,8 @@ declare interface UriHelp {
      * than text the module's author wrote. Absent: the module's own text.
      */
     readonly thirdPartyContent?: true;
+    /** The module's own markdown for this result, shown instead of the host's default rendering. */
+    readonly markdown?: string;
 }
 
 declare interface UriHintTriggers {
@@ -394,6 +529,12 @@ declare interface UriListResult {
     readonly items: readonly UriListItem[];
     readonly nextCursor?: string;
     readonly metadata?: UriListMetadata;
+    /** How long the host may cache this result; see {@link UriCachePolicy.ttlMs}. */
+    readonly cachePolicy?: Pick<UriCachePolicy, "ttlMs">;
+    /** The module's own markdown for this result, shown instead of the host's default rendering. */
+    readonly markdown?: string;
+    /** The touched resource's name for the transcript row, as on `RawResource.label`. */
+    readonly label?: UriResourceLabel;
 }
 
 declare type UriLocateContext = Pick<UriResolveContext, "cwd" | "signal" | "connection" | "sessionId" | "paths"> & {
@@ -411,31 +552,13 @@ declare type UriLocateResult = {
     readonly kind: "not-disk-backed";
 };
 
-declare type UriMarkdownRenderInput = {
-    readonly operation: "help";
-    readonly uri: string;
-    readonly result: UriHelp;
-} | {
-    readonly operation: "list";
-    readonly uri: string;
-    readonly result: UriListResult;
-} | {
-    readonly operation: "search";
-    readonly uri: string;
-    readonly result: UriSearchResult;
-} | {
-    readonly operation: Extract<UriOperation, "write" | "edit" | "delete">;
-    readonly uri: string;
-    readonly result: UriMutationResult;
-};
-
 declare interface UriModule {
     readonly id: string;
     /**
      * Explicit human-readable name for catalog/display purposes (the plugin
      * manifest's `contributes.uriModules[].displayName`, threaded through by
-     * hand since there is no automatic manifest→runtime-module composition
-     * step). Falls back to a mechanical id-derived title when absent — see
+     * hand since there is no automatic manifest->runtime-module composition
+     * step). Falls back to a mechanical id-derived title when absent - see
      * `uriCatalogTitle`.
      */
     readonly title?: string;
@@ -455,14 +578,26 @@ declare interface UriModule {
      * calls `parseLineSelector` itself and reports what it did through `RawResource.selector`.
      */
     readonly ownsLineSelectors?: boolean;
+    /** Opt in to host-resolved supplementary sources; absent means unsupported. */
+    readonly acceptsWriteSources?: boolean;
+    /**
+     * Opt in to raw bytes as `write`'s content; absent means text and JSON only. The `write`
+     * tool's `source` copy leg is the only producer: a provider's binary resource (an attachment,
+     * an image, a PDF) reaches a module that declares this as a `Uint8Array`, never decoded into
+     * the model's context, and a binary copy to any other module is refused before it runs.
+     */
+    readonly acceptsBytes?: boolean;
     readonly claims?: readonly UriClaim[];
+    /**
+     * The routes the module's scheme-root `help` lists, as data, so a host can list them without
+     * calling `help`.
+     */
+    readonly templates?: readonly UriTemplate[];
     /** Migration-only prompt summary until structured help/catalog coverage replaces prose. */
     readonly description?: string;
     readonly agentHint?: UriAgentHint;
     readonly requiresAuth?: UriAuthRequirement;
     readonly authActions?: UriAuthActionPolicy;
-    /** Pure route/payload validation applied before a consequential permission ask. */
-    readonly preflight?: UriOperationPreflightPolicy;
     /**
      * Structured facts for approval surfaces, or `undefined` when unavailable.
      * A one-line description must name the whole consequence; `preview` instead
@@ -472,120 +607,46 @@ declare interface UriModule {
      * of covered payload fields and query parameters. Unknown fields cost the summary.
      * The host owns framing, the whole-quote fit (no elision) and display-safety admission.
      *
-     * Unlike preflight, this hook is async and may do I/O. Resolve names through `ctx`,
+     * This hook is async and may do I/O. Resolve names through `ctx`,
      * the same dispatch context used by execution, never an ambient or cached account. A name
      * the module resolved under that account may be cached for a bounded time, keyed by that
      * account's identity and never answered to another account or after a failed lookup.
-     * The host calls it once before raising the ask, enforces the short `ctx.signal`
-     * deadline and discards late answers. A throw yields no summary and a module-attributed
-     * diagnostic; declining costs a click into the app, never an under-described approval.
-     */
-    describeOperation?(request: {
-        readonly operation: UriOperation;
-        readonly uri: string;
-        readonly payload: unknown;
-    }, ctx: UriResolveContext): Promise<UriOperationDescription | undefined>;
-    /**
-     * Rebuild a call from the person's "Allow with edits" answer: the same payload
-     * {@link describeOperation} was given, with the values the person typed into the preview's
-     * `editable` fields put in their place. Implement it beside any preview that marks a field
-     * `editable`; without it the host drops every editable marker from that module's previews, so
-     * a field is never offered for editing that cannot be honoured.
-     *
-     * Pure and fast: it must not send, write or otherwise act, and it should not do I/O (it gets
-     * the dispatch context `ctx` only so a name can be resolved the way `describeOperation` does).
-     * Return the COMPLETE amended payload in the shape the module's own handler reads. Validate it
-     * with the handler's own schema, so an amended call is exactly as valid as one the model made.
-     * Decline by returning `undefined` or throwing; either denies the call with nothing done.
+     * The host calls it once before raising the ask and waits for the answer, with no deadline;
+     * `ctx.signal` fires when the host stops waiting (the session closes, or a caller gives up),
+     * and a late answer is discarded. A throw yields no
+     * summary and a module-attributed diagnostic; declining costs a click into the app, never an
+     * under-described approval.
      *
-     * The host calls it once, after the person allowed the call, never for a denial, and only for
-     * a `write` whose payload this module described. The kernel passes the `edits` through
-     * unchanged. Bonsai's daemon has already refused, before the ask settled, a key that is not an
-     * `editable` field of the preview it showed, a repeated key, a blank value and a value past the
-     * field's `maxLength`, but another host may not, so refuse each of those here yourself (return
-     * `undefined`).
-     *
-     * The host then holds the amended call to what the person was shown, in two steps, and runs it
-     * only if both pass. It classifies the amended call again and requires the same tool, rule key,
-     * kind, resources, scheme and target address, so an edit cannot reach a different route. It then
-     * calls {@link describeOperation} on the amended call and requires that preview to read exactly
-     * as the one the person saw, apart from the values of the fields they edited: the same title, the
-     * same fields in the same order, each with the same label, key, `editable` marker and
+     * "Allow with edits": a field marked `editable` may be rewritten by the person on the card.
+     * The host rebuilds the call itself (see the field's `editable`), then holds the rebuilt call to
+     * what the person was shown, in two steps, and runs it only if both pass. It classifies the
+     * rebuilt call again and requires the same tool, rule key, kind, resources, scheme and target
+     * address. It then calls this hook on the rebuilt call and requires that preview to read exactly
+     * as the one the person saw, apart from the values of the fields they edited: the same title,
+     * the same fields in the same order, each with the same label, key, `editable` marker and
      * `maxLength`, and every read-only field with the same value. Anything else refuses the call
-     * with nothing done: a mismatch, and also a describer that is missing, declines, throws or
-     * overruns its deadline. The `description` line is not compared.
-     *
-     * So rebuild from the original payload and change only the fields you offered. A recipient, a
-     * thread or an attachment list that an amendment changed is caught by the second step, but only
-     * where the preview shows it: put whatever says where a call goes, or what it does beyond its
+     * with nothing done: a mismatch, and also an answer of `undefined` or a throw. The `description`
+     * line is not compared. So put whatever says where a call goes, or what it does beyond its
      * editable fields, in the preview's `title` or a field, never only in its `description`, and
      * keep recipients, destinations and thread bindings out of `editable` fields.
      */
-    amendOperation?(request: {
+    describeOperation?(request: {
         readonly operation: UriOperation;
         readonly uri: string;
         readonly payload: unknown;
-        readonly edits: readonly UriPreviewEdit[];
-    }, ctx: UriResolveContext): Promise<UriOperationAmendment | undefined>;
-    /**
-     * A short, render-only name for the resource a settled call on `request.uri` touched, which the
-     * host stamps on the tool result's `details` so a transcript row can name it where it would
-     * otherwise print the address (`#lane-analytics` and `thread`, not a channel id). Answer
-     * `undefined` for any address you cannot honestly name.
-     *
-     * Called once per successful URI verb call, AFTER the verb handler has returned, with the same
-     * dispatch context. Resolve names through `ctx` and nothing else, and prefer a cache your own
-     * verb handlers warm, keyed by the executing account: a name one account saw is never answered
-     * to another, and a failed, blank or aborted lookup is never cached. The host bounds the wait
-     * (a finished result is held at most a quarter of a second), gives `ctx.signal` a hard deadline,
-     * and drops a late, thrown or refused answer without failing the call; a throw is reported as a
-     * module-attributed diagnostic. The label is a label, never an identity: the address remains the
-     * click target, hover text and accessible name. It is UI-only, so it never enters the tool
-     * result's content and no telemetry reads it.
-     *
-     * Unlike `describeOperation` this is not an approval surface: it carries no consequence, no
-     * quote and no coverage claim, and nothing may gate a permission on it.
-     */
-    labelResource?(request: UriResourceLabelRequest, ctx: UriResolveContext): Promise<UriResourceLabel | undefined>;
+    }, ctx: UriResolveContext): Promise<UriOperationDescription | undefined>;
+    readonly getCachePolicy?: UriCachePolicyResolver;
     /**
-     * Per-resource observability: does a `format: "observation"` read of THIS
-     * uri render source-native material ({@link UriResolveContext.format})?
-     * Route-parse only — cheap, side-effect-free, no I/O, no auth (the same
-     * discipline as `matches`); a throw is treated as `false`. Returning true
-     * is the resource's contract that its observation read returns an
-     * observation render and that failures under that format throw typed,
-     * status-bearing errors rather than resolving a friendly fallback page.
-     * The kernel stamps the answer onto the resource's access events, which is
-     * what ambient index consumers replay on — so "PRs are observable" is
-     * declared here, route by route, never module-wide. Absent means no read
-     * of this module is observable. A vendor's own gone-vocabulary (HTTP 410,
-     * a 200-body "ok:false"/"archived:true"/"status:cancelled", or a
-     * 403/404-ambiguous lost-access response) is this module's job to
-     * translate into `UriNotFoundError` or a `status: 404` error under the
-     * observation format — the fold that retires a doc never learns vendor
-     * vocabulary (see `ObservationMaterial`'s doc comment).
+     * Code matching, for the host's own modules whose addresses no claim can describe (a bare file
+     * path). A plugin module has none; it routes through its `claims` alone.
      */
-    observes?(uri: string): boolean;
+    matches?(input: string, ctx: UriResolveContext): boolean;
+    /** The official spelling, for the host's own modules; a plugin's comes from its claims' `normalizeTo`. */
+    normalize?(input: string, ctx: UriResolveContext): UriNormalizeResult | undefined;
     /**
-     * Head-only revision probe: the resource's CURRENT source-native revision
-     * without fetching its body, or `undefined` when that cannot be known
-     * cheaply. The host calls it before a repeat `read` of an address the
-     * session already holds, with `ctx.expectedRevision` set to the revision
-     * that read reported (`RawResourceMetadata.revision`); a value equal to it
-     * means "unchanged" and the fetch is skipped, anything else falls through
-     * to the ordinary read. A module whose read revision embeds more than the
-     * head can know (a content digest beside a stat stamp) may answer relative
-     * to `expectedRevision` — return it when the cheap part matches, `undefined`
-     * when it does not — but must never return a value it has not verified.
-     * `undefined` is always safe: it costs one fetch, never a wrong answer.
-     * Must be cheaper than the read (a metadata request, a `stat`); a throw is
-     * treated as `undefined`.
+     * The pill's title and link, for the host's own modules only; a plugin module has none, and its
+     * pill comes from its claims' `title` and `sourceUrl`.
      */
-    revision?(uri: string, ctx: UriResolveContext): Promise<string | undefined>;
-    readonly getCachePolicy?: UriCachePolicyResolver;
-    /** Retained matching escape hatch; future dispatch should prefer compiled claims. */
-    matches(input: string, ctx: UriResolveContext): boolean;
-    normalize?(input: string, ctx: UriResolveContext): UriNormalizeResult | undefined;
     describe?(input: string, ctx: UriDescribeContext): UriResourceDescription | undefined;
     locate?(input: string, ctx: UriLocateContext): Promise<UriLocateResult>;
     /**
@@ -598,33 +659,21 @@ declare interface UriModule {
     read(input: string, ctx: UriResolveContext): Promise<RawResource>;
     /** Observes only; see {@link read}. */
     help?(input: string, ctx: UriResolveContext): Promise<UriHelp>;
-    write?(input: string, content: UriPayload, ctx: UriResolveContext): Promise<UriMutationResult | void>;
-    /** Opt-in structured write with one or more host-resolved resources delivered beside the content. */
-    writeWithSources?(input: string, content: UriPayload, sources: readonly UriWriteSource[], ctx: UriResolveContext): Promise<UriMutationResult | void>;
     /**
-     * Opt-in byte sink: write RAW BYTES to this address, no UTF-8 round trip.
-     * `UriPayload` is text/JSON by contract, so a module that can store bytes
-     * declares it here instead of stretching `write`. The only caller today is
-     * the `write` tool's `source` copy leg, which is how a provider's binary
-     * resource — a Gmail attachment, an image, a PDF, a zip — reaches a
-     * byte-capable destination without ever being decoded into the model's
-     * context. A module that omits it is text-only, and a binary copy targeting
-     * it is refused with an error naming a byte-capable destination.
-     *
-     * `source` describes what the bytes are: a filesystem-backed sink can ignore
-     * it (the target path already carries the name), while a remote provider
-     * sink needs it to name and type the stored file. It sits before `ctx` so a
-     * forwarding wrapper that fails to thread it is a compile error, not a
-     * silent drop.
+     * `sources` is empty for ordinary writes; populated only with `acceptsWriteSources: true`.
+     * `content` is a `Uint8Array` only with `acceptsBytes: true`, and then `ctx.writeSource`
+     * names and types it. It is `undefined` when the call carried neither `content` nor `source`.
+     * The module decides what that means: a route that takes no body (a folder
+     * create) proceeds, and a route that needs one refuses with an error naming
+     * what is missing. Never treat it as empty content.
      */
-    writeBytes?(input: string, bytes: Uint8Array, source: UriSourceDescriptor, ctx: UriResolveContext): Promise<UriMutationResult | void>;
+    write?(input: string, content: UriPayload | Uint8Array | undefined, sources: readonly UriWriteSource[], ctx: UriResolveContext): Promise<UriMutationResult | void>;
     edit?(input: string, patch: UriPayload, ctx: UriResolveContext): Promise<UriMutationResult>;
     /** Observes only; see {@link read}. */
     list?(input: string, params: UriListParams, ctx: UriResolveContext): Promise<UriListResult>;
     /** Observes only; see {@link read}. */
     search?(input: string, params: UriSearchParams, ctx: UriResolveContext): Promise<UriSearchResult>;
     delete?(input: string, ctx: UriResolveContext): Promise<UriMutationResult>;
-    toMarkdown?(input: UriMarkdownRenderInput, ctx: UriResolveContext): string | undefined;
 }
 
 /** Authoritative lifecycle facts for a successful record-like URI mutation. */
@@ -650,6 +699,12 @@ declare interface UriMutationResult {
     readonly receipt?: UriMutationReceipt;
     /** Opaque source-native revision after this successful mutation. */
     readonly revision?: string;
+    /** Cached reads this mutation made stale; see {@link UriCachePolicy.invalidate}. */
+    readonly cachePolicy?: Pick<UriCachePolicy, "invalidate">;
+    /** The module's own markdown for this result, shown instead of the host's default rendering. */
+    readonly markdown?: string;
+    /** The touched resource's name for the transcript row, as on `RawResource.label`. */
+    readonly label?: UriResourceLabel;
 }
 
 declare interface UriNodeCapability {
@@ -670,11 +725,6 @@ declare interface UriNormalizeResult {
 
 declare type UriOperation = "help" | "read" | "write" | "edit" | "list" | "search" | "delete";
 
-/** The call {@link UriModule.amendOperation} rebuilt: the whole payload, in the shape the module reads. */
-declare interface UriOperationAmendment {
-    readonly payload: unknown;
-}
-
 declare interface UriOperationDescription {
     /** Static verb phrase authored by the module. Never interpolated from input. */
     readonly action: string;
@@ -697,9 +747,11 @@ declare interface UriOperationDescription {
              */
             readonly key?: string;
             /**
-             * `true` offers this field to the person for editing on the approval card. Offer it only
-             * when the module implements {@link UriModule.amendOperation} for this call and can honour
-             * any value within `maxLength`; the host drops the offer otherwise. Absent means read-only.
+             * `true` offers this field to the person for editing on the approval card. The host applies
+             * an edit itself: it copies the payload and replaces the value of the top-level string
+             * property named `key`. So offer a field only when the payload is an object, `key` is one
+             * of its string properties, and the module would send any value within `maxLength` as it
+             * sends the model's; the host drops the offer otherwise. Absent means read-only.
              */
             readonly editable?: true;
             /** Longest edited value, in UTF-16 code units. Meaningful only with `editable`. */
@@ -717,56 +769,6 @@ declare interface UriOperationDescription {
     };
 }
 
-/**
- * Pure, route-aware validation that runs before permission policy can surface an ask.
- *
- * This is deliberately narrower than execution: it receives only the canonical URI,
- * operation, and operation payload, performs no I/O, and returns a user-actionable
- * rejection for calls that the module already knows cannot succeed. The handler must
- * still validate again when it executes because approval is not an authority boundary.
- */
-declare interface UriOperationPreflightPolicy {
-    /**
-     * The rejection half. Optional since kay#7684: a module whose only preflight
-     * fact is affirmative (`acceptsPayloadlessWrite`) must not have to stub a
-     * validator that never rejects.
-     */
-    validateOperation?(request: {
-        readonly operation: UriOperation;
-        readonly uri: string;
-        readonly payload: unknown;
-    }): string | undefined;
-    /**
-     * Route-level affirmative: may a `write` to this URI carry NO payload at all
-     * — neither `content` nor `source`? (The canonical case is folder creation,
-     * e.g. `?type=folder`.) The write tool's generic shape rule requires exactly
-     * one payload form; a route answers `true` here when a payloadless write is
-     * meaningful FOR THAT ROUTE, and the rule then admits the call.
-     *
-     * This exists because an empty body is not always sendable: on some
-     * model/provider paths a top-level empty-string argument (`content: ""`)
-     * never reaches the host — the key arrives absent, indistinguishable from an
-     * omitted argument (kay#7684). A contract that can only be invoked with an
-     * empty string is unreachable on those paths, so a route whose write is
-     * meaningful with no body must declare it and let the caller omit the
-     * payload instead.
-     *
-     * Pure and side-effect-free like {@link validateOperation}: route-parse
-     * only, no I/O. A throw NEVER admits the write, but the two consult paths
-     * disagree on purpose about what happens next: pre-ask (permission
-     * resolution, which must never crash the gate) answers no and records a
-     * module-attributed diagnostic; at execute time the write tool asks only
-     * when the call genuinely carries no payload, and a throw there is the
-     * module's own bug surfacing as the call's error — louder than a misleading
-     * \"provide exactly one of content or source\" the model could never
-     * satisfy. Absent means no route of this module accepts a payloadless
-     * write.
-     */
-    acceptsPayloadlessWrite?(request: {
-        readonly uri: string;
-    }): boolean;
-}
-
 declare interface UriParameter {
     readonly name: string;
     readonly in: "uri" | "query" | "selector";
@@ -776,29 +778,60 @@ declare interface UriParameter {
     readonly examples?: readonly unknown[];
 }
 
+/**
+ * A claim on a module's own custom-scheme addresses. The pattern matches with or without an
+ * account prefix: `gcal://@work/events/x` is matched as `gcal://events/x`, and the prefix is put
+ * back on the official spelling, so one claim covers both spellings.
+ */
 declare interface UriPatternClaim {
     readonly kind: "uriPattern";
     readonly pattern: UriPatternInit;
     /**
-     * Canonical spelling rebuilt from the captures. When the template keeps the
-     * input's scheme (the module's own addressing), the input's query string is
+     * Canonical spelling rebuilt from the captures (see {@link UriClaimTemplate}). When the template
+     * keeps the input's scheme (the module's own addressing), the input's query string is
      * carried over verbatim so a route flag such as `?permanent=true` survives
      * canonicalization (kay#7859); a template that re-targets to another scheme
      * (a projection to a web link) drops it, as does a pattern that consumed the
      * query itself or a template that spells its own.
      */
-    readonly normalizeTo?: string;
+    readonly normalizeTo?: UriClaimTemplate;
+    /**
+     * Names the route this claim matches, so data keyed by route (a module's sign-in action rules)
+     * can say which addresses it means. Several claims may name the same route.
+     */
+    readonly route?: string;
+    /**
+     * The web page a matched address opens, filled from the captures (see
+     * {@link UriClaimTemplate}). The host matches an address's official spelling and paints its
+     * reference with the source URL of the first matching claim that declares one.
+     */
+    readonly sourceUrl?: UriClaimTemplate;
+    /**
+     * The name a matched address's reference shows: literal text, with each `:name` replaced by
+     * that capture as decoded (`"Flow :flow"`, or a fixed `"BFS"`). The first matching claim that
+     * declares one names the address.
+     */
+    readonly title?: string;
     readonly examples?: readonly string[];
 }
 
 declare interface UriPatternInit {
     readonly protocol?: string;
+    /**
+     * Dot-delimited host pattern. A pattern that is one capture (`:owner`) takes the whole host,
+     * dots included, as a `github://some.org/repo` owner must.
+     */
     readonly hostname?: string;
     /**
      * Slash-delimited path pattern. A final capture may use `:name*` to consume
-     * the remaining path segments, preserving `/` in the captured value.
+     * the remaining path segments, preserving `/` in the captured value. Unless the pattern itself
+     * ends in `/`, an input path ending in one `/` matches as if the slash were absent, so
+     * `threads/t1/` is `threads/t1` (captures and official spelling included) and a lone `/` after a
+     * host is the empty path; a doubled `//` is never dropped, nor the root path of an address with
+     * no host (`bfs:///`).
      */
     readonly pathname?: string;
+    /** `&`-delimited query pattern; `""` matches only an address with no query. */
     readonly search?: string;
 }
 
@@ -817,7 +850,7 @@ declare interface UriPayloadContract {
 
 /**
  * The three-state permission vocabulary a plugin declares for its default permissions.
- * Maps to `PermissionRule.effect`: `allow` → allow, `ask` → ask, `never` → deny.
+ * Maps to `PermissionRule.effect`: `allow` -> allow, `ask` -> ask, `never` -> deny.
  */
 declare type UriPermissionDefault = "allow" | "ask" | "never";
 
@@ -835,19 +868,6 @@ declare interface UriPermissionDefaults {
     readonly delete?: UriPermissionDefault;
 }
 
-/**
- * One change a person made to an `editable` field of a call's action preview ("Allow with
- * edits"): the field's `key` and the value they want it to hold. Values are message content, so
- * a module must not log or persist them.
- */
-declare interface UriPreviewEdit {
-    readonly key: string;
-    readonly value: string;
-}
-
-/** The read shape a caller may request via {@link UriResolveContext.format}. */
-declare type UriReadFormat = "observation";
-
 declare interface UriResolveContext {
     readonly cwd: string;
     readonly signal?: AbortSignal;
@@ -856,8 +876,8 @@ declare interface UriResolveContext {
     readonly auth?: UriResolvedAuth;
     /**
      * Id of the session dispatching this call, stamped by the host at the dispatch site.
-     * It never originates from anything the caller can influence — no verb argument, no write
-     * body — so a module may treat it as trustworthy caller identity and stamp it onto writes.
+     * It never originates from anything the caller can influence - no verb argument, no write
+     * body - so a module may treat it as trustworthy caller identity and stamp it onto writes.
      *
      * Absent when no session owns the dispatch: registry matching and permission pre-checks
      * resolve a URI outside any verb call.
@@ -865,14 +885,14 @@ declare interface UriResolveContext {
     readonly sessionId?: string;
     /**
      * WHO the dispatching session acts as, stamped by the host at the same dispatch site as
-     * {@link UriResolveContext.sessionId} and just as un-influenceable by the caller — so a module
+     * {@link UriResolveContext.sessionId} and just as un-influenceable by the caller - so a module
      * writing to a store it owns can record the actor without the agent being able to choose one.
      *
      * Free text minted by the host's own runtime (Bonsai's form is `user`, `subagent`,
      * `system/<surface>`, `followup/<surface>`) rather than a closed union: the surface half is the
      * host's vocabulary, and a second enumeration of it here would drift from the first.
      *
-     * Absent whenever the host has nothing to say — no session owns the dispatch, or the session
+     * Absent whenever the host has nothing to say - no session owns the dispatch, or the session
      * predates the host recording an origin. A module must then omit the actor rather than assume
      * one; an invented actor written into a durable artifact can never be walked back.
      */
@@ -888,7 +908,7 @@ declare interface UriResolveContext {
         readonly origin: "model" | "host";
         /**
          * The daemon-assigned id of the run driving this invocation, when the host's own execution
-         * frame carried one. Absent means the frame carried none — never a reason to guess one: a
+         * frame carried one. Absent means the frame carried none - never a reason to guess one: a
          * module recording this onto a durable artifact must treat absence as unresolved provenance,
          * not as "no run was active".
          */
@@ -897,39 +917,33 @@ declare interface UriResolveContext {
         readonly toolName?: string;
     };
     /**
-     * An OPAQUE, host-captured context for the mutation this dispatch is about to make —
+     * An OPAQUE, host-captured context for the mutation this dispatch is about to make -
      * the artifact-provenance counterpart of `sessionId`/`actor`, and stamped at the same
      * un-influenceable dispatch site.
      *
      * The host composes it from facts a caller cannot supply: which session is acting, the
      * run driving it, the tool invocation, and whatever the host resolved about how that
-     * session came to exist. The kernel treats it as an uninterpreted JSON value — it never
+     * session came to exist. The kernel treats it as an uninterpreted JSON value - it never
      * reads a field, only checks that the value is lossless JSON before it crosses the
-     * dispatch boundary — so this layer stays ignorant of any one product's provenance
+     * dispatch boundary - so this layer stays ignorant of any one product's provenance
      * semantics. A module that owns a durable artifact carries it to its store and validates
      * it against its OWN schema at the point it persists, where the target revision is known.
      *
      * Absent means the host captured nothing for this dispatch (a read, a host with no
-     * capture resolver, or a capture that failed) — never a claim that there was nothing to
+     * capture resolver, or a capture that failed) - never a claim that there was nothing to
      * capture. Present only on mutating dispatches (`write`/`edit`/`delete`); reads never pay
      * for it.
      */
     readonly captureContext?: Readonly<Record<string, unknown>>;
     /**
-     * Requested read shape. A module may ignore this and return its normal read; honoring
-     * it means returning an `ObservationMaterial` via `observationResource(...)` instead.
-     * Opt-in only — there is no advertisement surface or capability flag.
-     */
-    readonly format?: UriReadFormat;
-    /**
-     * Host-provided writable data root for the OWNING extension of the module handling this call —
+     * Host-provided writable data root for the OWNING extension of the module handling this call -
      * structurally identical to the per-extension `paths` a tool/handler context already receives, so
      * a module authored against both surfaces reads `ctx.paths?.dataDir` uniformly. Lets a URI module
      * own durable local state (a JSON store, a small file tree) instead of the host constructing and
      * injecting it. Host-populated after dispatch selects a module and keyed to that module's owner;
      * always absent during matching, and absent for modules with no owning extension (builtins) or a
      * host that wires no per-module data dir. Unlike a tool context, the host only NAMES this path for
-     * a URI module and does NOT pre-create the directory — create it on first write and tolerate its
+     * a URI module and does NOT pre-create the directory - create it on first write and tolerate its
      * absence on read.
      */
     readonly paths?: {
@@ -944,6 +958,15 @@ declare interface UriResolveContext {
      * proceeds as before.
      */
     readonly expectedRevision?: string;
+    /**
+     * The revision this session already holds for the address a `read` is about to fetch: the
+     * `RawResourceMetadata.revision` its last read reported. Set only on a repeat `read`, never
+     * on a mutation (`expectedRevision` is the mutation witness). A module with a cheap
+     * current-revision check (a metadata request, a `stat`) may compare first and, when it has
+     * verified the two are equal, answer {@link RawResource.unchanged} with no body. A module
+     * with no such check ignores it and reads in full, which is always correct.
+     */
+    readonly knownRevision?: string;
     /** Host marks a mediated session that enforces its private revision witness ledger. */
     readonly requiresRevisionWitness?: boolean;
     /** Host-derived descriptor for a top-level copied resource; absent for inline writes. */
@@ -953,26 +976,13 @@ declare interface UriResolveContext {
 declare interface UriResolvedAuth {
     readonly connection?: UriConnection;
     /** Present only for verb handlers of a module declaring `requiresAuth`; absent during matching. */
-    readonly credential?: UriResolvedCredential;
+    readonly credential?: ResolvedCredential;
     /** Present for handlers gated by a non-injectable external-CLI readiness scheme. */
     readonly externalCli?: UriExternalCliRunner;
     /** Opaque host metadata; not a credential channel. */
     readonly metadata?: Record<string, unknown>;
 }
 
-declare interface UriResolvedCredential {
-    /** Bearer for OAuth schemes, apiKey for api-key schemes. Host-resolved and refreshed. */
-    readonly accessToken: string;
-    readonly accountId: string;
-    readonly schemeId: string;
-    readonly scopes?: readonly string[];
-    /**
-     * Every value of a multi-field api-key credential, keyed by the scheme's declared field id
-     * (`accessToken` mirrors the primary field). Absent for single-secret schemes.
-     */
-    readonly fields?: Readonly<Record<string, string>>;
-}
-
 declare interface UriResourceDescription {
     readonly uri: string;
     /** Absent when the caller should retain its existing label. */
@@ -992,13 +1002,6 @@ declare interface UriResourceLabel {
     readonly section?: string;
 }
 
-/** The call a module is asked to label. */
-declare interface UriResourceLabelRequest {
-    readonly operation: UriOperation;
-    /** The dispatch address: selector-stripped, the exact form the module's verb handler received. */
-    readonly uri: string;
-}
-
 declare interface UriSchemeClaim {
     readonly kind: "scheme";
     readonly scheme: string;
@@ -1032,15 +1035,21 @@ declare interface UriSearchResult {
      * so the caller knows the matches may be partial.
      */
     readonly metadata?: UriListMetadata;
+    /** How long the host may cache this result; see {@link UriCachePolicy.ttlMs}. */
+    readonly cachePolicy?: Pick<UriCachePolicy, "ttlMs">;
+    /** The module's own markdown for this result, shown instead of the host's default rendering. */
+    readonly markdown?: string;
+    /** The touched resource's name for the transcript row, as on `RawResource.label`. */
+    readonly label?: UriResourceLabel;
 }
 
 /**
  * What a copied resource IS, minus its bytes: the identity half of a mediated
  * source. The host derives it once (filename inferred from the source address,
  * `mimeType` carried from the source module's own `RawResource.mimeType`) and
- * delivers it on both byte-bearing write hooks — inside each `UriWriteSource`,
- * and as the standalone third argument to `writeBytes` — so a remote sink can
- * name and type what it stores without re-deriving either from raw bytes.
+ * delivers it inside each `UriWriteSource`, and on `ctx.writeSource` for a
+ * `source` copy - so a remote sink can name and type what it stores without
+ * re-deriving either from raw bytes.
  */
 declare interface UriSourceDescriptor {
     readonly uri: string;
@@ -1055,11 +1064,11 @@ declare interface UriTemplate {
     /**
      * Per-operation effect docs for this route, keyed by operation. A route
      * whose shared {@link description} spans several verbs ("Read, edit, or
-     * trash a thread") is ambiguous for any surface that groups by verb — a
+     * trash a thread") is ambiguous for any surface that groups by verb - a
      * permission view must not describe `read` with a sentence that mentions
      * trashing. Each entry says what THAT operation concretely does at THIS
      * route; operations without an entry fall back to the shared description.
-     * Additive and optional — existing templates are unaffected.
+     * Additive and optional - existing templates are unaffected.
      */
     readonly operationDocs?: Partial<Record<UriOperation, string>>;
     /**
@@ -1099,13 +1108,13 @@ declare interface UriValidationMessage {
 
 /**
  * Author-declared, human-facing documentation of what each supported verb
- * CONCRETELY does against the provider — the capability half of a module's
+ * CONCRETELY does against the provider - the capability half of a module's
  * boolean verb-support declaration. Written for a permission/capability
  * surface ("what am I allowing?"), not for the model: one plain sentence per
  * verb naming the real-world effect ("Sends mail, creates/updates drafts,
  * applies label changes"), never wire mechanics or URI shapes. Verbs the
  * module does not support are omitted; at runtime a supported verb with no
- * entry simply renders undocumented (fail-open metadata) — but for a plugin's
+ * entry simply renders undocumented (fail-open metadata) - but for a plugin's
  * `kay.agent` URI modules, `auditPluginDisclosure` (`@bonsai/plugin-sdk/
  * disclosure`) enforces coverage of every supported verb at authoring/load
  * time.
@@ -1113,7 +1122,7 @@ declare interface UriValidationMessage {
  * Lives here in the protocol layer (beside {@link UriTemplate.operationDocs},
  * its per-route sibling) so both `@herd/uri-extensions`' `UriExtensionModule`
  * and herd-agent's kernel `UriModule` can carry it without inverting the
- * `@herd/uri` ← `@herd/uri-extensions` dependency.
+ * `@herd/uri` <- `@herd/uri-extensions` dependency.
  */
 declare interface UriVerbDocs {
     /** What a `read` of this address space returns (also covers `help`). */
@@ -1136,6 +1145,7 @@ declare interface UriVerbSupport {
     readonly editable: boolean;
     readonly deletable?: boolean;
     readonly listable: boolean;
+    readonly searchable?: boolean;
 }
 
 /** A mediated resource supplied beside structured write content without entering model context. */
@@ -1143,10 +1153,12 @@ declare interface UriWriteSource extends UriSourceDescriptor {
     readonly content: string | Uint8Array;
 }
 
+/** A claim on a public web link (`http` or `https`), usually folded onto the module's own scheme. */
 declare interface UrlPatternClaim {
     readonly kind: "urlPattern";
     readonly pattern: UriPatternInit;
-    readonly normalizeTo?: string;
+    readonly normalizeTo?: UriClaimTemplate;
+    readonly route?: string;
     readonly examples?: readonly string[];
 }
 
@@ -1157,7 +1169,7 @@ export declare type VendoredMcpClaim = NonNullable<UriExtensionModule["claims"]>
  * Everything a vendored-MCP plugin's URI module is, expressed as data.
  *
  * The plugin package supplies one of these and gets back a conformant {@link UriExtensionModule};
- * it writes no read projection, no help document, and no route parsing. That is deliberate — this
+ * it writes no read projection, no help document, and no route parsing. That is deliberate - this
  * kit exists because five pilot plugins were about to become five copies of one 460-line module,
  * and ~40 more are queued behind them.
  */
@@ -1193,11 +1205,89 @@ export declare interface VendoredMcpDescriptor {
     readonly skills: readonly string[];
 }
 
+/** The claim shapes a vendored plugin declares, with plain mutable arrays so a manifest can spread them. */
+declare type VendoredMcpFactClaim = {
+    kind: "scheme";
+    scheme: string;
+} | {
+    kind: "uriPattern";
+    pattern: FactPattern;
+    normalizeTo: string;
+    route: string;
+    sourceUrl: string;
+} | {
+    kind: "urlPattern";
+    pattern: FactPattern;
+    normalizeTo?: string;
+    route?: string;
+    examples?: string[];
+};
+
+/**
+ * ---
+ * responsibility: The one interface through which a vendored-MCP plugin's code calls a tool on its
+ *   own vendored MCP server, so every read-through plugin and the daemon that implements the port
+ *   agree on the same shape by construction.
+ * owns:
+ *   - {@link VendoredMcpPort} - what a plugin's URI module and tools call.
+ *   - {@link VendoredMcpOutcome} - the typed result a plugin decodes, including every failure it
+ *     must surface to the agent rather than swallow.
+ * does_not_own:
+ *   - The implementation. A plugin never dials MCP itself: it takes the port from
+ *     `api.vendoredMcp.port(server)` (`@bonsai/plugin-sdk/kay-agent`), which the daemon binds to the
+ *     plugin's own hosted server over its MCP host. Plugin source stays host-free, and a plugin
+ *     under test substitutes a fake port.
+ *   - Which tool names exist. `TTool` is the plugin's own union of the vendor tools it calls; the
+ *     port is generic so a typo in a tool name fails typecheck inside the plugin.
+ * ---
+ */
+/**
+ * Why a call failed, as the plugin must tell the agent. `needs-auth` carries the exact service to
+ * reconnect (`serviceId`) so a plugin can name it in its error instead of returning an empty
+ * result; today's plugins name their statically declared `requiresAuth` service instead, which is
+ * the same service for a single-service plugin. `unknown-server` and `unknown-tool` are wiring
+ * faults (a server Bonsai does not host for this plugin, or a tool name the server does not have)
+ * and stay loud for the same reason: an unreachable host must never decode as "no data".
+ */
+declare type VendoredMcpFailureReason = "needs-auth" | "unknown-server" | "unknown-tool" | "failed";
+
+export declare type VendoredMcpOutcome = 
+/**
+* `value` is the tool's `structuredContent` when it sent one, else its text content parsed as
+* JSON, else that text as a string: a vendor tool that answers in prose (a transcript, a
+* markdown summary) is a result, not a failure. A route that needs a record rejects a string
+* itself, with its own message.
+*/
+    {
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly ok: false;
+    readonly reason: VendoredMcpFailureReason;
+    readonly message: string;
+    /** Exact reconnect target supplied by the MCP host for an auth failure. */
+    readonly serviceId?: string;
+};
+
+/**
+ * One vendored MCP server, as the plugin that declares it calls it. `invoke` calls any tool the
+ * server has, whether it reads or writes. The port checks no permission of its own: a call is as
+ * permitted as the plugin tool or URI verb that makes it.
+ */
+export declare interface VendoredMcpPort<TTool extends string = string> {
+    invoke(input: {
+        /** The session's working directory; the host resolves the server binding per cwd. */
+        readonly cwd: string;
+        readonly tool: TTool;
+        readonly args: Readonly<Record<string, unknown>>;
+    }): Promise<VendoredMcpOutcome>;
+}
+
 /**
  * One addressable resource shape, as the PAIR that makes the whole pattern work: the canonical
- * `<ns>://…` URI Bonsai stores, and the public web URL that URI came from and opens back to.
+ * `<ns>://...` URI Bonsai stores, and the public web URL that URI came from and opens back to.
  *
- * Both templates use the same `:name` capture syntax and MUST name exactly the same captures —
+ * Both templates use the same `:name` capture syntax and MUST name exactly the same captures -
  * {@link createVendoredMcpUriModule} throws otherwise. That symmetry is the point: a canonical
  * URI carrying an id the web URL drops is a pill that cannot be opened, and a web URL naming a
  * capture the canonical URI never captured renders a literal `:pageId` into the user's browser.
@@ -1214,4 +1304,43 @@ export declare interface VendoredMcpRoute {
     readonly example: string;
 }
 
+/** What a vendored-MCP plugin's manifest declares for its URI module. */
+export declare interface VendoredMcpUriModuleFacts {
+    description: string;
+    agentHint: {
+        summary: string;
+        commonFlows: {
+            label: string;
+            example: string;
+        }[];
+        triggers: {
+            keywords: string[];
+        };
+        helpUri: string;
+        skills: string[];
+    };
+    verbs: {
+        readable: true;
+        writable: false;
+        editable: false;
+        listable: false;
+    };
+    verbDocs: {
+        read: string;
+    };
+    templates: {
+        uri: string;
+        description: string;
+        operations: ["read"];
+    }[];
+    claims: VendoredMcpFactClaim[];
+}
+
+/**
+ * The facts for one descriptor. Each route becomes a `uriPattern` claim whose `normalizeTo` is the
+ * route's canonical URI and whose `sourceUrl` is the route's web URL, so a pasted or stored address
+ * resolves to its canonical spelling and a pill that opens the vendor's page.
+ */
+export declare function vendoredMcpUriModuleFacts(descriptor: VendoredMcpDescriptor): VendoredMcpUriModuleFacts;
+
 export { }