@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/domains/middleware/stalled-turn.ts

@@ -0,0 +1,71 @@
+import type { MiddlewareRuleDefinition } from "./runtime.js";
+import type { MiddlewareHookInput } from "./types.js";
+
+export const STALLED_TURN_REGISTRATION_ID = "nudge.stalled-turn";
+
+export const STALLED_TURN_REQUEST_CONTINUATION_MESSAGE =
+	"You ended your turn after announcing an action without executing it: no tools were called. Continue now and perform the announced action, or state plainly that you are finished and waiting for the user.";
+
+const INTENT_PATTERN = /\b(let me|i['’]ll|i will|i am going to|i['’]m going to|now i|next i|let's|let us)\b/i;
+const LET_ME_KNOW_PATTERN = /\blet me know\b/i;
+const COMPLETION_PATTERN =
+	/^\s*(?:all\s+done|done|complete|completed|all\s+set)\b|^\s*(?:here(?:'s| is)\s+)?(?:a\s+)?summary\b|^\s*summary\s*:?$/i;
+
+export const STALLED_TURN_RULE_DEFINITION: MiddlewareRuleDefinition = {
+	rule: {
+		id: STALLED_TURN_REGISTRATION_ID,
+		source: "builtin",
+		description: "request an automatic continuation when a turn announces work but calls no tools",
+		enabled: true,
+		hooks: ["turn_end"],
+		effectKinds: ["request_continuation"],
+	},
+	effects: [{ kind: "request_continuation", message: STALLED_TURN_REQUEST_CONTINUATION_MESSAGE }],
+	predicate: shouldRequestStalledTurnContinuation,
+};
+
+export function shouldRequestStalledTurnContinuation(input: MiddlewareHookInput): boolean {
+	if (input.hook !== "turn_end") return false;
+	if (input.metadata?.turnToolCalls !== 0) return false;
+	if (!isNormalStopReason(input.metadata?.stopReason)) return false;
+
+	const lastLine = lastNonEmptyLine(input.text ?? "");
+	if (lastLine === null) return false;
+	const finalSentence = lastSentence(lastLine);
+	if (finalSentence.length === 0) return false;
+
+	if (isQuestion(finalSentence)) return false;
+	if (LET_ME_KNOW_PATTERN.test(finalSentence)) return false;
+	if (COMPLETION_PATTERN.test(lastLine) || COMPLETION_PATTERN.test(finalSentence)) return false;
+
+	return finalSentence.endsWith(":") || INTENT_PATTERN.test(finalSentence);
+}
+
+function isNormalStopReason(value: unknown): boolean {
+	if (value === undefined || value === null) return true;
+	if (typeof value !== "string") return false;
+	const normalized = value
+		.trim()
+		.toLowerCase()
+		.replace(/[\s-]+/g, "_");
+	return normalized === "stop" || normalized === "end_turn" || normalized.startsWith("stop_sequence");
+}
+
+function lastNonEmptyLine(text: string): string | null {
+	const lines = text.split(/\r?\n/);
+	for (let index = lines.length - 1; index >= 0; index -= 1) {
+		const line = lines[index]?.trim();
+		if (line && line.length > 0) return line;
+	}
+	return null;
+}
+
+function lastSentence(line: string): string {
+	const matches = line.match(/[^.!?]+[.!?]+(?:["')\]]+)?|[^.!?]+$/g);
+	const sentence = matches?.at(-1)?.trim() ?? line.trim();
+	return sentence.replace(/^[\s"'([{-]+/, "").trim();
+}
+
+function isQuestion(sentence: string): boolean {
+	return /[?]["')\]]*$/.test(sentence.trim());
+}

package/src/domains/middleware/task-board-reminder.ts

@@ -0,0 +1,87 @@
+import type { MiddlewareHookRegistration } from "./runtime.js";
+import { type MiddlewareEffect, metadataNumber } from "./types.js";
+
+/**
+ * Task-board reminder for explicitly enumerated multi-step requests. The
+ * skill-mastery batteries established that local models read and ignore
+ * ambient prompt channels (the Tool Contract routing line and the tasks
+ * prompt hint both ask for a board before multi-step work) but comply with
+ * the identical instruction as visible user-message text. Once per session,
+ * on the first turn whose user text literally enumerates three or more
+ * steps, this registration injects one compact line telling the model to
+ * open the board first. Reminder text only: no tool policy changes.
+ */
+
+export const TASK_BOARD_REMINDER_REGISTRATION_ID = "observer.task-board-reminder";
+
+export function taskBoardReminderMessage(steps: number): string {
+	return (
+		`[Tasks] This request enumerates ${steps} steps. Before the first edit, declare the task board: ` +
+		'tasks action="plan" with a title and one task per step, then work them one at a time ' +
+		'("start", then "done" with an evidence note).'
+	);
+}
+
+/**
+ * Count explicitly enumerated steps in a user turn. Only unambiguous
+ * enumerations count: a run of numeric markers ("1)", "2.", "(3)", "step 4:")
+ * that starts at 1 and increments without gaps, or three or more bulleted
+ * lines. Prose that merely mentions numbers never triggers, so the reminder
+ * cannot fire on ordinary requests.
+ */
+export function countEnumeratedSteps(text: string | undefined): number {
+	const value = text ?? "";
+	if (value.trim().length === 0) return 0;
+	const markers: number[] = [];
+	const markerPattern = /(?:^|[\s(])(?:step\s+)?([1-9])\s*[).:]\s/gi;
+	let match = markerPattern.exec(value);
+	while (match !== null) {
+		const digit = Number(match[1]);
+		if (Number.isInteger(digit)) markers.push(digit);
+		match = markerPattern.exec(value);
+	}
+	let run = 0;
+	for (const digit of markers) {
+		if (digit === run + 1) run += 1;
+		else if (digit === 1) run = 1;
+	}
+	if (run >= 3) return run;
+	const bulletLines = value.split(/\r?\n/).filter((line) => /^\s*[-*]\s+\S/.test(line)).length;
+	return bulletLines >= 3 ? bulletLines : 0;
+}
+
+const NO_EFFECTS: ReadonlyArray<MiddlewareEffect> = [];
+
+export function createTaskBoardReminderRegistration(): MiddlewareHookRegistration {
+	// Same session-tracking shape as the skills reminder: the opening turn of a
+	// fresh session can fire before the session id exists, and a genuinely
+	// different id resets the per-session state.
+	let lastSeenSessionId: string | null | undefined;
+	let spentForActiveSession = false;
+
+	return {
+		id: TASK_BOARD_REMINDER_REGISTRATION_ID,
+		description: "once per session, on the first explicitly enumerated multi-step turn, teaches the board-first protocol",
+		hooks: ["turn_start"],
+		evaluate(input): ReadonlyArray<MiddlewareEffect> {
+			const sessionId = input.sessionId ?? null;
+			if (lastSeenSessionId === undefined || (lastSeenSessionId === null && sessionId !== null)) {
+				lastSeenSessionId = sessionId;
+			} else if (sessionId !== lastSeenSessionId) {
+				lastSeenSessionId = sessionId;
+				spentForActiveSession = false;
+			}
+			if (spentForActiveSession) return NO_EFFECTS;
+
+			const steps = countEnumeratedSteps(input.text);
+			if (steps < 3) return NO_EFFECTS;
+			spentForActiveSession = true;
+
+			// A turn already carrying an operator-chosen skill flows through that
+			// skill's own workflow; do not compete with it.
+			const pendingSkillRequests = metadataNumber(input, "pendingSkillRequests");
+			if (pendingSkillRequests !== null && pendingSkillRequests > 0) return NO_EFFECTS;
+			return [{ kind: "inject_reminder", severity: "info", message: taskBoardReminderMessage(steps) }];
+		},
+	};
+}

package/src/domains/middleware/task-nudge.ts

@@ -0,0 +1,77 @@
+import { ToolNames } from "../../core/tool-names.js";
+import { type TaskBoardSnapshot, type TaskBoardTask, taskBoardCounts } from "../session/task-board.js";
+import type { MiddlewareHookRegistration } from "./runtime.js";
+import type { MiddlewareEffect, MiddlewareHookInput } from "./types.js";
+
+/**
+ * Open-tasks nudge, packaged as a turn_end hook registration.
+ *
+ * When a settled work turn (one that called tools) ends while the session
+ * task board still has pending or active tasks, the turn is carried onward
+ * with a `request_continuation` plus a paired reminder listing the open
+ * tasks. The chat-loop's one-nudge-per-turn guard bounds it: a model that
+ * stalls again after the nudge is handed back to the operator, never looped.
+ *
+ * Deliberate non-triggers: pure conversation turns (no tool calls — the
+ * operator is discussing, not delegating), aborted or errored turns, and
+ * boards where every remaining task is blocked (blocked is an honest recorded
+ * state that waits for the operator, not a stall).
+ */
+
+export const TASK_NUDGE_REGISTRATION_ID = "nudge.open-tasks";
+
+export interface CreateTaskNudgeRegistrationOptions {
+	/** Live board snapshot, or null when no board has been declared. */
+	getBoard: () => TaskBoardSnapshot | null;
+}
+
+function openTasks(board: TaskBoardSnapshot): TaskBoardTask[] {
+	return board.tasks.filter((task) => task.status === "pending" || task.status === "active");
+}
+
+export function buildOpenTasksMessage(board: TaskBoardSnapshot): string {
+	const open = openTasks(board);
+	const counts = taskBoardCounts(board);
+	const rows = open.map((task) => `  ${task.status === "active" ? "[>]" : "[ ]"} ${task.id} ${task.title}`);
+	return (
+		`[Clio Coder] task board "${board.title}" still has ${open.length} of ${counts.total} task(s) open:\n` +
+		`${rows.join("\n")}\n` +
+		`Continue working them, or record the honest state on the board: ` +
+		`tasks action="done" with an evidence note, action="block" with a reason, or action="drop". ` +
+		`Do not end the turn with a stale board.`
+	);
+}
+
+export function createTaskNudgeRegistration(options: CreateTaskNudgeRegistrationOptions): MiddlewareHookRegistration {
+	return {
+		id: TASK_NUDGE_REGISTRATION_ID,
+		description: "carry the turn onward when a work turn ends with open task-board tasks",
+		hooks: ["turn_end"],
+		evaluate(input: MiddlewareHookInput): ReadonlyArray<MiddlewareEffect> {
+			if (input.hook !== "turn_end") return [];
+			// Only settled stop turns are candidates; aborted and errored turns
+			// already carry their own recovery path. Absent stopReason is "stop",
+			// mirroring the finish contract.
+			const stopReason = input.metadata?.stopReason;
+			if (stopReason !== undefined && stopReason !== "stop") return [];
+			const turnToolCalls = input.metadata?.turnToolCalls;
+			if (typeof turnToolCalls !== "number" || turnToolCalls <= 0) return [];
+			// A surface without the tasks tool can never update the board, so
+			// nudging it would loop against a wall.
+			const activeToolNames = input.metadata?.activeToolNames;
+			if (typeof activeToolNames === "string" && !activeToolNames.split(",").includes(ToolNames.Tasks)) return [];
+			let board: TaskBoardSnapshot | null;
+			try {
+				board = options.getBoard();
+			} catch {
+				return [];
+			}
+			if (board === null || openTasks(board).length === 0) return [];
+			const message = buildOpenTasksMessage(board);
+			return [
+				{ kind: "request_continuation", message },
+				{ kind: "inject_reminder", message, severity: "warn" },
+			];
+		},
+	};
+}

package/src/domains/middleware/tool-choice-control.ts

@@ -0,0 +1,42 @@
+import type { MiddlewareEffect } from "./types.js";
+
+export type MiddlewareToolChoice = { kind: "auto" } | { kind: "required"; toolName: string } | { kind: "none" };
+
+/**
+ * Small mutable bridge between middleware hooks and the provider payload.
+ *
+ * Tool hooks run inside the registry, after a provider response has already
+ * been emitted. Their routing effects therefore apply to the *next* provider
+ * round. A required tool clears only when that exact tool starts; a text-only
+ * lock wins over later requirements and lasts until the next submitted turn.
+ */
+export interface MiddlewareToolChoiceControl {
+	apply(effects: ReadonlyArray<MiddlewareEffect>): void;
+	current(): MiddlewareToolChoice;
+	toolStarted(toolName: string): void;
+	reset(): void;
+}
+
+export function createMiddlewareToolChoiceControl(): MiddlewareToolChoiceControl {
+	let choice: MiddlewareToolChoice = { kind: "auto" };
+	return {
+		apply(effects) {
+			for (const effect of effects) {
+				if (effect.kind === "lock_tools") {
+					choice = { kind: "none" };
+					continue;
+				}
+				if (effect.kind === "require_tool" && choice.kind !== "none") {
+					choice = { kind: "required", toolName: effect.toolName };
+				}
+			}
+		},
+		current: () => choice,
+		toolStarted(toolName) {
+			if (choice.kind === "required" && choice.toolName === toolName) choice = { kind: "auto" };
+		},
+		reset() {
+			choice = { kind: "auto" };
+		},
+	};
+}

package/src/domains/middleware/types.ts

@@ -0,0 +1,131 @@
+/**
+ * The five lifecycle events of the unified middleware layer (w3 cutover).
+ * Every event has a live producer: the registry fires before_tool/after_tool
+ * in runSpec, the chat-loop fires turn_start on prompt acceptance, turn_end
+ * when the final assistant message of a run lands, and on_compaction
+ * (observe-only) before each compaction stage.
+ */
+export const MIDDLEWARE_HOOKS = ["before_tool", "after_tool", "turn_start", "turn_end", "on_compaction"] as const;
+
+export type MiddlewareHook = (typeof MIDDLEWARE_HOOKS)[number];
+
+export const MIDDLEWARE_EFFECT_KINDS = [
+	"inject_reminder",
+	"annotate_tool_result",
+	"block_tool",
+	"protect_path",
+	"request_continuation",
+	"require_tool",
+	"lock_tools",
+] as const;
+
+export type MiddlewareEffectKind = (typeof MIDDLEWARE_EFFECT_KINDS)[number];
+
+export const MIDDLEWARE_REMINDER_SEVERITIES = ["info", "advisory", "warn", "hard-block"] as const;
+
+export type MiddlewareReminderSeverity = (typeof MIDDLEWARE_REMINDER_SEVERITIES)[number];
+
+export const MIDDLEWARE_ANNOTATION_SEVERITIES = ["info", "warn"] as const;
+
+export type MiddlewareAnnotationSeverity = (typeof MIDDLEWARE_ANNOTATION_SEVERITIES)[number];
+
+export type MiddlewareEffect =
+	| { kind: "inject_reminder"; message: string; severity?: MiddlewareReminderSeverity }
+	| { kind: "annotate_tool_result"; message: string; severity?: MiddlewareAnnotationSeverity }
+	| { kind: "block_tool"; reason: string; severity: "hard-block" }
+	| { kind: "protect_path"; path: string; reason: string }
+	| { kind: "request_continuation"; message: string }
+	| { kind: "require_tool"; toolName: string }
+	| { kind: "lock_tools" };
+
+export type MiddlewareRuleSource = "builtin";
+
+export interface MiddlewareRule {
+	id: string;
+	source: MiddlewareRuleSource;
+	description: string;
+	enabled: boolean;
+	hooks: ReadonlyArray<MiddlewareHook>;
+	effectKinds: ReadonlyArray<MiddlewareEffectKind>;
+}
+
+export interface MiddlewareSnapshot {
+	version: 1;
+	rules: ReadonlyArray<MiddlewareRule>;
+}
+
+export type MiddlewareMetadataValue = string | number | boolean | null;
+
+export type MiddlewareMetadata = Readonly<Record<string, MiddlewareMetadataValue>>;
+
+/**
+ * Cap for `MiddlewareHookInput.text`, in characters. The runtime truncates
+ * longer payloads from the head when cloning inputs, so no registration ever
+ * evaluates unbounded text. Producers report the true length out of band
+ * (chat-loop sets `metadata.assistantTextChars` on turn_end).
+ */
+export const MIDDLEWARE_HOOK_TEXT_MAX_CHARS = 16_000;
+
+export interface MiddlewareHookInput {
+	hook: MiddlewareHook;
+	runId?: string;
+	sessionId?: string;
+	turnId?: string;
+	toolCallId?: string;
+	correlationId?: string;
+	toolName?: string;
+	modelId?: string;
+	metadata?: MiddlewareMetadata;
+	/**
+	 * Tool-call arguments, supplied by the registry on before_tool and
+	 * after_tool. Read-only by contract: the runtime shallow-copies the record
+	 * per evaluation, and registrations must never mutate nested values. The
+	 * typed-field route (rather than JSON in `metadata`) follows the Q3
+	 * decision for `turn_end` text.
+	 */
+	toolArgs?: Readonly<Record<string, unknown>>;
+	/** Structured result details, supplied by the registry on after_tool. Read-only by contract. */
+	toolResultDetails?: Readonly<Record<string, unknown>>;
+	/**
+	 * Free text attached to the hook occurrence; on turn_end this is the final
+	 * assistant message text. The one typed exception to the scalar `metadata`
+	 * contract (Q3 decision), capped at MIDDLEWARE_HOOK_TEXT_MAX_CHARS by the
+	 * runtime when inputs are cloned.
+	 */
+	text?: string;
+}
+
+export interface MiddlewareHookResult {
+	hook: MiddlewareHook;
+	input: MiddlewareHookInput;
+	effects: ReadonlyArray<MiddlewareEffect>;
+	ruleIds: ReadonlyArray<string>;
+}
+
+/**
+ * Read a finite number out of a hook input's metadata, or null.
+ *
+ * Metadata is an open bag a caller fills in, so a missing key, a string, a
+ * boolean, and a NaN are all the same answer: this hook was not told. Null is
+ * that answer; a zero would be a count the caller never reported.
+ */
+export function metadataNumber(input: MiddlewareHookInput, key: string): number | null {
+	const value = input.metadata?.[key];
+	return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+export function isMiddlewareHook(value: string): value is MiddlewareHook {
+	return (MIDDLEWARE_HOOKS as ReadonlyArray<string>).includes(value);
+}
+
+export function isMiddlewareEffectKind(value: string): value is MiddlewareEffectKind {
+	return (MIDDLEWARE_EFFECT_KINDS as ReadonlyArray<string>).includes(value);
+}
+
+export function isMiddlewareReminderSeverity(value: string): value is MiddlewareReminderSeverity {
+	return (MIDDLEWARE_REMINDER_SEVERITIES as ReadonlyArray<string>).includes(value);
+}
+
+export function isMiddlewareAnnotationSeverity(value: string): value is MiddlewareAnnotationSeverity {
+	return (MIDDLEWARE_ANNOTATION_SEVERITIES as ReadonlyArray<string>).includes(value);
+}