@poa-box/agent 0.1.0

package/dist/commands/brain/subscribe.js

@@ -0,0 +1,90 @@
+"use strict";
+/**
+ * pop brain subscribe — keep the process alive and log incoming head-CID
+ * announcements on a doc's gossipsub topic. The manual test surface for
+ * MVP step 5.
+ *
+ * Typical 2-terminal smoke test:
+ *   Terminal A:  pop brain subscribe --doc pop.brain.shared
+ *   Terminal B:  (any write that calls applyBrainChange — step 7 ships
+ *                the write CLI; until then, a direct script or test)
+ *
+ * Terminal A logs each announcement it sees: docId, CID, claimed author
+ * (not trusted — see brain.ts#BrainHeadAnnouncement), the peer it came
+ * from. Block fetch + load is step 6.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.subscribeHandler = void 0;
+const brain_1 = require("../../lib/brain");
+exports.subscribeHandler = {
+    builder: (yargs) => yargs
+        .option('doc', {
+        describe: 'Brain document ID (e.g. pop.brain.shared)',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('log-only', {
+        describe: 'Only log announcements — do NOT fetch blocks or update manifest',
+        type: 'boolean',
+        default: false,
+    }),
+    handler: async (argv) => {
+        const docId = argv.doc;
+        const topic = (0, brain_1.topicForDoc)(docId);
+        console.log(`Subscribing to ${topic} ...`);
+        const helia = await (0, brain_1.initBrainNode)();
+        const peerId = helia.libp2p.peerId.toString();
+        console.log(`Local peer: ${peerId}`);
+        console.log(`Listening on:`);
+        for (const a of helia.libp2p.getMultiaddrs()) {
+            console.log(`  ${a.toString()}`);
+        }
+        console.log('');
+        console.log('Waiting for announcements. Press Ctrl-C to exit.');
+        console.log('');
+        const logOnly = argv.logOnly === true;
+        if (logOnly) {
+            console.log('(log-only mode — will NOT fetch blocks)');
+            console.log('');
+        }
+        const unsubscribe = await (0, brain_1.subscribeBrainTopic)(docId, (ann, from) => {
+            const when = new Date(ann.timestamp * 1000).toISOString();
+            console.log(`[${when}] head ${ann.cid}`);
+            console.log(`           doc=${ann.docId}  author=${ann.author}  from=${from}`);
+            if (logOnly)
+                return;
+            // Step 6: fetch the block via Bitswap, verify, merge, update manifest.
+            // Runs async inside the event callback — we fire and forget so
+            // the listener doesn't block on slow network fetches.
+            (0, brain_1.fetchAndMergeRemoteHead)(ann.docId, ann.cid)
+                .then((result) => {
+                if (result.action === 'reject') {
+                    console.log(`           -> REJECTED: ${result.reason}`);
+                }
+                else {
+                    console.log(`           -> ${result.action}: ${result.reason}`);
+                    if ('headCid' in result && result.headCid !== ann.cid) {
+                        console.log(`              new local head = ${result.headCid}`);
+                    }
+                }
+            })
+                .catch((err) => {
+                console.log(`           -> ERROR during sync: ${err.message}`);
+            });
+        });
+        // Keep the process alive. SIGINT cleanly unsubscribes and stops Helia.
+        const shutdown = async () => {
+            console.log('\nShutting down...');
+            try {
+                unsubscribe();
+            }
+            catch { }
+            await (0, brain_1.stopBrainNode)();
+            process.exit(0);
+        };
+        process.on('SIGINT', shutdown);
+        process.on('SIGTERM', shutdown);
+        // Block forever — keepalive so libp2p keeps running.
+        await new Promise(() => { });
+    },
+};

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

@@ -0,0 +1,46 @@
+/**
+ * pop brain tag — add or remove tags on an existing brain lesson.
+ *
+ * Task #347 (Retro #1 fallback #6). Companion to `pop brain search`.
+ * Tags are an optional `string[]` field on each lesson. Vocabulary is
+ * free-form — suggested conventions live in docs/agents/brain-layer-setup.md
+ * but nothing enforces them. The goal is search-ability not rigor.
+ *
+ * Usage:
+ *   pop brain tag --doc pop.brain.shared --lesson-id <id> --add tag1,tag2
+ *   pop brain tag --doc pop.brain.shared --lesson-id <id> --remove old-tag
+ *
+ * --add and --remove both accept comma-separated lists. At least one must
+ * be supplied. Idempotent: re-adding a tag or removing a missing tag is a
+ * no-op on the tags array itself but still writes a new head CID (the
+ * tag operation is a legitimate change event for the provenance trail).
+ */
+import type { Argv, ArgumentsCamelCase } from 'yargs';
+interface TagArgs {
+    doc: string;
+    lessonId: string;
+    add?: string;
+    remove?: string;
+    allowInvalidShape?: boolean;
+    'idempotency-key'?: string;
+    'no-idempotency'?: boolean;
+}
+export declare const tagHandler: {
+    builder: (yargs: Argv) => Argv<{
+        doc: string;
+    } & {
+        "lesson-id": string;
+    } & {
+        add: string | undefined;
+    } & {
+        remove: string | undefined;
+    } & {
+        "allow-invalid-shape": boolean;
+    } & {
+        "idempotency-key": string | undefined;
+    } & {
+        "no-idempotency": boolean;
+    }>;
+    handler: (argv: ArgumentsCamelCase<TagArgs>) => Promise<void>;
+};
+export {};

package/dist/commands/brain/tag.js

@@ -0,0 +1,192 @@
+"use strict";
+/**
+ * pop brain tag — add or remove tags on an existing brain lesson.
+ *
+ * Task #347 (Retro #1 fallback #6). Companion to `pop brain search`.
+ * Tags are an optional `string[]` field on each lesson. Vocabulary is
+ * free-form — suggested conventions live in docs/agents/brain-layer-setup.md
+ * but nothing enforces them. The goal is search-ability not rigor.
+ *
+ * Usage:
+ *   pop brain tag --doc pop.brain.shared --lesson-id <id> --add tag1,tag2
+ *   pop brain tag --doc pop.brain.shared --lesson-id <id> --remove old-tag
+ *
+ * --add and --remove both accept comma-separated lists. At least one must
+ * be supplied. Idempotent: re-adding a tag or removing a missing tag is a
+ * no-op on the tags array itself but still writes a new head CID (the
+ * tag operation is a legitimate change event for the provenance trail).
+ */
+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.tagHandler = 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"));
+function parseList(s) {
+    if (!s)
+        return [];
+    return s
+        .split(',')
+        .map((x) => x.trim())
+        .filter((x) => x.length > 0);
+}
+exports.tagHandler = {
+    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 of the entry to tag',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('add', {
+        describe: 'Comma-separated list of tags to add',
+        type: 'string',
+    })
+        .option('remove', {
+        describe: 'Comma-separated list of tags to remove',
+        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.',
+    })
+        .check((argv) => {
+        if (!argv.add && !argv.remove) {
+            throw new Error('Must supply at least one of --add or --remove');
+        }
+        return true;
+    }),
+    handler: async (argv) => {
+        try {
+            const addTags = parseList(argv.add);
+            const removeTags = parseList(argv.remove);
+            // Pre-flight existence check — fail fast with candidate ids if not
+            // found. Same UX as edit-lesson / remove-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 && 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;
+            }
+            // Task #374: idempotency check (agent-scoped).
+            const signerKey = process.env.POP_PRIVATE_KEY;
+            const authorScope = signerKey ? new ethers_1.ethers.Wallet(signerKey).address.toLowerCase() : 'anonymous';
+            const idempKey = argv.idempotencyKey || (0, idempotency_1.argvToIdempotencyString)(argv);
+            if (!argv.noIdempotency) {
+                const cached = (0, idempotency_1.checkIdempotencyCache)(authorScope, 'brain.tag', idempKey);
+                if (cached) {
+                    if (output.isJsonMode()) {
+                        output.json({ status: 'ok', cached: true, ...cached });
+                    }
+                    else {
+                        console.log('');
+                        console.log(`  Lesson "${argv.lessonId}" tags already updated (idempotency cache hit)`);
+                        console.log(`  head:   ${cached.headCid}`);
+                        console.log('');
+                    }
+                    return;
+                }
+            }
+            const result = await (0, brain_ops_1.routedDispatch)({
+                type: 'tagLesson',
+                docId: argv.doc,
+                lessonId: argv.lessonId,
+                addTags,
+                removeTags,
+                allowInvalidShape: argv.allowInvalidShape,
+            });
+            if (!argv.noIdempotency) {
+                (0, idempotency_1.recordIdempotentResult)(authorScope, 'brain.tag', idempKey, {
+                    docId: argv.doc,
+                    lessonId: argv.lessonId,
+                    added: addTags,
+                    removed: removeTags,
+                    headCid: result.headCid,
+                });
+            }
+            if (output.isJsonMode()) {
+                output.json({
+                    status: 'ok',
+                    docId: argv.doc,
+                    lessonId: argv.lessonId,
+                    added: addTags,
+                    removed: removeTags,
+                    headCid: result.headCid,
+                    routedViaDaemon: result.routedViaDaemon,
+                });
+            }
+            else {
+                console.log('');
+                console.log(`  Lesson "${argv.lessonId}" tags updated in ${argv.doc}`);
+                if (addTags.length > 0)
+                    console.log(`  added:   ${addTags.join(', ')}`);
+                if (removeTags.length > 0)
+                    console.log(`  removed: ${removeTags.join(', ')}`);
+                console.log(`  head:    ${result.headCid}`);
+                console.log('');
+            }
+        }
+        catch (err) {
+            output.error(err.message);
+            process.exitCode = 1;
+        }
+        finally {
+            await (0, brain_1.stopBrainNode)();
+        }
+    },
+};

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @poa-box/agent — agent + brain command surface for the POP CLI.
+ *
+ * This module is the plugin contract with @poa-box/cli: the CLI probes for this
+ * package at startup (require('@poa-box/agent'), falling back to the in-repo
+ * packages/agent/dist path) and, when present, registers these two command
+ * groups. Visibility is the CLI's decision — hidden from `pop --help` unless
+ * POP_AGENT_MODE=1, always visible under the `pop-agent` bin.
+ *
+ * Nothing here may import the p2p/CRDT stack at module load. The brain
+ * runtime (libp2p, helia, automerge) is loaded lazily inside lib/brain.ts via
+ * an ESM-import bridge, and must stay that way: this module loads on EVERY
+ * `pop` invocation when the package is installed, and a human running
+ * `pop task list` must not pay for a gossip mesh they will never use.
+ */
+export { registerAgentCommands } from './commands/agent';
+export { registerBrainCommands } from './commands/brain';

package/dist/index.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * @poa-box/agent — agent + brain command surface for the POP CLI.
+ *
+ * This module is the plugin contract with @poa-box/cli: the CLI probes for this
+ * package at startup (require('@poa-box/agent'), falling back to the in-repo
+ * packages/agent/dist path) and, when present, registers these two command
+ * groups. Visibility is the CLI's decision — hidden from `pop --help` unless
+ * POP_AGENT_MODE=1, always visible under the `pop-agent` bin.
+ *
+ * Nothing here may import the p2p/CRDT stack at module load. The brain
+ * runtime (libp2p, helia, automerge) is loaded lazily inside lib/brain.ts via
+ * an ESM-import bridge, and must stay that way: this module loads on EVERY
+ * `pop` invocation when the package is installed, and a human running
+ * `pop task list` must not pay for a gossip mesh they will never use.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerBrainCommands = exports.registerAgentCommands = void 0;
+var agent_1 = require("./commands/agent");
+Object.defineProperty(exports, "registerAgentCommands", { enumerable: true, get: function () { return agent_1.registerAgentCommands; } });
+var brain_1 = require("./commands/brain");
+Object.defineProperty(exports, "registerBrainCommands", { enumerable: true, get: function () { return brain_1.registerBrainCommands; } });

package/dist/lib/brain-daemon.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Brain daemon — persistent libp2p process that keeps gossipsub alive between
+ * agent CLI invocations and periodically re-broadcasts the local manifest's
+ * head CIDs so peers coming online can catch up.
+ *
+ * ## Why
+ *
+ * The brain layer's HB#322 dogfood finding: three consecutive vigil_01 brain
+ * writes were invisible to argus_prime because agent sessions run in separate
+ * 15-min cron slots and never overlap in wall-clock time. Gossipsub is
+ * broadcast-only (no store-and-forward), so announcements published while a
+ * peer is offline vanish permanently. Every agent ended up with a per-agent
+ * append-only journal, not a shared substrate.
+ *
+ * Hudson's HB#322 directive: fix it properly with a long-running daemon. No
+ * shortcuts. Model it on the go-ds-crdt reference architecture
+ * (github.com/ipfs/go-ds-crdt, examples/globaldb/globaldb.go).
+ *
+ * ## Design (mapped from go-ds-crdt)
+ *
+ *   go-ds-crdt                  |  This module
+ *   -----------------------------|--------------------------------------
+ *   Datastore (long-lived)       |  runDaemon() — single process per agent
+ *   Broadcaster (PubSub)         |  existing publishBrainHead / subscribeBrainTopic
+ *   DAGSyncer (DAGService)       |  existing Helia blockstore + Bitswap
+ *   RebroadcastInterval = 1m     |  REBROADCAST_INTERVAL_MS = 60_000
+ *   keepalive netTopic (20s)     |  KEEPALIVE_TOPIC + 20s interval
+ *   seenHeads map                |  DEFERRED — v1 rebroadcasts unconditionally
+ *   RepairInterval = 1h          |  DEFERRED — MVP envelope is snapshot-per-write
+ *                                |  so there's no DAG to walk
+ *   signal handling              |  SIGTERM / SIGINT / SIGHUP
+ *   PutHook / DeleteHook         |  DEFERRED — v2 adds IPC routing so existing
+ *                                |  commands become clients
+ *
+ * ## Process model
+ *
+ *   pop brain daemon start        parent spawns a detached child running
+ *                                 `node dist/index.js brain daemon __run`;
+ *                                 parent writes PID file and exits
+ *   pop brain daemon __run        the child entrypoint, calls runDaemon()
+ *   pop brain daemon stop         reads PID, sends SIGTERM, waits cleanup
+ *   pop brain daemon status       reads PID, checks liveness, opens Unix
+ *                                 socket, sends {method: "status"}, prints
+ *   pop brain daemon logs         tails daemon.log
+ *
+ *   ${POP_BRAIN_HOME}/daemon.pid  parent-written PID file
+ *   ${POP_BRAIN_HOME}/daemon.sock Unix socket for IPC (mode 0600)
+ *   ${POP_BRAIN_HOME}/daemon.log  append-only log
+ *
+ * ## IPC protocol
+ *
+ * Newline-delimited JSON over Unix socket. Each request is one line:
+ *
+ *   {"id": "1", "method": "status"}
+ *
+ * Each response is one line:
+ *
+ *   {"id": "1", "result": {...}}
+ *   {"id": "1", "error": "..."}
+ *
+ * First-ship methods: status. Second-ship methods: appendLesson, readDoc,
+ * snapshot — those let existing CLI commands route through a running daemon
+ * instead of spinning up their own libp2p.
+ */
+export declare const REBROADCAST_INTERVAL_MS = 60000;
+export declare const REBROADCAST_JITTER = 0.3;
+export declare const REBROADCAST_GRACE_MS = 5000;
+export declare const KEEPALIVE_INTERVAL_MS = 20000;
+export declare const REDIAL_INTERVAL_MS = 30000;
+export declare const KEEPALIVE_TOPIC = "pop/brain/net/v1";
+/**
+ * Canonical brain docs every daemon subscribes to at startup regardless
+ * of local manifest state. A fresh brain home has an empty manifest, so
+ * without this list the daemon would not subscribe to any doc topics
+ * and could never receive remote head announcements for
+ * `pop.brain.shared` / `pop.brain.projects` until after its first
+ * local write.
+ *
+ * Adding a new canonical doc here makes every daemon pick it up on
+ * next restart. To experiment with a non-canonical doc, just perform a
+ * local write via `pop brain append-lesson --doc <id>` — the write
+ * path adds the doc to the manifest, and the next daemon loop iteration
+ * picks it up via listBrainDocs().
+ */
+export declare const CANONICAL_BRAIN_DOCS: string[];
+export declare function getDaemonPidPath(): string;
+export declare function getDaemonSockPath(): string;
+export declare function getDaemonLogPath(): string;
+/**
+ * Check if a daemon appears to be running for this brain home.
+ * Returns the PID if alive, null otherwise. Cleans up stale PID files.
+ */
+export declare function getRunningDaemonPid(): number | null;
+/**
+ * Run the daemon event loop. Blocks until a termination signal arrives.
+ * This is the __run entrypoint invoked by the detached child process.
+ *
+ * NEVER call this from the parent CLI path — it will never return.
+ */
+export declare function runDaemon(): Promise<void>;
+/**
+ * Typed IPC error. Attaches a `.code` for the caller to branch on.
+ *
+ *   phase = 'pre-connect'  The connection was never established (socket
+ *                          missing, ECONNREFUSED). Safe to fall back to a
+ *                          local execution path — the write did not land
+ *                          in the daemon's process.
+ *   phase = 'post-connect' The connection was established and the request
+ *                          was sent, but a response did not come back. The
+ *                          write may or may not have landed. NOT safe to
+ *                          fall back — see routedDispatch() in brain-ops.ts.
+ */
+export declare class BrainIpcError extends Error {
+    code: string;
+    phase: 'pre-connect' | 'post-connect';
+    constructor(message: string, code: string, phase: 'pre-connect' | 'post-connect');
+}
+/**
+ * IPC client helper: send a request to the running daemon.
+ *
+ * Throws a BrainIpcError whose `.phase` indicates whether the failure is
+ * safe to recover from by falling back to a local code path. Pre-connect
+ * failures (ECONNREFUSED, ENOENT, daemon not running) are safe. Post-connect
+ * failures (timeout, ECONNRESET, EPIPE) leave the write in an unknown state.
+ */
+export declare function sendIpcRequest(method: string, params?: any, timeoutMs?: number): Promise<any>;