@poa-box/agent 0.1.0

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

@@ -0,0 +1,245 @@
+"use strict";
+/**
+ * pop brain append-lesson — user-facing write path into the CRDT brain
+ * substrate. Thin wrapper over applyBrainChange that pushes a lesson
+ * object onto `doc.lessons` and auto-publishes the new head via
+ * gossipsub (step 5) + seeds it for Bitswap (step 6).
+ *
+ * Before this command, writing a lesson required a Node script that
+ * imported dist/lib/brain.js and called applyBrainChange manually.
+ * This command closes the last ergonomic gap before the brain
+ * substrate is day-to-day usable for heartbeat work.
+ *
+ * Usage:
+ *   pop brain append-lesson --doc pop.brain.shared \
+ *     --title "Don't upgrade libp2p past 2.x" \
+ *     --body "gossipsub 14 crashes on libp2p 3+ ... "
+ *
+ *   pop brain append-lesson --doc pop.brain.shared \
+ *     --title "Long form lesson" \
+ *     --body-file /tmp/lesson.md
+ */
+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.appendLessonHandler = 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 idempotency_1 = require("@poa-box/cli/lib/idempotency");
+const output = __importStar(require("@poa-box/cli/lib/output"));
+/**
+ * Keep this in sync with the slugify in brain-migrate.ts — these are
+ * separate code paths but produce compatible ids.
+ */
+function slugify(s) {
+    return s
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 60);
+}
+exports.appendLessonHandler = {
+    builder: (yargs) => yargs
+        .option('doc', {
+        describe: 'Brain document ID (e.g. pop.brain.shared)',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('title', {
+        describe: 'Short title for the lesson (used as the markdown header + default id)',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('body', {
+        describe: 'Lesson body text (inline). Prefer --body-file for multi-paragraph content.',
+        type: 'string',
+    })
+        .option('body-file', {
+        describe: 'Path to a file whose contents will be used as the lesson body',
+        type: 'string',
+    })
+        .option('author', {
+        describe: 'Override the author name (default: signing wallet address)',
+        type: 'string',
+    })
+        .option('id', {
+        describe: 'Override the auto-generated lesson id',
+        type: 'string',
+    })
+        .option('allow-invalid-shape', {
+        describe: 'Bypass write-time schema validation (Task #346). Use only when you deliberately need a non-canonical shape.',
+        type: 'boolean',
+        default: false,
+    })
+        .option('idempotency-key', {
+        type: 'string',
+        describe: 'Task #370 (HB#214): explicit idempotency key. Two identical append-lesson calls within 15 minutes return the same result without re-submitting. Default: auto-derived from argv (title + body + docId). Scope: author address (brain writes are agent-scoped not org-scoped).',
+    })
+        .option('no-idempotency', {
+        type: 'boolean',
+        default: false,
+        describe: 'Bypass the idempotency cache and always submit a new lesson.',
+    })
+        .check((argv) => {
+        if (!argv.body && !argv['body-file']) {
+            throw new Error('Must supply --body or --body-file');
+        }
+        return true;
+    }),
+    handler: async (argv) => {
+        try {
+            // Resolve body content.
+            let body;
+            if (argv.bodyFile) {
+                const p = (0, path_1.resolve)(argv.bodyFile);
+                if (!(0, fs_1.existsSync)(p)) {
+                    output.error(`--body-file not found: ${p}`);
+                    process.exitCode = 1;
+                    return;
+                }
+                body = (0, fs_1.readFileSync)(p, 'utf8').replace(/\s+$/, '');
+            }
+            else {
+                body = (argv.body ?? '').trim();
+            }
+            if (!body) {
+                output.error('Lesson body is empty.');
+                process.exitCode = 1;
+                return;
+            }
+            const now = Math.floor(Date.now() / 1000);
+            // Default id: slug(title) + suffix so two lessons with the same
+            // title still land at distinct ids. Callers can override with --id
+            // when they want a stable key (e.g. upserting a policy rule).
+            const id = argv.id ?? `${slugify(argv.title) || 'lesson'}-${now}`;
+            // Resolve the author up front — for the default case (no --author
+            // flag) we derive the Ethereum address from POP_PRIVATE_KEY so the
+            // lesson.author field matches the envelope signer that brain-signing
+            // will stamp on the block. Doing this before applyBrainChange keeps
+            // the change fn pure and avoids a two-phase update dance.
+            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();
+            }
+            // Task #370: idempotency check. Brain writes are agent-scoped
+            // (no orgId), so the scope is the author address instead.
+            const idempKey = argv.idempotencyKey || (0, idempotency_1.argvToIdempotencyString)(argv);
+            if (!argv.noIdempotency) {
+                const cached = (0, idempotency_1.checkIdempotencyCache)(authorLabel, 'brain.appendLesson', idempKey);
+                if (cached) {
+                    if (output.isJsonMode()) {
+                        output.json({
+                            status: 'ok',
+                            cached: true,
+                            ...cached,
+                            note: 'Prior call within 15-min window produced this result.',
+                        });
+                    }
+                    else {
+                        console.log('');
+                        console.log(`  Lesson already appended (idempotency cache hit)`);
+                        console.log(`  id:     ${cached.lessonId}`);
+                        console.log(`  head:   ${cached.headCid}`);
+                        console.log(`  note:   Prior call within 15-min window. Use --no-idempotency to force re-submit.`);
+                        console.log('');
+                    }
+                    return;
+                }
+            }
+            // Route through the unified dispatcher (HB#324 ship-2). When a
+            // brain daemon is running, this sends the op via IPC so the
+            // daemon's long-lived gossipsub mesh handles the publish. When
+            // no daemon, it falls back to in-process applyBrainChange via
+            // dispatchOp. Same result shape in both cases.
+            const result = await (0, brain_ops_1.routedDispatch)({
+                type: 'appendLesson',
+                docId: argv.doc,
+                id,
+                title: argv.title,
+                body,
+                author: authorLabel,
+                timestamp: now,
+                allowInvalidShape: argv.allowInvalidShape,
+            });
+            // Task #370: record idempotent result after successful dispatch
+            if (!argv.noIdempotency) {
+                (0, idempotency_1.recordIdempotentResult)(authorLabel, 'brain.appendLesson', idempKey, {
+                    docId: argv.doc,
+                    lessonId: id,
+                    headCid: result.headCid,
+                    author: authorLabel,
+                });
+            }
+            if (output.isJsonMode()) {
+                output.json({
+                    status: 'ok',
+                    docId: argv.doc,
+                    lessonId: id,
+                    headCid: result.headCid,
+                    author: authorLabel,
+                    envelopeAuthor: result.envelopeAuthor,
+                    routedViaDaemon: result.routedViaDaemon,
+                });
+            }
+            else {
+                console.log('');
+                console.log(`  Lesson appended to ${argv.doc}`);
+                console.log(`  id:      ${id}`);
+                console.log(`  author:  ${authorLabel}`);
+                console.log(`  head:    ${result.headCid}`);
+                console.log(`  routed:  ${result.routedViaDaemon ? 'via brain daemon' : 'in-process (no daemon)'}`);
+                console.log('');
+            }
+        }
+        catch (err) {
+            output.error(err.message);
+            process.exitCode = 1;
+        }
+        finally {
+            await (0, brain_1.stopBrainNode)();
+        }
+    },
+};

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

@@ -0,0 +1,154 @@
+/**
+ * pop brain brainstorm-* — cross-agent ideation surface commands.
+ *
+ * Task #354 phase (b) (HB#208). Forward-looking companion to
+ * pop.brain.retros (reactive session retrospectives) and
+ * pop.brain.projects (lifecycle state machine for existing projects).
+ *
+ * The brainstorm surface is the missing deliberation primitive for
+ * new ideation: agents post a theme/question, debate it via messages +
+ * ideas + per-agent votes (support/explore/oppose), and top-ranked
+ * ideas get promoted to pop.brain.projects at the `propose` stage.
+ * Promotion links back via the `promotedToProjectIds` array.
+ *
+ * All commands dispatch through routedDispatch so they work with or
+ * without the brain daemon. Schema validation (#346) catches malformed
+ * writes at applyBrainChange time.
+ *
+ * Five sub-commands registered from src/commands/brain/index.ts:
+ *   pop brain brainstorm-start      — open a new brainstorm
+ *   pop brain brainstorm-respond    — post message / add idea / cast vote
+ *   pop brain brainstorm-promote    — promote an idea to a brain project
+ *   pop brain brainstorm-close      — close a brainstorm with no promotion
+ *   pop brain brainstorm-remove     — soft-delete tombstone
+ */
+import type { Argv, ArgumentsCamelCase } from 'yargs';
+interface StartArgs {
+    doc: string;
+    title: string;
+    prompt: string;
+    author?: string;
+    id?: string;
+    windowFromHb?: number;
+    windowToHb?: number;
+}
+export declare const brainstormStartHandler: {
+    builder: (yargs: Argv) => Argv<{
+        doc: string;
+    } & {
+        title: string;
+    } & {
+        prompt: string;
+    } & {
+        author: string | undefined;
+    } & {
+        id: string | undefined;
+    } & {
+        "window-from-hb": number | undefined;
+    } & {
+        "window-to-hb": number | undefined;
+    } & {
+        "idempotency-key": string | undefined;
+    } & {
+        "no-idempotency": boolean;
+    }>;
+    handler: (argv: ArgumentsCamelCase<StartArgs>) => Promise<void>;
+};
+interface RespondArgs {
+    doc: string;
+    id: string;
+    author?: string;
+    message?: string;
+    addIdea?: string;
+    vote?: string[];
+}
+export declare const brainstormRespondHandler: {
+    builder: (yargs: Argv) => Argv<{
+        doc: string;
+    } & {
+        id: string;
+    } & {
+        author: string | undefined;
+    } & {
+        message: string | undefined;
+    } & {
+        "add-idea": string | undefined;
+    } & {
+        vote: string[] | undefined;
+    } & {
+        "idempotency-key": string | undefined;
+    } & {
+        "no-idempotency": boolean;
+    }>;
+    handler: (argv: ArgumentsCamelCase<RespondArgs>) => Promise<void>;
+};
+interface PromoteArgs {
+    doc: string;
+    id: string;
+    ideaId: string;
+    projectId: string;
+    author?: string;
+}
+export declare const brainstormPromoteHandler: {
+    builder: (yargs: Argv) => Argv<{
+        doc: string;
+    } & {
+        id: string;
+    } & {
+        "idea-id": string;
+    } & {
+        "project-id": string;
+    } & {
+        author: string | undefined;
+    } & {
+        "idempotency-key": string | undefined;
+    } & {
+        "no-idempotency": boolean;
+    }>;
+    handler: (argv: ArgumentsCamelCase<PromoteArgs>) => Promise<void>;
+};
+interface CloseArgs {
+    doc: string;
+    id: string;
+    reason?: string;
+    author?: string;
+}
+export declare const brainstormCloseHandler: {
+    builder: (yargs: Argv) => Argv<{
+        doc: string;
+    } & {
+        id: string;
+    } & {
+        reason: string | undefined;
+    } & {
+        author: string | undefined;
+    } & {
+        "idempotency-key": string | undefined;
+    } & {
+        "no-idempotency": boolean;
+    }>;
+    handler: (argv: ArgumentsCamelCase<CloseArgs>) => Promise<void>;
+};
+interface RemoveArgs {
+    doc: string;
+    id: string;
+    reason?: string;
+    author?: string;
+}
+export declare const brainstormRemoveHandler: {
+    builder: (yargs: Argv) => Argv<{
+        doc: string;
+    } & {
+        id: string;
+    } & {
+        reason: string | undefined;
+    } & {
+        author: string | undefined;
+    } & {
+        "idempotency-key": string | undefined;
+    } & {
+        "no-idempotency": boolean;
+    }>;
+    handler: (argv: ArgumentsCamelCase<RemoveArgs>) => Promise<void>;
+};
+export {};