@gajae-code/coding-agent 0.14.2 → 0.15.0

package/src/task/types.ts

@@ -1,7 +1,9 @@
 import type { ThinkingLevel } from "@gajae-code/agent-core";
 import type { Usage } from "@gajae-code/ai/core";
+import type { FallbackTriggerClass } from "@gajae-code/ai/utils/fallback-transport";
 import { $env } from "@gajae-code/utils";
 import * as z from "zod/v4";
+import { AUTOROUTING_SELECTOR_MAX_LENGTH, type AutoroutingReasonCode } from "../config/autorouting-contract";
 import { isValidTaskId, TASK_ID_DESCRIPTION } from "./id";
 import type { TaskResultReceipt } from "./receipt";
 import type { SpawnRoiReconciliation } from "./roi-reconciliation";
@@ -97,6 +99,10 @@ const createTaskItemSchema = (_contextEnabled: boolean) =>
 		id: z.string().max(48).refine(isValidTaskId, TASK_ID_DESCRIPTION).describe("filesystem-safe task identifier"),
 		description: z.string().describe("ui label, not seen by subagent"),
 		assignment: z.string().describe(assignmentDescription),
+		tier: z
+			.enum(["fast", "balanced", "strong"])
+			.optional()
+			.describe("Advisory unless autorouting is enabled; omitted routes as balanced."),
 		executionMode: z
 			.enum(["default", "ultragoal-red-team"])
 			.optional()
@@ -427,6 +433,154 @@ export function createSetupFailureSummary(error: unknown): SetupFailureSummary {
 	};
 }
 
+/** Bounded, redaction-safe summary of a terminal local (non-provider) subagent failure. */
+export interface LocalErrorSummary {
+	kind: string;
+	summary: string;
+}
+
+/**
+ * Closed stage vocabulary accepted at the executor trust boundary. Mirrors the
+ * agent runtime's `MANAGED_LOCAL_FAILURE_STAGES` overflow entries; a shape
+ * naming any other stage is rejected as untrusted (#4618).
+ */
+const LOCAL_OVERFLOW_STAGES: ReadonlySet<string> = new Set(["overflow.preMeasure", "overflow.staged"]);
+
+const isLocalOverflowCounter = (value: unknown): value is number =>
+	typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+
+/**
+ * Runtime-validate a structured overflow diagnostic at the consuming trust
+ * boundary. Presence on an `AssistantMessage` is NOT authenticity: a foreign
+ * provider/stream payload could set the field, so every value is checked —
+ * closed `stage`/`exceeded` literals and finite non-negative integer counters.
+ * Returns `undefined` for anything that fails, and the caller then degrades to
+ * a fixed neutral sentence instead of interpolating untrusted values (#4618).
+ */
+export function validateLocalOverflowShape(overflow: unknown):
+	| {
+			stage: string;
+			exceeded: "events" | "bytes" | "both";
+			stagedEventCount: number;
+			stagedBytes: number;
+			incomingEventBytes: number;
+			maxStagedEvents: number;
+			maxStagedBytes: number;
+	  }
+	| undefined {
+	if (!overflow || typeof overflow !== "object") return undefined;
+	const shape = overflow as Record<string, unknown>;
+	if (typeof shape.stage !== "string" || !LOCAL_OVERFLOW_STAGES.has(shape.stage)) return undefined;
+	if (shape.exceeded !== "events" && shape.exceeded !== "bytes" && shape.exceeded !== "both") return undefined;
+	const stagedEventCount = shape.stagedEventCount;
+	const stagedBytes = shape.stagedBytes;
+	const incomingEventBytes = shape.incomingEventBytes;
+	const maxStagedEvents = shape.maxStagedEvents;
+	const maxStagedBytes = shape.maxStagedBytes;
+	if (
+		!isLocalOverflowCounter(stagedEventCount) ||
+		!isLocalOverflowCounter(stagedBytes) ||
+		!isLocalOverflowCounter(incomingEventBytes) ||
+		!isLocalOverflowCounter(maxStagedEvents) ||
+		!isLocalOverflowCounter(maxStagedBytes)
+	) {
+		return undefined;
+	}
+	// The shape must be internally consistent with the cap it claims tripped,
+	// so a fabricated near-miss cannot masquerade as a real rejection.
+	const projectedEvents = stagedEventCount + 1;
+	const projectedBytes = stagedBytes + incomingEventBytes;
+	if (shape.exceeded === "events" || shape.exceeded === "both") {
+		if (projectedEvents <= maxStagedEvents) return undefined;
+	}
+	if (shape.exceeded === "bytes" || shape.exceeded === "both") {
+		if (projectedBytes <= maxStagedBytes) return undefined;
+	}
+	return {
+		stage: shape.stage,
+		exceeded: shape.exceeded,
+		stagedEventCount,
+		stagedBytes,
+		incomingEventBytes,
+		maxStagedEvents,
+		maxStagedBytes,
+	};
+}
+
+/**
+ * Render the parent-facing summary of a validated overflow diagnostic. Built
+ * ONLY from the closed-vocabulary stage/exceeded literals and the numeric
+ * counters — no producer-controlled text participates, so a hostile or buggy
+ * child can inject nothing through this path (#4618).
+ */
+export function formatBufferOverflowSummary(overflow: {
+	stage: string;
+	exceeded: "events" | "bytes" | "both";
+	stagedEventCount: number;
+	stagedBytes: number;
+	incomingEventBytes: number;
+	maxStagedEvents: number;
+	maxStagedBytes: number;
+}): string {
+	return (
+		`staging-buffer overflow at ${overflow.stage} (exceeded=${overflow.exceeded}); ` +
+		`retained ${overflow.stagedEventCount}/${overflow.maxStagedEvents} events, ` +
+		`${overflow.stagedBytes} staged bytes; rejected event ${overflow.incomingEventBytes} bytes; ` +
+		`projected ${overflow.stagedBytes + overflow.incomingEventBytes}/${overflow.maxStagedBytes} bytes. ` +
+		"Local gjc staging limit, not a provider or context-window failure; re-issuing reproduces it."
+	);
+}
+
+/** Fixed, bounded summary for a terminal snapshot failure — never free-form child text (#4618). */
+const LOCAL_SNAPSHOT_FAILURE_SUMMARY =
+	"Managed fallback could not produce a serializable event snapshot (local snapshot bug, not a provider failure).";
+
+/**
+ * Build the safe parent-facing summary for a terminal local failure.
+ *
+ * Trust boundary: the structured `bufferOverflow` shape is runtime-validated
+ * (`validateLocalOverflowShape`) before any value is interpolated — closed
+ * literals and checked integers only. A shape that fails validation, or an
+ * overflow kind with no shape at all, degrades to a fixed neutral sentence.
+ * `local_snapshot_failure` uses a fixed sentence too: regex redaction cannot
+ * make arbitrary child message text safe to embed in a parent receipt.
+ */
+export function createLocalErrorSummary(
+	kind: unknown,
+	_message: string | undefined,
+	overflow?: unknown,
+): LocalErrorSummary {
+	const normalizedKind = kind === "local_buffer_overflow" || kind === "local_snapshot_failure" ? kind : "local";
+	if (normalizedKind === "local_buffer_overflow") {
+		const validated = validateLocalOverflowShape(overflow);
+		return {
+			kind: normalizedKind,
+			summary: validated
+				? formatBufferOverflowSummary(validated)
+				: "Local staging-buffer overflow; structured diagnostic unavailable.",
+		};
+	}
+	if (normalizedKind === "local_snapshot_failure") {
+		return {
+			kind: normalizedKind,
+			// Fixed text: a self-labeled foreign error can set the kind, and no
+			// free-form message — redacted or not — is forwarded to the parent.
+			summary: LOCAL_SNAPSHOT_FAILURE_SUMMARY,
+		};
+	}
+	return {
+		kind: normalizedKind,
+		summary: "Subagent failed with a local error.",
+	};
+}
+
+const ASSISTANT_LOCAL_ERROR_KINDS: ReadonlySet<string> = new Set(["local_buffer_overflow", "local_snapshot_failure"]);
+
+/** Whether an assistant terminal message carries a known local (non-provider) failure kind. */
+export function isAssistantLocalErrorKind(kind: unknown): kind is "local_buffer_overflow" | "local_snapshot_failure" {
+	return typeof kind === "string" && ASSISTANT_LOCAL_ERROR_KINDS.has(kind);
+}
+
 export interface TaskRecoveryArtifactRef {
 	uri: string;
 	sizeBytes: number;
@@ -447,6 +601,159 @@ export interface TaskPersistenceResult {
 	recoveryRef?: TaskRecoveryArtifactRef;
 }
 
+export type RoutingSubstitution = "auth_substituted" | "assistant_model_mismatch";
+
+/** A typed failure observed while an autorouting candidate is still before the real provider fence. */
+export type AutoroutingPreflightFailure =
+	| {
+			kind: "local";
+			op: "auth_resolve" | "session_open" | "tool_bootstrap" | "preflight_validation";
+			transient: boolean;
+	  }
+	| { kind: "transport"; class: FallbackTriggerClass };
+
+export type AutoroutingAttemptCode =
+	| "probe_passed"
+	| "accepted"
+	| "spawn_transient_retry"
+	| "credential_unavailable"
+	| "config_invalid_terminal"
+	| "post_acceptance_failure"
+	| "unclassified_terminal";
+
+export type AutoroutingAttempt = {
+	selector: string;
+	phase: "probe" | "durable";
+	code: AutoroutingAttemptCode;
+};
+
+export type AutoroutingSkip = {
+	selector: string;
+	code: AutoroutingReasonCode;
+};
+
+export interface TaskRoutingEvidence {
+	tier: "fast" | "balanced" | "strong";
+	requestedTier?: "fast" | "balanced" | "strong";
+	defaultTierApplied?: true;
+	requestedSelector: string;
+	authResolvedModel?: string;
+	effectiveModel?: string;
+	notExecuted?: true;
+	substitutions: RoutingSubstitution[];
+	manualFallbackReason?: "tier_unmatched" | "tier_missing_in_map";
+	freshOnResume?: true;
+	note?: string;
+	skips?: AutoroutingSkip[];
+	omittedSkipCount?: number;
+	omittedByCode?: Partial<Record<AutoroutingSkip["code"], number>>;
+	attempts?: AutoroutingAttempt[];
+	terminal?: "preflight_exhausted" | "all_candidates_skipped";
+}
+
+const AUTOROUTING_ATTEMPT_CODES = new Set<AutoroutingAttemptCode>([
+	"probe_passed",
+	"accepted",
+	"spawn_transient_retry",
+	"credential_unavailable",
+	"config_invalid_terminal",
+	"post_acceptance_failure",
+	"unclassified_terminal",
+]);
+
+const ROUTING_UNSAFE_TEXT_RE = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/u;
+
+function validBoundedSelector(value: unknown): value is string {
+	return (
+		typeof value === "string" &&
+		value.length > 0 &&
+		value.length <= AUTOROUTING_SELECTOR_MAX_LENGTH &&
+		!ROUTING_UNSAFE_TEXT_RE.test(value)
+	);
+}
+
+export function assertRoutingEvidenceInvariant(evidence: TaskRoutingEvidence): void {
+	const terminalWithoutModel = evidence.terminal !== undefined || evidence.notExecuted === true;
+	if (
+		!terminalWithoutModel &&
+		(!evidence.effectiveModel || evidence.effectiveModel.length > AUTOROUTING_SELECTOR_MAX_LENGTH)
+	)
+		throw new Error("Invalid effective routing model.");
+	if (!validBoundedSelector(evidence.requestedSelector)) throw new Error("Invalid requested routing selector.");
+	if (evidence.authResolvedModel && evidence.authResolvedModel === evidence.effectiveModel)
+		throw new Error("authResolvedModel must differ from effectiveModel when present.");
+	if (evidence.authResolvedModel !== undefined && !validBoundedSelector(evidence.authResolvedModel))
+		throw new Error("Invalid auth-resolved routing model.");
+
+	if (evidence.skips && evidence.skips.length > 16) throw new Error("Too many autorouting skips.");
+	if (evidence.attempts && evidence.attempts.length > 6) throw new Error("Too many autorouting attempts.");
+	if (
+		evidence.omittedSkipCount !== undefined &&
+		(!Number.isSafeInteger(evidence.omittedSkipCount) || evidence.omittedSkipCount < 0)
+	)
+		throw new Error("Invalid omitted autorouting skip count.");
+	for (const [code, count] of Object.entries(evidence.omittedByCode ?? {})) {
+		if (!Number.isSafeInteger(count) || count < 0) throw new Error("Invalid omitted autorouting skip aggregate.");
+		if (
+			!(
+				code in
+				{
+					tier_unmatched: true,
+					tier_missing_in_map: true,
+					config_invalid: true,
+					map_absent: true,
+					selector_not_provider_qualified: true,
+					auth_substituted: true,
+					assistant_model_mismatch: true,
+					provider_disabled: true,
+					snapshot_missing: true,
+					credential_unavailable: true,
+					preflight_spawn_failed: true,
+					preflight_exhausted: true,
+				}
+			)
+		)
+			throw new Error("Invalid omitted autorouting skip code.");
+	}
+	for (const skip of evidence.skips ?? []) {
+		if (!validBoundedSelector(skip.selector)) throw new Error("Invalid autorouting skip selector.");
+		if (
+			!(
+				skip.code in
+				{
+					tier_unmatched: true,
+					tier_missing_in_map: true,
+					config_invalid: true,
+					map_absent: true,
+					selector_not_provider_qualified: true,
+					auth_substituted: true,
+					assistant_model_mismatch: true,
+					provider_disabled: true,
+					snapshot_missing: true,
+					credential_unavailable: true,
+					preflight_spawn_failed: true,
+					preflight_exhausted: true,
+				}
+			)
+		)
+			throw new Error("Invalid autorouting skip code.");
+	}
+	for (const attempt of evidence.attempts ?? []) {
+		if (!validBoundedSelector(attempt.selector) || !AUTOROUTING_ATTEMPT_CODES.has(attempt.code))
+			throw new Error("Invalid autorouting attempt.");
+		if (attempt.code === "accepted" && attempt.phase !== "durable")
+			throw new Error("accepted requires durable phase.");
+		if (attempt.code === "probe_passed" && attempt.phase !== "probe")
+			throw new Error("probe_passed requires probe phase.");
+		if (attempt.phase === "probe" && attempt.code === "post_acceptance_failure")
+			throw new Error("post_acceptance_failure requires durable phase.");
+		if (attempt.phase === "durable" && attempt.code === "probe_passed")
+			throw new Error("probe_passed requires probe phase.");
+	}
+	if (evidence.terminal === undefined && evidence.omittedSkipCount && !evidence.skips)
+		throw new Error("Omitted skips require skip evidence.");
+}
+
 /** Result from a single agent execution */
 export interface SingleResult {
 	index: number;
@@ -468,13 +775,22 @@ export interface SingleResult {
 	contextTokens?: number;
 	/** Model's context window in tokens, when known. */
 	contextWindow?: number;
+	routing?: TaskRoutingEvidence;
+
 	modelOverride?: string | string[];
 	modelSubstitutionWarning?: ModelSubstitutionWarning;
 	/** Whether the resolved subagent model ran under the effective fast service tier. */
 	fastMode?: boolean;
 	error?: string;
+	/** Safe summary of a terminal local (non-provider) failure kind, e.g. `local_buffer_overflow`. */
+	localErrorSummary?: LocalErrorSummary;
 	/** Safe diagnostic for a failure before the subagent sent its first LLM request. */
 	setupFailure?: SetupFailureSummary;
+	/** Internal typed autorouting preflight outcome; receipt sanitization omits this field. */
+	preflightFailure?: AutoroutingPreflightFailure;
+	preflightFenceCrossed?: boolean;
+	preflightProbeAccepted?: boolean;
+	preflightCommitFailure?: boolean;
 	aborted?: boolean;
 	abortReason?: string;