@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/domains/middleware/rules.ts

@@ -0,0 +1,42 @@
+import type { MiddlewareRuleDefinition } from "./runtime.js";
+import { STALLED_TURN_RULE_DEFINITION } from "./stalled-turn.js";
+import type { MiddlewareRule } from "./types.js";
+
+/**
+ * Builtin middleware rule definitions. Add entries here (declarative rule plus
+ * effect payloads/pure predicates) to ship a builtin policy; the snapshot
+ * channel delivers the declarative half to workers, which resolve payloads
+ * from this table by rule id.
+ */
+const BUILTIN_MIDDLEWARE_RULE_DEFINITIONS: ReadonlyArray<MiddlewareRuleDefinition> = [STALLED_TURN_RULE_DEFINITION];
+
+export const BUILTIN_MIDDLEWARE_RULE_IDS = BUILTIN_MIDDLEWARE_RULE_DEFINITIONS.map((definition) => definition.rule.id);
+
+export function listMiddlewareRuleDefinitions(): MiddlewareRuleDefinition[] {
+	return BUILTIN_MIDDLEWARE_RULE_DEFINITIONS.map(cloneRuleDefinition);
+}
+
+export function listMiddlewareRules(): MiddlewareRule[] {
+	return BUILTIN_MIDDLEWARE_RULE_DEFINITIONS.map((definition) => cloneMiddlewareRule(definition.rule));
+}
+
+export function cloneMiddlewareRule(rule: MiddlewareRule): MiddlewareRule {
+	return {
+		id: rule.id,
+		source: rule.source,
+		description: rule.description,
+		enabled: rule.enabled,
+		hooks: [...rule.hooks],
+		effectKinds: [...rule.effectKinds],
+	};
+}
+
+function cloneRuleDefinition(definition: MiddlewareRuleDefinition): MiddlewareRuleDefinition {
+	const cloned: MiddlewareRuleDefinition = {
+		rule: cloneMiddlewareRule(definition.rule),
+		effects: [...definition.effects],
+	};
+	if (definition.toolNames !== undefined) cloned.toolNames = [...definition.toolNames];
+	if (definition.predicate !== undefined) cloned.predicate = definition.predicate;
+	return cloned;
+}

package/src/domains/middleware/runtime.ts

@@ -0,0 +1,333 @@
+import { createHookBudgetTracker, type HookBudgetStats, type HookBudgetTracker } from "./budget.js";
+import { listMiddlewareRuleDefinitions } from "./rules.js";
+import {
+	MIDDLEWARE_HOOK_TEXT_MAX_CHARS,
+	type MiddlewareEffect,
+	type MiddlewareHook,
+	type MiddlewareHookInput,
+	type MiddlewareHookResult,
+	type MiddlewareRule,
+} from "./types.js";
+
+/**
+ * Runtime pairing of a declarative middleware rule with the data it needs to
+ * act. The declarative `MiddlewareRule` is what validate.ts validates and what
+ * travels in `MiddlewareSnapshot`; it carries no payloads, so effect payloads
+ * and tool scoping live here, in process, as plain data. Evaluation is a pure
+ * function over the hook input; no subprocess, no I/O.
+ */
+export interface MiddlewareRuleDefinition {
+	rule: MiddlewareRule;
+	/**
+	 * Exact tool names this rule applies to. Absent means the rule applies to
+	 * every hook input, including hooks that carry no tool name. When present,
+	 * inputs without a tool name never match.
+	 */
+	toolNames?: ReadonlyArray<string>;
+	/**
+	 * Effects emitted verbatim when the rule matches. Effects whose kind is not
+	 * declared in `rule.effectKinds` are dropped at evaluation time.
+	 */
+	effects: ReadonlyArray<MiddlewareEffect>;
+	/**
+	 * Optional pure predicate for builtin rules that need hook input inspection
+	 * beyond hook/tool matching while still travelling as visible snapshot
+	 * rules. It must not mutate input or hold runtime state.
+	 */
+	predicate?: (input: MiddlewareHookInput) => boolean;
+}
+
+/**
+ * Coded hook registration: the in-process counterpart of a declarative rule.
+ * `evaluate` runs synchronously on the caller's stack and may hold internal
+ * state it owns (loop windows, per-turn budgets), but it communicates with the
+ * rest of the system exclusively through the returned effects. Registrations
+ * share an id namespace with declarative rules; on collision the earlier
+ * entry wins.
+ */
+export interface MiddlewareHookRegistration {
+	id: string;
+	description: string;
+	hooks: ReadonlyArray<MiddlewareHook>;
+	/** Exact tool names, same matcher semantics as `MiddlewareRuleDefinition.toolNames`. */
+	toolNames?: ReadonlyArray<string>;
+	/** Synchronous evaluation. A throw is isolated and contributes no effects. */
+	evaluate(input: MiddlewareHookInput, context?: MiddlewareHookEvaluationContext): ReadonlyArray<MiddlewareEffect>;
+	/**
+	 * Optional serialized I/O phase for awaited turn boundaries. Tool callers
+	 * continue to use only `evaluate`; no async work is detached from a hook.
+	 */
+	evaluateAsync?(
+		input: MiddlewareHookInput,
+		context?: MiddlewareHookEvaluationContext,
+	): Promise<ReadonlyArray<MiddlewareEffect>>;
+}
+
+/**
+ * Ordered-evaluation context. `priorEffects` carries the effects emitted by
+ * earlier registrations in the same hook run, so a consumer registered last
+ * (e.g. the protected-artifacts guard absorbing `protect_path`) can react to
+ * them deterministically without any shared mutable state.
+ */
+export interface MiddlewareHookEvaluationContext {
+	priorEffects: ReadonlyArray<MiddlewareEffect>;
+}
+
+export type MiddlewareDiagnostic =
+	| { kind: "hook_failed"; registrationId: string; hook: MiddlewareHook; message: string }
+	| {
+			kind: "budget_exceeded";
+			registrationId: string;
+			hook: MiddlewareHook;
+			elapsedMs: number;
+			budgetMs: number;
+			/**
+			 * Steady-state signal: this post-warmup overrun is part of consistent
+			 * slowness (≥N of the last M post-warmup calls over budget), not a lone
+			 * spike. Only steady-state overruns surface as an operator notice; every
+			 * post-warmup overrun still rides the bus for telemetry.
+			 */
+			steadyStateWarn: boolean;
+			/** Rolling-window stats (p50/p95/over-count) for diagnosis. */
+			stats: HookBudgetStats;
+	  };
+
+export type MiddlewareDiagnosticSink = (diagnostic: MiddlewareDiagnostic) => void;
+
+/**
+ * Default diagnostic sink. stderr-only for now; once the typed bus lands a
+ * `middleware.hookFailed` channel, the composition root supplies a sink that
+ * also emits there.
+ */
+export function writeMiddlewareDiagnosticToStderr(diagnostic: MiddlewareDiagnostic): void {
+	if (diagnostic.kind === "hook_failed") {
+		process.stderr.write(
+			`[clio:middleware] registration '${diagnostic.registrationId}' failed on '${diagnostic.hook}': ${diagnostic.message}\n`,
+		);
+		return;
+	}
+	// A single post-warmup spike is telemetry, not operator-facing noise: only
+	// consistent slowness prints, unless CLIO_CODER_HOOK_BUDGET_DEBUG=1 asks for all.
+	if (!diagnostic.steadyStateWarn && process.env.CLIO_CODER_HOOK_BUDGET_DEBUG !== "1") return;
+	const stats = diagnostic.stats;
+	const trend =
+		stats.window > 0
+			? ` (slow on ${stats.overCount}/${stats.window} recent ${diagnostic.hook} calls, p95 ${stats.p95Ms.toFixed(1)}ms)`
+			: "";
+	process.stderr.write(
+		`[clio:middleware] registration '${diagnostic.registrationId}' exceeded budget on '${diagnostic.hook}': ` +
+			`${diagnostic.elapsedMs.toFixed(1)}ms > ${diagnostic.budgetMs}ms${trend}\n`,
+	);
+}
+
+/**
+ * Wrap a declarative rule definition as a degenerate coded registration so a
+ * single ordered evaluation path serves both. The wrapped `evaluate` keeps the
+ * rule's enabled flag, hook list, tool scoping, and declared-effect-kind
+ * filtering exactly as `runMiddlewareHook` always applied them.
+ */
+export function registrationFromRuleDefinition(definition: MiddlewareRuleDefinition): MiddlewareHookRegistration {
+	const registration: MiddlewareHookRegistration = {
+		id: definition.rule.id,
+		description: definition.rule.description,
+		hooks: [...definition.rule.hooks],
+		evaluate: (input) => evaluateRuleDefinition(definition, input),
+	};
+	if (definition.toolNames !== undefined) registration.toolNames = [...definition.toolNames];
+	return registration;
+}
+
+export interface RunMiddlewareRegistrationsOptions {
+	/** Receives isolation and budget diagnostics. Defaults to the stderr writer. */
+	onDiagnostic?: MiddlewareDiagnosticSink;
+	/** Millisecond clock, injectable for budget tests. */
+	now?: () => number;
+	/**
+	 * Session-scoped budget tracker carrying phase budgets, warmup grace, and the
+	 * rolling window. The bundle threads one persistent tracker across the run;
+	 * when absent a fresh per-call tracker is used, so a lone direct call is
+	 * always in warmup and never warns.
+	 */
+	budgetTracker?: HookBudgetTracker;
+}
+
+/**
+ * Evaluate every matching registration, in array order, against one hook
+ * input. Every registration runs; effects accumulate; the caller decides what
+ * the effects mean (the registry treats the first `block_tool` as the
+ * verdict). A throwing registration is reported and skipped, never propagated.
+ */
+export function runMiddlewareRegistrations(
+	input: MiddlewareHookInput,
+	registrations: ReadonlyArray<MiddlewareHookRegistration>,
+	options: RunMiddlewareRegistrationsOptions = {},
+): MiddlewareHookResult {
+	const onDiagnostic = options.onDiagnostic ?? writeMiddlewareDiagnosticToStderr;
+	const now = options.now ?? (() => performance.now());
+	const budgetTracker = options.budgetTracker ?? createHookBudgetTracker();
+	const effects: MiddlewareEffect[] = [];
+	const ruleIds: string[] = [];
+	for (const registration of registrations) {
+		if (!registration.hooks.includes(input.hook)) continue;
+		if (registration.toolNames !== undefined) {
+			if (input.toolName === undefined) continue;
+			if (!registration.toolNames.includes(input.toolName)) continue;
+		}
+		let emitted: ReadonlyArray<MiddlewareEffect>;
+		const startedAt = now();
+		try {
+			// Each evaluate gets its own clone so a misbehaving registration
+			// cannot mutate the input seen by later registrations.
+			emitted = registration.evaluate(cloneHookInput(input), { priorEffects: [...effects] });
+		} catch (err) {
+			emitDiagnostic(onDiagnostic, {
+				kind: "hook_failed",
+				registrationId: registration.id,
+				hook: input.hook,
+				message: err instanceof Error ? err.message : String(err),
+			});
+			continue;
+		}
+		const elapsedMs = now() - startedAt;
+		// Record every evaluation so the rolling window has an accurate
+		// denominator, but never surface warmup overruns (one-time JIT/module
+		// warmup is not misbehavior). Post-warmup overruns ride the bus for
+		// telemetry; only steady-state slowness carries steadyStateWarn.
+		const outcome = budgetTracker.record(registration.id, input.hook, elapsedMs);
+		if (outcome.exceeded && !outcome.warmup) {
+			emitDiagnostic(onDiagnostic, {
+				kind: "budget_exceeded",
+				registrationId: registration.id,
+				hook: input.hook,
+				elapsedMs,
+				budgetMs: outcome.budgetMs,
+				steadyStateWarn: outcome.warn,
+				stats: outcome.stats,
+			});
+		}
+		if (emitted.length === 0) continue;
+		for (const effect of emitted) {
+			effects.push(cloneMiddlewareEffect(effect));
+		}
+		if (!ruleIds.includes(registration.id)) ruleIds.push(registration.id);
+	}
+	return {
+		hook: input.hook,
+		input: cloneHookInput(input),
+		effects,
+		ruleIds,
+	};
+}
+
+/**
+ * Run only registrations with an async phase. Callers await this after the
+ * synchronous phase and pass its effects as prior context, preserving order
+ * without changing the latency-sensitive tool-hook contract.
+ */
+export async function runMiddlewareAsyncRegistrations(
+	input: MiddlewareHookInput,
+	registrations: ReadonlyArray<MiddlewareHookRegistration>,
+	priorEffects: ReadonlyArray<MiddlewareEffect> = [],
+	options: Pick<RunMiddlewareRegistrationsOptions, "onDiagnostic"> = {},
+): Promise<MiddlewareHookResult> {
+	const onDiagnostic = options.onDiagnostic ?? writeMiddlewareDiagnosticToStderr;
+	const effects: MiddlewareEffect[] = [];
+	const ruleIds: string[] = [];
+	for (const registration of registrations) {
+		if (registration.evaluateAsync === undefined || !registration.hooks.includes(input.hook)) continue;
+		if (registration.toolNames !== undefined) {
+			if (input.toolName === undefined || !registration.toolNames.includes(input.toolName)) continue;
+		}
+		let emitted: ReadonlyArray<MiddlewareEffect>;
+		try {
+			emitted = await registration.evaluateAsync(cloneHookInput(input), {
+				priorEffects: [...priorEffects, ...effects],
+			});
+		} catch (err) {
+			emitDiagnostic(onDiagnostic, {
+				kind: "hook_failed",
+				registrationId: registration.id,
+				hook: input.hook,
+				message: err instanceof Error ? err.message : String(err),
+			});
+			continue;
+		}
+		for (const effect of emitted) effects.push(cloneMiddlewareEffect(effect));
+		if (emitted.length > 0) ruleIds.push(registration.id);
+	}
+	return { hook: input.hook, input: cloneHookInput(input), effects, ruleIds };
+}
+
+function emitDiagnostic(sink: MiddlewareDiagnosticSink, diagnostic: MiddlewareDiagnostic): void {
+	try {
+		sink(diagnostic);
+	} catch {
+		// A diagnostics sink must never affect hook evaluation or the turn.
+	}
+}
+
+export function runMiddlewareHook(
+	input: MiddlewareHookInput,
+	definitions: ReadonlyArray<MiddlewareRuleDefinition> = listMiddlewareRuleDefinitions(),
+): MiddlewareHookResult {
+	return runMiddlewareRegistrations(input, definitions.map(registrationFromRuleDefinition));
+}
+
+function evaluateRuleDefinition(definition: MiddlewareRuleDefinition, input: MiddlewareHookInput): MiddlewareEffect[] {
+	const rule = definition.rule;
+	if (!rule.enabled) return [];
+	if (!rule.hooks.includes(input.hook)) return [];
+	if (definition.toolNames !== undefined) {
+		if (input.toolName === undefined) return [];
+		if (!definition.toolNames.includes(input.toolName)) return [];
+	}
+	if (definition.predicate !== undefined && !definition.predicate(input)) return [];
+	const declaredKinds = new Set(rule.effectKinds);
+	const emitted: MiddlewareEffect[] = [];
+	for (const effect of definition.effects) {
+		if (!declaredKinds.has(effect.kind)) continue;
+		emitted.push(cloneMiddlewareEffect(effect));
+	}
+	return emitted;
+}
+
+export function cloneMiddlewareEffect(effect: MiddlewareEffect): MiddlewareEffect {
+	switch (effect.kind) {
+		case "inject_reminder": {
+			const cloned: MiddlewareEffect = { kind: "inject_reminder", message: effect.message };
+			if (effect.severity !== undefined) cloned.severity = effect.severity;
+			return cloned;
+		}
+		case "annotate_tool_result": {
+			const cloned: MiddlewareEffect = { kind: "annotate_tool_result", message: effect.message };
+			if (effect.severity !== undefined) cloned.severity = effect.severity;
+			return cloned;
+		}
+		case "block_tool":
+			return { kind: "block_tool", reason: effect.reason, severity: effect.severity };
+		case "protect_path":
+			return { kind: "protect_path", path: effect.path, reason: effect.reason };
+		case "request_continuation":
+			return { kind: "request_continuation", message: effect.message };
+		case "require_tool":
+			return { kind: "require_tool", toolName: effect.toolName };
+		case "lock_tools":
+			return { kind: "lock_tools" };
+	}
+}
+
+function cloneHookInput(input: MiddlewareHookInput): MiddlewareHookInput {
+	const cloned: MiddlewareHookInput = { hook: input.hook };
+	if (input.runId !== undefined) cloned.runId = input.runId;
+	if (input.sessionId !== undefined) cloned.sessionId = input.sessionId;
+	if (input.turnId !== undefined) cloned.turnId = input.turnId;
+	if (input.toolCallId !== undefined) cloned.toolCallId = input.toolCallId;
+	if (input.correlationId !== undefined) cloned.correlationId = input.correlationId;
+	if (input.toolName !== undefined) cloned.toolName = input.toolName;
+	if (input.modelId !== undefined) cloned.modelId = input.modelId;
+	if (input.metadata !== undefined) cloned.metadata = { ...input.metadata };
+	if (input.toolArgs !== undefined) cloned.toolArgs = { ...input.toolArgs };
+	if (input.toolResultDetails !== undefined) cloned.toolResultDetails = { ...input.toolResultDetails };
+	if (input.text !== undefined) cloned.text = input.text.slice(0, MIDDLEWARE_HOOK_TEXT_MAX_CHARS);
+	return cloned;
+}

package/src/domains/middleware/skills-reminder.ts

@@ -0,0 +1,187 @@
+import { SKILL_SUGGESTION_ANCHOR } from "../../core/skill-activation.js";
+import type { MiddlewareHookRegistration } from "./runtime.js";
+import { type MiddlewareEffect, metadataNumber } from "./types.js";
+
+/**
+ * First-turn skills reminder. The skill-mastery batteries proved local
+ * models read and ignore every ambient prompt channel but comply with the
+ * identical instruction when it is visible user-message text, and
+ * middleware reminders are the sanctioned mechanism for that text. Once
+ * per session, on the first substantive task turn, when model-visible
+ * skills exist, this registration injects one compact line teaching the
+ * same reply protocol as the context(scope="skills") listing footer.
+ * Reminder text only: loading stays operator-gated (`pendingSkillPolicy`
+ * untouched), and a turn that already carries a pending skill request gets
+ * no reminder because the operator has already chosen.
+ */
+
+export const SKILLS_REMINDER_REGISTRATION_ID = "observer.skills-reminder";
+
+export { SKILL_SUGGESTION_ANCHOR };
+
+export function skillsReminderMessage(count: number): string {
+	// Unconditional imperative, deliberately: the skill-mastery batteries
+	// showed literal local models comply with "list and check" but never act
+	// on wording that first asks them to classify the task as skill-shaped.
+	// One listing call on the session's first turn is the accepted price.
+	return (
+		`[Skills] ${count} installed. Start this task by listing them with context(scope="skills") ` +
+		"and checking for a match; if one matches, open your reply with the line " +
+		`\`${SKILL_SUGGESTION_ANCHOR}\` (a comma-separated sequence, in order, when several compose) ` +
+		"and wait for the operator; load only on operator request. If none match, do not mention " +
+		"skills and continue with the task."
+	);
+}
+
+export interface SkillsReminderDeps {
+	/** Count of skills the model may see and suggest; 0 disables the reminder. */
+	countModelVisibleSkills(): number;
+}
+
+const NO_EFFECTS: ReadonlyArray<MiddlewareEffect> = [];
+
+// Bare greetings/acknowledgements that carry no task. A turn is treated as a
+// greeting only when EVERY token is one of these, so any real word ("fix",
+// "how", a path) makes it substantive. Conservative by design: misclassifying
+// a real task as a greeting would skip the reminder, so the set stays small.
+const GREETING_WORDS = new Set([
+	"hi",
+	"hello",
+	"hey",
+	"heya",
+	"hiya",
+	"howdy",
+	"yo",
+	"sup",
+	"hola",
+	"greetings",
+	"gm",
+	"gn",
+	"morning",
+	"afternoon",
+	"evening",
+	"good",
+	"day",
+	"night",
+	"there",
+	"you",
+	"clio",
+	"thanks",
+	"thank",
+	"thankyou",
+	"thx",
+	"ty",
+	"ok",
+	"okay",
+	"k",
+	"cool",
+	"nice",
+	"test",
+	"testing",
+	"ping",
+	"pong",
+]);
+
+/**
+ * True when a user turn carries an actual task, false for a bare greeting or
+ * acknowledgement ("hi", "hello there", "thanks"). Used to decide whether the
+ * once-per-session skills reminder spends its shot on this turn. Conservative
+ * toward substantive: empty input is the only non-greeting that returns false,
+ * and any token outside {@link GREETING_WORDS} makes the whole turn substantive,
+ * so a misclassification can only reproduce the pre-change behavior, never a
+ * new false negative on a real task.
+ */
+export function isSubstantiveUserTurn(text: string | undefined): boolean {
+	const normalized = (text ?? "")
+		.toLowerCase()
+		.replace(/[^\p{L}\p{N}\s]/gu, " ")
+		.replace(/\s+/g, " ")
+		.trim();
+	if (normalized.length === 0) return false;
+	const tokens = normalized.split(" ");
+	// A short all-greeting message is not substantive; anything longer, or with
+	// any non-greeting token, is a real task.
+	if (tokens.length > 4) return true;
+	return tokens.some((token) => !GREETING_WORDS.has(token));
+}
+
+export function createSkillsReminderRegistration(deps: SkillsReminderDeps): MiddlewareHookRegistration {
+	// The first turn_start of a fresh session fires before the session is
+	// created, so sessionId can be null there; the spent flag tracks the
+	// active session and resets when turn_start reports a different one
+	// (new/resume/fork all route through a session change).
+	let lastSeenSessionId: string | null | undefined;
+	let spentForActiveSession = false;
+	// True once we have observed this session from its opening turn (a turn with
+	// an empty conversation). A greeting-first session grows its conversation
+	// before the real task lands, so conversationMessages alone can no longer
+	// tell "fresh session, still waiting for a substantive turn" from "resumed
+	// mid-session": this flag carries that knowledge across the greeting turns.
+	let observedFreshStart = false;
+	let observedAnyTurn = false;
+
+	return {
+		id: SKILLS_REMINDER_REGISTRATION_ID,
+		description: "once per session, on the first substantive turn, teaches the skill-suggestion reply protocol",
+		hooks: ["turn_start"],
+		evaluate(input): ReadonlyArray<MiddlewareEffect> {
+			const sessionId = input.sessionId ?? null;
+			if (lastSeenSessionId === undefined) {
+				lastSeenSessionId = sessionId;
+			} else if (lastSeenSessionId === null && sessionId !== null) {
+				// A fresh session's opening turn fires before the session is created
+				// (null id); the session is created during that turn, so the next
+				// turn carries the concrete id. That is the SAME session gaining an
+				// id, not a new one, so adopt the id without resetting — otherwise a
+				// greeting-first session would look brand new on its second turn.
+				lastSeenSessionId = sessionId;
+			} else if (sessionId !== lastSeenSessionId) {
+				// A genuinely different session (new/resume/fork all route through a
+				// concrete id change): reset the per-session state.
+				lastSeenSessionId = sessionId;
+				spentForActiveSession = false;
+				observedFreshStart = false;
+				observedAnyTurn = false;
+			}
+			if (spentForActiveSession) return NO_EFFECTS;
+
+			const conversationMessages = metadataNumber(input, "conversationMessages");
+			if (!observedAnyTurn) {
+				observedAnyTurn = true;
+				// A resumed/forked conversation is first observed with history
+				// already present: mark it spent without ever reminding, so the
+				// line can never surprise mid-session. We also can't reason about
+				// freshness without the count, so treat unknown as spent.
+				if (conversationMessages === null || conversationMessages > 0) {
+					spentForActiveSession = true;
+					return NO_EFFECTS;
+				}
+				observedFreshStart = true;
+			}
+			// Only a session we watched from its opening turn is eligible; a turn
+			// we joined mid-stream never reminds.
+			if (!observedFreshStart) {
+				spentForActiveSession = true;
+				return NO_EFFECTS;
+			}
+
+			// Bare greetings do not spend the shot: it carries to the first real
+			// task turn. Everything from here consumes the session's one chance.
+			if (!isSubstantiveUserTurn(input.text)) return NO_EFFECTS;
+			spentForActiveSession = true;
+
+			// The operator already chose a skill for this turn; a reminder about
+			// suggesting one would only add noise.
+			const pendingSkillRequests = metadataNumber(input, "pendingSkillRequests");
+			if (pendingSkillRequests !== null && pendingSkillRequests > 0) return NO_EFFECTS;
+			let count = 0;
+			try {
+				count = deps.countModelVisibleSkills();
+			} catch {
+				return NO_EFFECTS;
+			}
+			if (count <= 0) return NO_EFFECTS;
+			return [{ kind: "inject_reminder", severity: "info", message: skillsReminderMessage(count) }];
+		},
+	};
+}

package/src/domains/middleware/snapshot.ts

@@ -0,0 +1,71 @@
+import { createHookBudgetTracker, resolveHookBudgetsFromEnv, resolveHookBudgetTunablesFromEnv } from "./budget.js";
+import type { MiddlewareContract } from "./contract.js";
+import { cloneMiddlewareRule, listMiddlewareRuleDefinitions, listMiddlewareRules } from "./rules.js";
+import {
+	cloneMiddlewareEffect,
+	type MiddlewareDiagnosticSink,
+	type MiddlewareHookRegistration,
+	type MiddlewareRuleDefinition,
+	registrationFromRuleDefinition,
+	runMiddlewareRegistrations,
+} from "./runtime.js";
+import type { MiddlewareRule, MiddlewareSnapshot } from "./types.js";
+
+export function createMiddlewareSnapshot(
+	rules: ReadonlyArray<MiddlewareRule> = listMiddlewareRules(),
+): MiddlewareSnapshot {
+	return {
+		version: 1,
+		rules: rules.map(cloneMiddlewareRule),
+	};
+}
+
+/**
+ * Rebuild a middleware contract from a declarative snapshot, typically inside
+ * a worker subprocess. The snapshot carries no effect payloads, so each rule
+ * is resolved against the builtin definition table by id; the snapshot's
+ * declarative fields (enabled, hooks, effectKinds) stay authoritative. A rule
+ * id with no builtin definition in this binary evaluates to no effects.
+ */
+export function createMiddlewareContractFromSnapshot(snapshot: MiddlewareSnapshot): MiddlewareContract {
+	const builtinById = new Map(listMiddlewareRuleDefinitions().map((definition) => [definition.rule.id, definition]));
+	const definitions: MiddlewareRuleDefinition[] = snapshot.rules.map((rule) => {
+		const builtin = builtinById.get(rule.id);
+		const definition: MiddlewareRuleDefinition = {
+			rule: cloneMiddlewareRule(rule),
+			effects: builtin === undefined ? [] : builtin.effects.map(cloneMiddlewareEffect),
+		};
+		if (builtin?.toolNames !== undefined) definition.toolNames = [...builtin.toolNames];
+		if (builtin?.predicate !== undefined) definition.predicate = builtin.predicate;
+		return definition;
+	});
+	const registrations: MiddlewareHookRegistration[] = definitions.map(registrationFromRuleDefinition);
+	const registeredIds = new Set(registrations.map((registration) => registration.id));
+	const budgetTracker = createHookBudgetTracker({
+		budgets: resolveHookBudgetsFromEnv(),
+		...resolveHookBudgetTunablesFromEnv(),
+	});
+	let diagnosticSink: MiddlewareDiagnosticSink | undefined;
+	return {
+		runHook(input) {
+			return runMiddlewareRegistrations(input, registrations, {
+				budgetTracker,
+				...(diagnosticSink !== undefined ? { onDiagnostic: diagnosticSink } : {}),
+			});
+		},
+		listRules() {
+			return definitions.map((definition) => cloneMiddlewareRule(definition.rule));
+		},
+		snapshot() {
+			return createMiddlewareSnapshot(definitions.map((definition) => definition.rule));
+		},
+		registerHook(registration) {
+			if (registeredIds.has(registration.id)) return;
+			registeredIds.add(registration.id);
+			registrations.push(registration);
+		},
+		setDiagnosticSink(sink) {
+			diagnosticSink = sink;
+		},
+	};
+}