@treeseed/dsh-chapters 0.2.0 → 0.2.2-dev.2

package/lib/prompt-loop.js

@@ -0,0 +1,141 @@
+/**
+ * Autorun: the suggestion loop that starts the next real turn (#113).
+ *
+ * This is the piece that makes the feature a loop rather than a widget, and it is deliberately built out of
+ * the host goal driver's own observed semantics:
+ *   - the flag is **process-local** and starts disarmed, so a restart cannot resurrect a loop
+ *     (`dsh-goal-round-driver` disarms every agent on mount; a re-arm is an explicit human act);
+ *   - the next turn is started with the agent's own `followup`, which is how the goal round chains turns —
+ *     no timers, no private queue, nothing that can drift from the agent's real idle state;
+ *   - a human message **disarms** it. The host's driver only defers in that case; here the human said
+ *     "stop", because the maintainer's rule is that autorun runs "until the user stops it".
+ *
+ * The authored message carries our producer kind and its own form, so it is captured as conversation by
+ * `isSessionStateNarration` yet can never be mistaken for a human turn — the host's goal tool decides
+ * "direct human turn" by `source.kind === 'user'`, so authoring as `user` would hand this loop authority to
+ * pause and resume goals. It also never uses `source.kind: 'goal'`: an invariant companion deep-equals every
+ * goal-sourced message against the host's own template, so impersonating it is a loud failure by design.
+ */
+import { assertKernelAcceptedUserMessage } from "./notice.js";
+import { goalDriverOwnsTheTurn } from "./prompt-state.js";
+export function makePromptLoop(deps) {
+    const slots = new Map();
+    const slot = (id) => {
+        let s = slots.get(id);
+        if (s === undefined) {
+            s = { armed: 'disarmed', fired: 0, firedFor: null };
+            slots.set(id, s);
+        }
+        return s;
+    };
+    const note = (m) => { deps.log?.(m); };
+    return {
+        statusOf: (id) => { const s = slot(id); return { autorun: s.armed, fired: s.fired }; },
+        setArmed(id, on) {
+            const s = slot(id);
+            s.armed = on ? 'armed' : 'disarmed';
+            // Displace, do not defer. One loop owns the next turn: whichever the human armed last.
+            let displaced = false;
+            if (on && deps.displaceGoal !== undefined) {
+                try {
+                    displaced = deps.displaceGoal(id) === true;
+                }
+                catch (error) {
+                    deps.warn?.(`prompt: could not disarm the goal driver for ${id}: ${String(error?.message ?? error).slice(0, 120)}`);
+                }
+            }
+            // Arming mid-offer is allowed to fire for the offer already on screen: the human said "keep going
+            // from here", and making them wait for the next turn boundary is the difference between a loop and a
+            // poller. Re-arming does NOT reset the budget — that is what stops it being an infinite bypass.
+            note(on
+                ? `prompt: autorun armed for ${id} — ${displaced
+                    ? "goal continuation DISARMED (objective unchanged); the suggestion loop drives the worker"
+                    : 'the goal keeps its own continuation; this loop yields the turn to it'}`
+                : `prompt: autorun disarmed for ${id} (${String(s.fired)} round(s) spent of ${String(deps.maxRounds())})`);
+            return { autorun: s.armed, fired: s.fired, displaced };
+        },
+        disarmForHuman(id) {
+            const s = slot(id);
+            if (s.armed === 'disarmed')
+                return s.armed;
+            s.armed = 'disarmed';
+            note(`prompt: autorun disarmed for ${id} — a human prompt took the wheel`);
+            return s.armed;
+        },
+        maybeFire(id, state, goal = null) {
+            const s = slot(id);
+            if (s.armed !== 'armed' || state.status !== 'ready' || state.text === '')
+                return false;
+            // #113, the authority boundary the host drew: `GOAL:` offers RE-CUT the standing objective, and
+            // dsh-tool-goal gates that on a direct human turn (`source.kind === 'user'` in the open turn). Our
+            // autorun message is plugin-authored, so running it would either be refused mid-turn or — if we
+            // faked the kind — escalate the loop into authority it was never given. Hold it for the keystroke
+            // and SAY so, rather than trying.
+            if (state.intent === 'goal-edit') {
+                deps.log?.(`prompt: NOT auto-run for ${id} — this step re-cuts the goal, which needs your keystroke (Run)`);
+                return false;
+            }
+            // One turn-starter per boundary. The host driver queues its own round when the goal is active AND
+            // armed; two loops following up at one idle edge is a race with the driver's reservation fence. We
+            // keep generating (the director's eye stays open) and run nothing until the driver is not owning it.
+            if (goalDriverOwnsTheTurn(goal)) {
+                deps.log?.(`prompt: yielding the next turn to the goal driver for ${id} (goal active and armed) — offers continue, autorun does not`);
+                return false;
+            }
+            // A goal edit invalidates the offer made against the previous revision: do not push last cycle's
+            // directive into an objective the human just re-cut.
+            if (goal !== null && state.goalRevision !== null && goal.revision !== state.goalRevision) {
+                deps.log?.(`prompt: dropping a stale offer for ${id} (generated against revision ${String(state.goalRevision)}, goal is now ${String(goal.revision)})`);
+                return false;
+            }
+            if (state.turnSeq === null)
+                return false;
+            if (s.firedFor === state.turnSeq)
+                return false; // one turn per offer, never a retry storm
+            const cap = deps.maxRounds();
+            if (s.fired >= cap) {
+                s.armed = 'disarmed';
+                deps.warn?.(`prompt: autorun stopped for ${id} after ${String(cap)} rounds (promptMaxRounds) — re-arm to continue`);
+                return false;
+            }
+            s.fired += 1;
+            s.firedFor = state.turnSeq;
+            deps.followup(id, state.text);
+            note(`prompt: autorun fired round ${String(s.fired)} of ${String(cap)} for ${id} (turn ${String(state.turnSeq)})`);
+            return true;
+        },
+        goalSignal: (id) => (deps.goalSignal === undefined ? null : deps.goalSignal(id)),
+        reset(id) {
+            slots.set(id, { armed: 'disarmed', fired: 0, firedFor: null });
+        },
+    };
+}
+/**
+ * The message the loop puts into the conversation, as kernel-admitted `user/message` data: our producer kind,
+ * a published form, and an id so the row survives the host's own admission checks.
+ *
+ * `form: 'notice'` is a deliberate pick from the kernel's published `ContextForm` union
+ * (`instructions|catalog|snapshot|notice|relay|recall`, `dsh-llm/lib/types/message.d.ts:46`), not an invented
+ * word: my first version used `prompt-suggestion` and the shared assertion refused it at the authorship
+ * boundary — which is exactly what that guard exists for. `snapshot` was unavailable in practice: it is the
+ * TOC notice's own kind+form pair, and reusing it would have made the archive screen read suggestions as
+ * notices of the archive. Reuses `notice.ts`'s
+ * assertion rather than re-deriving the rules — one predicate for one decision (#59's lesson), and the
+ * `host-seed-contract` row already drift-gates that transcription against the kernel itself.
+ *
+ * Deliberately NOT `kind: 'user'`: the host's goal tool decides "a direct human turn exists" by exactly that
+ * (`dsh-tool-goal:49-65`), so a user-kinded suggestion would hand this loop the authority to pause and
+ * resume goals. And never `kind: 'goal'`: an invariant companion deep-equals every goal-sourced message
+ * against the host's own `<goal_round>` template, so impersonation fails loudly by design.
+ */
+export function suggestPromptMessage(text, id) {
+    const data = {
+        id: `suggested-${id}`,
+        role: 'user',
+        source: { kind: 'plugin:dsh-chapters', form: 'notice' },
+        content: [{ type: 'text', text }],
+    };
+    assertKernelAcceptedUserMessage({ type: 'user/message', seq: 0, data });
+    return data;
+}
+//# sourceMappingURL=prompt-loop.js.map

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-runner.d.ts

@@ -0,0 +1,44 @@
+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;
+    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,85 @@
+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;
+                }
+                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.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.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.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.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,124 @@
+/**
+ * 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;
+    }>;
+    /** `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): {
+        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): Promise<{
+        ok: boolean;
+        text?: string;
+        reason?: string;
+    }>;
+    disarmHuman(sessionId: string): void;
+    setOff(sessionId: string): Promise<void>;
+    setOn(sessionId: string): Promise<void>;
+}

package/lib/prompt-state.js

@@ -0,0 +1,96 @@
+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 [
+        `An ACTIVE GOAL governs this session (revision ${String(goal.revision)}): ${goal.objective.slice(0, 600)}`,
+        '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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"}

package/lib/prompt.d.ts

@@ -6,9 +6,32 @@ export interface PromptRoute {
     provider: string;
     model: string;
 }
+/**
+ * An offer, or a refusal. `quiet: true` marks the refusals that are NOT news — "there is nothing to recommend
+ * yet" and "suggestions are off" — so a caller can tell silence from failure (#113: the first thing the
+ * feature did on a fresh thread was shout). Genuine failures (no route, assembly, the model call) leave
+ * `quiet` falsy so they stay visible.
+ *
+ * WHY THIS IS NOT WIRED INTO `/chapters-prompt suggest` yet: the composer ghost obtains its suggestion by
+ * EXECUTING that same command over the client remote (`src/client/prompt-ghost.ts:61-65`) and treats
+ * `kind === 'success'` with non-empty text as AN OFFER. So softening the command's `kind` would render
+ * "no suggestion — nothing to recommend yet" as ghost text: a new bug, worse than the one it fixes. The
+ * command result carries no payload slot for this distinction, and the ghost's own guard
+ * (`shouldShowGhost`) has nothing to key on. Fixing the silence properly needs one of: a structured field on
+ * the command result the client may read, the ghost calling the surface through its own seam instead of a
+ * human-facing command, or the refusal text being machine-tagged. Decided deliberately, not by prose-prefix
+ * matching — see #113.
+ */
 export interface PromptSuggestionResult {
     ok: boolean;
-    text: string;
+    text: string; /** 'nothing to recommend' when quiet; otherwise what went wrong — the bar shows it (#61). */
+    quiet?: boolean;
+    reason?: string;
+}
+/** What the surface will and won't accept, for a caller that must REPORT it (the command block, #113). */
+export interface PromptLimits {
+    maxChars: number;
+    contextChars: number;
 }
 export interface PromptConfig {
     /** config default for the model; '' ⇒ off unless a stored override says otherwise. */
@@ -42,7 +65,8 @@ export interface PromptDeps {
 export interface SuggestSession {
     id: string;
     title?: string | undefined;
-    events: SessionEventLike[];
+    events: SessionEventLike[]; /** #113: when a goal governs the session, the constraint on the next step — see `goalDirectiveOf`. Text, not a goal object: goal semantics stay in one module. */
+    goalDirective?: string | undefined;
 }
 /** The surface the host command and `/chapters-status` speak to. */
 export interface PromptSurface {
@@ -53,6 +77,10 @@ export interface PromptSurface {
     };
     setModel(spec: string | null): Promise<void>;
     suggest(session: SuggestSession): Promise<PromptSuggestionResult>;
+    /** #113: the Suggested Next Step bar's server-side access — the row plus the process-local loop flags. */
+    bar?: import('./prompt-state.ts').PromptBarAccess;
+    /** the configured caps, so an output can state the number it validated against */
+    limits(): PromptLimits;
     /** One line for /chapters-status — ON names the model, OFF names the command. */
     statusLine(): string;
 }
@@ -83,6 +111,8 @@ export declare function tailFromEvents(events: SessionEventLike[]): {
     text: string;
 }[];
 export interface SuggestFacts {
+    /** #113: the active goal's constraint on the next step, already worded. Absent ⇒ no goal block. */
+    goalDirective?: string | undefined;
     title?: string | undefined;
     chapters: {
         number: number;