@jbarket/loomai 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -12,6 +12,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-10-24
+
+### Added
+
+- **Pieces: `loom <piece>` dispatches to `loom-<piece>` on PATH, and `loom
+  pieces` lists them.** loom's command namespace now reaches separate,
+  swappable extensions (tasks, secrets, a wake clock, …) the way `git` reaches
+  `git-<cmd>`. loom never links them, and they never write loom's stores. Core
+  commands always win, piece names are validated before PATH is searched,
+  loom's env passes through unchanged, and the piece's exit code comes back.
+  The tiers, the rules (alone, composes without requiring, a contract per
+  role, no secrets in argv) and how pieces meet through named seams are in
+  `docs/extensions.md`.
+
 ## [0.6.0] - 2026-10-24
 
 ### Added
@@ -574,7 +588,8 @@ Initial public release.
   stack and all added external-service dependencies or operational
   overhead.
 
-[Unreleased]: https://github.com/sleepunit-agents/loom/compare/v0.6.0...HEAD
+[Unreleased]: https://github.com/sleepunit-agents/loom/compare/v0.7.0...HEAD
+[0.7.0]: https://github.com/sleepunit-agents/loom/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/sleepunit-agents/loom/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/sleepunit-agents/loom/compare/v0.4.1...v0.5.0
 [0.4.1]: https://github.com/sleepunit-agents/loom/compare/v0.3.1...v0.4.1

package/README.md

@@ -593,6 +593,24 @@ loom migrate --dry-run   # check without applying
 loom migrate --json      # machine-readable output
 ```
 
+### Pieces — `loom tasks`, `loom secrets`, … as separate programs
+
+loom stays identity and memory. Everything else an agent leans on (tasks,
+secrets, a wake clock, an approval page) is a **piece**: its own program,
+reached through loom's command namespace the way `git` reaches `git-<cmd>`.
+`loom tasks list` runs the first `loom-tasks` on `PATH` with `list`, and
+passes back its exit code. Core commands can't be shadowed. Pieces never
+write loom's stores, work alone, and compose when others are installed. Each
+piece role has a contract, so an implementation can be swapped for another.
+
+```bash
+loom pieces            # what's installed (name → path)
+loom tasks ready       # → loom-tasks ready
+```
+
+The rules, the dispatch details and how pieces compose:
+[`docs/extensions.md`](docs/extensions.md).
+
 ### Harness manifests and self-describe
 
 A **harness** is the MCP-capable runtime the agent runs in (Claude Code,

package/dist/cli/index.js

@@ -9,6 +9,7 @@ import { realStreams } from './io.js';
 import { SUBCOMMANDS } from './subcommands.js';
 import { extractGlobalFlags, firstNonGlobalIndex } from './args.js';
 import { REMOTE_VERBS, runRemote } from './remote.js';
+import { findPiece, isPieceName, runPiece } from './pieces.js';
 const TOP_HELP = `Usage: loom <command> [options]
 
 Commands:
@@ -30,6 +31,10 @@ Commands:
   install           Write loom-setup skill into a harness's skills dir
   doctor            Probe the loom environment (read-only)
   migrate           Apply pending schema migrations to memories.db
+  pieces            List installed pieces (loom-<name> on PATH)
+
+Pieces: \`loom <name> ...\` runs an installed extension, loom-<name> on PATH
+(e.g. loom tasks list). Core commands always win. See docs/extensions.md.
 
 Global flags:
   --context-dir <path>   Agent context dir (default: $LOOM_CONTEXT_DIR or ~/.config/loom/default)
@@ -50,6 +55,19 @@ async function readVersion() {
     return pkg.version;
 }
 export async function runCli(argv, io = realStreams()) {
+    // A piece (docs/extensions.md): not a core command, and loom-<name> is on PATH.
+    const pieceIdx = firstNonGlobalIndex(argv);
+    const pieceName = argv[pieceIdx];
+    if (isPieceName(pieceName)) {
+        const path = findPiece(pieceName, io.env);
+        if (path) {
+            if (pieceIdx > 0) {
+                io.stderr(`loom: global flags (${argv.slice(0, pieceIdx).join(' ')}) don't apply to pieces; put the piece's own flags after its name.\n`);
+                return 2;
+            }
+            return runPiece(path, argv.slice(pieceIdx + 1), io);
+        }
+    }
     const resolved = await resolveSubcommand(argv, io);
     if (typeof resolved === 'number')
         return resolved;
@@ -101,6 +119,8 @@ async function resolveSubcommand(argv, io) {
     }
     if (!SUBCOMMANDS.includes(first)) {
         io.stderr(`Unknown subcommand: ${first}\n`);
+        if (isPieceName(first))
+            io.stderr(`(no piece installed either: nothing named loom-${first} on PATH; \`loom pieces\` lists what is)\n`);
         io.stderr(TOP_HELP);
         return 2;
     }
@@ -174,6 +194,10 @@ async function dispatch(sub, rest, io) {
             const { run } = await import('./migrate.js');
             return run(rest, io);
         }
+        case 'pieces': {
+            const { runPiecesCommand } = await import('./pieces.js');
+            return runPiecesCommand(rest, io);
+        }
         default:
             io.stderr(`Subcommand not implemented yet: ${sub}\n`);
             return 2;

package/dist/cli/pieces.d.ts

@@ -0,0 +1,24 @@
+import type { IOStreams } from './io.js';
+/** A piece name: lowercase, starts with a letter, no dots or slashes. */
+export declare const PIECE_NAME: RegExp;
+/** Whether `name` could be a piece (valid name, not a core subcommand). */
+export declare function isPieceName(name: string | undefined): name is string;
+/** The executable that answers `loom <name>`: the first `loom-<name>` on PATH. */
+export declare function findPiece(name: string, env: NodeJS.ProcessEnv): string | undefined;
+export interface InstalledPiece {
+    name: string;
+    path: string;
+}
+/** Every installed piece, first on PATH wins (the one `loom <name>` would run). */
+export declare function listPieces(env: NodeJS.ProcessEnv): InstalledPiece[];
+/**
+ * Run a piece with `args`, passing loom's env through unchanged. With the
+ * process's own streams the piece inherits the terminal (so it can prompt,
+ * e.g. for a secret's value); with captured streams (tests) its output is
+ * forwarded. Exit code: the piece's own, 128+signal if it was killed, 127 if
+ * it couldn't start.
+ */
+export declare function runPiece(path: string, args: string[], io: IOStreams): Promise<number>;
+/** `loom pieces`: list what's installed. */
+export declare function runPiecesCommand(argv: string[], io: IOStreams): number;
+export declare const PIECES_USAGE = "Usage: loom pieces [--json]\n\nList the installed pieces: every executable named loom-<name> on PATH, which\nanswers `loom <name> ...`. The first one on PATH wins; core commands can't be\nshadowed. See docs/extensions.md.\n";

package/dist/cli/pieces.js

@@ -0,0 +1,139 @@
+/**
+ * Pieces — `loom <piece> ...` runs the installed extension `loom-<piece>`
+ * (docs/extensions.md, t-1466).
+ *
+ * Git-style dispatch: an executable named `loom-tasks` on PATH answers
+ * `loom tasks list`. loom doesn't know what a piece does and never links its
+ * code: the piece is its own program, reached as its own process, so it can't
+ * reach into loom's stores and can be swapped for anything else that installs
+ * the same name and honors that piece's contract.
+ *
+ * Core subcommands always win (a `loom-recall` on PATH is never consulted),
+ * and a name must match PIECE_NAME before PATH is searched at all.
+ */
+import { accessSync, constants, readdirSync, statSync } from 'node:fs';
+import { delimiter, join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { constants as osConstants } from 'node:os';
+import { SUBCOMMANDS } from './subcommands.js';
+/** A piece name: lowercase, starts with a letter, no dots or slashes. */
+export const PIECE_NAME = /^[a-z][a-z0-9-]{0,39}$/;
+const PREFIX = 'loom-';
+const CORE = new Set(SUBCOMMANDS);
+function isExecutableFile(path) {
+    try {
+        if (!statSync(path).isFile())
+            return false;
+        accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function pathDirs(env) {
+    return (env.PATH ?? '').split(delimiter).filter(Boolean);
+}
+/** Whether `name` could be a piece (valid name, not a core subcommand). */
+export function isPieceName(name) {
+    return name !== undefined && PIECE_NAME.test(name) && !CORE.has(name);
+}
+/** The executable that answers `loom <name>`: the first `loom-<name>` on PATH. */
+export function findPiece(name, env) {
+    if (!isPieceName(name))
+        return undefined;
+    for (const dir of pathDirs(env)) {
+        const candidate = join(dir, PREFIX + name);
+        if (isExecutableFile(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+/** Every installed piece, first on PATH wins (the one `loom <name>` would run). */
+export function listPieces(env) {
+    const seen = new Map();
+    for (const dir of pathDirs(env)) {
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries.sort()) {
+            if (!entry.startsWith(PREFIX))
+                continue;
+            const name = entry.slice(PREFIX.length);
+            if (seen.has(name) || !isPieceName(name))
+                continue;
+            const path = join(dir, entry);
+            if (isExecutableFile(path))
+                seen.set(name, path);
+        }
+    }
+    return [...seen].map(([name, path]) => ({ name, path })).sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * Run a piece with `args`, passing loom's env through unchanged. With the
+ * process's own streams the piece inherits the terminal (so it can prompt,
+ * e.g. for a secret's value); with captured streams (tests) its output is
+ * forwarded. Exit code: the piece's own, 128+signal if it was killed, 127 if
+ * it couldn't start.
+ */
+export async function runPiece(path, args, io) {
+    const inherit = io.stdin === process.stdin;
+    const child = spawn(path, args, {
+        env: io.env,
+        stdio: inherit ? 'inherit' : ['pipe', 'pipe', 'pipe'],
+    });
+    if (!inherit) {
+        child.stdout?.on('data', (d) => io.stdout(d.toString()));
+        child.stderr?.on('data', (d) => io.stderr(d.toString()));
+        if (child.stdin) {
+            if (io.stdinIsTTY)
+                child.stdin.end();
+            else
+                io.stdin.pipe(child.stdin);
+        }
+    }
+    return new Promise((resolve) => {
+        child.on('error', (err) => {
+            io.stderr(`loom: couldn't run ${path}: ${err.message}\n`);
+            resolve(127);
+        });
+        child.on('close', (code, signal) => {
+            if (signal)
+                resolve(128 + (osConstants.signals[signal] ?? 0));
+            else
+                resolve(code ?? 1);
+        });
+    });
+}
+/** `loom pieces`: list what's installed. */
+export function runPiecesCommand(argv, io) {
+    const json = argv.includes('--json');
+    const rest = argv.filter((a) => a !== '--json');
+    if (rest.includes('--help') || rest.includes('-h')) {
+        io.stdout(PIECES_USAGE);
+        return 0;
+    }
+    if (rest.length) {
+        io.stderr(`loom pieces takes no arguments.\n${PIECES_USAGE}`);
+        return 2;
+    }
+    const pieces = listPieces(io.env);
+    if (json) {
+        io.stdout(JSON.stringify(pieces, null, 2) + '\n');
+        return 0;
+    }
+    io.stdout(pieces.length === 0
+        ? 'no pieces installed (a piece is an executable named loom-<name> on PATH)\n'
+        : pieces.map((p) => `${p.name}\t${p.path}`).join('\n') + '\n');
+    return 0;
+}
+export const PIECES_USAGE = `Usage: loom pieces [--json]
+
+List the installed pieces: every executable named loom-<name> on PATH, which
+answers \`loom <name> ...\`. The first one on PATH wins; core commands can't be
+shadowed. See docs/extensions.md.
+`;

package/dist/cli/subcommands.d.ts

@@ -3,5 +3,5 @@
  * (src/cli/index.ts) and the CLI-vs-MCP routing gate (src/index.ts) so
  * the set never drifts between entry points.
  */
-export declare const SUBCOMMANDS: readonly ['wake', 'recall', 'remember', 'forget', 'update', 'memory', 'knowledge', 'person', 'update-identity', 'bootstrap', 'serve', 'inject', 'harness', 'install', 'doctor', 'migrate'];
+export declare const SUBCOMMANDS: readonly ['wake', 'recall', 'remember', 'forget', 'update', 'memory', 'knowledge', 'person', 'update-identity', 'bootstrap', 'serve', 'inject', 'harness', 'install', 'doctor', 'migrate', 'pieces'];
 export type Subcommand = typeof SUBCOMMANDS[number];

package/dist/cli/subcommands.js

@@ -7,5 +7,5 @@ export const SUBCOMMANDS = [
     'wake', 'recall', 'remember', 'forget', 'update',
     'memory', 'knowledge', 'person', 'update-identity', 'bootstrap', 'serve',
     'inject', 'harness',
-    'install', 'doctor', 'migrate',
+    'install', 'doctor', 'migrate', 'pieces',
 ];

package/dist/index.js

@@ -27,6 +27,7 @@ import { createLoomServer } from './server.js';
 import { resolveContextDir } from './config.js';
 import { SUBCOMMANDS } from './cli/subcommands.js';
 import { firstNonGlobalIndex } from './cli/args.js';
+import { findPiece } from './cli/pieces.js';
 const CLI_KEYWORDS = new Set(SUBCOMMANDS);
 function isCliInvocation(argv) {
     const args = argv.slice(2);
@@ -37,7 +38,11 @@ function isCliInvocation(argv) {
         return true;
     if (first === '--version' || first === '-V')
         return true;
-    return CLI_KEYWORDS.has(first);
+    if (CLI_KEYWORDS.has(first))
+        return true;
+    // An installed piece (loom-<first> on PATH) is a CLI call too. Anything else
+    // still falls through to the stdio server, exactly as before.
+    return findPiece(first, process.env) !== undefined;
 }
 export { isCliInvocation };
 async function main() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jbarket/loomai",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "MCP server for persistent AI agent identity and memory. Single-file sqlite-vec + local ONNX embeddings; zero external services.",
   "type": "module",
   "main": "dist/index.js",