@pikku/skills 0.12.39 → 0.12.40

package/package.json

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

package/skills/pikku-agent/references/agents.md

@@ -102,6 +102,13 @@ await rpc.agent.resume(runId, { toolCallId, approved })
 await rpc.agent.interrupt(runId, 'user' | 'speech' | 'timeout')
 ```
 
+`rpc.agent` is built from a factory that `@pikku/core/agent` registers when it
+is imported, so the agent runtime lands only in a deployment unit that actually
+holds an agent. A unit that declares one imports it through its own agent file
+and needs nothing extra; a unit that reaches `rpc.agent` while holding no agent
+throws `Agent runtime not available` rather than silently paying ~52 KB for a
+runtime it never uses.
+
 `context` is a string injected into the system prompt for this request only —
 use it for upfront state (current org, project, deployment) so the agent stops
 asking the user for identifiers it could have been handed.

package/skills/pikku-build/SKILL.md

@@ -115,21 +115,17 @@ generated functions through `ref()`.
 
   A person who has to go hunting for the port assumes the app did not start.
 
-## Keep a BUILD-REPORT.md
+## Report what pikku got wrong, as it happens
 
 Whenever pikku or a skill costs you time — a command that failed on a fresh
 tree, a skill that described a flag the CLI does not have, generated code you
-had to fix by hand — add an entry to `BUILD-REPORT.md` at the repo root as it
-happens: what you ran, what you expected, what happened, and the workaround.
-Leave out secrets, tokens and customer data.
-
-At hand-over, show the file and ask the user whether to send it. Only with
-their okay, send each entry with `pikku fabric report --stdin` (JSON on stdin;
-`"kind": "product"` when pikku behaved wrongly, `"kind": "harness"` with
-`"skill"` and `"passage"` when a skill misled you). The `pikku-report` skill
-has the fields. When the CLI is not signed in to Fabric, the report is queued
-locally rather than sent: say so, and that `pikku fabric findings flush` sends
-the queue once they sign in. Do not retry or file it twice.
+had to fix by hand — file it then with `pikku fabric report --stdin`. The
+`pikku-report` skill has the fields. Leave out secrets, tokens and customer data.
+
+Findings are held until hand-over. The last thing in the hand-over, after the
+app runs (and is deployed, if they chose to), is `pikku fabric report`: if it
+lists findings and asks, ask the user — Yes, No, Always or Never — and run it
+again with `--consent <answer>`. If it says reporting is off, do not ask.
 
 ## Who you are talking to
 

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

@@ -515,9 +515,11 @@ Rules that are not optional:
 - Surface errors. No empty catch, no swallowed promise. If a mutation can fail,
   render the failure inline next to the control that triggered it — not a toast.
 - An exposed function with no session and no permission is reachable by anyone
-  over `POST /rpc/:rpcName` (PKU574). Either gate it or drop `expose: true`.
+  over `POST /rpc/:rpcName` (PKU574). Either gate it, drop `expose: true`, or —
+  when public is the point — write `auth: false` on it to say so.
 - A public, signed-out read (a homepage's programme, a price list) is a
-  `pikkuSessionlessFunc`. `pikkuFunc` with `auth: false` still answers
+  `pikkuSessionlessFunc` with `auth: false` written out, which is what keeps
+  PKU574 quiet for it. `pikkuFunc` with `auth: false` still answers
   `MissingSessionError` over `/rpc` to a caller with no session.
 - Better Auth already owns the `user`, `session`, `account` and `verification`
   tables. A domain table with one of those names — a class _session_, a drop-in

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

@@ -259,14 +259,14 @@ Do not push without explicit confirmation. Do not merge.
 When pikku itself is what cost you time — a wrong generated type, a check that
 passed when it should not, a skill that misled you — file it with `pikku fabric
 report`. The `pikku-report` skill owns the ladder, the two kinds, the JSON-on-
-stdin form and the local spool; read it before filing.
+stdin form and asking the user at hand-over; read it before filing.
 
-Reporting at all is permitted here (see **Hard constraints**) and is the one
-network call a build may make. Nothing is written to the repo. Never patch pikku
+Filing is permitted here (see **Hard constraints**), and sending what was filed
+is the one network call a build may make, once the user agrees. Nothing is
+written to the repo. Never patch pikku
 itself — not `node_modules`, not a linked checkout — work around it in the app,
 report it, and let the fix happen once.
 
-
 ## Hard constraints
 
 The skill's `allowed-tools` does **not** permit:

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

@@ -135,7 +135,7 @@ than they save:
   type params, never an inline return type. The schema is the type.
 - Permission checks go in the `permissions` field, never the function body. An
   exposed function with no session and no permission is reachable by anyone over
-  `POST /rpc/:rpcName` (PKU574).
+  `POST /rpc/:rpcName` (PKU574). If that is the point, write `auth: false` on it.
 - No `process.env` inside a function — use the injected `variables` / `secrets`
   services.
 - A `z.date()` **input** arrives over RPC as an ISO string, not a `Date`.

package/skills/pikku-report/SKILL.md

@@ -3,12 +3,11 @@ name: pikku-report
 description: >-
   Use when pikku itself cost you time — wrong generated types, a check that passes when it
   should not, output that is quietly wrong, a skill that misled you — or when the user asks you
-  to report a framework bug, file a finding, or look at what is queued. Owns `pikku fabric
-  report` (a finding is about pikku, not the app), the product-vs-harness kinds, the
-  workaround-first ladder, and the local findings spool. TRIGGER when: the framework fought you,
+  to report a framework bug or file a finding. Owns `pikku fabric report` (a finding is about
+  pikku, not the app), the product-vs-harness kinds, the workaround-first ladder, and asking the
+  user at hand-over whether to send what was filed. TRIGGER when: the framework fought you,
   codegen produced something broken, a skill told you to run something that does not exist, the
-  user says "report this to pikku" / "file a finding" / "check the findings queue", or a finding
-  was queued and never sent. DO NOT TRIGGER when: the bug is in the app you are building (fix it
+  user says "report this to pikku" / "file a finding", or you are handing over a build. DO NOT TRIGGER when: the bug is in the app you are building (fix it
   there), or you are tempted to patch pikku's source (never do that from an app).
 installGroups: [core]
 ---
@@ -19,9 +18,9 @@ A finding is about **pikku**, not about the app you are building. It is how the
 framework learns what cost its users time — the bug, the misleading skill, the
 silence where a check should have complained.
 
-Nothing is written to the repository. The terminal receipt shows exactly what
-left your machine, and the command is spelled `pikku fabric report` — there is
-no top-level report command.
+File each one the moment it happens. Nothing leaves the machine until the user
+says so at hand-over, and nothing is written to the repository. The command is
+spelled `pikku fabric report` — there is no top-level report command.
 
 ## Report at the moment it happens
 
@@ -62,7 +61,7 @@ baseline noise that was already failing before you started.
 - `--kind harness` — a skill misled you: it told you to run something that does
   not exist, described a flag that is spelled differently, or contradicted what
   the CLI actually did. Pass `--skill <name>` and `--passage "<the line or
-  section>"`. This is the most useful kind to file, because it is fixable
+section>"`. This is the most useful kind to file, because it is fixable
   immediately — so file it even when the cost was small.
 
 ## The command
@@ -102,24 +101,44 @@ before anything is sent:
 Add whichever of these you actually have: `error` (the error's message line,
 verbatim), `repro` (the shortest way to reach it again), `proposal`, `area`,
 `surface`, `cost` (measured if you measured it — "98s vs 20s steady" ranks;
-"slow" does not), `run` (an id shared by every finding from this build),
-`deployTarget`.
+"slow" does not), `deployTarget`.
 
 Versions, platform and package manager are read off the installed tree for you.
 Do not pass them and do not ask the user for them.
 
-## When it cannot send
+## At hand-over
 
-Reporting never fails a build. A finding that cannot be sent — logged out, or
-fabric unreachable — is held on the machine and goes out with the next report
-that succeeds, so nothing you file is lost:
+Filing holds the finding on the machine, tied to this build by a run id the CLI
+makes for the checkout. The terminal says `held until hand-over`; carry on.
 
-- `pikku fabric findings list` shows what is queued.
-- `pikku fabric findings flush` sends everything queued.
-- `pikku fabric findings clear` discards it.
+The last thing in the hand-over — after the app runs, and is deployed if they
+chose to — is:
 
-If the terminal says the finding was queued, carry on with what you were doing.
-Do not try to fix the send, and do not file the same thing again.
+```bash
+pikku fabric report
+```
+
+With no finding, it lists what this build filed. What happens next depends on
+what the user said before, which the CLI keeps on their machine:
+
+- **Always** — every finding was sent the moment you filed it. Tell the user in
+  one line.
+- **Never** — nothing was kept. Do not ask and do not mention it.
+- **Nothing saved** — show the user the titles and ask once: _"Send these to the
+  Pikku team so they can fix them?"_ — **Yes**, **No**, **Always** or
+  **Never**. Then run it again with their answer:
+
+  ```bash
+  pikku fabric report --consent yes|no|always|never
+  ```
+
+  Yes sends and No discards what is held now; Always and Never are saved and the
+  question is not asked again. If nobody answers, leave them held and say that
+  `pikku fabric report` sends them later.
+
+Findings are anonymous: no account, no project. The receipt printed when you
+filed each one is exactly what leaves the machine. A send that fails keeps what
+was not sent; do not retry or file it twice.
 
 ## Never fix pikku itself
 

package/skills/pikku-workflow/SKILL.md

@@ -159,6 +159,9 @@ export const processOrder = pikkuWorkflowFunc({
 // RPC step — run a registered Pikku function as a step (opts: retries, retryDelay, description)
 const result = await workflow.do('Step name', 'rpcFunctionName', { ...data }, { retries: 3, retryDelay: '1s' })
 
+// Sub-workflow step — name another workflow instead of an RPC (see "Sub-workflows")
+const onboarded = await workflow.do('Onboard', 'onboardUserWorkflow', { userId })
+
 // Inline closure step — immediate execution, cached for replay
 const msg = await workflow.do('Generate', async () => `Welcome, ${data.email}!`)
 
@@ -277,9 +280,59 @@ const users = await Promise.all(
 )
 ```
 
+### Sub-workflows
+
+A step whose second argument names a **workflow** rather than an RPC starts that
+workflow as a child run and resolves to its output. There is no separate API —
+it is the same `workflow.do`, and the generated `TypedWorkflow` has an overload
+keyed on `FlattenedWorkflowMap`, so the child's input and output are type-checked
+exactly like an RPC step's.
+
+```typescript
+export const signupWorkflow = pikkuWorkflowFunc<
+  { email: string },
+  { userId: string }
+>({
+  func: async (_services, data, { workflow }) => {
+    const user = await workflow.do('Create user', 'createUser', data)
+    // runs onboardUserWorkflow as a child run; awaits its output
+    await workflow.do('Onboard', 'onboardUserWorkflow', { userId: user.id })
+    await workflow.do('Send welcome', 'sendWelcomeEmail', { userId: user.id })
+    return { userId: user.id }
+  },
+})
+```
+
+How the child runs:
+
+- **It is its own run.** It gets its own `runId`, its own steps and its own
+  history; the parent step records it as `childRunId` and the child's wire
+  carries `parentRunId`/`parentStepId`. Inspect the child's steps on the child
+  run, not the parent.
+- **Identity is inherited.** The child's wire copies the parent's
+  `pikkuUserId`, so the child runs as whoever started the parent.
+- **Inline vs queued follows the deployment.** Without a `queueService` the
+  child runs inline and the parent step returns its output directly. With one,
+  the child is queued, the parent parks on that step, and the child's
+  completion writes the parent step's result and resumes the parent.
+- **Failure propagates.** A child that fails or is cancelled fails the parent
+  step (`'Sub-workflow failed'` / `'Sub-workflow was cancelled'` when the child
+  left no message). Inline, the step's `retries` start a fresh child run per
+  attempt; queued, the child's failure lands on the parent step once and is
+  not retried — put retries on the child's own steps instead.
+
+Use a sub-workflow when the child is a real orchestration you also start on
+its own, or reuse from several parents. A child that would be a single
+`workflow.do` is a function — call the RPC directly (see the single-RPC rule
+above).
+
+To start a workflow **without waiting** for it, that is not a sub-workflow:
+have an RPC step call `rpc.startWorkflow(name, input)`, which returns
+`{ runId }` immediately, and the new run has no parent link.
+
 ### Graph workflow (DAG)
 
-`pikkuWorkflowGraph` derives types from the RPC map — no explicit `input`/`output`. Nodes map `nodeName → Pikku function name`; `config.<node>.next` lists nodes to run after it (in parallel); `config.<node>.input: (ref) => ...` transforms input using refs to prior node outputs.
+`pikkuWorkflowGraph` derives types from the RPC map — no explicit `input`/`output`. Nodes map `nodeName → Pikku function name` — or a workflow name, which runs that workflow as a sub-workflow node; `config.<node>.next` lists nodes to run after it (in parallel); `config.<node>.input: (ref) => ...` transforms input using refs to prior node outputs.
 
 ```typescript
 import { pikkuWorkflowGraph } from '#pikku/workflow/pikku-workflow-types.gen.js'