@poa-box/agent 0.1.0

package/dist/lib/brain-migrate.js

@@ -0,0 +1,328 @@
+"use strict";
+/**
+ * Brain migration — one-shot parser that converts the hand-written
+ * agent/brain/Knowledge/shared.md (and siblings) into a structured
+ * SharedBrainDoc for seeding the Automerge CRDT layer.
+ *
+ * This is step 8 of the brain plan (cheeky-nibbling-raven.md).
+ * After this file has been run once on each hand-written knowledge
+ * file, the CRDT substrate is the source of truth and the hand-written
+ * files become historical snapshots.
+ *
+ * ## Design notes
+ *
+ * - **Pure function.** parseSharedMarkdown takes a raw string and
+ *   returns a SharedBrainDoc. No I/O, no Date.now, no environment
+ *   reads. The CLI command handles all I/O and timestamp-from-now
+ *   decisions.
+ *
+ * - **Heuristic, not canonical.** This is a one-shot parse; we're
+ *   allowed to lose fidelity on layout details as long as the
+ *   content content survives. Each H2 section becomes one entry.
+ *
+ * - **Short sections become rules, long sections become lessons.**
+ *   A rule is a short-form policy item (one to a few lines of plain
+ *   text, often bullet-led). A lesson is a longer structured
+ *   narrative. The heuristic: if a section's body has more than 200
+ *   characters OR contains a code fence, it's a lesson; otherwise
+ *   it's a rule. This maps the existing hand-written file's mix of
+ *   short policy bullets and long narrative notes to the brain doc
+ *   schema cleanly.
+ *
+ * - **HB# tags → timestamps.** Lines containing `HB#N` or `(HB#N,
+ *   author)` extract both the heartbeat number and the author.
+ *   Timestamps are derived from HB# via a caller-provided anchor
+ *   (see MigrationContext below) rather than guessed — keeps the
+ *   parser pure.
+ *
+ * - **Code fences are preserved verbatim.** We do NOT split on ##
+ *   headers inside a ``` block — that would corrupt embedded code
+ *   samples. Tracked via a simple in-fence toggle.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSharedMarkdown = parseSharedMarkdown;
+const HB_TAG_RE = /\(\s*HB#(\d+)(?:\s*,\s*([^\s)]+))?\s*\)/i;
+const BARE_HB_RE = /\bHB#(\d+)\b/i;
+/**
+ * Slugify a string for use as an entry id. Keeps lowercase letters,
+ * digits, and hyphens; collapses other characters to hyphens.
+ */
+function slugify(s) {
+    return s
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 60);
+}
+/**
+ * Split raw markdown into sections delimited by `^## ` headers at
+ * the top level. Returns an ordered list of { header, body } pairs.
+ * Skips content before the first H2 (preamble) entirely — it's
+ * usually the file's title and intro paragraph.
+ *
+ * Code fences are respected: `##` inside a ``` block is treated as
+ * literal content, not a section break. This matters because the
+ * hand-written shared.md embeds shell command examples with
+ * triple-backtick fences, and one of those happens to include a
+ * markdown header in a commented line.
+ */
+function splitSections(raw) {
+    const lines = raw.split(/\r?\n/);
+    const sections = [];
+    let inFence = false;
+    let current = null;
+    for (const line of lines) {
+        // Track code fence state so we don't treat `##` inside code as
+        // a new section.
+        if (/^```/.test(line)) {
+            inFence = !inFence;
+            if (current)
+                current.body.push(line);
+            continue;
+        }
+        if (!inFence && /^##\s+/.test(line)) {
+            if (current)
+                sections.push({ header: current.header, body: current.body.join('\n').trim() });
+            current = { header: line.replace(/^##\s+/, '').trim(), body: [] };
+            continue;
+        }
+        if (current)
+            current.body.push(line);
+        // lines before the first H2 are dropped (preamble)
+    }
+    if (current)
+        sections.push({ header: current.header, body: current.body.join('\n').trim() });
+    return sections;
+}
+/**
+ * Extract an HB#/author tag from a block of text. Returns the first
+ * match found (usually the header or the first body line). Returns
+ * null if nothing matches.
+ */
+function extractHBTag(text) {
+    const m = HB_TAG_RE.exec(text);
+    if (m)
+        return { hb: Number(m[1]), author: m[2] ?? null };
+    const bare = BARE_HB_RE.exec(text);
+    if (bare)
+        return { hb: Number(bare[1]), author: null };
+    return null;
+}
+/**
+ * Detect whether the input is a modern `.generated.md` snapshot produced by
+ * `pop brain snapshot` (task #352+), not a hand-written `shared.md`. The
+ * discriminator is the DO-NOT-HAND-EDIT banner that the projector emits.
+ *
+ * Task #357 (HB#358): before this detection existed, parseSharedMarkdown
+ * tried the legacy H2 scanner against the generated.md format and found
+ * only 6 of 59 lessons — matching H2 headers like `## Lessons`,
+ * `## What worked this session`, etc., as lesson titles. This is a
+ * permanent format mismatch, not a parse bug; the solution is a
+ * different parser for each format, dispatched by banner detection.
+ */
+function isModernGeneratedMd(raw) {
+    return /^# GENERATED BY `pop brain snapshot`/m.test(raw.slice(0, 500));
+}
+/**
+ * Parse a modern `.generated.md` snapshot (task #357 / HB#358).
+ *
+ * Structure produced by brain-projections.ts `projectShared`:
+ *
+ *   # GENERATED BY `pop brain snapshot` — DO NOT HAND-EDIT
+ *   <!-- ... -->
+ *
+ *   # Shared Agent Brain — `pop.brain.shared`
+ *   *Head CID: `bafk...`*
+ *
+ *   ## Lessons
+ *
+ *   ### <lesson title> [possibly containing (HB#N, author)]
+ *   *author: <name> · at: <ISO timestamp> · id: <lesson-id>*
+ *
+ *   <body paragraphs — may contain code fences AND `##` subheaders>
+ *
+ *   ---
+ *
+ *   ### <next lesson title>
+ *   ...
+ *
+ *   ## Removed lessons
+ *   ...
+ *
+ * Rules for this parser:
+ *   1. Only consider content after the `## Lessons` header
+ *   2. A lesson starts at `### <title>` (H3)
+ *   3. The line immediately after (if matching `*author: ... · at: ... · id: ...*`)
+ *      provides metadata
+ *   4. Body = everything until the NEXT `### <title>` OR one of the known
+ *      terminator H2 headers (`## Removed lessons`, `## Other fields`)
+ *   5. `##` subheaders INSIDE a lesson body (e.g. `## What worked` inside a
+ *      retro-style lesson) are content, not terminators
+ *   6. `---` horizontal rules between lessons are cosmetic and dropped
+ *   7. Code fences are respected: `###` inside ``` is literal content
+ *
+ * Every modern lesson is parsed as a lesson (not a rule). Rules only exist
+ * in the legacy hand-written format and aren't produced by the modern
+ * projector anymore.
+ */
+function parseModernGeneratedMd(raw, ctx) {
+    const lessons = [];
+    const lines = raw.split(/\r?\n/);
+    // Find the `## Lessons` header. Everything before is banner + doc title.
+    let startIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (/^##\s+Lessons\s*$/.test(lines[i])) {
+            startIdx = i + 1;
+            break;
+        }
+    }
+    if (startIdx === -1) {
+        // No lessons section — return empty. This is a valid case for a
+        // fresh generated.md before any lesson has been written.
+        return { rules: [], lessons: [] };
+    }
+    // Known terminator H2 headers that end the Lessons section.
+    const TERMINATORS = [
+        /^##\s+Removed lessons\s*$/,
+        /^##\s+Other fields\s*$/,
+    ];
+    const isTerminator = (line) => TERMINATORS.some(re => re.test(line));
+    // Metadata line format: `*author: X · at: ISO-TIMESTAMP · id: lesson-id*`
+    // Each field is separated by ` · ` (middle dot with spaces).
+    const METADATA_RE = /^\*author:\s*([^·]+?)\s*·\s*at:\s*([^·]+?)\s*·\s*id:\s*([^*\s]+)\s*\*?$/;
+    let inFence = false;
+    let pending = null;
+    const commitPending = () => {
+        if (!pending)
+            return;
+        // Title may contain HB#N tag. Extract for timestamp resolution and
+        // also strip from the title for cleanliness.
+        const tag = extractHBTag(pending.title);
+        // Prefer the metadata author field; fall back to HB# tag author;
+        // fall back to default.
+        const author = pending.author ?? tag?.author ?? ctx.defaultAuthor;
+        // Prefer the metadata `at:` ISO timestamp (parse to unix seconds).
+        // Fall back to HB-derived timestamp, then default.
+        let timestamp = ctx.defaultTimestamp;
+        if (pending.at) {
+            const parsed = Date.parse(pending.at);
+            if (Number.isFinite(parsed)) {
+                timestamp = Math.floor(parsed / 1000);
+            }
+        }
+        else if (tag && ctx.timestampForHB) {
+            timestamp = ctx.timestampForHB(tag.hb);
+        }
+        // Prefer the metadata `id:` field; fall back to slugified title.
+        const id = pending.id ?? slugify(pending.title) ?? `lesson-${lessons.length + 1}`;
+        // Join the body and trim trailing whitespace / trailing `---` separator.
+        const body = pending.bodyLines
+            .join('\n')
+            .replace(/\n+---\n*$/, '') // trim trailing horizontal rule
+            .trim();
+        if (body.length === 0 && !pending.id && !pending.author) {
+            // Empty lesson with no metadata — likely a parse artifact, skip.
+            pending = null;
+            return;
+        }
+        lessons.push({ id, title: pending.title, author, body, timestamp });
+        pending = null;
+    };
+    for (let i = startIdx; i < lines.length; i++) {
+        const line = lines[i];
+        // Track code fence state — `###` inside ``` is literal content.
+        if (/^```/.test(line)) {
+            inFence = !inFence;
+            if (pending)
+                pending.bodyLines.push(line);
+            continue;
+        }
+        if (!inFence) {
+            // Terminator: end of Lessons section. Commit + stop.
+            if (isTerminator(line)) {
+                commitPending();
+                break;
+            }
+            // New H3 = new lesson.
+            const h3Match = /^###\s+(.+?)\s*$/.exec(line);
+            if (h3Match) {
+                commitPending();
+                pending = {
+                    title: h3Match[1],
+                    author: null,
+                    at: null,
+                    id: null,
+                    bodyLines: [],
+                };
+                continue;
+            }
+            // Metadata line immediately after the H3 (pending has no body yet).
+            if (pending && pending.bodyLines.length === 0 && pending.id === null) {
+                const metaMatch = METADATA_RE.exec(line);
+                if (metaMatch) {
+                    pending.author = metaMatch[1];
+                    pending.at = metaMatch[2];
+                    pending.id = metaMatch[3];
+                    continue;
+                }
+            }
+        }
+        // Content line — append to the pending lesson body.
+        if (pending)
+            pending.bodyLines.push(line);
+    }
+    // Commit the final lesson if we hit EOF without a terminator.
+    commitPending();
+    return { rules: [], lessons };
+}
+/**
+ * Parse the hand-written shared.md (or similar) into a SharedBrainDoc.
+ *
+ * Dispatches to `parseModernGeneratedMd` for modern snapshots produced by
+ * `pop brain snapshot` (detected via the DO-NOT-HAND-EDIT banner), or to
+ * the legacy H2-section scanner for hand-written shared.md files.
+ *
+ * Pure function — no I/O, no Date.now, no env reads. The caller must
+ * supply the migration context (default author, default timestamp,
+ * optional HB→timestamp function).
+ */
+function parseSharedMarkdown(raw, ctx) {
+    // Task #357 dispatch: modern generated.md vs legacy hand-written.
+    if (isModernGeneratedMd(raw)) {
+        return parseModernGeneratedMd(raw, ctx);
+    }
+    const sections = splitSections(raw);
+    const rules = [];
+    const lessons = [];
+    for (const { header, body } of sections) {
+        if (body.length === 0)
+            continue;
+        const combinedForTagHunt = `${header}\n${body.split('\n').slice(0, 2).join('\n')}`;
+        const tag = extractHBTag(combinedForTagHunt);
+        const author = tag?.author ?? ctx.defaultAuthor;
+        const timestamp = tag && ctx.timestampForHB
+            ? ctx.timestampForHB(tag.hb)
+            : ctx.defaultTimestamp;
+        const hasCodeFence = /^```/m.test(body);
+        const isLesson = body.length > 200 || hasCodeFence;
+        const id = slugify(header) || `section-${lessons.length + rules.length + 1}`;
+        if (isLesson) {
+            lessons.push({
+                id,
+                title: header,
+                author,
+                body,
+                timestamp,
+            });
+        }
+        else {
+            rules.push({
+                id,
+                author,
+                text: body,
+                timestamp,
+            });
+        }
+    }
+    return { rules, lessons };
+}

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

@@ -0,0 +1,271 @@
+/**
+ * Unified brain write dispatcher (HB#324 principal-engineer ship-2).
+ *
+ * ## Why this module exists
+ *
+ * Before this module, every brain write command (append-lesson, edit-lesson,
+ * remove-lesson, new-project, advance-stage, remove-project, …) called
+ * `applyBrainChange` directly with a closure. That works fine in-process but
+ * cannot be routed through IPC to a running daemon — closures don't serialize.
+ *
+ * The brain daemon needs to be the single owner of libp2p/gossipsub when it's
+ * running (HB#312 dogfood wedge proved sequential agent sessions never overlap
+ * in wall-clock time, so a short-lived in-process libp2p can't reliably
+ * deliver a gossipsub announcement before exiting). For the daemon to be
+ * useful, every write has to route through it. For the daemon to be usable,
+ * the CLI commands need a transparent fallback when no daemon is running.
+ *
+ * The solution is to turn every brain write into a pure-data operation
+ * descriptor (`BrainOp`) and have two execution paths that share zero
+ * business logic:
+ *
+ *   `dispatchOp(op)`      Runs the op in the current process. Used by:
+ *                         (a) the daemon's IPC handler, and
+ *                         (b) CLI commands as a fallback when no daemon.
+ *   `routedDispatch(op)`  Entry point for CLI commands. Checks for a running
+ *                         daemon: if yes, sends `applyOp` via IPC; if no,
+ *                         calls dispatchOp locally.
+ *
+ * Both paths converge on the same `dispatchOp` function. There is no
+ * "local" vs "routed" business logic — only a transport decision.
+ *
+ * ## Fallback correctness (important)
+ *
+ * `routedDispatch` must be careful about when it falls back to local
+ * dispatch. If the daemon has already processed the write and only the
+ * *response* got lost, a silent local fallback causes a double-write.
+ *
+ * The rule:
+ *   - Pre-connect IPC failure (ECONNREFUSED, ENOENT, daemon not running at
+ *     all) → SAFE to fall back. The write definitely did not land in the
+ *     daemon's process because we never opened the connection.
+ *   - Post-connect IPC failure (ECONNRESET, EPIPE, timeout mid-call) → NOT
+ *     safe. The daemon may have processed the write. Error out and let the
+ *     operator decide.
+ *
+ * This is the opposite of retry-everything semantics, on purpose. Brain
+ * writes are append-mostly and deduplication is hard once the block lands.
+ *
+ * ## Adding a new op
+ *
+ *   1. Add the variant to the `BrainOp` discriminated union below.
+ *   2. Add the case to `dispatchOp`'s switch statement.
+ *   3. Replace the `applyBrainChange(doc, closure)` call in your command
+ *      with `routedDispatch({type: 'yourOp', ...})`.
+ *
+ * The daemon's IPC handler is a one-line `return dispatchOp(params.op)` —
+ * it does not need to be updated for new ops.
+ */
+export interface AppendLessonOp {
+    type: 'appendLesson';
+    docId: string;
+    id: string;
+    title: string;
+    body: string;
+    author: string;
+    timestamp: number;
+    /** Task #346: bypass write-time schema validation. Default false (strict). */
+    allowInvalidShape?: boolean;
+}
+export interface EditLessonOp {
+    type: 'editLesson';
+    docId: string;
+    lessonId: string;
+    fields: {
+        title?: string;
+        body?: string;
+        author?: string;
+    };
+    /** Bump the lesson's timestamp to now(), even when no fields change. */
+    touch: boolean;
+    /** Task #346: bypass write-time schema validation. Default false (strict). */
+    allowInvalidShape?: boolean;
+}
+export interface RemoveLessonOp {
+    type: 'removeLesson';
+    docId: string;
+    lessonId: string;
+    removedBy: string;
+    removedAt: number;
+    removedReason?: string;
+    /** Task #346: bypass write-time schema validation. Default false (strict). */
+    allowInvalidShape?: boolean;
+}
+export interface NewProjectOp {
+    type: 'newProject';
+    docId: string;
+    projectId: string;
+    /** Display name — matches the `name` field on the stored project object. */
+    name: string;
+    /** Optional short-form brief; omitted field when undefined. */
+    brief?: string;
+    /** Starting lifecycle stage (propose / discuss / plan / vote / execute / review / ship). */
+    stage: string;
+    /** Proposer label — default is lowercased wallet address. */
+    proposedBy: string;
+    /** Unix seconds — recorded as `proposedAt` on the stored project. */
+    proposedAt: number;
+}
+export interface AdvanceStageOp {
+    type: 'advanceStage';
+    docId: string;
+    projectId: string;
+    /** New lifecycle stage. */
+    newStage: string;
+    /** Unix seconds — recorded as `lastStageAdvanceAt` on the project. */
+    lastStageAdvanceAt: number;
+}
+export interface RemoveProjectOp {
+    type: 'removeProject';
+    docId: string;
+    projectId: string;
+    removedBy: string;
+    removedAt: number;
+    removedReason?: string;
+}
+export interface RetroChangeInput {
+    id: string;
+    summary: string;
+    details?: string;
+    status?: 'proposed' | 'agreed' | 'modified' | 'rejected' | 'filed';
+}
+export interface StartRetroOp {
+    type: 'startRetro';
+    docId: string;
+    retroId: string;
+    author: string;
+    /** HB number when the retro was started. */
+    hb: number;
+    window: {
+        from: number;
+        to: number;
+    };
+    observations: {
+        worked?: string;
+        didntWork?: string;
+    };
+    proposedChanges: RetroChangeInput[];
+    createdAt: number;
+}
+export interface RespondToRetroOp {
+    type: 'respondToRetro';
+    docId: string;
+    retroId: string;
+    author: string;
+    hb?: number;
+    message: string;
+    votePerChange?: Record<string, 'agree' | 'modify' | 'reject'>;
+    timestamp: number;
+}
+export interface UpdateChangeStatusOp {
+    type: 'updateChangeStatus';
+    docId: string;
+    retroId: string;
+    changeId: string;
+    newStatus: 'proposed' | 'agreed' | 'modified' | 'rejected' | 'filed';
+    filedTaskId?: string;
+}
+export interface RemoveRetroOp {
+    type: 'removeRetro';
+    docId: string;
+    retroId: string;
+    removedBy: string;
+    removedAt: number;
+    removedReason?: string;
+}
+export interface TagLessonOp {
+    type: 'tagLesson';
+    docId: string;
+    lessonId: string;
+    addTags: string[];
+    removeTags: string[];
+    /** Task #346: bypass write-time schema validation. Default false (strict). */
+    allowInvalidShape?: boolean;
+}
+export interface StartBrainstormOp {
+    type: 'startBrainstorm';
+    docId: string;
+    brainstormId: string;
+    title: string;
+    prompt: string;
+    author: string;
+    openedAt: number;
+    windowFromHB?: number;
+    windowToHB?: number;
+}
+export interface RespondToBrainstormOp {
+    type: 'respondToBrainstorm';
+    docId: string;
+    brainstormId: string;
+    author: string;
+    /** Message posted by the responding agent. Plain string, no schema. */
+    message?: string;
+    /** New idea to add to the brainstorm's ideas list. */
+    addIdea?: {
+        id: string;
+        message: string;
+    };
+    /** Map of idea id → stance (support/explore/oppose). Merges into existing votes without overwriting other agents' votes. */
+    votes?: Record<string, 'support' | 'explore' | 'oppose'>;
+    timestamp: number;
+}
+export interface PromoteIdeaOp {
+    type: 'promoteIdea';
+    docId: string;
+    brainstormId: string;
+    ideaId: string;
+    /** The pop.brain.projects id to link to after promotion. Caller creates the project separately via newProject; this op just records the back-reference. */
+    promotedProjectId: string;
+    promotedBy: string;
+    promotedAt: number;
+}
+export interface CloseBrainstormOp {
+    type: 'closeBrainstorm';
+    docId: string;
+    brainstormId: string;
+    closedBy: string;
+    closedAt: number;
+    /** Free-form reason for the close. */
+    reason?: string;
+}
+export interface RemoveBrainstormOp {
+    type: 'removeBrainstorm';
+    docId: string;
+    brainstormId: string;
+    removedBy: string;
+    removedAt: number;
+    removedReason?: string;
+}
+export type BrainOp = AppendLessonOp | EditLessonOp | RemoveLessonOp | NewProjectOp | AdvanceStageOp | RemoveProjectOp | StartRetroOp | RespondToRetroOp | UpdateChangeStatusOp | RemoveRetroOp | TagLessonOp | StartBrainstormOp | RespondToBrainstormOp | PromoteIdeaOp | CloseBrainstormOp | RemoveBrainstormOp;
+export interface DispatchResult {
+    headCid: string;
+    /** The Ethereum address that signed the envelope (from POP_PRIVATE_KEY). */
+    envelopeAuthor: string;
+    /** True iff the op was routed through a running brain daemon. */
+    routedViaDaemon: boolean;
+}
+/**
+ * Apply a BrainOp in the current process. Translates the op descriptor to
+ * the corresponding Automerge change function and calls `applyBrainChange`,
+ * which signs the envelope, writes the block, updates the manifest, and
+ * publishes the new head CID via gossipsub.
+ *
+ * Same function is called from two places:
+ *   - The daemon's `applyOp` IPC handler (when a CLI routed a write)
+ *   - The CLI's `routedDispatch` fallback (when no daemon is running)
+ *
+ * Errors thrown from the change function propagate out as normal Error
+ * instances. For example, editLesson throws if the target lesson id is
+ * missing.
+ */
+export declare function dispatchOp(op: BrainOp): Promise<DispatchResult>;
+/**
+ * Route a BrainOp through a running brain daemon, or run it locally if no
+ * daemon is up.
+ *
+ * Fallback safety: we only fall back on PRE-CONNECT IPC errors (daemon not
+ * running, socket missing, connection refused). POST-CONNECT errors leave
+ * the write in an unknown state, so we error out and ask the operator to
+ * verify. See module header comment for the full rationale.
+ */
+export declare function routedDispatch(op: BrainOp): Promise<DispatchResult>;