@llblab/pi-actors 0.53.0 → 0.53.1

package/AGENTS.md

@@ -44,6 +44,8 @@ Pi host
 
 `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.
 
+The committed `dist/` tree is required for npm and git package installs. `npm run build` compiles into a temporary candidate and atomically replaces the distributive; `npm run build:check` must reject source/artifact drift without rewriting the working tree.
+
 ## Key Domains
 
 - `extension-runtime.ts`: low-level Pi session lifecycle, tool adaptation, and runtime service composition behind the thin `index.ts` event-registration root.
@@ -150,4 +152,5 @@ When deferred Run results gate the next step, wait for their completion batch. I
 - 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.
+- Manifest-loaded packages expose bundled Skills only through `pi.skills`, preserving package resource filters and package-owned provenance. Only a checkout auto-discovered directly below a user or project Pi `extensions/` root may contribute its source Skill root through `resources_discover`; compiled-vs-source filename shape does not determine ownership.
 - Until a stable version beyond `1.x`, prefer clean breaking simplification over compatibility aliases or renamed legacy abstractions.

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 > Each release keeps at most 8 outcome records of at most 512 characters.
 
+## Unreleased
+
+## 0.53.1: Filterable Skills and drift-safe Git installs
+
+- `Filterable Packaged Skills`: Manifest-loaded runtime leaves all six bundled Skills to `pi.skills`, preserving filters and provenance. Auto-discovered checkouts contribute source Skills even when Pi selects compiled code; resolver regressions cover both modes. Unsupported source manifest aliases are removed, and the committed distributive supports git installs with drift-checking atomic builds.
+
 ## 0.53.0: Tree-Compressed Completion Delivery
 
 - `Quiet Draft Reloads`: Keeps automatic Recipe reload active for draft-directory changes while showing “Recipe tools refreshed” only for active non-draft Recipe changes or registry-root replacement, so ordinary spawn draft capture no longer produces misleading tool-refresh noise.

package/README.md

@@ -31,7 +31,7 @@ For local development:
 pi install /path/to/pi-actors
 ```
 
-The package contributes the extension and six capability-owning Skills for actors, artifacts, music playback, project work, Recipe memory, and swarm orchestration.
+The package contributes the extension and six capability-owning Skills for actors, artifacts, music playback, project work, Recipe memory, and swarm orchestration. Manifest-loaded packages expose those Skills through the package manifest so Pi resource filters and package provenance remain authoritative; a checkout auto-discovered directly under Pi's user or project extensions directory contributes its source Skills even when Pi selects the checkout's compiled entrypoint.
 
 ## Public Tools
 
@@ -238,7 +238,7 @@ npm run validate
 npm run test:preservation
 ```
 
-The build produces the JavaScript runtime used by detached Actor processes in npm installations. Pi can load a TypeScript extension entrypoint, but standalone Node processes cannot type-strip modules under `node_modules`; keeping compiled Run modules preserves process isolation without a runtime TypeScript loader.
+The atomic build produces the committed JavaScript runtime used by npm and git installs; `npm run build:check` verifies that `dist/` matches source without rewriting it. Pi can load a TypeScript extension entrypoint, but standalone Node processes cannot type-strip modules under `node_modules`; keeping compiled Run modules preserves process isolation without a runtime TypeScript loader.
 
 See the [documentation index](./docs/README.md), [Run lifecycle](./docs/async-runs.md), and [Recipe library](./docs/recipe-library.md).
 

package/dist/index.js

@@ -5,9 +5,12 @@
  */
 import * as ExtensionRuntime from "./lib/extension-runtime.js";
 import * as InspectorCommand from "./lib/inspector-command.js";
+import * as Paths from "./lib/paths.js";
 export default function toolRegistryExtension(pi) {
     const runtime = ExtensionRuntime.createActorExtensionRuntime(pi);
-    pi.on("resources_discover", async () => runtime.discoverResources(import.meta.url));
+    if (Paths.isRawExtensionCheckout(import.meta.url)) {
+        pi.on("resources_discover", async () => runtime.discoverResources(import.meta.url));
+    }
     pi.on("session_start", async (_event, ctx) => runtime.onSessionStart(ctx));
     pi.on("agent_settled", async (_event, ctx) => runtime.onAgentSettled(ctx));
     pi.on("context", async (event, ctx) => ({

package/dist/lib/paths.d.ts

@@ -21,6 +21,12 @@ export declare function getToolReviewStatePath(agentDir?: string): string;
 export declare function getToolReviewBatchDir(reviewId: string, agentDir?: string): string;
 export declare function getExtensionRuntimePaths(agentDir?: string): ExtensionRuntimePaths;
 export declare const EXTENSION_RUNTIME_PATHS: ExtensionRuntimePaths;
+export declare function getExtensionPackageRoot(extensionUrl: string): string;
+export interface RawExtensionCheckoutOptions {
+    agentDir?: string;
+    cwd?: string;
+}
+export declare function isRawExtensionCheckout(extensionUrl: string, options?: RawExtensionCheckoutOptions): boolean;
 export declare function getExtensionSkillsDir(extensionUrl: string): string;
 export declare function getExistingExtensionSkillPaths(extensionUrl: string): string[];
 export declare function getRecipeRoot(agentDir?: string): string;

package/dist/lib/paths.js

@@ -57,8 +57,26 @@ export function getExtensionRuntimePaths(agentDir = getAgentDir()) {
     };
 }
 export const EXTENSION_RUNTIME_PATHS = getExtensionRuntimePaths();
+export function getExtensionPackageRoot(extensionUrl) {
+    let current = dirname(fileURLToPath(extensionUrl));
+    while (true) {
+        if (existsSync(join(current, "package.json")))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return dirname(fileURLToPath(extensionUrl));
+        current = parent;
+    }
+}
+export function isRawExtensionCheckout(extensionUrl, options = {}) {
+    const packageRoot = resolve(getExtensionPackageRoot(extensionUrl));
+    const agentDir = resolve(options.agentDir ?? getAgentDir());
+    const cwd = resolve(options.cwd ?? process.cwd());
+    return dirname(packageRoot) === join(agentDir, "extensions") ||
+        dirname(packageRoot) === join(cwd, ".pi", "extensions");
+}
 export function getExtensionSkillsDir(extensionUrl) {
-    return join(dirname(fileURLToPath(extensionUrl)), "skills");
+    return join(getExtensionPackageRoot(extensionUrl), "skills");
 }
 export function getExistingExtensionSkillPaths(extensionUrl) {
     const skillsDir = getExtensionSkillsDir(extensionUrl);

package/dist/scripts/build-dist.mjs

@@ -1,47 +1,40 @@
 #!/usr/bin/env node
 
 /**
- * Build the JavaScript-only distributive tree.
- *
- * This is intentionally standalone: it is package/build glue, not reusable
- * actor-domain behavior. It cleans dist, compiles TypeScript, mirrors runtime
- * assets, and syntax-checks packaged scripts.
+ * Builds or verifies the JavaScript-only distributive tree without exposing a
+ * partial tree to Pi or destroying the previous distributive on failure.
  */
 
 import { spawnSync } from "node:child_process";
 import {
   cpSync,
+  existsSync,
   mkdirSync,
+  mkdtempSync,
+  readFileSync,
   readdirSync,
+  renameSync,
   rmSync,
   writeFileSync,
 } from "node:fs";
-import { join } from "node:path";
+import { join, relative } from "node:path";
+
+const DIST_DIR = "dist";
+const checkOnly = process.argv.includes("--check");
 
 function run(command, args) {
   const result = spawnSync(command, args, { stdio: "inherit" });
   if (result.error) throw result.error;
-  if (result.status !== 0) process.exit(result.status ?? 1);
+  if (result.status !== 0) {
+    throw new Error(`${command} exited with status ${result.status ?? "unknown"}.`);
+  }
 }
 
-rmSync("dist", { recursive: true, force: true });
-mkdirSync("dist", { recursive: true });
-
-run(process.execPath, [
-  join("node_modules", "typescript", "bin", "tsc"),
-  "-p",
-  "tsconfig.build.json",
-]);
-
-mkdirSync(join("dist", "pi-actors"), { recursive: true });
-writeFileSync(
-  join("dist", "pi-actors", "index.js"),
-  'export { default } from "../index.js";\n',
-  "utf8",
-);
-
-for (const dir of ["scripts", "fixtures", "skills"]) {
-  cpSync(dir, join("dist", dir), { recursive: true });
+function listFiles(root, current = root) {
+  return readdirSync(current, { withFileTypes: true }).flatMap((entry) => {
+    const path = join(current, entry.name);
+    return entry.isDirectory() ? listFiles(root, path) : [relative(root, path)];
+  }).sort();
 }
 
 function listModuleScripts(root) {
@@ -52,9 +45,80 @@ function listModuleScripts(root) {
   });
 }
 
-const builtScripts = [
-  ...listModuleScripts(join("dist", "scripts")),
-  ...listModuleScripts(join("dist", "skills")),
-];
+function normalizeTextFiles(root) {
+  const textSuffixes = [".js", ".ts", ".mjs", ".json", ".md"];
+  for (const path of listFiles(root)) {
+    if (!textSuffixes.some((suffix) => path.endsWith(suffix))) continue;
+    const absolutePath = join(root, path);
+    const source = readFileSync(absolutePath, "utf8");
+    const normalized = source.replace(/\r\n?/g, "\n");
+    if (normalized !== source) writeFileSync(absolutePath, normalized, "utf8");
+  }
+}
+
+function assertTreesEqual(expectedRoot, actualRoot) {
+  if (!existsSync(expectedRoot)) {
+    throw new Error(`${expectedRoot} is missing; run npm run build.`);
+  }
+  const expectedFiles = listFiles(expectedRoot);
+  const actualFiles = listFiles(actualRoot);
+  if (JSON.stringify(expectedFiles) !== JSON.stringify(actualFiles)) {
+    throw new Error("dist file inventory is stale; run npm run build.");
+  }
+  for (const path of expectedFiles) {
+    if (!readFileSync(join(expectedRoot, path)).equals(readFileSync(join(actualRoot, path)))) {
+      throw new Error(`dist/${path} is stale; run npm run build.`);
+    }
+  }
+}
+
+function replaceDist(candidate) {
+  const backup = `.dist-backup-${process.pid}-${Date.now()}`;
+  const hadDist = existsSync(DIST_DIR);
+  if (hadDist) renameSync(DIST_DIR, backup);
+  try {
+    renameSync(candidate, DIST_DIR);
+    if (hadDist) rmSync(backup, { recursive: true, force: true });
+  } catch (error) {
+    if (hadDist && existsSync(backup) && !existsSync(DIST_DIR)) {
+      renameSync(backup, DIST_DIR);
+    }
+    throw error;
+  }
+}
 
-run(process.execPath, ["--check", ...builtScripts]);
+const candidate = mkdtempSync(join(process.cwd(), ".dist-build-"));
+try {
+  run(process.execPath, [
+    join("node_modules", "typescript", "bin", "tsc"),
+    "-p",
+    "tsconfig.build.json",
+    "--outDir",
+    candidate,
+  ]);
+
+  mkdirSync(join(candidate, "pi-actors"), { recursive: true });
+  writeFileSync(
+    join(candidate, "pi-actors", "index.js"),
+    'export { default } from "../index.js";\n',
+    "utf8",
+  );
+  normalizeTextFiles(candidate);
+  for (const dir of ["scripts", "fixtures", "skills"]) {
+    cpSync(dir, join(candidate, dir), { recursive: true });
+  }
+  const builtScripts = [
+    ...listModuleScripts(join(candidate, "scripts")),
+    ...listModuleScripts(join(candidate, "skills")),
+  ];
+  run(process.execPath, ["--check", ...builtScripts]);
+
+  if (checkOnly) {
+    assertTreesEqual(DIST_DIR, candidate);
+    console.log("pi-actors: dist is current");
+  } else {
+    replaceDist(candidate);
+  }
+} finally {
+  rmSync(candidate, { recursive: true, force: true });
+}

package/index.ts

@@ -6,13 +6,16 @@
 
 import * as ExtensionRuntime from "./lib/extension-runtime.ts";
 import * as InspectorCommand from "./lib/inspector-command.ts";
+import * as Paths from "./lib/paths.ts";
 import * as Pi from "./lib/pi.ts";
 
 export default function toolRegistryExtension(pi: Pi.ExtensionAPI) {
   const runtime = ExtensionRuntime.createActorExtensionRuntime(pi);
-  pi.on("resources_discover", async () =>
-    runtime.discoverResources(import.meta.url),
-  );
+  if (Paths.isRawExtensionCheckout(import.meta.url)) {
+    pi.on("resources_discover", async () =>
+      runtime.discoverResources(import.meta.url),
+    );
+  }
   pi.on("session_start", async (_event, ctx) => runtime.onSessionStart(ctx));
   pi.on("agent_settled", async (_event, ctx) => runtime.onAgentSettled(ctx));
   pi.on("context", async (event, ctx) => ({

package/lib/paths.ts

@@ -93,8 +93,34 @@ export function getExtensionRuntimePaths(
 
 export const EXTENSION_RUNTIME_PATHS = getExtensionRuntimePaths();
 
+export function getExtensionPackageRoot(extensionUrl: string): string {
+  let current = dirname(fileURLToPath(extensionUrl));
+  while (true) {
+    if (existsSync(join(current, "package.json"))) return current;
+    const parent = dirname(current);
+    if (parent === current) return dirname(fileURLToPath(extensionUrl));
+    current = parent;
+  }
+}
+
+export interface RawExtensionCheckoutOptions {
+  agentDir?: string;
+  cwd?: string;
+}
+
+export function isRawExtensionCheckout(
+  extensionUrl: string,
+  options: RawExtensionCheckoutOptions = {},
+): boolean {
+  const packageRoot = resolve(getExtensionPackageRoot(extensionUrl));
+  const agentDir = resolve(options.agentDir ?? getAgentDir());
+  const cwd = resolve(options.cwd ?? process.cwd());
+  return dirname(packageRoot) === join(agentDir, "extensions") ||
+    dirname(packageRoot) === join(cwd, ".pi", "extensions");
+}
+
 export function getExtensionSkillsDir(extensionUrl: string): string {
-  return join(dirname(fileURLToPath(extensionUrl)), "skills");
+  return join(getExtensionPackageRoot(extensionUrl), "skills");
 }
 
 export function getExistingExtensionSkillPaths(extensionUrl: string): string[] {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.53.0",
+  "version": "0.53.1",
   "private": false,
   "description": "Local Actor Kernel for Pi",
   "keywords": [
@@ -31,9 +31,10 @@
     "test:preservation": "node --experimental-strip-types --test --test-concurrency=1 tests/async-runs.test.ts tests/observability.test.ts tests/session-evidence.test.ts tests/inspector-security.test.ts tests/inspector-overlay.test.ts tests/review-control.test.ts",
     "pack:dry": "npm pack --dry-run",
     "recipes:qa": "node skills/actors/scripts/validate-recipe.mjs skills --skills --qa --summary",
-    "validate": "npx tsc --noEmit && npm run recipes:qa && npm run build && npm run check && npm test && npm run conformance && npm run pack:dry",
+    "validate": "npx tsc --noEmit && npm run recipes:qa && npm run build:check && npm run check && npm test && npm run conformance && npm run pack:dry",
     "audit:dependencies": "npm audit --audit-level=high --omit=peer",
     "build": "node scripts/build-dist.mjs",
+    "build:check": "node scripts/build-dist.mjs --check",
     "prepack": "npm run build"
   },
   "files": [
@@ -54,15 +55,9 @@
     "extensions": [
       "./dist/pi-actors/index.js"
     ],
-    "sourceExtensions": [
-      "./index.ts"
-    ],
     "skills": [
       "./dist/skills"
     ],
-    "sourceSkills": [
-      "./skills"
-    ],
     "image": "https://raw.githubusercontent.com/llblab/pi-actors/main/banner.jpg"
   },
   "peerDependencies": {

package/scripts/build-dist.mjs

@@ -1,47 +1,40 @@
 #!/usr/bin/env node
 
 /**
- * Build the JavaScript-only distributive tree.
- *
- * This is intentionally standalone: it is package/build glue, not reusable
- * actor-domain behavior. It cleans dist, compiles TypeScript, mirrors runtime
- * assets, and syntax-checks packaged scripts.
+ * Builds or verifies the JavaScript-only distributive tree without exposing a
+ * partial tree to Pi or destroying the previous distributive on failure.
  */
 
 import { spawnSync } from "node:child_process";
 import {
   cpSync,
+  existsSync,
   mkdirSync,
+  mkdtempSync,
+  readFileSync,
   readdirSync,
+  renameSync,
   rmSync,
   writeFileSync,
 } from "node:fs";
-import { join } from "node:path";
+import { join, relative } from "node:path";
+
+const DIST_DIR = "dist";
+const checkOnly = process.argv.includes("--check");
 
 function run(command, args) {
   const result = spawnSync(command, args, { stdio: "inherit" });
   if (result.error) throw result.error;
-  if (result.status !== 0) process.exit(result.status ?? 1);
+  if (result.status !== 0) {
+    throw new Error(`${command} exited with status ${result.status ?? "unknown"}.`);
+  }
 }
 
-rmSync("dist", { recursive: true, force: true });
-mkdirSync("dist", { recursive: true });
-
-run(process.execPath, [
-  join("node_modules", "typescript", "bin", "tsc"),
-  "-p",
-  "tsconfig.build.json",
-]);
-
-mkdirSync(join("dist", "pi-actors"), { recursive: true });
-writeFileSync(
-  join("dist", "pi-actors", "index.js"),
-  'export { default } from "../index.js";\n',
-  "utf8",
-);
-
-for (const dir of ["scripts", "fixtures", "skills"]) {
-  cpSync(dir, join("dist", dir), { recursive: true });
+function listFiles(root, current = root) {
+  return readdirSync(current, { withFileTypes: true }).flatMap((entry) => {
+    const path = join(current, entry.name);
+    return entry.isDirectory() ? listFiles(root, path) : [relative(root, path)];
+  }).sort();
 }
 
 function listModuleScripts(root) {
@@ -52,9 +45,80 @@ function listModuleScripts(root) {
   });
 }
 
-const builtScripts = [
-  ...listModuleScripts(join("dist", "scripts")),
-  ...listModuleScripts(join("dist", "skills")),
-];
+function normalizeTextFiles(root) {
+  const textSuffixes = [".js", ".ts", ".mjs", ".json", ".md"];
+  for (const path of listFiles(root)) {
+    if (!textSuffixes.some((suffix) => path.endsWith(suffix))) continue;
+    const absolutePath = join(root, path);
+    const source = readFileSync(absolutePath, "utf8");
+    const normalized = source.replace(/\r\n?/g, "\n");
+    if (normalized !== source) writeFileSync(absolutePath, normalized, "utf8");
+  }
+}
+
+function assertTreesEqual(expectedRoot, actualRoot) {
+  if (!existsSync(expectedRoot)) {
+    throw new Error(`${expectedRoot} is missing; run npm run build.`);
+  }
+  const expectedFiles = listFiles(expectedRoot);
+  const actualFiles = listFiles(actualRoot);
+  if (JSON.stringify(expectedFiles) !== JSON.stringify(actualFiles)) {
+    throw new Error("dist file inventory is stale; run npm run build.");
+  }
+  for (const path of expectedFiles) {
+    if (!readFileSync(join(expectedRoot, path)).equals(readFileSync(join(actualRoot, path)))) {
+      throw new Error(`dist/${path} is stale; run npm run build.`);
+    }
+  }
+}
+
+function replaceDist(candidate) {
+  const backup = `.dist-backup-${process.pid}-${Date.now()}`;
+  const hadDist = existsSync(DIST_DIR);
+  if (hadDist) renameSync(DIST_DIR, backup);
+  try {
+    renameSync(candidate, DIST_DIR);
+    if (hadDist) rmSync(backup, { recursive: true, force: true });
+  } catch (error) {
+    if (hadDist && existsSync(backup) && !existsSync(DIST_DIR)) {
+      renameSync(backup, DIST_DIR);
+    }
+    throw error;
+  }
+}
 
-run(process.execPath, ["--check", ...builtScripts]);
+const candidate = mkdtempSync(join(process.cwd(), ".dist-build-"));
+try {
+  run(process.execPath, [
+    join("node_modules", "typescript", "bin", "tsc"),
+    "-p",
+    "tsconfig.build.json",
+    "--outDir",
+    candidate,
+  ]);
+
+  mkdirSync(join(candidate, "pi-actors"), { recursive: true });
+  writeFileSync(
+    join(candidate, "pi-actors", "index.js"),
+    'export { default } from "../index.js";\n',
+    "utf8",
+  );
+  normalizeTextFiles(candidate);
+  for (const dir of ["scripts", "fixtures", "skills"]) {
+    cpSync(dir, join(candidate, dir), { recursive: true });
+  }
+  const builtScripts = [
+    ...listModuleScripts(join(candidate, "scripts")),
+    ...listModuleScripts(join(candidate, "skills")),
+  ];
+  run(process.execPath, ["--check", ...builtScripts]);
+
+  if (checkOnly) {
+    assertTreesEqual(DIST_DIR, candidate);
+    console.log("pi-actors: dist is current");
+  } else {
+    replaceDist(candidate);
+  }
+} finally {
+  rmSync(candidate, { recursive: true, force: true });
+}