@poa-box/agent 0.1.0

package/dist/commands/brain/brainstorm.js

@@ -0,0 +1,573 @@
+"use strict";
+/**
+ * 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
+ */
+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.brainstormRemoveHandler = exports.brainstormCloseHandler = exports.brainstormPromoteHandler = exports.brainstormRespondHandler = exports.brainstormStartHandler = 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"));
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+function resolveAuthor(argvAuthor) {
+    if (argvAuthor)
+        return argvAuthor;
+    const key = process.env.POP_PRIVATE_KEY;
+    if (!key) {
+        throw new Error('POP_PRIVATE_KEY not set — cannot derive default author. Pass --author explicitly.');
+    }
+    return new ethers_1.ethers.Wallet(key).address.toLowerCase();
+}
+function slugify(s) {
+    return s
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 60);
+}
+exports.brainstormStartHandler = {
+    builder: (yargs) => yargs
+        .option('doc', {
+        describe: 'Brain document ID (default: pop.brain.brainstorms)',
+        type: 'string',
+        default: 'pop.brain.brainstorms',
+    })
+        .option('title', {
+        describe: 'Short brainstorm title (used as default slug for id)',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('prompt', {
+        describe: 'Longer description / question being brainstormed',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('author', {
+        describe: 'Override the author address (default: signing wallet)',
+        type: 'string',
+    })
+        .option('id', {
+        describe: 'Override the auto-generated brainstorm id',
+        type: 'string',
+    })
+        .option('window-from-hb', {
+        describe: 'Starting HB number of the brainstorm window',
+        type: 'number',
+    })
+        .option('window-to-hb', {
+        describe: 'Ending HB number of the brainstorm window',
+        type: 'number',
+    })
+        .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 author = resolveAuthor(argv.author);
+            const now = Math.floor(Date.now() / 1000);
+            const id = argv.id ?? `${slugify(argv.title) || 'brainstorm'}-${now}`;
+            // Task #375 idempotency check, agent-scoped
+            const idempKey = argv.idempotencyKey || (0, idempotency_1.argvToIdempotencyString)(argv);
+            if (!argv.noIdempotency) {
+                const cached = (0, idempotency_1.checkIdempotencyCache)(author, 'brain.brainstormStart', idempKey);
+                if (cached) {
+                    if (output.isJsonMode())
+                        output.json({ status: 'ok', cached: true, ...cached });
+                    else
+                        console.log(`  Brainstorm already opened (idempotency cache hit). id: ${cached.brainstormId} head: ${cached.headCid}`);
+                    return;
+                }
+            }
+            const result = await (0, brain_ops_1.routedDispatch)({
+                type: 'startBrainstorm',
+                docId: argv.doc,
+                brainstormId: id,
+                title: argv.title,
+                prompt: argv.prompt,
+                author,
+                openedAt: now,
+                windowFromHB: argv.windowFromHb,
+                windowToHB: argv.windowToHb,
+            });
+            if (!argv.noIdempotency) {
+                (0, idempotency_1.recordIdempotentResult)(author, 'brain.brainstormStart', idempKey, {
+                    docId: argv.doc,
+                    brainstormId: id,
+                    headCid: result.headCid,
+                });
+            }
+            if (output.isJsonMode()) {
+                output.json({
+                    status: 'ok',
+                    docId: argv.doc,
+                    brainstormId: id,
+                    headCid: result.headCid,
+                    author,
+                    routedViaDaemon: result.routedViaDaemon,
+                });
+            }
+            else {
+                console.log('');
+                console.log(`  Brainstorm opened in ${argv.doc}`);
+                console.log(`  id:       ${id}`);
+                console.log(`  title:    ${argv.title}`);
+                console.log(`  author:   ${author}`);
+                console.log(`  head:     ${result.headCid}`);
+                console.log(`  routed:   ${result.routedViaDaemon ? 'via brain daemon' : 'in-process (no daemon)'}`);
+                console.log('');
+                console.log(`  Other agents respond via pop brain brainstorm-respond --id ${id} ` +
+                    `[--message M] [--add-idea M] [--vote idea-id=stance].`);
+                console.log('');
+            }
+        }
+        catch (err) {
+            output.error(err.message);
+            process.exitCode = 1;
+        }
+        finally {
+            await (0, brain_1.stopBrainNode)();
+        }
+    },
+};
+exports.brainstormRespondHandler = {
+    builder: (yargs) => yargs
+        .option('doc', {
+        type: 'string',
+        default: 'pop.brain.brainstorms',
+    })
+        .option('id', {
+        describe: 'Brainstorm id to respond to',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('author', {
+        describe: 'Override the author address',
+        type: 'string',
+    })
+        .option('message', {
+        describe: 'Free-form discussion message to post',
+        type: 'string',
+    })
+        .option('add-idea', {
+        describe: 'Add a new idea with this text (id auto-generated from a slug)',
+        type: 'string',
+    })
+        .option('vote', {
+        describe: 'Cast a vote: <idea-id>=<support|explore|oppose>. Repeatable.',
+        type: 'array',
+        string: true,
+    })
+        .option('idempotency-key', { type: 'string', describe: 'Task #375 (HB#217) idempotency cache.' })
+        .option('no-idempotency', { type: 'boolean', default: false, describe: 'Bypass the idempotency cache.' })
+        .check((argv) => {
+        if (!argv.message && !argv.addIdea && (!argv.vote || argv.vote.length === 0)) {
+            throw new Error('Must supply at least one of --message / --add-idea / --vote');
+        }
+        return true;
+    }),
+    handler: async (argv) => {
+        try {
+            const author = resolveAuthor(argv.author);
+            const now = Math.floor(Date.now() / 1000);
+            // Pre-flight lookup to fail fast with candidate ids if missing
+            const { doc: currentDoc } = await (0, brain_1.openBrainDoc)(argv.doc);
+            const brainstorms = Array.isArray(currentDoc?.brainstorms) ? currentDoc.brainstorms : [];
+            const target = brainstorms.find((b) => b && b.id === argv.id);
+            if (!target) {
+                const candidates = brainstorms
+                    .map((b) => b?.id)
+                    .filter((id) => typeof id === 'string')
+                    .slice(0, 8);
+                output.error(`Brainstorm "${argv.id}" not found in ${argv.doc}. ` +
+                    `Available ids (first 8): ${candidates.join(', ') || '(none)'}`);
+                process.exitCode = 1;
+                return;
+            }
+            // Parse --vote entries into { ideaId: stance }
+            const votes = {};
+            for (const entry of argv.vote ?? []) {
+                const [ideaId, stance] = entry.split('=').map((s) => s.trim());
+                if (!ideaId || !stance) {
+                    throw new Error(`Malformed --vote "${entry}" — expected format <idea-id>=<stance>`);
+                }
+                if (stance !== 'support' && stance !== 'explore' && stance !== 'oppose') {
+                    throw new Error(`Invalid stance "${stance}" in --vote "${entry}" — must be support|explore|oppose`);
+                }
+                votes[ideaId] = stance;
+            }
+            // If adding an idea, generate a new idea id from a slug
+            let addIdeaPayload;
+            if (argv.addIdea) {
+                const ideaId = `${slugify(argv.addIdea) || 'idea'}-${now}`;
+                addIdeaPayload = { id: ideaId, message: argv.addIdea };
+            }
+            // Task #375 idempotency check, agent-scoped
+            const idempKey = argv.idempotencyKey || (0, idempotency_1.argvToIdempotencyString)(argv);
+            if (!argv.noIdempotency) {
+                const cached = (0, idempotency_1.checkIdempotencyCache)(author, 'brain.brainstormRespond', idempKey);
+                if (cached) {
+                    if (output.isJsonMode())
+                        output.json({ status: 'ok', cached: true, ...cached });
+                    else
+                        console.log(`  Brainstorm response already recorded (idempotency cache hit). head: ${cached.headCid}`);
+                    return;
+                }
+            }
+            const result = await (0, brain_ops_1.routedDispatch)({
+                type: 'respondToBrainstorm',
+                docId: argv.doc,
+                brainstormId: argv.id,
+                author,
+                message: argv.message,
+                addIdea: addIdeaPayload,
+                votes: Object.keys(votes).length > 0 ? votes : undefined,
+                timestamp: now,
+            });
+            if (!argv.noIdempotency) {
+                (0, idempotency_1.recordIdempotentResult)(author, 'brain.brainstormRespond', idempKey, {
+                    docId: argv.doc,
+                    brainstormId: argv.id,
+                    headCid: result.headCid,
+                });
+            }
+            if (output.isJsonMode()) {
+                output.json({
+                    status: 'ok',
+                    docId: argv.doc,
+                    brainstormId: argv.id,
+                    ideaAdded: addIdeaPayload?.id ?? null,
+                    votesCast: Object.keys(votes),
+                    message: argv.message ? 'posted' : null,
+                    headCid: result.headCid,
+                    author,
+                    routedViaDaemon: result.routedViaDaemon,
+                });
+            }
+            else {
+                console.log('');
+                console.log(`  Responded to brainstorm "${argv.id}" in ${argv.doc}`);
+                if (argv.message)
+                    console.log(`  message: posted`);
+                if (addIdeaPayload)
+                    console.log(`  new idea: ${addIdeaPayload.id}`);
+                if (Object.keys(votes).length > 0) {
+                    console.log(`  votes:`);
+                    for (const [ideaId, stance] of Object.entries(votes)) {
+                        console.log(`    ${ideaId} = ${stance}`);
+                    }
+                }
+                console.log(`  head:    ${result.headCid}`);
+                console.log('');
+            }
+        }
+        catch (err) {
+            output.error(err.message);
+            process.exitCode = 1;
+        }
+        finally {
+            await (0, brain_1.stopBrainNode)();
+        }
+    },
+};
+exports.brainstormPromoteHandler = {
+    builder: (yargs) => yargs
+        .option('doc', {
+        type: 'string',
+        default: 'pop.brain.brainstorms',
+    })
+        .option('id', {
+        describe: 'Brainstorm id containing the idea to promote',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('idea-id', {
+        describe: 'Idea id to promote to a brain project',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('project-id', {
+        describe: 'Existing pop.brain.projects id to link to (create the project via `pop brain new-project` first)',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('author', {
+        describe: 'Override the author address',
+        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 author = resolveAuthor(argv.author);
+            const now = Math.floor(Date.now() / 1000);
+            const idempKey = argv.idempotencyKey || (0, idempotency_1.argvToIdempotencyString)(argv);
+            if (!argv.noIdempotency) {
+                const cached = (0, idempotency_1.checkIdempotencyCache)(author, 'brain.brainstormPromote', idempKey);
+                if (cached) {
+                    if (output.isJsonMode())
+                        output.json({ status: 'ok', cached: true, ...cached });
+                    else
+                        console.log(`  Idea already promoted (idempotency cache hit). head: ${cached.headCid}`);
+                    return;
+                }
+            }
+            const result = await (0, brain_ops_1.routedDispatch)({
+                type: 'promoteIdea',
+                docId: argv.doc,
+                brainstormId: argv.id,
+                ideaId: argv.ideaId,
+                promotedProjectId: argv.projectId,
+                promotedBy: author,
+                promotedAt: now,
+            });
+            if (!argv.noIdempotency) {
+                (0, idempotency_1.recordIdempotentResult)(author, 'brain.brainstormPromote', idempKey, {
+                    docId: argv.doc,
+                    brainstormId: argv.id,
+                    ideaId: argv.ideaId,
+                    headCid: result.headCid,
+                });
+            }
+            if (output.isJsonMode()) {
+                output.json({
+                    status: 'ok',
+                    docId: argv.doc,
+                    brainstormId: argv.id,
+                    ideaId: argv.ideaId,
+                    promotedProjectId: argv.projectId,
+                    headCid: result.headCid,
+                    author,
+                    routedViaDaemon: result.routedViaDaemon,
+                });
+            }
+            else {
+                console.log('');
+                console.log(`  Idea "${argv.ideaId}" promoted from brainstorm "${argv.id}" to project "${argv.projectId}"`);
+                console.log(`  promotedBy: ${author}`);
+                console.log(`  head:       ${result.headCid}`);
+                console.log('');
+            }
+        }
+        catch (err) {
+            output.error(err.message);
+            process.exitCode = 1;
+        }
+        finally {
+            await (0, brain_1.stopBrainNode)();
+        }
+    },
+};
+exports.brainstormCloseHandler = {
+    builder: (yargs) => yargs
+        .option('doc', {
+        type: 'string',
+        default: 'pop.brain.brainstorms',
+    })
+        .option('id', {
+        describe: 'Brainstorm id to close',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('reason', {
+        describe: 'Reason for closing without promoting',
+        type: 'string',
+    })
+        .option('author', {
+        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 author = resolveAuthor(argv.author);
+            const now = Math.floor(Date.now() / 1000);
+            const idempKey = argv.idempotencyKey || (0, idempotency_1.argvToIdempotencyString)(argv);
+            if (!argv.noIdempotency) {
+                const cached = (0, idempotency_1.checkIdempotencyCache)(author, 'brain.brainstormClose', idempKey);
+                if (cached) {
+                    if (output.isJsonMode())
+                        output.json({ status: 'ok', cached: true, ...cached });
+                    else
+                        console.log(`  Brainstorm "${argv.id}" already closed (idempotency cache hit). head: ${cached.headCid}`);
+                    return;
+                }
+            }
+            const result = await (0, brain_ops_1.routedDispatch)({
+                type: 'closeBrainstorm',
+                docId: argv.doc,
+                brainstormId: argv.id,
+                closedBy: author,
+                closedAt: now,
+                reason: argv.reason,
+            });
+            if (!argv.noIdempotency) {
+                (0, idempotency_1.recordIdempotentResult)(author, 'brain.brainstormClose', idempKey, {
+                    docId: argv.doc,
+                    brainstormId: argv.id,
+                    headCid: result.headCid,
+                });
+            }
+            if (output.isJsonMode()) {
+                output.json({
+                    status: 'ok',
+                    docId: argv.doc,
+                    brainstormId: argv.id,
+                    headCid: result.headCid,
+                    author,
+                    routedViaDaemon: result.routedViaDaemon,
+                });
+            }
+            else {
+                console.log('');
+                console.log(`  Brainstorm "${argv.id}" closed in ${argv.doc}`);
+                console.log(`  closedBy: ${author}`);
+                if (argv.reason)
+                    console.log(`  reason:   ${argv.reason}`);
+                console.log(`  head:     ${result.headCid}`);
+                console.log('');
+            }
+        }
+        catch (err) {
+            output.error(err.message);
+            process.exitCode = 1;
+        }
+        finally {
+            await (0, brain_1.stopBrainNode)();
+        }
+    },
+};
+exports.brainstormRemoveHandler = {
+    builder: (yargs) => yargs
+        .option('doc', {
+        type: 'string',
+        default: 'pop.brain.brainstorms',
+    })
+        .option('id', {
+        describe: 'Brainstorm id to soft-delete',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('reason', {
+        describe: 'Removal reason',
+        type: 'string',
+    })
+        .option('author', {
+        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 author = resolveAuthor(argv.author);
+            const now = Math.floor(Date.now() / 1000);
+            const idempKey = argv.idempotencyKey || (0, idempotency_1.argvToIdempotencyString)(argv);
+            if (!argv.noIdempotency) {
+                const cached = (0, idempotency_1.checkIdempotencyCache)(author, 'brain.brainstormRemove', idempKey);
+                if (cached) {
+                    if (output.isJsonMode())
+                        output.json({ status: 'ok', cached: true, ...cached });
+                    else
+                        console.log(`  Brainstorm "${argv.id}" already removed (idempotency cache hit). head: ${cached.headCid}`);
+                    return;
+                }
+            }
+            const result = await (0, brain_ops_1.routedDispatch)({
+                type: 'removeBrainstorm',
+                docId: argv.doc,
+                brainstormId: argv.id,
+                removedBy: author,
+                removedAt: now,
+                removedReason: argv.reason,
+            });
+            if (!argv.noIdempotency) {
+                (0, idempotency_1.recordIdempotentResult)(author, 'brain.brainstormRemove', idempKey, {
+                    docId: argv.doc,
+                    brainstormId: argv.id,
+                    headCid: result.headCid,
+                });
+            }
+            if (output.isJsonMode()) {
+                output.json({
+                    status: 'ok',
+                    docId: argv.doc,
+                    brainstormId: argv.id,
+                    headCid: result.headCid,
+                    author,
+                    routedViaDaemon: result.routedViaDaemon,
+                });
+            }
+            else {
+                console.log('');
+                console.log(`  Brainstorm "${argv.id}" soft-deleted in ${argv.doc}`);
+                console.log(`  removedBy: ${author}`);
+                if (argv.reason)
+                    console.log(`  reason:    ${argv.reason}`);
+                console.log(`  head:      ${result.headCid}`);
+                console.log('');
+            }
+        }
+        catch (err) {
+            output.error(err.message);
+            process.exitCode = 1;
+        }
+        finally {
+            await (0, brain_1.stopBrainNode)();
+        }
+    },
+};

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

@@ -0,0 +1,31 @@
+/**
+ * pop brain daemon — process control for the persistent brain daemon
+ * (HB#322 architecture: go-ds-crdt-shaped rebroadcast + keepalive loop,
+ * see src/lib/brain-daemon.ts for the full design rationale).
+ *
+ * Subcommands:
+ *   start    spawn a detached daemon child
+ *   stop     signal a running daemon to shut down gracefully
+ *   status   print daemon stats (peer count, topics, uptime, rebroadcast
+ *            counts) via IPC
+ *   logs     tail the daemon log file
+ *   __run    internal — the actual daemon entrypoint. Never call directly
+ *            from the shell; start uses this.
+ */
+import type { Argv, ArgumentsCamelCase } from 'yargs';
+interface DaemonArgs {
+    action: 'start' | 'stop' | 'status' | 'logs' | '__run';
+    follow?: boolean;
+    tail?: number;
+}
+export declare const daemonHandler: {
+    builder: (yargs: Argv) => Argv<{
+        action: "start" | "status" | "stop" | "logs" | "__run" | undefined;
+    } & {
+        follow: boolean;
+    } & {
+        tail: number;
+    }>;
+    handler: (argv: ArgumentsCamelCase<DaemonArgs>) => Promise<void>;
+};
+export {};