@escalay/kit 0.0.0-stage → 1.7.0

package/src/a2a/index.ts

@@ -0,0 +1,262 @@
+/**
+ * A2A (Agent2Agent, spec 1.0) over the app's MCP tools: the Agent Card at `/.well-known/agent-card.json` and a JSON-RPC
+ * endpoint (`SendMessage`, `GetTask`, `ListTasks`, `CancelTask`). Each skill is one tool: a message's text fills the
+ * tool's main argument (a `data` part may give all of them), the tool runs its route in-process with the caller's own
+ * credentials, and the answer comes back as a Task whose artifact holds the tool's summary (text) and the route's JSON
+ * (data). A slow route (202 + run) leaves the task working; `GetTask` asks again. Tasks live in the store for a day and
+ * only their caller sees them. No streaming, push notifications or extended card: the card says so.
+ *
+ * @example
+ * mountA2A(app, {
+ *   info: { name: 'Cookbook', description: 'Recipes and menus…', version: '1.0.0' },
+ *   skills: [{ tool: exploreIdea, text: 'idea', tags: ['research'], examples: ['split a bill with friends'] }],
+ *   callApi: inProcess(app), store: state.oauth, oauth: true,
+ * })
+ */
+import { randomUUID } from 'node:crypto'
+import type { AuthInfo } from '@modelcontextprotocol/server'
+import type { Context, Hono } from 'hono'
+import { sendPublic, WELL_KNOWN } from '../core/discovery.js'
+import { originOf } from '../core/hal.js'
+import { callWaiting, FORWARDED, problemText, type CallApi, type McpTool } from '../mcp/index.js'
+import { memoryStore, type KeyValueStore } from '../core/kv.js'
+
+export const A2A_VERSION = '1.0'
+
+/** One A2A skill: an MCP tool, the argument a plain-text message fills, and how registries should file it. */
+export type A2ASkill = {
+  tool: McpTool
+  /** The tool's argument that a message's text fills, e.g. `idea` or `purpose`. */
+  text: string
+  tags: string[]
+  examples?: string[]
+}
+
+/** Any key-value store with expiry (`kv.ts`); the OAuth store fits (tasks are kept under the kind `a2a-task`). */
+export type A2ATaskStore = KeyValueStore
+
+export type A2AConfig = {
+  path?: string
+  info: { name: string; description: string; version: string; organization?: string }
+  /** The first is used when a message names none (`metadata.skill`). */
+  skills: A2ASkill[]
+  callApi: CallApi
+  store?: A2ATaskStore
+  /** Advertise the app's OAuth server (`oauth.ts`) beside API keys. */
+  oauth?: boolean
+  /** How long `SendMessage` waits for a slow route before answering with a working task. */
+  waitMs?: number
+}
+
+type Part = { text?: string; data?: unknown; url?: string; raw?: string; mediaType?: string; filename?: string; metadata?: Record<string, unknown> }
+type Message = { messageId: string; role: string; parts: Part[]; contextId?: string; taskId?: string; metadata?: Record<string, unknown> }
+type TaskState = 'TASK_STATE_WORKING' | 'TASK_STATE_COMPLETED' | 'TASK_STATE_FAILED' | 'TASK_STATE_CANCELED' | 'TASK_STATE_AUTH_REQUIRED'
+type Task = { id: string; contextId: string; status: { state: TaskState; message?: Message; timestamp: string }; artifacts?: unknown[]; history?: Message[]; metadata: Record<string, unknown> }
+type Stored = { owner: string; task: Task; skill: string; args: Record<string, unknown>; created: number }
+
+const TERMINAL = new Set<TaskState>(['TASK_STATE_COMPLETED', 'TASK_STATE_FAILED', 'TASK_STATE_CANCELED'])
+const DAY = 86_400_000
+const KIND = 'a2a-task'
+const INDEX = 'a2a-tasks'
+
+/** JSON-RPC and A2A error codes (spec §5.4, §9.5). */
+const ERRORS = {
+  parse: [-32700, 'Invalid JSON payload'],
+  request: [-32600, 'Request payload validation error'],
+  method: [-32601, 'Method not found'],
+  params: [-32602, 'Invalid parameters'],
+  taskNotFound: [-32001, 'Task not found', 'TASK_NOT_FOUND'],
+  notCancelable: [-32002, 'Task cannot be canceled', 'TASK_NOT_CANCELABLE'],
+  noPush: [-32003, 'Push notifications are not supported', 'PUSH_NOTIFICATION_NOT_SUPPORTED'],
+  unsupported: [-32004, 'This operation is not supported', 'UNSUPPORTED_OPERATION'],
+  version: [-32009, 'This A2A version is not supported', 'VERSION_NOT_SUPPORTED'],
+} as const
+
+class RpcError extends Error {
+  constructor(readonly error: (typeof ERRORS)[keyof typeof ERRORS], readonly detail: string) {
+    super(detail)
+  }
+}
+
+const rpcError = (id: unknown, [code, message, reason]: readonly [number, string, string?], detail: string) => ({
+  jsonrpc: '2.0',
+  id: id ?? null,
+  error: { code, message, data: [{ '@type': 'type.googleapis.com/google.rpc.ErrorInfo', reason: reason ?? message.toUpperCase().replace(/\W+/g, '_'), domain: 'a2a-protocol.org', metadata: { detail } }] },
+})
+
+const agentMessage = (text: string, task: Pick<Task, 'id' | 'contextId'>): Message => ({ messageId: randomUUID(), role: 'ROLE_AGENT', parts: [{ text }], taskId: task.id, contextId: task.contextId })
+
+/** The Agent Card (spec §4.4.1) for this origin. */
+export const agentCard = (origin: string, { path = '/a2a', info, skills, oauth }: A2AConfig) => ({
+  name: info.name,
+  description: info.description,
+  supportedInterfaces: [{ url: origin + path, protocolBinding: 'JSONRPC', protocolVersion: A2A_VERSION }],
+  provider: { organization: info.organization ?? info.name, url: origin },
+  version: info.version,
+  documentationUrl: origin + WELL_KNOWN.guide,
+  capabilities: { streaming: false, pushNotifications: false, extendedAgentCard: false },
+  securitySchemes: {
+    ...(oauth
+      ? {
+          oauth: {
+            oauth2SecurityScheme: {
+              description: 'The owner approves each agent: register at /oauth/register (or follow /auth.md), then the authorization code flow with PKCE.',
+              flows: { authorizationCode: { authorizationUrl: `${origin}/oauth/authorize`, tokenUrl: `${origin}/oauth/token`, refreshUrl: `${origin}/oauth/token`, scopes: { read: 'Look things up.', write: 'Change saved state.' }, pkceRequired: true } },
+              oauth2MetadataUrl: `${origin}/.well-known/oauth-authorization-server`,
+            },
+          },
+        }
+      : {}),
+    apiKey: { httpAuthSecurityScheme: { description: 'An API key from the owner, as a bearer token.', scheme: 'Bearer' } },
+  },
+  securityRequirements: [...(oauth ? [{ schemes: { oauth: { list: ['read'] } } }] : []), { schemes: { apiKey: { list: [] } } }],
+  defaultInputModes: ['text/plain', 'application/json'],
+  defaultOutputModes: ['text/plain', 'application/json'],
+  skills: skills.map(({ tool, tags, examples }) => ({ id: tool.name, name: tool.title, description: tool.description, tags, ...(examples ? { examples } : {}) })),
+})
+
+/** Serves the Agent Card and the JSON-RPC endpoint. Mount after `createAgentApi`, whose `authenticate` guards `path`. */
+export const mountA2A = (app: Hono<any, any, any>, config: A2AConfig) => {
+  const { path = '/a2a', skills, callApi, store = memoryStore(), waitMs = 60_000 } = config
+  // Each Worker isolate has its own memory: a task made in one is missing in the next
+  if (!config.store && globalThis.navigator?.userAgent === 'Cloudflare-Workers') console.warn('mountA2A: tasks are kept in memory; on Workers pass a store in the database (dbOAuthStore(db) fits)')
+  const byId = new Map(skills.map((skill) => [skill.tool.name, skill]))
+
+  app.get(WELL_KNOWN.agentCard, (c: Context) => sendPublic(c, JSON.stringify(agentCard(originOf(c), config), null, 2), 'application/json'))
+
+  const ownerOf = (c: Context) => {
+    const caller = c.get('caller' as never) as { kind: string; name?: string; email?: string } | undefined
+    return `${caller?.kind ?? 'anonymous'}:${caller?.name ?? caller?.email ?? ''}`
+  }
+  const authOf = (c: Context): AuthInfo => ({
+    token: '',
+    clientId: ownerOf(c),
+    scopes: [],
+    extra: {
+      headers: {
+        ...Object.fromEntries(FORWARDED.flatMap((name) => (c.req.header(name) ? [[name, c.req.header(name)!]] : []))),
+        'x-forwarded-proto': new URL(originOf(c)).protocol.replace(':', ''),
+        'x-forwarded-host': new URL(originOf(c)).host,
+      },
+    },
+  })
+
+  const save = async (owner: string, stored: Stored) => {
+    // The store takes epoch seconds
+    await store.put(KIND, stored.task.id, stored as never, Math.floor((stored.created + DAY) / 1000))
+    const index = ((await store.get(INDEX, owner))?.ids as string[] | undefined) ?? []
+    if (!index.includes(stored.task.id)) await store.put(INDEX, owner, { ids: [stored.task.id, ...index].slice(0, 500) }, Math.floor((Date.now() + DAY) / 1000))
+  }
+  const load = async (owner: string, id: unknown) => {
+    const stored = typeof id === 'string' ? ((await store.get(KIND, id)) as Stored | null) : null
+    if (!stored || stored.owner !== owner) throw new RpcError(ERRORS.taskNotFound, `No task ${String(id)} for this caller (tasks are kept for a day).`)
+    return stored
+  }
+  const shown = (stored: Stored, historyLength?: number) => {
+    const { history = [], ...task } = stored.task
+    return historyLength === 0 ? task : { ...task, history: historyLength ? history.slice(-historyLength) : history }
+  }
+
+  /** Runs (or asks again for) the task's tool call and records the outcome on the task. */
+  const run = async (c: Context, stored: Stored, wait: number) => {
+    const skill = byId.get(stored.skill)!
+    const { response, pending } = await callWaiting(callApi, skill.tool.call(stored.args as never), authOf(c), wait)
+    const json = await response.json().catch(() => null)
+    const at = new Date().toISOString()
+    const task = stored.task
+    if (pending) task.status = { state: 'TASK_STATE_WORKING', message: agentMessage(`Still working (run ${pending}). Ask again with GetTask.`, task), timestamp: at }
+    else if (response.ok) {
+      task.status = { state: 'TASK_STATE_COMPLETED', timestamp: at }
+      task.artifacts = [{ artifactId: randomUUID(), name: skill.tool.title, parts: [{ text: skill.tool.summarize(json, stored.args as never), mediaType: 'text/plain' }, { data: json, mediaType: 'application/json' }] }]
+    } else {
+      const state = response.status === 401 || response.status === 403 ? 'TASK_STATE_AUTH_REQUIRED' : 'TASK_STATE_FAILED'
+      task.status = { state, message: agentMessage(problemText(json, response.status), task), timestamp: at }
+    }
+    if (task.status.message) task.history = [...(task.history ?? []), task.status.message]
+    await save(stored.owner, stored)
+    return stored
+  }
+
+  const argsOf = (skill: A2ASkill, message: Message) => {
+    const data = message.parts.find((part) => part.data && typeof part.data === 'object' && !Array.isArray(part.data))?.data as Record<string, unknown> | undefined
+    const text = message.parts.flatMap((part) => (typeof part.text === 'string' ? [part.text] : [])).join('\n').trim()
+    const args = { ...(text ? { [skill.text]: text } : {}), ...data }
+    const parsed = skill.tool.input.safeParse(args)
+    if (!parsed.success) throw new RpcError(ERRORS.params, `${skill.tool.name}: ${parsed.error.issues.map((issue) => `${issue.path.join('.') || skill.text}: ${issue.message}`).join('; ')}`)
+    return parsed.data as Record<string, unknown>
+  }
+
+  const methods: Record<string, (c: Context, params: any) => Promise<unknown>> = {
+    SendMessage: async (c, params) => {
+      const message = params?.message as Message | undefined
+      if (!message || typeof message.messageId !== 'string' || message.role !== 'ROLE_USER' || !Array.isArray(message.parts) || !message.parts.length)
+        throw new RpcError(ERRORS.params, 'params.message needs messageId, role ROLE_USER and at least one part.')
+      const owner = ownerOf(c)
+      if (message.taskId) {
+        const stored = await load(owner, message.taskId)
+        if (TERMINAL.has(stored.task.status.state)) throw new RpcError(ERRORS.unsupported, `Task ${stored.task.id} is finished; send a new message without taskId.`)
+        return { task: shown(await run(c, stored, 0), params?.configuration?.historyLength) }
+      }
+      const name = (params?.metadata?.skill ?? message.metadata?.skill ?? skills[0]?.tool.name) as string
+      const skill = byId.get(name)
+      if (!skill) throw new RpcError(ERRORS.params, `Unknown skill ${name}. Skills: ${[...byId.keys()].join(', ')}.`)
+      const args = argsOf(skill, message)
+      const task: Task = { id: randomUUID(), contextId: message.contextId ?? randomUUID(), status: { state: 'TASK_STATE_WORKING', timestamp: new Date().toISOString() }, metadata: { skill: name } }
+      task.history = [{ ...message, taskId: task.id, contextId: task.contextId }]
+      const stored = await run(c, { owner, task, skill: name, args, created: Date.now() }, params?.configuration?.returnImmediately ? 0 : waitMs)
+      return { task: shown(stored, params?.configuration?.historyLength) }
+    },
+    GetTask: async (c, params) => {
+      const stored = await load(ownerOf(c), params?.id)
+      return shown(stored.task.status.state === 'TASK_STATE_WORKING' ? await run(c, stored, 0) : stored, params?.historyLength)
+    },
+    ListTasks: async (c, params) => {
+      const owner = ownerOf(c)
+      const ids = ((await store.get(INDEX, owner))?.ids as string[] | undefined) ?? []
+      const all = (await Promise.all(ids.map((id) => store.get(KIND, id) as Promise<Stored | null>))).filter((stored): stored is Stored => !!stored && stored.owner === owner)
+      const matching = all.filter((stored) => (!params?.contextId || stored.task.contextId === params.contextId) && (!params?.status || stored.task.status.state === params.status))
+      const pageSize = Math.min(Math.max(Number(params?.pageSize) || 50, 1), 100)
+      const start = Number(params?.pageToken) || 0
+      const page = matching.slice(start, start + pageSize)
+      return {
+        tasks: page.map((stored) => {
+          const task = shown(stored, params?.historyLength ?? 0) as Task
+          return params?.includeArtifacts ? task : { ...task, artifacts: undefined }
+        }),
+        nextPageToken: start + pageSize < matching.length ? String(start + pageSize) : '',
+        pageSize,
+        totalSize: matching.length,
+      }
+    },
+    CancelTask: async (c, params) => {
+      const stored = await load(ownerOf(c), params?.id)
+      if (TERMINAL.has(stored.task.status.state)) throw new RpcError(ERRORS.notCancelable, `Task ${stored.task.id} already ended (${stored.task.status.state}).`)
+      stored.task.status = { state: 'TASK_STATE_CANCELED', timestamp: new Date().toISOString() }
+      await save(stored.owner, stored)
+      return shown(stored)
+    },
+  }
+  const unsupported = ['SendStreamingMessage', 'SubscribeToTask', 'GetExtendedAgentCard']
+  const push = ['CreateTaskPushNotificationConfig', 'GetTaskPushNotificationConfig', 'ListTaskPushNotificationConfigs', 'DeleteTaskPushNotificationConfig']
+
+  app.post(path, async (c: Context) => {
+    const reply = (body: unknown) => c.json(body as never, 200)
+    const body = await c.req.json().catch(() => undefined)
+    if (body === undefined) return reply(rpcError(null, ERRORS.parse, 'The body is not JSON.'))
+    if (!body || typeof body !== 'object' || Array.isArray(body) || body.jsonrpc !== '2.0' || typeof body.method !== 'string')
+      return reply(rpcError(body?.id, ERRORS.request, 'Send one JSON-RPC 2.0 request: {"jsonrpc":"2.0","id":1,"method":"SendMessage","params":{…}}.'))
+    // An absent version means 0.3 (spec §3.2.6); this endpoint speaks 1.0
+    const version = c.req.header('a2a-version') ?? c.req.query('A2A-Version') ?? '0.3'
+    if (version.split('.').slice(0, 2).join('.') !== A2A_VERSION) return reply(rpcError(body.id, ERRORS.version, `Send the header A2A-Version: ${A2A_VERSION}.`))
+    if (unsupported.includes(body.method)) return reply(rpcError(body.id, ERRORS.unsupported, `${body.method}: this agent answers SendMessage and GetTask only (no streaming, no extended card).`))
+    if (push.includes(body.method)) return reply(rpcError(body.id, ERRORS.noPush, 'Poll with GetTask instead.'))
+    const method = methods[body.method]
+    if (!method) return reply(rpcError(body.id, ERRORS.method, `Methods: ${Object.keys(methods).join(', ')}.`))
+    try {
+      return reply({ jsonrpc: '2.0', id: body.id ?? null, result: await method(c, body.params) })
+    } catch (error) {
+      if (error instanceof RpcError) return reply(rpcError(body.id, error.error, error.detail))
+      throw error
+    }
+  })
+}

package/src/boards/README.md

@@ -0,0 +1,35 @@
+# boards
+
+The owner's own collections of the app's items for a project, with a note per item: the part of a read-only catalog
+you can write. Routes, MCP tools, and the reference shape of a kit feature.
+
+Needs: `db`, `mcp`.
+
+```ts
+import { boardTools, registerBoards } from './kit/boards/index.js'
+
+await registerBoards(app, { db, item: RecipeCardSchema, refExample: 'recipe:soup', itemOf: (ref, origin) => cardOfRef(ref, origin), suggestions })
+const tools = boardTools({ noun: 'recipes', label: (recipe) => recipe.title, suggestions: true })
+```
+
+Routes: `GET|POST /api/boards` (`?item=<ref>`: the boards holding it), `GET|PATCH|DELETE /api/boards/{id}`,
+`PUT|DELETE /api/boards/{id}/items/{ref}` (idempotent), `GET /api/boards/{id}/suggestions`. Writes need `write`.
+
+## The feature shape (copy it for your own features)
+
+| File | What |
+|---|---|
+| `schema.ts` | the Drizzle tables and `BOARDS_MIGRATIONS` (step 1 = its tables) |
+| `repo.ts` | `boardsRepo(db)`: the only queries, nothing about HTTP |
+| `routes.ts` | `boardRoutes(config)`: the `createRoute` contracts and their schemas |
+| `handlers.ts` | `boardHandlers(config, repo)`: request → repo → HAL; a missing board or item is a `ProblemError` |
+| `tools.ts` | `boardTools`: the MCP tools over the routes |
+| `refs.ts` | `boardRef(type, id)`, `parseBoardRef(ref)`, `BOARD_REF`: also copied with `boards-client` |
+| `index.ts` | `registerBoards`: migrate, then wire routes to handlers |
+
+## Rules
+
+- A ref is `<type>:<id>`; the id may hold colons (`segment:episode:intro:2`). Build and read refs with
+  `boardRef` / `parseBoardRef`, never by hand.
+- An app whose boards also list other things (curated collections beside the owner's) keeps its own feature, in this shape.
+- Standard: `docs/STANDARD.md` §17.

package/src/boards/handlers.ts

@@ -0,0 +1,87 @@
+/** The board routes' handlers: request → repo → HAL answer; a missing board or item is a problem. No queries here. */
+import type { RouteHandler } from '@hono/zod-openapi'
+import { linksOf, originOf } from '../core/hal.js'
+import { ProblemError } from '../core/problem.js'
+import type { BoardsConfig } from './index.js'
+import type { BoardRow, BoardsRepo } from './repo.js'
+import type { BoardRoutes } from './routes.js'
+
+export const boardHandlers = (config: BoardsConfig, repo: BoardsRepo) => {
+  const path = config.path ?? '/api/boards'
+  const rowOf = async (boardId: string) => {
+    const row = await repo.get(boardId)
+    if (!row) throw new ProblemError('not_found', { detail: `No board ${boardId}. GET ${path} lists them.` })
+    return row
+  }
+  const boardOf = async (origin: string, row: BoardRow, withItems = false) => ({
+    id: row.id,
+    name: row.name,
+    description: row.description,
+    items: row.items,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+    _links: linksOf(origin, {
+      self: `${path}/${row.id}`,
+      item: { path: `${path}/${row.id}/items/{ref}`, templated: true, title: 'PUT to add, DELETE to remove' },
+      suggestions: config.suggestions ? { path: `${path}/${row.id}/suggestions`, title: 'More like what is on it' } : null,
+    }),
+    ...(withItems ? { _embedded: { items: (await repo.items(row.id)).map((item) => ({ ...item, item: config.itemOf(item.ref, origin) ?? null })) } } : {}),
+  })
+
+  const list: RouteHandler<BoardRoutes['list']> = async (c) => {
+    const { item } = c.req.valid('query')
+    const rows = await repo.list(item)
+    const origin = originOf(c)
+    return c.json({ count: rows.length, _links: linksOf(origin, { self: `${path}${item ? `?item=${encodeURIComponent(item)}` : ''}`, create: { path, title: 'POST { name } to make one' } }), _embedded: { boards: await Promise.all(rows.map((row) => boardOf(origin, row))) } }, 200)
+  }
+
+  const create: RouteHandler<BoardRoutes['create']> = async (c) => {
+    const { name, description } = c.req.valid('json')
+    const boardId = await repo.create({ name: name.trim(), description: description?.trim() || null })
+    return c.json(await boardOf(originOf(c), await rowOf(boardId)), 201, { location: `${path}/${boardId}` })
+  }
+
+  const get: RouteHandler<BoardRoutes['get']> = async (c) => c.json(await boardOf(originOf(c), await rowOf(c.req.valid('param').id), true), 200)
+
+  const update: RouteHandler<BoardRoutes['update']> = async (c) => {
+    const { id: boardId } = c.req.valid('param')
+    const { name, description } = c.req.valid('json')
+    const row = await rowOf(boardId)
+    await repo.update(boardId, { name: name?.trim() || row.name, description: description === undefined ? row.description : description.trim() || null })
+    return c.json(await boardOf(originOf(c), await rowOf(boardId)), 200)
+  }
+
+  const remove: RouteHandler<BoardRoutes['remove']> = async (c) => {
+    const { id: boardId } = c.req.valid('param')
+    await rowOf(boardId)
+    await repo.remove(boardId)
+    return c.body(null, 204)
+  }
+
+  const save: RouteHandler<BoardRoutes['save']> = async (c) => {
+    const { id: boardId, ref: itemRef } = c.req.valid('param')
+    const { note } = ((await c.req.json().catch(() => ({}))) ?? {}) as { note?: string }
+    await rowOf(boardId)
+    if (config.itemOf(itemRef, originOf(c)) == null) throw new ProblemError('not_found', { detail: `No item ${itemRef} in the catalog. Add items by the ref their search results and links give.` })
+    const saved = await repo.save(boardId, itemRef, note?.trim() || null)
+    return c.json(await boardOf(originOf(c), await rowOf(boardId)), saved === 'added' ? 201 : 200)
+  }
+
+  const unsave: RouteHandler<BoardRoutes['unsave']> = async (c) => {
+    const { id: boardId, ref: itemRef } = c.req.valid('param')
+    await rowOf(boardId)
+    await repo.unsave(boardId, itemRef)
+    return c.body(null, 204)
+  }
+
+  const suggestions: RouteHandler<BoardRoutes['suggestions']> = async (c) => {
+    const { id: boardId } = c.req.valid('param')
+    await rowOf(boardId)
+    const refs = await repo.refs(boardId)
+    const origin = originOf(c)
+    const items = refs.length && config.suggestions ? config.suggestions(refs, c.req.valid('query').limit, origin) : []
+    return c.json({ count: items.length, _links: linksOf(origin, { self: `${path}/${boardId}/suggestions`, board: `${path}/${boardId}` }), _embedded: { items } }, 200)
+  }
+
+  return { list, create, get, update, remove, save, unsave, suggestions }
+}

package/src/boards/index.ts

@@ -0,0 +1,64 @@
+/**
+ * Boards: the owner's own collections of the app's items for a project, the part of a catalog you can write. An item
+ * is addressed by a ref the app chooses (`recipe:<slug>`, `cook:<id>`); adding is idempotent (`PUT`) and every item
+ * can carry a note. Kept in the app's database (`db`, the same one as its OAuth state), read and written through:
+ *   GET    {path}                     every board, newest change first; `?item=<ref>` only the boards holding it
+ *   POST   {path}                     a new board → 201 with `Location`
+ *   GET    {path}/{id}                a board with its items (each resolved to the app's card, null if it left)
+ *   PATCH  {path}/{id}                rename or describe it
+ *   DELETE {path}/{id}                delete it (its items are only references)
+ *   PUT    {path}/{id}/items/{ref}    add an item, or change its note
+ *   DELETE {path}/{id}/items/{ref}    take it off
+ *   GET    {path}/{id}/suggestions    more like what is on it (when the app gives `suggestions`)
+ * Writes need the `write` scope (an OAuth token with it, a key, or the owner's browser on the same site).
+ *
+ * @example
+ * await registerBoards(app, { db: await openDb(`file:${stateFile}`), item: RecipeCardSchema, refExample: 'recipe:soup', itemOf: (ref, origin) => cardOfRef(ref, origin) })
+ * mcpServerFactory({ tools: [...boardTools({ noun: 'recipes', label: (recipe) => recipe.title }), …], … })
+ */
+import type { OpenAPIHono, z } from '@hono/zod-openapi'
+import { migrate, type Db } from '../db/index.js'
+import { boardHandlers } from './handlers.js'
+import { boardsRepo } from './repo.js'
+import { boardRoutes } from './routes.js'
+import { BOARDS_MIGRATIONS } from './schema.js'
+
+export { BOARD_REF, boardRef, parseBoardRef } from './refs.js'
+export { boardsRepo, type BoardRow, type BoardsRepo } from './repo.js'
+export { boardRoutes, type BoardRoutes } from './routes.js'
+export { boardItems, boards, BOARDS_MIGRATIONS } from './schema.js'
+export { boardTools } from './tools.js'
+
+export type BoardsConfig = {
+  /** Default `/api/boards`. */
+  path?: string
+  /** The app's database (`openDb`); the boards tables are migrated into it. */
+  db: Db
+  /** The OpenAPI schema of an item's card. */
+  item: z.ZodTypeAny
+  /** A ref → the app's card for it, or null when it left the catalog. */
+  itemOf: (ref: string, origin: string) => unknown
+  /** What a ref looks like (default `BOARD_REF`, `<type>:<id>`). */
+  refPattern?: RegExp
+  refExample: string
+  tag?: string
+  /** Cards for refs like those on a board, best first, leaving out what is on it. */
+  suggestions?: (refs: string[], limit: number, origin: string) => unknown[]
+}
+
+/**
+ * Registers the board routes on the app, after migrating the boards tables. Call it after `createAgentApi`.
+ */
+export const registerBoards = async (app: OpenAPIHono, config: BoardsConfig) => {
+  await migrate(config.db, 'boards', BOARDS_MIGRATIONS)
+  const routes = boardRoutes(config)
+  const handle = boardHandlers(config, boardsRepo(config.db))
+  app.openapi(routes.list, handle.list)
+  app.openapi(routes.create, handle.create)
+  app.openapi(routes.get, handle.get)
+  app.openapi(routes.update, handle.update)
+  app.openapi(routes.remove, handle.remove)
+  app.openapi(routes.save, handle.save)
+  app.openapi(routes.unsave, handle.unsave)
+  if (config.suggestions) app.openapi(routes.suggestions, handle.suggestions)
+}

package/src/boards/refs.ts

@@ -0,0 +1,23 @@
+/**
+ * Board refs: how a board addresses an item, `<type>:<id>`. The type is a short lowercase word the app chooses
+ * (`recipe`, `segment`); the id is everything after the first colon and may hold colons itself
+ * (`segment:episode:intro:2`). Shared by `boards` (server) and `boards-client` (browser), so both read refs
+ * the same way.
+ *
+ * @example
+ * boardRef('recipe', 'soup')                        // 'recipe:soup'
+ * parseBoardRef('segment:episode:intro:2')  // { type: 'segment', id: 'episode:intro:2' }
+ * parseBoardRef('fox')                           // null: no type
+ */
+
+/** A whole ref: a type, a colon, an id of word characters, dots, colons and hyphens. */
+export const BOARD_REF = /^([a-z][\w-]*):([\w.:-]+)$/
+
+/** The ref for an item of this type. */
+export const boardRef = (type: string, id: string) => `${type}:${id}`
+
+/** A ref's type and id, or null when it isn't a ref. */
+export const parseBoardRef = (ref: string): { type: string; id: string } | null => {
+  const match = BOARD_REF.exec(ref)
+  return match ? { type: match[1]!, id: match[2]! } : null
+}

package/src/boards/repo.ts

@@ -0,0 +1,50 @@
+/** Boards in the database: the only place they are queried, and nothing about HTTP. */
+import { randomUUID } from 'node:crypto'
+import { and, desc, eq, exists, sql } from 'drizzle-orm'
+import type { Db } from '../db/index.js'
+import { boardItems, boards } from './schema.js'
+
+export type BoardRow = typeof boards.$inferSelect & { items: number }
+
+export const boardsRepo = (db: Db) => {
+  const columns = { id: boards.id, name: boards.name, description: boards.description, createdAt: boards.createdAt, updatedAt: boards.updatedAt, items: sql<number>`(select count(*) from ${boardItems} where ${boardItems.boardId} = ${boards.id})`.mapWith(Number) }
+  const now = () => new Date().toISOString()
+  const touch = (id: string) => db.update(boards).set({ updatedAt: now() }).where(eq(boards.id, id))
+  return {
+    /** Every board, newest change first; with a ref, only those holding it. */
+    list: (holding?: string): Promise<BoardRow[]> =>
+      db
+        .select(columns)
+        .from(boards)
+        .where(holding ? exists(db.select({ one: sql`1` }).from(boardItems).where(and(eq(boardItems.boardId, boards.id), eq(boardItems.ref, holding)))) : undefined)
+        .orderBy(desc(boards.updatedAt)),
+    get: async (id: string): Promise<BoardRow | undefined> => (await db.select(columns).from(boards).where(eq(boards.id, id)))[0],
+    create: async ({ name, description }: { name: string; description: string | null }) => {
+      const id = randomUUID()
+      const at = now()
+      await db.insert(boards).values({ id, name, description, createdAt: at, updatedAt: at })
+      return id
+    },
+    update: (id: string, change: { name: string; description: string | null }) => db.update(boards).set({ ...change, updatedAt: now() }).where(eq(boards.id, id)),
+    remove: async (id: string) => {
+      await db.delete(boardItems).where(eq(boardItems.boardId, id))
+      await db.delete(boards).where(eq(boards.id, id))
+    },
+    items: (id: string) => db.select({ ref: boardItems.ref, note: boardItems.note, addedAt: boardItems.addedAt }).from(boardItems).where(eq(boardItems.boardId, id)).orderBy(desc(boardItems.addedAt)),
+    refs: async (id: string) => (await db.select({ ref: boardItems.ref }).from(boardItems).where(eq(boardItems.boardId, id))).map((row) => row.ref),
+    /** Puts an item on a board, or changes its note; 'added' or 'noted'. */
+    save: async (id: string, ref: string, note: string | null): Promise<'added' | 'noted'> => {
+      const existed = (await db.select({ ref: boardItems.ref }).from(boardItems).where(and(eq(boardItems.boardId, id), eq(boardItems.ref, ref)))).length > 0
+      if (existed) await db.update(boardItems).set({ note: sql`coalesce(${note}, ${boardItems.note})` }).where(and(eq(boardItems.boardId, id), eq(boardItems.ref, ref)))
+      else await db.insert(boardItems).values({ boardId: id, ref, note, addedAt: now() })
+      await touch(id)
+      return existed ? 'noted' : 'added'
+    },
+    unsave: async (id: string, ref: string) => {
+      await db.delete(boardItems).where(and(eq(boardItems.boardId, id), eq(boardItems.ref, ref)))
+      await touch(id)
+    },
+  }
+}
+
+export type BoardsRepo = ReturnType<typeof boardsRepo>

package/src/boards/routes.ts

@@ -0,0 +1,83 @@
+/** The board routes as OpenAPI contracts: paths, parameters, bodies and answers, built around the app's item card. */
+import { createRoute, z } from '@hono/zod-openapi'
+import { HAL_JSON, LinksSchema } from '../core/hal.js'
+import { problemResponses } from '../core/problem.js'
+import type { BoardsConfig } from './index.js'
+import { BOARD_REF } from './refs.js'
+
+export const boardRoutes = (config: BoardsConfig) => {
+  const { path = '/api/boards', tag = 'Boards' } = config
+  const BoardItemSchema = z
+    .object({
+      ref: z.string().openapi({ description: 'The item’s address, e.g. `' + config.refExample + '`.', example: config.refExample }),
+      note: z.string().nullable().openapi({ description: 'Why it is here.' }),
+      addedAt: z.string(),
+      item: config.item.nullable().openapi({ description: 'The item’s card (null if it left the catalog).' }),
+    })
+    .openapi('BoardItem', { description: 'Something on a board, with its note.' })
+  const BoardSchema = z
+    .object({
+      id: z.string(),
+      name: z.string(),
+      description: z.string().nullable(),
+      items: z.number().int().openapi({ description: 'How many items are on it.' }),
+      createdAt: z.string(),
+      updatedAt: z.string(),
+      _links: LinksSchema,
+      _embedded: z.object({ items: z.array(BoardItemSchema) }).optional(),
+    })
+    .openapi('Board', { description: 'A board: a collection of items for a project, with notes.' })
+  const BoardListSchema = z.object({ count: z.number().int(), _links: LinksSchema, _embedded: z.object({ boards: z.array(BoardSchema) }) }).openapi('BoardList', { description: 'Boards, most recently changed first.' })
+  const BoardInputSchema = z.object({ name: z.string().min(1).max(120).openapi({ example: 'Bank identity references' }), description: z.string().max(1000).optional().openapi({ description: 'What the board is for.' }) }).openapi('BoardInput', { description: 'A board’s name and what it is for.' })
+  const BoardPatchSchema = BoardInputSchema.partial().openapi('BoardPatch', { description: 'A new name or description.' })
+  const NoteSchema = z.object({ note: z.string().max(1000).optional().openapi({ description: 'Why it is here.' }) }).openapi('BoardItemInput', { description: 'An optional note for the item.' })
+  const SuggestionsSchema = z.object({ count: z.number().int(), _links: LinksSchema, _embedded: z.object({ items: z.array(config.item) }) }).openapi('BoardSuggestions', { description: 'Items like those on a board, best first.' })
+  const id = z.string().min(1).max(80).openapi({ description: 'The board’s id.', example: '0b2e4c1a-5d1f-4b3e-9a51-7c8f2e6d1a90' })
+  const ref = z.string().regex(config.refPattern ?? BOARD_REF).openapi({ description: 'The item’s ref, e.g. `' + config.refExample + '`.', example: config.refExample })
+  const ok = <Schema extends z.ZodTypeAny>(description: string, schema: Schema) => ({ content: { [HAL_JSON]: { schema } }, description })
+
+  return {
+    list: createRoute({
+      method: 'get', path, operationId: 'listBoards', tags: [tag], summary: 'Boards', description: 'Every board with how many items it holds, most recently changed first. `item` keeps only the boards that hold that item (to show where something is saved).',
+      request: { query: z.object({ item: ref.optional().openapi({ description: 'Only boards holding this ref.' }) }) },
+      responses: { 200: ok('Boards.', BoardListSchema), ...problemResponses(400, 401) },
+    }),
+    create: createRoute({
+      method: 'post', path, operationId: 'createBoard', tags: [tag], summary: 'Make a board', description: 'A new, empty board with a name and what it is for. Answers 201 with its address in `Location`.',
+      request: { body: { required: true, content: { 'application/json': { schema: BoardInputSchema } } } },
+      responses: { 201: ok('The new board.', BoardSchema), ...problemResponses(400, 401, 403) },
+    }),
+    get: createRoute({
+      method: 'get', path: `${path}/{id}`, operationId: 'getBoard', tags: [tag], summary: 'One board with its items', description: 'A board and everything on it, newest first, each with its note and the item’s card (null if it left the catalog).',
+      request: { params: z.object({ id }) },
+      responses: { 200: ok('The board.', BoardSchema), ...problemResponses(401, 404) },
+    }),
+    update: createRoute({
+      method: 'patch', path: `${path}/{id}`, operationId: 'updateBoard', tags: [tag], summary: 'Rename or describe a board', description: 'Changes a board’s name, its description, or both.',
+      request: { params: z.object({ id }), body: { required: true, content: { 'application/json': { schema: BoardPatchSchema } } } },
+      responses: { 200: ok('The board.', BoardSchema), ...problemResponses(400, 401, 403, 404) },
+    }),
+    remove: createRoute({
+      method: 'delete', path: `${path}/{id}`, operationId: 'deleteBoard', tags: [tag], summary: 'Delete a board', description: 'Deletes the board and its notes. The items themselves stay in the catalog.',
+      request: { params: z.object({ id }) },
+      responses: { 204: { description: 'Deleted.' }, ...problemResponses(401, 403, 404) },
+    }),
+    save: createRoute({
+      method: 'put', path: `${path}/{id}/items/{ref}`, operationId: 'putBoardItem', tags: [tag], summary: 'Add an item to a board', description: 'Adds the item, or changes its note when it is already there; doing it twice is harmless. 201 when added, 200 when only the note changed.',
+      request: { params: z.object({ id, ref }), body: { required: false, content: { 'application/json': { schema: NoteSchema } } } },
+      responses: { 200: ok('The board.', BoardSchema), 201: ok('The board.', BoardSchema), ...problemResponses(400, 401, 403, 404) },
+    }),
+    unsave: createRoute({
+      method: 'delete', path: `${path}/{id}/items/{ref}`, operationId: 'deleteBoardItem', tags: [tag], summary: 'Take an item off a board', description: 'Removes the item and its note from the board; harmless when it was not there.',
+      request: { params: z.object({ id, ref }) },
+      responses: { 204: { description: 'Removed.' }, ...problemResponses(400, 401, 403, 404) },
+    }),
+    suggestions: createRoute({
+      method: 'get', path: `${path}/{id}/suggestions`, operationId: 'listBoardSuggestions', tags: [tag], summary: 'More like what is on a board', description: 'Items like the ones on the board, best first, leaving out what is already on it. Free.',
+      request: { params: z.object({ id }), query: z.object({ limit: z.coerce.number().int().min(1).max(100).default(24).openapi({ description: 'At most this many (1–100, default 24).' }) }) },
+      responses: { 200: ok('Suggestions.', SuggestionsSchema), ...problemResponses(400, 401, 404) },
+    }),
+  }
+}
+
+export type BoardRoutes = ReturnType<typeof boardRoutes>

package/src/boards/schema.ts

@@ -0,0 +1,28 @@
+/** The boards tables, and the SQL that makes them (one migration step per change, never edited once shipped). */
+import { index, primaryKey, sqliteTable, text } from 'drizzle-orm/sqlite-core'
+
+export const boards = sqliteTable('boards', {
+  id: text('id').primaryKey(),
+  name: text('name').notNull(),
+  description: text('description'),
+  createdAt: text('created_at').notNull(),
+  updatedAt: text('updated_at').notNull(),
+})
+
+export const boardItems = sqliteTable(
+  'board_items',
+  {
+    boardId: text('board_id').notNull().references(() => boards.id, { onDelete: 'cascade' }),
+    ref: text('ref').notNull(),
+    note: text('note'),
+    addedAt: text('added_at').notNull(),
+  },
+  (table) => [primaryKey({ columns: [table.boardId, table.ref] }), index('board_items_ref').on(table.ref)],
+)
+
+/** The tables as SQL, one step per change, never edited once shipped. Step 1 is what every app's state already holds. */
+export const BOARDS_MIGRATIONS = [
+  `create table if not exists boards (id text primary key, name text not null, description text, created_at text not null, updated_at text not null);
+create table if not exists board_items (board_id text not null references boards(id) on delete cascade, ref text not null, note text, added_at text not null, primary key (board_id, ref));
+create index if not exists board_items_ref on board_items(ref)`,
+] as const