@pithy-sh/core 0.12.0 → 0.14.0

package/src/mcp/annotations.ts

@@ -0,0 +1,38 @@
+// 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 const KIND_SENTENCES: Readonly<Record<ScopeKind, string>> = {
+  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. */
+export function kindAnnotations(kind: ScopeKind): ToolAnnotations {
+  return {
+    readOnlyHint: kind === "reads",
+    destructiveHint: kind === "charges" || kind === "deletes" || kind === "credentials",
+    ...(kind === "reads" ? { idempotentHint: true as const } : {}),
+    openWorldHint: kind === "sends" || kind === "charges",
+  };
+}

package/src/mcp/tools.ts

@@ -0,0 +1,220 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { AdminOperation } from "../controlPlane/discovery/adminRoute";
+import { inputOf } from "../controlPlane/discovery/routeInput";
+import { controlPlaneToolName } from "../controlPlane/discovery/toolName";
+import { ValidationError } from "../error/pithyError";
+import { type RouteSpec, routeSpecOf, type ToolEffect } from "../http/routeSpec";
+import type { RouteGroup } from "../openapi/document";
+import { isMiddlewareOnly, operationsOf } from "../openapi/operations";
+import { KIND_SENTENCES, kindAnnotations, 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 const EFFECT_SENTENCES: Readonly<Record<ToolEffect, string>> = {
+  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. */
+export function toolAnnotations(effect: ToolEffect | null): ToolAnnotations {
+  return kindAnnotations(effect ?? "reads");
+}
+
+/** One described route that opted in, before it is a tool. */
+interface Declared {
+  readonly capability: string;
+  readonly method: string;
+  readonly path: string;
+  readonly spec: RouteSpec;
+  readonly handlers: readonly unknown[];
+}
+
+/** Every described route in these groups, with the method it is mounted under. */
+function described(groups: readonly RouteGroup[]): Declared[] {
+  return groups.flatMap((group) =>
+    operationsOf(group.routes)
+      .filter((operation) => !isMiddlewareOnly(operation))
+      .flatMap((operation) => {
+        const spec = operation.handlers.map(routeSpecOf).find((candidate) => candidate !== undefined);
+        return spec === undefined
+          ? []
+          : [
+              {
+                capability: group.tag,
+                method: operation.method.toUpperCase(),
+                path: operation.path,
+                spec,
+                handlers: operation.handlers,
+              },
+            ];
+      }),
+  );
+}
+
+function refuse(message: string, detail: string): never {
+  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.
+ */
+export function assertToolDeclarations(groups: readonly RouteGroup[]): void {
+  const operations = new Map<string, string>();
+  const names = new Map<string, string>();
+  for (const route of described(groups)) {
+    const where = `${route.method} ${route.path}`;
+    const { operation, tool } = route.spec;
+    if (operation !== undefined) {
+      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 !== undefined) {
+        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 === undefined) continue;
+    if (operation === undefined) {
+      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 !== undefined) {
+      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: RouteSpec, effect: ToolEffect | null): string {
+  return [spec.summary, spec.description, effect === null ? undefined : EFFECT_SENTENCES[effect]]
+    .filter((part): part is string => part !== undefined && part.length > 0)
+    .join(" ");
+}
+
+/** Every tool these groups declare, in registration order. Refuses a wrong declaration first. */
+export function appTools(groups: readonly RouteGroup[]): AppTool[] {
+  assertToolDeclarations(groups);
+  return described(groups).flatMap((route): AppTool[] => {
+    const { spec } = route;
+    if (spec.tool === undefined || spec.operation === undefined) 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 ?? [],
+      },
+    ];
+  });
+}
+
+/** 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 function mayCall(tool: AppTool, caller: ToolCaller): boolean {
+  if (tool.power !== undefined && (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).
+ */
+export function offeredTools(tools: readonly AppTool[], caller: ToolCaller): AppTool[] {
+  return tools.filter((tool) => mayCall(tool, caller));
+}

package/src/openapi/document.ts

@@ -9,6 +9,7 @@ import { pathParams } from "../http/routeContract";
 import { type DocumentedMethod, type RouteResponse, type RouteSpec, routeSpecOf } from "../http/routeSpec";
 import { type RequestContract, requestContractOf } from "../http/validation";
 import type { VerificationStrategy } from "../http/verification";
+import { isMiddlewareOnly, type Operation, operationsOf } from "./operations";
 
 /**
  * **The OpenAPI contract, read off a composed app.**
@@ -76,7 +77,8 @@ const SECURITY_SCHEMES: Record<string, unknown> = {
   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",
@@ -134,33 +136,6 @@ export function jsonSchema(schema: z.ZodType, io: "input" | "output"): JsonSchem
   return rest;
 }
 
-/** One route's handlers, grouped by method and path the way Hono stores them: one entry per handler. */
-interface Operation {
-  readonly method: string;
-  readonly path: string;
-  readonly handlers: unknown[];
-}
-
-function operationsOf(routes: readonly RouterRoute[]): Operation[] {
-  const byKey = new Map<string, Operation>();
-  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: Operation): boolean {
-  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. */
 export function undescribedRoutes(groups: readonly RouteGroup[]): UndescribedRoute[] {
   return groups.flatMap((group) =>
@@ -274,6 +249,11 @@ function operationOf(tag: string, method: string, operation: Operation, spec: Ro
     responses,
     ...(strategies.length === 0 ? {} : { security, "x-pithy-verification": strategies }),
     ...(spec.scopes === undefined || spec.scopes.length === 0 ? {} : { "x-pithy-scopes": spec.scopes }),
+    // What the route declared for the app's MCP endpoint: the power its gate installs, its permanent name,
+    // and its effect when it is a tool. A client generated from the contract reads the gate it will meet.
+    ...(spec.power === undefined ? {} : { "x-pithy-power": spec.power }),
+    ...(spec.operation === undefined ? {} : { "x-pithy-operation": spec.operation }),
+    ...(spec.tool === undefined ? {} : { "x-pithy-tool": spec.tool === true ? { effect: null } : spec.tool }),
   };
 }
 

package/src/openapi/operations.ts

@@ -0,0 +1,62 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { type RouteSpec, routeSpecOf } 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 function operationsOf(routes: readonly RouterRoute[]): Operation[] {
+  const byKey = new Map<string, Operation>();
+  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.
+ */
+export function isMiddlewareOnly(operation: Operation): boolean {
+  return operation.method === "ALL" && !operation.handlers.some((handler) => routeSpecOf(handler));
+}
+
+/** 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 function describedOperations(groups: readonly RouteGroup[]): DescribedOperation[] {
+  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 !== undefined),
+      })),
+  );
+}

package/src/presence/channel.ts

@@ -0,0 +1,46 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { SocketChannel } from "../http/socket";
+import { type PresenceDeclaration, presenceSocketPath } from "./declaration";
+import {
+  PRESENCE_ROOM_VERSIONS,
+  PresenceActivityFrame,
+  PresenceJoinedFrame,
+  PresenceLeftFrame,
+  PresenceRoomErrorFrame,
+  PresenceRoomInitFrame,
+  PresenceRoomPing,
+  PresenceRoomPong,
+  PresenceSetActivityFrame,
+} from "./frames";
+import { PresenceRoomParams } from "./http/schemas";
+
+/**
+ * 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 function presenceRoomsSocket(capability: string, presence: PresenceDeclaration): SocketChannel {
+  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 },
+    ],
+  };
+}