@poa-box/agent 0.1.0

package/dist/commands/brain/retro-show.js

@@ -0,0 +1,100 @@
+"use strict";
+/**
+ * pop brain retro show — render a single retro as markdown.
+ *
+ * Loads the retro doc, extracts the requested retro, and runs it
+ * through the projection layer. Same shape + schema as projectRetros
+ * produces for the full doc snapshot, but scoped to one entry.
+ *
+ * Pure read path — no daemon routing required.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.retroShowHandler = void 0;
+const brain_1 = require("../../lib/brain");
+const brain_projections_1 = require("../../lib/brain-projections");
+const output = __importStar(require("@poa-box/cli/lib/output"));
+exports.retroShowHandler = {
+    builder: (yargs) => yargs
+        .positional('retro-id', {
+        describe: 'The retro.id to show',
+        type: 'string',
+    })
+        .option('doc', {
+        describe: 'Brain document ID (default: pop.brain.retros)',
+        type: 'string',
+        default: 'pop.brain.retros',
+    })
+        .demandOption('retro-id'),
+    handler: async (argv) => {
+        try {
+            const { doc, headCid } = await (0, brain_1.openBrainDoc)(argv.doc);
+            const retros = Array.isArray(doc?.retros) ? doc.retros : [];
+            const target = retros.find(r => r?.id === argv.retroId);
+            if (!target) {
+                const candidates = retros
+                    .map(r => r?.id)
+                    .filter((id) => typeof id === 'string')
+                    .slice(0, 8);
+                output.error(`Retro "${argv.retroId}" not found in ${argv.doc}. ` +
+                    `Available ids (first 8): ${candidates.join(', ') || '(none)'}`);
+                process.exitCode = 1;
+                return;
+            }
+            if (output.isJsonMode()) {
+                output.json({
+                    docId: argv.doc,
+                    headCid,
+                    retro: target,
+                });
+                return;
+            }
+            // Render the ONE retro through the projection layer by wrapping
+            // it in a synthetic single-retro doc. This keeps the output
+            // format identical to what `pop brain snapshot` would produce,
+            // so reviewers see the same rendered structure whether they're
+            // looking at a live retro or a committed snapshot.
+            const markdown = (0, brain_projections_1.projectRetros)({ retros: [target] }, headCid);
+            console.log(markdown);
+        }
+        catch (err) {
+            output.error(err.message);
+            process.exitCode = 1;
+        }
+        finally {
+            await (0, brain_1.stopBrainNode)();
+        }
+    },
+};

package/dist/commands/brain/retro-start.d.ts

@@ -0,0 +1,55 @@
+/**
+ * pop brain retro start — create a new retrospective entry in pop.brain.retros.
+ *
+ * Input:
+ *   --window-from <HB#>        lower bound of the HB window covered
+ *   --window-to <HB#>          upper bound of the HB window covered
+ *   --observations-file <path> markdown file with "## What worked" and
+ *                              "## What didn't work" sections (both optional)
+ *   --changes-file <path>      JSON or markdown file listing proposed
+ *                              changes. JSON shape is an array of
+ *                              {id, summary, details?} objects;
+ *                              markdown shape is `- **change-1** — summary`
+ *                              lines (details on the next indented line).
+ *   --id <retro-id>            optional override (default: retro-<hb>-<unix>)
+ *   --author <label>           optional override (default: signing address)
+ *   --doc <doc-id>             default: pop.brain.retros
+ *
+ * The retro is written via routedDispatch so it lands in a running daemon
+ * when present and falls back to in-process applyBrainChange otherwise.
+ * Schema validation happens inside dispatchOp at write time — empty
+ * changes list, bad window, duplicate change ids all fail fast with a
+ * clear error.
+ */
+import type { Argv, ArgumentsCamelCase } from 'yargs';
+interface RetroStartArgs {
+    doc: string;
+    windowFrom: number;
+    windowTo: number;
+    observationsFile?: string;
+    changesFile: string;
+    id?: string;
+    author?: string;
+    hb?: number;
+}
+export declare const retroStartHandler: {
+    builder: (yargs: Argv) => Argv<{
+        doc: string;
+    } & {
+        "window-from": number;
+    } & {
+        "window-to": number;
+    } & {
+        "observations-file": string | undefined;
+    } & {
+        "changes-file": string;
+    } & {
+        id: string | undefined;
+    } & {
+        author: string | undefined;
+    } & {
+        hb: number | undefined;
+    }>;
+    handler: (argv: ArgumentsCamelCase<RetroStartArgs>) => Promise<void>;
+};
+export {};

package/dist/commands/brain/retro-start.js

@@ -0,0 +1,311 @@
+"use strict";
+/**
+ * pop brain retro start — create a new retrospective entry in pop.brain.retros.
+ *
+ * Input:
+ *   --window-from <HB#>        lower bound of the HB window covered
+ *   --window-to <HB#>          upper bound of the HB window covered
+ *   --observations-file <path> markdown file with "## What worked" and
+ *                              "## What didn't work" sections (both optional)
+ *   --changes-file <path>      JSON or markdown file listing proposed
+ *                              changes. JSON shape is an array of
+ *                              {id, summary, details?} objects;
+ *                              markdown shape is `- **change-1** — summary`
+ *                              lines (details on the next indented line).
+ *   --id <retro-id>            optional override (default: retro-<hb>-<unix>)
+ *   --author <label>           optional override (default: signing address)
+ *   --doc <doc-id>             default: pop.brain.retros
+ *
+ * The retro is written via routedDispatch so it lands in a running daemon
+ * when present and falls back to in-process applyBrainChange otherwise.
+ * Schema validation happens inside dispatchOp at write time — empty
+ * changes list, bad window, duplicate change ids all fail fast with a
+ * clear error.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.retroStartHandler = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const ethers_1 = require("ethers");
+const brain_1 = require("../../lib/brain");
+const brain_ops_1 = require("../../lib/brain-ops");
+const output = __importStar(require("@poa-box/cli/lib/output"));
+/**
+ * Parse the observations file. Expects a markdown document with
+ * `## What worked` and `## What didn't work` sections. Both sections
+ * are optional; sections outside those two are ignored.
+ */
+function parseObservationsFile(content) {
+    const result = {};
+    // Split into sections on H2 headers. The regex keeps the header text
+    // as a capture so we can dispatch on it.
+    const sections = content.split(/^##\s+/m).slice(1);
+    for (const section of sections) {
+        const nl = section.indexOf('\n');
+        if (nl < 0)
+            continue;
+        const header = section.slice(0, nl).trim().toLowerCase();
+        const body = section.slice(nl + 1).trim();
+        if (!body)
+            continue;
+        if (/worked/i.test(header) && !/didn/i.test(header)) {
+            result.worked = body;
+        }
+        else if (/didn.?t\s*work|didntwork|not\s*work/i.test(header)) {
+            result.didntWork = body;
+        }
+        // Silently drop other sections — they might be "Next actions" or
+        // similar that don't belong in observations.
+    }
+    return result;
+}
+/**
+ * Parse the proposed-changes file. Supports two shapes:
+ *
+ * 1. JSON: `[{"id": "change-1", "summary": "...", "details": "..."}, ...]`
+ * 2. Markdown: `- **change-1** — summary\n  details (indented)\n- **change-2** — ...`
+ *
+ * JSON is tried first. If parse fails, fall back to markdown scanning.
+ */
+function parseChangesFile(content) {
+    // Try JSON first.
+    const trimmed = content.trim();
+    if (trimmed.startsWith('[') || trimmed.startsWith('{')) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            const items = Array.isArray(parsed) ? parsed : parsed.changes ?? [];
+            return items.map((item) => {
+                if (!item.id || !item.summary) {
+                    throw new Error(`change entry missing id or summary: ${JSON.stringify(item)}`);
+                }
+                const out = {
+                    id: String(item.id),
+                    summary: String(item.summary),
+                };
+                if (item.details)
+                    out.details = String(item.details);
+                return out;
+            });
+        }
+        catch (err) {
+            throw new Error(`Failed to parse changes file as JSON: ${err.message}`);
+        }
+    }
+    // Markdown: bullet lines that start with `- **<id>**`. Anything
+    // indented under a bullet belongs to that change's details.
+    const changes = [];
+    const lines = content.split('\n');
+    let current = null;
+    const detailLines = [];
+    const commit = () => {
+        if (!current)
+            return;
+        if (detailLines.length > 0) {
+            current.details = detailLines.join('\n').trim();
+        }
+        changes.push(current);
+        current = null;
+        detailLines.length = 0;
+    };
+    const bulletRe = /^-\s+\*\*([^*]+)\*\*\s*[—–-]\s*(.+)$/;
+    for (const rawLine of lines) {
+        const m = rawLine.match(bulletRe);
+        if (m) {
+            commit();
+            current = { id: m[1].trim(), summary: m[2].trim() };
+            continue;
+        }
+        if (current && /^\s+\S/.test(rawLine)) {
+            detailLines.push(rawLine.replace(/^\s+/, ''));
+        }
+    }
+    commit();
+    if (changes.length === 0) {
+        throw new Error('Failed to parse changes file as markdown — expected bullet lines ' +
+            'like `- **change-1** — summary`. Try JSON format instead.');
+    }
+    return changes;
+}
+exports.retroStartHandler = {
+    builder: (yargs) => yargs
+        .option('doc', {
+        describe: 'Target brain document ID (default: pop.brain.retros)',
+        type: 'string',
+        default: 'pop.brain.retros',
+    })
+        .option('window-from', {
+        describe: 'First HB number covered by this retro',
+        type: 'number',
+        demandOption: true,
+    })
+        .option('window-to', {
+        describe: 'Last HB number covered by this retro',
+        type: 'number',
+        demandOption: true,
+    })
+        .option('observations-file', {
+        describe: 'Markdown file with `## What worked` and `## What didn\'t work` sections',
+        type: 'string',
+    })
+        .option('changes-file', {
+        describe: 'JSON or markdown file listing proposed changes. JSON: array of {id, summary, details?}. Markdown: bullet list with `- **id** — summary`.',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('id', {
+        describe: 'Override the auto-generated retro id (default: retro-<hb>-<unix>)',
+        type: 'string',
+    })
+        .option('author', {
+        describe: 'Override the author label (default: signing wallet address)',
+        type: 'string',
+    })
+        .option('hb', {
+        describe: 'Heartbeat number at retro start (default: window-to)',
+        type: 'number',
+    }),
+    handler: async (argv) => {
+        try {
+            if (argv.windowFrom > argv.windowTo) {
+                output.error(`--window-from (${argv.windowFrom}) must be <= --window-to (${argv.windowTo})`);
+                process.exitCode = 1;
+                return;
+            }
+            // Resolve author.
+            let authorLabel;
+            if (argv.author) {
+                authorLabel = argv.author;
+            }
+            else {
+                const key = process.env.POP_PRIVATE_KEY;
+                if (!key) {
+                    output.error('POP_PRIVATE_KEY not set — cannot derive default author. Pass --author explicitly.');
+                    process.exitCode = 1;
+                    return;
+                }
+                authorLabel = new ethers_1.ethers.Wallet(key).address.toLowerCase();
+            }
+            // Read observations file if provided.
+            let observations = {};
+            if (argv.observationsFile) {
+                const p = (0, path_1.resolve)(argv.observationsFile);
+                if (!(0, fs_1.existsSync)(p)) {
+                    output.error(`--observations-file not found: ${p}`);
+                    process.exitCode = 1;
+                    return;
+                }
+                const content = (0, fs_1.readFileSync)(p, 'utf8');
+                observations = parseObservationsFile(content);
+            }
+            // Read + parse changes file.
+            const changesPath = (0, path_1.resolve)(argv.changesFile);
+            if (!(0, fs_1.existsSync)(changesPath)) {
+                output.error(`--changes-file not found: ${changesPath}`);
+                process.exitCode = 1;
+                return;
+            }
+            const changesContent = (0, fs_1.readFileSync)(changesPath, 'utf8');
+            let proposedChanges;
+            try {
+                proposedChanges = parseChangesFile(changesContent);
+            }
+            catch (err) {
+                output.error(err.message);
+                process.exitCode = 1;
+                return;
+            }
+            if (proposedChanges.length === 0) {
+                output.error('Changes file produced zero entries — retros must have at least one proposed change');
+                process.exitCode = 1;
+                return;
+            }
+            const now = Math.floor(Date.now() / 1000);
+            const hb = argv.hb ?? argv.windowTo;
+            const retroId = argv.id ?? `retro-${hb}-${now}`;
+            const result = await (0, brain_ops_1.routedDispatch)({
+                type: 'startRetro',
+                docId: argv.doc,
+                retroId,
+                author: authorLabel,
+                hb,
+                window: { from: argv.windowFrom, to: argv.windowTo },
+                observations,
+                proposedChanges,
+                createdAt: now,
+            });
+            if (output.isJsonMode()) {
+                output.json({
+                    status: 'ok',
+                    docId: argv.doc,
+                    retroId,
+                    hb,
+                    window: { from: argv.windowFrom, to: argv.windowTo },
+                    author: authorLabel,
+                    changeCount: proposedChanges.length,
+                    changeIds: proposedChanges.map(c => c.id),
+                    headCid: result.headCid,
+                    envelopeAuthor: result.envelopeAuthor,
+                    routedViaDaemon: result.routedViaDaemon,
+                });
+            }
+            else {
+                console.log('');
+                console.log(`  Retro started in ${argv.doc}`);
+                console.log(`  id:        ${retroId}`);
+                console.log(`  window:    HB#${argv.windowFrom}..HB#${argv.windowTo}`);
+                console.log(`  author:    ${authorLabel}`);
+                console.log(`  changes:   ${proposedChanges.length} proposed`);
+                for (const c of proposedChanges) {
+                    console.log(`    - ${c.id}: ${c.summary}`);
+                }
+                console.log(`  head:      ${result.headCid}`);
+                console.log(`  routed:    ${result.routedViaDaemon ? 'via brain daemon' : 'in-process (no daemon)'}`);
+                console.log('');
+                console.log(`  Next steps: other agents run "pop brain retro respond --to ${retroId}" ` +
+                    `to discuss proposed changes. When changes are agreed, run ` +
+                    `"pop brain retro file-tasks --retro ${retroId}" to convert them to on-chain tasks.`);
+                console.log('');
+            }
+        }
+        catch (err) {
+            output.error(err.message);
+            process.exitCode = 1;
+        }
+        finally {
+            await (0, brain_1.stopBrainNode)();
+        }
+    },
+};

package/dist/commands/brain/search.d.ts

@@ -0,0 +1,48 @@
+/**
+ * pop brain search — keyword / tag / author / HB filters over brain lesson docs.
+ *
+ * Task #347 (Retro #1 fallback #6). The pop.brain.shared / pop.brain.lessons
+ * doc has grown past the "cold read is cheap" threshold. Agents reaching for
+ * "is there a lesson about X" were grepping heartbeat-log.md as a faster
+ * proxy, which defeated the purpose of the canonical lesson substrate.
+ * This command makes lesson search cheaper than log grep.
+ *
+ * Filters compose as AND:
+ *   --query    case-insensitive substring match over title + body
+ *   --tag      exact tag match (one tag per invocation; run twice to AND)
+ *   --author   exact author match (0x lowercase)
+ *   --since    HB number: only lessons with timestamp >= the HB's wall-clock.
+ *              Heuristic — the HB number is not stored on the lesson; we
+ *              approximate by comparing the lesson timestamp against a
+ *              provided unix-seconds lower bound passed as --since-ts.
+ *
+ * Output is ranked by timestamp descending (most recent first) since that's
+ * the useful default for "what happened lately about X". JSON mode for
+ * programmatic consumption.
+ */
+import type { Argv, ArgumentsCamelCase } from 'yargs';
+interface SearchArgs {
+    doc: string;
+    query?: string;
+    tag?: string;
+    author?: string;
+    sinceTs?: number;
+    limit?: number;
+}
+export declare const searchHandler: {
+    builder: (yargs: Argv) => Argv<{
+        doc: string;
+    } & {
+        query: string | undefined;
+    } & {
+        tag: string | undefined;
+    } & {
+        author: string | undefined;
+    } & {
+        "since-ts": number | undefined;
+    } & {
+        limit: number;
+    }>;
+    handler: (argv: ArgumentsCamelCase<SearchArgs>) => Promise<void>;
+};
+export {};