@pithy-sh/core 0.13.0 → 0.14.0

package/dist/logger/record.d.ts

@@ -121,6 +121,13 @@ export declare const LogRecord: z.ZodObject<{
         detail: z.ZodOptional<z.ZodString>;
         code: z.ZodLiteral<"auth/account_deleted">;
         status: z.ZodLiteral<403>;
+    }, z.core.$strip>, z.ZodObject<{
+        message: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        action: z.ZodOptional<z.ZodString>;
+        detail: z.ZodOptional<z.ZodString>;
+        code: z.ZodLiteral<"auth/handoff_invalid">;
+        status: z.ZodLiteral<400>;
     }, z.core.$strip>, z.ZodObject<{
         message: z.ZodString;
         params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
@@ -198,6 +205,20 @@ export declare const LogRecord: z.ZodObject<{
         detail: z.ZodOptional<z.ZodString>;
         code: z.ZodLiteral<"core/webhook_unverified">;
         status: z.ZodLiteral<401>;
+    }, z.core.$strip>, z.ZodObject<{
+        message: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        action: z.ZodOptional<z.ZodString>;
+        detail: z.ZodOptional<z.ZodString>;
+        code: z.ZodLiteral<"core/presence_ticket_invalid">;
+        status: z.ZodLiteral<401>;
+    }, z.core.$strip>, z.ZodObject<{
+        message: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        action: z.ZodOptional<z.ZodString>;
+        detail: z.ZodOptional<z.ZodString>;
+        code: z.ZodLiteral<"core/presence_room_full">;
+        status: z.ZodLiteral<409>;
     }, z.core.$strip>, z.ZodObject<{
         message: z.ZodString;
         params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
@@ -527,6 +548,27 @@ export declare const LogRecord: z.ZodObject<{
         detail: z.ZodOptional<z.ZodString>;
         code: z.ZodLiteral<"ledger/invalid_amount">;
         status: z.ZodLiteral<400>;
+    }, z.core.$strip>, z.ZodObject<{
+        message: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        action: z.ZodOptional<z.ZodString>;
+        detail: z.ZodOptional<z.ZodString>;
+        code: z.ZodLiteral<"ledger/entry_not_found">;
+        status: z.ZodLiteral<404>;
+    }, z.core.$strip>, z.ZodObject<{
+        message: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        action: z.ZodOptional<z.ZodString>;
+        detail: z.ZodOptional<z.ZodString>;
+        code: z.ZodLiteral<"ledger/entry_not_reversible">;
+        status: z.ZodLiteral<409>;
+    }, z.core.$strip>, z.ZodObject<{
+        message: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        action: z.ZodOptional<z.ZodString>;
+        detail: z.ZodOptional<z.ZodString>;
+        code: z.ZodLiteral<"ledger/ref_conflict">;
+        status: z.ZodLiteral<409>;
     }, z.core.$strip>, z.ZodObject<{
         message: z.ZodString;
         params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
@@ -569,6 +611,62 @@ export declare const LogRecord: z.ZodObject<{
         detail: z.ZodOptional<z.ZodString>;
         code: z.ZodLiteral<"rating/record_forbidden">;
         status: z.ZodLiteral<403>;
+    }, z.core.$strip>, z.ZodObject<{
+        message: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        action: z.ZodOptional<z.ZodString>;
+        detail: z.ZodOptional<z.ZodString>;
+        code: z.ZodLiteral<"consent/unknown_purpose">;
+        status: z.ZodLiteral<404>;
+    }, z.core.$strip>, z.ZodObject<{
+        message: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        action: z.ZodOptional<z.ZodString>;
+        detail: z.ZodOptional<z.ZodString>;
+        code: z.ZodLiteral<"consent/stale_notice">;
+        status: z.ZodLiteral<409>;
+    }, z.core.$strip>, z.ZodObject<{
+        message: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        action: z.ZodOptional<z.ZodString>;
+        detail: z.ZodOptional<z.ZodString>;
+        code: z.ZodLiteral<"consent/method_below_minimum">;
+        status: z.ZodLiteral<400>;
+    }, z.core.$strip>, z.ZodObject<{
+        message: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        action: z.ZodOptional<z.ZodString>;
+        detail: z.ZodOptional<z.ZodString>;
+        code: z.ZodLiteral<"consent/withdrawal_below_grant">;
+        status: z.ZodLiteral<400>;
+    }, z.core.$strip>, z.ZodObject<{
+        message: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        action: z.ZodOptional<z.ZodString>;
+        detail: z.ZodOptional<z.ZodString>;
+        code: z.ZodLiteral<"consent/evidence_missing">;
+        status: z.ZodLiteral<400>;
+    }, z.core.$strip>, z.ZodObject<{
+        message: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        action: z.ZodOptional<z.ZodString>;
+        detail: z.ZodOptional<z.ZodString>;
+        code: z.ZodLiteral<"consent/expiry_passed">;
+        status: z.ZodLiteral<400>;
+    }, z.core.$strip>, z.ZodObject<{
+        message: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        action: z.ZodOptional<z.ZodString>;
+        detail: z.ZodOptional<z.ZodString>;
+        code: z.ZodLiteral<"consent/document_not_found">;
+        status: z.ZodLiteral<404>;
+    }, z.core.$strip>, z.ZodObject<{
+        message: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        action: z.ZodOptional<z.ZodString>;
+        detail: z.ZodOptional<z.ZodString>;
+        code: z.ZodLiteral<"consent/evidence_store_missing">;
+        status: z.ZodLiteral<500>;
     }, z.core.$strip>, z.ZodObject<{
         message: z.ZodString;
         params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;

package/dist/logger/record.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../../src/logger/record.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;GAKG;AAEH,4GAA4G;AAC5G,eAAO,MAAM,QAAQ;;;;;EAE4F,CAAC;AAClH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,QAAQ,CAAC,CAAC;AAEjD;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAgD,CAAC;AAEtG;;;;GAIG;AACH,eAAO,MAAM,SAAS,wCAEsF,CAAC;AAC7G,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,SAAS,CAAC,CAAC;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAW+E,CAAC;AACtG,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,SAAS,CAAC,CAAC;AAmBnD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAMzD"}
+{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../../src/logger/record.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;GAKG;AAEH,4GAA4G;AAC5G,eAAO,MAAM,QAAQ;;;;;EAE4F,CAAC;AAClH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,QAAQ,CAAC,CAAC;AAEjD;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAgD,CAAC;AAEtG;;;;GAIG;AACH,eAAO,MAAM,SAAS,wCAEsF,CAAC;AAC7G,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,SAAS,CAAC,CAAC;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAW+E,CAAC;AACtG,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,SAAS,CAAC,CAAC;AAmBnD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAMzD"}

package/dist/mcp/annotations.d.ts

@@ -0,0 +1,20 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { ScopeKind } from "../controlPlane/scope/kind";
+/**
+ * What an MCP tool says about itself, from the kind of thing it does. One mapping for both servers: the app's own
+ * tools, whose effect is a kind without `reads` or `credentials`, and the control-plane tools `pithy mcp serve`
+ * offers, whose route declares its scope's kind.
+ */
+/** The MCP annotations a tool carries, set by its kind. `idempotentHint` is claimed for a read and nothing else. */
+export interface ToolAnnotations {
+    readonly readOnlyHint: boolean;
+    readonly destructiveHint: boolean;
+    readonly idempotentHint?: true;
+    readonly openWorldHint: boolean;
+}
+/** What each kind says in a tool's description, and on the consent screen. One sentence each. */
+export declare const KIND_SENTENCES: Readonly<Record<ScopeKind, string>>;
+/** The MCP annotations for a kind. */
+export declare function kindAnnotations(kind: ScopeKind): ToolAnnotations;
+//# sourceMappingURL=annotations.d.ts.map

package/dist/mcp/annotations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotations.d.ts","sourceRoot":"","sources":["../../src/mcp/annotations.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAE5D;;;;GAIG;AAEH,oHAAoH;AACpH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,cAAc,CAAC,EAAE,IAAI,CAAC;IAC/B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CACjC;AAED,iGAAiG;AACjG,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAO9D,CAAC;AAEF,sCAAsC;AACtC,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,GAAG,eAAe,CAOhE"}

package/dist/mcp/annotations.js

@@ -0,0 +1,23 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+//#region src/mcp/annotations.ts
+/** What each kind says in a tool's description, and on the consent screen. One sentence each. */
+const KIND_SENTENCES = {
+	reads: "Reads data and changes nothing.",
+	writes: "Changes data in this application.",
+	sends: "Sends a message to somebody.",
+	charges: "Charges money.",
+	deletes: "Deletes data, and it cannot be undone.",
+	credentials: "Mints, rotates or revokes a credential."
+};
+/** The MCP annotations for a kind. */
+function kindAnnotations(kind) {
+	return {
+		readOnlyHint: kind === "reads",
+		destructiveHint: kind === "charges" || kind === "deletes" || kind === "credentials",
+		...kind === "reads" ? { idempotentHint: true } : {},
+		openWorldHint: kind === "sends" || kind === "charges"
+	};
+}
+//#endregion
+export { KIND_SENTENCES, kindAnnotations };

package/dist/mcp/tools.d.ts

@@ -0,0 +1,75 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { type ToolEffect } from "../http/routeSpec";
+import type { RouteGroup } from "../openapi/document";
+import { type ToolAnnotations } from "./annotations";
+/**
+ * The app's own MCP tools, read off the composed router (`docs/AGENT-ACCESS.md` §4.1, §5).
+ *
+ * **The route declarations are already a tool list.** A route that opts in with `describeRoute({ tool })` carries
+ * everything a tool definition needs: the `summary` an agent chooses on, a `description` for what the schemas do not
+ * say, the `power` that gates it, the `scopes` a caller must carry, and an `operation` that names it. Its input is
+ * the route's own `validate(...)` schemas, in the same `{ path, query, body }` shape the control-plane server's tools
+ * take. Nothing is written twice: a route that changes its body, its power or its summary changes its tool on the
+ * same commit.
+ *
+ * **A tool inherits its route's power. That is the whole mapping**, and there is no tool-to-role table to maintain.
+ */
+/** One route, as a tool. */
+export interface AppTool {
+    /** `<capability>_<operation>`, through the control-plane server's normalizer. */
+    readonly name: string;
+    /** The capability that registered the route — the unit of consent. */
+    readonly capability: string;
+    /** The route's declared operation. */
+    readonly operation: string;
+    /** The HTTP method a call dispatches with. */
+    readonly method: string;
+    /** The mounted path a call dispatches to, Hono's spelling. */
+    readonly path: string;
+    /** The route's summary, in its capability's own words. What the consent screen lists. */
+    readonly summary: string;
+    /** What an agent reads: the summary, the route's description, and its effect said aloud. */
+    readonly description: string;
+    /** The route's input as JSON Schema. */
+    readonly inputSchema: Record<string, unknown>;
+    /** What the tool does beyond reading, or `null` for a read. */
+    readonly effect: ToolEffect | null;
+    /** The MCP annotations its effect sets. */
+    readonly annotations: ToolAnnotations;
+    /** The power the caller's role must hold, or `undefined` when the route declares none. */
+    readonly power: string | undefined;
+    /** The attestation scopes a caller must carry, from `describeRoute({ scopes })`. */
+    readonly scopes: readonly string[];
+}
+/** What each effect says in a tool's description and on the consent screen. One sentence each. */
+export declare const EFFECT_SENTENCES: Readonly<Record<ToolEffect, string>>;
+/** The MCP annotations for an effect. `null` is a read. */
+export declare function toolAnnotations(effect: ToolEffect | null): ToolAnnotations;
+/**
+ * Refuse a composition whose tool declarations are wrong, naming the route.
+ *
+ * **This is where "it does not compile" is enforced.** `describeRoute` cannot see the method it is mounted under, so
+ * a `POST` saying `tool: true` type-checks; `createBackend` calls this at assembly, so the Worker refuses to boot
+ * and the kit's own composition fails its tests. Five checks: a non-`GET` opting in without an effect, a `GET`
+ * declaring one, a tool with no operation, an operation outside the published alphabet, and two routes sharing an
+ * operation within a capability — or two capabilities whose names normalize to one tool.
+ */
+export declare function assertToolDeclarations(groups: readonly RouteGroup[]): void;
+/** Every tool these groups declare, in registration order. Refuses a wrong declaration first. */
+export declare function appTools(groups: readonly RouteGroup[]): AppTool[];
+/** What a caller holds, for {@link offeredTools}. */
+export interface ToolCaller {
+    /** Whether the caller's role holds a power, or `null` when no organization is in force — nothing is held. */
+    readonly roleAllows: ((power: string) => boolean) | null;
+    /** The attestation scopes the caller carries. */
+    readonly scopes: readonly string[];
+}
+/** Whether this caller may call this tool, by exactly the checks its route makes. */
+export declare function mayCall(tool: AppTool, caller: ToolCaller): boolean;
+/**
+ * The tools this caller may call. **A tool a role withholds is absent, not locked**: offering it discloses that it
+ * exists and spends a call to learn what the answer would be (`docs/AGENT-ACCESS.md` §4.1).
+ */
+export declare function offeredTools(tools: readonly AppTool[], caller: ToolCaller): AppTool[];
+//# sourceMappingURL=tools.d.ts.map

package/dist/mcp/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/mcp/tools.ts"],"names":[],"mappings":"AAOA,OAAO,EAA+B,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACjF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEtD,OAAO,EAAmC,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAEtF;;;;;;;;;;;GAWG;AAEH,4BAA4B;AAC5B,MAAM,WAAW,OAAO;IACtB,iFAAiF;IACjF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,sCAAsC;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,8CAA8C;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yFAAyF;IACzF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,4FAA4F;IAC5F,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,wCAAwC;IACxC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9C,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;IACnC,2CAA2C;IAC3C,QAAQ,CAAC,WAAW,EAAE,eAAe,CAAC;IACtC,0FAA0F;IAC1F,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,oFAAoF;IACpF,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED,kGAAkG;AAClG,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAKjE,CAAC;AAEF,2DAA2D;AAC3D,wBAAgB,eAAe,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,GAAG,eAAe,CAE1E;AA0CD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,GAAG,IAAI,CAiD1E;AASD,iGAAiG;AACjG,wBAAgB,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,GAAG,OAAO,EAAE,CAuBjE;AAED,qDAAqD;AACrD,MAAM,WAAW,UAAU;IACzB,6GAA6G;IAC7G,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,IAAI,CAAC;IACzD,iDAAiD;IACjD,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED,qFAAqF;AACrF,wBAAgB,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAGlE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,OAAO,EAAE,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,EAAE,CAErF"}

package/dist/mcp/tools.js

@@ -0,0 +1,118 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { ValidationError } from "../error/pithyError.js";
+import { routeSpecOf } from "../http/routeSpec.js";
+import { AdminOperation } from "../controlPlane/discovery/adminRoute.js";
+import { isMiddlewareOnly, operationsOf } from "../openapi/operations.js";
+import { inputOf } from "../controlPlane/discovery/routeInput.js";
+import { controlPlaneToolName } from "../controlPlane/discovery/toolName.js";
+import { KIND_SENTENCES, kindAnnotations } from "./annotations.js";
+//#region src/mcp/tools.ts
+/** What each effect says in a tool's description and on the consent screen. One sentence each. */
+const EFFECT_SENTENCES = {
+	writes: KIND_SENTENCES.writes,
+	sends: KIND_SENTENCES.sends,
+	charges: KIND_SENTENCES.charges,
+	deletes: KIND_SENTENCES.deletes
+};
+/** The MCP annotations for an effect. `null` is a read. */
+function toolAnnotations(effect) {
+	return kindAnnotations(effect ?? "reads");
+}
+/** Every described route in these groups, with the method it is mounted under. */
+function described(groups) {
+	return groups.flatMap((group) => operationsOf(group.routes).filter((operation) => !isMiddlewareOnly(operation)).flatMap((operation) => {
+		const spec = operation.handlers.map(routeSpecOf).find((candidate) => candidate !== void 0);
+		return spec === void 0 ? [] : [{
+			capability: group.tag,
+			method: operation.method.toUpperCase(),
+			path: operation.path,
+			spec,
+			handlers: operation.handlers
+		}];
+	}));
+}
+function refuse(message, detail) {
+	throw new ValidationError({
+		message,
+		action: "Fix the route's describeRoute({ operation, tool }). A GET opts in with `tool: true`; any other method declares `tool: { effect }`.",
+		detail
+	});
+}
+/**
+* Refuse a composition whose tool declarations are wrong, naming the route.
+*
+* **This is where "it does not compile" is enforced.** `describeRoute` cannot see the method it is mounted under, so
+* a `POST` saying `tool: true` type-checks; `createBackend` calls this at assembly, so the Worker refuses to boot
+* and the kit's own composition fails its tests. Five checks: a non-`GET` opting in without an effect, a `GET`
+* declaring one, a tool with no operation, an operation outside the published alphabet, and two routes sharing an
+* operation within a capability — or two capabilities whose names normalize to one tool.
+*/
+function assertToolDeclarations(groups) {
+	const operations = /* @__PURE__ */ new Map();
+	const names = /* @__PURE__ */ new Map();
+	for (const route of described(groups)) {
+		const where = `${route.method} ${route.path}`;
+		const { operation, tool } = route.spec;
+		if (operation !== void 0) {
+			if (!AdminOperation.safeParse(operation).success) refuse(`The operation "${operation}" on ${where} is not a valid name.`, `capability ${route.capability} route ${where} declares operation "${operation}"; an operation is lowercase words joined by ".", "_" or "-"`);
+			const key = `${route.capability} ${operation}`;
+			const earlier = operations.get(key);
+			if (earlier !== void 0) refuse(`Two ${route.capability} routes declare the operation "${operation}".`, `${earlier} and ${where} both declare operation "${operation}" in capability ${route.capability}`);
+			operations.set(key, where);
+		}
+		if (tool === void 0) continue;
+		if (operation === void 0) refuse(`${where} opts in as a tool with no operation.`, `capability ${route.capability} route ${where} declares tool but no operation, so its tool has no name`);
+		if (route.method !== "GET" && tool === true) refuse(`${where} opts in as a tool without an effect.`, `capability ${route.capability} route ${where} is not a GET, so it must declare tool: { effect } (writes, sends, charges or deletes)`);
+		if (route.method === "GET" && tool !== true) refuse(`${where} is a read and declares an effect.`, `capability ${route.capability} route ${where} is a GET; a GET opts in with tool: true`);
+		const name = controlPlaneToolName(route.capability, operation);
+		const clash = names.get(name);
+		if (clash !== void 0) refuse(`Two routes are both the tool ${name}.`, `${clash} and ${where} both normalize to the tool name ${name}`);
+		names.set(name, where);
+	}
+}
+/** The description an agent reads: the summary, the route's own description, and its effect. */
+function descriptionOf(spec, effect) {
+	return [
+		spec.summary,
+		spec.description,
+		effect === null ? void 0 : EFFECT_SENTENCES[effect]
+	].filter((part) => part !== void 0 && part.length > 0).join(" ");
+}
+/** Every tool these groups declare, in registration order. Refuses a wrong declaration first. */
+function appTools(groups) {
+	assertToolDeclarations(groups);
+	return described(groups).flatMap((route) => {
+		const { spec } = route;
+		if (spec.tool === void 0 || spec.operation === void 0) return [];
+		const effect = spec.tool === true ? null : spec.tool.effect;
+		return [{
+			name: controlPlaneToolName(route.capability, spec.operation),
+			capability: route.capability,
+			operation: spec.operation,
+			method: route.method,
+			path: route.path,
+			summary: spec.summary,
+			description: descriptionOf(spec, effect),
+			inputSchema: inputOf(route.handlers),
+			effect,
+			annotations: toolAnnotations(effect),
+			power: spec.power,
+			scopes: spec.scopes ?? []
+		}];
+	});
+}
+/** Whether this caller may call this tool, by exactly the checks its route makes. */
+function mayCall(tool, caller) {
+	if (tool.power !== void 0 && (caller.roleAllows === null || !caller.roleAllows(tool.power))) return false;
+	return tool.scopes.every((scope) => caller.scopes.includes(scope));
+}
+/**
+* The tools this caller may call. **A tool a role withholds is absent, not locked**: offering it discloses that it
+* exists and spends a call to learn what the answer would be (`docs/AGENT-ACCESS.md` §4.1).
+*/
+function offeredTools(tools, caller) {
+	return tools.filter((tool) => mayCall(tool, caller));
+}
+//#endregion
+export { EFFECT_SENTENCES, appTools, assertToolDeclarations, mayCall, offeredTools, toolAnnotations };

package/dist/openapi/document.d.ts.map

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

package/dist/openapi/document.js

@@ -1,10 +1,11 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
-import { CONTROL_PLANE_HEADER } from "../controlPlane/wire.js";
+import { ErrorBody } from "../error/wire.js";
 import { routeSpecOf } from "../http/routeSpec.js";
 import { requestContractOf } from "../http/validation.js";
-import { ErrorBody } from "../error/wire.js";
+import { CONTROL_PLANE_HEADER } from "../controlPlane/wire.js";
 import { pathParams } from "../http/routeContract.js";
+import { isMiddlewareOnly, operationsOf } from "./operations.js";
 import { z } from "zod";
 //#region src/openapi/document.ts
 /**
@@ -29,7 +30,7 @@ const SECURITY_SCHEMES = {
 	bearer: {
 		type: "http",
 		scheme: "bearer",
-		description: "A short-lived access token from `@pithy-sh/auth`, sent as `Authorization: Bearer <token>`."
+		description: "A session token from `@pithy-sh/auth`, sent as `Authorization: Bearer <token>`: the one sign-in returns, then the `refreshToken` each `/token/rotate` answers with. The rotation's `accessToken` is a JWT for services outside the Worker, and these routes refuse it."
 	},
 	session: {
 		type: "apiKey",
@@ -76,28 +77,6 @@ function jsonSchema(schema, io) {
 	});
 	return rest;
 }
-function operationsOf(routes) {
-	const byKey = /* @__PURE__ */ new Map();
-	for (const route of routes) {
-		const key = `${route.method} ${route.path}`;
-		const entry = byKey.get(key) ?? {
-			method: route.method,
-			path: route.path,
-			handlers: []
-		};
-		entry.handlers.push(route.handler);
-		byKey.set(key, entry);
-	}
-	return [...byKey.values()];
-}
-/**
-* An `ALL` entry with no spec is `app.use` — middleware, not a route — because Hono records both as
-* `ALL`. An `app.all` route that forgot its `describeRoute` is therefore invisible to the coverage
-* check, which is the one blind spot here; the kit has one such route and it is described.
-*/
-function isMiddlewareOnly(operation) {
-	return operation.method === "ALL" && !operation.handlers.some((handler) => routeSpecOf(handler));
-}
 /** Every route in these groups that registered no `describeRoute`. Empty is the contract being met. */
 function undescribedRoutes(groups) {
 	return groups.flatMap((group) => operationsOf(group.routes).filter((operation) => !isMiddlewareOnly(operation)).filter((operation) => !operation.handlers.some((handler) => routeSpecOf(handler))).map(({ method, path }) => ({
@@ -204,7 +183,10 @@ function operationOf(tag, method, operation, spec) {
 			security,
 			"x-pithy-verification": strategies
 		},
-		...spec.scopes === void 0 || spec.scopes.length === 0 ? {} : { "x-pithy-scopes": spec.scopes }
+		...spec.scopes === void 0 || spec.scopes.length === 0 ? {} : { "x-pithy-scopes": spec.scopes },
+		...spec.power === void 0 ? {} : { "x-pithy-power": spec.power },
+		...spec.operation === void 0 ? {} : { "x-pithy-operation": spec.operation },
+		...spec.tool === void 0 ? {} : { "x-pithy-tool": spec.tool === true ? { effect: null } : spec.tool }
 	};
 }
 /** The methods an operation is documented under: its own, or for `app.all` the ones its spec names. */

package/dist/openapi/operations.d.ts

@@ -0,0 +1,35 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { type RouteSpec } from "../http/routeSpec";
+import type { RouteGroup, RouterRoute } from "./document";
+/**
+ * The composed route table as operations: one per method and path, with the spec its `describeRoute` declared.
+ *
+ * Hono keeps one entry per handler, so a route with a `describeRoute` ahead of its handler appears twice in
+ * `app.routes`. Two readers need the grouped view: the OpenAPI document, which turns each operation into a path
+ * item, and the evidence pack (#821), which counts how every route verifies its caller. They group the same way
+ * because they group here, and the pack never loads the JSON Schema conversion the document needs.
+ */
+/** One route's handlers, grouped by method and path the way Hono stores them: one entry per handler. */
+export interface Operation {
+    readonly method: string;
+    readonly path: string;
+    readonly handlers: unknown[];
+}
+/** Group a route table into operations, in registration order. */
+export declare function operationsOf(routes: readonly RouterRoute[]): Operation[];
+/**
+ * An `ALL` entry with no spec is `app.use` — middleware, not a route — because Hono records both as
+ * `ALL`. An `app.all` route that forgot its `describeRoute` is therefore invisible to the coverage
+ * check, which is the one blind spot here; the kit has one such route and it is described.
+ */
+export declare function isMiddlewareOnly(operation: Operation): boolean;
+/** One route, and the spec it declared — `undefined` for a route that registered no `describeRoute`. */
+export interface DescribedOperation {
+    readonly method: string;
+    readonly path: string;
+    readonly spec: RouteSpec | undefined;
+}
+/** Every route in these groups, middleware left out, each with the spec it declared or `undefined`. */
+export declare function describedOperations(groups: readonly RouteGroup[]): DescribedOperation[];
+//# sourceMappingURL=operations.d.ts.map

package/dist/openapi/operations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operations.d.ts","sourceRoot":"","sources":["../../src/openapi/operations.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,SAAS,EAAe,MAAM,mBAAmB,CAAC;AAChE,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE1D;;;;;;;GAOG;AAEH,wGAAwG;AACxG,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,OAAO,EAAE,CAAC;CAC9B;AAED,kEAAkE;AAClE,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,GAAG,SAAS,EAAE,CASxE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAE9D;AAED,wGAAwG;AACxG,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,CAAC;CACtC;AAED,uGAAuG;AACvG,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,GAAG,kBAAkB,EAAE,CAUvF"}

package/dist/openapi/operations.js

@@ -0,0 +1,37 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { routeSpecOf } from "../http/routeSpec.js";
+//#region src/openapi/operations.ts
+/** Group a route table into operations, in registration order. */
+function operationsOf(routes) {
+	const byKey = /* @__PURE__ */ new Map();
+	for (const route of routes) {
+		const key = `${route.method} ${route.path}`;
+		const entry = byKey.get(key) ?? {
+			method: route.method,
+			path: route.path,
+			handlers: []
+		};
+		entry.handlers.push(route.handler);
+		byKey.set(key, entry);
+	}
+	return [...byKey.values()];
+}
+/**
+* An `ALL` entry with no spec is `app.use` — middleware, not a route — because Hono records both as
+* `ALL`. An `app.all` route that forgot its `describeRoute` is therefore invisible to the coverage
+* check, which is the one blind spot here; the kit has one such route and it is described.
+*/
+function isMiddlewareOnly(operation) {
+	return operation.method === "ALL" && !operation.handlers.some((handler) => routeSpecOf(handler));
+}
+/** Every route in these groups, middleware left out, each with the spec it declared or `undefined`. */
+function describedOperations(groups) {
+	return groups.flatMap((group) => operationsOf(group.routes).filter((operation) => !isMiddlewareOnly(operation)).map((operation) => ({
+		method: operation.method,
+		path: operation.path,
+		spec: operation.handlers.map(routeSpecOf).find((candidate) => candidate !== void 0)
+	})));
+}
+//#endregion
+export { describedOperations, isMiddlewareOnly, operationsOf };

package/dist/presence/channel.d.ts

@@ -0,0 +1,11 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { SocketChannel } from "../http/socket";
+import { type PresenceDeclaration } from "./declaration";
+/**
+ * A capability's presence room socket, declared for the AsyncAPI contract. `defineCapability` adds it to the
+ * capability's `sockets` whenever it declares room kinds, from the same `basePath` the routes mount on, so a
+ * declared socket and a mounted one cannot be two different things.
+ */
+export declare function presenceRoomsSocket(capability: string, presence: PresenceDeclaration): SocketChannel;
+//# sourceMappingURL=channel.d.ts.map

package/dist/presence/channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../../src/presence/channel.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,KAAK,mBAAmB,EAAsB,MAAM,eAAe,CAAC;AAc7E;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,mBAAmB,GAAG,aAAa,CAsBpG"}

package/dist/presence/channel.js

@@ -0,0 +1,65 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { PRESENCE_ROOM_VERSIONS, PresenceActivityFrame, PresenceJoinedFrame, PresenceLeftFrame, PresenceRoomErrorFrame, PresenceRoomInitFrame, PresenceRoomPing, PresenceRoomPong, PresenceSetActivityFrame } from "./frames.js";
+import { presenceSocketPath } from "./declaration.js";
+import { PresenceRoomParams } from "./http/schemas.js";
+//#region src/presence/channel.ts
+/**
+* A capability's presence room socket, declared for the AsyncAPI contract. `defineCapability` adds it to the
+* capability's `sockets` whenever it declares room kinds, from the same `basePath` the routes mount on, so a
+* declared socket and a mounted one cannot be two different things.
+*/
+function presenceRoomsSocket(capability, presence) {
+	return {
+		name: `${capability}PresenceRooms`,
+		path: presenceSocketPath(presence.basePath),
+		summary: `Who else has a ${capability} record open, and what they are doing, live.`,
+		description: `Mint a ticket first — \`POST /control-plane/presence/tickets\` for a management client, \`POST ${presence.basePath}/presence/tickets\` for a signed-in user — then offer \`pithy.presence.v1\` and \`pithy.ticket.<ticket>\` in \`Sec-WebSocket-Protocol\`. The ticket is the credential: single use, 60 seconds, this room only. The room sends \`init\` first, then \`joined\`, \`left\` and \`activity\` as they happen. Send \`set_activity\` to announce one of the kind's declared activities, and \`ping\` as plain text to get \`pong\`. Room kinds: ${presence.rooms.map((room) => `\`${room.kind}\``).join(", ")}.`,
+		verification: "public",
+		params: PresenceRoomParams,
+		versions: PRESENCE_ROOM_VERSIONS,
+		send: [
+			{
+				name: "init",
+				summary: "Everyone in the room, sent once on connect.",
+				schema: PresenceRoomInitFrame
+			},
+			{
+				name: "joined",
+				summary: "Another participant joined.",
+				schema: PresenceJoinedFrame
+			},
+			{
+				name: "left",
+				summary: "Another participant left, or their socket dropped.",
+				schema: PresenceLeftFrame
+			},
+			{
+				name: "activity",
+				summary: "Another participant changed what they are doing.",
+				schema: PresenceActivityFrame
+			},
+			{
+				name: "error",
+				summary: "A frame the room could not accept.",
+				schema: PresenceRoomErrorFrame
+			},
+			{
+				name: "pong",
+				summary: "The answer to `ping`, as plain text.",
+				text: PresenceRoomPong.value
+			}
+		],
+		receive: [{
+			name: "set_activity",
+			summary: "Announce a declared activity.",
+			schema: PresenceSetActivityFrame
+		}, {
+			name: "ping",
+			summary: "The keepalive, as plain text.",
+			text: PresenceRoomPing.value
+		}]
+	};
+}
+//#endregion
+export { presenceRoomsSocket };