@dungle-scrubs/harness-cli-normalizer 0.6.0 → 0.6.2

package/src/cli/session.ts

@@ -2,7 +2,14 @@ import { randomUUID } from "node:crypto";
 import { createInterface } from "node:readline/promises";
 import { nodeRunnerDeps } from "../execution/node-deps.js";
 import { CLOSE_GRACE_MS, openSession } from "../execution/open-session.js";
+import {
+  composeAnswer,
+  isQuestionMode,
+  QUESTION_MODES,
+  type QuestionMode,
+} from "../interpretation/question.js";
 import { ArgvRefusalError } from "../interpretation/refusal.js";
+import type { BehaviorTier } from "../interpretation/resolve-options.js";
 import type { HarnessDescriptor } from "../knowledge/descriptor.js";
 import { defaultDescriptors } from "../knowledge/overrides.js";
 import { createRenderState, renderEvent } from "./render.js";
@@ -22,7 +29,7 @@ export const session = async (harnessName: string, rawArgs: string[]): Promise<v
       .map((d) => d.name);
     const err = new ArgvRefusalError({
       issue: "no-session-mode",
-      harness: harnessName as "claude",
+      harness: h.name,
       supported,
       detail: `session mode is available on ${supported.join(", ")}; ${harnessName} declares no persistent headless session`,
     });
@@ -37,7 +44,7 @@ export const session = async (harnessName: string, rawArgs: string[]): Promise<v
     return;
   }
 
-  const { parseCommonFlags } = await import("./args.js");
+  const { parseCommonFlags, resumeIdOf } = await import("./args.js");
   let parsed: ReturnType<typeof parseCommonFlags>;
   try {
     parsed = parseCommonFlags(rawArgs);
@@ -57,23 +64,34 @@ export const session = async (harnessName: string, rawArgs: string[]): Promise<v
   }
 
   const values = parsed.values as Record<string, unknown>;
-  // --resume and --session-id are aliases for one concept: resume an existing
-  // session. Passing both is refused, matching hcn run's parseRunExtra shape
-  // (src/cli/args.ts) rather than inventing a second parser.
-  if (values.resume !== undefined && values["session-id"] !== undefined) {
-    const { ArgvRefusalError: AliasError } = await import("../interpretation/refusal.js");
-    const err = new AliasError({
-      issue: "mutually-exclusive-options",
-      harness: h.name,
-      supported: ["--resume or --session-id, not both (--session-id is an alias for --resume)"],
-      detail: "both --resume and --session-id given",
-    });
-    const { refusalOf: aliasRefusalOf, refuse: aliasRefuse } = await import("./refuse.js");
-    aliasRefuse(aliasRefusalOf(err), jsonMode, "closed");
+  if (values.isolation !== undefined) {
+    const { refuse, refusalOf } = await import("./refuse.js");
+    refuse(
+      refusalOf(
+        new ArgvRefusalError({
+          harness: h.name,
+          message: "isolation is available only for a fresh hcn run",
+          issue: "invalid-option-value",
+          option: "isolation",
+          supported: ["hcn run --isolation tool-free"],
+        }),
+      ),
+      jsonMode,
+      "closed",
+    );
+    return;
+  }
+  // --resume and --session-id are aliases for one concept; the one check
+  // every command calls decides whether both were given.
+  let resumeId: string | undefined;
+  try {
+    resumeId = resumeIdOf(values);
+  } catch (err) {
+    if (!(err instanceof ArgvRefusalError)) throw err;
+    const { refusalOf, refuse } = await import("./refuse.js");
+    refuse(refusalOf(err), jsonMode, "closed");
     return;
   }
-  const resumeId =
-    (values.resume as string | undefined) ?? (values["session-id"] as string | undefined);
   // The two flags are aliases for "use this session". Whether that means
   // RESUME is decided by the store, not by which spelling was typed: an id
   // that exists is resumed (resumeFlag rendered), an id that does not exist
@@ -107,18 +125,18 @@ export const session = async (harnessName: string, rawArgs: string[]): Promise<v
   const provider = values.provider as string | undefined;
   const effort = values.effort as string | undefined;
 
-  // question mode precedence arg > project > user > default (ask)
+  // question mode: the arg is validated through the one predicate, then
+  // precedence resolves through the one owner (RFC-02 change 6).
   const rawArgMode = values.questions !== undefined ? String(values.questions) : undefined;
-  if (rawArgMode !== undefined && !["ask", "assume", "none"].includes(rawArgMode)) {
+  if (rawArgMode !== undefined && !isQuestionMode(rawArgMode)) {
     const { refuse, refusalOf } = await import("./refuse.js");
-    const { ArgvRefusalError } = await import("../interpretation/refusal.js");
     refuse(
       refusalOf(
         new ArgvRefusalError({
           issue: "invalid-option-value",
           harness: h.name,
           option: "questions",
-          supported: ["ask", "assume", "none"],
+          supported: [...QUESTION_MODES],
           detail: rawArgMode,
         }),
       ),
@@ -127,27 +145,19 @@ export const session = async (harnessName: string, rawArgs: string[]): Promise<v
     );
     return;
   }
-  let questionMode: import("../interpretation/question.js").QuestionMode;
-  let questionTier: "arg" | "project-config" | "user-config" | "default";
+  let questionMode: QuestionMode;
+  let questionTier: BehaviorTier;
   try {
     const { loadUserConfig, loadProjectConfig } = await import("./config.js");
-    const user = loadUserConfig()?.config as { questions?: string } | undefined;
-    const project = loadProjectConfig()?.config as { questions?: string } | undefined;
-    const userMode = user?.questions;
-    const projectMode = project?.questions;
-    if (rawArgMode !== undefined) {
-      questionMode = rawArgMode as import("../interpretation/question.js").QuestionMode;
-      questionTier = "arg";
-    } else if (projectMode !== undefined) {
-      questionMode = projectMode as import("../interpretation/question.js").QuestionMode;
-      questionTier = "project-config";
-    } else if (userMode !== undefined) {
-      questionMode = userMode as import("../interpretation/question.js").QuestionMode;
-      questionTier = "user-config";
-    } else {
-      questionMode = "ask";
-      questionTier = "default";
-    }
+    const { resolveBehavior } = await import("../interpretation/resolve-options.js");
+    const behavior = resolveBehavior(
+      {
+        questions: rawArgMode !== undefined && isQuestionMode(rawArgMode) ? rawArgMode : undefined,
+      },
+      { user: loadUserConfig()?.config, project: loadProjectConfig()?.config },
+    );
+    questionMode = behavior.questions.value;
+    questionTier = behavior.questions.tier;
   } catch (configErr) {
     process.stderr.write(`config error: ${(configErr as Error).message}\n`);
     if (jsonMode) {
@@ -382,10 +392,7 @@ export const session = async (harnessName: string, rawArgs: string[]): Promise<v
             answer = a;
           }
         }
-        handle.send({
-          id: `you-${++sendCount}`,
-          text: `The user answered the question: "${q.question}" with: ${answer}. Continue accordingly.`,
-        });
+        handle.send({ id: `you-${++sendCount}`, text: composeAnswer(q.question, answer) });
         // Drain the answer turn BEFORE prompting again - the pump's
         // backpressure stalls the harness until the turn iterable is
         // consumed (verified live: menu answered, you-prompt rendered, no

package/src/cli/skills-root.ts

@@ -31,10 +31,7 @@ export const listKnownSkills = (): string[] => {
   });
 };
 
-export const resolveSkillNames = (
-  names: readonly string[],
-  harness: HarnessName = "claude",
-): string[] => {
+export const resolveSkillNames = (names: readonly string[], harness: HarnessName): string[] => {
   const root = skillsRoot();
   const known = new Set(listKnownSkills());
   const unknown = names.filter((n) => !known.has(n));

package/src/execution/decode.ts

@@ -10,7 +10,7 @@ import { decodeIdentity } from "../interpretation/identity.js";
 import { detectLimitInLine } from "../interpretation/limits.js";
 import type { HarnessDescriptor, StreamingGranularity } from "../knowledge/descriptor.js";
 import type { HarnessEvent } from "./events.js";
-import { failureFromBudget } from "./failure.js";
+import { failureFromBudget, failureFromLimit } from "./failure.js";
 
 export interface DecodeState {
   lastSeenId: string | null;
@@ -99,47 +99,21 @@ export const decodeParsed = (
     }
   }
 
-  // Content (message/token/tool/error/budget) is per-harness; identity
-  // above is descriptor-driven. contentEventsOf dispatches by harness
-  // name. budget is not a HarnessEvent kind and must not leak out.
+  // Content (message/token/tool/error/budget/limit) is per-harness;
+  // identity above is descriptor-driven. contentEventsOf dispatches by
+  // harness name inside interpretation. budget and limit are not
+  // HarnessEvent kinds of their own here: both become failures.
   for (const content of contentEventsOf(h.name, raw)) {
     if (content.kind === "budget") {
       events.push({ kind: "failure", ...failureFromBudget(content.detail) });
+    } else if (content.kind === "limit") {
+      events.push({
+        kind: "failure",
+        ...failureFromLimit(content.code, content.detail, content.resetsAt),
+      });
     } else {
       events.push(content);
     }
   }
-
-  // claude's rate_limit_event: only non-"allowed" statuses are failures.
-  // overageStatus is deliberately not classified - it is a separate
-  // billing signal, not a rate limit.
-  if (h.name === "claude" && typeof (raw as Record<string, unknown>).type === "string") {
-    const rec = raw as Record<string, unknown>;
-    if (rec.type === "rate_limit_event") {
-      const info = rec.rate_limit_info as Record<string, unknown> | undefined;
-      const status = info?.status as string | undefined;
-      if (status !== undefined && status !== "allowed") {
-        const rawResets = info?.resetsAt;
-        let resetsAt: number | undefined;
-        if (typeof rawResets === "number" && Number.isFinite(rawResets) && rawResets > 0) {
-          // Arithmetic conversion: resetsAt is seconds, we need milliseconds. No wall clock read.
-          resetsAt = rawResets * 1000;
-          if (!Number.isFinite(resetsAt) || resetsAt <= 0) resetsAt = undefined;
-        }
-        // Push a failure event directly - this is a structured record, not a wall scan
-        const failure: import("./failure.js").FailureSummary = {
-          class: "rate-limit",
-          retryable: true,
-          message: `Rate limit hit (rate_limit_event status=${status}) - retry after backoff or route to another provider`,
-          code: "rate-limit" as const,
-          ...(resetsAt !== undefined ? { resetsAt } : {}),
-        };
-        events.push({
-          kind: "failure",
-          ...failure,
-        } as unknown as import("./events.js").HarnessEvent);
-      }
-    }
-  }
   return events;
 };

package/src/execution/events.ts

@@ -15,6 +15,7 @@
  * concatenate both.
  */
 import type { CapabilityResult } from "../interpretation/capabilities.js";
+import type { QuestionMode } from "../interpretation/question.js";
 import type { LimitCode } from "../knowledge/descriptor.js";
 import type { FailureSummary } from "./failure.js";
 
@@ -29,7 +30,9 @@ export type ExitCause =
    * SUCCESSFUL turn (process exit 0); the caller resumes with the answer. */
   | "awaiting-input";
 
-export type EscalationMode = "ask" | "assume" | "none";
+/** The question mode the turn ran under - the one vocabulary question.ts
+ * owns, recorded on done per RFC-01. */
+export type EscalationMode = QuestionMode;
 export type EscalationDetection = "block" | "malformed" | "none";
 export interface EscalationRecord {
   readonly mode: EscalationMode;

package/src/execution/failure.ts

@@ -103,7 +103,7 @@ const messageFor = (cls: FailureClass, detail?: string): string => {
 }; /** D11: the run outlived its caller-set wall-clock budget. */
 export const failureFromTimeout = (): FailureSummary => ({
   class: "timeout",
-  retryable: false,
+  retryable: retryableOf("timeout"),
   message: messageFor("timeout"),
 });
 
@@ -114,7 +114,7 @@ export const failureFromNative = (
   stderrTail: readonly string[],
 ): FailureSummary => ({
   class: "native",
-  retryable: false,
+  retryable: retryableOf("native"),
   message: messageFor(
     "native",
     stderrTail.slice(-3).join(" | ").slice(0, 512) || `exit ${nativeExitCode}`,
@@ -122,7 +122,13 @@ export const failureFromNative = (
   nativeExitCode: nativeExitCode ?? undefined,
 });
 
-export const failureFromLimit = (code: LimitCode): FailureSummary => {
+/** A limit, from a wall phrasing (detail defaults to the code) or from a
+ * structured record that names its status and, sometimes, a reset time. */
+export const failureFromLimit = (
+  code: LimitCode,
+  detail: string = code,
+  resetsAt?: number,
+): FailureSummary => {
   const cls: FailureClass =
     code === "rate-limit"
       ? "rate-limit"
@@ -132,14 +138,15 @@ export const failureFromLimit = (code: LimitCode): FailureSummary => {
   return {
     class: cls,
     retryable: retryableOf(cls),
-    message: messageFor(cls, code),
-    code: code as LimitCode,
+    message: messageFor(cls, detail),
+    code,
+    ...(resetsAt !== undefined ? { resetsAt } : {}),
   };
 };
 
 export const failureFromAuth = (kind: AuthFailureKind): FailureSummary => ({
   class: "auth",
-  retryable: true,
+  retryable: retryableOf("auth"),
   message: messageFor("auth", kind),
   authKind: kind,
 });
@@ -157,25 +164,25 @@ export const failureFromTerminalError = (h: HarnessDescriptor, message: string):
 
 export const failureFromTask = (detail?: string): FailureSummary => ({
   class: "task",
-  retryable: false,
+  retryable: retryableOf("task"),
   message: messageFor("task", detail),
 });
 
 export const failureFromBudget = (detail?: string): FailureSummary => ({
   class: "budget",
-  retryable: false,
+  retryable: retryableOf("budget"),
   message: messageFor("budget", detail),
 });
 
 export const failureFromTransport = (detail?: string): FailureSummary => ({
   class: "transport",
-  retryable: true,
+  retryable: retryableOf("transport"),
   message: messageFor("transport", detail),
 });
 
 export const failureFromUnavailable = (detail?: string): FailureSummary => ({
   class: "unavailable",
-  retryable: true,
+  retryable: retryableOf("unavailable"),
   message: messageFor("unavailable", detail),
 });
 
@@ -189,7 +196,7 @@ export const failureFromRejected = (opts: {
   detail?: string;
 }): FailureSummary => ({
   class: "rejected",
-  retryable: false,
+  retryable: retryableOf("rejected"),
   // D8: hint first, support list second - prose order matches the
   // structured fields so an agent scanning the message hits the
   // stay-on-harness suggestion before the switch temptation.