@poa-box/agent 0.1.0

package/dist/commands/brain/remove-lesson.d.ts

@@ -0,0 +1,47 @@
+/**
+ * pop brain remove-lesson — mark an existing lesson as soft-deleted.
+ *
+ * Sets a tombstone on the lesson object:
+ *
+ *   {
+ *     removed: true,
+ *     removedAt: <unix-seconds>,
+ *     removedBy: <signing wallet address>,
+ *     removedReason: <optional --reason string>
+ *   }
+ *
+ * The lesson stays in doc.lessons — the projection layer filters
+ * tombstoned entries out of rendered markdown. This is the CRDT-safe
+ * shape: hard delete from an Automerge list can lose concurrent edits,
+ * and two concurrent soft-deletes converge via last-write-wins at the
+ * field level (adding `removed: true` twice is idempotent).
+ *
+ * No --undo / --restore in this ship. If we need undelete later, the
+ * shape is another field like `restoredAt` that supersedes removedAt.
+ */
+import type { Argv, ArgumentsCamelCase } from 'yargs';
+interface RemoveArgs {
+    doc: string;
+    lessonId: string;
+    reason?: string;
+    allowInvalidShape?: boolean;
+    'idempotency-key'?: string;
+    'no-idempotency'?: boolean;
+}
+export declare const removeLessonHandler: {
+    builder: (yargs: Argv) => Argv<{
+        doc: string;
+    } & {
+        "lesson-id": string;
+    } & {
+        reason: string | undefined;
+    } & {
+        "allow-invalid-shape": boolean;
+    } & {
+        "idempotency-key": string | undefined;
+    } & {
+        "no-idempotency": boolean;
+    }>;
+    handler: (argv: ArgumentsCamelCase<RemoveArgs>) => Promise<void>;
+};
+export {};

package/dist/commands/brain/remove-lesson.js

@@ -0,0 +1,206 @@
+"use strict";
+/**
+ * pop brain remove-lesson — mark an existing lesson as soft-deleted.
+ *
+ * Sets a tombstone on the lesson object:
+ *
+ *   {
+ *     removed: true,
+ *     removedAt: <unix-seconds>,
+ *     removedBy: <signing wallet address>,
+ *     removedReason: <optional --reason string>
+ *   }
+ *
+ * The lesson stays in doc.lessons — the projection layer filters
+ * tombstoned entries out of rendered markdown. This is the CRDT-safe
+ * shape: hard delete from an Automerge list can lose concurrent edits,
+ * and two concurrent soft-deletes converge via last-write-wins at the
+ * field level (adding `removed: true` twice is idempotent).
+ *
+ * No --undo / --restore in this ship. If we need undelete later, the
+ * shape is another field like `restoredAt` that supersedes removedAt.
+ */
+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.removeLessonHandler = void 0;
+const ethers_1 = require("ethers");
+const brain_1 = require("../../lib/brain");
+const brain_ops_1 = require("../../lib/brain-ops");
+const idempotency_1 = require("@poa-box/cli/lib/idempotency");
+const output = __importStar(require("@poa-box/cli/lib/output"));
+exports.removeLessonHandler = {
+    builder: (yargs) => yargs
+        .option('doc', {
+        describe: 'Brain document ID (e.g. pop.brain.shared)',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('lesson-id', {
+        describe: 'The lesson.id to tombstone',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('reason', {
+        describe: 'Optional human-readable reason recorded on the tombstone',
+        type: 'string',
+    })
+        .option('allow-invalid-shape', {
+        describe: 'Bypass write-time schema validation (Task #346).',
+        type: 'boolean',
+        default: false,
+    })
+        .option('idempotency-key', {
+        type: 'string',
+        describe: 'Task #374 (HB#215): explicit idempotency key. Agent-scoped.',
+    })
+        .option('no-idempotency', {
+        type: 'boolean',
+        default: false,
+        describe: 'Bypass the idempotency cache.',
+    }),
+    handler: async (argv) => {
+        try {
+            // Pre-flight peek: locate the lesson, fail fast with candidate
+            // ids if not found. Same pattern as edit-lesson.
+            const { doc: currentDoc } = await (0, brain_1.openBrainDoc)(argv.doc);
+            const lessons = Array.isArray(currentDoc?.lessons) ? currentDoc.lessons : [];
+            const target = lessons.find((l) => l?.id === argv.lessonId);
+            if (!target) {
+                const candidates = lessons
+                    .map((l) => l?.id)
+                    .filter((id) => typeof id === 'string')
+                    .slice(0, 8);
+                output.error(`Lesson "${argv.lessonId}" not found in ${argv.doc}. ` +
+                    `Available ids (first 8): ${candidates.join(', ') || '(none)'}`);
+                process.exitCode = 1;
+                return;
+            }
+            // Already tombstoned — short-circuit.
+            if (target.removed === true) {
+                if (output.isJsonMode()) {
+                    output.json({
+                        status: 'already-removed',
+                        docId: argv.doc,
+                        lessonId: argv.lessonId,
+                        removedAt: target.removedAt,
+                        removedBy: target.removedBy,
+                    });
+                }
+                else {
+                    console.log(`Lesson "${argv.lessonId}" is already tombstoned ` +
+                        `(removedAt=${target.removedAt}, removedBy=${target.removedBy}). No-op.`);
+                }
+                return;
+            }
+            // Derive the remover address from POP_PRIVATE_KEY so the
+            // tombstone's removedBy matches the signing envelope's author.
+            const key = process.env.POP_PRIVATE_KEY;
+            if (!key) {
+                output.error('POP_PRIVATE_KEY not set — cannot record removedBy. Set the env var and retry.');
+                process.exitCode = 1;
+                return;
+            }
+            const removerAddress = new ethers_1.ethers.Wallet(key).address.toLowerCase();
+            const now = Math.floor(Date.now() / 1000);
+            // Task #374: idempotency check (agent-scoped, uses removerAddress)
+            const idempKey = argv.idempotencyKey || (0, idempotency_1.argvToIdempotencyString)(argv);
+            if (!argv.noIdempotency) {
+                const cached = (0, idempotency_1.checkIdempotencyCache)(removerAddress, 'brain.removeLesson', idempKey);
+                if (cached) {
+                    if (output.isJsonMode()) {
+                        output.json({ status: 'ok', cached: true, ...cached });
+                    }
+                    else {
+                        console.log('');
+                        console.log(`  Lesson "${argv.lessonId}" already removed (idempotency cache hit)`);
+                        console.log(`  head:   ${cached.headCid}`);
+                        console.log('');
+                    }
+                    return;
+                }
+            }
+            // Route through the unified dispatcher (HB#324 ship-2).
+            const result = await (0, brain_ops_1.routedDispatch)({
+                type: 'removeLesson',
+                docId: argv.doc,
+                lessonId: argv.lessonId,
+                removedBy: removerAddress,
+                removedAt: now,
+                removedReason: argv.reason,
+                allowInvalidShape: argv.allowInvalidShape,
+            });
+            if (!argv.noIdempotency) {
+                (0, idempotency_1.recordIdempotentResult)(removerAddress, 'brain.removeLesson', idempKey, {
+                    docId: argv.doc,
+                    lessonId: argv.lessonId,
+                    headCid: result.headCid,
+                });
+            }
+            if (output.isJsonMode()) {
+                output.json({
+                    status: 'ok',
+                    docId: argv.doc,
+                    lessonId: argv.lessonId,
+                    headCid: result.headCid,
+                    routedViaDaemon: result.routedViaDaemon,
+                    removedAt: now,
+                    removedBy: removerAddress,
+                    removedReason: argv.reason ?? null,
+                });
+            }
+            else {
+                console.log('');
+                console.log(`  Lesson "${argv.lessonId}" tombstoned in ${argv.doc}`);
+                console.log(`  removedBy: ${removerAddress}`);
+                console.log(`  removedAt: ${new Date(now * 1000).toISOString()}`);
+                if (argv.reason)
+                    console.log(`  reason:    ${argv.reason}`);
+                console.log(`  new head:  ${result.headCid}`);
+                console.log(`  routed:    ${result.routedViaDaemon ? 'via brain daemon' : 'in-process (no daemon)'}`);
+                console.log('');
+                console.log(`  The lesson is still in the Automerge doc (pop brain read still shows it). ` +
+                    `The next pop brain snapshot will filter it out of the rendered markdown.`);
+                console.log('');
+            }
+        }
+        catch (err) {
+            output.error(err.message);
+            process.exitCode = 1;
+        }
+        finally {
+            await (0, brain_1.stopBrainNode)();
+        }
+    },
+};

package/dist/commands/brain/remove-project.d.ts

@@ -0,0 +1,36 @@
+/**
+ * pop brain remove-project — soft-delete a project entry in pop.brain.projects.
+ *
+ * Mirror of remove-lesson (#304). Sets {removed: true, removedAt,
+ * removedBy, removedReason?} on the project object. The raw Automerge
+ * state is unchanged; projectProjects filters tombstoned projects
+ * out of the main Projects section and surfaces a compact '## Removed
+ * projects' summary at the bottom.
+ *
+ * Soft delete stays CRDT-safe: concurrent tombstones are idempotent
+ * at the field-level LWW, and concurrent edits to a project that's
+ * tombstoned concurrently still converge cleanly.
+ */
+import type { Argv, ArgumentsCamelCase } from 'yargs';
+interface RemoveProjectArgs {
+    doc: string;
+    projectId: string;
+    reason?: string;
+    'idempotency-key'?: string;
+    'no-idempotency'?: boolean;
+}
+export declare const removeProjectHandler: {
+    builder: (yargs: Argv) => Argv<{
+        doc: string;
+    } & {
+        "project-id": string;
+    } & {
+        reason: string | undefined;
+    } & {
+        "idempotency-key": string | undefined;
+    } & {
+        "no-idempotency": boolean;
+    }>;
+    handler: (argv: ArgumentsCamelCase<RemoveProjectArgs>) => Promise<void>;
+};
+export {};

package/dist/commands/brain/remove-project.js

@@ -0,0 +1,177 @@
+"use strict";
+/**
+ * pop brain remove-project — soft-delete a project entry in pop.brain.projects.
+ *
+ * Mirror of remove-lesson (#304). Sets {removed: true, removedAt,
+ * removedBy, removedReason?} on the project object. The raw Automerge
+ * state is unchanged; projectProjects filters tombstoned projects
+ * out of the main Projects section and surfaces a compact '## Removed
+ * projects' summary at the bottom.
+ *
+ * Soft delete stays CRDT-safe: concurrent tombstones are idempotent
+ * at the field-level LWW, and concurrent edits to a project that's
+ * tombstoned concurrently still converge cleanly.
+ */
+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.removeProjectHandler = void 0;
+const ethers_1 = require("ethers");
+const brain_1 = require("../../lib/brain");
+const brain_ops_1 = require("../../lib/brain-ops");
+const idempotency_1 = require("@poa-box/cli/lib/idempotency");
+const output = __importStar(require("@poa-box/cli/lib/output"));
+exports.removeProjectHandler = {
+    builder: (yargs) => yargs
+        .option('doc', {
+        describe: 'Brain document ID (typically pop.brain.projects)',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('project-id', {
+        describe: 'The project.id to tombstone',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('reason', {
+        describe: 'Optional human-readable reason recorded on the tombstone',
+        type: 'string',
+    })
+        .option('idempotency-key', { type: 'string', describe: 'Task #375 (HB#217) idempotency cache.' })
+        .option('no-idempotency', { type: 'boolean', default: false, describe: 'Bypass the idempotency cache.' }),
+    handler: async (argv) => {
+        try {
+            const { doc: currentDoc } = await (0, brain_1.openBrainDoc)(argv.doc);
+            const projects = Array.isArray(currentDoc?.projects) ? currentDoc.projects : [];
+            const target = projects.find((p) => p?.id === argv.projectId);
+            if (!target) {
+                const candidates = projects
+                    .map((p) => p?.id)
+                    .filter((id) => typeof id === 'string')
+                    .slice(0, 8);
+                output.error(`Project "${argv.projectId}" not found in ${argv.doc}. ` +
+                    `Available ids (first 8): ${candidates.join(', ') || '(none)'}`);
+                process.exitCode = 1;
+                return;
+            }
+            if (target.removed === true) {
+                if (output.isJsonMode()) {
+                    output.json({
+                        status: 'already-removed',
+                        docId: argv.doc,
+                        projectId: argv.projectId,
+                        removedAt: target.removedAt,
+                        removedBy: target.removedBy,
+                    });
+                }
+                else {
+                    console.log(`Project "${argv.projectId}" is already tombstoned ` +
+                        `(removedAt=${target.removedAt}, removedBy=${target.removedBy}). No-op.`);
+                }
+                return;
+            }
+            const key = process.env.POP_PRIVATE_KEY;
+            if (!key) {
+                output.error('POP_PRIVATE_KEY not set — cannot record removedBy. Set the env var and retry.');
+                process.exitCode = 1;
+                return;
+            }
+            const removerAddress = new ethers_1.ethers.Wallet(key).address.toLowerCase();
+            const now = Math.floor(Date.now() / 1000);
+            // Task #375 (HB#217): agent-scoped idempotency cache
+            const idempKey = argv.idempotencyKey || (0, idempotency_1.argvToIdempotencyString)(argv);
+            if (!argv.noIdempotency) {
+                const cached = (0, idempotency_1.checkIdempotencyCache)(removerAddress, 'brain.removeProject', idempKey);
+                if (cached) {
+                    if (output.isJsonMode()) {
+                        output.json({ status: 'ok', cached: true, ...cached });
+                    }
+                    else {
+                        console.log(`  Project "${argv.projectId}" already removed (idempotency cache hit). head: ${cached.headCid}`);
+                    }
+                    return;
+                }
+            }
+            // Route through the unified dispatcher (HB#324 ship-2).
+            const result = await (0, brain_ops_1.routedDispatch)({
+                type: 'removeProject',
+                docId: argv.doc,
+                projectId: argv.projectId,
+                removedBy: removerAddress,
+                removedAt: now,
+                removedReason: argv.reason,
+            });
+            if (!argv.noIdempotency) {
+                (0, idempotency_1.recordIdempotentResult)(removerAddress, 'brain.removeProject', idempKey, {
+                    docId: argv.doc,
+                    projectId: argv.projectId,
+                    headCid: result.headCid,
+                });
+            }
+            if (output.isJsonMode()) {
+                output.json({
+                    status: 'ok',
+                    docId: argv.doc,
+                    projectId: argv.projectId,
+                    headCid: result.headCid,
+                    routedViaDaemon: result.routedViaDaemon,
+                    removedAt: now,
+                    removedBy: removerAddress,
+                    removedReason: argv.reason ?? null,
+                });
+            }
+            else {
+                console.log('');
+                console.log(`  Project "${argv.projectId}" tombstoned in ${argv.doc}`);
+                console.log(`  removedBy: ${removerAddress}`);
+                console.log(`  removedAt: ${new Date(now * 1000).toISOString()}`);
+                if (argv.reason)
+                    console.log(`  reason:    ${argv.reason}`);
+                console.log(`  new head:  ${result.headCid}`);
+                console.log(`  routed:    ${result.routedViaDaemon ? 'via brain daemon' : 'in-process (no daemon)'}`);
+                console.log('');
+                console.log(`  The project is still in the Automerge doc (pop brain read still shows it). ` +
+                    `The next pop brain snapshot will filter it out of the rendered markdown.`);
+                console.log('');
+            }
+        }
+        catch (err) {
+            output.error(err.message);
+            process.exitCode = 1;
+        }
+        finally {
+            await (0, brain_1.stopBrainNode)();
+        }
+    },
+};

package/dist/commands/brain/retro-file-tasks.d.ts

@@ -0,0 +1,84 @@
+/**
+ * pop brain retro file-tasks — convert agreed retro changes into on-chain tasks.
+ *
+ * Usage:
+ *
+ *   pop brain retro file-tasks --retro retro-327-1776...
+ *   pop brain retro file-tasks --retro retro-327-1776... --dry-run
+ *   pop brain retro file-tasks --retro retro-327-1776... --project "CLI Infrastructure"
+ *
+ * Flow:
+ *
+ *   1. Load the retro from pop.brain.retros.
+ *   2. Find every proposed change whose status is 'agreed'. Changes at any
+ *      other status are skipped — 'proposed' needs more discussion first,
+ *      'rejected' was explicitly rejected, 'modified' needs a second round,
+ *      and 'filed' is already done (this is the idempotency guarantee:
+ *      re-running the command is safe because filed changes are no-ops).
+ *   3. For each agreed change:
+ *      a. Call `pop task create` with a structured description derived
+ *         from the change summary + details + retro window.
+ *      b. Capture the returned task id.
+ *      c. Run `updateChangeStatus` to flip the change to 'filed' with
+ *         filedTaskId set.
+ *   4. When every change is filed or rejected, the updateChangeStatus op
+ *      auto-advances the retro status to 'shipped' with a closedAt
+ *      timestamp.
+ *
+ * ## Idempotency
+ *
+ * This command is safe to run multiple times. A change with status='filed'
+ * is skipped. A change that was already converted won't be re-filed. The
+ * idempotency guarantee requires the `agreed → filed` transition to be
+ * the only way a change gets converted. Operators who want to re-file a
+ * change after filing it should run `pop brain retro respond --vote
+ * change-X=agree` again and then call file-tasks — but the previous
+ * filed task id is never overwritten, so the old task sticks around
+ * unless manually cancelled. That's a deliberate safety design: no
+ * accidental re-filing of the same work.
+ *
+ * ## Dry-run
+ *
+ * `--dry-run` prints the plan (which changes would be filed, what task
+ * description would be produced) without actually creating any tasks or
+ * mutating the retro. Use this to preview before committing.
+ *
+ * ## Project selection
+ *
+ * Defaults to "CLI Infrastructure" — the historical catch-all for brain
+ * layer + CLI work. Override with --project if the retro's proposed
+ * changes belong to a different project (e.g. "DeFi Research",
+ * "Agent Protocol").
+ */
+import type { Argv, ArgumentsCamelCase } from 'yargs';
+interface RetroFileTasksArgs {
+    doc: string;
+    retro: string;
+    project?: string;
+    payout?: number;
+    difficulty?: 'easy' | 'medium' | 'hard';
+    estHours?: number;
+    dryRun?: boolean;
+    yes?: boolean;
+}
+export declare const retroFileTasksHandler: {
+    builder: (yargs: Argv) => Argv<{
+        doc: string;
+    } & {
+        retro: string;
+    } & {
+        project: string;
+    } & {
+        payout: number;
+    } & {
+        difficulty: "medium" | "easy" | "hard";
+    } & {
+        "est-hours": number;
+    } & {
+        "dry-run": boolean;
+    } & {
+        yes: boolean;
+    }>;
+    handler: (argv: ArgumentsCamelCase<RetroFileTasksArgs>) => Promise<void>;
+};
+export {};