@jbarket/loomai 0.5.0

package/dist/blocks/harness.js

@@ -0,0 +1,142 @@
+/**
+ * Harness manifest reader.
+ *
+ * Each harness an agent has ever sleeved into gets one manifest at
+ * `<contextDir>/harnesses/<client>.md`. The manifest describes the
+ * harness independently of the model running inside it — tool prefixes,
+ * delegation primitive, scheduling, session search, known gotchas.
+ *
+ * Contract: stack spec v1 §4.7.
+ */
+import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parseFrontmatter } from './types.js';
+import { assertSafePathSegment } from '../path-safety.js';
+const DIR = 'harnesses';
+export async function read(contextDir, key) {
+    assertSafePathSegment(key, 'harness name');
+    const path = resolve(contextDir, DIR, `${key}.md`);
+    if (!existsSync(path))
+        return null;
+    const raw = await readFile(path, 'utf-8');
+    if (raw.trim() === '')
+        return null;
+    const { frontmatter, body } = parseFrontmatter(raw);
+    return { key, frontmatter, body: body.trim(), path };
+}
+export async function list(contextDir) {
+    const path = resolve(contextDir, DIR);
+    if (!existsSync(path))
+        return [];
+    const entries = await readdir(path);
+    return entries
+        .filter((name) => name.endsWith('.md'))
+        .map((name) => name.slice(0, -'.md'.length))
+        .sort();
+}
+/**
+ * Normalize an MCP peer's clientInfo.name to a harness-filename-shaped key.
+ *
+ * Proxies annotate the name with a trailing parenthetical, e.g.
+ * "claude-ai (via mcp-remote 0.1.37)" — strip that first, then lowercase and
+ * collapse spaces/underscores to hyphens so "Claude Desktop" and "claude_desktop"
+ * both land on "claude-desktop".
+ */
+export function normalizePeer(peerName) {
+    const base = peerName.split(/\s*\(/, 1)[0];
+    return base.trim().toLowerCase().replace(/[\s_]+/g, '-');
+}
+/**
+ * Resolve a connected MCP peer to a harness manifest key, DATA-DRIVEN from the
+ * manifest files on disk (not a hardcoded code map). A harness is recognized
+ * when the normalized peer matches either the manifest's filename OR one of the
+ * comma-separated values in its `answersTo` frontmatter (each normalized the
+ * same way). A brand-new harness is recognized by dropping a file — no code
+ * change. Returns undefined when nothing matches.
+ */
+export async function resolvePeerToHarness(contextDir, peerName) {
+    if (!peerName)
+        return undefined;
+    const normalized = normalizePeer(peerName);
+    if (!normalized)
+        return undefined;
+    const keys = await list(contextDir);
+    // Filename match is the cheapest and most direct signal.
+    if (keys.includes(normalized))
+        return normalized;
+    // Otherwise scan each manifest's answersTo frontmatter for the peer.
+    for (const key of keys) {
+        const block = await read(contextDir, key);
+        if (!block)
+            continue;
+        const answersTo = block.frontmatter.answersTo;
+        if (!answersTo)
+            continue;
+        const aliases = answersTo
+            .split(',')
+            .map((alias) => normalizePeer(alias))
+            .filter(Boolean);
+        if (aliases.includes(normalized))
+            return key;
+    }
+    return undefined;
+}
+/**
+ * Write (or overwrite) a harness manifest from a connected harness describing
+ * itself. Lands strictly under `<contextDir>/harnesses/<targetKey>.md` with
+ * stamped frontmatter (harness/version/updated) followed by the provided body.
+ * Re-runnable — overwrites. assertSafePathSegment guards the key so the creed
+ * and other tiers are structurally unreachable.
+ */
+export async function describeHarness(contextDir, targetKey, content, opts = {}) {
+    assertSafePathSegment(targetKey, 'harness name');
+    const dir = resolve(contextDir, DIR);
+    await mkdir(dir, { recursive: true });
+    const path = resolve(dir, `${targetKey}.md`);
+    const exists = existsSync(path);
+    const version = opts.version ?? '0.1';
+    const body = content.trim();
+    const manifest = `---\n` +
+        `harness: ${targetKey}\n` +
+        `version: ${version}\n` +
+        `updated: ${new Date().toISOString()}\n` +
+        `---\n\n` +
+        `${body}\n`;
+    await writeFile(path, manifest, 'utf-8');
+    return { key: targetKey, path, action: exists ? 'overwritten' : 'created' };
+}
+export function template(key) {
+    return `---
+harness: ${key}
+version: 0.4
+---
+
+## Tool prefixes
+<tool-prefix list — see stack spec §4.7>
+
+## Delegation primitive
+<primary sub-agent mechanism>
+
+## Cron / scheduling
+<scheduling primitive if any, and local-vs-UTC note>
+
+## Session search
+<how transcripts are searched>
+
+## Gotchas
+<known quirks>
+`;
+}
+export async function initHarness(contextDir, name, opts = {}) {
+    assertSafePathSegment(name, 'harness name');
+    const dir = resolve(contextDir, DIR);
+    await mkdir(dir, { recursive: true });
+    const path = resolve(dir, `${name}.md`);
+    const exists = existsSync(path);
+    if (exists && !opts.overwrite) {
+        return { name, path, action: 'skipped-exists' };
+    }
+    await writeFile(path, template(name), 'utf-8');
+    return { name, path, action: exists ? 'overwritten' : 'created' };
+}

package/dist/blocks/model.d.ts

@@ -0,0 +1,4 @@
+import { type Block } from './types.js';
+export declare function read(contextDir: string, key: string): Promise<Block | null>;
+export declare function list(contextDir: string): Promise<string[]>;
+export declare function template(key: string): string;

package/dist/blocks/model.js

@@ -0,0 +1,56 @@
+/**
+ * Model manifest reader.
+ *
+ * Each model family the agent has ever sleeved into gets one manifest at
+ * `<contextDir>/models/<key>.md`. Describes capability notes, workarounds,
+ * and when-to-use / when-not-to-use guidance — independent of harness.
+ *
+ * Contract: stack spec v1 §4.8.
+ */
+import { readFile, readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parseFrontmatter } from './types.js';
+import { assertSafePathSegment } from '../path-safety.js';
+const DIR = 'models';
+export async function read(contextDir, key) {
+    assertSafePathSegment(key, 'model name');
+    const path = resolve(contextDir, DIR, `${key}.md`);
+    if (!existsSync(path))
+        return null;
+    const raw = await readFile(path, 'utf-8');
+    if (raw.trim() === '')
+        return null;
+    const { frontmatter, body } = parseFrontmatter(raw);
+    return { key, frontmatter, body: body.trim(), path };
+}
+export async function list(contextDir) {
+    const path = resolve(contextDir, DIR);
+    if (!existsSync(path))
+        return [];
+    const entries = await readdir(path);
+    return entries
+        .filter((name) => name.endsWith('.md'))
+        .map((name) => name.slice(0, -'.md'.length))
+        .sort();
+}
+export function template(key) {
+    return `---
+model: ${key}
+family: <family name>
+size: <size hint if meaningful>
+---
+
+## Capability notes
+<strengths and weaknesses that matter operationally>
+
+## Workarounds
+<known-good compensation patterns — or "None required.">
+
+## When to use
+<concrete situations this model is the right choice>
+
+## When not to use
+<concrete situations where a different model is better>
+`;
+}

package/dist/blocks/types.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Shared block types for loom stack blocks.
+ *
+ * A "block" is a markdown file in the stack that an adapter loads during
+ * the wake sequence — a harness manifest or a model manifest.
+ * This module defines the common shape and a tiny frontmatter parser.
+ * We intentionally avoid a YAML dep: frontmatter here is key: value lines,
+ * small and strict.
+ */
+/** A single block read from disk. */
+export interface Block {
+    /** Filename without `.md`. Also the harness / model name. */
+    key: string;
+    /** Parsed frontmatter as flat key→value. Empty object when absent or malformed. */
+    frontmatter: Record<string, string>;
+    /** Markdown body after the frontmatter fences. Not trimmed — callers trim as needed. */
+    body: string;
+    /** Absolute path this block was read from. */
+    path: string;
+}
+/** The common reader surface harness and model both implement. */
+export interface BlockReader {
+    /** Read a single block by key. Returns null when the file is missing or empty. */
+    read(contextDir: string, key: string): Promise<Block | null>;
+    /** Sorted list of keys present in this block's directory. */
+    list(contextDir: string): Promise<string[]>;
+    /** A blank template for this block type, parameterized by key. */
+    template(key: string): string;
+}
+/**
+ * Split `---` frontmatter from the markdown body. Missing or malformed
+ * fences yield `{}` frontmatter + the original text as body. Individual
+ * lines that aren't `key: value` are ignored.
+ *
+ * Normalizes CRLF → LF before parsing so files authored on Windows parse correctly.
+ */
+export declare function parseFrontmatter(text: string): {
+    frontmatter: Record<string, string>;
+    body: string;
+};

package/dist/blocks/types.js

@@ -0,0 +1,34 @@
+/**
+ * Shared block types for loom stack blocks.
+ *
+ * A "block" is a markdown file in the stack that an adapter loads during
+ * the wake sequence — a harness manifest or a model manifest.
+ * This module defines the common shape and a tiny frontmatter parser.
+ * We intentionally avoid a YAML dep: frontmatter here is key: value lines,
+ * small and strict.
+ */
+/**
+ * Split `---` frontmatter from the markdown body. Missing or malformed
+ * fences yield `{}` frontmatter + the original text as body. Individual
+ * lines that aren't `key: value` are ignored.
+ *
+ * Normalizes CRLF → LF before parsing so files authored on Windows parse correctly.
+ */
+export function parseFrontmatter(text) {
+    // Normalize CRLF → LF so the regex works cross-platform.
+    const normalized = text.replace(/\r\n/g, '\n');
+    const match = normalized.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+    if (!match)
+        return { frontmatter: {}, body: text };
+    const frontmatter = {};
+    for (const line of match[1].split('\n')) {
+        const colon = line.indexOf(':');
+        if (colon === -1)
+            continue;
+        const key = line.slice(0, colon).trim();
+        const value = line.slice(colon + 1).trim();
+        if (key)
+            frontmatter[key] = value;
+    }
+    return { frontmatter, body: match[2] };
+}

package/dist/categories.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared memory category vocabulary — the single source of truth for
+ * write-side category enforcement across MCP schemas and the CLI
+ * (store-convergence spec, "One boundary discipline").
+ *
+ * Reads (recall / memory_list / forget) intentionally accept arbitrary
+ * strings so memories written before the vocabulary existed (e.g.
+ * legacy "general") stay reachable. Only writes are enforced.
+ */
+export declare const MEMORY_CATEGORIES: readonly ['user', 'project', 'self', 'feedback', 'reference', 'pursuit', 'episode'];
+/** The category that carries the short-term cross-body tape. */
+export declare const EPISODE_CATEGORY = "episode";
+/** Episodes expire by default — they are a tape, not the stack. */
+export declare const EPISODE_DEFAULT_TTL = "48h";
+export type MemoryCategory = (typeof MEMORY_CATEGORIES)[number];
+export declare function isMemoryCategory(value: string): value is MemoryCategory;

package/dist/categories.js

@@ -0,0 +1,29 @@
+/**
+ * Shared memory category vocabulary — the single source of truth for
+ * write-side category enforcement across MCP schemas and the CLI
+ * (store-convergence spec, "One boundary discipline").
+ *
+ * Reads (recall / memory_list / forget) intentionally accept arbitrary
+ * strings so memories written before the vocabulary existed (e.g.
+ * legacy "general") stay reachable. Only writes are enforced.
+ */
+export const MEMORY_CATEGORIES = [
+    'user',
+    'project',
+    'self',
+    'feedback',
+    'reference',
+    'pursuit',
+    // Short-term cross-body tier (t-142): a 3-line "where / what / open" note a
+    // sleeve leaves so the NEXT sleeve knows what just happened across all of
+    // Art. Defaults to a 48h TTL on write; injected at boot as a time-ordered
+    // tape (never salience-ranked) and excluded from the Top-of-Mind digest.
+    'episode',
+];
+/** The category that carries the short-term cross-body tape. */
+export const EPISODE_CATEGORY = 'episode';
+/** Episodes expire by default — they are a tape, not the stack. */
+export const EPISODE_DEFAULT_TTL = '48h';
+export function isMemoryCategory(value) {
+    return MEMORY_CATEGORIES.includes(value);
+}

package/dist/cli/args.d.ts

@@ -0,0 +1,21 @@
+export interface ResolvedEnv {
+    contextDir: string;
+    client?: string;
+    model?: string;
+    json: boolean;
+}
+export interface RawGlobalFlags {
+    contextDir?: string;
+    client?: string;
+    model?: string;
+    json?: boolean;
+}
+export declare function resolveEnv(flags: RawGlobalFlags, processEnv: NodeJS.ProcessEnv): ResolvedEnv;
+/**
+ * Extracts global flags from an argv slice, returning the remaining argv.
+ * Recognizes: --context-dir, --client, --model, --json.
+ */
+export declare function extractGlobalFlags(argv: string[]): {
+    flags: RawGlobalFlags;
+    rest: string[];
+};

package/dist/cli/args.js

@@ -0,0 +1,47 @@
+/**
+ * Shared argv helpers — global flag resolution + context-dir/env
+ * precedence. Individual commands parse their own subcommand flags
+ * via node:util parseArgs.
+ */
+import { resolve } from 'node:path';
+import { resolveDefaultContextPath } from '../config.js';
+export function resolveEnv(flags, processEnv) {
+    const contextDir = flags.contextDir ??
+        processEnv.LOOM_CONTEXT_DIR ??
+        resolveDefaultContextPath(processEnv.HOME);
+    return {
+        contextDir: resolve(contextDir),
+        client: flags.client ?? processEnv.LOOM_CLIENT,
+        model: flags.model ?? processEnv.LOOM_MODEL,
+        json: Boolean(flags.json),
+    };
+}
+/**
+ * Extracts global flags from an argv slice, returning the remaining argv.
+ * Recognizes: --context-dir, --client, --model, --json.
+ */
+export function extractGlobalFlags(argv) {
+    const flags = {};
+    const rest = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--context-dir') {
+            flags.contextDir = argv[++i];
+            continue;
+        }
+        if (a === '--client') {
+            flags.client = argv[++i];
+            continue;
+        }
+        if (a === '--model') {
+            flags.model = argv[++i];
+            continue;
+        }
+        if (a === '--json') {
+            flags.json = true;
+            continue;
+        }
+        rest.push(a);
+    }
+    return { flags, rest };
+}

package/dist/cli/bootstrap.d.ts

@@ -0,0 +1,2 @@
+import type { IOStreams } from './io.js';
+export declare function run(argv: string[], io: IOStreams): Promise<number>;

package/dist/cli/bootstrap.js

@@ -0,0 +1,214 @@
+/**
+ * loom bootstrap — initialize a fresh agent.
+ *
+ * Param sources (precedence):
+ *   1. flags (--user, --name, --purpose, --voice, --preferences, --clients)
+ *   2. piped JSON on stdin
+ *   3. interactive readline prompts (only when stdin is a TTY)
+ */
+import { parseArgs } from 'node:util';
+import { join, dirname } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { lstat, symlink } from 'node:fs/promises';
+import { bootstrap } from '../tools/bootstrap.js';
+import { assertStackVersionCompatible, resolveDefaultContextPath } from '../config.js';
+import { extractGlobalFlags, resolveEnv } from './args.js';
+import { readStdin, renderJson, stderrWritable } from './io.js';
+import { validateAgentName } from '../install/names.js';
+const USAGE = `Usage: loom bootstrap [options]
+
+Initializes IDENTITY.md, preferences.md, and self-model.md
+in the context directory.
+
+Param sources (first match wins):
+  1. Flags (--name / --purpose / --voice)
+  2. Piped JSON on stdin: {"name","purpose","voice","user"?,"clients"?}
+  3. Interactive prompts when stdin is a TTY and nothing else is set
+
+Options:
+  --user <str>           The human this agent works with (their name)
+  --name <str>           Agent name (required)
+  --purpose <str>        One-line purpose
+  --voice <str>          Short voice descriptor
+  --preferences <str>    Optional preferences preamble
+  --clients <csv>        Comma-separated client adapters (e.g. claude-code)
+  --force                Overwrite an existing IDENTITY.md
+  --json                 Emit {contextDir, wrote: string[]}
+  --context-dir <path>   Agent context dir
+  --help, -h             Show this help
+`;
+function checkName(name, io) {
+    const r = validateAgentName(name);
+    if (r.ok)
+        return null;
+    io.stderr(`Invalid --name: ${r.reason}\n`);
+    return 2;
+}
+async function promptInteractive(io) {
+    const rl = createInterface({ input: io.stdin, output: stderrWritable(io) });
+    // Race each question against the readline 'close' event (fires when stdin
+    // ends before the user answers — e.g. piped /dev/null or empty test streams).
+    let closed = false;
+    const closedPromise = new Promise((resolve) => {
+        rl.once('close', () => { closed = true; resolve(null); });
+    });
+    const ask = (q) => Promise.race([
+        rl.question(q).then((s) => s),
+        closedPromise,
+    ]);
+    try {
+        if (closed)
+            return null;
+        const user = ((await ask('Your name (the human): ')) ?? '').trim();
+        if (closed)
+            return null;
+        const name = ((await ask('Agent name: ')) ?? '').trim();
+        if (!name)
+            return null;
+        const purpose = ((await ask('Purpose (one line): ')) ?? '').trim();
+        if (!purpose)
+            return null;
+        const voice = ((await ask('Voice (short descriptor): ')) ?? '').trim();
+        if (!voice)
+            return null;
+        const clientsRaw = ((await ask('Clients (comma-separated, e.g. claude-code): ')) ?? '').trim();
+        const clients = clientsRaw ? clientsRaw.split(',').map((s) => s.trim()).filter(Boolean) : undefined;
+        return { user: user || undefined, name, purpose, voice, clients };
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function run(argv, io) {
+    const { flags: global, rest } = extractGlobalFlags(argv);
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: rest,
+            options: {
+                user: { type: 'string' },
+                name: { type: 'string' },
+                purpose: { type: 'string' },
+                voice: { type: 'string' },
+                preferences: { type: 'string' },
+                clients: { type: 'string' },
+                force: { type: 'boolean' },
+                help: { type: 'boolean', short: 'h' },
+            },
+            strict: true,
+            allowPositionals: false,
+        });
+    }
+    catch (err) {
+        io.stderr(`${err.message}\n${USAGE}`);
+        return 2;
+    }
+    if (parsed.values.help) {
+        io.stdout(USAGE);
+        return 0;
+    }
+    const env = resolveEnv(global, io.env);
+    try {
+        assertStackVersionCompatible(env.contextDir);
+    }
+    catch (err) {
+        io.stderr(`${err.message}\n`);
+        return 1;
+    }
+    let params = null;
+    if (parsed.values.name || parsed.values.purpose || parsed.values.voice || parsed.values.user) {
+        if (!parsed.values.name || !parsed.values.purpose || !parsed.values.voice) {
+            io.stderr(`When using flags, --name, --purpose, and --voice are all required.\n`);
+            return 2;
+        }
+        const clientsCsv = parsed.values.clients;
+        params = {
+            user: parsed.values.user,
+            name: parsed.values.name,
+            purpose: parsed.values.purpose,
+            voice: parsed.values.voice,
+            preferences: parsed.values.preferences,
+            clients: clientsCsv ? clientsCsv.split(',').map((s) => s.trim()).filter(Boolean) : undefined,
+            force: Boolean(parsed.values.force),
+        };
+    }
+    else if (!io.stdinIsTTY) {
+        const raw = await readStdin(io.stdin);
+        const trimmed = raw.trim();
+        if (!trimmed) {
+            io.stderr(`No bootstrap params supplied (no flags, no stdin, no TTY).\n${USAGE}`);
+            return 2;
+        }
+        try {
+            const body = JSON.parse(trimmed);
+            if (!body.name || !body.purpose || !body.voice) {
+                io.stderr(`Piped JSON must include name, purpose, and voice.\n`);
+                return 2;
+            }
+            params = {
+                user: body.user,
+                name: body.name, purpose: body.purpose, voice: body.voice,
+                preferences: body.preferences, clients: body.clients,
+                force: Boolean(parsed.values.force),
+            };
+        }
+        catch (err) {
+            io.stderr(`Could not parse stdin as JSON: ${err.message}\n`);
+            return 2;
+        }
+    }
+    else {
+        const prompted = await promptInteractive(io);
+        if (!prompted || !prompted.name || !prompted.purpose || !prompted.voice) {
+            io.stderr(`name, purpose, and voice are all required.\n`);
+            return 2;
+        }
+        params = { ...prompted, force: Boolean(parsed.values.force) };
+    }
+    const nameCode = checkName(params.name, io);
+    if (nameCode !== null)
+        return nameCode;
+    try {
+        // params is always set by this point — all null paths return early above.
+        const text = await bootstrap(env.contextDir, params);
+        // Provision the default symlink if the new agent dir is directly under
+        // the loom config root and no default pointer exists yet.
+        const home = io.env.HOME ?? process.env.HOME;
+        const defaultLink = resolveDefaultContextPath(home);
+        if (dirname(env.contextDir) === dirname(defaultLink) && env.contextDir !== defaultLink) {
+            try {
+                await lstat(defaultLink); // throws if default doesn't exist at all
+            }
+            catch {
+                // default doesn't exist — create symlink
+                try {
+                    await symlink(env.contextDir, defaultLink);
+                    if (!env.json) {
+                        io.stdout(`Created default pointer: ${defaultLink} -> ${env.contextDir}\n`);
+                    }
+                }
+                catch {
+                    // Non-fatal: symlink creation may fail in sandboxed or read-only environments
+                }
+            }
+        }
+        if (env.json) {
+            renderJson(io, {
+                contextDir: env.contextDir,
+                wrote: [
+                    join(env.contextDir, 'IDENTITY.md'),
+                    join(env.contextDir, 'preferences.md'),
+                    join(env.contextDir, 'self-model.md'),
+                ],
+            });
+        }
+        else {
+            io.stdout(text.endsWith('\n') ? text : text + '\n');
+        }
+        return 0;
+    }
+    catch (err) {
+        io.stderr(`${err.message}\n`);
+        return 1;
+    }
+}

package/dist/cli/doctor.d.ts

@@ -0,0 +1,2 @@
+import type { IOStreams } from './io.js';
+export declare function run(argv: string[], io: IOStreams): Promise<number>;