@llblab/pi-actors 0.12.0 → 0.12.2

package/AGENTS.md

@@ -9,7 +9,7 @@
 
 ## Concept
 
-`pi-actors` is a local-first, cybernetic actor layer for pi. It persists user/agent-registered tools in `~/.pi/agent/tools.json` and registers them automatically across sessions, giving agents durable operational muscle memory for trusted local commands, scripts, actor recipes, and async actor runs. Treat it as MCP-adjacent local capability creation: the agent can create and refine its own tools instead of depending only on external tool servers.
+`pi-actors` is a local-first, cybernetic actor layer for pi. It persists user/agent-registered actor-control tools in `~/.pi/agent/actors-tools.json` and registers them automatically across sessions, giving agents durable operational muscle memory for trusted local commands, scripts, actor recipes, and async actor runs. Treat it as MCP-adjacent local capability creation: the agent can create and refine its own tools instead of depending only on external tool servers.
 
 ## Topology
 
@@ -35,7 +35,7 @@
 
 ## Durable Conventions
 
-- `Tool registry source`: `~/.pi/agent/tools.json` is the persistent user config | Trigger: Any runtime registration or migration work | Action: Preserve atomic writes and avoid hidden format changes without an explicit migration path
+- `Tool registry source`: `~/.pi/agent/actors-tools.json` is the persistent user config | Trigger: Any runtime registration or migration work | Action: Preserve atomic writes and avoid hidden format changes without an explicit migration path
 - `Current runtime contract`: Register trusted command templates with tool names from registry keys, placeholder-derived args, progressive typed arg declarations, inline/default/`??`/ternary config fallback, placeholder-derived numeric node controls, split-first command-arg construction, sequential or `parallel: true` composition, direct no-shell execution, optional per-node `when`, optional per-node positive `timeout` disabled by default, lightweight warnings for obvious trusted-executable risk shapes, per-node `delay`, bounded leaf/node `retry`, `failure: "continue|branch|root"` propagation, `recover` cleanup between retry attempts, template recipes with explicit `async: true` detached mode, actor-oriented `spawn`/`message`/`inspect` tools with run-local JSONL outbox messages, Unix FIFO send, graceful cancel, and force kill, generic detached run primitives with process-group cancellation, injected async `{run_id}` and `{state_dir}` values, coordinator-scoped event-driven observability with at least one triangle per active async run and extra triangles for active parallel branches, runtime-inferred `command.done` bubbling for packaged multi-agent fanout, named recipe `artifacts`, recipe `mailbox` metadata, terminal follow-ups for `done`/`failed`/unhandled `killed`/`exited` states, `template` recipe references, recipe-layer `imports`, co-located recipe entries, `~/.pi/agent/recipes/*.json` template recipe files, run state under `~/.pi/agent/tmp/pi-actors/runs`, and `{file}` as the canonical local file path arg | Trigger: Changing registration or invocation behavior | Action: Keep README, command-template docs, template-recipe docs, async-run docs, actor-message docs, implementation, and migration notes aligned
 - `Typed arg authoring`: Typed args support `string`, `path`, `int`, `number`, `bool`, and `enum(...)` plus two equivalent readability styles: metadata-first (`args` + `defaults` + simple `{name}` placeholders) for long command lines, and inline-first (`{name:type=default}` placeholders) for compact one-property templates | Trigger: Changing arg parsing, docs, schema generation, or registry serialization | Action: Preserve both styles, keep explicit `args` type declarations higher priority than inline placeholder types, and make breaking cleanup explicit when removing old arg shapes
 - `Template recipe graph`: The valid execution chain is `tool → template → recipe → run → template`; file-backed and co-located recipes are storage variants of that chain | Trigger: Adding registry bindings, recipes, docs, or runtime shortcuts | Action: Keep command templates synchronous and portable, use `async: true` as the detached run switch, require every recipe to own `template` directly, and reject cyclic shortcuts such as recipe-owned `tool`

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 0.12.2: Registry Migration Notes
+
+- `[Docs]` Added explicit rename migration instructions for copying `~/.pi/agent/auto-tools.json` or the short-lived `~/.pi/agent/tools.json` to `~/.pi/agent/actors-tools.json`. Impact: operators keep control of config migration while the package avoids silent rewrites of old registry files.
+
+## 0.12.1: Actor Tool Registry Name
+
+- `[Registry]` Renamed the new pi-actors registry filename from `tools.json` to `actors-tools.json`. Impact: the persisted config name now clearly describes actor-control tools instead of implying every pi tool belongs to this extension.
+
+## 0.12.0: Rename to pi-actors
+
 - `[Rename]` Renamed the package and current public surface from `@llblab/pi-auto-tools` / `pi-auto-tools` to `@llblab/pi-actors` / `pi-actors`, moved the persistent registry filename from `auto-tools.json` to `tools.json`, and moved runtime state defaults from `~/.pi/agent/tmp/pi-auto-tools` to `~/.pi/agent/tmp/pi-actors`. Impact: the package name now matches the actor API model introduced in 0.10-0.11, while the durable registry becomes the generic pi agent tools config.
 
 ## 0.11.0: Actor API Compression

package/README.md

@@ -15,7 +15,7 @@ Actor runtime and persistent local tool registry extension for the pi coding age
 
 - **Local-First Tool Memory**: Lets agents create and persist their own trusted local tools, forming durable operational muscle memory instead of one-off shell commands.
 - **Commands Become Capabilities**: Turns stable local workflows into semantic agent tools, so the agent chooses what it can do instead of reconstructing how to run shell commands.
-- **Persistent Tool Registry**: Stores tool definitions in `~/.pi/agent/tools.json` and registers them automatically on session start.
+- **Actor Tool Registry**: Stores actor-control tool definitions in `~/.pi/agent/actors-tools.json` and registers them automatically on session start.
 - **Compact Semantic Interface**: Exposes short tool names, descriptions, named args, and defaults instead of long paths, positional command-arg order, and repeated command boilerplate.
 - **Safer Local Automation**: Wraps trusted command templates as narrow tools using split-first command-arg construction, placeholder substitution, and no shell evaluation.
 - **Reusable Building Blocks**: Makes skill scripts, sub-agent wrappers, diagnostics, and project workflows available as composable agent capabilities.
@@ -40,6 +40,28 @@ From git:
 pi install git:github.com/llblab/pi-actors
 ```
 
+## Rename Migration
+
+`pi-actors` reads persistent actor-control tools from:
+
+```text
+~/.pi/agent/actors-tools.json
+```
+
+If you previously used `pi-auto-tools`, copy the old registry intentionally:
+
+```bash
+cp ~/.pi/agent/auto-tools.json ~/.pi/agent/actors-tools.json
+```
+
+If you installed the brief `0.12.0`/`0.12.1` line and created `tools.json`, copy that file instead:
+
+```bash
+cp ~/.pi/agent/tools.json ~/.pi/agent/actors-tools.json
+```
+
+The extension does not silently rewrite old registry files; keep or delete the old file after confirming the new registry loads as expected.
+
 ## Mental Model
 
 `pi-actors` has one execution idea that grows in place:
@@ -157,7 +179,7 @@ register_tool name=shader_ring \
 
 If the recipe file contains `async: true`, calling `shader_ring` starts a detached run and returns metadata immediately. If `async` is omitted or false, the same recipe runs foreground and returns normal tool output.
 
-A recipe can also be co-located in `tools.json` when keeping metadata and the recipe body together is clearer:
+A recipe can also be co-located in `actors-tools.json` when keeping metadata and the recipe body together is clearer:
 
 ```json
 {
@@ -196,7 +218,7 @@ register_tool name=call_subagent template=null
 
 ## Resulting Config
 
-The commands above persist entries like this in `~/.pi/agent/tools.json`; tool names come from the top-level keys. Stored entries keep `template` last so flags and metadata are read before executable content:
+The commands above persist entries like this in `~/.pi/agent/actors-tools.json`; tool names come from the top-level keys. Stored entries keep `template` last so flags and metadata are read before executable content:
 
 ```json
 {
@@ -216,7 +238,7 @@ The commands above persist entries like this in `~/.pi/agent/tools.json`; tool n
 }
 ```
 
-This file is the durable registry. `register_tool` is the interactive API; `tools.json` is the persisted state that is loaded on future sessions.
+This file is the durable actor-tool registry. `register_tool` is the interactive API; `actors-tools.json` is the persisted state that is loaded on future sessions.
 
 ## Manage Run Actors
 

package/docs/template-recipes.md

@@ -180,7 +180,7 @@ A registered tool can point at an actor recipe by storing the recipe path or nam
 
 If `shader-ring-8-parallel.json` contains `async: true`, calling `shader_ring` starts a detached run and returns metadata. If `async` is omitted or false, calling `shader_ring` executes the recipe foreground and returns normal tool output.
 
-A registered tool may also co-locate an actor recipe directly in `tools.json`:
+A registered tool may also co-locate an actor recipe directly in `actors-tools.json`:
 
 ```json
 {

package/docs/tool-registry.md

@@ -1,9 +1,25 @@
 # Tool Registry
 
-`pi-actors` stores registered command-template tools and template-recipe launchers in `~/.pi/agent/tools.json` and registers them automatically on session start.
+`pi-actors` stores registered actor-control command-template tools and template-recipe launchers in `~/.pi/agent/actors-tools.json` and registers them automatically on session start.
 
 This document is the local adaptation of the portable [Command Template Standard](./command-templates.md).
 
+## Rename Migration
+
+`pi-actors` reads only `~/.pi/agent/actors-tools.json` as its registry source. When moving from `pi-auto-tools`, copy the previous registry explicitly:
+
+```bash
+cp ~/.pi/agent/auto-tools.json ~/.pi/agent/actors-tools.json
+```
+
+If a short-lived `~/.pi/agent/tools.json` file exists from the early `pi-actors` rename window, copy that file instead:
+
+```bash
+cp ~/.pi/agent/tools.json ~/.pi/agent/actors-tools.json
+```
+
+No automatic rewrite is performed so operators can decide when to retire old config files.
+
 ## Registering Tools
 
 `register_tool` is the interactive API for listing, creating, updating, or deleting persistent tools. Call it without arguments to list registered tools.

package/index.ts

@@ -2,7 +2,7 @@
  * pi-actors — actor runtime and persistent local tool registry for pi.
  * Zones: composition root, pi agent, actor runtime
  *
- * Wraps command templates as callable pi tools, stores their definitions in tools.json, and exposes actor orchestration across reloads and sessions.
+ * Wraps command templates as callable pi tools, stores their definitions in actors-tools.json, and exposes actor orchestration across reloads and sessions.
  */
 
 import { existsSync, readdirSync, watch, type FSWatcher } from "node:fs";

package/lib/config.ts

@@ -1,7 +1,7 @@
 /**
  * Persistent tool registry config helpers
  * Zones: registry config, persistence, migration boundary
- * Owns tools.json loading, normalization, unsupported-shape rejection, and serialization
+ * Owns actors-tools.json loading, normalization, unsupported-shape rejection, and serialization
  */
 
 import { existsSync, readFileSync } from "node:fs";

package/lib/paths.ts

@@ -16,7 +16,7 @@ export function getAgentDir(
 }
 
 export function getConfigPath(agentDir = getAgentDir()): string {
-  return join(agentDir, "tools.json");
+  return join(agentDir, "actors-tools.json");
 }
 
 export function getExtensionTmpDir(

package/lib/prompts.ts

@@ -6,7 +6,7 @@
 
 export const REGISTER_TOOL_DESCRIPTION =
   "Register a persistent custom tool from a command template, template recipe path, or co-located template recipe. " +
-  "Definitions are stored in tools.json across reloads. " +
+  "Definitions are stored in actors-tools.json across reloads. " +
   "Use update=true to overwrite an existing tool, template=null/empty to delete.";
 
 export const REGISTER_TOOL_PROMPT_SNIPPET =

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.12.0",
+  "version": "0.12.2",
   "private": false,
   "description": "Persistent template-backed tools for pi",
   "type": "module",