@llblab/pi-actors 0.45.1 → 0.46.1

package/AGENTS.md

@@ -36,11 +36,11 @@ Pi host
      -> lib/observability.ts          terminal + Trace-attention observation
      -> lib/inspector*.ts             owner-filtered actor-instance inspection
      -> scripts/*.mjs                 process/service entrypoints
-     -> recipes/*.json                packaged Recipe library
+     -> skills/*/recipes/*            Skill-owned Recipe components
      -> skills/* + docs/*             agent and human guidance
 ```
 
-`index.ts` wires Pi ports and must not own domain behavior. Keep the local TypeScript import graph acyclic.
+`index.ts` wires Pi ports and must not own domain behavior. Keep the local TypeScript import graph acyclic. For architecture-affecting work, load and follow `.agents/skills/domain-dag/SKILL.md`; its validator is local agent tooling, not an npm, CI, or release gate.
 
 ## Key Domains
 
@@ -58,17 +58,20 @@ Pi host
 - `observability.ts`, `run-ui-runtime.ts`: Trace attention, terminal reconciliation, and Pi follow-up delivery.
 - automatic draft/tool review domains: structurally redacted model review, journaled mutation, lineage, recovery, and explicit retry/reset safety.
 
-Scripts remain self-contained when no non-script consumer justifies a TypeScript domain. Command-template script leaves infer `.js`/`.mjs` in order through Node, Bun, or `deno run` and `.sh` through Bash without shell evaluation. Helper-backed packaged Recipes self-locate their installed package root while explicit caller values remain authoritative. Recipes stay optional, composable, policy-light, and caller-configurable.
+The bundled Skill Recipe dependency DAG is `artifacts → actors, swarm`, `media → artifacts`, and `project-work → actors, artifacts, swarm`; `actors`, `swarm`, and `recipe-memory` have no cross-Skill Recipe dependencies.
+
+Scripts remain self-contained when no non-script consumer justifies a TypeScript domain. Command-template script leaves infer `.js`/`.mjs` in order through Node, Bun, or `deno run` and `.sh` through Bash without shell evaluation. Helper-backed Skill Recipes self-locate through runtime-owned `{skill_dir}`. Recipes stay optional, composable, policy-light, and caller-configurable.
 
 ## Operating Principles
 
 ### Recipe
 
+- Skill Recipe identity is `<active Skill name>/<Recipe filename stem>`; Recipe files have no top-level `name`. `SKILL.md` `name` is Pi host metadata matching the Skill directory, not a second pi-actors identity field.
 - Recipe files may define args/defaults, imports, artifacts, command-template flags, and `control`.
 - Declare actor-local actions only when a long-lived process implements them.
 - Actions are lowercase, unique, and cannot use runtime-reserved lifecycle names.
 - Removed communication-plane metadata fails explicitly; never translate it.
-- User Recipes shadow packaged definitions; invalid shadowing blocks fallback.
+- User Recipes are discovered only from the persistent user registry; Skill Recipes are exact components outside tool discovery. Explicit entry paths resolve from invocation `cwd`; relative imports resolve from their importing file.
 - Files over 1 MiB, import depth over 32, and import cycles fail closed.
 
 ### Trace
@@ -136,11 +139,10 @@ When a deferred Run result gates the next step, wait for its terminal follow-up.
 ## Documentation and Release Discipline
 
 - Keep published text portable: use `~`, `<repo>`, or relative paths.
-- Keep executable JavaScript and TypeScript blocks compact: no blank lines inside function bodies or control-flow blocks. Structural object, type, interface, class, and module bodies are exempt.
 - Update `skills/actors/SKILL.md` when durable operating mechanics change.
 - Keep `skills/swarm/SKILL.md` focused on multi-agent methodology rather than kernel internals.
-- Recipe `description` is optional because discovery supplies stable fallback tool copy; packaged Recipe QA must report zero diagnostics and zero release-blocking warnings without component boilerplate.
-- Before release run build, full tests, preservation tests, Recipe QA, Domain DAG validation, ABCd context validation, line-count gates, and release gates.
+- Recipe `description` is optional. Skill Recipe QA recursively validates direct filesystem-owned components and capability semantics with zero diagnostics or warnings; it does not enforce aesthetics or architecture policy.
+- Before release run the normal product validation and dependency audit. Use the project-local Domain DAG Skill during architecture-affecting development, not as publication automation.
 - `.github/workflows/release.yml` owns the immutable sequence reusable validation → npm Trusted Publisher publication/verification → GitHub Release convergence; follow [docs/releasing.md](docs/releasing.md).
 - Keep npm publication tokenless: use the exact npm Trusted Publisher binding and job-scoped OIDC permission, never a long-lived npm token or token fallback.
 - Until a stable version beyond `1.x`, prefer clean breaking simplification over compatibility aliases or renamed legacy abstractions.

package/BACKLOG.md

@@ -1,3 +1,585 @@
 # Project Backlog
 
+## 0.46.1 — Registration Truth
+
+**Base:** `0.46.0` at `4abe9b26525a57883446b1d897e9e1ddf6cacde5`  
+**Release type:** patch / contract repair  
+**Primary evidence:** `tests/registration-truth.test.ts`, distilled from `PI_ACTORS_RECIPE_UX_SESSION_REPORT.md`  
+**Release sentence:** every live pi-actors surface resolves user Recipes against the same session Skill context, registration validates the effective delegated contract before persistence, activation is truthfully observable, and unrelated invalid Skill components can no longer poison valid capability discovery.
+
+## Mission
+
+Repair the runtime seams exposed by the first real `0.46.0` Skill-Recipe authoring session before redesigning agent guidance.
+
+The intended operation was:
+
+```text
+maintained Skill Recipe
+    media/player
+        ↓ specialize
+persistent user tool
+    music_player
+        ↓ activate
+call in the same session
+```
+
+The session instead observed:
+
+```text
+spawn resolves media/player
+standalone QA resolves media/player
+register_tool cannot resolve media/player
+live registry rejects the wrapper
+one unrelated invalid Skill Recipe empties the catalog
+runtime-owned placeholders leak into the tool schema
+registry persistence is reported as registration success
+spawn is mistakenly used as proof of tool invocation
+```
+
+`0.46.1` owns the mechanical truth required for `0.47.0` agent-native UX.
+
+Do **not** solve these failures with more prose, compatibility aliases, copied Recipe contracts, helper paths, shell wrappers, or new orchestration concepts.
+
+The target transaction is:
+
+```text
+current session
+    ↓
+one RecipeResolutionContext
+    ↓
+resolve candidate
+    ↓
+derive effective Recipe/tool contract
+    ↓
+validate candidate
+    ↓
+persist
+    ↓
+registry admission
+    ↓
+host registration + active-tool reconciliation
+    ↓
+verify activation
+    ↓
+return truthful state
+```
+
+---
+
+# 1. Retained Canon
+
+The `0.46.0` capability model remains authoritative:
+
+```text
+Recipe --spawn--> Run
+Run = Recipe + Trace + Control
+```
+
+Public Run verbs remain:
+
+```text
+spawn
+message
+inspect
+```
+
+Persistent capability mutation remains:
+
+```text
+register_tool
+```
+
+Run views remain:
+
+```text
+recipe
+trace
+control
+```
+
+Recipe references remain exactly:
+
+```text
+<skill>/<recipe>
+explicit/path.json
+explicit/path.md
+```
+
+Skill Recipe identity remains:
+
+```text
+<active Skill identity>/<direct Recipe filename stem>
+```
+
+Retain:
+
+- six bundled Skill-owned capability packs;
+- flat Skill `recipes/` directories;
+- no root packaged Recipe library;
+- no `std:` or `skill:` prefixes;
+- no top-level file-backed Recipe `name`;
+- session-scoped active Skill identity;
+- runtime-owned `{recipe_dir}` and `{skill_dir}`;
+- bounded Trace and Control;
+- owner/generation/process fencing;
+- automatic review transactions;
+- secure npm publication;
+- project-local Domain DAG Skill outside CI/release.
+
+---
+
+# 2. Contract
+
+## 2.1 One live resolution environment
+
+Every operation that decides whether a Recipe can be used in the live session must consume the same immutable session resolution environment.
+
+Conceptually:
+
+```ts
+interface RecipeResolutionContext {
+  session_id: string;
+  cwd: string;
+  active_skills: ActiveSkillRecipeContext;
+  generation: string;
+}
+```
+
+The exact internal type may be smaller, but there must be one explicit owner and one semantic contract.
+
+The following must not invent independent active-Skill contexts:
+
+```text
+spawn
+register_tool candidate validation
+user Recipe registry admission
+user Recipe registry reload
+tool schema derivation
+inspect recipes
+inspect tool
+automatic review when resolving user wrappers
+live Recipe validation used by registration
+```
+
+Standalone package QA may still construct an offline package context, but it must be labeled as offline/package QA and may not be represented as proof of live registry admission.
+
+## 2.2 One user Recipe admission path
+
+A user Recipe under:
+
+```text
+~/.pi/agent/recipes/<name>.json
+```
+
+is an active agent tool only if one authoritative admission function can:
+
+1. parse the authored Recipe;
+2. resolve its delegation/import graph with the live `RecipeResolutionContext`;
+3. derive runtime-owned origins;
+4. derive the effective argument/type/default contract;
+5. classify async behavior;
+6. validate Control/artifacts;
+7. produce one `RegisteredTool` projection;
+8. produce bounded diagnostics on failure.
+
+`register_tool`, startup/reload discovery, and live revalidation must use this same admission contract.
+
+Do not maintain one path that creates a `RegisteredTool` directly from `register_tool` input and another path that later interprets the persisted Recipe differently.
+
+## 2.3 Registration is a state transition
+
+A successful registration response must distinguish at least:
+
+```text
+resolved
+validated
+persisted
+registry_active
+host_registered
+active_tool
+callable_now
+```
+
+These states may all become `true` in the healthy path, but they are not synonyms.
+
+Never return text that implies current-session invocation if the system cannot prove it.
+
+## 2.4 Effective contract before mutation
+
+A Recipe-backed tool must be validated from the **resolved effective contract**, not the shallow wrapper shape.
+
+For:
+
+```json
+{
+  "description": "Play local music.",
+  "defaults": {
+    "source": "~/Music/1MIX"
+  },
+  "template": "media/player"
+}
+```
+
+the effective tool contract inherits from `media/player`:
+
+```text
+async
+args
+arg types
+defaults
+artifacts
+Control
+runtime-owned origins
+```
+
+without copying those fields into the authored wrapper.
+
+The tool schema must contain only caller-owned inputs.
+
+## 2.5 Partial catalog, exact resolver
+
+The active Skill component catalog is diagnostic/discovery state.
+
+It must never be required for exact resolution of an unrelated valid component.
+
+An invalid:
+
+```text
+some-skill/bad-recipe
+```
+
+must not make:
+
+```text
+media/player
+```
+
+unresolvable merely because a catalog listing failed.
+
+---
+
+# 3. Runtime-Owned Inputs
+
+The following are runtime-owned and must never leak into caller-facing tool schemas merely because they occur in an effective Recipe template:
+
+```text
+recipe_dir
+skill_dir
+state_dir
+trace_file
+run_instance_id
+owner/session identity
+runtime state root
+```
+
+`run_id` remains an intentional caller-visible optional override for async tool invocation if the existing public contract retains it.
+
+The executor must inventory every runtime-injected placeholder and centralize ownership rather than maintaining ad hoc exclusion lists in unrelated schema code.
+
+Declared user args retain their actual types:
+
+```text
+string
+path
+bool
+int
+number
+enum
+array
+```
+
+A delegated Recipe may not degrade them all to strings.
+
+---
+
+# 4. Activation Truth
+
+`pi-actors` must determine what the Pi host can actually guarantee after dynamic `registerTool`.
+
+Preferred contract:
+
+```text
+register_tool returns callable_now=true
+→ host definition exists
+→ tool is in the current active tool set
+→ the next model step in the same session can call it
+```
+
+If the Pi host cannot guarantee that:
+
+```text
+register_tool returns callable_now=false
+activation=<exact boundary>
+```
+
+and all prompts/docs must say so.
+
+Do not infer model visibility from persistence or an extension-local map.
+
+The implementation must test the real Pi integration path, not only mocked registration callbacks.
+
+---
+
+# 5. Registration Atomicity
+
+For a new registration:
+
+```text
+candidate
+→ resolve/validate without mutation
+→ durable write
+→ authoritative registry admission
+→ host registration/activation
+→ verification
+```
+
+If failure occurs before persistence, no user Recipe file appears.
+
+If persistence succeeds but authoritative admission fails unexpectedly:
+
+- restore/delete the just-written candidate under the canonical mutation lock;
+- restore prior in-memory registry state;
+- report the exact failed phase;
+- do not leave an invalid file while returning generic success.
+
+For updates:
+
+- preserve the prior file bytes until replacement is known valid;
+- do not destroy a working tool because the replacement cannot resolve;
+- retain existing CAS/path/symlink/mutation safety.
+
+Host APIs that cannot unregister stale dynamic definitions must be explicitly accounted for. Validate as much as possible before host mutation.
+
+---
+
+# 6. Registry and Component Observability
+
+Existing:
+
+```text
+inspect target=recipes view=status
+inspect target=recipes view=summary
+inspect target=recipes view=doctor
+inspect target=tool:<name> view=status
+inspect target=tool:<name> view=schema
+```
+
+remain the public surfaces.
+
+Do not add a new `recipe:` target in this patch.
+
+Recipe registry inspection must expose bounded current state such as:
+
+```text
+registry_generation
+scanned_at
+resolution_generation
+watch_status
+user_recipe_count
+active_tool_count
+skill_component_count
+rejected_skill_component_count
+catalog_partial
+```
+
+Rejected Skill components must be reported individually with:
+
+```text
+skill
+stem if derivable
+portable file location
+reason
+```
+
+Use portable paths such as:
+
+```text
+~/.pi/agent/skills/...
+<pi-actors>/skills/...
+```
+
+rather than raw home-directory leakage.
+
+`inspect tool:<name> view=status` must expose activation state where it can be proven.
+
+---
+
+# 7. Fail-Soft Skill Component Discovery
+
+Refactor active Skill component listing so it returns valid entries and failures together.
+
+Conceptually:
+
+```ts
+interface SkillComponentInventory {
+  components: ActiveSkillRecipeComponent[];
+  rejected: SkillComponentDiagnostic[];
+  partial: boolean;
+}
+```
+
+Rules:
+
+- invalid top-level `Recipe.name` rejects that component;
+- nested Recipe files reject those files/that namespace as appropriate;
+- JSON/Markdown same-stem collision rejects that stem;
+- one duplicate active Skill identity may invalidate that Skill namespace;
+- unrelated Skill namespaces continue;
+- every rejection is bounded and diagnosable;
+- exact resolver remains independent and may resolve a valid exact component while catalog inventory is partial.
+
+Do not silently omit bad components.
+
+---
+
+# 8. Launch-Kind Truth
+
+Keep existing usage distinctions:
+
+```text
+tool
+spawn
+direct Recipe/foreground execution where applicable
+```
+
+At minimum:
+
+- `spawn` result/details expose `launch_kind: "spawn"`;
+- registered tool invocation evidence exposes `launch_kind: "tool"`;
+- `inspect tool` usage summary distinguishes tool calls from Recipe spawn calls;
+- no product copy describes `spawn recipe=<user-wrapper>` as invoking the registered tool.
+
+Do not add a second generic invocation mechanism just for testing.
+
+---
+
+# 9. Work Items
+
+## RGT-12 — Publish `0.46.1`
+
+**Goal:** ship the prepared registration-truth release before agent UX redesign.
+
+**State:** gated on explicit release intent and repository `ADMIN` authority.
+
+**Remaining:**
+
+- Run the existing guarded GitHub release flow for prepared version `0.46.1`.
+- Verify npm package identity/provenance and GitHub Release convergence.
+- After successful publication, reset this backlog to:
+
+```text
+# Project Backlog
+
 No open items.
+```
+
+**Unblocker:** the operator explicitly authorizes the `0.46.1` release and confirms `ADMIN` permission for this repository.
+
+**Dependencies:** none.
+
+---
+
+# 10. Dependency Graph
+
+```text
+RGT-12
+```
+
+Integration hotspots:
+
+```text
+lib/extension-runtime.ts
+lib/recipes-references.ts
+lib/recipes-discovery.ts
+lib/runtime.ts
+lib/registry.ts
+lib/tools-register.ts
+lib/tools-local.ts
+lib/tools-inspect.ts
+lib/schema.ts
+lib/recipes-usage.ts
+```
+
+Use one integration owner for resolution/admission semantics.
+
+---
+
+# 11. Required Test Matrix
+
+| Boundary               | Required evidence                                                 |
+| ---------------------- | ----------------------------------------------------------------- |
+| Live context           | spawn/register/registry/inspect share exact session Skill context |
+| Session isolation      | no context bleed across sessions/replacements                     |
+| Startup                | Skill-dependent user tools reconcile after active Skills known    |
+| Watcher                | reload uses current context/generation, stale callback fenced     |
+| Delegation             | compact wrapper inherits effective Recipe contract                |
+| Invalid wrapper        | rejected before persistence with precise diagnostic               |
+| Schema ownership       | runtime-owned values absent                                       |
+| Schema types           | enum/bool/int/path/array retained                                 |
+| Defaults               | wrapper overrides validated against effective types               |
+| Catalog                | unrelated bad component yields partial inventory                  |
+| Exact resolution       | valid component resolves despite unrelated rejection              |
+| Registry observability | generation/time/watch/current counts available                    |
+| Registration           | persisted/active/host/callable states separated                   |
+| Rollback               | failed update preserves previous working tool                     |
+| Pi host                | same-session injection proven or truthful limitation returned     |
+| Launch kind            | tool vs spawn explicit in result/usage                            |
+| Source/dist            | same behavior in repository and packed install                    |
+| Security               | path/CAS/redaction/generation/review safety retained              |
+
+---
+
+# 12. Explicitly Deferred to `0.47.0`
+
+Only the **agent interface/guidance layer** is deferred:
+
+```text
+register_tool from=<skill>/<recipe>
+register_tool defaults={...}
+system prompt redesign as Skill-loading meta-protocol
+actors Skill redesign as root agent operating protocol
+capability Skill description/entrypoint redesign
+agent-facing delegation-vs-import decision guidance
+focused resolution explanation UX
+fresh-agent journey dogfood
+human-doc vs agent-Skill separation cleanup
+```
+
+Do not defer any known runtime inconsistency from the report.
+
+---
+
+# 13. Negative Scope
+
+Do not add:
+
+```text
+new Run nouns
+new Run views
+new generic invocation tool
+new recipe target namespace
+task graph runtime
+actor chat
+rooms/peers/mailboxes
+remote Recipe registry
+compatibility std:/skill: aliases
+copied packaged Recipe wrappers
+shell fallbacks
+new capability-authoring Skill
+large system-prompt rewrite
+```
+
+---
+
+# 14. Stop Conditions
+
+Stop and preserve evidence if:
+
+- Pi cannot dynamically expose a newly registered tool in the same session and the product cannot observe the activation boundary;
+- one authoritative user Recipe admission path cannot serve registry and `register_tool`;
+- session-scoped Skill-dependent tools require global mutable state;
+- rollback would overwrite concurrent user edits;
+- schema ownership cannot distinguish runtime and caller values without changing Recipe semantics;
+- fixing a failure appears to require copying a Skill Recipe contract into the user wrapper.
+
+Resolve blockers at the owning boundary rather than hiding them with agent guidance.

package/CHANGELOG.md

@@ -1,6 +1,22 @@
 # Changelog
 
-> Each release keeps at most 8 outcome records of at most 512 characters.
+## 0.46.1: Registration Truth
+
+- `Live Resolution`: Spawn, registration, registry admission/reload, schema derivation, and Inspect now consume one immutable session Recipe context. Skill-dependent user wrappers reconcile only after Pi supplies active Skills, watcher reloads retain the current generation, and stale session consumers fail closed.
+- `Effective Admission`: One user-Recipe admission path resolves direct delegation before persistence, inheriting async behavior, typed arguments/defaults, artifacts, Control, and runtime origins without copying maintained contracts. Malformed or mistyped wrappers fail before mutation, and failed updates roll back prior bytes, registry state, host definitions, and active tools.
+- `Schema Ownership`: Caller schemas preserve enum, bool, integer, number, path, and array types while centrally excluding runtime-owned inputs such as `recipe_dir`, `skill_dir`, `state_dir`, Trace/run identity, and runtime state roots. The intentional async `run_id` override remains public.
+- `Fail-Soft Catalog`: Active-Skill inventory returns valid components alongside bounded per-component rejections and an explicit partial state. Invalid unrelated Recipes and duplicate namespaces remain diagnosable without poisoning exact resolution of valid components.
+- `Activation and Observability`: Registration reports resolved, validated, persisted, registry, host, active-tool, and callable states from Pi host evidence. Recipe inspection adds generation, scan, watcher, portable-root, and partial-catalog state; tool status reports current activation and separate spawn/tool usage.
+- `Launch Truth and Dogfood`: Spawn and registered-tool launches expose distinct `launch_kind` evidence. Source and packed-package regressions activate `media/player`, quarantine an unrelated stale component, register and invoke a compact `music_player` in the same session, preserve inherited Control/schema, exercise repair reloads and negative cases, and reject shell/copy workarounds.
+
+## 0.46.0: Skill-Owned Capability Packs
+
+- `Breaking Recipe Grammar`: File-backed identity now comes only from the filename; top-level Recipe `name`, nested Skill identities, JSON/Markdown stem collisions, bare references, and the old `std:` / `skill:` prefixes fail with migration guidance. Composition accepts exact `<active-skill>/<stem>` references or explicit `.json` / `.md` paths, with entry paths based at invocation cwd and relative imports based at their owning Recipe.
+- `Skill-Owned Distribution`: All 58 bundled components move from the root Recipe library into six flat Pi Skills—Actors, Artifacts, Media, Project Work, Recipe Memory, and Swarm—with 67 explicit imports and an acyclic cross-Skill graph. Root and `dist` Recipe libraries, package-root discovery, fallback/shadowing, wrapper installation, and obsolete root capability helpers are removed; Skill components never auto-register as tools.
+- `Scoped Resolution and Provenance`: Immutable active-Skill contexts are session-scoped and captured per Run. Recipe inspection distinguishes user registry capabilities, active Skill components, and explicit files while recording entry/import roles, filename stems, logical identities, Skill ownership, and alias ancestry without exposing private `source_file`, `{skill_dir}`, or `{recipe_dir}` values to model/Inspector surfaces.
+- `Capability Safety`: Automatic review resolves exact package-owned `recipe-memory/*` components so user files cannot redirect reviewers. Helpers self-locate through runtime-owned `{skill_dir}`; Control, Trace, lifecycle fencing, review transactions, and the public `spawn`, `message`, `inspect`, `register_tool` plus Recipe/Trace/Control view contracts remain unchanged.
+- `Validation and Architecture`: Recursive Skill QA validates direct identity, parse/import semantics, origins, Control, portable paths, and helper targets in source and installed packages. The custom release-gate and executable-style policy scanners are removed; CI runs product validation plus dependency audit, while a non-packaged project-local Domain DAG Skill supports architecture work without becoming a release gate.
+- `Dogfood and Migration`: Source and installed tests execute repository health, release readiness, quorum review, artifact bundle, media player, and package-owned draft review through qualified Skill references, plus relative/absolute file imports and all breaking failures. Migrate `std:foo` to `owning-skill/foo`, `skill:foo/bar` to `foo/bar`, root Recipes to their owning Skill filename, and delete Recipe `name` fields.
 
 ## 0.45.1: Entrypoint and Release Policy