@pikku/skills 0.12.60 → 0.12.61

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/skills",
-  "version": "0.12.60",
+  "version": "0.12.61",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",

package/skills/pikku-addon/SKILL.md

@@ -49,7 +49,7 @@ wireAddon({
   rpcEndpoint?: string,            // Optional remote RPC endpoint for distributed execution
   auth?: boolean,                  // Require a session for every function in the addon
   mcp?: boolean | string[],        // true: every function the addon declared mcp: true; a list: the tools this app offers, typed against the addon's function names
-  expose?: boolean | string[],     // what rpc.exposed / POST /rpc may reach: unset/true = the addon's own expose: true, false = none, a list = exactly those (typed; PKU343 on unknown names)
+  expose?: boolean | string[],     // opt-in: what rpc.exposed / POST /rpc may reach. true = every function the addon declared expose: true, a list = those of them named (typed; PKU343 on unknown or undeclared names), unset/false = none
   tags?: string[],                 // Tags applied to all addon functions
   scopes?: string[],               // Required of every function, on top of its own
   secretOverrides?: Record<string, string>,      // Remap secret names (and grant them)
@@ -279,6 +279,45 @@ everything else. Leave it out and the addon installs fine and fails to typecheck
 in every app that depends on it, which is what `pikku validate` is there to
 catch before you publish.
 
+### Remote functions and the SDK
+
+A `remote: true` function is called over the wire by apps that use
+`wireRemoteAddon`. Those apps build against the addon's SDK, not its source, so
+**a remote function's input and output must be exported zod schemas**. If it
+uses generics (`pikkuSessionlessFunc<In, Out>`) or returns a type declared in
+`src/`, codegen fails with PKU922. Functions that are not remote can keep their
+generics.
+
+```typescript
+// src/functions/listNotes.schemas.ts
+import { z } from 'zod'
+
+export const NoteRows = z.array(z.object({ id: z.string(), body: z.string() }))
+```
+
+```typescript
+// src/functions/listNotes.function.ts
+import { pikkuSessionlessFunc } from '#pikku/addon/function'
+import { NoteRows } from './listNotes.schemas.js'
+
+export const listNotes = pikkuSessionlessFunc({
+  output: NoteRows,
+  func: async ({ kysely }) =>
+    kysely.selectFrom('notes').select(['id', 'body']).execute(),
+  remote: true,
+})
+```
+
+```bash
+yarn pikku all            # also writes .pikku/sdk/ + <scope>-<name>-<version>.sdk.tgz
+yarn pikku versions check # fails on a remote contract changed without a new version
+```
+
+In an addon, `pikku all` packs the SDK on every run, at the package.json
+version. The SDK carries only the remote RPCs, the `expose: true` workflows and
+the types they reach. Changing a published `remote: true` contract needs a new
+`version` on the function, which `pikku versions check` enforces.
+
 ### Database tables
 
 An addon may **ship** tables. It must never **create** them: it runs inside the
@@ -361,6 +400,13 @@ covered, and writes only the delta after an addon upgrade. An addon wired with
 `wireRemoteAddon` contributes no schema at all: its tables belong to the
 deployment that runs its functions.
 
+A `wireRemoteAddon` whose `package` carries a range (`'@scope/name@^1.4.0'`)
+is not installed at all: `pikku all` downloads its SDK into
+`.pikku/remote` and pins it in `pikku-addons.lock` (commit the lock). If
+codegen reports PKU338 for one, run `pikku all`, not an install; to move
+to a newer SDK, edit the range by hand (`pikku update` prints the file:line
+and the new literal; it never rewrites source), then run `pikku all`.
+
 ### Call via RPC
 
 ```typescript
@@ -381,9 +427,10 @@ and the frontend calls `rpc.invoke('todos:listTodos', …)` (over HTTP,
 Use `ref('todos:listTodos')` on an HTTP or MCP wiring only when the addon needs
 a route of its own. Don't write an app function that calls `rpc.invoke` and
 returns the result unchanged: it's a second name and a second schema for the
-same thing, and it drifts. `expose: true` exposes only what the addon itself
-declared `expose: true` — an OpenAPI-generated addon declares none, so list
-the names.
+same thing, and it drifts. Nothing in an addon is reachable over `/rpc` until
+the wiring opts in, and it can only open what the addon itself declared
+`expose: true` — an OpenAPI-generated addon declares every operation, so list
+the ones the frontend needs.
 
 Write your own function when the app needs the data narrowed, typed, or
 combined (a flag the upstream sends as `"0"`, a total summed from several

package/skills/pikku-build/references/platform.md

@@ -60,7 +60,7 @@ Most surfaces are switched on by the CLI rather than hand-wired:
 bunx --bun pikku enable workflow      # workflow workers
 bunx --bun pikku enable agent         # public agent endpoints
 bunx --bun pikku enable events        # realtime events channel + SSE stream
-bunx --bun pikku enable remote-rpc    # internal RPC queue worker + HTTP endpoint
+bunx --bun pikku enable mesh-rpc      # mesh RPC queue worker + HTTP endpoint
 bunx --bun pikku enable webhook       # outgoing webhook delivery queue worker
 bunx --bun pikku enable scenarios     # scenario instrumentation
 bunx --bun pikku enable rpc           # public RPC endpoint

package/skills/pikku-build/references/ship.md

@@ -74,7 +74,7 @@ builds anyway (`config`, `logger`, `variables`, `schema`, `secrets`, and the
 per-request `rpc`/`mcp`/`channel`/`userSession`). Units are named for that set —
 `svc-todo-store`, `svc-event-hub-todo-store`, `svc-base` for functions needing
 nothing else — and each records it as `servicesKey` in the manifest. On the
-`templates/functions` app it turns 44 units into 10.
+`recipes/functions` app it turns 44 units into 10.
 
 The deploy target is part of the key, so a `server` unit is named `-server` and
 can never merge with its serverless twin. That is what keeps `services` from

package/skills/pikku-wiring/references/rpc.md

@@ -13,14 +13,14 @@
 | Method                           | Purpose                                   |
 | -------------------------------- | ----------------------------------------- |
 | `rpc.invoke(name, data)`         | Internal call to any wired function       |
-| `rpc.remote(name, data)`         | Remote call via DeploymentService         |
+| `rpc.mesh(name, data)`           | Mesh call via DeploymentService           |
 | `rpc.exposed(name, data)`        | Call functions marked with `expose: true` |
 | `rpc.startWorkflow(name, input)` | Start a workflow (see `pikku-workflow`)   |
 | `rpc.agent.run/stream(...)`      | Run an AI agent (see `pikku-agent`)       |
 | `rpc.agent.resume/approve(...)`  | Answer a tool-approval interrupt          |
 | `rpc.agent.interrupt(runId)`     | Stop an in-flight run                     |
 
-`rpc.invoke`, `rpc.remote` and `rpc.startWorkflow` are typed off the generated
+`rpc.invoke`, `rpc.mesh` and `rpc.startWorkflow` are typed off the generated
 RPC map, so the name and the payload are checked. `rpc.exposed` is deliberately
 `(name: string, data: any) => Promise<any>` — it exists to dispatch a name that
 arrived from outside, which by definition cannot be checked at compile time.