@fractalsynapse/dsh-chapters 0.0.0-stage → 0.2.20

package/lib/prompt-loop.js.map

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

package/lib/prompt-push.d.ts

@@ -0,0 +1,47 @@
+/** The record grammar: lowercase segments, each starting with a letter or digit (host grammar). */
+export declare const PROMPT_RECORD_TYPE = "plugin:dsh-chapters/prompt";
+/** Projection key — shared with the client through ONE module (src/prompt-keys.ts), never retyped. */
+export { PROMPT_PROJECTION_KEY } from './prompt-keys.ts';
+/** The bar's durable facts, versioned. `v` rides along so a future shape never folds into a lie. */
+export interface PromptPushPayload {
+    v: 1;
+    status: 'off' | 'analyzing' | 'ready' | 'failed';
+    text: string;
+    turnSeq: number | null;
+    error: string;
+    intent: 'worker-step' | 'goal-edit';
+    goalRevision: number | null;
+    autorun: 'armed' | 'disarmed';
+    at: string;
+}
+export declare function promptRecordPayload(facts: Omit<PromptPushPayload, 'v'>): PromptPushPayload;
+/** Projection fold: ours last-wins (each record carries the WHOLE state), anything else is not ours. */
+export declare function foldPromptRecord(state: PromptPushPayload | null, event: {
+    type?: unknown;
+    data?: unknown;
+} | null | undefined): PromptPushPayload | null;
+/**
+ * #218: REAL zod schemas, like the goal projection — the duck-typed `{parse}` shapes passed the
+ * server-side fold (the probe measured `stateOf` working) but the CLIENT delivery validates
+ * through `wire.viewSchema`, and an object that is not a real schema can fail that validation
+ * silently — killing the one hop this transport exists to provide. Same shape as the goal
+ * definition: stateSchema, init, apply, wire, stateVersion.
+ */
+export declare function promptProjectionDefinition(): unknown;
+export interface PushWriter {
+    append(session: unknown, payload: PromptPushPayload): boolean;
+}
+/**
+ * Resolve the host's own `appendPluginRecord`, or nothing. The anchor is the host binary
+ * (`process.argv[1]`), NOT this module's resolution scope — the probe measured every alternative
+ * failing (own copy: foreign class; bare import: realpath into the source tree). Injectable seams
+ * for tests; a production call passes nothing and reads the process.
+ */
+export declare function resolvePushWriter(seams?: {
+    anchor?: string;
+    requireFn?: (anchor: string) => {
+        resolve(spec: string): string;
+    };
+    importFn?: (resolved: string) => Promise<Record<string, unknown>>;
+    log?: (message: string) => void;
+}): Promise<PushWriter | null>;

package/lib/prompt-push.js

@@ -0,0 +1,115 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/**
+ * The push transport (#194): the bar's state as a durable plugin record + a projection fold.
+ *
+ * Probe-verified on host 0.2.1-rc.5 (spikes/push-probe/FINDINGS.md — four real boots):
+ *  - `appendPluginRecord` commits `ignorable: true` records; unknown `plugin:` types are skipped by
+ *    readers and rendered by nothing, so the steady state writes ZERO history nodes.
+ *  - The function MUST come from the host's own module instance: the plugin's own copy at the
+ *    IDENTICAL version throws `Receiver must be an instance of class Session` against a host
+ *    session, and a bare import from a `link:` install resolves by realpath into the source tree
+ *    (on a dev machine: a different host checkout than the running server). Hence the host-anchored
+ *    createRequire recipe below, one try behind try/catch, failure = pull fallback for the process.
+ *  - The projection is registered ONLY when the writer resolved — registration is the feature
+ *    signal the client reads through the standard `useProjection` seat (undefined ⇒ pull schedule).
+ */
+import { createRequire } from 'node:module';
+import { z } from 'zod';
+/** The record grammar: lowercase segments, each starting with a letter or digit (host grammar). */
+export const PROMPT_RECORD_TYPE = 'plugin:dsh-chapters/prompt';
+/** Projection key — shared with the client through ONE module (src/prompt-keys.ts), never retyped. */
+export { PROMPT_PROJECTION_KEY } from "./prompt-keys.js";
+import { PROMPT_PROJECTION_KEY } from "./prompt-keys.js";
+export function promptRecordPayload(facts) {
+    return { v: 1, ...facts };
+}
+/** Projection fold: ours last-wins (each record carries the WHOLE state), anything else is not ours. */
+export function foldPromptRecord(state, event) {
+    if (event === null || event === undefined)
+        return state;
+    if (event.type !== PROMPT_RECORD_TYPE)
+        return state;
+    const d = event.data;
+    if (d === undefined || d === null || d.v !== 1 || typeof d.status !== 'string')
+        return state;
+    return d;
+}
+/**
+ * The projection definition, duck-typed schemas included (the probe measured that the host's
+ * register accepts `{parse}` shapes; zod is not required and would be a second schema system here).
+ * Kept a value builder so the wiring can register it only when the writer resolved.
+ */
+const promptPayloadSchema = z.object({
+    v: z.literal(1),
+    status: z.enum(['off', 'analyzing', 'ready', 'failed']),
+    text: z.string(),
+    turnSeq: z.number().nullable(),
+    error: z.string(),
+    intent: z.enum(['worker-step', 'goal-edit']),
+    goalRevision: z.number().nullable(),
+    autorun: z.enum(['armed', 'disarmed']),
+    at: z.string(),
+});
+/**
+ * #218: REAL zod schemas, like the goal projection — the duck-typed `{parse}` shapes passed the
+ * server-side fold (the probe measured `stateOf` working) but the CLIENT delivery validates
+ * through `wire.viewSchema`, and an object that is not a real schema can fail that validation
+ * silently — killing the one hop this transport exists to provide. Same shape as the goal
+ * definition: stateSchema, init, apply, wire, stateVersion.
+ */
+export function promptProjectionDefinition() {
+    return {
+        key: PROMPT_PROJECTION_KEY,
+        stateSchema: promptPayloadSchema.nullable(),
+        init: () => null,
+        apply: (state, event) => foldPromptRecord(state, event),
+        wire: { viewSchema: promptPayloadSchema.nullable(), view: (s) => s },
+        stateVersion: 2,
+    };
+}
+/**
+ * Resolve the host's own `appendPluginRecord`, or nothing. The anchor is the host binary
+ * (`process.argv[1]`), NOT this module's resolution scope — the probe measured every alternative
+ * failing (own copy: foreign class; bare import: realpath into the source tree). Injectable seams
+ * for tests; a production call passes nothing and reads the process.
+ */
+export async function resolvePushWriter(seams) {
+    const anchor = seams?.anchor ?? process.argv[1] ?? process.execPath;
+    try {
+        const req = seams?.requireFn ?? ((a) => createRequire(a));
+        const resolved = req(anchor).resolve('@deepseek-ai/dsh-session');
+        const mod = await (seams?.importFn ?? ((r) => import(__rewriteRelativeImportExtension(r))))(resolved);
+        const fn = mod.appendPluginRecord ?? mod.default?.appendPluginRecord;
+        if (typeof fn !== 'function') {
+            seams?.log?.(`prompt push: host module resolved but appendPluginRecord is absent (${resolved}) — pull transport stands`);
+            return null;
+        }
+        const append = fn;
+        return {
+            append(session, payload) {
+                try {
+                    append(session, PROMPT_RECORD_TYPE, payload);
+                    return true;
+                }
+                catch (error) {
+                    // A failed append is a degraded push, never a crashed bar: the row write already happened,
+                    // the client's staleness-confirm pull covers the gap, and the reason is logged (#61).
+                    seams?.log?.(`prompt push: append failed (${String(error?.message ?? error).slice(0, 140)}) — the pull schedule covers this session`);
+                    return false;
+                }
+            },
+        };
+    }
+    catch (error) {
+        seams?.log?.(`prompt push: unavailable on this host (${String(error?.message ?? error).slice(0, 140)}) — pull transport stands`);
+        return null;
+    }
+}
+//# sourceMappingURL=prompt-push.js.map

package/lib/prompt-push.js.map

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

package/lib/prompt-runner.d.ts

@@ -0,0 +1,48 @@
+import { type PromptSuggestionState } from './prompt-state.ts';
+import type { SessionState } from './registry.ts';
+export interface GenerateOutcome {
+    ok: boolean;
+    text?: string;
+    /** #113: the goal revision this offer was generated against (null = no goal). A later edit bumps it, and
+     * an outstanding offer made under the OLD revision must not run — that is how a re-cut objective interrupts
+     * the loop instead of being bulldozed by last cycle's directive. */
+    goalRevision?: number | null;
+    /** Present when !ok && !quiet: what actually went wrong. */
+    reason?: string;
+    /** True for "there is nothing to recommend yet" — stored as `off`, never as an error. */
+    quiet?: boolean;
+}
+export interface PromptRunnerDeps {
+    /** The model IS the switch: false ⇒ the door is inert and writes nothing at all. */
+    enabled: () => boolean;
+    /** Session eligibility: root, interactive, preset-mounted. Headless children never pay the call. */
+    eligible: (session: {
+        id: string;
+        header?: Record<string, unknown>;
+    }) => boolean;
+    store: {
+        mutate(sessionId: string, fn: (state: SessionState) => SessionState): Promise<unknown>;
+    };
+    generate: (session: {
+        id: string;
+        header?: Record<string, unknown>;
+    }, turnSeq: number) => Promise<GenerateOutcome>;
+    /**
+     * Called after a `ready` offer is durably written, with the state as written. The autorun loop rides this
+     * rather than polling the row: firing on a persisted offer is what makes "the offer the human would have
+     * seen" and "the offer that ran" the same fact, and a loop that fires from its own memory can outrun the
+     * row it is supposed to be showing.
+     */
+    onReady?: (sessionId: string, state: PromptSuggestionState) => void;
+    /** #194: mirror every durable row write to the push transport. The wiring owns payload assembly
+     * and ordering; the runner only reports (session, id) at each write. Failures here must never
+     * affect the round — the pull schedule and its staleness confirm cover a dead push. */
+    pushRow?: (session: unknown, sessionId: string) => void;
+    now: () => string;
+    log?: (message: string) => void;
+    warn?: (message: string) => void;
+}
+export declare function makePromptRoundRunner(deps: PromptRunnerDeps): (session: {
+    id: string;
+    header?: Record<string, unknown>;
+}, event: unknown) => void;

package/lib/prompt-runner.js

@@ -0,0 +1,90 @@
+import { classifyOffer, noSuggestion } from "./prompt-state.js";
+export function makePromptRoundRunner(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));
+    };
+    const write = async (id, next) => {
+        await deps.store.mutate(id, (row) => ({ ...row, promptSuggestion: next }));
+    };
+    return (session, event) => {
+        try {
+            const ev = event;
+            if (ev?.type !== 'turn/end' || typeof ev.seq !== 'number')
+                return;
+            // Each early return NAMED, because "the bar never updates" has three different causes and only one of
+            // them is a switch the human set. Silent guards are how tonight took a day.
+            if (!deps.enabled()) {
+                deps.log?.('prompt: not enabled (no defining model) — round skipped');
+                return;
+            }
+            if (!deps.eligible(session)) {
+                deps.log?.(`prompt: session ${String(session.id)} not eligible — round skipped`);
+                return;
+            }
+            const id = session.id;
+            const turnSeq = ev.seq;
+            section(id, async () => {
+                // Claim the turn inside the mutate: the row is the only place "have I already done this turn?" can
+                // be answered after a restart, and the decision must see the LIVE row, not a snapshot.
+                let claimed = false;
+                await deps.store.mutate(id, (row) => {
+                    const cur = row.promptSuggestion ?? noSuggestion;
+                    const inFlightForThisTurn = cur.turnSeq === turnSeq && (cur.status === 'analyzing' || cur.status === 'ready' || cur.status === 'failed');
+                    if (inFlightForThisTurn) {
+                        claimed = false;
+                        return row;
+                    }
+                    claimed = true;
+                    return { ...row, promptSuggestion: { ...noSuggestion, status: 'analyzing', turnSeq, at: deps.now() } };
+                });
+                if (!claimed) {
+                    deps.log?.(`prompt: turn ${String(turnSeq)} already claimed for ${id}`);
+                    return;
+                }
+                deps.pushRow?.(session, id);
+                try {
+                    const out = await deps.generate(session, turnSeq);
+                    if (out.ok && typeof out.text === 'string' && out.text !== '') {
+                        // Classified HERE, at the moment of authorship: intent is a property of the durable offer, so the
+                        // bar, the `state` verb and the loop read the same fact instead of re-parsing the text three ways
+                        // (one predicate per decision, #59). The `GOAL:` prefix is stripped — the worker must never be
+                        // handed protocol scaffolding as if it were the human's own words.
+                        const offer = classifyOffer(out.text);
+                        const ready = {
+                            status: 'ready', text: offer.text, turnSeq, error: '', at: deps.now(),
+                            intent: offer.intent, goalRevision: out.goalRevision ?? null,
+                        };
+                        await write(id, ready);
+                        deps.pushRow?.(session, id);
+                        deps.log?.(`prompt: recommended next step ready for ${id} (turn ${String(turnSeq)}, ${offer.intent})`);
+                        deps.onReady?.(id, ready);
+                        return;
+                    }
+                    if (out.quiet === true) {
+                        await write(id, { ...noSuggestion, turnSeq: null });
+                        deps.pushRow?.(session, id);
+                        deps.log?.(`prompt: nothing to recommend for ${id} — bar stays silent`);
+                        return;
+                    }
+                    await write(id, { ...noSuggestion, status: 'failed', turnSeq, error: out.reason ?? 'the suggestion call returned nothing', at: deps.now() });
+                    deps.pushRow?.(session, id);
+                    deps.warn?.(`prompt: generation failed for ${id}: ${out.reason ?? 'unknown'}`);
+                }
+                catch (error) {
+                    // A failed generation is a DELIVERED failure (#61): the bar shows it, it does not vanish.
+                    const message = String(error?.message ?? error).slice(0, 200);
+                    await write(id, { ...noSuggestion, status: 'failed', turnSeq, error: message, at: deps.now() }).catch(() => undefined);
+                    deps.pushRow?.(session, id);
+                    deps.warn?.(`prompt: generation threw for ${id}: ${message}`);
+                }
+            });
+        }
+        catch (error) {
+            deps.warn?.(`prompt: turn listener failed: ${String(error?.message ?? error).slice(0, 160)}`);
+        }
+    };
+}
+//# sourceMappingURL=prompt-runner.js.map

package/lib/prompt-runner.js.map

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

package/lib/prompt-state.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Reading the session's goal, so a suggestion can serve it (#113).
+ *
+ * The durable-log shape is measured, not assumed — from a live session's own `goal/change` events:
+ *   { kind:'goal/change', version:1, operation:'create'|'resume'|'pause'|…,
+ *     goal:{ id, revision, objective, phase:'active'|'paused'|…, maxGoalRounds } }
+ * and goal rounds themselves arrive as `user/message` with `source.kind:'goal'` carrying
+ * `{goalId, revision, round}`. So the goal is readable from the log with no service dependency, which is how
+ * this plugin works everywhere else (durable reads, never a guessed API).
+ *
+ * Why it matters: a suggested next step that ignores an active goal is noise. The maintainer's rule is that
+ * the two compose — the suggestion runs alongside the goal and the loop yields when the purpose ends.
+ */
+import type { SessionEventLike } from './types.ts';
+export type GoalPhaseView = 'none' | 'active' | 'paused' | 'blocked' | 'complete';
+export interface ActiveGoal {
+    id: string;
+    revision: number;
+    objective: string;
+    phase: GoalPhaseView;
+    maxGoalRounds: number | null;
+}
+/**
+ * The newest goal declaration in the events, or null when the session has no goal.
+ *
+ * A malformed or partial row is SKIPPED rather than thrown on: this is host-authored data crossing a plugin
+ * boundary, and one unexpected row must not take the bar (or the archive) down with it.
+ *
+ * The operation vocabulary is now established from the shipped types — `GoalOperation =
+ * 'create'|'edit'|'pause'|'resume'|'complete'|'block'|'clear'` (`dsh-goal/lib/types/domain.d.ts:12`) — so
+ * `clear` (which carries `cleared: GoalRef`, not `goal`) is the real terminal removal. `delete`/`remove` are
+ * still accepted defensively: when I first wrote this I could not see the type, and a reader should not have
+ * to trust that a host rename would not silently resurrect a finished goal.
+ *
+ * LIVE reads should prefer the host's own accessors over this fold — `ctx.get('goals').get(agent)` for a
+ * `GoalView` (which also carries `roundsStarted` and the process-local `activation`), or
+ * `ctx.sessionProjections.stateOf(session,'goal')` the way `tools.ts` already reads `agentPreset`. This
+ * function exists for the paths that have only the log: repair, distill, and tests.
+ */
+export declare function readActiveGoal(events: readonly SessionEventLike[]): ActiveGoal | null;
+/** Whether the autorun loop still has a purpose to serve: armed means run on, anything else means stand down. */
+export declare function goalAuthorizesAutorun(goal: ActiveGoal | null): boolean;
+/**
+ * The goal block folded into the suggestion input. Written as a constraint on the NEXT step, not a restated
+ * objective: the model already has the conversation, and what it cannot see is that a goal governs this one.
+ */
+export declare function goalDirectiveOf(goal: ActiveGoal | null): string;
+/**
+ * The bar's durable facts, as stored on the session row (#113). `turnSeq` is the identity of an offer:
+ * it is the `turn/end` seq the suggestion was generated FOR, which is what makes "one generation per
+ * turn" idempotent across a re-delivered event, a restart, or a second pull by the client.
+ *
+ * Deliberately absent: `autorun` and `expanded`. Those are the client's process-local intent — the goal
+ * bar's `activation` in everything but name — and persisting them would let a loop resume itself across a
+ * restart, which is the property the host's goal driver explicitly does NOT have.
+ */
+export interface PromptSuggestionState {
+    status: 'off' | 'analyzing' | 'ready' | 'failed';
+    text: string;
+    turnSeq: number | null;
+    error: string;
+    at: string;
+    /** #113: what kind of step this is. `goal-edit` re-cuts the standing objective, which the host reserves for
+     * a human turn, so autorun must never act on it. Measured: `dsh-tool-goal`'s `requireDirectHuman` gates
+     * create/edit/pause/resume on `source.kind === 'user'` in the open turn. */
+    intent: 'worker-step' | 'goal-edit';
+    /** The goal `revision` this offer was generated against, or null when no goal was active. A revision bump
+     * invalidates an outstanding offer rather than pushing last cycle's directive into a re-cut objective. */
+    goalRevision: number | null;
+}
+export declare const noSuggestion: PromptSuggestionState;
+/** What the loop needs to know about the goal RIGHT NOW, from the service (activation is process-local and
+ *  is not in the log, so this is the only honest source). */
+export interface GoalSignal {
+    phase: GoalPhaseView;
+    activation: 'armed' | 'disarmed';
+    revision: number;
+}
+/**
+ * Split the protocol prefix off a suggestion. `GOAL:` means "this step changes the objective" and the human
+ * must be the one to send it; anything else is worker execution and may auto-run.
+ *
+ * Deliberately a PREFIX rule on the model's own one-line answer rather than a second structured call: the
+ * suggestion surface already validates one bounded string, and a protocol the model can see in the rules
+ * (see `prompt.ts`) costs 5 characters of `promptMaxChars` instead of another auxiliary request.
+ */
+export declare function classifyOffer(raw: string): {
+    intent: 'worker-step' | 'goal-edit';
+    text: string;
+};
+/**
+ * Does the host goal driver intend to start the next turn itself? Measured rule (`dsh-goal-round-driver`):
+ * it queues a round on idle when `phase === 'active' && activation === 'armed'`. Two loops starting turns at
+ * one boundary is a race against the driver's own reservation fence, so when this says yes we yield.
+ */
+export declare function goalDriverOwnsTheTurn(goal: GoalSignal | null): boolean;
+/**
+ * What the Suggested Next Step bar can ask the server for (#113), and the single shape the command plane
+ * exposes to the client. Kept next to `PromptSuggestionState` rather than in the loop module because the bar
+ * and the row are the same contract — a client that can read it can render it.
+ */
+export interface PromptBarAccess {
+    read(sessionId: string): Promise<PromptSuggestionState & {
+        autorun: 'armed' | 'disarmed';
+        fired: number;
+    }>;
+    /** #231: the DURABLE row alone, no loop status, no side effects — the state verb answers from this
+     * whenever a row exists. Null when the session has never been served (the mirror-worthy moment). */
+    peekRow(sessionId: string): Promise<(PromptSuggestionState & {
+        autorun: 'armed' | 'disarmed';
+        fired: number;
+    }) | null>;
+    /** #229: the heartbeat the SERVER has configured, carried on every state reply so the client's
+     * schedule matches the operator's setting without a second channel. Absent ⇒ the client treats
+     * it as zero (no ambient clock). */
+    quietHeartbeatSec?: number;
+    /** #218: mirror a just-served state read into the push transport, so the NEXT mount reads the
+     *  projection instead of pulling again — discovery self-extinguishes. Optional: a pull-only
+     *  surface (no writer) simply does not implement it, and the caller's feature check makes that a
+     *  no-op rather than an error. */
+    mirror?: (sessionId: string, session: unknown) => void;
+    /** `displaced` is the answer to "who starts the next turn": true when arming this loop also disarmed the
+     * goal driver's continuation, so the human is told which engine they just opted into. */
+    setAutorun(sessionId: string, on: boolean, session?: unknown): {
+        autorun: 'armed' | 'disarmed';
+        fired: number;
+        displaced: boolean;
+    };
+    /** #113: the bar's Run. Submits the offer on screen as a HUMAN-authored user turn, through the same
+     * follow-up path autorun uses — one behavior for "run it", whether a keystroke or the loop came first. */
+    runNow(sessionId: string, session?: unknown): Promise<{
+        ok: boolean;
+        text?: string;
+        reason?: string;
+    }>;
+    /** #225: `/chapters-prompt suggest` writes its answer INTO the row (and mirrors the record where
+     *  push exists), so an explicit request lands on the bar instead of a fenced block to copy by hand. */
+    setSuggested?(sessionId: string, text: string, session?: unknown): Promise<void>;
+    disarmHuman(sessionId: string, session?: unknown): void;
+    setOff(sessionId: string, session?: unknown): Promise<void>;
+    setOn(sessionId: string, session?: unknown): Promise<void>;
+}

package/lib/prompt-state.js

@@ -0,0 +1,101 @@
+const isStr = (v) => typeof v === 'string' && v.length > 0;
+/**
+ * The newest goal declaration in the events, or null when the session has no goal.
+ *
+ * A malformed or partial row is SKIPPED rather than thrown on: this is host-authored data crossing a plugin
+ * boundary, and one unexpected row must not take the bar (or the archive) down with it.
+ *
+ * The operation vocabulary is now established from the shipped types — `GoalOperation =
+ * 'create'|'edit'|'pause'|'resume'|'complete'|'block'|'clear'` (`dsh-goal/lib/types/domain.d.ts:12`) — so
+ * `clear` (which carries `cleared: GoalRef`, not `goal`) is the real terminal removal. `delete`/`remove` are
+ * still accepted defensively: when I first wrote this I could not see the type, and a reader should not have
+ * to trust that a host rename would not silently resurrect a finished goal.
+ *
+ * LIVE reads should prefer the host's own accessors over this fold — `ctx.get('goals').get(agent)` for a
+ * `GoalView` (which also carries `roundsStarted` and the process-local `activation`), or
+ * `ctx.sessionProjections.stateOf(session,'goal')` the way `tools.ts` already reads `agentPreset`. This
+ * function exists for the paths that have only the log: repair, distill, and tests.
+ */
+export function readActiveGoal(events) {
+    let current = null;
+    for (const ev of events) {
+        if (ev.type !== 'goal/change')
+            continue;
+        const data = (ev.data ?? {});
+        const operation = isStr(data.operation) ? data.operation : '';
+        if (operation === 'clear' || operation === 'delete' || operation === 'remove') {
+            current = null;
+            continue;
+        }
+        const goal = (data.goal ?? {});
+        if (!isStr(goal.id) || !isStr(goal.objective))
+            continue;
+        const rawPhase = isStr(goal.phase) ? goal.phase : 'active';
+        const phase = rawPhase === 'paused' ? 'paused'
+            : rawPhase === 'blocked' ? 'blocked'
+                : rawPhase === 'complete' ? 'complete'
+                    : 'active';
+        const merged = {
+            id: goal.id,
+            revision: Number.isFinite(goal.revision) ? goal.revision : (current?.revision ?? 0),
+            objective: goal.objective,
+            // A later terminal phase must not be resurrected by an unrelated row: complete is sticky per id.
+            phase: current !== null && current.id === goal.id && current.phase === 'complete' ? 'complete' : phase,
+            maxGoalRounds: Number.isFinite(goal.maxGoalRounds) ? goal.maxGoalRounds : null,
+        };
+        current = operation === 'complete' ? { ...merged, phase: 'complete' } : merged;
+    }
+    return current === null || current.phase === 'complete' ? null : current;
+}
+/** Whether the autorun loop still has a purpose to serve: armed means run on, anything else means stand down. */
+export function goalAuthorizesAutorun(goal) {
+    return goal !== null && goal.phase === 'active';
+}
+/**
+ * The goal block folded into the suggestion input. Written as a constraint on the NEXT step, not a restated
+ * objective: the model already has the conversation, and what it cannot see is that a goal governs this one.
+ */
+export function goalDirectiveOf(goal) {
+    if (goal === null)
+        return 'No goal is active for this session. Recommend the next step the work itself calls for.';
+    return [
+        // #188 invariant: the objective rides WHOLE. The slice(0, 600) that stood here was itself the
+        // truncation the contract forbids — real objectives exceed 600 chars (the one this repo's own
+        // session ran under was ~1,200), and a director steering against half an objective is the exact
+        // hallucination invite zero-truncation exists to forbid. The assembly's budget handles size:
+        // the goal block is protected, and a protected set that cannot fit refuses with the numbers.
+        `An ACTIVE GOAL governs this session (revision ${String(goal.revision)}): ${goal.objective}`,
+        'The recommended next step MUST advance that goal — a step that merely continues current work does not count.',
+        'If the goal is already accomplished, recommend the step that closes it out (mark it complete) rather than another round.',
+    ].join('\n');
+}
+export const noSuggestion = { status: 'off', text: '', turnSeq: null, error: '', at: '', intent: 'worker-step', goalRevision: null };
+/**
+ * Split the protocol prefix off a suggestion. `GOAL:` means "this step changes the objective" and the human
+ * must be the one to send it; anything else is worker execution and may auto-run.
+ *
+ * Deliberately a PREFIX rule on the model's own one-line answer rather than a second structured call: the
+ * suggestion surface already validates one bounded string, and a protocol the model can see in the rules
+ * (see `prompt.ts`) costs 5 characters of `promptMaxChars` instead of another auxiliary request.
+ */
+export function classifyOffer(raw) {
+    const t = raw.trim();
+    const m = /^GOAL\s*:\s*/i.exec(t);
+    if (m === null)
+        return { intent: 'worker-step', text: t };
+    const rest = t.slice(m[0].length).trim();
+    // `GOAL:` with nothing after it is not a re-cut; treat it as a worker step so an empty protocol never
+    // blocks the loop with a phantom "needs you" offer.
+    if (rest === '')
+        return { intent: 'worker-step', text: t };
+    return { intent: 'goal-edit', text: rest };
+}
+/**
+ * Does the host goal driver intend to start the next turn itself? Measured rule (`dsh-goal-round-driver`):
+ * it queues a round on idle when `phase === 'active' && activation === 'armed'`. Two loops starting turns at
+ * one boundary is a race against the driver's own reservation fence, so when this says yes we yield.
+ */
+export function goalDriverOwnsTheTurn(goal) {
+    return goal !== null && goal.phase === 'active' && goal.activation === 'armed';
+}
+//# sourceMappingURL=prompt-state.js.map

package/lib/prompt-state.js.map

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