@staix/agent-hub 0.12.7 → 0.12.9

package/src/models/route/relay-selector.ts

@@ -0,0 +1,102 @@
+import type { ModelBackend, ModelRelayOptions, RelayRequest } from "../relay.ts";
+import { normalizeConversation } from "./normalize.ts";
+import { extractToolSignals } from "./signals.ts";
+import { selectStage, type StageState } from "./stage.ts";
+import { SessionState } from "./state.ts";
+
+type RelaySelectorOptions = Pick<ModelRelayOptions, "mlx" | "selectBackend" | "routeSessionKey" | "onRoute" | "allowedDGXmodels">;
+type RouteSource = "override" | "dimensions" | "hold" | "classifier" | "default";
+type RelayRouteEvent = { route: "hub/auto"; tier: string; source: RouteSource; score: number; ms: number };
+type EstimateInputTokens = (messages: RelayRequest["messages"], tools?: unknown[]) => number;
+
+/** Stage selection for the relay's virtual `hub/auto` model. */
+export class AutoRouteSelector {
+  private readonly states = new SessionState<StageState>(512, 60 * 60_000);
+
+  constructor(
+    private readonly options: RelaySelectorOptions,
+    private readonly defaultBackend: ModelBackend,
+    private readonly mlxAlias: string,
+    private readonly estimateInputTokens: EstimateInputTokens,
+  ) {}
+
+  async select(body: RelayRequest): Promise<ModelBackend> {
+    const started = performance.now();
+    let sessionKey: string | undefined;
+    try {
+      const key = this.options.routeSessionKey?.(body);
+      if (typeof key === "string" && key.length > 0 && key.length <= 512) sessionKey = key;
+    } catch { /* host identity lookup is fail-open */ }
+    const priorState = sessionKey ? this.states.get(sessionKey) ?? { capableHoldTurnsRemaining: 0 } : { capableHoldTurnsRemaining: 0 };
+
+    let backend = this.defaultBackend;
+    let tier = this.aliasOf(backend);
+    let source: RouteSource = "default";
+    let score = 0;
+    try {
+      const signals = extractToolSignals(normalizeConversation(body));
+      const decision = selectStage(signals, { mode: "efficient_first", confidenceThreshold: 0.5, capableHoldTurns: 2 }, priorState);
+      if (sessionKey) this.states.set(sessionKey, decision.state);
+      score = decision.score;
+      source = this.sourceOf(decision.source);
+      const selectedTier = decision.tier ?? decision.defaultTier;
+      const stagedBackend = this.stageBackend(selectedTier, body);
+      if (stagedBackend) {
+        backend = stagedBackend;
+        tier = this.aliasOf(stagedBackend);
+      } else {
+        source = "default";
+      }
+    } catch {
+      source = "default";
+    }
+
+    if (this.options.selectBackend) {
+      try {
+        const override = await this.options.selectBackend(body);
+        if (this.isAllowed(override)) {
+          backend = override;
+          tier = this.aliasOf(override);
+          source = "override";
+        }
+      } catch { /* deterministic stage choice is the fail-open route */ }
+    }
+
+    this.emit({ route: "hub/auto", tier, source, score, ms: Math.max(0, performance.now() - started) });
+    return backend;
+  }
+
+  private stageBackend(tier: "capable" | "efficient", body: RelayRequest): ModelBackend | undefined {
+    if (tier === "capable") return "dgx/coding" in this.options.allowedDGXmodels ? { kind: "dgx", alias: "dgx/coding" } : undefined;
+    if (this.options.mlx && this.mlxFitsBudget(body)) return { kind: "mlx", alias: this.mlxAlias };
+    return "dgx/fast" in this.options.allowedDGXmodels ? { kind: "dgx", alias: "dgx/fast" } : undefined;
+  }
+
+  private mlxFitsBudget(body: RelayRequest): boolean {
+    const context = Math.min(8192, this.options.mlx?.contextWindow ?? 8192);
+    const maxOutput = this.options.mlx?.maxTokens ?? 2048;
+    const output = body.max_tokens ?? maxOutput;
+    const input = this.estimateInputTokens(body.messages, body.tools);
+    const inputLimit = this.options.mlx?.maxInputTokens ?? (this.options.mlx?.provider === "ollama" ? 6000 : 16_000);
+    return Number.isInteger(output) && output > 0 && output <= maxOutput && input <= inputLimit && input + output <= context;
+  }
+
+  private isAllowed(backend: ModelBackend): boolean {
+    return backend.kind === "mlx" ? !!this.options.mlx : backend.kind === "dgx" && backend.alias in this.options.allowedDGXmodels;
+  }
+
+  private aliasOf(backend: ModelBackend): string {
+    return backend.kind === "mlx" ? backend.alias ?? this.mlxAlias : backend.alias;
+  }
+
+  private sourceOf(source: string): RouteSource {
+    if (source === "capable_hold") return "hold";
+    if (source === "override" || source === "dimensions") return source;
+    if (source === "llm-classifier") return "classifier";
+    return "default";
+  }
+
+  private emit(event: RelayRouteEvent): void {
+    try { this.options.onRoute?.(event); } catch { /* observation cannot fail routing */ }
+  }
+}

package/src/models/route/runtime.ts

@@ -0,0 +1,156 @@
+import type { ChatMessage, ChatResult } from "../../omniroute/client.ts";
+import { AdvisorGate, buildAdvisorJudgeRequest, redoFeedback } from "./advisor.ts";
+import type { HubRoute } from "./config.ts";
+import { buildEscalationJudgeRequest, parseEscalationVerdict } from "./escalation.ts";
+import { normalizeConversation } from "./normalize.ts";
+import { extractToolSignals } from "./signals.ts";
+import { RouteLabelTracker, type RouteLabelEvent, type RouteTurnContext, type RouteTurnOutcome } from "./labels.ts";
+import { dimensionsFromSignal, selectStage, type StageState } from "./stage.ts";
+import { EscalationState, SessionState } from "./state.ts";
+import { parseAdvisorVerdict } from "./text.ts";
+import { planExecutePhase, type PlanExecuteState } from "./plan-execute.ts";
+
+export interface RouteEvent {
+  route: string; tier: string; source: "override" | "dimensions" | "hold" | "classifier" | "default"; score: number; ms: number;
+  decision?: string; turn?: string; task?: number; pii?: boolean; severity?: number; spinning?: number; exploring?: number; production?: number;
+}
+export interface AdvisorEvent { route: string; trigger: string; verdict: "approve" | "redo" | "failed"; discardedChars: number }
+interface RouteState { fingerprint: string; stage: StageState; plan: PlanExecuteState; escalation: EscalationState; advisor: AdvisorGate }
+export interface RouteHost {
+  execute: (model: string, messages: ChatMessage[], judge: boolean, signal: AbortSignal, maxTokens?: number) => Promise<ChatResult>;
+  onCampus: () => Promise<boolean>;
+  onRoute?: (event: RouteEvent) => void;
+  onRouteOutcome?: (event: RouteLabelEvent) => void;
+  onAdvisor?: (event: AdvisorEvent) => void;
+}
+
+/** Transport stays in the host. Optional judge work has one deadline and five-minute failure backoff. */
+export class HubRouteRuntime {
+  private readonly states = new SessionState<RouteState>();
+  private readonly labels: RouteLabelTracker;
+  private judgeOffUntil = 0;
+  constructor(private readonly host: RouteHost, private readonly judgeTimeoutMs = 8000) {
+    this.labels = new RouteLabelTracker(event => this.host.onRouteOutcome?.(event));
+  }
+
+  beginTurn(context: RouteTurnContext): void { try { this.labels.beginTurn(context); } catch { /* labels are optional telemetry */ } }
+
+  endTurn(turnId: string, outcome: RouteTurnOutcome): void {
+    try { this.labels.endTurn(turnId, outcome, event => this.host.onRouteOutcome?.(event)); } catch { /* labels are optional telemetry */ }
+  }
+
+  observeResults(decisionId: string | undefined, assistant: ChatMessage, toolMessages: ChatMessage[]): void {
+    try { this.labels.observeResults(decisionId, assistant, toolMessages); } catch { /* model output cannot break a turn through telemetry */ }
+  }
+
+  private state(route: string, config: HubRoute, scope: string): RouteState {
+    const key = `${scope}:${route}`, fingerprint = JSON.stringify(config);
+    const prior = this.states.get(key);
+    if (prior?.fingerprint === fingerprint) return prior;
+    const value: RouteState = { fingerprint, stage: { capableHoldTurnsRemaining: 0 }, plan: { executingSessions: [] }, escalation: new EscalationState(), advisor: new AdvisorGate({ trigger: config.trigger, pattern: config.pattern, maxReviews: config.max_reviews, gateStallTurns: config.gate_stall_turns, gateMinToolResults: config.gate_min_tool_results, transcriptMaxChars: config.transcript_max_chars }) };
+    this.states.set(key, value); return value;
+  }
+
+  /** Executor failures retry the fixed model only in the caller; no tool has run yet. */
+  async call(route: string, config: HubRoute, messages: ChatMessage[], scope: string, pii: boolean, signal: AbortSignal): Promise<ChatResult> {
+    const labelTurn = this.labels.captureTurn();
+    const started = performance.now(), state = this.state(route, config, scope);
+    const conversation = normalizeConversation(messages), signals = extractToolSignals(conversation);
+    const dimensions = dimensionsFromSignal(signals);
+    const efficient = config.efficient ?? "fast", capable = config.capable ?? "coding";
+    let model = efficient, source: RouteEvent["source"] = "default", score = 0;
+    let sent = messages;
+    if (config.type === "stage") {
+      const decision = selectStage(signals, { confidenceThreshold: config.confidence_threshold, capableHoldTurns: config.hold_turns }, state.stage);
+      state.stage = decision.state;
+      model = (decision.tier ?? decision.defaultTier) === "capable" ? capable : efficient;
+      score = decision.score;
+      source = decision.source === "capable_hold" ? "hold" : decision.source === "override" || decision.source === "dimensions" ? decision.source : "default";
+    } else if (config.type === "plan_execute") {
+      const decision = planExecutePhase(signals, scope, state.plan);
+      model = decision.tier === "capable" ? capable : efficient;
+      state.plan = decision.state;
+      if (decision.planningPrompt) sent = [{ role: "system", content: decision.planningPrompt }, ...messages];
+    } else if (config.type === "escalation" && state.escalation.snapshot().latched) model = capable;
+    let decisionId = this.emitRoute({ route, tier: model, source, score, ms: performance.now() - started }, labelTurn, dimensions, pii, messages);
+    const result = await this.host.execute(model, sent, false, signal);
+    if (config.type !== "escalation" || state.escalation.snapshot().latched) return this.withDecision(result, decisionId);
+    const request = buildEscalationJudgeRequest(normalizeConversation([...messages, result.message]), signals.assistantTurnCount + 1);
+    const answer = await this.judge(config.judge ?? capable, [{ role: "system", content: request.systemPrompt }, ...request.messages], pii, signal, request.maxOutputTokens);
+    const verdict = answer ? parseEscalationVerdict(answer) : undefined;
+    if (answer && !verdict) this.judgeOffUntil = Date.now() + 5 * 60_000;
+    const snapshot = state.escalation.apply(verdict, config.confirmations ?? 2);
+    if (snapshot.latched) { try { this.labels.setLatched(labelTurn, true); } catch { /* optional labels */ } }
+    if (!snapshot.latched || signal.aborted) return this.withDecision(result, decisionId);
+    // The discarded efficient response is not inserted into history or executed as a tool batch.
+    decisionId = this.emitRoute({ route, tier: capable, source: "classifier", score: 0, ms: performance.now() - started }, labelTurn, dimensions, pii, messages);
+    return this.withDecision(await this.host.execute(capable, messages, false, signal), decisionId);
+  }
+
+  /** Reviews held no-tool responses. A redo is fed into the same local turn and bounded by its normal step cap. */
+  async review(route: string, config: HubRoute, messages: ChatMessage[], scope: string, pii: boolean, signal: AbortSignal, decisionId?: string): Promise<string | undefined> {
+    if (config.type !== "advisor") return undefined;
+    const state = this.state(route, config, scope), conversation = normalizeConversation(messages);
+    const latest = messages.at(-1);
+    if (!state.advisor.shouldReview(conversation, { hasToolUse: !!latest?.tool_calls?.length, visibleText: latest?.content ?? "" }, scope) || !state.advisor.reserve(scope)) return undefined;
+    const request = buildAdvisorJudgeRequest(conversation, latest?.content ?? undefined, config.transcript_max_chars);
+    const answer = await this.judge(config.judge ?? config.capable ?? "coding", [{ role: "system", content: request.systemPrompt }, ...request.messages], pii, signal, request.maxOutputTokens);
+    const verdict = answer ? parseAdvisorVerdict(answer) : undefined;
+    state.advisor.settle(scope, verdict ? "success" : "failure");
+    try { this.labels.observeAdvisor(decisionId, verdict?.kind ?? "failed"); } catch { /* optional labels */ }
+    if (answer && !verdict) this.judgeOffUntil = Date.now() + 5 * 60_000;
+    try { this.host.onAdvisor?.({ route, trigger: config.trigger ?? "no_tool_call", verdict: verdict?.kind ?? "failed", discardedChars: Math.max(0, [...JSON.stringify(conversation.messages)].length - (config.transcript_max_chars ?? 200_000)) }); } catch { /* optional telemetry */ }
+    return verdict?.kind === "redo" ? redoFeedback(verdict, latest?.content ?? "").user : undefined;
+  }
+
+  private withDecision(result: ChatResult, decisionId: string | undefined): ChatResult {
+    return decisionId ? { ...result, routeDecision: decisionId } : result;
+  }
+
+  private emitRoute(event: RouteEvent, turn: ReturnType<RouteLabelTracker["captureTurn"]>, dimensions: ReturnType<typeof dimensionsFromSignal>, pii: boolean, priorMessages: ChatMessage[]): string | undefined {
+    if (turn && turn.closed) return undefined;
+    let decision: string | undefined;
+    try {
+      decision = this.labels.addDecision(turn, {
+        severity: dimensions.severity,
+        spinning: dimensions.spinning,
+        exploring: dimensions.exploring,
+        production: dimensions.productionIntensity,
+      }, priorMessages);
+    } catch { /* model inputs cannot fail routing through telemetry */ }
+    const labeled: RouteEvent = decision ? {
+      ...event,
+      decision,
+      turn: turn!.context.turn,
+      ...(turn!.context.task === undefined ? {} : { task: turn!.context.task }),
+      pii: turn!.context.pii,
+      severity: dimensions.severity,
+      spinning: dimensions.spinning,
+      exploring: dimensions.exploring,
+      production: dimensions.productionIntensity,
+    } : event;
+    try { this.host.onRoute?.(labeled); } catch { /* optional telemetry */ }
+    return decision;
+  }
+
+  private async judge(model: string, messages: ChatMessage[], pii: boolean, parent: AbortSignal, maxTokens = 2048): Promise<string | undefined> {
+    if (parent.aborted || Date.now() < this.judgeOffUntil) return undefined;
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    parent.addEventListener("abort", abort, { once: true });
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const work = async (): Promise<string | undefined> => {
+      if (pii && !(await this.host.onCampus())) return undefined;
+      if (controller.signal.aborted) return undefined;
+      const result = await this.host.execute(model, messages, true, controller.signal, maxTokens);
+      return result.message.content?.trim() || undefined;
+    };
+    try {
+      const timeout = new Promise<undefined>(resolve => { timer = setTimeout(() => { controller.abort(); resolve(undefined); }, this.judgeTimeoutMs); });
+      const result = await Promise.race([work(), timeout]);
+      if (!result && !parent.aborted) this.judgeOffUntil = Date.now() + 5 * 60_000;
+      return result;
+    } catch { if (!parent.aborted) this.judgeOffUntil = Date.now() + 5 * 60_000; return undefined; }
+    finally { clearTimeout(timer); parent.removeEventListener("abort", abort); }
+  }
+}

package/src/models/route/signals.ts

@@ -0,0 +1,234 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+// Ported to TypeScript from NVIDIA NeMo Switchyard crates/libsy/src/algorithms/util/tool_signals.rs at c8848511, modified.
+
+import type { Conversation, NormalizedToolCall } from './normalize.ts';
+
+export const DEFAULT_RECENT_WINDOW = 3;
+export const SOFT = 0.3;
+export const HARD = 0.7;
+export const CRITICAL = 1.0;
+
+const EDIT = new Set(['edit', 'multiedit', 'notebookedit', 'str_replace', 'str_replace_based_edit_tool', 'apply_patch', 'text_editor', 'patch']);
+const EDITOR = new Set(['str_replace_based_edit_tool', 'text_editor']);
+const WRITE = new Set(['write', 'create_file', 'new_file', 'write_file']);
+const READ = new Set(['read', 'view', 'read_file', 'search_files', 'glob', 'grep', 'find', 'ls']);
+const PLAN = new Set(['todowrite', 'todo_write', 'todo', 'update_plan', 'todo_list']);
+const SHELL = new Set(['bash', 'shell_command', 'shell', 'local_shell_call', 'terminal', 'exec_command', 'exec', 'powershell']);
+const BASH_READ_COMMANDS = new Set(['cat', 'rg', 'nl', 'jq', 'pwd', 'tree', 'sed', 'grep', 'ls', 'find', 'head', 'tail', 'wc', 'diff', 'which', 'ps', 'df', 'du', 'stat', 'file', 'less', 'more', 'readlink', 'realpath', 'basename', 'dirname', 'printenv']);
+const GIT_READ = new Set(['status', 'diff', 'log', 'show', 'show-ref', 'rev-parse', 'ls-files', 'ls-remote', 'ls-tree', 'grep', 'blame', 'merge-base', 'check-ignore', 'tag']);
+
+export interface ToolObservation {
+  name: string;
+  command?: string;
+  resultText?: string;
+  isError?: boolean;
+  source?: string;
+  /** Actual native assistant/model turn identity, absent when the surface cannot prove it. */
+  turn?: string;
+}
+
+export interface ToolSignals {
+  severity: number;
+  repeatedFailure: boolean;
+  noErrorStreak: number;
+  editCount: number;
+  writeCount: number;
+  readCount: number;
+  todowriteCount: number;
+  recentEditCount: number;
+  recentWriteCount: number;
+  recentReadCount: number;
+  recentTodowriteCount: number;
+  newCount: number;
+  recentNewCount: number;
+  pureBashStreak: number;
+  testsPassed: boolean;
+  toolResultCount: number;
+  assistantTurnCount: number;
+  turnDepth: number;
+  compacted: boolean;
+}
+
+type Semantic = 'write' | 'edit' | 'read' | 'plan' | 'new' | 'unknown';
+const emptySignals = (turnDepth: number): ToolSignals => ({
+  severity: 0, repeatedFailure: false, noErrorStreak: 0, editCount: 0, writeCount: 0,
+  readCount: 0, todowriteCount: 0, recentEditCount: 0, recentWriteCount: 0,
+  recentReadCount: 0, recentTodowriteCount: 0, newCount: 0, recentNewCount: 0,
+  pureBashStreak: 0, testsPassed: false, toolResultCount: 0, assistantTurnCount: 0,
+  turnDepth, compacted: false,
+});
+
+function argumentCommand(args: unknown): string | undefined {
+  if (typeof args === 'string') {
+    const raw = args;
+    try { args = JSON.parse(raw) as unknown; } catch { return raw; }
+  }
+  if (!args || typeof args !== 'object') return undefined;
+  const obj = args as Record<string, unknown>;
+  for (const key of ['command', 'cmd', 'input']) if (typeof obj[key] === 'string') return obj[key] as string;
+  if (typeof obj.command === 'object' && obj.command && typeof (obj.command as Record<string, unknown>).text === 'string') return (obj.command as Record<string, string>).text;
+  return undefined;
+}
+
+function splitShell(command: string): string[] {
+  const parts: string[] = []; let start = 0; let quote = ''; let escaped = false;
+  for (let i = 0; i < command.length; i++) {
+    const c = command[i]!;
+    if (escaped) { escaped = false; continue; }
+    if (c === '\\' && quote !== "'") { escaped = true; continue; }
+    if (quote === c) quote = '';
+    else if (!quote && (c === "'" || c === '"')) quote = c;
+    else if (!quote && ['\n', ';', '|', '&'].includes(c)) { const s = command.slice(start, i).trim(); if (s) parts.push(s); start = i + 1; }
+  }
+  const rest = command.slice(start).trim(); if (rest) parts.push(rest); return parts;
+}
+
+function shellWords(segment: string): string[] {
+  const words = segment.split(/[\t\n\v\f\r ]+/u).filter(Boolean);
+  let i = 0;
+  if (words[i] === 'env') { i++; while (words[i]?.startsWith('-')) i++; }
+  while (words[i]?.includes('=') && !words[i]?.startsWith('=')) i++;
+  return words.slice(i);
+}
+function baseProgram(word: string): string { return word.split('/').pop() ?? word; }
+function shellClassification(command: string): Semantic {
+  const lower = command.toLowerCase();
+  if (['cat >', 'cat >>', 'echo >', 'echo >>', 'tee ', 'printf >', 'printf >>', '> /', '>> /', "<< 'eof'", '<<eof', "<<'eof'", '<< eof'].some((p) => lower.includes(p))) return 'write';
+  if (lower.includes('python') && ['write_text(', 'writelines(', '.write('].some((p) => lower.includes(p))) return 'write';
+  if (splitShell(lower).some((s) => baseProgram(shellWords(s)[0] ?? '') === 'node') && ['writefilesync(', 'writefile(', 'appendfilesync(', 'appendfile('].some((p) => lower.includes(p))) return 'write';
+  const segments = splitShell(lower);
+  for (const segment of segments) {
+    const words = shellWords(segment); const p = baseProgram(words[0] ?? '');
+    if (['cp', 'mkdir', 'touch', 'install'].includes(p)) return 'write';
+    const redirectsOutput = words.some((word) => word === '>' || word === '>>' || /^\d*>{1,2}(?!&)\S*$/u.test(word));
+    if (redirectsOutput && (['echo', 'printf', 'git'].includes(p) || BASH_READ_COMMANDS.has(p))) return 'write';
+  }
+  if (['sed -i', 'sed --in-place', 'awk -i inplace', "awk 'inplace=1'", 'patch ', 'patch -p', 'perl -i', 'perl -p -i', 'perl -pi'].some((p) => lower.includes(p))) return 'edit';
+  for (const segment of segments) {
+    const words = shellWords(segment); const p = baseProgram(words[0] ?? ''); const has = (x: string) => words.includes(x);
+    if (p === 'mv' || p === 'rm') return 'edit';
+    if (p === 'perl' && words.slice(1).some((w) => w.startsWith('-') && w.slice(1).includes('i'))) return 'edit';
+    if (p === 'git' && ['apply', 'am', 'restore'].includes(words[1] ?? '')) return 'edit';
+    if (p === 'gofmt' && has('-w')) return 'edit';
+    if (p === 'cargo' && words[1] === 'fmt' && !has('--check')) return 'edit';
+    if (p === 'ruff' && ((words[1] === 'format' && !has('--check')) || (words[1] === 'check' && has('--fix')))) return 'edit';
+    if (p === 'prettier' && has('--write')) return 'edit';
+    if (p === 'black' && !has('--check')) return 'edit';
+    if (words.some((word) => baseProgram(word) === 'prettier') && has('--write')) return 'edit';
+    if (words.some((word) => baseProgram(word) === 'ruff') && ((has('format') && !has('--check')) || (has('check') && has('--fix')))) return 'edit';
+  }
+  if (segments.some((s) => /\b(?:cat \/|cat \.\/|cat \.\.\/|grep |ls |ls -|find |head |tail |wc |diff |which |ps |df |du |stat |file |less |more )/u.test(s))) return 'read';
+  for (const segment of segments) {
+    const words = shellWords(segment); const p = baseProgram(words[0] ?? '');
+    if (BASH_READ_COMMANDS.has(p) || segment === 'env' || (p === 'command' && words[1] === '-v') || p === 'type') return 'read';
+    if (p === 'git') {
+      const sub = words[1];
+      if (GIT_READ.has(sub ?? '') || (sub === 'branch' && (!words[2] || words[2]!.startsWith('-'))) || (sub === 'remote' && (!words[2] || words[2]!.startsWith('-') || words[2] === 'get-url')) || (sub === 'config' && ['--get', '--get-all', '--list', '-l'].includes(words[2] ?? ''))) return 'read';
+    }
+  }
+  return 'unknown';
+}
+
+function semantic(name: string, command?: string, source?: string): Semantic {
+  if (source?.toLowerCase() === 'filechange') return 'edit';
+  const lower = name.toLowerCase();
+  if (source === 'codex' && lower === 'filechange') return 'edit';
+  if (WRITE.has(lower)) return 'write';
+  if (EDITOR.has(lower) && command === 'view') return 'read';
+  if (EDIT.has(lower)) return 'edit';
+  if (READ.has(lower)) return 'read';
+  if (PLAN.has(lower)) return 'plan';
+  if (SHELL.has(lower) && command !== undefined) return shellClassification(command);
+  return 'unknown';
+}
+
+interface Result { text: string; isError: boolean; }
+function lower(text: string): string { return text.toLowerCase(); }
+const patterns: Array<[string, number, string[]]> = [
+  ['oom', CRITICAL, ['out of memory', 'memoryerror', 'cannot allocate memory']],
+  ['connection_refused', HARD, ['connection refused', 'connectionrefusederror', 'econnrefused']],
+  ['traceback', HARD, ['traceback (most recent call last)']],
+  ['import_error', HARD, ['modulenotfounderror:', 'importerror:', 'no module named ']],
+  ['cmd_not_found', HARD, ['command not found', 'not found\n', '/usr/bin/env: ']],
+  ['assertion', HARD, ['assertionerror']], ['value_error', HARD, ['valueerror:']], ['syntax_error', HARD, ['syntaxerror:']],
+  ['timeout', HARD, ['timed out', 'timeouterror', 'timeout expired', 'deadline exceeded']],
+  ['no_such_file', HARD, ['filenotfounderror:', 'no such file or directory', 'file does not exist']],
+  ['exit_nonzero', SOFT, ['returned non-zero']],
+];
+function failureSeverity(text: string, isError: boolean): { severity: number; names: string[] } {
+  const l = lower(text); let severity = 0; const names: string[] = [];
+  for (const [name, value, needles] of patterns) if (needles.some((needle) => l.includes(needle))) { severity = Math.max(severity, value); names.push(name); }
+  const exitPhrases = ['exit code', 'exit status', 'exited with code', 'exited with status'];
+  for (const phrase of exitPhrases) {
+    let cursor = 0;
+    while (cursor < l.length) {
+      const at = l.indexOf(phrase, cursor);
+      if (at < 0) break;
+      const digits = l.slice(at + phrase.length).replace(/^[\s:='"`]*/u, '').match(/^\d+/u)?.[0];
+      if (digits && Number(digits) !== 0) { severity = Math.max(severity, SOFT); break; }
+      cursor = at + phrase.length;
+    }
+  }
+  if (l.split('\n').some((line) => {
+    const trimmed = line.trimStart();
+    if (['compilation failed', 'error: compilation failed', 'error: could not compile'].includes(trimmed) || trimmed.startsWith('error: could not compile ')) return true;
+    const match = trimmed.match(/^error\[e(\d+)\]:/u);
+    return match !== null && match[1]!.length > 0;
+  })) { severity = Math.max(severity, HARD); names.push('compiler'); }
+  if (/(?:typeerror|referenceerror|rangeerror|runtimeerror|keyerror|attributeerror):/u.test(l) && /\n\s{2,}at\s/u.test(l)) { severity = Math.max(severity, HARD); names.push('runtime_exception'); }
+  if (/panic: runtime error:/u.test(l) && /\ngoroutine |\[signal sig/u.test(l)) { severity = Math.max(severity, HARD); names.push('runtime_panic'); }
+  if (/^(?:error: patch failed:|patch failed:|invalid context)|: patch does not apply/mu.test(l.split('\n').map(line => line.trimStart()).join('\n'))) { severity = Math.max(severity, HARD); names.push('patch_failure'); }
+  return { severity: isError ? Math.max(severity, HARD) : severity, names };
+}
+export function fingerprint(text: string, isError: boolean): string | undefined {
+  const detected = failureSeverity(text, isError); if (detected.severity < HARD && !isError) return undefined;
+  const lines = lower(text).split('\n');
+  const diagnostic = lines.find((line) => /error|exception|panic|failed|timed out|timeout|connection refused|cannot allocate memory|out of memory|not found/u.test(line.trim())) ?? lines.find((line) => line.trim()) ?? '';
+  const normalized = [...diagnostic.split(/\s+/u).map((word) => word.startsWith('/') || word.includes('/src/') || word.includes('/tmp/') ? '<path>' : word.replace(/\d+/gu, '#')).join(' ')].slice(0, 240).join('');
+  return `${detected.names.join(',')}|${normalized}`;
+}
+function nonzeroFailureCount(text: string): boolean {
+  for (const m of text.matchAll(/\b(\d+)\s+(failed|failure|failures|errors|error)\b/gu)) if (Number(m[1]) !== 0) return true;
+  return false;
+}
+function testPass(text: string): boolean {
+  const l = lower(text);
+  const pass = [' passed', 'passed in', 'tests passed', 'all tests passed', 'test ok', 'test result: ok', 'passed.\n', 'tests pass', '\nok ', '✓ '].some((p) => l.includes(p));
+  return pass && !['✗ ', 'fatal:', 'assertionerror', 'error:'].some((p) => l.includes(p)) && !nonzeroFailureCount(l);
+}
+
+function buildSignals(calls: Array<{name:string;command?:string;source?:string}>, results: Result[], turnDepth:number, assistantTurns:number, compacted:boolean, recentWindow:number): ToolSignals {
+  const signal = emptySignals(turnDepth); signal.assistantTurnCount = assistantTurns; signal.toolResultCount = results.length; signal.compacted = compacted;
+  const window = Math.max(1, recentWindow); const recentResults = results.slice(-window);
+  signal.severity = recentResults.reduce((max, result) => Math.max(max, failureSeverity(result.text, result.isError).severity), 0);
+  const fingerprints = recentResults.map((r) => fingerprint(r.text,r.isError)).filter((v):v is string=>v!==undefined);
+  signal.repeatedFailure = new Set(fingerprints).size < fingerprints.length;
+  for (const result of [...results].reverse()) { if (result.isError || failureSeverity(result.text,false).severity > 0) break; signal.noErrorStreak++; }
+  signal.testsPassed = recentResults.some((result,index) => {
+    const latestFailure = recentResults.map((r,i)=>failureSeverity(r.text,r.isError).severity>0||r.isError?i:-1).filter(i=>i>=0).at(-1) ?? -1;
+    return index > latestFailure && testPass(result.text);
+  });
+  const recentCalls = calls.slice(-window); const count = (list:typeof calls) => list.map((call)=>semantic(call.name,call.command,call.source));
+  const all = count(calls); const recent = count(recentCalls);
+  signal.writeCount = all.filter((s)=>s==='write').length; signal.editCount=all.filter((s)=>s==='edit').length; signal.readCount=all.filter((s)=>s==='read').length; signal.todowriteCount=all.filter((s)=>s==='plan').length;
+  signal.recentWriteCount=recent.filter((s)=>s==='write').length; signal.recentEditCount=recent.filter((s)=>s==='edit').length; signal.recentReadCount=recent.filter((s)=>s==='read').length; signal.recentTodowriteCount=recent.filter((s)=>s==='plan').length; signal.newCount=all.filter((s)=>s==='new').length; signal.recentNewCount=recent.filter((s)=>s==='new').length;
+  for(const s of [...all].reverse()){if(s!=='unknown')break;signal.pureBashStreak++;}
+  return signal;
+}
+
+export function extractToolSignals(conversation: Conversation, recentWindow = DEFAULT_RECENT_WINDOW): ToolSignals {
+  const calls: Array<{name:string;command?:string}> = []; const results: Result[]=[]; const ids=new Map<string,boolean>(); let assistants=0; let compacted=false;
+  for(const message of conversation.messages){if(message.role==='assistant')assistants++;
+    if(message.content.toLowerCase().includes('session is being continued'))compacted=true;
+    for(const call of message.toolCalls){const command=argumentCommand(call.arguments);calls.push({name:call.name,...(command!==undefined?{command}:{})}); ids.set(call.id,semantic(call.name,command)==='read');}
+    for(const result of message.toolResults){const retrieval=ids.get(result.toolCallId)===true&&!result.isError;results.push({text:retrieval?'':result.content,isError:result.isError===true});}
+  }
+  return buildSignals(calls,results,conversation.messages.length,assistants,compacted,recentWindow);
+}
+
+export function extractToolSignalsFromObservations(observations: readonly ToolObservation[], turnDepth = observations.length, recentWindow = DEFAULT_RECENT_WINDOW): ToolSignals {
+  const calls=observations.map((o)=>({name:o.name, ...(o.command!==undefined?{command:o.command}:{}), ...(o.source!==undefined?{source:o.source}:{})}));
+  const results=observations.filter((o)=>o.resultText!==undefined||o.isError===true).map((o)=>({text:!o.isError && semantic(o.name,o.command,o.source)==='read' ? '' : o.resultText??'',isError:o.isError===true}));
+  return buildSignals(calls,results,turnDepth,turnDepth,false,recentWindow);
+}

package/src/models/route/stage.ts

@@ -0,0 +1,93 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+// Ported to TypeScript from NVIDIA NeMo Switchyard crates/libsy/src/algorithms/util/stage.rs at c8848511, modified.
+
+import type { ToolSignals } from './signals.ts';
+
+export type Tier = 'capable' | 'efficient';
+export type PickerMode = 'capable_first' | 'efficient_first';
+export type DecisionSource = 'override' | 'capable_hold' | 'dimensions' | 'ambiguous' | 'llm-classifier' | 'fall_open';
+export interface CodingAgentDimensions { severity:number; spinning:number; exploring:number; productionIntensity:number }
+export interface ScoreResult { score:number; confidence:number }
+export type PickOutcome =
+  | {kind:'resolved';tier:Tier;source:DecisionSource;probability:number;confidence:number|null}
+  | {kind:'consult_classifier';probability:number;confidence:number;defaultTier:Tier};
+export interface StageState { capableHoldTurnsRemaining:number }
+export interface HandoffNoteConfig {
+  escalationNote: string;
+  deescalationNote?: string;
+  onlyOnWrongSignalEscalation?: boolean;
+}
+export interface StageOptions { mode?:PickerMode; confidenceThreshold?:number; capableHoldTurns?:number; handoffNotes?:HandoffNoteConfig }
+export interface StageDecision { tier:Tier|undefined; defaultTier:Tier; source:DecisionSource; probability:number; confidence:number; score:number; dimensions:CodingAgentDimensions; note?:string; state:StageState }
+
+const STALL_MIN_TURN_DEPTH=8;
+const SCORE_GAIN=5;
+const HARD_SEVERITY=0.7;
+const SIGNAL_UNIT=0.1;
+const SEVERITY_CRITICAL=1;
+
+export function dimensionsFromSignal(signal:ToolSignals):CodingAgentDimensions {
+  const recentOps=signal.recentWriteCount+signal.recentEditCount+signal.recentReadCount+signal.recentTodowriteCount;
+  const deep=signal.turnDepth>=STALL_MIN_TURN_DEPTH;
+  const noProduction=signal.recentWriteCount===0&&signal.recentEditCount===0;
+  const investigating=signal.recentReadCount>=1||signal.recentTodowriteCount>=1;
+  const newActivity=signal.recentNewCount>=1;
+  const spinning=deep&&noProduction&&!investigating&&!newActivity;
+  const exploring=deep&&noProduction&&investigating&&!newActivity;
+  const production=recentOps===0?0:(signal.recentWriteCount+signal.recentEditCount)/recentOps;
+  return {severity:signal.severity,spinning:spinning?1:0,exploring:exploring?1:0,productionIntensity:production};
+}
+
+export function scoreSignal(signal:ToolSignals):ScoreResult {
+  const d=dimensionsFromSignal(signal);
+  const raw=SIGNAL_UNIT*(d.severity/HARD_SEVERITY+d.spinning+d.exploring-d.productionIntensity);
+  const score=Math.tanh(SCORE_GAIN*raw);
+  return {score,confidence:Math.abs(score)};
+}
+
+export function pickTier(signal:ToolSignals, mode:PickerMode='efficient_first', confidenceThreshold=0.5):PickOutcome {
+  const defaultTier:Tier=mode==='capable_first'?'capable':'efficient';
+  if(signal.compacted||signal.severity>=SEVERITY_CRITICAL||signal.repeatedFailure)
+    return {kind:'resolved',tier:'capable',source:'override',probability:0.5,confidence:1};
+  const scored=scoreSignal(signal); const probability=(scored.score+1)/2; const half=confidenceThreshold/2;
+  if(probability>0.5+half||probability<0.5-half)
+    return {kind:'resolved',tier:probability>0.5?'capable':'efficient',source:'dimensions',probability,confidence:scored.confidence};
+  return {kind:'consult_classifier',probability,confidence:scored.confidence,defaultTier};
+}
+
+export function handoffNoteFor(tier:Tier, source:DecisionSource, config:HandoffNoteConfig):string|undefined {
+  if(tier==='capable') {
+    const signalDriven=source==='override'||source==='dimensions';
+    return (config.onlyOnWrongSignalEscalation??true)&&!signalDriven ? undefined : config.escalationNote;
+  }
+  return config.deescalationNote;
+}
+
+/** Apply stage hard rules, dimension scoring, and the capable recovery hold. */
+export function selectStage(signal:ToolSignals, options:StageOptions={}, state:StageState={capableHoldTurnsRemaining:0}):StageDecision {
+  const mode=options.mode??'efficient_first'; const defaultTier:Tier=mode==='capable_first'?'capable':'efficient';
+  const holdTurns=Math.max(0,Math.trunc(options.capableHoldTurns??2));
+  let remaining=Math.max(0,Math.trunc(state.capableHoldTurnsRemaining));
+  const cleanTestPass=signal.testsPassed&&signal.noErrorStreak>0;
+  if(cleanTestPass)remaining=0;
+  let outcome:PickOutcome;
+  if(!cleanTestPass&&remaining>0){remaining--;outcome={kind:'resolved',tier:'capable',source:'capable_hold',probability:0.5,confidence:1};}
+  else outcome=pickTier(signal,mode,options.confidenceThreshold??0.5);
+  if(outcome.kind==='resolved'&&outcome.tier==='capable'&&(outcome.source==='override'||outcome.source==='dimensions'))remaining=holdTurns;
+  const dimensions=dimensionsFromSignal(signal); const score=scoreSignal(signal).score;
+  const note = outcome.kind === 'resolved' && options.handoffNotes
+    ? handoffNoteFor(outcome.tier, outcome.source, options.handoffNotes)
+    : undefined;
+  return {
+    tier: outcome.kind === 'resolved' ? outcome.tier : undefined,
+    defaultTier,
+    source: outcome.kind === 'consult_classifier' ? 'ambiguous' : outcome.source,
+    probability: outcome.probability,
+    confidence: outcome.confidence ?? 0,
+    score,
+    dimensions,
+    ...(note === undefined ? {} : { note }),
+    state: { capableHoldTurnsRemaining: remaining },
+  };
+}

package/src/models/route/state.ts

@@ -0,0 +1,54 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+// Ported to TypeScript from NVIDIA NeMo Switchyard crates/libsy/src/algorithms/escalation.rs at commit c8848511, modified.
+
+import type { EscalationCategory, EscalationVerdict } from "./escalation.ts";
+
+export interface EscalationStateSnapshot { latched: boolean; category?: EscalationCategory; streak: number }
+
+/** Confirmation streak and session latch used by the trajectory escalation policy. */
+export class EscalationState {
+  private category?: EscalationCategory;
+  private streak = 0;
+  private latched = false;
+  apply(verdict: EscalationVerdict | undefined, confirmations = 2): EscalationStateSnapshot {
+    if (this.latched) return this.snapshot();
+    if (verdict && verdict.escalate && verdict.category !== "none" && verdict.newEvidence) {
+      this.streak = this.category === verdict.category ? this.streak + 1 : 1;
+      this.category = verdict.category;
+      if (this.streak >= confirmations) this.latched = true;
+    } else if (verdict) {
+      this.streak = 0;
+      this.category = undefined;
+    }
+    return this.snapshot();
+  }
+  reset(): void { this.category = undefined; this.streak = 0; this.latched = false; }
+  snapshot(): EscalationStateSnapshot { return { latched: this.latched, ...(this.category ? { category: this.category } : {}), streak: this.streak }; }
+}
+
+/** Bounded keyed state helper with one-hour idle expiry for independent sessions. */
+export class SessionState<T> {
+  private readonly values = new Map<string, { value: T; touchedAt: number }>();
+  constructor(private readonly maxEntries = 1024, private readonly ttlMs = 60 * 60 * 1000) {}
+  get(key: string, now = Date.now()): T | undefined {
+    this.expire(now);
+    const entry = this.values.get(key);
+    if (entry) entry.touchedAt = now;
+    return entry?.value;
+  }
+  set(key: string, value: T, now = Date.now()): void {
+    this.expire(now);
+    this.values.delete(key);
+    while (this.values.size >= this.maxEntries) {
+      const oldest = this.values.keys().next().value;
+      if (oldest === undefined) break;
+      this.values.delete(oldest);
+    }
+    this.values.set(key, { value, touchedAt: now });
+  }
+  delete(key: string): void { this.values.delete(key); }
+  private expire(now: number): void {
+    for (const [key, entry] of this.values) if (now - entry.touchedAt >= this.ttlMs) this.values.delete(key);
+  }
+}