@pithy-sh/core 0.13.0 → 0.15.0

package/src/error/payload.ts

@@ -213,6 +213,20 @@ const AuthAccountDeletedPublic = z
   })
   .describe("The account is deleted and awaiting its purge (403).");
 
+const AuthHandoffInvalidPublic = z
+  .object({
+    code: z
+      .literal("auth/handoff_invalid")
+      .describe(
+        "The one-time code a native app trades for its session after a redirect sign-in is spent, expired, was never issued, or came with the wrong verifier. One code for all four, so the answer says nothing about which codes exist or why a trade failed. The remedy is the same for each: sign in again.",
+      ),
+    status: z
+      .literal(400)
+      .describe("Bad Request — the code presented cannot be traded. Not 401: no credential was presented to refuse."),
+    ...publicFields,
+  })
+  .describe("A sign-in handoff code that is spent, expired, unknown or presented with the wrong verifier (400).");
+
 const NotFoundPublic = z
   .object({
     code: z.literal("core/not_found").describe("The requested resource does not exist."),
@@ -339,6 +353,30 @@ const WebhookUnverifiedPublic = z
   })
   .describe("An inbound webhook failed its signature check (401).");
 
+// --- @pithy-sh/core: presence rooms ---
+
+const PresenceTicketInvalidPublic = z
+  .object({
+    code: z
+      .literal("core/presence_ticket_invalid")
+      .describe(
+        "A presence socket was opened without a ticket this Worker accepts. Deliberately one code for every failing step — no ticket, a bad signature, an expired one, one already spent, or one minted for another room — so a caller holding a stolen ticket learns nothing about which check it tripped. `detail` names the step for the log, and the codec strips it.",
+      ),
+    status: z.literal(401).describe("Unauthorized — mint a fresh ticket and open the socket with it."),
+    ...publicFields,
+  })
+  .describe("A presence socket upgrade carried no valid ticket (401).");
+
+const PresenceRoomFullPublic = z
+  .object({
+    code: z
+      .literal("core/presence_room_full")
+      .describe("A presence room already holds as many participants as its room kind allows."),
+    status: z.literal(409).describe("Conflict — the room is at its participant cap. Try again when someone leaves."),
+    ...publicFields,
+  })
+  .describe("A presence room is at its participant cap (409).");
+
 // --- @pithy-sh/cloudflare: out-of-Worker CF REST client codes ---
 
 const CloudflareNotConfiguredPublic = z
@@ -855,6 +893,42 @@ const LedgerInvalidAmountPublic = z
   })
   .describe("An amount is not a positive integer (400).");
 
+const LedgerEntryNotFoundPublic = z
+  .object({
+    code: z
+      .literal("ledger/entry_not_found")
+      .describe(
+        "No ledger entry with that reference exists on the account named. An entry on another account is answered the same way, so a reversal can never reach past the account its path names.",
+      ),
+    status: z.literal(404).describe("Not Found."),
+    ...publicFields,
+  })
+  .describe("A referenced ledger entry does not exist on that account (404).");
+
+const LedgerEntryNotReversiblePublic = z
+  .object({
+    code: z
+      .literal("ledger/entry_not_reversible")
+      .describe(
+        "Only a credit or a debit reverses, and never one that is itself a reversal. A hold has release; a capture spends escrow and a transfer touches a second account, so both are refused. `params.kind` names the entry's kind, and `params.reverses` the entry a reversal reversed. Nothing was written.",
+      ),
+    status: z.literal(409).describe("Conflict — the entry's kind does not reverse."),
+    ...publicFields,
+  })
+  .describe("A ledger entry of a kind that does not reverse (409).");
+
+const LedgerRefConflictPublic = z
+  .object({
+    code: z
+      .literal("ledger/ref_conflict")
+      .describe(
+        "The ref a control-plane write would be written under is already held by a different entry, so the write cannot be recorded and is not a replay either: a credit's or a debit's key already used for another account, the other act, another amount or a hold, or the derived ref of a reversal or a hold's resolution held by an unrelated entry. Nothing moved; the entry stays unreversed, or the hold stays open.",
+      ),
+    status: z.literal(409).describe("Conflict — the ref belongs to another entry."),
+    ...publicFields,
+  })
+  .describe("A write whose ref another entry already holds (409).");
+
 // --- @pithy-sh/rating: skill-rating + experience tracker codes ---
 
 const RatingUnknownAlgorithmPublic = z
@@ -921,6 +995,96 @@ const RatingRecordForbiddenPublic = z
   })
   .describe("The caller lacks the scope to record a rated outcome (403).");
 
+// --- @pithy-sh/consent: purposes, grants and withdrawals ---
+
+const ConsentUnknownPurposePublic = z
+  .object({
+    code: z
+      .literal("consent/unknown_purpose")
+      .describe("No consent purpose with that id is declared by a composed capability or in `consent({ purposes })`."),
+    status: z.literal(404).describe("Not Found."),
+    ...publicFields,
+  })
+  .describe("A consent purpose that is not declared (404).");
+
+const ConsentStaleNoticePublic = z
+  .object({
+    code: z
+      .literal("consent/stale_notice")
+      .describe(
+        "The grant names a notice version that is not the purpose's current one. A person agrees to the notice in force, so the screen showing an older one has to be reloaded.",
+      ),
+    status: z.literal(409).describe("Conflict — the notice has moved on."),
+    ...publicFields,
+  })
+  .describe("A grant against a notice version that is not current (409).");
+
+const ConsentMethodBelowMinimumPublic = z
+  .object({
+    code: z
+      .literal("consent/method_below_minimum")
+      .describe(
+        "The grant was given by a method below the purpose's minimum — a click where the purpose needs a typed name, a drawn signature or a provider's envelope.",
+      ),
+    status: z.literal(400).describe("Bad Request — the method is below the purpose's minimum."),
+    ...publicFields,
+  })
+  .describe("A grant below the purpose's minimum method (400).");
+
+const ConsentWithdrawalBelowGrantPublic = z
+  .object({
+    code: z
+      .literal("consent/withdrawal_below_grant")
+      .describe(
+        "The purpose requires a withdrawal at least at the grade of the grant it withdraws, as a HIPAA revocation must be in writing, and this one is below it.",
+      ),
+    status: z.literal(400).describe("Bad Request — the withdrawal is below the grant's method."),
+    ...publicFields,
+  })
+  .describe("A withdrawal below the grade its purpose requires (400).");
+
+const ConsentEvidenceMissingPublic = z
+  .object({
+    code: z
+      .literal("consent/evidence_missing")
+      .describe(
+        "The method names evidence the request did not carry: a typed name for `typed`, a drawn image for `drawn`, a provider and envelope for `provider`, or the document a signed grant is given against.",
+      ),
+    status: z.literal(400).describe("Bad Request — the evidence for the method is missing."),
+    ...publicFields,
+  })
+  .describe("A grant or withdrawal missing the evidence its method needs (400).");
+
+const ConsentExpiryPassedPublic = z
+  .object({
+    code: z
+      .literal("consent/expiry_passed")
+      .describe("The grant's expiry is not in the future, so it would answer no from the moment it was recorded."),
+    status: z.literal(400).describe("Bad Request — the expiry has already passed."),
+    ...publicFields,
+  })
+  .describe("A grant whose expiry has already passed (400).");
+
+const ConsentDocumentNotFoundPublic = z
+  .object({
+    code: z.literal("consent/document_not_found").describe("No signed document with that content hash is kept."),
+    status: z.literal(404).describe("Not Found."),
+    ...publicFields,
+  })
+  .describe("A signed document that is not kept (404).");
+
+const ConsentEvidenceStoreMissingPublic = z
+  .object({
+    code: z
+      .literal("consent/evidence_store_missing")
+      .describe(
+        "A drawn signature or a provider's certificate is stored in R2, and the Worker has no `CONSENT_EVIDENCE` bucket bound. A binding we never got, so the answer is in this Worker's wiring.",
+      ),
+    status: z.literal(500).describe("Internal Server Error — the evidence bucket is not bound."),
+    ...publicFields,
+  })
+  .describe("The evidence bucket is not bound (500).");
+
 // --- @pithy-sh/matchmaking: pairing + presence capability codes ---
 
 const MatchmakingRoomNotFoundPublic = z
@@ -1840,6 +2004,7 @@ export const KitPublicErrorPayload = z
     AuthSessionNotFreshPublic,
     AuthAccountSuspendedPublic,
     AuthAccountDeletedPublic,
+    AuthHandoffInvalidPublic,
     NotFoundPublic,
     ConflictPublic,
     RateLimitPublic,
@@ -1851,6 +2016,8 @@ export const KitPublicErrorPayload = z
     UnknownWorkflowPublic,
     WorkflowFailedPublic,
     WebhookUnverifiedPublic,
+    PresenceTicketInvalidPublic,
+    PresenceRoomFullPublic,
     CloudflareNotConfiguredPublic,
     CloudflareRequestFailedPublic,
     CloudflareInvalidResponsePublic,
@@ -1898,12 +2065,23 @@ export const KitPublicErrorPayload = z
     LedgerInsufficientFundsPublic,
     LedgerHoldNotOpenPublic,
     LedgerInvalidAmountPublic,
+    LedgerEntryNotFoundPublic,
+    LedgerEntryNotReversiblePublic,
+    LedgerRefConflictPublic,
     RatingUnknownAlgorithmPublic,
     RatingUnsupportedPlayerCountPublic,
     RatingInvalidParamsPublic,
     RatingGameNotFoundPublic,
     RatingPoolNotFoundPublic,
     RatingRecordForbiddenPublic,
+    ConsentUnknownPurposePublic,
+    ConsentStaleNoticePublic,
+    ConsentMethodBelowMinimumPublic,
+    ConsentWithdrawalBelowGrantPublic,
+    ConsentEvidenceMissingPublic,
+    ConsentExpiryPassedPublic,
+    ConsentDocumentNotFoundPublic,
+    ConsentEvidenceStoreMissingPublic,
     MatchmakingRoomNotFoundPublic,
     MatchmakingRoomFullPublic,
     MatchmakingInvalidCodePublic,
@@ -2006,6 +2184,9 @@ const AuthAccountSuspended = AuthAccountSuspendedPublic.extend(internalFields).d
 const AuthAccountDeleted = AuthAccountDeletedPublic.extend(internalFields).describe(
   AuthAccountDeletedPublic.description ?? "",
 );
+const AuthHandoffInvalid = AuthHandoffInvalidPublic.extend(internalFields).describe(
+  AuthHandoffInvalidPublic.description ?? "",
+);
 const NotFound = NotFoundPublic.extend(internalFields).describe(NotFoundPublic.description ?? "");
 const Conflict = ConflictPublic.extend(internalFields).describe(ConflictPublic.description ?? "");
 const RateLimit = RateLimitPublic.extend(internalFields).describe(RateLimitPublic.description ?? "");
@@ -2023,6 +2204,12 @@ const WorkflowFailed = WorkflowFailedPublic.extend(internalFields).describe(Work
 const WebhookUnverified = WebhookUnverifiedPublic.extend(internalFields).describe(
   WebhookUnverifiedPublic.description ?? "",
 );
+const PresenceTicketInvalid = PresenceTicketInvalidPublic.extend(internalFields).describe(
+  PresenceTicketInvalidPublic.description ?? "",
+);
+const PresenceRoomFull = PresenceRoomFullPublic.extend(internalFields).describe(
+  PresenceRoomFullPublic.description ?? "",
+);
 const CloudflareNotConfigured = CloudflareNotConfiguredPublic.extend(internalFields).describe(
   CloudflareNotConfiguredPublic.description ?? "",
 );
@@ -2150,6 +2337,15 @@ const LedgerHoldNotOpen = LedgerHoldNotOpenPublic.extend(internalFields).describ
 const LedgerInvalidAmount = LedgerInvalidAmountPublic.extend(internalFields).describe(
   LedgerInvalidAmountPublic.description ?? "",
 );
+const LedgerEntryNotFound = LedgerEntryNotFoundPublic.extend(internalFields).describe(
+  LedgerEntryNotFoundPublic.description ?? "",
+);
+const LedgerEntryNotReversible = LedgerEntryNotReversiblePublic.extend(internalFields).describe(
+  LedgerEntryNotReversiblePublic.description ?? "",
+);
+const LedgerRefConflict = LedgerRefConflictPublic.extend(internalFields).describe(
+  LedgerRefConflictPublic.description ?? "",
+);
 const RatingUnknownAlgorithm = RatingUnknownAlgorithmPublic.extend(internalFields).describe(
   RatingUnknownAlgorithmPublic.description ?? "",
 );
@@ -2168,6 +2364,30 @@ const RatingPoolNotFound = RatingPoolNotFoundPublic.extend(internalFields).descr
 const RatingRecordForbidden = RatingRecordForbiddenPublic.extend(internalFields).describe(
   RatingRecordForbiddenPublic.description ?? "",
 );
+const ConsentUnknownPurpose = ConsentUnknownPurposePublic.extend(internalFields).describe(
+  ConsentUnknownPurposePublic.description ?? "",
+);
+const ConsentStaleNotice = ConsentStaleNoticePublic.extend(internalFields).describe(
+  ConsentStaleNoticePublic.description ?? "",
+);
+const ConsentMethodBelowMinimum = ConsentMethodBelowMinimumPublic.extend(internalFields).describe(
+  ConsentMethodBelowMinimumPublic.description ?? "",
+);
+const ConsentWithdrawalBelowGrant = ConsentWithdrawalBelowGrantPublic.extend(internalFields).describe(
+  ConsentWithdrawalBelowGrantPublic.description ?? "",
+);
+const ConsentEvidenceMissing = ConsentEvidenceMissingPublic.extend(internalFields).describe(
+  ConsentEvidenceMissingPublic.description ?? "",
+);
+const ConsentExpiryPassed = ConsentExpiryPassedPublic.extend(internalFields).describe(
+  ConsentExpiryPassedPublic.description ?? "",
+);
+const ConsentDocumentNotFound = ConsentDocumentNotFoundPublic.extend(internalFields).describe(
+  ConsentDocumentNotFoundPublic.description ?? "",
+);
+const ConsentEvidenceStoreMissing = ConsentEvidenceStoreMissingPublic.extend(internalFields).describe(
+  ConsentEvidenceStoreMissingPublic.description ?? "",
+);
 const MatchmakingRoomNotFound = MatchmakingRoomNotFoundPublic.extend(internalFields).describe(
   MatchmakingRoomNotFoundPublic.description ?? "",
 );
@@ -2417,6 +2637,7 @@ export const KitErrorPayload = z
     AuthSessionNotFresh,
     AuthAccountSuspended,
     AuthAccountDeleted,
+    AuthHandoffInvalid,
     NotFound,
     Conflict,
     RateLimit,
@@ -2428,6 +2649,8 @@ export const KitErrorPayload = z
     UnknownWorkflow,
     WorkflowFailed,
     WebhookUnverified,
+    PresenceTicketInvalid,
+    PresenceRoomFull,
     CloudflareNotConfigured,
     CloudflareRequestFailed,
     CloudflareInvalidResponse,
@@ -2475,12 +2698,23 @@ export const KitErrorPayload = z
     LedgerInsufficientFunds,
     LedgerHoldNotOpen,
     LedgerInvalidAmount,
+    LedgerEntryNotFound,
+    LedgerEntryNotReversible,
+    LedgerRefConflict,
     RatingUnknownAlgorithm,
     RatingUnsupportedPlayerCount,
     RatingInvalidParams,
     RatingGameNotFound,
     RatingPoolNotFound,
     RatingRecordForbidden,
+    ConsentUnknownPurpose,
+    ConsentStaleNotice,
+    ConsentMethodBelowMinimum,
+    ConsentWithdrawalBelowGrant,
+    ConsentEvidenceMissing,
+    ConsentExpiryPassed,
+    ConsentDocumentNotFound,
+    ConsentEvidenceStoreMissing,
     MatchmakingRoomNotFound,
     MatchmakingRoomFull,
     MatchmakingInvalidCode,

package/src/error/pithyError.ts

@@ -192,6 +192,48 @@ export class WebhookUnverifiedError extends PithyError {
   }
 }
 
+/**
+ * One code for every way a presence socket's ticket fails — missing, forged, expired, spent, or minted for
+ * another room. The step goes in `detail`, which the codec strips: a caller holding somebody else's ticket
+ * learns only that it no longer works.
+ */
+export class PresenceTicketInvalidError extends PithyError {
+  declare readonly payload: Extract<ErrorPayload, { code: "core/presence_ticket_invalid" }>;
+
+  constructor(args: ErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "core/presence_ticket_invalid",
+        status: 401,
+        message: args.message ?? "That presence ticket is not valid.",
+        action: args.action ?? "Mint a fresh ticket and open the socket within 60 seconds.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+/** A presence room is at the participant cap its room kind declares. */
+export class PresenceRoomFullError extends PithyError {
+  declare readonly payload: Extract<ErrorPayload, { code: "core/presence_room_full" }>;
+
+  constructor(args: ErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "core/presence_room_full",
+        status: 409,
+        message: args.message ?? "That room is full.",
+        action: args.action,
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
 export class ForbiddenError extends PithyError {
   declare readonly payload: Extract<ErrorPayload, { code: "auth/forbidden" }>;
 

package/src/http/routeSpec.ts

@@ -3,6 +3,8 @@
 
 import type { MiddlewareHandler } from "hono";
 import type { z } from "zod";
+import type { PithyHonoEnv } from "../capability/capability";
+import { ForbiddenError, UnauthorizedError } from "../error/pithyError";
 import type { VerificationStrategy } from "./verification";
 
 /**
@@ -43,6 +45,24 @@ export interface RouteResponse {
 /** The HTTP methods an `app.all` route is documented under. OpenAPI has no "any method". */
 export type DocumentedMethod = "get" | "post" | "put" | "patch" | "delete" | "head" | "options";
 
+/**
+ * What a tool does beyond reading, which every non-`GET` tool must say (`docs/AGENT-ACCESS.md` §4).
+ *
+ * **A route is a tool only when it says so, and a non-`GET` says so louder.** One that sends mail, charges a card or
+ * deletes something is a tool an agent can call in a loop, so the effect is not inferred from the method: it is
+ * declared, it sets the tool's MCP annotations, it is written into the tool's description, and it is counted on the
+ * consent screen beside its capability.
+ */
+export const TOOL_EFFECTS = ["writes", "sends", "charges", "deletes"] as const;
+export type ToolEffect = (typeof TOOL_EFFECTS)[number];
+
+/**
+ * A route's opt-in to the app's MCP endpoint. `true` is a read, and only a `GET` may say it; anything else declares
+ * its {@link ToolEffect}. `createBackend` refuses a composition where either half is wrong — `describeRoute` cannot
+ * see the method it is mounted under, so the composition is the first place the pair can be checked.
+ */
+export type RouteTool = true | { readonly effect: ToolEffect };
+
 /** What a route is for, how its caller is verified, and what it returns. */
 export interface RouteSpec {
   /** One sentence, in the brand voice. The operation's title in the contract. */
@@ -64,14 +84,64 @@ export interface RouteSpec {
   readonly responses: Readonly<Record<number, z.ZodType | RouteResponse>>;
   /** For an `app.all` route only: the methods it is documented under. */
   readonly methods?: readonly DocumentedMethod[];
+  /**
+   * The power a caller's role must hold to reach this route at all. **Declaring it installs the gate**: the
+   * same middleware that carries this spec refuses a caller whose acting organization's role does not hold it, so
+   * what the MCP endpoint filters `tools/list` on and what the route enforces are one value and cannot drift.
+   *
+   * A route whose access depends on the record — its owner may, a manager may — declares the power that lets a
+   * member reach it at all, and keeps its in-handler check. Absent, the route is gated by its other guards alone,
+   * and a tool for it is offered to every signed-in user the endpoint admits.
+   */
+  readonly power?: string;
+  /**
+   * The route's permanent name within its capability, e.g. `threads.reply`. Its MCP tool is
+   * `<capability>_<operation>`, through the one normalizer the control-plane server's tools use. Unique within a
+   * capability, and never renamed once published: an agent references a tool by name.
+   */
+  readonly operation?: string;
+  /**
+   * The route's opt-in to the app's MCP endpoint. Absent, the route is not a tool. See {@link RouteTool}.
+   */
+  readonly tool?: RouteTool;
 }
 
-/** Declare what a route is for, how its caller is verified, and what it returns. See {@link RouteSpec}. */
+/**
+ * Declare what a route is for, how its caller is verified, and what it returns. See {@link RouteSpec}.
+ *
+ * With a {@link RouteSpec.power} it is also the route's power gate, read off the acting-organization seam the way
+ * every capability outside tenancy asks it. It sits first on the route line, so it answers an anonymous caller
+ * itself rather than assuming a guard below it will: a 401, because signing in might help, where a role that does
+ * not hold the power is a 403.
+ */
 export function describeRoute(spec: RouteSpec): MiddlewareHandler {
-  const middleware: MiddlewareHandler = async (_c, next) => {
-    await next();
-  };
-  return Object.assign(middleware, { [ROUTE_SPEC]: spec });
+  const { power } = spec;
+  const middleware: MiddlewareHandler<PithyHonoEnv> =
+    power === undefined
+      ? async (_c, next) => {
+          await next();
+        }
+      : async (c, next) => {
+          if (!c.var.auth) {
+            throw new UnauthorizedError({
+              message: "Authentication required.",
+              action: "Sign in and retry with a valid session or bearer token.",
+              detail: `describeRoute(power: ${power}) ran with no signed-in caller`,
+            });
+          }
+          const acting = await c.var.actingOrganization();
+          if (acting === null || !acting.roleAllows(power)) {
+            throw new ForbiddenError({
+              message: `Your role does not allow \`${power}\`.`,
+              detail:
+                acting === null
+                  ? `no organization is in force for user ${c.var.auth.userId}, so ${power} is not held`
+                  : `the role in organization ${acting.organizationId} does not hold ${power}`,
+            });
+          }
+          await next();
+        };
+  return Object.assign(middleware as MiddlewareHandler, { [ROUTE_SPEC]: spec });
 }
 
 /** The spec a {@link describeRoute} middleware carries, or `undefined` for any other handler. */

package/src/http/verification.ts

@@ -11,7 +11,9 @@ import { z } from "zod";
  */
 export const VerificationStrategy = z
   .union([
-    z.literal("bearer").describe("Short-lived access token via Authorization: Bearer; validated by @pithy-sh/auth."),
+    z
+      .literal("bearer")
+      .describe("A session token via Authorization: Bearer, rotated before it expires; validated by @pithy-sh/auth."),
     z.literal("session").describe("Cookie-based web session, CSRF-protected; validated by @pithy-sh/auth."),
     z
       .literal("signed-webhook")

package/src/i18n/translator.ts

@@ -90,7 +90,8 @@ export interface TranslatorInput {
   readonly formattingLocale?: string;
   /**
    * The catalogs to walk, most-specific first. `@pithy-sh/i18n` passes adopter-locale, adopter-default,
-   * kit-locale, kit-default; a copied screen passes its own baked English and nothing else.
+   * kit-locale, composed-locale, composed-default, composed English; a copied screen passes its own baked
+   * English and nothing else.
    */
   readonly layers: readonly (MessageCatalog | undefined)[];
 }

package/src/index.ts

@@ -99,6 +99,8 @@ export {
   ANY_VERIFIED_CALLER,
   type ControlPlaneRequirement,
   ControlPlaneScope,
+  ERASURE_READ_SCOPE,
+  EVIDENCE_READ_SCOPE,
   KEYS_ROTATE_SCOPE,
   MANIFEST_READ_SCOPE,
   MIGRATIONS_READ_SCOPE,

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",
+  };
+}