@fractalsynapse/dsh-chapters 0.0.0-stage → 0.2.21

package/lib/auto-save.js

@@ -0,0 +1,334 @@
+/**
+ * Door 5 — subagent settlement auto-save (issue #47).
+ *
+ * The host publishes a `subagent/end` lifecycle event for every settled child
+ * run (one-shot AND each residency epoch of a continuable child). This module
+ * turns each such settlement of a chapters-preset child into an archive through
+ * the SHARED save core (src/save-core.ts) — the same pipeline `/chapters-save`
+ * runs, never a second implementation.
+ *
+ * The seam facts this leans on are MEASURED, not assumed
+ * (spikes/subagent-end/FINDINGS.md, host-subagent-seam drift rows):
+ *   - `end` fires synchronously from a microtask attached at spawn, strictly
+ *     BEFORE the run holder's dispose continuation → a SYNCHRONOUS snapshot
+ *     inside the listener sees the live child's complete log and header.
+ *   - the child header is durable kernel state (`childSessionMeta`):
+ *     `origin: 'subagent'`, `parentSession`, `agentPreset`, `delegationDepth`.
+ *     The gate reads the HEADER, never an event scan (a synthetic child can
+ *     complete turns without ever carrying `agent-preset/selected` — measured).
+ *   - fallback arm: `sessionQuery.listEvents` + `listSessions` headers are
+ *     ambient-readable after disposal (not capability-gated) — used only when
+ *     the live handle is gone at emit.
+ *
+ * Containment is the signature-listener discipline: the emitter catches listener
+ * throws by contract, but we ALSO never let one lose knowledge silently — every
+ * non-archive is either a quiet, expected skip (wrong preset, no completed turn)
+ * or a LOUD warn (unreadable, save failed).
+ */
+import { diagnosticWarn } from "./diag.js";
+import { formatWarnings } from "./warnings.js";
+import { isActiveChapter } from "./registry.js";
+import { saveSession } from "./save-core.js";
+import { lineageOf } from "./types.js";
+const hasCompletedTurn = (events) => events.some((e) => e.type === 'turn/end');
+/**
+ * The listener factory. Pure against injected reads — the real pipeline is wired
+ * by `wireSubagentAutoSave` below, and both are covered by
+ * tests/{unit,integration} rows. The callback itself is SYNCHRONOUS on the
+ * snapshot (that is the race-avoidance), chained asynchronously per child.
+ */
+export function makeSubagentEndListener(deps) {
+    // Per-child promise chain: repeated settlements of the SAME child serialize
+    // (the watermark makes the second save only see the first's records); distinct
+    // children never queue against each other. Same pattern as the signature listener.
+    const chains = new Map();
+    return (info) => {
+        try {
+            const id = info?.id;
+            if (typeof id !== 'string' || id === '') {
+                deps.warn('subagent auto-save: settlement event without a child session id — nothing archived');
+                return;
+            }
+            // --- synchronous snapshot NOW: `end` strictly precedes disposal (measured).
+            let view;
+            try {
+                view = deps.liveChild(id);
+            }
+            catch (error) {
+                deps.warn(`subagent auto-save: live read failed for ${id}: ${String(error?.message ?? error)}`);
+                view = undefined;
+            }
+            const hadLiveHandle = view !== undefined;
+            const job = async () => {
+                let arm = 'live';
+                if (view === undefined && deps.durableChild !== undefined) {
+                    try {
+                        view = await deps.durableChild(id);
+                        arm = 'durable';
+                    }
+                    catch (error) {
+                        deps.warn(`subagent auto-save: durable read failed for ${id}: ${String(error?.message ?? error)}`);
+                    }
+                }
+                if (view === undefined) {
+                    deps.warn(`subagent auto-save: child ${id} unreadable at settlement (live handle ${hadLiveHandle ? 'read failed' : 'gone'}${deps.durableChild === undefined ? ', no durable arm available' : ', durable read empty'}) — its knowledge was NOT archived`);
+                    deps.onSettled?.(id, 'skipped:unreadable');
+                    return;
+                }
+                const suffix = arm === 'durable' ? '@durable' : '';
+                // Gates, in the order the docs state. Expected skips are quiet: this fires
+                // for EVERY subagent in the profile; a warn per non-chapters child would
+                // bury the anomalies that need a human.
+                if (view.header.origin !== 'subagent') {
+                    deps.onSettled?.(id, `skipped:origin${suffix}`);
+                    return;
+                }
+                if (view.header.agentPreset !== deps.presetId) {
+                    deps.onSettled?.(id, `skipped:preset${suffix}`);
+                    return;
+                }
+                if (!hasCompletedTurn(view.events)) {
+                    deps.onSettled?.(id, `skipped:no-completed-turn${suffix}`);
+                    return;
+                }
+                try {
+                    const out = await deps.save(view);
+                    // #58: 'payloadless' is an anomaly, not an expected skip — the child settled with a
+                    // read that carried no bytes, so its knowledge is NOT archived. Loud, by the same
+                    // containment rule as 'unreadable'. 'nothing-new'/'no-completed-turn' stay quiet.
+                    if (out.skipped === 'payloadless') {
+                        deps.warn(`subagent auto-save: ${id} settled with an archive that rendered nothing — NOT archived (a payload-less read, not a short conversation): ${out.warnings.join('; ')}`);
+                    }
+                    deps.onSettled?.(id, out.skipped === null ? `saved${suffix}` : `skipped:${out.skipped}${suffix}`);
+                }
+                catch (error) {
+                    deps.warn(`subagent auto-save: archiving ${id} failed: ${String(error?.message ?? error)} — its knowledge was NOT archived`);
+                    deps.onSettled?.(id, `failed${suffix}`);
+                }
+            };
+            const prev = chains.get(id);
+            const next = prev === undefined ? job() : prev.then(job);
+            chains.set(id, next);
+            void next.catch(() => undefined).finally(() => { if (chains.get(id) === next)
+                chains.delete(id); });
+        }
+        catch (error) {
+            // never-break containment, twice: the emitter catches us, we catch ourselves.
+            deps.warn(`subagent auto-save listener threw (contained): ${String(error?.message ?? error)}`);
+        }
+    };
+}
+/**
+ * Bind the listener to the host-plane services: `agents` for the live read,
+ * `sessionQuery` for the durable fallback, `saveSession` for the archive.
+ * Returns the callback to register with `ctx.on('subagent/end', …)`.
+ *
+ * ENRICHMENT DELIBERATELY ABSENT: settlement never runs the annotator — a
+ * ten-child fanout must not fire ten LLM drains; new chapters are pending work
+ * for the idle/afterPush ladders exactly like a `/chapters-save` that skipped
+ * the manual nudge. A test pins that nothing here calls runNow.
+ */
+/**
+ * The ONE payload-bearing durable read (docs/contract.md § Durable reads, issue #58).
+ *
+ * Door 5 needs it because a continuable child is disposed before `subagent/end`; the repair door
+ * (`/chapters-repair`, #60) needs the same thing because re-deriving a chapter is worthless if the read
+ * returns metadata rows. Two copies of "read the log" is how 12 children were archived as empty shells
+ * and the seam still looked alive: `listEvents` succeeds, returns 10 correctly-typed
+ * `SessionEventRecord`s, and none of them has `data`. So this function is exported and pinned by a
+ * source-shape row that fails if a door starts reading the log by hand again.
+ */
+export async function readDurableSession(get, sessionId, onError) {
+    const sq = get('sessionQuery');
+    if (sq?.readSession === undefined)
+        return undefined;
+    // #101, measured live: the kernel can REFUSE a session (`stored session "ch-…" is corrupt: …`) even
+    // though the bytes decode fine offline, because it validates against its own format rules. Left
+    // uncaught, that one refusal propagated out of a per-session loop and cancelled an audit of 49
+    // rows — one poison item stopping the rest, the same rule the finalize queue already obeys. So the
+    // read is contained here, in the one helper both planes share, and the caller is handed the reason:
+    // skipping must be reported, never silent (#61a).
+    let read;
+    try {
+        read = await sq.readSession(sessionId);
+    }
+    catch (error) {
+        onError?.(String(error?.message ?? error).slice(0, 200));
+        return undefined;
+    }
+    const events = read?.events;
+    if (!Array.isArray(events) || events.length === 0)
+        return undefined;
+    // The header rides the same observation as the bytes being archived — origin/agentPreset/cwd are
+    // never inferred from a second scan (and never from the events, which is the r28 lesson).
+    return { events, header: read.session ?? {} };
+}
+/**
+ * The seventh archive moment (#61, Amendment A): **a rooted child that has never archived.**
+ *
+ * Door 5 is keyed on `origin: 'subagent'`. A `ch-*` continuation child is NOT a subagent — its header
+ * says `origin: user` with a `parentSession` — so no moment was watching it at all. The field case was
+ * `ch-dc3be3ab`: 2,363 events, 414 tool calls, 2 completed turns, `chapters: []`, `reservations: {}`.
+ * Not a failed archive: one never attempted. Its knowledge sits in the log and is invisible to every
+ * search on the machine, which is precisely what this plugin exists to prevent.
+ *
+ * This is the PURE gate — the listener below only does I/O, so the decision is testable (and reviewable)
+ * without a host.
+ */
+export function shouldForceChildArchive(input) {
+    if (!input.enabled)
+        return { fire: false, reason: 'childAutoArchive is off in config' };
+    if (input.header.agentPreset !== 'chapters')
+        return { fire: false, reason: 'not a chapters-preset session' };
+    // door 5 owns delegation; two doors on one child would double-write the same span
+    if (input.header.origin === 'subagent')
+        return { fire: false, reason: 'owned by subagent settlement (door 5)' };
+    // Only a ROOTED child: a session with no parent anywhere is the user's own session, whose doors are
+    // 1–3 (a human, a button, pressure) and which this plugin must not archive behind their back.
+    const parent = input.header.parentSession ?? input.lineageParent ?? '';
+    if (parent === undefined || parent === '') {
+        return { fire: false, reason: 'no lineage (header, registry row, or ch- id) — a root session, doors 1–3 own it' };
+    }
+    if (input.anchor <= 0)
+        return { fire: false, reason: 'no completed turn yet' };
+    if (input.chapterCount === 0) {
+        return { fire: true, reason: 'never archived — the hole #61 measured (2,363 events, chapters: [])' };
+    }
+    if (input.completedTurnsAboveWatermark < input.minTurns) {
+        return { fire: false, reason: `${input.completedTurnsAboveWatermark} unarchived turn(s) < childAutoArchiveMinTurns=${input.minTurns}` };
+    }
+    return { fire: true, reason: `${input.completedTurnsAboveWatermark} completed turns past the watermark (seq ${input.lastArchivedSeq})` };
+}
+/**
+ * The listener. Save-only — creates NO session and compacts NO surface, so the "no
+ * continuation-creating actions mid-step" rule is not engaged (the same reasoning that let door 5
+ * exist). Fires only on `turn/end`, reads the LIVE session's own payload-bearing events, and is
+ * watermark-idempotent: a re-run finds `nothing-new` and writes nothing.
+ */
+export function makeChildArchiveListener(deps) {
+    const chains = new Map();
+    const section = (id, job) => {
+        const prev = chains.get(id) ?? Promise.resolve();
+        const next = prev.then(job, job);
+        chains.set(id, next.then(() => undefined, () => undefined));
+    };
+    return (session, event) => {
+        try {
+            if (event?.type !== 'turn/end')
+                return;
+            const s = session;
+            const id = s?.id;
+            const header = s?.header;
+            const cwd = header?.cwd;
+            if (id === undefined || header === undefined || cwd === undefined || typeof s?.snapshotEvents !== 'function')
+                return;
+            const events = [...(s.snapshotEvents())];
+            const anchor = [...events].reverse().find((e) => e.type === 'turn/end')?.seq ?? -1;
+            section(id, async () => {
+                // resolved ONCE per section: calling the getter twice would reopen the domain store inside a
+                // live turn boundary.
+                const store = await deps.store();
+                const state0 = await store.get(id);
+                const lastArchived = state0.chapters.reduce((m, c) => Math.max(m, c.endSeq), -1);
+                const completed = events.filter((e) => e.type === 'turn/end' && e.seq > lastArchived && e.seq <= anchor).length;
+                const gate = shouldForceChildArchive({
+                    header,
+                    lineageParent: state0.parentSession ?? (id.startsWith('ch-') ? 'continuation-id' : undefined),
+                    // #255: removed stubs are not knowledge either — the gate counts what IS knowledge,
+                    // through the ONE predicate (the watermark line above still reads ALL records by design).
+                    chapterCount: state0.chapters.filter(isActiveChapter).length,
+                    lastArchivedSeq: lastArchived,
+                    anchor,
+                    completedTurnsAboveWatermark: completed,
+                    minTurns: deps.minTurns,
+                    enabled: deps.enabled,
+                });
+                if (!gate.fire)
+                    return;
+                const out = await saveSession({
+                    events, sessionId: id, cwd, store, config: deps.wiring,
+                    subagentOf: lineageOf(header),
+                });
+                if (out.records.length > 0) {
+                    deps.ctx.logger?.info?.(`dsh-chapters: forced child archive ${id} (${out.records.length} chapter(s), seqs ${out.fromSeq}..${out.anchor}) — ${gate.reason}`);
+                    // enrichment QUEUED, never run inline: this fires inside a live turn boundary.
+                    deps.wiring.scheduler?.schedule(cwd, 'archive:save');
+                    deps.onArchived?.(id, out.records.length);
+                }
+                else if (out.skipped !== 'nothing-new') {
+                    // loud, per #61: a door that decided to archive and then did not must say why.
+                    diagnosticWarn(deps.ctx.logger, 'child-archive', `${id} forced archive produced nothing (${out.skipped ?? 'unknown'}); ${formatWarnings(out.warnings, 3)}`);
+                }
+            });
+        }
+        catch (error) {
+            diagnosticWarn(deps.ctx.logger, 'child-archive', `listener failed: ${String(error?.message ?? error)}`);
+        }
+    };
+}
+export function wireSubagentAutoSave(ctx, store, wiring) {
+    const warn = (message) => {
+        // #54: the shared seam (logger warn + sink), not a second copy of the same three lines.
+        diagnosticWarn(ctx.logger, 'auto-save', message);
+    };
+    const liveChild = (sessionId) => {
+        const agents = ctx.get?.('agents');
+        const handle = agents?.get?.(sessionId);
+        const session = handle?.agent?.session ?? handle?.session;
+        if (session === undefined || typeof session.snapshotEvents !== 'function')
+            return undefined;
+        return { events: [...session.snapshotEvents()], header: (session.header ?? {}) };
+    };
+    /**
+     * The durable arm — and for a **continuable** child the ONLY arm, because the host disposes the
+     * handle before it emits `subagent/end` (`host-subagent-seam.test.ts` F4). It must return
+     * payload-bearing events, so it reads `sessionQuery.readSession` (cloned header +
+     * `snapshotSessionEvent` events, one call) and **not** `listEvents`, whose `SessionEventRecord`
+     * rows carry `seq`/`type`/`time`/`surface` and no `data` — the shape that archived 12 children
+     * as empty shells (#58; `docs/contract.md` § Durable reads).
+     */
+    const durableChild = (sessionId) => readDurableSession((name) => { try {
+        return ctx.get?.(name);
+    }
+    catch {
+        return undefined;
+    } }, sessionId);
+    const save = async (child) => {
+        const cwd = child.header.cwd;
+        if (cwd === undefined || cwd === '')
+            throw new Error('subagent child session has no workspace cwd — nowhere reachable to write');
+        const out = await saveSession({
+            events: child.events,
+            sessionId: child.header.id ?? '',
+            cwd,
+            store,
+            config: wiring,
+            subagentOf: lineageOf(child.header),
+        });
+        // Lineage: the child stays its OWN root, and that is deliberate (#47 decision, re-checked
+        // under #58). Two candidate reasons to `linkChild` it to the parent were tested and both fail:
+        // a subagent is never an ANCESTOR of anything the parent walks, so `buildIndex` would still
+        // omit it from the parent's TOC; and `rootSession` is the STORE DIRECTORY (`archive.ts:110`,
+        // `engine-core.ts:310`), so linking would silently re-home every child chapter into the
+        // parent's tree. Cross-session reachability is search's job — `buildLocalCorpus` walks every
+        // tree under the store root — and rule ancestry already reads the kernel header's parentSession
+        // (`session-rules.ruleAncestorSet`), which the frontmatter records from the same source.
+        if (out.skipped === null && out.records.length > 0 && cwd !== '') {
+            wiring.scheduler?.schedule(cwd, 'archive:autoSave');
+        }
+        // #58: `writeArchive` already says "N event(s) rendered no output"; dropping that array was
+        // why an entire door of empty archives ran for days with a clean log. Surface every warning.
+        for (const w of out.warnings)
+            warn(`subagent auto-save: ${child.header.id ?? '?'}: ${w}`);
+        return { archived: out.records.length, skipped: out.skipped, warnings: out.warnings };
+    };
+    return makeSubagentEndListener({
+        presetId: wiring.presetId,
+        liveChild,
+        durableChild,
+        save,
+        warn,
+        onSettled: (id, outcome) => { ctx.logger?.info?.(`dsh-chapters: subagent ${id} settled → ${outcome}`); },
+    });
+}
+//# sourceMappingURL=auto-save.js.map

package/lib/auto-save.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-save.js","sourceRoot":"","sources":["../src/auto-save.ts"],"names":[],"mappings":"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"}

package/lib/aux-message.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The one user-role message of an auxiliary, out-of-band model call.
+ *
+ * Several features ask a model a question without entering a session: the post-relief plot elicitation in
+ * `engine.ts`, the bar's suggestion generators in `index.ts`. Their payload is a single user message streamed through
+ * `ctx.llm.stream(...)` — it is never admitted to a session log, so it makes no producer claim and needs no
+ * `plugin:*` kind.
+ *
+ * That distinction is the point of this file. Session format v4 retired the catch-all `source.kind: 'plugin'`
+ * (`@deepseek-ai/dsh-llm`'s `MessageSourceMap`: *"there is no shared catch-all `plugin` kind"*), and a bare `plugin`
+ * is refused at row admission on 0.2.x (#43). Four aux call sites still carried the retired spelling and passed every
+ * gate for two host minors, because the repo type-checked against 0.1.5-rc.2 while the rig boots 0.2.0-rc.2
+ * (`tests/unit/host-dep-pinning.test.ts` now forbids that drift). One helper, one honest kind.
+ */
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+/** @param text - the auxiliary prompt, verbatim. @returns a user-role message for a one-off `llm.stream` call. */
+export declare function auxPromptMessage(text: string): ReturnType<typeof createUserMessage>;

package/lib/aux-message.js

@@ -0,0 +1,20 @@
+/**
+ * The one user-role message of an auxiliary, out-of-band model call.
+ *
+ * Several features ask a model a question without entering a session: the post-relief plot elicitation in
+ * `engine.ts`, the bar's suggestion generators in `index.ts`. Their payload is a single user message streamed through
+ * `ctx.llm.stream(...)` — it is never admitted to a session log, so it makes no producer claim and needs no
+ * `plugin:*` kind.
+ *
+ * That distinction is the point of this file. Session format v4 retired the catch-all `source.kind: 'plugin'`
+ * (`@deepseek-ai/dsh-llm`'s `MessageSourceMap`: *"there is no shared catch-all `plugin` kind"*), and a bare `plugin`
+ * is refused at row admission on 0.2.x (#43). Four aux call sites still carried the retired spelling and passed every
+ * gate for two host minors, because the repo type-checked against 0.1.5-rc.2 while the rig boots 0.2.0-rc.2
+ * (`tests/unit/host-dep-pinning.test.ts` now forbids that drift). One helper, one honest kind.
+ */
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+/** @param text - the auxiliary prompt, verbatim. @returns a user-role message for a one-off `llm.stream` call. */
+export function auxPromptMessage(text) {
+    return createUserMessage({ content: [{ type: 'text', text }], source: { kind: 'user' } });
+}
+//# sourceMappingURL=aux-message.js.map

package/lib/aux-message.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aux-message.js","sourceRoot":"","sources":["../src/aux-message.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AAExD,kHAAkH;AAClH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,iBAAiB,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,CAAA;AAC3F,CAAC"}