@hydraharness/harness-plan-mode 0.1.1-rc.6

package/lib/types/index.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Plan mode is logged per-agent collaboration state: while active, a
+ * deployment-owned guidance section is included in each model request, and
+ * `exit_plan_mode` presents the completed plan for user review, while the
+ * `/plan off` command lets a user leave directly. Sandbox mode and approval
+ * policy enforce restrictions independently and do not read or write plan
+ * state.
+ *
+ * The state in force is folded from the session log (`plan/mode`, last one
+ * wins), so resume and fork restore it without a live mirror. User selections
+ * remain pending until the next accepted in-turn pre-step. The service includes
+ * the selected state in the proposed step assembly, then appends `plan/mode`
+ * from `agent/pre-step` only when the step is accepted. Same-step request
+ * retries reuse their assembly.
+ *
+ * The exit tool remains registered while plan mode is inactive, so entering
+ * or leaving plan mode changes only the prompt section, not the request tool
+ * catalog.
+ *
+ * Agent Note:
+ * - .agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md
+ *
+ * @module @hydraharness/harness-plan-mode
+ */
+import { Context, Service } from '@hydraharness/cordis';
+import type { Agent } from '@hydraharness/harness-agent';
+import type { SessionEvent } from '@hydraharness/harness-session';
+import type { CommandId } from '@hydraharness/harness-commands';
+export type * from './types.ts';
+declare module '@hydraharness/harness-session/types' {
+    interface SessionEventMap {
+        /**
+         * Whether plan mode is in force from this point on: log-only, non-surface,
+         * whole-value replace. The last `plan/mode` wins; a log with none folds to
+         * inactive through {@link foldPlanMode}.
+         */
+        'plan/mode': {
+            active: boolean;
+        };
+    }
+}
+declare module '@hydraharness/cordis' {
+    interface Context {
+        planMode: PlanModeController;
+    }
+}
+/**
+ * The model-facing exit tool's name. It stays registered while plan mode is
+ * inactive so the request tool catalog is stable across transitions.
+ */
+export declare const EXIT_PLAN_MODE = "exit_plan_mode";
+/** Deployment-owned plan guidance. */
+export interface PlanModeConfig {
+    /** Guidance rendered as the `plan:policy` prompt section while plan mode is active. */
+    section: string;
+}
+/**
+ * Validate deployment-owned plan guidance. Missing, blank, non-string, or
+ * unknown fields fail at plugin load rather than being ignored.
+ *
+ * @param config Raw plugin config.
+ * @returns A detached validated config.
+ */
+export declare function resolveConfig(config: PlanModeConfig): PlanModeConfig;
+/**
+ * Whether plan mode is active after the first `end` events. The last
+ * `plan/mode` wins; a prefix with none is inactive.
+ *
+ * @param events The session log or any prefix of it.
+ * @param end Fold `events[0, end)`; defaults to the whole log.
+ * @returns Whether plan mode is active.
+ */
+export declare function foldPlanMode(events: readonly SessionEvent[], end?: number): boolean;
+/**
+ * Projection unit state: the logged mode, the latest successful `/plan`
+ * selection not yet resolved by a `plan/mode` commit, and an execution whose
+ * paired `command/done` has not settled. Plain JSON (persisted-cache
+ * precondition).
+ */
+interface PlanUnitState {
+    active: boolean;
+    /** The selection's target mode; null when no selection is outstanding. */
+    wanted: boolean | null;
+    /** The latest plan command awaiting its paired settlement. */
+    running: {
+        commandId: CommandId;
+        wanted: boolean;
+    } | null;
+}
+declare module '@hydraharness/harness-session-projection/types' {
+    interface SessionProjectionStateMap {
+        plan: PlanUnitState;
+    }
+}
+/**
+ * `ctx.planMode`: owns logged plan state, applies and narrates selected state at step start,
+ * the `plan:policy` section, the `/plan` command, and the stable exit tool.
+ * UIs observe committed flips through `session/event`; there is no live mirror.
+ */
+export declare class PlanModeController extends Service {
+    static inject: string[];
+    /** Validated deployment-owned guidance. */
+    private readonly section;
+    /**
+     * Latest selection per session awaiting the next accepted in-turn pre-step.
+     * `narrate` is true for user selections and false for the exit tool, whose
+     * result already narrates the transition.
+     */
+    private readonly pendingIntents;
+    constructor(ctx: Context, config?: PlanModeConfig);
+    /**
+     * Read the logged plan state and any selected state awaiting the next
+     * accepted in-turn pre-step.
+     *
+     * @param agent The agent to read.
+     * @returns Current logged state plus a pending selection, when present.
+     */
+    get(agent: Agent): {
+        active: boolean;
+        pending?: boolean;
+    };
+    /**
+     * Select whether plan mode should be active. Between turns the method
+     * appends the change immediately because no in-turn pre-step will run until
+     * another prompt starts a turn. The open-turn fold is the idle signal:
+     * agent status stays `running` through post-turn checkpointing, when no
+     * further in-turn pre-step runs. During an open turn the selection remains
+     * pending until the next accepted in-turn pre-step. Repeated selection of
+     * the current or already-pending state is a no-op.
+     *
+     * @param agent The agent to switch.
+     * @param active Whether plan mode should be active.
+     * @returns what happened: `committed` (logged now), `queued` (awaiting the
+     * next accepted in-turn pre-step), `cancelled` (an opposite pending selection
+     * was cleared; the logged state already matches), or `noop` (already in that
+     * state).
+     */
+    set(agent: Agent, active: boolean): 'committed' | 'queued' | 'cancelled' | 'noop';
+    /** Append one pending selection before the next request assembly. */
+    private onBoundary;
+    /** Build a user-switch notice when the last logged header described the other mode. */
+    private narration;
+}
+export default PlanModeController;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -0,0 +1,449 @@
+/**
+ * Plan mode is logged per-agent collaboration state: while active, a
+ * deployment-owned guidance section is included in each model request, and
+ * `exit_plan_mode` presents the completed plan for user review, while the
+ * `/plan off` command lets a user leave directly. Sandbox mode and approval
+ * policy enforce restrictions independently and do not read or write plan
+ * state.
+ *
+ * The state in force is folded from the session log (`plan/mode`, last one
+ * wins), so resume and fork restore it without a live mirror. User selections
+ * remain pending until the next accepted in-turn pre-step. The service includes
+ * the selected state in the proposed step assembly, then appends `plan/mode`
+ * from `agent/pre-step` only when the step is accepted. Same-step request
+ * retries reuse their assembly.
+ *
+ * The exit tool remains registered while plan mode is inactive, so entering
+ * or leaving plan mode changes only the prompt section, not the request tool
+ * catalog.
+ *
+ * Agent Note:
+ * - .agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md
+ *
+ * @module @hydraharness/harness-plan-mode
+ */
+import { Service } from '@hydraharness/cordis';
+import { z as zod } from 'zod';
+import { createUserMessage } from '@hydraharness/harness-llm';
+import { defineTool } from '@hydraharness/harness-tools';
+import { UserQuestionError } from '@hydraharness/harness-user-questions';
+/**
+ * The model-facing exit tool's name. It stays registered while plan mode is
+ * inactive so the request tool catalog is stable across transitions.
+ */
+export const EXIT_PLAN_MODE = 'exit_plan_mode';
+/** The review question's id, echoed in the answer this tool reads. */
+const REVIEW_ID = 'plan-review';
+/** The review question's approve option label. */
+const APPROVE_LABEL = 'Approve';
+/** The review question's keep-planning option label. */
+const KEEP_PLANNING_LABEL = 'Keep planning';
+const EXIT_DESCRIPTION = 'Use only in plan mode. Present your plan for the user\'s review and, on approval, leave plan mode. '
+    + 'Send the COMPLETE plan as markdown, starting with a # heading that names it. '
+    + 'The user may approve (carry out the plan from your next step) or keep '
+    + 'planning — their feedback comes back in the tool result; revise and present again.';
+/** The plan's first markdown heading (any level), or `undefined` when it has none. */
+function firstHeading(plan) {
+    for (const line of plan.split('\n')) {
+        const match = /^#{1,6}\s+(.+?)\s*$/.exec(line);
+        if (match)
+            return match[1];
+    }
+    return undefined;
+}
+/**
+ * Validate deployment-owned plan guidance. Missing, blank, non-string, or
+ * unknown fields fail at plugin load rather than being ignored.
+ *
+ * @param config Raw plugin config.
+ * @returns A detached validated config.
+ */
+export function resolveConfig(config) {
+    const section = config.section;
+    if (typeof section !== 'string') {
+        throw new Error('PlanModeConfig needs a string `section`');
+    }
+    if (section.trim() === '') {
+        throw new Error('PlanModeConfig needs a non-empty `section`');
+    }
+    const unknown = Object.keys(config).filter(key => key !== 'section');
+    if (unknown.length > 0) {
+        throw new Error(`PlanModeConfig has unknown key(s) ${unknown.join(', ')} — config is { section }`);
+    }
+    return { section };
+}
+/**
+ * Whether plan mode is active after the first `end` events. The last
+ * `plan/mode` wins; a prefix with none is inactive.
+ *
+ * @param events The session log or any prefix of it.
+ * @param end Fold `events[0, end)`; defaults to the whole log.
+ * @returns Whether plan mode is active.
+ */
+export function foldPlanMode(events, end = events.length) {
+    let active = false;
+    let index = 0;
+    for (const event of events) {
+        if (index >= end)
+            break;
+        index++;
+        if (event.type === 'plan/mode')
+            active = event.data.active;
+    }
+    return active;
+}
+const planUnitStateSchema = zod.object({
+    active: zod.boolean(),
+    wanted: zod.boolean().nullable(),
+    running: zod.object({
+        commandId: zod.string(),
+        wanted: zod.boolean(),
+    }).strict().nullable(),
+}).strict();
+/** Wire payload schema of the `plan` projection. */
+const planProjectionSchema = zod.object({
+    active: zod.boolean(),
+    pending: zod.boolean(),
+});
+/** Whether the log holds an opened turn without its closing `turn/end`. */
+function hasOpenTurn(events) {
+    let open = false;
+    for (const event of events) {
+        if (event.type === 'turn/start')
+            open = true;
+        else if (event.type === 'turn/end')
+            open = false;
+    }
+    return open;
+}
+/** Plan state at the last logged request header, or `undefined` before the first header. */
+function planModeAtLastHeader(events) {
+    let lastHeader = -1;
+    let index = 0;
+    for (const event of events) {
+        if (event.type === 'request/header')
+            lastHeader = index;
+        index++;
+    }
+    if (lastHeader < 0)
+        return undefined;
+    return foldPlanMode(events, lastHeader + 1);
+}
+/**
+ * `ctx.planMode`: owns logged plan state, applies and narrates selected state at step start,
+ * the `plan:policy` section, the `/plan` command, and the stable exit tool.
+ * UIs observe committed flips through `session/event`; there is no live mirror.
+ */
+export class PlanModeController extends Service {
+    static inject = ['tools', 'systemPrompt'];
+    /** Validated deployment-owned guidance. */
+    section;
+    /**
+     * Latest selection per session awaiting the next accepted in-turn pre-step.
+     * `narrate` is true for user selections and false for the exit tool, whose
+     * result already narrates the transition.
+     */
+    pendingIntents = new WeakMap();
+    constructor(ctx, config = { section: '' }) {
+        super(ctx, 'planMode');
+        this.section = resolveConfig(config).section;
+        ctx.on('session/event', (session, event) => {
+            if (event.type === 'session/version' || event.type === 'session/version-selected')
+                this.pendingIntents.delete(session);
+        });
+        let disposed = false;
+        // Pre-step is outside Session.append publication, so it can append the
+        // log-only mode event inside an open turn without re-entering the session.
+        // A failed append remains pending for a later accepted in-turn pre-step,
+        // and policy cannot block the step.
+        ctx.on('agent/pre-step', async ({ agent, signal }, next) => {
+            const decision = await next();
+            const pending = this.pendingIntents.get(agent.session);
+            if (decision.kind === 'reject' || signal.aborted || pending === undefined)
+                return decision;
+            const narration = this.narration(agent.session, pending.active);
+            try {
+                this.onBoundary(agent.session);
+            }
+            catch (error) {
+                ctx.logger.warn('hydra-plan-mode: failed to append selected plan mode at step start: %o', error);
+                return decision;
+            }
+            return !pending.narrate || narration === undefined
+                ? decision
+                : { ...decision, messages: [...decision.messages, narration] };
+        });
+        ctx.effect(() => () => { disposed = true; }, 'hydra-plan-mode: close service lifetime');
+        ctx.systemPrompt.section({
+            name: 'plan:policy',
+            order: 50,
+            text: (context) => {
+                if (context.agent === undefined)
+                    return '';
+                const pending = this.pendingIntents.get(context.agent.session);
+                return (pending?.active ?? foldPlanMode(context.agent.session.activeEvents)) ? this.section : '';
+            },
+        });
+        // The plan projection unit (session-projection RFC): a pure event fold
+        // serving clients the whole {active, pending} value. `command/run`
+        // records the user's logged /plan selection, its paired `command/done`
+        // keeps only successful selections, and `plan/mode` records that
+        // selection and clears it. Pending is thereby a pure
+        // replay quantity: host restarts, other tabs, and cold reads all recover
+        // it from the log alone. The unit child activates only when a projection
+        // registry is composed (headless assemblies stay unaffected).
+        ctx.inject(['sessionProjections'], (projectionCtx) => {
+            projectionCtx.sessionProjections.register({
+                key: 'plan',
+                history: 'active-version',
+                stateSchema: planUnitStateSchema,
+                init: () => ({ active: false, wanted: null, running: null }),
+                apply: (state, event) => {
+                    if (event.type === 'command/run' && event.data.name === 'plan') {
+                        if (event.data.args === undefined)
+                            return state;
+                        const wanted = event.data.args.trim() !== 'off';
+                        return { ...state, running: { commandId: event.data.commandId, wanted } };
+                    }
+                    if (event.type === 'command/done' && event.data.commandId === state.running?.commandId) {
+                        const wanted = event.data.kind === 'success' && state.running.wanted !== state.active
+                            ? state.running.wanted
+                            : null;
+                        return { ...state, wanted, running: null };
+                    }
+                    if (event.type === 'plan/mode') {
+                        return { ...state, active: event.data.active, wanted: null };
+                    }
+                    return state;
+                },
+                wire: {
+                    viewSchema: planProjectionSchema,
+                    view: (state) => {
+                        const wanted = state.running?.wanted ?? state.wanted;
+                        return { active: state.active, pending: wanted !== null && wanted !== state.active };
+                    },
+                },
+                stateVersion: 3,
+            });
+        });
+        // The command child activates only when a command registry is composed.
+        ctx.inject(['commands'], (commandCtx) => {
+            commandCtx.commands.register({
+                name: 'plan',
+                description: 'Enter or leave plan mode',
+                input: { hint: '[off|message]', images: true },
+                handler: ({ agent, rawInput, attachments }) => {
+                    const message = rawInput.trim();
+                    if (message === 'off' && attachments.length > 0) {
+                        return { kind: 'error', text: 'Image attachments cannot accompany /plan off.' };
+                    }
+                    if (message === 'off') {
+                        switch (this.set(agent, false)) {
+                            case 'committed':
+                                return { kind: 'success', text: 'Plan mode off.' };
+                            case 'queued':
+                                return { kind: 'success', text: 'Leaving plan mode (applies from the next step).' };
+                            case 'cancelled':
+                                return { kind: 'success', text: 'Plan mode entry cancelled.' };
+                            case 'noop':
+                                // Repeat the queued wording while an exit still awaits the
+                                // next accepted pre-step; only a truly inactive session reads
+                                // idempotent.
+                                return foldPlanMode(agent.session.activeEvents)
+                                    ? { kind: 'success', text: 'Leaving plan mode (applies from the next step).' }
+                                    : { kind: 'success', text: 'Plan mode is already inactive.' };
+                        }
+                    }
+                    const outcome = this.set(agent, true);
+                    if (message !== '' || attachments.length > 0) {
+                        agent.steer(createUserMessage({
+                            content: [
+                                ...attachments,
+                                ...(message === '' ? [] : [{ type: 'text', text: message }]),
+                            ],
+                            source: { kind: 'user' },
+                        }));
+                    }
+                    return {
+                        kind: 'success',
+                        text: outcome === 'committed'
+                            ? 'Plan mode on. Use /plan off to leave.'
+                            : 'Entering plan mode (applies from the next step). Use /plan off to leave.',
+                    };
+                },
+            });
+        });
+        ctx.tools.register(defineTool({
+            name: EXIT_PLAN_MODE,
+            description: EXIT_DESCRIPTION,
+            parameters: {
+                plan: { type: 'string', required: true, description: 'The complete plan, as markdown, starting with a # heading that names it.' },
+            },
+            output: {
+                schema: {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                        approved: { type: 'boolean', const: true, required: true },
+                    },
+                },
+                render: () => [{ type: 'text', text: 'Plan approved — plan mode exited; carry out the plan starting with your next step.' }],
+            },
+            execute: async (args, exec) => {
+                const agent = exec.agent;
+                if (agent === undefined)
+                    throw new Error(`${EXIT_PLAN_MODE} requires a calling agent (no session to switch)`);
+                if (!foldPlanMode(agent.session.activeEvents)) {
+                    throw new Error(`${EXIT_PLAN_MODE} is only available in plan mode`);
+                }
+                if (!/^#\s+\S/.test(args.plan.trim())) {
+                    throw new Error(`${EXIT_PLAN_MODE} requires a non-empty markdown plan starting with a # heading`);
+                }
+                const interaction = ctx.get('userQuestions');
+                if (interaction === undefined) {
+                    throw new Error('no user-questions channel is available to review the plan; ask the user to switch the session mode instead');
+                }
+                const answer = await interaction.ask({
+                    questions: [{
+                            id: REVIEW_ID,
+                            header: 'Plan review',
+                            question: 'Approve this plan and leave plan mode?',
+                            detail: args.plan,
+                            options: [
+                                { label: APPROVE_LABEL, description: 'Leave plan mode; the plan is carried out from the next step.' },
+                                { label: KEEP_PLANNING_LABEL, description: 'Stay in plan mode; feedback goes back to the model.' },
+                            ],
+                            // Presentation only: a capable UI renders the plan as a review
+                            // decision instead of a generic question, and answers with one of
+                            // the labels above either way.
+                            intent: { kind: 'plan-review', approve: APPROVE_LABEL },
+                        }],
+                    agent,
+                    signal: exec.signal,
+                }).catch((cause) => {
+                    // A dismissed review is not a failed one: the user took the turn back
+                    // to say something the two options do not cover. Say so, because the
+                    // generic channel message names ask_user_question, which the model
+                    // never called. An abort (turn cancel, provider teardown) keeps its
+                    // own message — there is no user to wait for.
+                    if (cause instanceof UserQuestionError && cause.code === 'ASK_CANCELLED') {
+                        throw new Error('The user dismissed the plan review to speak instead; '
+                            + 'stay in plan mode, stop here, and wait for their message.');
+                    }
+                    throw cause;
+                });
+                // A review may outlive this plugin fiber. Without its pre-step listener,
+                // an approved selection could never be appended, so fail and keep planning.
+                if (disposed) {
+                    throw new Error('the plan-mode service was reloaded while the plan was under review; present the plan again');
+                }
+                const reviewItems = answer.answers.filter(entry => entry.id === REVIEW_ID);
+                const item = reviewItems.length === 1 ? reviewItems[0] : undefined;
+                if (item?.selected.length !== 1 || item.selected[0] !== APPROVE_LABEL || item.custom !== undefined) {
+                    const feedback = item?.custom ?? '';
+                    throw new Error(feedback === ''
+                        ? 'The user chose to keep planning; revise the plan and present it again.'
+                        : `The user chose to keep planning; their feedback: ${feedback}`);
+                }
+                // Keep plan guidance for the rest of this assistant tool batch. The
+                // silent selection is appended at the next accepted in-turn pre-step,
+                // before its request assembly.
+                this.pendingIntents.set(agent.session, { active: false, narrate: false });
+                return { approved: true };
+            },
+            presentCall: args => ({
+                card: 'generic',
+                title: firstHeading(args.plan) ?? 'Plan',
+                kind: 'other',
+                content: [{ type: 'text', text: args.plan }],
+            }),
+            presentResult: (_args, result) => ({
+                card: 'generic',
+                title: 'Plan review',
+                content: result.content,
+            }),
+        }));
+    }
+    /**
+     * Read the logged plan state and any selected state awaiting the next
+     * accepted in-turn pre-step.
+     *
+     * @param agent The agent to read.
+     * @returns Current logged state plus a pending selection, when present.
+     */
+    get(agent) {
+        const active = foldPlanMode(agent.session.activeEvents);
+        const pending = this.pendingIntents.get(agent.session);
+        return pending === undefined ? { active } : { active, pending: pending.active };
+    }
+    /**
+     * Select whether plan mode should be active. Between turns the method
+     * appends the change immediately because no in-turn pre-step will run until
+     * another prompt starts a turn. The open-turn fold is the idle signal:
+     * agent status stays `running` through post-turn checkpointing, when no
+     * further in-turn pre-step runs. During an open turn the selection remains
+     * pending until the next accepted in-turn pre-step. Repeated selection of
+     * the current or already-pending state is a no-op.
+     *
+     * @param agent The agent to switch.
+     * @param active Whether plan mode should be active.
+     * @returns what happened: `committed` (logged now), `queued` (awaiting the
+     * next accepted in-turn pre-step), `cancelled` (an opposite pending selection
+     * was cleared; the logged state already matches), or `noop` (already in that
+     * state).
+     */
+    set(agent, active) {
+        const session = agent.session;
+        const pending = this.pendingIntents.get(session);
+        const target = pending?.active ?? foldPlanMode(session.activeEvents);
+        if (active === target)
+            return 'noop';
+        if (hasOpenTurn(session.activeEvents)) {
+            this.pendingIntents.set(session, { active, narrate: true });
+            return foldPlanMode(session.activeEvents) === active ? 'cancelled' : 'queued';
+        }
+        // No open turn: commit now. Delete only after append succeeds so a
+        // failed durable write leaves the selection retryable, not dropped.
+        if (active === foldPlanMode(session.activeEvents)) {
+            this.pendingIntents.delete(session);
+            return 'cancelled';
+        }
+        session.append('plan/mode', { active });
+        this.pendingIntents.delete(session);
+        const narration = this.narration(session, active);
+        if (narration !== undefined)
+            agent.inject(narration);
+        return 'committed';
+    }
+    /** Append one pending selection before the next request assembly. */
+    onBoundary(session) {
+        const pending = this.pendingIntents.get(session);
+        if (pending === undefined)
+            return;
+        const target = pending.active;
+        if (target === foldPlanMode(session.activeEvents)) {
+            this.pendingIntents.delete(session);
+            return;
+        }
+        session.append('plan/mode', { active: target });
+        // Delete only after append succeeds so a later accepted in-turn pre-step
+        // can retry a failed durable write.
+        this.pendingIntents.delete(session);
+    }
+    /** Build a user-switch notice when the last logged header described the other mode. */
+    narration(session, target) {
+        const told = planModeAtLastHeader(session.activeEvents);
+        if (told === undefined || told === target)
+            return;
+        const text = target
+            ? 'The user switched this session to plan mode.'
+            : 'The user switched this session back to the default mode.';
+        return createUserMessage({
+            content: [{ type: 'text', text }],
+            // The narration is already one sentence, so it is its own summary.
+            source: { kind: 'plugin', plugin: 'plan-mode', form: 'notice', summary: text },
+        });
+    }
+}
+export default PlanModeController;
+//# sourceMappingURL=index.js.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,13 @@
+/** Package-owned durable plan-mode invariants. @module @hydraharness/harness-plan-mode/invariant */
+import type { Context } from '@hydraharness/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "plan-mode-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register the plan-mode invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/invariant.js

@@ -0,0 +1,43 @@
+/** Package-owned durable plan-mode invariants. @module @hydraharness/harness-plan-mode/invariant */
+const PACKAGE_NAME = '@hydraharness/harness-plan-mode';
+/** Cordis companion plugin name. */
+export const name = 'plan-mode-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/**
+ * Validate one `plan/mode` event before it reaches the durable log.
+ * `plan/mode` is a standalone whole-value event: an idle selection commits
+ * between turns and a mid-turn selection commits at the step boundary, so
+ * no turn-enclosure relation exists — only the payload shape is checkable.
+ */
+function validateEvent(event, fail) {
+    if (event.type !== 'plan/mode')
+        return;
+    const active = event.data.active;
+    if (typeof active !== 'boolean') {
+        fail(`plan/mode carries invalid active state ${JSON.stringify(active)}; expected a boolean`);
+    }
+}
+/** Install validation for loaded and newly appended plan-mode state. */
+const install = Object.assign((ctx, fail) => {
+    const seed = (session) => {
+        for (const event of session.events)
+            validateEvent(event, fail);
+    };
+    for (const session of ctx.sessions.list())
+        seed(session);
+    ctx.on('session/created', (session) => { seed(session); }, { global: true });
+    ctx.on('internal/dispatch', (_mode, eventName, args) => {
+        if (eventName !== 'session/event')
+            return;
+        const [, event] = args;
+        validateEvent(event, fail);
+    }, { global: true });
+}, { inject: ['sessions'] });
+/**
+ * Register the plan-mode invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//# sourceMappingURL=invariant.js.map

package/lib/types/types.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Pure types of the plan domain: the ONE home of the `plan` projection-key
+ * declaration, free of this package's host-side value imports (cordis
+ * service, @hydraharness/harness-tools, @hydraharness/harness-agent). Two namespace projections serve it —
+ * `./types` for host consumers, `./client` for client aggregates — with zero
+ * content duplication.
+ *
+ * @module @hydraharness/harness-plan-mode/types
+ */
+/**
+ * The plan projection's wire value. `active` is the logged state in force
+ * (the last `plan/mode`, inactive before the first); `pending` is true while
+ * a logged `/plan` selection targets a state other than `active`, has not
+ * failed through its paired `command/done`, and no later `plan/mode` event has
+ * recorded that state. Capability absence (plan-mode not composed) is the
+ * key's absence, never a value.
+ */
+export interface PlanProjection {
+    active: boolean;
+    pending: boolean;
+}
+declare module '@hydraharness/harness-session-projection/types' {
+    interface SessionProjectionMap {
+        /** Plan collaboration state folded from the plan command lifecycle and `plan/mode` events. */
+        plan: PlanProjection;
+    }
+}
+//# sourceMappingURL=types.d.ts.map