@pikku/skills 0.12.64 → 0.12.67

package/package.json

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

package/skills/pikku-addon/SKILL.md

@@ -200,7 +200,10 @@ npx pikku new addon stripe --display-name Stripe --category Payments --dir addon
 ```
 
 **Handed an OpenAPI or Swagger spec?** Don't hand-write the functions —
-`pikku new addon <name> --openapi <spec>` generates one function per operation,
+`pikku new addon <name> --openapi <spec>` generates one function per operation
+(`<spec>` is a path, a URL, or a registry catalogue name such as
+`amazonaws.com:applicationcostprofiler`; inside an app,
+`pikku addons add <catalogue-name>` does the same and picks `--auth` for you),
 with its schemas, service and credential. Read `references/openapi.md`.
 
 This generates `package.json` (exports `.pikku/*` + `dist/`), `pikku.config.json` (`addon: true`), `tsconfig.json` (`#pikku` path mapping), `src/services.ts`, `src/functions/`, and `types/application-types.d.ts`. For the full file contents/exports you rarely hand-edit, read `references/addon-package-manifest.md`.
@@ -378,7 +381,7 @@ At runtime an unmapped alias, or the wired name called directly, throws
 ### Studio screens
 
 An addon declares the screens it adds to Pikku Studio with `definePlugin`, in
-`src/screens.ts` (`pikku new addon-ui <name>` scaffolds one). It replaces
+`src/screens.ts` (`pikku new addon <name> --ui` scaffolds one). It replaces
 `defineScreens`, which no longer exists.
 
 ```typescript
@@ -421,18 +424,43 @@ export default definePlugin({
   addons only; Studio enforces that). `layout: 'bare'` renders without the shell.
 - Titles are message keys in the addon's `messages/{locale}.json`, found by
   convention next to its `package.json`; there is no field for them.
+- `agent: 'name'` makes that agent answer in Studio's chat panel (a second tab
+  beside the general chat) while the screen is open. It resolves to
+  `agents/<name>.md` at the addon's package root: the agent's instructions,
+  which name the skills it follows (plain folders `skills/<name>/SKILL.md`).
+  `agent: 'studio:<name>'` instead picks an agent Studio ships; `pikku all` only
+  checks the format and looks up no file.
+  The file starts with frontmatter whose `title` and `description` are message
+  keys in `messages/en.json`. The name matches `/^[a-z][a-z0-9-]*$/`.
+- `defaultChat: false` hides Studio's general Chat tab on the screen, so the
+  screen's `agent` is its only chat (with no `agent`, the screen has no chat).
+  It defaults to `true`, must be a boolean literal, and is only written to the
+  metadata when declared.
+- `agents/` and `skills/` ship in the published package. If `package.json` has a
+  `files` list, it must include them (`"files": ["dist", "messages", "agents",
+  "skills"]`, which `pikku new addon <name> --ui` scaffolds). A root glob such as
+  `**/*.md` does not count, so list the folder as well. With no `files` field
+  nothing is checked, so make sure `.npmignore`, or `.gitignore` when there is no
+  `.npmignore`, does not exclude them.
+- `package.json` carries a `studio` block, `{ "addon": "<name>", "ui": "./src",
+  "messages": "./messages/{locale}.json" }`. Studio only links (and loads the
+  agents and skills of) a package with `studio.addon`; it is the addon's short
+  name, the `<addon>` in an agent's scope `agent:<addon>:<name>`. The `--ui`
+  scaffold writes it with `addon` set to the addon's name.
 - `scopes` only hide the screen. The addon's functions must enforce the same
   scopes.
 
 The inspector reads every field statically, so each must be a literal.
 `pikku all` fails on:
 
-| Code   | When                                                         |
-| ------ | ------------------------------------------------------------ |
-| PKU345 | a field is not a literal (variable, call, spread, bad value) |
-| PKU357 | two screens of the addon use the same path                   |
-| PKU358 | a title key is missing from `messages/en.json`               |
-| PKU359 | `nav.badge` names no function of the addon                   |
+| Code   | When                                                                                                 |
+| ------ | ---------------------------------------------------------------------------------------------------- |
+| PKU345 | a field is not a literal (variable, call, spread, bad value)                                         |
+| PKU357 | two screens of the addon use the same path                                                           |
+| PKU358 | a title or agent frontmatter key is missing from `messages/en.json`                                  |
+| PKU359 | `nav.badge` names no function of the addon                                                           |
+| PKU365 | `agent` is neither a name nor `studio:<name>`, or a name has no non-empty `agents/<name>.md`, or no frontmatter `title` and `description` |
+| PKU366 | `package.json` `files` leaves out `agents/` while a screen names a valid (no PKU365) non-`studio:` agent, or `skills/` while the addon has a `skills/<name>/SKILL.md` |
 
 A key missing from another locale's catalog is a warning.
 

package/skills/pikku-addon/references/openapi.md

@@ -11,7 +11,8 @@
 - 6 — Check the spec against the real API
 - Then
 
-When you are handed an OpenAPI or Swagger spec — a file, or a URL to one — the
+When you are handed an OpenAPI or Swagger spec — a file, a URL to one, or the
+name of one in the registry's catalogue (`https://www.pikku.dev/openapis`) — the
 API it describes becomes an addon: one function per operation, each with its
 input and output schemas, behind one service that makes the HTTP calls. Say so
 before starting ("This is an OpenAPI spec — I'll turn it into an addon first"),
@@ -26,7 +27,23 @@ A JSON or YAML document with a top-level `openapi` key (3.x) or `swagger` key
 
 ## 1 — Look at the spec first
 
-`--openapi` takes a path or a URL. A spec published only to signed-in callers
+`--openapi` takes a path, a URL, or a catalogue name such as
+`amazonaws.com:applicationcostprofiler`. A name is anything that is neither a
+URL, a path, nor a `.json`/`.yaml` file; it is looked up in the registry
+(`--registry`, else `pikku.config.json`'s `registry`, else
+`https://api.pikkustudio.app`) and generated from the entry's spec URL. A name
+the registry does not know is refused before anything is written. On the
+website the page URL is a slug (`amazonaws-com-applicationcostprofiler`); the
+name to pass is the one the page's command shows, with its `.` and `:`.
+
+For a catalogue entry inside an app, the short form is
+`pikku addons add amazonaws.com:applicationcostprofiler`. It names the addon
+after the entry (`amazonaws-applicationcostprofiler`) and takes `--auth` from
+what the registry records: `none` for a public API, `user` for OAuth or a key
+each user brings, `shared` for a key the app holds, and `user` when the registry
+does not know. It prints the mode it picked; pass `--auth` to override it.
+
+A spec published only to signed-in callers
 takes the key the way the API reads it: `--openapi-header "NAME: value"`
 (repeatable), or in the URL's query string when the API reads it there
 (Dolibarr's explorer takes `?DOLAPIKEY=`). A 401 while fetching says which.
@@ -40,7 +57,7 @@ Keep a copy in `specs/` as the record of what the addon was generated from.
 ## 2 — Generate, from the app's root
 
 ```bash
-bunx --bun pikku new addon <name> --openapi <path-or-url>
+bunx --bun pikku new addon <name> --openapi <path-url-or-catalogue-name>
 ```
 
 One command. Inside an app it writes `packages/addon-<name>` as

package/skills/pikku-deploy/references/cloudflare.md

@@ -71,8 +71,8 @@ CF `1101`. It also stashes the env via `setCloudflareEnv`, which
 - A `GET` with `Upgrade: websocket` is routed to the hibernation server. Without
   one passed in it answers **426**, so a channel worker that forgets the second
   argument fails every upgrade while plain HTTP keeps working.
-- `CF-Ray` becomes the traceId when present, so a Cloudflare trace and a Pikku
-  trace line up without extra wiring.
+- `CF-Ray` does not set the traceId: it is not a W3C trace id. Core starts a new
+  trace, or continues a verified mesh caller's.
 - `options.exposeErrors` defaults to **`false`** — error detail is withheld from
   responses unless you opt in.
 

package/skills/pikku-deploy/references/lambda.md

@@ -92,7 +92,7 @@ export const scheduled: ScheduledHandler = async (event) => {
 ```
 
 `runLambdaScheduled` runs **every** scheduled task registered in the bundle,
-each with its own `cron-<uuid>` traceId, and logs rather than rethrows a task
+each on its own new trace, and logs rather than rethrows a task
 failure — so one bad task cannot fail the invocation or stop the others. The
 event itself is ignored; which tasks run is decided by what the unit bundled,
 not by which EventBridge rule fired.

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

@@ -243,3 +243,9 @@ wireChannel({
   },
 })
 ```
+
+## Tracing
+
+A channel has one trace per connection: `onConnect`, `onDisconnect`, each message and each `channel.remote` call are spans in it, read from `wire.trace`. A client's `traceparent` is ignored. A serverless channel keeps the trace in `ChannelStore`, so a custom store must return the `traceparent` it was added with.
+
+A reverse RPC carries `traceparent`, which `createChannelRPCResponder` ignores unless you pass `trustInboundTraceparent: true`. Only pass it for a peer you have authenticated.

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

@@ -81,6 +81,34 @@ Options:
 }
 ```
 
+### Tracing
+
+A job continues the trace of the function that enqueued it. Inside a function,
+`queueService.add` stamps `JobOptions.traceparent` from the wire, and the worker
+gets the same trace id in a new span on `wire.trace`. Pass `traceparent` yourself
+only to override it.
+
+Nothing stamps a job added from a singleton service, or from a queue service
+captured at start-up. That job starts a new trace. Pass `traceparent:
+rpc.traceparent` when you need to carry it through one of those.
+
+A custom `QueueService` must carry `traceparent` and set it on `QueueJob`. A
+missing or invalid one starts a new trace; it is never an error.
+
+### Running a job as a user
+
+Pass `pikkuUserId` in the job options and wrap the queue service in
+`SignedQueueService`. The worker then runs with `wire.pikkuUserId` and the user's
+stored session, on every adapter. An unsigned or forged id is dropped and the job
+runs with neither.
+
+Never take the id from client input. If the session has gone by the time the job
+runs, `wire.pikkuUserId` is still set and `wire.session` is not.
+
+A custom `QueueService` must carry `pikkuUserId` next to the payload and set it on
+`QueueJob`, leaving `job.data` as it was. Check it with
+`defineQueueIdentityTransportTests` from `@pikku/core/testing`.
+
 ## Usage Patterns
 
 ### Basic Queue Worker

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

@@ -63,6 +63,12 @@ will catch a skip and report it as a failure. If your middleware distinguishes
 success from failure, let the skip pass through rather than logging it as an
 error.
 
+### Tracing
+
+Each cron firing starts a new trace, on `wire.trace`. A delayed call fires on the
+trace passed as the last argument of `scheduleRPC`: a workflow sleep passes the
+run's, and nothing passes it for you elsewhere, so use `wire.rpc.traceparent`.
+
 ### Cron Expression Reference
 
 ```

package/skills/pikku-workflow/SKILL.md

@@ -371,6 +371,19 @@ export const userOnboarding = pikkuWorkflowGraph({
 })
 ```
 
+### Tracing
+
+A run owns one trace, stored on `run.wire.traceparent`. It starts from the wire or
+the caller's `rpc`; a start with neither, such as a trigger, gets a new trace. Every
+step, retry, sleep wake-up, resume, child workflow, recovery and job a step
+enqueues stays on it. Each hop is a new span whose parent is the span that started
+the run. An agent's tool calls are the exception: they are not on the run's trace
+yet.
+
+### Restarts
+
+A run survives a crash or deploy. `pikku dev` and `pikku serve` recover it at startup and every 30s: a sleep keeps its deadline, and a step caught in flight runs again as a new attempt. A settled step never reruns. So a step can run more than once: make its side effects idempotent on `workflowStep.invocationId`, which stays the same across attempts. A step with `retries: 0` caught in flight fails instead. Any other host calls `workflowService.startRecovery()` once the queue is consuming. Set `workflow.recovery: false` to turn it off.
+
 ## File conventions
 
 - Place workflows in `packages/functions/src/wirings/*.workflow.ts`; export the variable so the inspector discovers it (no manual registration).