@pikku/skills 0.12.66 → 0.12.67

package/package.json

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

package/skills/pikku-addon/SKILL.md

@@ -381,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
@@ -432,6 +432,21 @@ export default definePlugin({
   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.
 
@@ -445,6 +460,7 @@ The inspector reads every field statically, so each must be a literal.
 | 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-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).