@pikku/skills 0.12.2 → 0.12.6

package/skills/pikku-machine-auth/SKILL.md

@@ -157,7 +157,42 @@ addHTTPMiddleware([
 
 When the api-key header is present it is authoritative — the middleware never
 falls through to `getSession` (a bare mock session would shadow the scoped one).
-When it is absent, the human `getSession` path runs as normal.
+When it is absent, the human `getSession` path runs as normal. Either way the
+middleware bails out entirely if a session is already set, and it checks the
+*live* session rather than the wire's construction-time snapshot, so it can't
+clobber one an earlier middleware resolved.
+
+### Restricting a key below its owner
+
+Set `scopes` on the session `mapKey` returns and that set is **authoritative** —
+including an empty one. It is never widened back out to everything the owning
+service user holds:
+
+```typescript
+mapKey: async (key) => ({
+  userId: 'sandbox-runtime',
+  scopes: ['sandbox:read'], // this key can do only this
+})
+```
+
+Leave `scopes` unset for a key that acts with its owner's full rights. This is
+what makes one stable service user safely able to own keys of very different
+power — the restriction lives on the key, not on a proliferation of identities.
+
+### Failure handling is deliberately split
+
+A key that fails to verify is logged and treated as an ordinary "not
+authenticated" — an unusable credential is not an outage. A failure *inside*
+`mapKey` (your scope store is down) propagates as a real error instead. That
+asymmetry is on purpose: a scope lookup that silently failed would serve the
+request anonymously, which is exactly the wrong direction to fail in.
+
+### `betterAuthStatelessSession` has no machine path
+
+The lean cookie-cache middleware (`betterAuthStatelessSession` — no
+`services.auth()`, no DB) handles only the human path. Machine auth needs
+`betterAuthSession`, because `verifyApiKey` is a server call there is no
+stateless equivalent of. Both accept an `impersonation` option.
 
 ### WebSocket channels authenticate on the upgrade handshake
 

package/skills/pikku-mcp/SKILL.md

@@ -2,11 +2,11 @@
 name: pikku-mcp
 description: >-
   Use when exposing Pikku functions as MCP tools, resources, or prompts for AI assistants. Covers
-  mcp: true flag, pikkuMCPResourceFunc, pikkuMCPPromptFunc, and MCP wire object. TRIGGER when:
-  code uses mcp: true or pikkuMCPResourceFunc/pikkuMCPPromptFunc, user asks about MCP, Model
-  Context Protocol, AI tool integration, or exposing functions to Claude/ChatGPT. DO NOT TRIGGER
-  when: user asks about AI agents (use pikku-ai-agent) or general function definitions (use
-  pikku-concepts).
+  mcp: true, pikkuMCPToolFunc, pikkuMCPResourceFunc, pikkuMCPPromptFunc, wireMCPResource,
+  wireMCPPrompt, the MCP wire object and PikkuMCPServer. TRIGGER when: code uses mcp: true or any
+  pikkuMCP*Func/wireMCP* helper, user asks about MCP, Model Context Protocol, AI tool integration,
+  or exposing functions to Claude/ChatGPT. DO NOT TRIGGER when: user asks about AI agents (use
+  pikku-ai-agent) or general function definitions (use pikku-concepts).
 installGroups: [core]
 ---
 
@@ -33,209 +33,219 @@ pikku info tags --verbose        # Understand project organization
 
 See `pikku-concepts` for the core mental model.
 
+## The shape of MCP in Pikku
+
+MCP has three surfaces, and Pikku wires them differently:
+
+| Surface | Function factory | Wiring | Return type |
+| --- | --- | --- | --- |
+| **Tool** | `mcp: true` on a `pikkuFunc`, or `pikkuMCPToolFunc` | none — the function *is* the registration | the func's own output, or MCP content blocks |
+| **Resource** | `pikkuMCPResourceFunc` | `wireMCPResource({ uri, title, … })` | `Array<{ uri, text }>` |
+| **Prompt** | `pikkuMCPPromptFunc` | `wireMCPPrompt({ name, description, … })` | `Array<MCPPromptMessage>` |
+
+Tools are the odd one out — there is no `wireMCPTool`. Resources and prompts
+carry protocol metadata (a URI template, a prompt name) that belongs to the
+endpoint rather than the implementation, so that metadata lives on the wiring and
+the `pikkuMCP*Func` factory stays a plain function.
+
+Import every factory and wiring from `#pikku`.
+
 ## API Reference
 
-### MCP Tools (simplest approach)
+### Tools
 
-Add `mcp: true` to any existing `pikkuFunc` to expose it as an MCP tool:
+Add `mcp: true` to any existing function:
 
 ```typescript
-const myFunc = pikkuFunc({
-  description: string,      // Used as MCP tool description
-  input: ZodSchema,         // Becomes MCP tool input schema
-  output: ZodSchema,        // Return type
-  mcp: true,                // ← Expose as MCP tool
-  func: async (services, data) => { ... },
+export const createTodo = pikkuFunc({
+  description: 'Create a new todo item',   // becomes the MCP tool description
+  input: CreateTodoInput,                  // becomes the MCP tool input schema
+  output: CreateTodoOutput,
+  mcp: true,
+  func: async ({ db }, { text, priority }) => db.createTodo({ text, priority }),
 })
 ```
 
-### MCP Resources (`pikkuMCPResourceFunc`)
+A missing `description` is all an assistant has to go on, so codegen warns about
+it rather than failing — treat the warning as a bug.
+
+Use `pikkuMCPToolFunc` when the tool should control its own presentation. It
+returns MCP content blocks (`{ type: 'text', text }` or `{ type: 'image', data }`
+with base64), so the assistant reads prose rather than raw JSON:
 
 ```typescript
-import { pikkuMCPResourceFunc } from '#pikku'
+import { pikkuMCPToolFunc } from '#pikku'
 
-const resource = pikkuMCPResourceFunc({
-  uri: string,              // URI template, e.g. 'todos/{id}'
-  title: string,            // Human-readable title
-  description?: string,
-  func: async (services, data, { mcp }) => {
-    // Must return array of { uri, text } or { uri, blob, mimeType }
-    return [{ uri: mcp.uri!, text: JSON.stringify(result) }]
+export const createTodoTool = pikkuMCPToolFunc({
+  description: 'Create a todo item with title, priority, due date and tags',
+  input: CreateTodoWithUserInputSchema,
+  func: async (_services, input, { rpc }) => {
+    const { todo } = await rpc.invoke('createTodo', input)
+    return [
+      { type: 'text' as const, text: `Created "${todo.title}" (${todo.id})` },
+    ]
   },
 })
 ```
 
-### MCP Prompts (`pikkuMCPPromptFunc`)
+It also accepts `name`, `title`, `summary`, `tags`, `middleware` and
+`permissions`. The function is sessionless and gets `mcp` and `rpc` on its wire —
+calling existing business functions through `rpc.invoke` keeps the tool a thin
+presentation layer over logic that is already tested and reachable over HTTP.
+
+### Resources
 
 ```typescript
-import { pikkuMCPPromptFunc } from '#pikku'
+import { pikkuMCPResourceFunc } from '#pikku'
 
-const prompt = pikkuMCPPromptFunc({
-  name: string,
-  description: string,
-  func: async (services, data) => {
-    // Must return array of MCP messages
+export const getTodoResource = pikkuMCPResourceFunc<{ id: string }>(
+  async (_services, { id }, { rpc, mcp }) => {
+    const { todo } = await rpc.invoke('getTodo', { id })
     return [
       {
-        role: 'user',
-        content: { type: 'text', text: '...' },
+        uri: mcp.uri!,
+        text: todo ? formatTodo(todo) : `Todo "${id}" not found.`,
       },
     ]
-  },
-})
-```
-
-### MCP Wire Object
-
-Inside MCP-enabled functions, `wire.mcp` provides:
-
-```typescript
-mcp.uri // Current resource URI (for resources)
-mcp.sendResourceUpdated(uri) // Notify clients a resource changed
-mcp.enableTools({ toolName: true }) // Dynamically enable/disable tools
+  }
+)
 ```
 
-## Usage Patterns
-
-### Expose Existing Functions as MCP Tools
-
-The simplest path — add `mcp: true` to any function:
+The factory takes either a bare function (as above) or a config object — `{ func, name }`,
+or `{ func, input }` with a schema. A resource returns `Array<{ uri, text }>`;
+it is text only, with no blob variant. `mcp.uri` is the concrete URI the client
+asked for, which is why each entry echoes it back.
 
 ```typescript
-export const createTodo = pikkuFunc({
-  description: 'Create a new todo item',
-  input: CreateTodoInput,
-  output: CreateTodoOutput,
-  mcp: true,
-  func: async ({ db }, { text, priority }) => {
-    return await db.createTodo({ text, priority })
-  },
-})
-```
+import { wireMCPResource } from '#pikku'
 
-### MCP Resources with URI Templates
-
-```typescript
-export const getTodo = pikkuMCPResourceFunc({
-  uri: 'todos/{id}',
+wireMCPResource({
+  uri: 'todos/{id}', // URI template
   title: 'Todo Details',
-  description: 'Get a todo by ID',
-  func: async ({ db }, { id }, { mcp }) => {
-    const todo = await db.getTodo(id)
-    return [{ uri: mcp.uri!, text: JSON.stringify(todo) }]
-  },
+  description: 'Get details of a specific todo by ID',
+  func: getTodoResource,
+  tags: ['todos'],
+  // also: summary?, mimeType?, size?, streaming?, errors?, middleware?
 })
 ```
 
-### MCP Prompts
+Every `{param}` in `uri` is checked against the function's input at compile time,
+so `todos/{id}` wired to a function whose input has no `id` fails to build rather
+than handing the function an `undefined`.
+
+### Prompts
 
 ```typescript
-export const codeReview = pikkuMCPPromptFunc({
-  name: 'codeReview',
-  description: 'Generate a code review prompt',
-  func: async ({}, { filePath, context }) => {
+import { pikkuMCPPromptFunc, wireMCPPrompt } from '#pikku'
+
+export const planDayPrompt = pikkuMCPPromptFunc({
+  input: UserIdInputSchema,
+  func: async (_services, { userId }, { rpc }) => {
+    const { todos } = await rpc.invoke('listTodos', { userId, completed: false })
     return [
       {
-        role: 'user',
+        role: 'user' as const,
         content: {
-          type: 'text',
-          text: `Review ${filePath}. Context: ${context}`,
+          type: 'text' as const,
+          text: `Plan my day:\n${todos.map(formatTodo).join('\n')}`,
         },
       },
     ]
   },
 })
+
+wireMCPPrompt({
+  name: 'planDay',
+  description: 'Generate a daily plan based on pending todos',
+  func: planDayPrompt,
+  tags: ['productivity'],
+})
 ```
 
-### Dynamic Tool Control
+A message's `role` is `'user' | 'assistant' | 'system'` and its `content.type` is
+`'text' | 'image'`. The prompt arguments the client sees are derived from the
+input schema at codegen time: each property becomes a named argument, and
+schema-required properties become required arguments.
+
+### MCP Wire Object
+
+Available as `wire.mcp` inside any MCP function:
+
+```typescript
+mcp.uri // the resolved resource URI (resources only)
+mcp.sendResourceUpdated(uri) // notify clients a resource changed
+await mcp.enableTools({ archiveTodos: true })
+await mcp.enableResources({ todoDetails: false })
+await mcp.enablePrompts({ planDay: true })
+```
+
+The `enable*` calls are how a server presents a changing surface — hiding tools
+that are meaningless in the current state beats letting the assistant call them
+and fail. Each returns a boolean, and each name is typechecked against your
+generated endpoint names.
 
 ```typescript
-export const manageTodos = pikkuFunc({
-  description: 'Manage todo items',
-  input: ManageTodosInput,
-  output: ManageTodosOutput,
+export const deleteTodo = pikkuFunc({
+  description: 'Delete a todo item',
   mcp: true,
-  func: async ({ db }, { action, id }, { mcp }) => {
-    if (action === 'delete') {
-      await db.deleteTodo(id)
-      mcp.sendResourceUpdated(`todos/${id}`)
-      await mcp.enableTools({ archiveTodos: true })
-      return { deleted: true }
-    }
+  func: async ({ db }, { id }, { mcp }) => {
+    await db.deleteTodo(id)
+    mcp.sendResourceUpdated(`todos/${id}`)
+    return { deleted: true }
   },
 })
 ```
 
-### MCP Server Setup
+## MCP Server Setup
+
+`PikkuMCPServer` takes the server config and a logger — not your services. It
+loads the generated `mcp.gen.json`, and the bootstrap import is what registers
+your functions.
 
 ```typescript
 // start.ts
 import { PikkuMCPServer } from '@pikku/modelcontextprotocol'
+import { createConfig, createSingletonServices } from './services.js'
+import mcpJSON from '../.pikku/mcp/mcp.gen.json' with { type: 'json' }
+import '../.pikku/pikku-bootstrap.gen.js'
+
+const config = await createConfig()
+const singletonServices = await createSingletonServices(config)
+
+const server = new PikkuMCPServer(
+  {
+    name: 'pikku-mcp-server',
+    version: '1.0.0',
+    mcpJSON,
+    capabilities: { logging: {}, tools: {}, resources: {}, prompts: {} },
+  },
+  singletonServices.logger
+)
 
-const server = new PikkuMCPServer(config, singletonServices, createWireServices)
 await server.init()
-await server.start()
-```
 
-## Complete Example
+// stdio — the transport desktop MCP clients spawn
+await server.connectStdio()
+singletonServices.logger = server.createMCPLogger()
 
-```typescript
-// functions/todos.functions.ts
-export const listTodos = pikkuSessionlessFunc({
-  description: 'List all todo items',
-  input: ListTodosInput,
-  output: ListTodosOutput,
-  mcp: true,
-  func: async ({ db }, { status }) => {
-    return { todos: await db.listTodos(status) }
-  },
-})
+// …or streamable HTTP, for a hosted server
+const { close } = await server.connectHTTP({ port: 3000, host: '127.0.0.1' })
+```
 
-export const createTodo = pikkuFunc({
-  description: 'Create a new todo item',
-  input: CreateTodoInput,
-  output: CreateTodoOutput,
-  mcp: true,
-  func: async ({ db }, { text, priority }) => {
-    return await db.createTodo({ text, priority })
-  },
-})
+`capabilities` is a filter, not documentation: a surface you leave out is not
+advertised and its endpoints are never loaded, which is how you ship a tools-only
+server.
 
-export const completeTodo = pikkuFunc({
-  description: 'Mark a todo as complete',
-  input: CompleteTodoInput,
-  output: CompleteTodoOutput,
-  mcp: true,
-  func: async ({ db }, { todoId }) => {
-    return await db.completeTodo(todoId)
-  },
-})
+Over stdio the protocol owns stdout, so an ordinary console logger corrupts the
+frames — that is what `createMCPLogger()` is for. Swap the logger before
+anything logs.
 
-// functions/todos.mcp.ts
-export const getTodoResource = pikkuMCPResourceFunc({
-  uri: 'todos/{id}',
-  title: 'Todo Details',
-  description: 'Get details of a specific todo',
-  func: async ({ db }, { id }, { mcp }) => {
-    const todo = await db.getTodo(id)
-    return [{ uri: mcp.uri!, text: JSON.stringify(todo) }]
-  },
-})
+## Red flags
 
-export const planDayPrompt = pikkuMCPPromptFunc({
-  name: 'planDay',
-  description: 'Create a daily plan based on pending todos',
-  func: async ({ db }, {}) => {
-    const { todos } = await db.listTodos('pending')
-    return [
-      {
-        role: 'user',
-        content: {
-          type: 'text',
-          text: `Plan my day. Here are my pending todos:\n${todos.map((t) => `- ${t.text} (${t.priority})`).join('\n')}`,
-        },
-      },
-    ]
-  },
-})
-```
+| Symptom | Cause |
+| --- | --- |
+| `wireMCPTool` is not exported | There is no tool wiring — use `mcp: true` or `pikkuMCPToolFunc` |
+| `uri`/`title` rejected on `pikkuMCPResourceFunc` | Those belong on `wireMCPResource` |
+| Resource returning `{ uri, blob, mimeType }` | Resources are text only: `{ uri, text }` |
+| Client sees a tool with no description | `mcp: true` without a `description` — check the codegen warning |
+| stdio client disconnects on the first log line | Logger still writing to stdout; use `createMCPLogger()` |

package/skills/pikku-middleware/SKILL.md

@@ -136,7 +136,7 @@ Tags from the function definition and the wire object are merged — middleware
 ### Registering Tag Middleware
 
 ```typescript
-import { addTagMiddleware } from '.pikku/pikku-types.gen.js'
+import { addTagMiddleware } from '#pikku'
 
 addTagMiddleware('machine-agent', [machineAgentBearerAuth])
 ```
@@ -145,18 +145,30 @@ Call at module load time — typically in the same `wirings/*.ts` file as the `w
 
 ## Middleware Execution Order
 
-**Scope resolution order (broadest → narrowest):**
+Resolution happens in two steps, and the order matters more than it looks.
+
+**Step 1 — collect, broadest → narrowest:**
 
 ```text
 global → httpGroup/* → httpGroup/prefix → wiringTags → wiringMiddleware → funcTags → funcMiddleware → function body
 ```
 
-**Within each scope, sorted by priority:**
+**Step 2 — sort that whole flat list by priority:**
 
 ```text
 highest → high → medium (default) → low → lowest
 ```
 
+**Priority is the primary key across every scope, not within one.** The collected
+list is flattened first and sorted once, so a `priority: 'lowest'` global
+middleware runs *after* an inline per-route middleware of default priority — the
+narrower scope does not win. Scope order survives only as the tiebreaker between
+middleware of equal priority, because the sort is stable.
+
+This is what makes `telemetryOuter`/`telemetryInner` work: they pin themselves to
+`highest`/`lowest` so they bracket every other middleware no matter where those
+were registered.
+
 Set priority using the config-object form of `pikkuMiddleware`:
 
 ```typescript
@@ -167,7 +179,7 @@ const earlyMiddleware = pikkuMiddleware({
 })
 ```
 
-Priority is the primary sort key; within the same level, registration order is preserved. Use priority when a middleware must run before/after others regardless of registration order (e.g. telemetry wrapping everything, session extraction before auth checks).
+Within the same priority level, the collection order above is preserved. Use priority when a middleware must run before/after others regardless of where it was registered (e.g. telemetry wrapping everything, session extraction before auth checks).
 
 ## Service-to-Service Bearer Auth (canonical pattern)
 
@@ -185,7 +197,7 @@ export const getToken = () => _token
 ```typescript
 // wirings/http.wiring.ts
 import { timingSafeEqual } from 'node:crypto'
-import { addTagMiddleware, pikkuMiddleware } from '../../.pikku/pikku-types.gen.js'
+import { addTagMiddleware, pikkuMiddleware } from '#pikku'
 import { UnauthorizedError } from '@pikku/core/errors'
 import { getToken } from '../lib/host-token.js'
 

package/skills/pikku-mongodb/SKILL.md

@@ -59,17 +59,25 @@ await mongo.close()
 | `MongoDBAIStorageService`   | `AIStorageService, AIRunStateService` | AI conversation/run storage                    |
 | `MongoDBAgentRunService`    | `AgentRunService`                     | Agent execution tracking                       |
 | `MongoDBSecretService`      | `SecretService`                       | Encrypted secret storage (envelope encryption) |
+| `MongoDBSessionStore`       | `SessionStore`                        | Persisted user sessions                        |
 
 All services take a `Db` instance in their constructor and have an `init()` method that creates collections/indexes.
 
 ### Secret Service
 
+Envelope encryption: `key` derives the KEK that wraps each secret's own DEK.
+Keeping `previousKey` set is what makes `rotateKEK()` possible — it re-wraps
+every secret onto the current key and returns the new version.
+
 ```typescript
 import { MongoDBSecretService } from '@pikku/mongodb'
 
 const secrets = new MongoDBSecretService(mongo.db, {
-  kekSecret: 'your-key-encryption-key',
-  salt: 'your-salt',
+  key: 'your-key-encryption-passphrase',
+  keyVersion: 2, // defaults to 1
+  previousKey: 'the-passphrase-you-are-rotating-away-from',
+  audit: true, // log write/delete/rotate through the audit sink
+  auditReads: false, // reads too — noisy, off by default
 })
 await secrets.init()
 

package/skills/pikku-n8n-import/SKILL.md

@@ -35,16 +35,24 @@ missing dependency).
 ### 1 — Run the importer (do as much as possible, cheaply)
 
 ```bash
-pikku import n8n <export.json> [outDir]
+pikku import n8n <file> [--out <dir>]   # -o for short
 ```
 
+The output directory is an **option**, not a positional argument; omitted, it
+falls back to `scaffold.functionDir` from `pikku.config.json`, then cwd.
+
+`<file>` is one export, **or a directory** — the command reads every `.json` in
+it — and either form may hold a single workflow object, a bare array (`n8n
+export:workflow --all`), or a `{ workflows: [...] }` wrapper. All of those are
+flattened into one import per workflow, so there is no need to loop yourself.
+
 It writes `<slug>.graph.ts` (+ `.agent.ts` for AI workflows), `<slug>.addons.gen.ts`,
 a `<slug>.integrations.json` manifest, and one stub function per node it could not
-map. It **exits 1** on an un-importable input (a cross-workflow sub-workflow
-reference, a dynamic workflow target, a mid-flow `respondToWebhook`) with a
-`[reason] message` — relay that to the user; do not fake a partial scaffold.
-
-For a directory of exports, run it per file.
+map. An un-importable workflow (a cross-workflow sub-workflow reference, a dynamic
+workflow target, a mid-flow `respondToWebhook`) is reported as `[reason] message`
+and **skipped** — nothing partial is written for it. Across a batch the others
+still import; the command exits 1 at the end if any failed, so read the log rather
+than the exit code to know what landed. Relay every skipped workflow to the user.
 
 ### 2 — Triage what it left