@iowarp/clio-coder 0.3.4 → 0.3.7

package/src/domains/memory/validate.ts

@@ -2,9 +2,13 @@ import { isAbsolute, resolve } from "node:path";
 import {
 	MEMORY_SCOPES,
 	MEMORY_VERSION,
+	type MemoryAgentIdentity,
+	type MemoryPromotionRedaction,
 	type MemoryRecord,
+	type MemoryRecordProvenance,
 	type MemoryRecordValidationResult,
 	type MemoryRepositoryIdentity,
+	type MemoryRuntimeIdentity,
 	type MemoryScope,
 	type MemoryStoreValidationResult,
 	type MemoryValidationIssue,
@@ -65,6 +69,9 @@ function readMemoryRecord(value: unknown, path: string, issues: MemoryValidation
 			"approved",
 			"rejectedAt",
 			"repository",
+			"runtime",
+			"agent",
+			"provenance",
 		],
 		issues,
 	);
@@ -93,6 +100,9 @@ function readMemoryRecord(value: unknown, path: string, issues: MemoryValidation
 	const approved = readBoolean(value, `${path}.approved`, issues);
 	const rejectedAt = readOptionalIsoString(value, `${path}.rejectedAt`, issues);
 	const repository = readOptionalMemoryRepositoryIdentity(value, `${path}.repository`, issues);
+	const runtime = readOptionalNamedIdentity(value, `${path}.runtime`, "runtime", issues);
+	const agent = readOptionalNamedIdentity(value, `${path}.agent`, "agent", issues);
+	const provenance = readOptionalMemoryProvenance(value, `${path}.provenance`, issues);
 	if (approved === true && rejectedAt !== undefined) {
 		issues.push({ path: `${path}.rejectedAt`, message: "approved records must not be rejected" });
 	}
@@ -102,6 +112,18 @@ function readMemoryRecord(value: unknown, path: string, issues: MemoryValidation
 	if (repository === undefined && scope === "repo") {
 		issues.push({ path: `${path}.repository`, message: "repo scope requires repository applicability" });
 	}
+	if (runtime !== undefined && scope !== null && scope !== "runtime") {
+		issues.push({ path: `${path}.runtime`, message: "runtime applicability requires runtime scope" });
+	}
+	if (runtime === undefined && scope === "runtime") {
+		issues.push({ path: `${path}.runtime`, message: "runtime scope requires runtime applicability" });
+	}
+	if (agent !== undefined && scope !== null && scope !== "agent") {
+		issues.push({ path: `${path}.agent`, message: "agent applicability requires agent scope" });
+	}
+	if (agent === undefined && scope === "agent") {
+		issues.push({ path: `${path}.agent`, message: "agent scope requires agent applicability" });
+	}
 	if (
 		id === null ||
 		scope === null ||
@@ -132,6 +154,9 @@ function readMemoryRecord(value: unknown, path: string, issues: MemoryValidation
 	if (regressions !== undefined) record.regressions = regressions;
 	if (rejectedAt !== undefined) record.rejectedAt = rejectedAt;
 	if (repository !== undefined) record.repository = repository;
+	if (runtime !== undefined) record.runtime = runtime;
+	if (agent !== undefined) record.agent = agent;
+	if (provenance !== undefined) record.provenance = provenance;
 	return record;
 }
 
@@ -160,10 +185,163 @@ function readOptionalMemoryRepositoryIdentity(
 	return { kind, key };
 }
 
+function readOptionalNamedIdentity<T extends "runtime" | "agent">(
+	record: Record<string, unknown>,
+	path: string,
+	kind: T,
+	issues: MemoryValidationIssue[],
+): (T extends "runtime" ? MemoryRuntimeIdentity : MemoryAgentIdentity) | undefined {
+	const field = fieldName(path);
+	if (!Object.hasOwn(record, field)) return undefined;
+	const value = record[field];
+	if (!isRecord(value)) {
+		issues.push({ path, message: "expected object" });
+		return undefined;
+	}
+	rejectUnexpectedFields(value, path, ["kind", "key"], issues);
+	const actualKind = readString(value, `${path}.kind`, issues);
+	if (actualKind !== null && actualKind !== kind) {
+		issues.push({ path: `${path}.kind`, message: `expected ${kind}` });
+	}
+	const key = readString(value, `${path}.key`, issues);
+	if (key !== null && !isValidNamedIdentityKey(key)) {
+		issues.push({ path: `${path}.key`, message: `expected valid ${kind} identity` });
+	}
+	if (actualKind !== kind || key === null || !isValidNamedIdentityKey(key)) return undefined;
+	return { kind, key } as T extends "runtime" ? MemoryRuntimeIdentity : MemoryAgentIdentity;
+}
+
+function readOptionalMemoryProvenance(
+	record: Record<string, unknown>,
+	path: string,
+	issues: MemoryValidationIssue[],
+): MemoryRecordProvenance | undefined {
+	const field = fieldName(path);
+	if (!Object.hasOwn(record, field)) return undefined;
+	const value = record[field];
+	if (!isRecord(value)) {
+		issues.push({ path, message: "expected object" });
+		return undefined;
+	}
+	rejectUnexpectedFields(
+		value,
+		path,
+		[
+			"sourceKind",
+			"evidenceId",
+			"sourceSessionId",
+			"sourceEntryId",
+			"sourceEntryKind",
+			"sourceEntryCreatedAt",
+			"sourceEntryLastTouchedAt",
+			"redaction",
+		],
+		issues,
+	);
+	const sourceKind = readString(value, `${path}.sourceKind`, issues);
+	if (sourceKind !== null && !["evidence", "task-bank-entry", "handoff-snapshot"].includes(sourceKind)) {
+		issues.push({ path: `${path}.sourceKind`, message: "expected evidence, task-bank-entry, or handoff-snapshot" });
+	}
+	const evidenceId = readOptionalSourceString(value, `${path}.evidenceId`, issues);
+	const sourceSessionId = readOptionalSourceString(value, `${path}.sourceSessionId`, issues);
+	const sourceEntryId = readOptionalSourceString(value, `${path}.sourceEntryId`, issues);
+	const sourceEntryKind = readOptionalSourceString(value, `${path}.sourceEntryKind`, issues);
+	if (sourceEntryKind !== undefined && sourceEntryKind !== "knowledge" && sourceEntryKind !== "procedural") {
+		issues.push({ path: `${path}.sourceEntryKind`, message: "expected knowledge or procedural" });
+	}
+	const sourceEntryCreatedAt = readOptionalIsoString(value, `${path}.sourceEntryCreatedAt`, issues);
+	const sourceEntryLastTouchedAt = readOptionalIsoString(value, `${path}.sourceEntryLastTouchedAt`, issues);
+	const redaction = readOptionalPromotionRedaction(value, `${path}.redaction`, issues);
+	if (sourceKind === "evidence") {
+		if (evidenceId === undefined)
+			issues.push({ path: `${path}.evidenceId`, message: "evidence source requires evidence id" });
+		if (sourceEntryId !== undefined || sourceEntryKind !== undefined) {
+			issues.push({ path, message: "evidence source must not carry task-memory entry fields" });
+		}
+	}
+	if (sourceKind === "task-bank-entry" || sourceKind === "handoff-snapshot") {
+		if (sourceSessionId === undefined) {
+			issues.push({ path: `${path}.sourceSessionId`, message: "promotion source requires session id" });
+		}
+		if (sourceEntryId === undefined) {
+			issues.push({ path: `${path}.sourceEntryId`, message: "promotion source requires entry id" });
+		}
+		if (sourceEntryKind !== "knowledge" && sourceEntryKind !== "procedural") {
+			issues.push({ path: `${path}.sourceEntryKind`, message: "promotion source requires entry kind" });
+		}
+		if (redaction === undefined) {
+			issues.push({ path: `${path}.redaction`, message: "promotion source requires redaction provenance" });
+		}
+	}
+	if (sourceKind === null || !["evidence", "task-bank-entry", "handoff-snapshot"].includes(sourceKind)) {
+		return undefined;
+	}
+	const provenance: MemoryRecordProvenance = { sourceKind: sourceKind as MemoryRecordProvenance["sourceKind"] };
+	if (evidenceId !== undefined) provenance.evidenceId = evidenceId;
+	if (sourceSessionId !== undefined) provenance.sourceSessionId = sourceSessionId;
+	if (sourceEntryId !== undefined) provenance.sourceEntryId = sourceEntryId;
+	if (sourceEntryKind === "knowledge" || sourceEntryKind === "procedural") {
+		provenance.sourceEntryKind = sourceEntryKind;
+	}
+	if (sourceEntryCreatedAt !== undefined) provenance.sourceEntryCreatedAt = sourceEntryCreatedAt;
+	if (sourceEntryLastTouchedAt !== undefined) provenance.sourceEntryLastTouchedAt = sourceEntryLastTouchedAt;
+	if (redaction !== undefined) provenance.redaction = redaction;
+	return provenance;
+}
+
+function readOptionalPromotionRedaction(
+	record: Record<string, unknown>,
+	path: string,
+	issues: MemoryValidationIssue[],
+): MemoryPromotionRedaction | undefined {
+	const field = fieldName(path);
+	if (!Object.hasOwn(record, field)) return undefined;
+	const value = record[field];
+	if (!isRecord(value)) {
+		issues.push({ path, message: "expected object" });
+		return undefined;
+	}
+	rejectUnexpectedFields(value, path, ["appliedBeforePersistence", "replacementCount", "sourceFields"], issues);
+	const appliedBeforePersistence = readBoolean(value, `${path}.appliedBeforePersistence`, issues);
+	if (appliedBeforePersistence !== null && appliedBeforePersistence !== true) {
+		issues.push({ path: `${path}.appliedBeforePersistence`, message: "expected true" });
+	}
+	const replacementCount = readNumber(value, `${path}.replacementCount`, issues);
+	if (replacementCount !== null && (!Number.isInteger(replacementCount) || replacementCount < 0)) {
+		issues.push({ path: `${path}.replacementCount`, message: "expected non-negative integer" });
+	}
+	const sourceFields = readStringArray(value, `${path}.sourceFields`, issues);
+	if (appliedBeforePersistence !== true || replacementCount === null || sourceFields === null) return undefined;
+	return { appliedBeforePersistence, replacementCount, sourceFields };
+}
+
+function readOptionalSourceString(
+	record: Record<string, unknown>,
+	path: string,
+	issues: MemoryValidationIssue[],
+): string | undefined {
+	const field = fieldName(path);
+	if (!Object.hasOwn(record, field)) return undefined;
+	const value = record[field];
+	if (typeof value !== "string" || !isValidSourceValue(value)) {
+		issues.push({ path, message: "expected valid non-empty source value" });
+		return undefined;
+	}
+	return value;
+}
+
 function isNormalizedAbsoluteRepositoryPath(value: string): boolean {
 	return !/[\0\r\n]/u.test(value) && isAbsolute(value) && resolve(value) === value;
 }
 
+function isValidNamedIdentityKey(value: string): boolean {
+	return value.length > 0 && value.length <= 256 && value.trim() === value && !/[\0\r\n\t ]/u.test(value);
+}
+
+function isValidSourceValue(value: string): boolean {
+	return value.length > 0 && value.length <= 1_024 && value.trim() === value && !/[\0\r\n]/u.test(value);
+}
+
 function rejectUnexpectedFields(
 	record: Record<string, unknown>,
 	path: string,

package/src/domains/middleware/index.ts

@@ -152,3 +152,18 @@ export type {
 	MiddlewareValidationIssue,
 } from "./validate.js";
 export { validateMiddlewareEffect, validateMiddlewareRule } from "./validate.js";
+export {
+	coalesceTurnDiff,
+	createWatchdogRegistration,
+	WATCHDOG_DIFF_MAX_BYTES,
+	WATCHDOG_PATHS_MAX,
+	WATCHDOG_REGISTRATION_ID,
+	WATCHDOG_TASK,
+	WATCHDOG_TRUNCATION_MARKER,
+	type WatchdogDeps,
+	type WatchdogRegistration,
+	type WatchdogSettingsView,
+	type WatchdogTrigger,
+	type WatchdogTriggerReason,
+	watchdogBriefing,
+} from "./watchdog.js";

package/src/domains/middleware/memory-intervention.ts

@@ -1,4 +1,9 @@
 import { createHash } from "node:crypto";
+import {
+	legacyToolResultDigest,
+	sanitizeToolResultDigest,
+	type ToolResultDigest,
+} from "../../tools/result-disposition.js";
 import { TASK_MEMORY_DEFAULT_PROCEDURAL_CAP, type TaskMemoryBank } from "../memory/task-bank.js";
 import {
 	runTaskMemoryPolicy,
@@ -40,7 +45,6 @@ export interface MemoryInterventionSettings {
 	timeoutMs: number;
 }
 
-const RESULT_DIGEST_MAX_CHARS = 240;
 const CALL_DESCRIPTION_MAX_CHARS = 180;
 const NO_EFFECTS: ReadonlyArray<MiddlewareEffect> = [];
 
@@ -48,7 +52,7 @@ type ToolOutcome = "ok" | "error";
 
 interface PendingToolStep {
 	toolName: string;
-	fingerprint: string;
+	operationFingerprint: string;
 	callDescription: string;
 }
 
@@ -145,7 +149,7 @@ export function createMemoryInterventionRegistration(deps: MemoryInterventionDep
 	let toolStep = 0;
 	let lastTurnEndStep = 0;
 	let reactivateAfterCompaction = false;
-	let lastInjectedFingerprint: string | null = null;
+	let lastInjectedOperationFingerprint: string | null = null;
 	let currentTask = "(current task unavailable)";
 	let toolsSinceMemoryStep = 0;
 	let consecutiveErrors = 0;
@@ -467,13 +471,13 @@ export function createMemoryInterventionRegistration(deps: MemoryInterventionDep
 	function observeBeforeTool(input: MiddlewareHookInput): void {
 		const prepared = prepareToolStep(input);
 		if (prepared === null) return;
-		setBounded(pending, pendingKey(input, prepared.fingerprint), prepared, settings().windowSteps);
+		setBounded(pending, pendingKey(input, prepared.operationFingerprint), prepared, settings().windowSteps);
 	}
 
 	function observeAfterTool(input: MiddlewareHookInput): ReadonlyArray<MiddlewareEffect> {
 		const fallback = prepareToolStep(input);
 		if (fallback === null) return NO_EFFECTS;
-		const key = pendingKey(input, fallback.fingerprint);
+		const key = pendingKey(input, fallback.operationFingerprint);
 		const prepared = pending.get(key) ?? fallback;
 		pending.delete(key);
 		const outcome = input.metadata?.resultKind === "error" ? "error" : "ok";
@@ -487,11 +491,13 @@ export function createMemoryInterventionRegistration(deps: MemoryInterventionDep
 		} else {
 			consecutiveErrors = 0;
 		}
+		const digest = resultDigest(input, outcome);
 		const step: TrajectoryStep = {
 			...prepared,
 			step: toolStep,
 			outcome,
-			resultDigest: resultDigest(input, outcome),
+			resultDigest: digest.text,
+			resultDigestProvenance: digest.provenance,
 		};
 		trajectory.push(step);
 		if (trajectory.length > live.windowSteps) trajectory.splice(0, trajectory.length - live.windowSteps);
@@ -507,20 +513,20 @@ export function createMemoryInterventionRegistration(deps: MemoryInterventionDep
 	 * itself, which the model reads on its very next round.
 	 */
 	function annotateRepeatedFailure(step: TrajectoryStep): ReadonlyArray<MiddlewareEffect> {
-		if (annotatedThisTurn.has(step.fingerprint)) return NO_EFFECTS;
+		if (annotatedThisTurn.has(step.operationFingerprint)) return NO_EFFECTS;
 		const occurrences = trajectory.filter(
-			(candidate) => candidate.outcome === "error" && candidate.fingerprint === step.fingerprint,
+			(candidate) => candidate.outcome === "error" && candidate.operationFingerprint === step.operationFingerprint,
 		).length;
-		const failure = failures.get(step.fingerprint);
+		const failure = failures.get(step.operationFingerprint);
 		if (occurrences < 2 || failure === undefined) return NO_EFFECTS;
 		const message = boundedReminder(
 			`Memory: [${failure.entryId}] you already tried ${failure.callDescription} at step ${failure.firstStep} and it failed with ${failure.errorDigest}. Change the approach rather than repeating it.`,
 			settings().maxTokens,
 		);
 		if (message.length === 0) return NO_EFFECTS;
-		annotatedThisTurn.add(step.fingerprint);
+		annotatedThisTurn.add(step.operationFingerprint);
 		// Claim the turn-end channel too, so one repeated failure is surfaced once.
-		lastInjectedFingerprint = step.fingerprint;
+		lastInjectedOperationFingerprint = step.operationFingerprint;
 		lastDecision = "injected";
 		rulesInjectedSincePromptedStep = true;
 		annotatedSinceTurnEnd = true;
@@ -530,7 +536,7 @@ export function createMemoryInterventionRegistration(deps: MemoryInterventionDep
 	}
 
 	function rememberFailure(step: TrajectoryStep): void {
-		const previous = failures.get(step.fingerprint);
+		const previous = failures.get(step.operationFingerprint);
 		const attempts = (previous?.attempts ?? 0) + 1;
 		const firstStep = previous?.firstStep ?? step.step;
 		const content = proceduralContent(step.callDescription, attempts, firstStep, step.resultDigest);
@@ -546,7 +552,7 @@ export function createMemoryInterventionRegistration(deps: MemoryInterventionDep
 		}
 		setBounded(
 			failures,
-			step.fingerprint,
+			step.operationFingerprint,
 			{
 				entryId,
 				attempts,
@@ -566,21 +572,21 @@ export function createMemoryInterventionRegistration(deps: MemoryInterventionDep
 					step === undefined ||
 					step.outcome !== "error" ||
 					step.step <= lastTurnEndStep ||
-					step.fingerprint === lastInjectedFingerprint
+					step.operationFingerprint === lastInjectedOperationFingerprint
 				) {
 					continue;
 				}
 				const occurrences = trajectory.filter(
-					(candidate) => candidate.outcome === "error" && candidate.fingerprint === step.fingerprint,
+					(candidate) => candidate.outcome === "error" && candidate.operationFingerprint === step.operationFingerprint,
 				).length;
-				const failure = failures.get(step.fingerprint);
+				const failure = failures.get(step.operationFingerprint);
 				if (occurrences < 2 || failure === undefined) continue;
 				const message = boundedReminder(
 					`Memory: [${failure.entryId}] you already tried ${failure.callDescription} at step ${failure.firstStep} and it failed with ${failure.errorDigest}.`,
 					settings().maxTokens,
 				);
 				if (message.length === 0) return NO_EFFECTS;
-				lastInjectedFingerprint = step.fingerprint;
+				lastInjectedOperationFingerprint = step.operationFingerprint;
 				lastInjectedMessage = message;
 				lastDecision = "injected";
 				rulesInjectedSincePromptedStep = true;
@@ -624,31 +630,35 @@ function prepareToolStep(input: MiddlewareHookInput): PendingToolStep | null {
 	const canonical = hashToolCall(toolName, input.toolArgs ?? {});
 	return {
 		toolName,
-		fingerprint: createHash("sha256").update(canonical).digest("hex").slice(0, 16),
+		operationFingerprint: createHash("sha256").update(canonical).digest("hex").slice(0, 16),
 		callDescription: shortText(canonical, CALL_DESCRIPTION_MAX_CHARS),
 	};
 }
 
-function pendingKey(input: MiddlewareHookInput, fingerprint: string): string {
-	return input.toolCallId ?? `anonymous:${fingerprint}`;
+function pendingKey(input: MiddlewareHookInput, operationFingerprint: string): string {
+	return input.toolCallId ?? `anonymous:${operationFingerprint}`;
 }
 
-function resultDigest(input: MiddlewareHookInput, outcome: ToolOutcome): string {
+function resultDigest(input: MiddlewareHookInput, outcome: ToolOutcome): ToolResultDigest {
+	if (input.toolResultDigest !== undefined) return sanitizeToolResultDigest(input.toolResultDigest);
 	if (outcome === "error") {
 		const metadataMessage = input.metadata?.errorMessage;
 		if (typeof metadataMessage === "string" && metadataMessage.trim().length > 0) {
-			return shortText(diagnosticLine(metadataMessage), RESULT_DIGEST_MAX_CHARS);
+			return legacyToolResultDigest(diagnosticLine(metadataMessage), { outcome });
 		}
 		for (const key of ["error", "message"] as const) {
 			const value = input.toolResultDetails?.[key];
 			if (typeof value === "string" && value.trim().length > 0) {
-				return shortText(diagnosticLine(value), RESULT_DIGEST_MAX_CHARS);
+				return legacyToolResultDigest(diagnosticLine(value), { outcome });
 			}
 		}
-		return "an unknown tool error";
+		return legacyToolResultDigest("", { outcome });
 	}
 	const resultFingerprint = input.metadata?.resultFingerprint;
-	return typeof resultFingerprint === "string" ? `ok result ${resultFingerprint.slice(0, 16)}` : "ok";
+	return legacyToolResultDigest(
+		typeof resultFingerprint === "string" ? `ok result ${resultFingerprint.slice(0, 16)}` : "ok",
+		{ outcome },
+	);
 }
 
 const DIAGNOSTIC_HINT =

package/src/domains/middleware/runtime.ts

@@ -328,6 +328,12 @@ function cloneHookInput(input: MiddlewareHookInput): MiddlewareHookInput {
 	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.toolResultDigest !== undefined) {
+		cloned.toolResultDigest = {
+			text: input.toolResultDigest.text,
+			provenance: { ...input.toolResultDigest.provenance },
+		};
+	}
 	if (input.text !== undefined) cloned.text = input.text.slice(0, MIDDLEWARE_HOOK_TEXT_MAX_CHARS);
 	return cloned;
 }

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

@@ -1,5 +1,6 @@
 import { SKILL_SUGGESTION_ANCHOR } from "../../core/skill-activation.js";
 import type { MiddlewareHookRegistration } from "./runtime.js";
+import { isSkillSuggestionWait, SKILL_SUGGESTION_WAIT_CONTINUATION_MESSAGE } from "./stalled-turn.js";
 import { type MiddlewareEffect, metadataNumber } from "./types.js";
 
 /**
@@ -32,12 +33,17 @@ export function skillsReminderMessage(installed: number, installable = 0): strin
 		installable > 0
 			? `${installed} installed, ${installable} installable from the marketplace`
 			: `${installed} installed`;
+	// Inline and non-blocking (issue #184): a 27B model read "and wait for the
+	// operator" as the whole job, spent a 40-second turn deliberating over the
+	// suggestion, and ended without one repository read. The suggestion is one
+	// line, the task continues in the same turn, and only the operator loads.
 	return (
 		`[Skills] ${counts}. 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, and a marketplace skill is offered for " +
-		"install when the operator runs it. If none match, do not mention skills and continue with the task."
+		"and then continue the task in the same turn without the skill. Only the operator loads a skill, and a " +
+		"marketplace skill is offered for install when the operator runs it. If none match, do not mention skills " +
+		"and continue with the task."
 	);
 }
 
@@ -135,9 +141,18 @@ export function createSkillsReminderRegistration(deps: SkillsReminderDeps): Midd
 
 	return {
 		id: SKILLS_REMINDER_REGISTRATION_ID,
-		description: "once per session, on the first substantive turn, teaches the skill-suggestion reply protocol",
-		hooks: ["turn_start"],
+		description:
+			"once per session, on the first substantive turn, teaches the skill-suggestion reply protocol; keeps a turn going that stopped on the suggestion",
+		hooks: ["turn_start", "turn_end"],
 		evaluate(input): ReadonlyArray<MiddlewareEffect> {
+			// The registration that teaches "suggest, then continue" owns the
+			// consequence when a model suggests and stops. The generic stalled-turn
+			// rule cannot see this case: the listing call counts as a tool call.
+			if (input.hook === "turn_end") {
+				return isSkillSuggestionWait(input)
+					? [{ kind: "request_continuation", message: SKILL_SUGGESTION_WAIT_CONTINUATION_MESSAGE }]
+					: NO_EFFECTS;
+			}
 			const sessionId = input.sessionId ?? null;
 			if (lastSeenSessionId === undefined) {
 				lastSeenSessionId = sessionId;

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

@@ -1,11 +1,16 @@
+import { SKILL_SUGGESTION_PREFIX } from "../../core/skill-activation.js";
+import { ToolNames } from "../../core/tool-names.js";
 import type { MiddlewareRuleDefinition } from "./runtime.js";
-import type { MiddlewareHookInput } from "./types.js";
+import { type MiddlewareHookInput, metadataNumber, metadataString } 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.";
 
+export const SKILL_SUGGESTION_WAIT_CONTINUATION_MESSAGE =
+	"You ended your turn on a skill suggestion without doing the task. The suggestion line has already made the offer and only the operator loads a skill, so nothing is needed from them before you proceed. Continue the task now without the skill.";
+
 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;
 
 // Bare stems only. Inflected forms are derived below so that "running",
@@ -133,6 +138,43 @@ export const STALLED_TURN_RULE_DEFINITION: MiddlewareRuleDefinition = {
 	predicate: shouldRequestStalledTurnContinuation,
 };
 
+// "run /skill X or say skip", "Suggested skill: /skill x", "want me to use
+// the skill?": the sentence hands the operator a decision the protocol does
+// not require of them.
+const SKILL_WAIT_PATTERN = /\/skill\b|\bskills?\b|\bskip\b/i;
+
+/**
+ * A turn that made the skill suggestion and then stopped, with only the
+ * listing call behind it (issue #184). The generic stalled-turn predicate
+ * cannot see this: `context(scope="skills")` is a tool call, so the turn
+ * looks busy, and "say skip and I'll explore the tree" reads as a
+ * conditional offer rather than an announcement. The suggestion is supposed
+ * to be one inline line before the work, so a reply that is the suggestion
+ * plus a wait has not done the task.
+ */
+export function isSkillSuggestionWait(input: MiddlewareHookInput): boolean {
+	if (input.hook !== "turn_end") return false;
+	if (!isNormalStopReason(input.metadata?.stopReason)) return false;
+	const text = input.text ?? "";
+	if (!text.includes(SKILL_SUGGESTION_PREFIX)) return false;
+	const toolNames = metadataString(input, "turnToolNames");
+	if (toolNames === null) {
+		if ((metadataNumber(input, "turnToolCalls") ?? 0) !== 0) return false;
+	} else if (
+		toolNames
+			.split(",")
+			.filter((name) => name.length > 0)
+			.some((name) => name !== ToolNames.Context)
+	) {
+		return false;
+	}
+	const lastLine = lastNonEmptyLine(text);
+	if (lastLine === null) return false;
+	const finalSentence = lastSentence(lastLine);
+	if (finalSentence.length === 0) return false;
+	return SKILL_WAIT_PATTERN.test(finalSentence) || isQuestion(finalSentence) || LET_ME_KNOW_PATTERN.test(finalSentence);
+}
+
 export function shouldRequestStalledTurnContinuation(input: MiddlewareHookInput): boolean {
 	if (input.hook !== "turn_end") return false;
 	if (input.metadata?.turnToolCalls !== 0) return false;

package/src/domains/middleware/types.ts

@@ -1,3 +1,5 @@
+import type { ToolResultDigest } from "../../tools/result-disposition.js";
+
 /**
  * The five lifecycle events of the unified middleware layer (w3 cutover).
  * Every event has a live producer: the registry fires before_tool/after_tool
@@ -86,6 +88,8 @@ export interface MiddlewareHookInput {
 	toolArgs?: Readonly<Record<string, unknown>>;
 	/** Structured result details, supplied by the registry on after_tool. Read-only by contract. */
 	toolResultDetails?: Readonly<Record<string, unknown>>;
+	/** Bounded deterministic diagnostic supplied by the result-disposition layer on after_tool. */
+	toolResultDigest?: Readonly<ToolResultDigest>;
 	/**
 	 * 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`
@@ -114,6 +118,12 @@ export function metadataNumber(input: MiddlewareHookInput, key: string): number
 	return typeof value === "number" && Number.isFinite(value) ? value : null;
 }
 
+/** The string under `key`, or null when the caller did not report one. */
+export function metadataString(input: MiddlewareHookInput, key: string): string | null {
+	const value = input.metadata?.[key];
+	return typeof value === "string" ? value : null;
+}
+
 export function isMiddlewareHook(value: string): value is MiddlewareHook {
 	return (MIDDLEWARE_HOOKS as ReadonlyArray<string>).includes(value);
 }