@dungle-scrubs/harness-cli-normalizer 0.1.2 → 0.3.0

package/src/interpretation/argv.ts

@@ -5,37 +5,62 @@
  * no caller re-derives them.
  */
 import type { HarnessDescriptor, StreamingGranularity } from "../knowledge/descriptor.js";
+import { ArgvRefusalError } from "./refusal.js";
 import { assertUsableSessionId } from "./session-id.js";
+import { renderTurnOptions } from "./turn-options.js";
 import { validateModel } from "./vocabulary.js";
 
-/** Raised when launch options would corrupt or subvert the spawned argv. */
-export class ArgvRefusalError extends Error {
-  constructor(
-    readonly issue: string,
-    message: string,
-  ) {
-    super(message);
-    this.name = "ArgvRefusalError";
-  }
-}
+export type { RefusalIssue } from "./refusal.js";
+export { ArgvRefusalError, buildRefusalMessage, REFUSAL_ISSUES } from "./refusal.js";
 
 /** One guard for every builder that places a positional prompt. Selector
  * hygiene (session ids) lives in session-id.ts; model selectors go through
  * validateModel - both refuse, never sanitize. */
 const assertCleanPrompt = (h: HarnessDescriptor, prompt: string): void => {
   if (prompt.startsWith("-")) {
-    throw new ArgvRefusalError(
-      "prompt-flag-injection",
-      `positional prompt may not start with '-'; it would be parsed as a flag by ${h.bin}`,
-    );
+    throw new ArgvRefusalError({
+      issue: "prompt-flag-injection",
+      harness: h.name,
+      supported: ["prompt must not start with '-'"],
+      detail: `it would be parsed as a flag by ${h.bin}`,
+    });
   }
 };
 
+/**
+ * Variant that allows a leading '-' when the caller explicitly opted in via
+ * --prompt / --prompt-file. The positional guard still applies for implicit
+ * positional prompts, but an explicit opt-in bypasses it so `hcn run --prompt "-bad"`
+ * succeeds while `hcn run "-bad"` refuses. The caller must set
+ * `__explicitPrompt: true` on the options object when the prompt came from an
+ * explicit flag.
+ */
+const assertCleanPromptMaybe = (h: HarnessDescriptor, prompt: string, explicit?: boolean): void => {
+  if (explicit) return;
+  assertCleanPrompt(h, prompt);
+};
+
+export interface DiscoveryOptions {
+  readonly tools?: boolean;
+  readonly instructionFiles?: boolean;
+  readonly extensions?: boolean;
+  readonly skills?: boolean;
+}
+
 export interface TurnOptions {
   readonly prompt: string;
   readonly tools?: readonly string[];
   readonly model?: string;
   readonly autonomy?: boolean;
+  readonly effort?: string;
+  readonly sandbox?: string;
+  readonly provider?: string;
+  readonly discovery?: DiscoveryOptions;
+  readonly write?: boolean;
+  readonly shell?: boolean;
+  readonly maxSteps?: number;
+  /** Internal: set by CLI when prompt came from --prompt/--prompt-file to bypass leading '-' guard */
+  readonly __explicitPrompt?: boolean;
 }
 
 export interface ResumeOptions extends TurnOptions {
@@ -48,25 +73,47 @@ export type LaunchOptions = TurnOptions;
  * validated selections, with the variadic tools flag LAST and fed exactly
  * one joined token so nothing after it can be swallowed as a tool name. */
 const turnTail = (h: HarnessDescriptor, opts: TurnOptions): string[] => {
-  assertCleanPrompt(h, opts.prompt);
+  assertCleanPromptMaybe(h, opts.prompt, opts.__explicitPrompt);
   const tail = [opts.prompt, ...h.launch.streamFlags];
   if (opts.model !== undefined) {
     const validated = validateModel(h, opts.model);
-    if (!validated.ok) throw new ArgvRefusalError("unknown-model", validated.reason);
+    if (!validated.ok) {
+      const supported = [...h.vocabulary.models, ...Object.keys(h.vocabulary.aliases)];
+      throw new ArgvRefusalError({
+        issue: "unknown-model",
+        harness: h.name,
+        supported: supported.length ? supported : ["no curated models"],
+        detail: opts.model,
+      });
+    }
     tail.push(h.vocabulary.modelFlag, validated.id);
   }
   if (opts.autonomy === true) {
     if (h.autonomy === null) {
-      throw new ArgvRefusalError("no-autonomy-mode", `${h.bin} has no unattended-run flag`);
+      throw new ArgvRefusalError({
+        issue: "no-autonomy-mode",
+        harness: h.name,
+        supported: ["claude --dangerously-skip-permissions", "codex --yolo", "muse --yolo"],
+      });
     }
     tail.push(h.autonomy.flag);
   }
-  if (opts.tools !== undefined && h.launch.toolsFlag !== null) {
+  if (opts.tools !== undefined) {
+    if (h.launch.toolsFlag === null) {
+      throw new ArgvRefusalError({
+        issue: "unsupported-option",
+        harness: h.name,
+        supported: ["--allowedTools is claude-only"],
+        detail: "tools",
+      });
+    }
     if (opts.tools.length === 0 || opts.tools.some((t) => t.trim() === "" || t.includes(","))) {
-      throw new ArgvRefusalError(
-        "invalid-tool-grant",
-        `tool grant for ${h.bin} contains an empty entry or a comma; a blank ${h.launch.toolsFlag} value grants nothing detectable, and a comma inside one name silently splits the grant`,
-      );
+      throw new ArgvRefusalError({
+        issue: "invalid-tool-grant",
+        harness: h.name,
+        supported: ["non-empty, comma-free tool names"],
+        detail: `tools=${JSON.stringify(opts.tools)}`,
+      });
     }
     tail.push(h.launch.toolsFlag, opts.tools.join(","));
   }
@@ -76,6 +123,7 @@ const turnTail = (h: HarnessDescriptor, opts: TurnOptions): string[] => {
 export const buildLaunchArgv = (h: HarnessDescriptor, opts: LaunchOptions): string[] => [
   h.bin,
   ...h.launch.baseFlags,
+  ...renderTurnOptions(h, opts, "launch"),
   ...turnTail(h, opts),
 ];
 
@@ -92,6 +140,7 @@ export const buildResumeArgv = (h: HarnessDescriptor, opts: ResumeOptions): stri
     h.resume.flag,
     opts.sessionId,
     ...h.resume.extraFlags,
+    ...renderTurnOptions(h, opts, "resume"),
     ...turnTail(h, opts),
   ];
 };
@@ -103,10 +152,11 @@ export interface SessionOptions {
 
 export const buildSessionArgv = (h: HarnessDescriptor, opts: SessionOptions): string[] => {
   if (!h.sessionMode) {
-    throw new ArgvRefusalError(
-      "no-session-mode",
-      `${h.bin} declares no persistent headless session mode`,
-    );
+    throw new ArgvRefusalError({
+      issue: "no-session-mode",
+      harness: h.name,
+      supported: ["session is claude-only"],
+    });
   }
   assertUsableSessionId(opts.sessionId);
   const argv = [
@@ -118,7 +168,15 @@ export const buildSessionArgv = (h: HarnessDescriptor, opts: SessionOptions): st
   ];
   if (opts.model !== undefined) {
     const validated = validateModel(h, opts.model);
-    if (!validated.ok) throw new ArgvRefusalError("unknown-model", validated.reason);
+    if (!validated.ok) {
+      const supported = [...h.vocabulary.models, ...Object.keys(h.vocabulary.aliases)];
+      throw new ArgvRefusalError({
+        issue: "unknown-model",
+        harness: h.name,
+        supported: supported.length ? supported : ["no curated models"],
+        detail: opts.model,
+      });
+    }
     argv.push(h.vocabulary.modelFlag, validated.id);
   }
   return argv;

package/src/interpretation/dimensions.ts

@@ -8,13 +8,7 @@ import type { HarnessDescriptor } from "../knowledge/descriptor.js";
 
 export const stdinPolicyOf = (h: HarnessDescriptor): "inherit" | "close-required" => h.stdin;
 
-export const providerFlagOf = (h: HarnessDescriptor): string | null =>
-  h.provider === null ? null : h.provider.flag;
-
 export const toolsFlagOf = (h: HarnessDescriptor): string | null => h.launch.toolsFlag;
 
-export const discoveryDisableFlagsOf = (h: HarnessDescriptor): readonly string[] =>
-  h.discoveryDisableFlags;
-
 export const autonomyFlagOf = (h: HarnessDescriptor): string | null =>
   h.autonomy === null ? null : h.autonomy.flag;

package/src/interpretation/limits.ts

@@ -9,21 +9,112 @@
  * Feed these wall-eligible output only - stderr and the non-JSON tail of a
  * dying turn - never assistant message content, where the model merely
  * TALKING about limits would match.
+ *
+ * Matchers are serializable objects {pattern, flags, code/kind}; compilation
+ * to RegExp happens here with bounded inputs (pattern length, count, flags)
+ * and a WeakMap cache. The input window (first 4096 chars of a line), not
+ * pattern analysis, is the backtracking bound - a malicious pattern could
+ * otherwise catastrophically backtrack on a long line.
  */
-import type { AuthFailureKind, HarnessDescriptor, LimitCode } from "../knowledge/descriptor.js";
+
+import type {
+  AuthFailureKind,
+  AuthMatcher,
+  HarnessDescriptor,
+  LimitCode,
+  LimitMatcher,
+} from "../knowledge/descriptor.js";
 
 /** Bottom-up batch scans stop after this many non-empty lines: the wall is
  * virtually always the last thing a dying turn printed, and an unbounded
  * scan over an accumulating session buffer is O(turns x output). */
 const BATCH_SCAN_MAX_LINES = 200;
 
+/** Max pattern length and max matchers per harness per kind - load-bearing
+ * bounds that prevent a crafted override file from DoS'ing the matcher
+ * compiler or the scanner. */
+const MAX_PATTERN_LENGTH = 200;
+const MAX_MATCHERS_PER_KIND = 64;
+const WINDOW = 4096;
+
+// WeakMap cache: same matcher array instance reuses identical RegExp objects
+const limitCache = new WeakMap<
+  ReadonlyArray<LimitMatcher>,
+  ReadonlyArray<readonly [RegExp, LimitCode]>
+>();
+const authCache = new WeakMap<
+  ReadonlyArray<AuthMatcher>,
+  ReadonlyArray<readonly [RegExp, AuthFailureKind]>
+>();
+
+const validateAndCompile = (pattern: string, flags: string | undefined): RegExp => {
+  const f = flags ?? "i";
+  if (pattern.length > MAX_PATTERN_LENGTH) {
+    throw new Error(`pattern over ${MAX_PATTERN_LENGTH} characters`);
+  }
+  if (f.includes("g") || f.includes("y")) {
+    throw new Error(`flags must not contain g or y (got ${JSON.stringify(f)})`);
+  }
+  for (const ch of f) {
+    if (!"imsu".includes(ch)) throw new Error(`flag ${JSON.stringify(ch)} outside imsu`);
+  }
+  try {
+    return new RegExp(pattern, f);
+  } catch (e) {
+    throw new Error(`uncompilable pattern ${JSON.stringify(pattern)}: ${(e as Error).message}`);
+  }
+};
+
+export const compileLimitMatchers = (
+  matchers: ReadonlyArray<LimitMatcher>,
+): ReadonlyArray<readonly [RegExp, LimitCode]> => {
+  const cached = limitCache.get(matchers);
+  if (cached !== undefined) return cached;
+  if (matchers.length > MAX_MATCHERS_PER_KIND) {
+    throw new Error(`more than ${MAX_MATCHERS_PER_KIND} matchers per harness per kind`);
+  }
+  const compiled = matchers.map((m) => [validateAndCompile(m.pattern, m.flags), m.code] as const);
+  limitCache.set(matchers, compiled);
+  return compiled;
+};
+
+export const compileAuthMatchers = (
+  matchers: ReadonlyArray<AuthMatcher>,
+): ReadonlyArray<readonly [RegExp, AuthFailureKind]> => {
+  const cached = authCache.get(matchers);
+  if (cached !== undefined) return cached;
+  if (matchers.length > MAX_MATCHERS_PER_KIND) {
+    throw new Error(`more than ${MAX_MATCHERS_PER_KIND} matchers per harness per kind`);
+  }
+  const compiled = matchers.map((m) => [validateAndCompile(m.pattern, m.flags), m.kind] as const);
+  authCache.set(matchers, compiled);
+  return compiled;
+};
+
+// Generic alias for tests that call compileMatchers directly
+export const compileMatchers = <T extends LimitMatcher | AuthMatcher>(
+  matchers: ReadonlyArray<T>,
+): ReadonlyArray<readonly [RegExp, unknown]> => {
+  // Dispatch based on first element's shape - limit has code, auth has kind
+  if (matchers.length === 0) return [];
+  const first = matchers[0] as unknown as Record<string, unknown>;
+  if ("code" in first)
+    return compileLimitMatchers(
+      matchers as unknown as ReadonlyArray<LimitMatcher>,
+    ) as unknown as ReadonlyArray<readonly [RegExp, unknown]>;
+  return compileAuthMatchers(
+    matchers as unknown as ReadonlyArray<AuthMatcher>,
+  ) as unknown as ReadonlyArray<readonly [RegExp, unknown]>;
+};
+
 const scanLine = <Code>(
   line: string,
   matchers: ReadonlyArray<readonly [RegExp, Code]>,
 ): Code | null => {
+  const windowed = line.slice(0, WINDOW);
   for (let i = 0; i < matchers.length; i++) {
     const matcher = matchers[i];
-    if (matcher?.[0].test(line)) return matcher[1];
+    if (matcher?.[0].test(windowed)) return matcher[1];
   }
   return null;
 };
@@ -48,16 +139,16 @@ const scanTail = <Code>(
 
 /** Per-line entry point for streaming readers: O(1) per line, no rescans. */
 export const detectLimitInLine = (h: HarnessDescriptor, line: string): LimitCode | null =>
-  scanLine(line.trim(), h.limitMatchers);
+  scanLine(line.trim(), compileLimitMatchers(h.limitMatchers));
 
 /** Batch convenience over a turn's tail, bounded and bottom-up. */
 export const detectLimit = (h: HarnessDescriptor, output: string): LimitCode | null =>
-  scanTail(output, h.limitMatchers);
+  scanTail(output, compileLimitMatchers(h.limitMatchers));
 
 export const detectAuthFailureInLine = (
   h: HarnessDescriptor,
   line: string,
-): AuthFailureKind | null => scanLine(line.trim(), h.authMatchers);
+): AuthFailureKind | null => scanLine(line.trim(), compileAuthMatchers(h.authMatchers));
 
 export const detectAuthFailure = (h: HarnessDescriptor, output: string): AuthFailureKind | null =>
-  scanTail(output, h.authMatchers);
+  scanTail(output, compileAuthMatchers(h.authMatchers));

package/src/interpretation/refusal.ts

@@ -0,0 +1,116 @@
+/**
+ * Structured argv refusals: closed issue vocabulary and the typed error
+ * that carries harness, option, facet, and supported alternatives. The
+ * helper builds the message from those fields so the two cannot drift - a
+ * consumer branching on `issue` never has to parse English.
+ */
+
+import type { DiscoveryFacet, HarnessName, TurnOptionKey } from "../knowledge/descriptor.js";
+import { deepFreeze } from "../knowledge/descriptor.js";
+
+export const REFUSAL_ISSUES = deepFreeze([
+  "unsupported-option",
+  "unsupported-option-facet",
+  "unsupported-on-resume",
+  "invalid-option-value",
+  "unknown-effort",
+  "unknown-model",
+  "invalid-env",
+  "invalid-tool-grant",
+  "prompt-flag-injection",
+  "no-autonomy-mode",
+  "no-session-mode",
+] as const);
+export type RefusalIssue = (typeof REFUSAL_ISSUES)[number];
+
+/** One helper builds the message from the structured fields so message and
+ * fields cannot drift. Every message names an alternative, not only a
+ * negation, so an agent can pivot without reading the descriptor. */
+export const buildRefusalMessage = (
+  issue: RefusalIssue,
+  harness: HarnessName,
+  option?: TurnOptionKey,
+  facet?: DiscoveryFacet,
+  supported: readonly string[] = [],
+  detail?: string,
+): string => {
+  const supportedStr =
+    supported.length > 0 ? `supported: ${supported.join(", ")}` : "supported: (none)";
+  const facetSuffix = facet ? ` facet ${JSON.stringify(facet)}` : "";
+  const optionPart = option
+    ? ` option ${JSON.stringify(option)}${facetSuffix}`
+    : facet
+      ? ` facet ${JSON.stringify(facet)}`
+      : "";
+  const detailSuffix = detail ? ` (${detail})` : "";
+  switch (issue) {
+    case "unsupported-option":
+      return `${harness} cannot express${optionPart}${detailSuffix}; ${supportedStr} - drop the option or route this work to a harness that supports it`;
+    case "unsupported-option-facet":
+      return `${harness} cannot express discovery${facetSuffix}${detailSuffix}; ${supportedStr} - drop the facet or route this work to a harness that supports it`;
+    case "unsupported-on-resume": {
+      const name = option
+        ? JSON.stringify(option) + (facet ? `:${facet}` : "")
+        : facet
+          ? JSON.stringify(facet)
+          : "option";
+      return `${name} cannot be expressed on resume for ${harness}${detailSuffix}; ${supportedStr} - re-launch instead of resuming or drop the option`;
+    }
+    case "invalid-option-value":
+      return `invalid value for${optionPart} on ${harness}${detailSuffix}; ${supportedStr} - use a supported value instead`;
+    case "unknown-effort":
+      return `unknown effort for ${harness}${detail ? ` ${JSON.stringify(detail)}` : ""}; ${supportedStr} - use one of the ladder values`;
+    case "unknown-model":
+      return `unknown ${harness} model${detail ? ` ${JSON.stringify(detail)}` : ""}; ${supportedStr} - use one of the supported models`;
+    case "invalid-env":
+      return `invalid env key or value for ${harness}${detailSuffix}; ${supportedStr} - keys must match ^[A-Za-z_][A-Za-z0-9_]*$ and contain no NUL`;
+    case "invalid-tool-grant":
+      return `tool grant for ${harness} contains an empty entry or a comma; a blank tool flag value grants nothing detectable, and a comma inside one name silently splits the grant; ${supportedStr} - provide comma-free, non-empty tool names as separate entries`;
+    case "prompt-flag-injection":
+      return `positional prompt may not start with '-'; it would be parsed as a flag by ${harness}${detailSuffix}; ${supportedStr} - remove leading '-' or prefix with a space`;
+    case "no-autonomy-mode":
+      return `${harness} has no unattended-run flag; ${supportedStr} - drop autonomy or route to a supporting harness (claude --dangerously-skip-permissions, codex/muse --yolo)`;
+    case "no-session-mode":
+      return `${harness} declares no persistent headless session mode; ${supportedStr} - use streamTurn instead of openSession`;
+    default: {
+      const exhaustive: never = issue;
+      return `${exhaustive as string} for ${harness}${optionPart}${detailSuffix}; ${supportedStr}`;
+    }
+  }
+};
+
+/** Raised when launch options would corrupt or subvert the spawned argv. */
+export class ArgvRefusalError extends Error {
+  readonly issue: RefusalIssue;
+  readonly harness: HarnessName;
+  readonly option?: TurnOptionKey;
+  readonly facet?: DiscoveryFacet;
+  readonly supported: readonly string[];
+  constructor(args: {
+    readonly issue: RefusalIssue;
+    readonly harness: HarnessName;
+    readonly option?: TurnOptionKey;
+    readonly facet?: DiscoveryFacet;
+    readonly supported?: readonly string[];
+    readonly detail?: string;
+    readonly message?: string;
+  }) {
+    const message =
+      args.message ??
+      buildRefusalMessage(
+        args.issue,
+        args.harness,
+        args.option,
+        args.facet,
+        args.supported ?? [],
+        args.detail,
+      );
+    super(message);
+    this.name = "ArgvRefusalError";
+    this.issue = args.issue;
+    this.harness = args.harness;
+    this.option = args.option;
+    this.facet = args.facet;
+    this.supported = args.supported ?? [];
+  }
+}