@fractalsynapse/dsh-chapters 0.0.0-stage → 0.2.21

package/lib/preset.d.ts

@@ -0,0 +1,186 @@
+/**
+ * The `chapters` agent preset row — our implementation of the host's own
+ * `@deepseek-ai/dsh-agent-preset` declaration row, mounted from the bundle patch
+ * (`cordis.patch.yml`, row id `preset-chapters`), so the preset is a visible Loader entry
+ * exactly like `preset-standard` / `preset-ptc` rather than something a plugin does aside.
+ *
+ * WHY OUR ROW AND NOT THE HOST PACKAGE DIRECTLY
+ * --------------------------------------------
+ * A preset can be unusable in two ways and both are total: one unresolvable child row makes
+ * the WHOLE preset `broken` (`mountPreset` throws on any failed row → `record.broken` →
+ * `retain()` refuses with `agent-preset/invalid`), which is the same user-visible failure as
+ * a missing preset — every chapters session stops composing while its durable log sits there
+ * intact. Measured on the stable release with a composition copy-anchored to the alpha:
+ * `@deepseek-ai/dsh-tool-schedule` is not published at 0.2.0-rc.2 at all, and the boot said
+ * `preset "chapters" is DECLARED BUT BROKEN — tool-schedule … never started`.
+ *
+ * So this row does what the host's does, plus drop-what-will-not-load. It also refuses to
+ * brick a host predating the mechanism: a `@deepseek-ai/dsh-agent-preset` row is
+ * unresolvable before 0.1.7-alpha.1, and ONE unresolvable row aborts a legacy plugin tree
+ * (`plugin tree failed to load: … Cannot find package`), while a row naming our own package
+ * resolves wherever our package runs. The support floor is 0.2.0, so that is now
+ * belt-and-braces rather than the reason — and it is why the row plugin is ours.
+ *
+ * WHAT IS COPIED FROM THE HOST'S PLUGIN, LINE FOR LINE
+ * ---------------------------------------------------
+ *  - `static inject = ['agentPresets']` — the registry's shape, never a version test.
+ *  - `static [EntryGroup.key] = true` — "preserve child expressions until their own plugins
+ *    activate". Without it the Loader interpolates `!!js` against the HOST context, and
+ *    `disabled: !!js process.platform === 'win32'` stops belonging to the child row that
+ *    owns it.
+ *  - `[Service.init]` `yield`s the registry's disposer, so Cordis owns the registration's
+ *    lifetime. That also disposes of the trap the first draft fell into: calling
+ *    `ctx.effect(disposer)` from `apply()` fires when the apply FIBER finishes, which
+ *    un-registered the preset the instant it had been registered (measured on 0.2.0-rc.2:
+ *    `register()` reported success while the roster came back without `chapters`).
+ *
+ * @module dsh-chapters/src/preset
+ */
+import { Service } from '@deepseek-ai/cordis';
+import { EntryGroup } from '@deepseek-ai/cordis-plugin-loader';
+import z from '@deepseek-ai/schemastery';
+/** One mounted plugin row of a preset composition (the Loader's own shape). A group row
+ *  carries its children in `config`; an ordinary row carries a config map. */
+export interface PresetRow {
+    id: string;
+    name: string;
+    config?: Record<string, unknown> | PresetRow[];
+    disabled?: boolean;
+    group?: boolean;
+    isolate?: Record<string, boolean>;
+}
+/** The preset definition, in the shape `AgentPresetRegistry.register()` accepts — the host
+ *  plugin's own Config: id, name?, description?, order, plugins. */
+export interface PresetDefinition {
+    id: string;
+    name?: string;
+    description?: string;
+    order?: number;
+    plugins: PresetRow[];
+}
+/** The preset identity. `config.id` is DURABLE STATE: every continuation child's log
+ *  records it as `agent-preset/selected`, so renaming it orphans those sessions. */
+export declare const CHAPTERS_PRESET_ID = "chapters";
+/**
+ * Drop rows whose module cannot be imported, keeping the group structure intact.
+ *
+ * The probe is asked with the row's FULL specifier, so a package that still exists but no
+ * longer exports the subpath a row names (`…/tools`, `…/list-agents`) is caught too — those
+ * renames are what eat presets between host versions.
+ *
+ * @param rows the composition, groups included.
+ * @param resolvable asked with each row's module specifier. MUST NOT throw.
+ * @returns the composition to register, and every drop NAMED — a silent drop is how a
+ *          preset loses a tool nobody notices.
+ */
+export declare function pruneUnresolvableRows(rows: PresetRow[], resolvable: (specifier: string) => boolean): {
+    kept: PresetRow[];
+    dropped: string[];
+};
+/** What registering a preset can end up as. Every arm has its own log line and its own
+ *  remedy, because the silent case is the one that cost a human hours. */
+export type RegisterOutcome = {
+    state: 'registered';
+} | {
+    state: 'pruned';
+    dropped: string[];
+} | {
+    state: 'already-declared';
+} | {
+    state: 'unsupported';
+} | {
+    state: 'failed';
+    reason: string;
+};
+/** The narrow surface of `ctx.get('agentPresets')` this row uses. */
+export interface PresetRegistryLike {
+    register?: (definition: PresetDefinition) => Promise<() => Promise<void>>;
+    list?: () => Promise<unknown>;
+    /** `compositionInventory()` in `@deepseek-ai/dsh-agent-preset-registry`: every declared
+     *  preset with its mounted rows and their Loader states. */
+    compositionInventory?: () => Promise<unknown>;
+}
+/**
+ * Register a declared preset, dropping rows this host cannot import.
+ *
+ * Split out of the plugin class so every arm is unit-testable without a host: the caller
+ * hands in the registry surface and a resolver.
+ *
+ * @returns the outcome AND the disposer the registry hands back — the caller must keep it
+ *          alive for the row's lifetime, which is what yielding it from `[Service.init]`
+ *          does; nothing else has the right lifetime (see the module header).
+ */
+export declare function registerPrunedPreset(presets: PresetRegistryLike | undefined, definition: PresetDefinition, resolvable: (specifier: string) => boolean): Promise<{
+    outcome: RegisterOutcome;
+    disposer?: () => Promise<void>;
+}>;
+/** One mounted row of a live preset composition, as the host's inventory reports it.
+ *  `fiberState` is the Loader's state for that row; an enabled row that is not `active`
+ *  cannot serve a session, and the roster's `broken` flag reports that only for the whole
+ *  mount — which is why the witness asks for the rows as well. */
+export interface InventoryRow {
+    entryId?: string;
+    moduleName?: string;
+    enabled?: boolean;
+    fiberState?: string;
+}
+/** One preset's entry in a `compositionInventory()` response. */
+export interface InventoryEntry {
+    id?: string;
+    broken?: string;
+    rows?: InventoryRow[];
+}
+/** Find one preset in an inventory response, tolerating a missing or odd shape. */
+export declare function inventoryEntry(raw: unknown, presetId: string): InventoryEntry | undefined;
+/** Enabled rows of one preset that are not active. A row `pending` a host service can still
+ *  activate later, so this is reported apart from `broken` and never as a refusal. */
+export declare function unusableRows(entry: InventoryEntry | undefined): string[];
+/**
+ * Whether a module specifier can be imported from THIS package's resolution family.
+ *
+ * Two limits are the host's, not ours to paper over: a RELATIVE specifier resolves without
+ * touching the filesystem (so a file-URL row would always be reported resolvable — the
+ * composition uses package specifiers only, and the drift test pins that), and a name that
+ * resolves is not yet a name that ACTIVATES, which is what the roster line reports as
+ * `DECLARED BUT BROKEN`. Never throws: an unresolvable specifier is the answer.
+ */
+export declare function resolvableFromThisPackage(specifier: string): boolean;
+/** The narrow slice of the Cordis context this row needs. */
+interface RowCtx {
+    agentPresets: PresetRegistryLike;
+    logger?: {
+        info?: (m: string) => void;
+        warn?: (m: string) => void;
+    };
+}
+/**
+ * The declaration row. `config` IS the preset definition, exactly as the host's
+ * `AgentPreset` plugin consumes it, so a profile patch can override `preset-chapters`
+ * wholesale or `disabled: true` it — the two things a runtime registration done in
+ * `apply()` cannot offer, and the reason this is a row.
+ */
+export default class ChaptersPresetRow {
+    static inject: readonly ["agentPresets"];
+    /** Preserve child `!!js` expressions until their own plugins activate. */
+    static [EntryGroup.key]: boolean;
+    static Config: z<Schemastery.ObjectS<{
+        id: z<string, string>;
+        name: z<string, string>;
+        description: z<string, string>;
+        order: z<number, number>;
+        plugins: z<any[], any[]>;
+    }>, Schemastery.ObjectT<{
+        id: z<string, string>;
+        name: z<string, string>;
+        description: z<string, string>;
+        order: z<number, number>;
+        plugins: z<any[], any[]>;
+    }>>;
+    ctx: RowCtx;
+    config: PresetDefinition;
+    constructor(ctx: RowCtx, config: PresetDefinition);
+    /** Registers, then yields the disposer so Cordis owns the registration's lifetime — the
+     *  host's own row plugin does exactly this (`yield await this.ctx.agentPresets.register(…)`). */
+    [Service.init](): AsyncGenerator<() => Promise<void>, void>;
+}
+export {};

package/lib/preset.js

@@ -0,0 +1,212 @@
+/**
+ * The `chapters` agent preset row — our implementation of the host's own
+ * `@deepseek-ai/dsh-agent-preset` declaration row, mounted from the bundle patch
+ * (`cordis.patch.yml`, row id `preset-chapters`), so the preset is a visible Loader entry
+ * exactly like `preset-standard` / `preset-ptc` rather than something a plugin does aside.
+ *
+ * WHY OUR ROW AND NOT THE HOST PACKAGE DIRECTLY
+ * --------------------------------------------
+ * A preset can be unusable in two ways and both are total: one unresolvable child row makes
+ * the WHOLE preset `broken` (`mountPreset` throws on any failed row → `record.broken` →
+ * `retain()` refuses with `agent-preset/invalid`), which is the same user-visible failure as
+ * a missing preset — every chapters session stops composing while its durable log sits there
+ * intact. Measured on the stable release with a composition copy-anchored to the alpha:
+ * `@deepseek-ai/dsh-tool-schedule` is not published at 0.2.0-rc.2 at all, and the boot said
+ * `preset "chapters" is DECLARED BUT BROKEN — tool-schedule … never started`.
+ *
+ * So this row does what the host's does, plus drop-what-will-not-load. It also refuses to
+ * brick a host predating the mechanism: a `@deepseek-ai/dsh-agent-preset` row is
+ * unresolvable before 0.1.7-alpha.1, and ONE unresolvable row aborts a legacy plugin tree
+ * (`plugin tree failed to load: … Cannot find package`), while a row naming our own package
+ * resolves wherever our package runs. The support floor is 0.2.0, so that is now
+ * belt-and-braces rather than the reason — and it is why the row plugin is ours.
+ *
+ * WHAT IS COPIED FROM THE HOST'S PLUGIN, LINE FOR LINE
+ * ---------------------------------------------------
+ *  - `static inject = ['agentPresets']` — the registry's shape, never a version test.
+ *  - `static [EntryGroup.key] = true` — "preserve child expressions until their own plugins
+ *    activate". Without it the Loader interpolates `!!js` against the HOST context, and
+ *    `disabled: !!js process.platform === 'win32'` stops belonging to the child row that
+ *    owns it.
+ *  - `[Service.init]` `yield`s the registry's disposer, so Cordis owns the registration's
+ *    lifetime. That also disposes of the trap the first draft fell into: calling
+ *    `ctx.effect(disposer)` from `apply()` fires when the apply FIBER finishes, which
+ *    un-registered the preset the instant it had been registered (measured on 0.2.0-rc.2:
+ *    `register()` reported success while the roster came back without `chapters`).
+ *
+ * @module dsh-chapters/src/preset
+ */
+import { Service } from '@deepseek-ai/cordis';
+import { EntryGroup } from '@deepseek-ai/cordis-plugin-loader';
+import z from '@deepseek-ai/schemastery';
+/** The preset identity. `config.id` is DURABLE STATE: every continuation child's log
+ *  records it as `agent-preset/selected`, so renaming it orphans those sessions. */
+export const CHAPTERS_PRESET_ID = 'chapters';
+/** Whether a row's module must be probed at all. `cordis:` rows are pseudo-modules the
+ *  Loader always provides; our own package is by definition present — its realm row is the
+ *  whole point of the preset, and pruning it would quietly delete the feature. */
+function needsProbe(row) {
+    return !row.name.startsWith('cordis:') && !row.name.startsWith('@fractalsynapse/dsh-chapters');
+}
+/**
+ * Drop rows whose module cannot be imported, keeping the group structure intact.
+ *
+ * The probe is asked with the row's FULL specifier, so a package that still exists but no
+ * longer exports the subpath a row names (`…/tools`, `…/list-agents`) is caught too — those
+ * renames are what eat presets between host versions.
+ *
+ * @param rows the composition, groups included.
+ * @param resolvable asked with each row's module specifier. MUST NOT throw.
+ * @returns the composition to register, and every drop NAMED — a silent drop is how a
+ *          preset loses a tool nobody notices.
+ */
+export function pruneUnresolvableRows(rows, resolvable) {
+    const dropped = [];
+    const keep = (row) => {
+        if (!needsProbe(row))
+            return true;
+        if (resolvable(row.name))
+            return true;
+        dropped.push(`${row.id} (${row.name})`);
+        return false;
+    };
+    const visit = (list) => list.flatMap((row) => {
+        if (row.group !== true || !Array.isArray(row.config))
+            return keep(row) ? [row] : [];
+        const children = row.config.filter(keep);
+        if (children.length === 0) {
+            dropped.push(`${row.id} (group emptied)`);
+            return [];
+        }
+        return [{ ...row, config: children }];
+    });
+    return { kept: visit(rows), dropped };
+}
+/**
+ * Register a declared preset, dropping rows this host cannot import.
+ *
+ * Split out of the plugin class so every arm is unit-testable without a host: the caller
+ * hands in the registry surface and a resolver.
+ *
+ * @returns the outcome AND the disposer the registry hands back — the caller must keep it
+ *          alive for the row's lifetime, which is what yielding it from `[Service.init]`
+ *          does; nothing else has the right lifetime (see the module header).
+ */
+export async function registerPrunedPreset(presets, definition, resolvable) {
+    if (typeof presets?.register !== 'function')
+        return { outcome: { state: 'unsupported' } };
+    const { kept, dropped } = pruneUnresolvableRows(definition.plugins, resolvable);
+    const pruned = { ...definition, plugins: kept };
+    let disposer;
+    try {
+        disposer = await presets.register(pruned);
+    }
+    catch (error) {
+        const reason = String(error?.message ?? error);
+        // A duplicate is not our failure: someone declared `chapters` themselves — a profile
+        // patch override is a legitimate choice. Their row wins; ours must not throw, because a
+        // row that fails to activate takes the preset with it, and the roster line with it.
+        if (/duplicate agent preset/i.test(reason))
+            return { outcome: { state: 'already-declared' } };
+        return { outcome: { state: 'failed', reason } };
+    }
+    return {
+        outcome: dropped.length > 0 ? { state: 'pruned', dropped } : { state: 'registered' },
+        disposer,
+    };
+}
+/** Find one preset in an inventory response, tolerating a missing or odd shape. */
+export function inventoryEntry(raw, presetId) {
+    return Array.isArray(raw) ? raw.find((entry) => entry?.id === presetId) : undefined;
+}
+/** Enabled rows of one preset that are not active. A row `pending` a host service can still
+ *  activate later, so this is reported apart from `broken` and never as a refusal. */
+export function unusableRows(entry) {
+    if (!Array.isArray(entry?.rows))
+        return [];
+    return entry.rows
+        .filter((row) => row.enabled !== false && typeof row.fiberState === 'string' && row.fiberState !== 'active')
+        .map((row) => `${row.entryId ?? '?'} (${row.moduleName ?? '?'}) ${row.fiberState}`);
+}
+/**
+ * Whether a module specifier can be imported from THIS package's resolution family.
+ *
+ * Two limits are the host's, not ours to paper over: a RELATIVE specifier resolves without
+ * touching the filesystem (so a file-URL row would always be reported resolvable — the
+ * composition uses package specifiers only, and the drift test pins that), and a name that
+ * resolves is not yet a name that ACTIVATES, which is what the roster line reports as
+ * `DECLARED BUT BROKEN`. Never throws: an unresolvable specifier is the answer.
+ */
+export function resolvableFromThisPackage(specifier) {
+    if (specifier.startsWith('.') || specifier.startsWith('/') || specifier.startsWith('file:'))
+        return true;
+    try {
+        import.meta.resolve(specifier);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The declaration row. `config` IS the preset definition, exactly as the host's
+ * `AgentPreset` plugin consumes it, so a profile patch can override `preset-chapters`
+ * wholesale or `disabled: true` it — the two things a runtime registration done in
+ * `apply()` cannot offer, and the reason this is a row.
+ */
+export default class ChaptersPresetRow {
+    static inject = ['agentPresets'];
+    /** Preserve child `!!js` expressions until their own plugins activate. */
+    static [EntryGroup.key] = true;
+    static Config = z.object({
+        id: z.string().required(),
+        name: z.string(),
+        description: z.string(),
+        order: z.number(),
+        plugins: z.array(z.any()).required(),
+    });
+    ctx;
+    config;
+    constructor(ctx, config) {
+        this.ctx = ctx;
+        this.config = config;
+    }
+    /** Registers, then yields the disposer so Cordis owns the registration's lifetime — the
+     *  host's own row plugin does exactly this (`yield await this.ctx.agentPresets.register(…)`). */
+    async *[Service.init]() {
+        const { outcome, disposer } = await registerPrunedPreset(this.ctx.agentPresets, this.config, resolvableFromThisPackage);
+        const log = (message, warn) => {
+            // `ctx.logger` alone is invisible to a headless `dsh web` (r19), so the loud arms go
+            // to stderr as well — a health line nobody reads is how the silent case survived.
+            if (warn) {
+                this.ctx.logger?.warn?.(message);
+                console.error(message);
+            }
+            else
+                this.ctx.logger?.info?.(message);
+        };
+        if (outcome.state === 'unsupported') {
+            // Pre-0.1.7 hosts have no register(). They are below the support floor, but saying so
+            // beats aborting their plugin tree over a row they cannot read.
+            log(`dsh-chapters: this host cannot register preset declaration rows (before 0.2.0) — the "${CHAPTERS_PRESET_ID}" preset cannot exist here; the chapters tools still work`, true);
+            return;
+        }
+        if (outcome.state === 'already-declared') {
+            log(`dsh-chapters: preset "${this.config.id}" is also declared by another row — that one is kept, this bundle's copy stands down`, false);
+            return;
+        }
+        if (outcome.state === 'failed') {
+            log(`dsh-chapters: UNHEALTHY — registering the "${this.config.id}" preset was refused: ${outcome.reason} — every session choosing it will fail to compose`, true);
+            return;
+        }
+        if (outcome.state === 'pruned') {
+            log(`dsh-chapters: preset "${this.config.id}" registered — dropped ${outcome.dropped.length} row(s) this host cannot import: ${outcome.dropped.join(', ')} (one unresolvable row would make the whole preset broken, so they are gone rather than mounted)`, false);
+        }
+        else {
+            log(`dsh-chapters: preset "${this.config.id}" registered as a declaration row`, false);
+        }
+        if (disposer !== undefined)
+            yield disposer;
+    }
+}
+//# sourceMappingURL=preset.js.map

package/lib/preset.js.map

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

package/lib/prompt-keys.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Identifiers shared by BOTH planes of the push transport (#194). One module, one spelling: the
+ * server registers the projection under this key and the client reads `useProjection(key)` — two
+ * literals in two planes would be exactly the drift #59 forbids. No node imports (the client
+ * compiles this), no DOM (the server imports this).
+ */
+export declare const PROMPT_PROJECTION_KEY = "chaptersPrompt";

package/lib/prompt-keys.js

@@ -0,0 +1,8 @@
+/**
+ * Identifiers shared by BOTH planes of the push transport (#194). One module, one spelling: the
+ * server registers the projection under this key and the client reads `useProjection(key)` — two
+ * literals in two planes would be exactly the drift #59 forbids. No node imports (the client
+ * compiles this), no DOM (the server imports this).
+ */
+export const PROMPT_PROJECTION_KEY = 'chaptersPrompt';
+//# sourceMappingURL=prompt-keys.js.map

package/lib/prompt-keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-keys.js","sourceRoot":"","sources":["../src/prompt-keys.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,gBAAgB,CAAA"}

package/lib/prompt-loop.d.ts

@@ -0,0 +1,73 @@
+import { type GoalSignal } from './prompt-state.ts';
+import type { PromptSuggestionState } from './prompt-state.ts';
+export type AutorunFlag = 'armed' | 'disarmed';
+export interface PromptLoopDeps {
+    /**
+     * Stop the goal driver re-injecting its own round while KEEPING the goal durable and unchanged
+     * (`GoalService.disarm` — "without changing durable goal phase or revision"). Optional: if the seam is
+     * absent the loop falls back to yielding the turn, so a missing host verb degrades safely instead of
+     * starting two turns at one boundary.
+     */
+    displaceGoal?: (sessionId: string) => boolean;
+    /** live-session authoring: the runner supplies the agent handle it was given at the turn boundary. */
+    followup: (sessionId: string, text: string) => void;
+    /** counts only FIRED rounds, so a suggestion nobody armed never spends the budget. */
+    maxRounds: () => number;
+    /** The LIVE goal signal for a session, from the goal service. Optional: absent means "no goal read", and
+     * the loop then behaves as if there is no goal — never as if a goal is armed. */
+    goalSignal?: (sessionId: string) => GoalSignal | null;
+    now?: () => string;
+    log?: (message: string) => void;
+    warn?: (message: string) => void;
+}
+export interface PromptLoop {
+    statusOf(sessionId: string): {
+        autorun: AutorunFlag;
+        fired: number;
+    };
+    /** The human's `/chapters-prompt autorun on|off`. Arming does not fire anything by itself. */
+    /**
+     * The human's `/chapters-prompt autorun on|off`. Arming fires nothing by itself — but it DOES displace the
+     * goal's continuation, per the spec: prompt autorun "can either introduce or REPLACE the autorun by the
+     * goal if it is running". My first pass yielded to an armed goal instead, which made the two features
+     * mutually exclusive — with a goal armed, a director's autorun would have quietly done nothing.
+     */
+    setArmed(sessionId: string, on: boolean): {
+        autorun: AutorunFlag;
+        fired: number;
+        displaced: boolean;
+    };
+    /** A human took the wheel: disarm now, keep the offer visible, and say why. */
+    disarmForHuman(sessionId: string): AutorunFlag;
+    /** Called after the runner persisted a `ready` offer. Fires at most one turn per offer. */
+    /**
+     * `goal` is the LIVE goal signal from the service, or null when there is no goal. Passing it in rather than
+     * reading a cached copy is the point: activation is process-local and changes under us (a human pause, a
+     * goal edit), and a loop that starts turns must decide against the current fact.
+     */
+    maybeFire(sessionId: string, state: PromptSuggestionState, goal?: GoalSignal | null): boolean;
+    /** `agent/created` and mount parity with the host driver: nothing arrives armed. */
+    reset(sessionId: string): void;
+    /** The live goal signal, exposed so the door can pass it at the moment of firing (never a cached copy). */
+    goalSignal(sessionId: string): GoalSignal | null;
+}
+export declare function makePromptLoop(deps: PromptLoopDeps): PromptLoop;
+/**
+ * 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 declare function suggestPromptMessage(text: string, id: string): Record<string, unknown>;

package/lib/prompt-loop.js

@@ -0,0 +1,147 @@
+/**
+ * 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
+            // #188: the round budget is a governor for open-ended iteration, not a guillotine for a goal.
+            // While a goal exists (active OR paused — paused may resume), the pursuit is bounded by the
+            // GOAL's lifecycle: max_goal_rounds where the driver runs, complete/blocked/cleared where this
+            // loop displaced it. The suggestion budget must never cut the pursuit off before the objective.
+            // No goal, or a goal that reached a terminal phase: the budget applies exactly as before.
+            const goalBoundsIt = goal !== null && (goal.phase === 'active' || goal.phase === 'paused');
+            const cap = deps.maxRounds();
+            if (!goalBoundsIt && 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