portable-agent-layer 0.108.0 → 0.110.0

package/src/hooks/lib/adaptation-candidates.ts

@@ -1,15 +1,24 @@
 /**
  * Rule candidates: drafts the small model wrote from repeated corrections, each
- * with the proof of its trigger. Only a proven candidate becomes a draft in the
- * rule store for the user to review; one the log is still too short to judge
- * waits and is proven again as the log grows.
+ * with the proof of its trigger. A proven candidate becomes a draft rule; one
+ * whose trigger failed becomes a draft that can only be kept as an opinion, since
+ * the mistake recurs even when no pattern catches it, but only once its kind has
+ * recurred enough to measure. One the log is still too short to judge waits and
+ * is proven again as the log grows.
  */
 
 import { randomUUID } from "node:crypto";
 import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { addDraft, type DraftInput, type TriggerProof } from "./adaptation-rules";
+import {
+  addDraft,
+  type DraftInput,
+  type OpinionGate,
+  readRules,
+  type TriggerProof,
+} from "./adaptation-rules";
 import type { RequestedTurn } from "./adaptation-turns";
+import { opinionGate } from "./opinion-gate";
 import { paths } from "./paths";
 import {
   type ProofVerdict,
@@ -22,12 +31,10 @@ export interface CandidateInput extends DraftInput {
   check: string;
 }
 
-export interface Candidate extends CandidateInput {
+export type Candidate = CandidateInput & {
   id: string;
   createdAt: string;
-  verdict: ProofVerdict;
-  proof: TriggerProof;
-}
+} & ({ verdict: ProofVerdict; proof: TriggerProof } | { verdict: "untriggered" });
 
 function candidatesPath(): string {
   return resolve(paths.adaptation(), "candidates.jsonl");
@@ -59,15 +66,35 @@ function writeCandidates(candidates: Candidate[]): void {
 }
 
 function prove(candidate: Candidate, turns: RequestedTurn[]): Candidate {
+  if (!candidate.trigger) return { ...candidate, verdict: "untriggered" };
   const proof = proveTrigger(candidate.trigger, turns);
   const verdict = candidate.widens ? widenedProofVerdict(proof) : proofVerdict(proof);
   return { ...candidate, proof, verdict };
 }
 
-function promoteIfPassed(candidate: Candidate): void {
-  if (candidate.verdict !== "passed") return;
+function canOnlyBeOpinion(candidate: Candidate): boolean {
+  const unproven = candidate.verdict === "failed" || candidate.verdict === "untriggered";
+  return unproven && !candidate.widens;
+}
+
+function gateFor(candidate: Candidate, turns: RequestedTurn[]): OpinionGate | undefined {
+  if (!candidate.kind || candidate.widens) return undefined;
+  return opinionGate(candidate.kind, readRules(), turns);
+}
+
+function draftOf(candidate: Candidate, turns: RequestedTurn[]): DraftInput | null {
   const { id: _id, createdAt: _createdAt, verdict: _verdict, ...draft } = candidate;
-  addDraft(draft);
+  const gate = gateFor(candidate, turns);
+  const gated = gate ? { ...draft, opinionGate: gate } : draft;
+  if (!canOnlyBeOpinion(candidate)) return gated;
+  if (!candidate.kind || (gate && "corrections" in gate)) return null;
+  return { ...gated, offer: "opinion-only" };
+}
+
+function promoteIfDecided(candidate: Candidate, turns: RequestedTurn[]): void {
+  if (candidate.verdict !== "passed" && !canOnlyBeOpinion(candidate)) return;
+  const draft = draftOf(candidate, turns);
+  if (draft) addDraft(draft);
 }
 
 export function recordCandidate(
@@ -82,7 +109,7 @@ export function recordCandidate(
   } as Candidate;
   const candidate = prove(fresh, turns);
   writeCandidates([...readCandidates(), candidate]);
-  promoteIfPassed(candidate);
+  promoteIfDecided(candidate, turns);
   return candidate;
 }
 
@@ -91,5 +118,6 @@ export function reproveWaiting(turns: RequestedTurn[]): void {
   if (!candidates.some((c) => c.verdict === "waiting")) return;
   const updated = candidates.map((c) => (c.verdict === "waiting" ? prove(c, turns) : c));
   writeCandidates(updated);
-  updated.filter((c, i) => candidates[i].verdict === "waiting").forEach(promoteIfPassed);
+  for (const candidate of updated.filter((_c, i) => candidates[i].verdict === "waiting"))
+    promoteIfDecided(candidate, turns);
 }

package/src/hooks/lib/adaptation-rules.ts

@@ -2,6 +2,8 @@
  * Adaptation rules: "when this happens, steer like this", learned from the
  * user's corrections. A rule starts as a draft and only steers once the user
  * approves it. A denied rule stays on record so the same rule is not drafted again.
+ * An opinion is an approved rule without a trigger: it steers every session, so
+ * the opinions together are capped, and a new one past the cap is refused.
  */
 
 import { randomUUID } from "node:crypto";
@@ -9,8 +11,11 @@ import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { paths } from "./paths";
 
-export type RuleStatus = "draft" | "approved" | "denied";
-type Decision = Exclude<RuleStatus, "draft">;
+type RuleStatus = "draft" | "approved" | "denied" | "retired";
+type Decision = "approved" | "denied" | "opinion";
+
+const OPINION_CAP = 8;
+const OPINION_CHARS = 1500;
 
 export interface RuleTrigger {
   /** Whether the pattern is matched against the user's prompt or the assistant's reply. */
@@ -28,21 +33,78 @@ export interface TriggerProof {
 
 export interface DraftInput {
   when: string;
-  trigger: RuleTrigger;
+  /** Absent when the situation shows in no text a pattern could match; it can only be an opinion. */
+  trigger?: RuleTrigger;
   steering: string;
+  /** The correction kind the rule prevents; its rate measures the rule. */
+  kind?: string;
   evidence: string[];
   /** How to tell from a reply whether the steering was followed. */
   check?: string;
   proof?: TriggerProof;
   /** The approved rule whose trigger this draft replaces with a wider one. */
   widens?: string;
+  /** Its trigger failed the proof, so it can only be kept as an opinion or denied. */
+  offer?: "opinion-only";
+  /** Why it cannot be kept as an opinion: too few corrections of its kind, or another targets it. */
+  opinionGate?: OpinionGate;
 }
 
+export type OpinionGate = { corrections: number } | { duplicates: string };
+
 export interface AdaptationRule extends DraftInput {
   id: string;
   status: RuleStatus;
+  /** "always" makes an approved rule an opinion, injected every session. */
+  delivery?: "always";
   createdAt: string;
   decidedAt?: string;
+  retiredAt?: string;
+}
+
+export function isOpinion(rule: AdaptationRule): boolean {
+  return rule.status === "approved" && rule.delivery === "always";
+}
+
+type Deliverable = Pick<AdaptationRule, "delivery" | "trigger"> & { status: string };
+
+export function isTriggerRule<R extends Deliverable>(
+  rule: R
+): rule is R & { trigger: RuleTrigger } {
+  return rule.status === "approved" && rule.delivery !== "always" && !!rule.trigger;
+}
+
+function opinionLine(rule: Pick<AdaptationRule, "when" | "steering">): string {
+  return `- ${rule.when}: ${rule.steering}`;
+}
+
+export function opinionsContext(): string {
+  const opinions = readRules().filter(isOpinion);
+  if (opinions.length === 0) return "";
+  return [
+    "## Opinions",
+    "The user approved these from past corrections. Follow them on every turn:",
+    ...opinions.map(opinionLine),
+  ].join("\n");
+}
+
+function sameKindOpinion(rules: AdaptationRule[], added: AdaptationRule): string | null {
+  const taken = added.kind && rules.find((r) => isOpinion(r) && r.kind === added.kind);
+  return taken
+    ? `Opinion ${taken.id} already targets ${added.kind}, and two would share one rate; retire it first`
+    : null;
+}
+
+function opinionRefusal(rules: AdaptationRule[], added: AdaptationRule): string | null {
+  const opinions = [...rules.filter(isOpinion), added];
+  const sameKind = sameKindOpinion(rules, added);
+  if (sameKind) return sameKind;
+  if (opinions.length > OPINION_CAP)
+    return `Opinions are capped at ${OPINION_CAP}; retire one first`;
+  const size = opinions.map(opinionLine).join("\n").length;
+  if (size > OPINION_CHARS)
+    return `Opinions are capped at ${OPINION_CHARS} characters, this one would make ${size}; retire one first`;
+  return null;
 }
 
 type DecideResult = { ok: true; rule: AdaptationRule } | { ok: false; reason: string };
@@ -101,18 +163,85 @@ function approveWidening(
   return { ok: true, rule: widened };
 }
 
+function decided(rule: AdaptationRule, decision: Decision): AdaptationRule {
+  const decidedAt = new Date().toISOString();
+  if (decision === "opinion")
+    return { ...rule, status: "approved", delivery: "always", decidedAt };
+  return { ...rule, status: decision, decidedAt };
+}
+
+function replaceRule(rules: AdaptationRule[], rule: AdaptationRule): DecideResult {
+  writeRules(rules.map((r) => (r.id === rule.id ? rule : r)));
+  return { ok: true, rule };
+}
+
+function gateReason(gate: OpinionGate): string {
+  return "corrections" in gate
+    ? `its kind has only ${gate.corrections} corrections`
+    : `${gate.duplicates} already targets its kind`;
+}
+
+function decisionRefusal(rule: AdaptationRule, decision: Decision): string | null {
+  if (decision === "opinion" && rule.widens)
+    return `Rule ${rule.id} widens a trigger; it cannot be an opinion`;
+  if (decision === "opinion" && !rule.kind)
+    return `Rule ${rule.id} has no correction kind, so its effect could not be measured`;
+  if (decision === "opinion" && rule.opinionGate)
+    return `Rule ${rule.id} cannot be an opinion: ${gateReason(rule.opinionGate)}`;
+  if (decision === "approved" && !rule.trigger)
+    return `Rule ${rule.id} has no trigger; keep it as an opinion or deny it`;
+  if (decision === "approved" && rule.offer === "opinion-only")
+    return `Rule ${rule.id}'s trigger did not prove; keep it as an opinion or deny it`;
+  return null;
+}
+
 export function decideRule(id: string, decision: Decision): DecideResult {
   const rules = readRules();
   const rule = rules.find((r) => r.id === id);
   if (!rule) return { ok: false, reason: `No rule with id ${id}` };
   if (rule.status !== "draft")
     return { ok: false, reason: `Rule ${id} was already ${rule.status}` };
+  const refused = decisionRefusal(rule, decision);
+  if (refused) return { ok: false, reason: refused };
   if (rule.widens && decision === "approved") return approveWidening(rules, rule);
-  const decided: AdaptationRule = {
-    ...rule,
-    status: decision,
-    decidedAt: new Date().toISOString(),
+  const result = decided(rule, decision);
+  const refusal = isOpinion(result) ? opinionRefusal(rules, result) : null;
+  return refusal ? { ok: false, reason: refusal } : replaceRule(rules, result);
+}
+
+export interface OpinionInput {
+  when: string;
+  steering: string;
+  kind: string;
+  evidence: string[];
+}
+
+export function addOpinion(input: OpinionInput): DecideResult {
+  const now = new Date().toISOString();
+  const opinion: AdaptationRule = {
+    ...input,
+    id: randomUUID().slice(0, 8),
+    status: "approved",
+    delivery: "always",
+    createdAt: now,
+    decidedAt: now,
   };
-  writeRules(rules.map((r) => (r.id === id ? decided : r)));
-  return { ok: true, rule: decided };
+  const rules = readRules();
+  const refusal = opinionRefusal(rules, opinion);
+  if (refusal) return { ok: false, reason: refusal };
+  writeRules([...rules, opinion]);
+  return { ok: true, rule: opinion };
+}
+
+export function retireRule(id: string): DecideResult {
+  const rules = readRules();
+  const rule = rules.find((r) => r.id === id);
+  if (!rule) return { ok: false, reason: `No rule with id ${id}` };
+  if (rule.status !== "approved")
+    return { ok: false, reason: `Rule ${id} is ${rule.status}, not approved` };
+  return replaceRule(rules, {
+    ...rule,
+    status: "retired",
+    retiredAt: new Date().toISOString(),
+  });
 }

package/src/hooks/lib/adaptation-steering.ts

@@ -5,7 +5,12 @@
  */
 
 import { appendFileSync } from "node:fs";
-import { type AdaptationRule, type RuleTrigger, readRules } from "./adaptation-rules";
+import {
+  type AdaptationRule,
+  isTriggerRule,
+  type RuleTrigger,
+  readRules,
+} from "./adaptation-rules";
 import { alreadySentBack } from "./claim-log";
 import { hookFinalReply, hookSessionId } from "./hook-turn";
 import { replyEnd } from "./interaction-samples";
@@ -20,7 +25,7 @@ const REMINDER_HEADER =
 type Side = RuleTrigger["side"];
 
 function triggers(rule: AdaptationRule, side: Side, text: string): boolean {
-  if (rule.status !== "approved" || rule.trigger.side !== side) return false;
+  if (!isTriggerRule(rule) || rule.trigger.side !== side) return false;
   try {
     return new RegExp(rule.trigger.pattern, "i").test(text);
   } catch {

package/src/hooks/lib/adaptation-turns.ts

@@ -6,7 +6,15 @@
  * other's lines; a month is deleted whole once it ends before the window.
  */
 
-import { appendFileSync, existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import {
+  appendFileSync,
+  existsSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { resolve } from "node:path";
 import { paths } from "./paths";
 
@@ -24,6 +32,15 @@ export interface TurnInput {
   issue: string;
   /** Set on a correction: whether the second label agreed. */
   confirmed?: boolean;
+  /** Set on a confirmed correction: its kind, under the kind set's version. */
+  correctionKind?: StoredCorrectionKind;
+}
+
+interface StoredCorrectionKind {
+  kind: string;
+  suggested: string;
+  description: string;
+  version: number;
 }
 
 export interface Turn extends TurnInput {
@@ -99,6 +116,31 @@ function parseLine(line: string): Turn | null {
   }
 }
 
+export function turnKey(turn: Turn): string {
+  return `${turn.session} ${turn.ts}`;
+}
+
+function replacedLine(line: string, replacements: Map<string, Turn>): string {
+  const turn = parseLine(line);
+  const replacement = turn && replacements.get(turnKey(turn));
+  return replacement ? JSON.stringify(replacement) : line;
+}
+
+/**
+ * Rewrites the given turns in place. Each month file is read and replaced in one
+ * synchronous step, leaving only microseconds in which another session's append
+ * could be lost; a backfill runs once, so that window is accepted.
+ */
+export function replaceTurns(replacements: Map<string, Turn>): void {
+  for (const file of monthFiles()) {
+    const path = resolve(paths.adaptation(), file);
+    const lines = readFileSync(path, "utf-8").split("\n");
+    const rewritten = lines.map((line) => replacedLine(line, replacements));
+    writeFileSync(`${path}.tmp`, rewritten.join("\n"));
+    renameSync(`${path}.tmp`, path);
+  }
+}
+
 export function readTurns(days: number = WINDOW_DAYS, now: Date = new Date()): Turn[] {
   const cutoff = now.getTime() - days * DAY_MS;
   return monthFiles()

package/src/hooks/lib/context.ts

@@ -5,11 +5,11 @@
 
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { opinionsContext } from "./adaptation-rules";
 import type { AgentName } from "./agent-registry";
 import { resolveAnchor } from "./anchor";
 import { dueNudgeSections } from "./daily-nudge";
 import { loadHandoffContext } from "./handoff-context";
-import { loadOpinionContext } from "./opinions";
 import { paths, toPath } from "./paths";
 import { loadActiveProjectsContext } from "./projects";
 import { loadRecentNotes } from "./relationship";
@@ -215,7 +215,7 @@ export function buildSystemReminder(
   const failures =
     settings.isEnabled("failurePatterns") && !skipSemiStatic ? loadFailurePatterns() : "";
   const opinions =
-    !skipSemiStatic && settings.isEnabled("opinions") ? loadOpinionContext() : "";
+    !skipSemiStatic && settings.isEnabled("opinions") ? opinionsContext() : "";
   const selfModel =
     !skipSemiStatic && settings.isEnabled("selfModel") ? loadSelfModel() : "";
   const steering = skipSemiStatic ? "" : loadSteeringRules();

package/src/hooks/lib/correction-backfill.ts

@@ -0,0 +1,56 @@
+/**
+ * Labels the confirmed corrections that carry no kind of the current version, so
+ * the rate of each kind has one labelling across its history. A relabel runs over
+ * every confirmed correction again.
+ */
+
+import { readTurns, replaceTurns, type Turn, turnKey } from "./adaptation-turns";
+import {
+  type CorrectionKind,
+  correctionKindRequest,
+  hasCurrentKind,
+  parseCorrectionKind,
+  withCorrectionKind,
+} from "./correction-kind";
+import { inference } from "./inference";
+
+export type KindLabeller = (turn: Turn) => Promise<CorrectionKind | null>;
+
+export interface BackfillResult {
+  labelled: number;
+  failed: number;
+}
+
+export interface BackfillOptions {
+  label?: KindLabeller;
+  relabel?: boolean;
+  onLabelled?: (turn: Turn, kind: CorrectionKind | null) => void;
+}
+
+export function correctionsToLabel(turns: Turn[], relabel = false): Turn[] {
+  return turns.filter(
+    (turn) => turn.confirmed === true && (relabel || !hasCurrentKind(turn))
+  );
+}
+
+export async function labelWithInference(turn: Turn): Promise<CorrectionKind | null> {
+  const request = correctionKindRequest(turn.replyEnd, turn.message, turn.issue);
+  const result = await inference(request);
+  return result.success ? parseCorrectionKind(result.output) : null;
+}
+
+export async function backfillCorrectionKinds(
+  options: BackfillOptions = {}
+): Promise<BackfillResult> {
+  const label = options.label ?? labelWithInference;
+  const replacements = new Map<string, Turn>();
+  let failed = 0;
+  for (const turn of correctionsToLabel(readTurns(), options.relabel)) {
+    const kind = await label(turn);
+    options.onLabelled?.(turn, kind);
+    if (!kind) failed++;
+    else replacements.set(turnKey(turn), { ...turn, ...withCorrectionKind(turn, kind) });
+  }
+  if (replacements.size > 0) replaceTurns(replacements);
+  return { labelled: replacements.size, failed };
+}

package/src/hooks/lib/correction-kind.ts

@@ -0,0 +1,165 @@
+/**
+ * The kind of mistake a confirmed correction points at. Rates of each kind
+ * before and after an opinion is approved measure whether the opinion works, so
+ * the set is closed; a correction that fits none lands in `other` with the
+ * model's own name for it, which a later check can promote to a kind.
+ */
+
+import type { TurnInput } from "./adaptation-turns";
+
+/** Bump on every change to the kinds or the prompt: rates compare only labels of one version. */
+export const CORRECTION_KINDS_VERSION = 2;
+
+export function hasCurrentKind<T extends TurnInput>(
+  turn: T
+): turn is T & Required<Pick<TurnInput, "correctionKind">> {
+  return turn.correctionKind?.version === CORRECTION_KINDS_VERSION;
+}
+
+const NAMED_KINDS = {
+  "missed-the-question":
+    "the reply did not answer what the user asked, or buried the answer",
+  "unverified-claim":
+    "the reply stated a fact or the state of something (tests pass, CI is green, a tool is missing, a fix is merged) that was wrong or never checked",
+  "off-instruction":
+    "the reply went against an instruction the user had given in an earlier message: it reordered their steps, worked on a different target than the one they named, changed the scope, or put the work somewhere else, such as a separate PR",
+  "revisited-decision":
+    "the reply proposed or kept something the user had already ruled out or decided against earlier",
+  "stopped-short":
+    "the reply deferred, paused or handed back work the user wanted done now, or waited for something (a merge, a review, an answer) instead of starting",
+  "wrong-format":
+    "the reply ignored the shape or length the user asked for, such as a table, a list or one line, or padded the answer",
+  "no-verdict":
+    "the user wanted a judgement and the reply gave none: it agreed without reasoning, listed options without picking one, or criticised without an alternative",
+  "dismissed-user-view":
+    "the reply argued past or brushed aside the user's own view or hypothesis",
+  "undefined-reference":
+    "the reply used a term, name, number or id the user did not know or had not been told; the user says they don't know it, or asks what it is or to list it",
+  "skipped-existing":
+    "the reply designed or built something without checking what already exists: code, a mechanism, a tool, a convention or prior art",
+  "status-quo-bias":
+    "the reply treated the current setup as a fixed constraint instead of considering a better design",
+} as const;
+
+type NamedKind = keyof typeof NAMED_KINDS;
+export type CorrectionKindName = NamedKind | "other";
+
+export const CORRECTION_KINDS = [
+  ...(Object.keys(NAMED_KINDS) as NamedKind[]),
+  "other",
+] as const satisfies readonly CorrectionKindName[];
+
+export interface CorrectionKind {
+  kind: CorrectionKindName;
+  suggested: string;
+  description: string;
+}
+
+const KIND_LINES = Object.entries(NAMED_KINDS)
+  .map(([kind, meaning]) => `- ${kind}: ${meaning}.`)
+  .join("\n");
+
+export const CORRECTION_KIND_SYSTEM = `The user corrected an AI assistant's reply. Name the kind of mistake the reply made.
+
+Pick the one kind that best explains why the user had to correct the reply:
+${KIND_LINES}
+- other: none of the kinds above fits.
+
+Judge the mistake, not the topic: a wrong claim about CI is unverified-claim, and a question about CI the reply never answered is missed-the-question.
+
+The user's correction is often a question itself. That alone does not make it missed-the-question: missed-the-question means the reply failed to answer something the user had asked before the reply. When the correction asks a new question, find the mistake that made the user ask it.
+
+The first reader's words are a hint, not the answer. It writes "did not answer" or "did not address the question" for many kinds of mistake, so do not pick missed-the-question because of that wording; judge the reply and the message yourself.
+
+missed-the-question is the most general kind, so pick it last: only when no more specific kind below explains the mistake.
+
+When kinds overlap, prefer the most specific one:
+- the user does not know or understand something the reply referred to ("what is X?", "I don't get", "list them"): undefined-reference, even when they ask about it;
+- the user asked whether something is worth it, right, or should be done, and the reply gave no clear yes or no: no-verdict;
+- the user asked why, and the reply argued for something else instead of giving the reason: missed-the-question, not dismissed-user-view, even when the issue says the reply contradicted the user. dismissed-user-view needs a view or idea the user had put forward that the reply rejected;
+- the user says they meant a different thing than the reply worked on: off-instruction;
+- a correction nearly always tells the assistant what to do instead. That alone is never off-instruction, which needs an instruction from an earlier message that the reply broke;- the user reminds the reply of something agreed or ruled out earlier ("didn't we say", "we discussed"): revisited-decision;
+- the reply put off work the user wanted now, or said it would start only after something else happened (a merge, a review, an answer): stopped-short, even when it also changed the order.
+
+Pick a kind only when its description fits the mistake itself. When a kind fits only loosely, answer other.
+
+For other, set suggested to a short lowercase kebab-case name for the mistake, and description to one sentence saying what the reply did wrong. For any other kind, set both to an empty string.`;
+
+const CORRECTION_KIND_SCHEMA = {
+  type: "object",
+  properties: {
+    kind: { enum: [...CORRECTION_KINDS] },
+    suggested: { type: "string" },
+    description: { type: "string" },
+  },
+  required: ["kind", "suggested", "description"],
+  additionalProperties: false,
+} as const;
+
+export function correctionKindSchema() {
+  return CORRECTION_KIND_SCHEMA;
+}
+
+const MESSAGE_MAX = 800;
+
+export function correctionKindUser(replyEnd: string, message: string, issue: string) {
+  return `The end of the assistant's reply:\n<reply_end>\n${replyEnd}\n</reply_end>\n\nThe user's correction:\n<message>\n${message.slice(0, MESSAGE_MAX)}\n</message>\n\nWhat the reply got wrong, in a first reader's words:\n<issue>\n${issue}\n</issue>`;
+}
+
+export function correctionKindRequest(
+  replyEnd: string,
+  message: string,
+  issue: string,
+  sessionId?: string
+) {
+  return {
+    system: CORRECTION_KIND_SYSTEM,
+    user: correctionKindUser(replyEnd, message, issue),
+    maxTokens: 200,
+    timeout: 90_000,
+    jsonSchema: CORRECTION_KIND_SCHEMA,
+    caller: "correction-kind",
+    sessionId,
+  };
+}
+
+function text(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function isCorrectionKind(value: unknown): value is CorrectionKindName {
+  return CORRECTION_KINDS.includes(value as CorrectionKindName);
+}
+
+function unlistedKind(kind: unknown, description: string): CorrectionKind | null {
+  const suggested = text(kind);
+  return suggested ? { kind: "other", suggested, description } : null;
+}
+
+export function parseCorrectionKind(
+  output: string | null | undefined
+): CorrectionKind | null {
+  if (!output) return null;
+  try {
+    const parsed = JSON.parse(output) as Record<string, unknown>;
+    const description = text(parsed.description);
+    if (!isCorrectionKind(parsed.kind)) return unlistedKind(parsed.kind, description);
+    if (parsed.kind !== "other")
+      return { kind: parsed.kind, suggested: "", description: "" };
+    return { kind: "other", suggested: text(parsed.suggested), description };
+  } catch {
+    return null;
+  }
+}
+
+export function needsCorrectionKind(turn: TurnInput | null): turn is TurnInput {
+  return turn?.confirmed === true;
+}
+
+export function withCorrectionKind(
+  turn: TurnInput,
+  kind: CorrectionKind | null
+): TurnInput {
+  if (!kind) return turn;
+  return { ...turn, correctionKind: { ...kind, version: CORRECTION_KINDS_VERSION } };
+}