@sayknow-cli/coding-agent 0.3.16 → 0.4.0

package/src/modes/shared/agent-wire/deep-interview-gate.ts

@@ -7,28 +7,33 @@
  * back into the exact QuestionResult shape the human path produces, so ambiguity
  * scoring/state updates proceed identically whether a human or an agent answers.
  *
- * This is the pure mapping primitive. Routing the ask tool through it (instead of
- * the interactive select/editor UI) when an unattended controller + gate broker
- * are attached is wired with the transport in #321 and exercised by #323.
+ * This is the pure mapping primitive used by SDK-native workflow gate emitters.
  */
-import type { RpcJsonSchema, RpcWorkflowGateKind, RpcWorkflowStage } from "../../rpc/rpc-types";
-import type { OpenGateInput } from "./workflow-gate-broker";
 
-/** "Other (type your own)" sentinel, mirroring the interactive ask tool. */
-export const GATE_OTHER_OPTION = "Other (type your own)";
+import { isDeepInterviewAskQuestion } from "../../../deep-interview/render-middleware";
+import {
+	assertDeepInterviewInputWithinLimit,
+	MAX_USER_RESPONSE_LENGTH,
+} from "../../../skc-runtime/deep-interview-state";
+import type { OpenGateInput } from "./workflow-gate-broker";
+import {
+	type AskGateDeepInterviewState,
+	buildAskGateAnswerSchema,
+	buildAskGateStageState as buildCanonicalAskGateStageState,
+	type WorkflowGateKind,
+	type WorkflowStage,
+} from "./workflow-gate-types";
 
-/** Optional structured deep-interview round metadata supplied by the agent. */
-export interface AskGateDeepInterviewState {
-	round_id?: string;
-	round: number;
-	component: string;
-	dimension: string;
-	ambiguity: number;
-}
+export {
+	type AskGateDeepInterviewState,
+	buildAskGateAnswerSchema,
+	GATE_OTHER_OPTION,
+	validateAskGateStageState,
+} from "./workflow-gate-types";
 
 export interface AskGateWorkflowGateMeta {
-	stage: RpcWorkflowStage;
-	kind: RpcWorkflowGateKind;
+	stage: WorkflowStage;
+	kind: WorkflowGateKind;
 }
 
 export interface AskGateQuestion {
@@ -96,7 +101,7 @@ function deepInterviewQuestionState(questionText: string): Record<string, unknow
 	const state: Record<string, unknown> = {};
 	if (roundMatch) {
 		const round = Number(roundMatch[1]);
-		if (Number.isFinite(round)) state.round = round;
+		if (Number.isSafeInteger(round) && round >= 0) state.round = round;
 		const mode = roundMatch[2]?.trim();
 		if (mode) {
 			state.mode = mode;
@@ -104,8 +109,9 @@ function deepInterviewQuestionState(questionText: string): Record<string, unknow
 			if (normalized.includes("topology")) state.topology_gate = true;
 			if (/(contrarian|simplifier|ontologist)/u.test(normalized)) state.challenge_mode = normalized;
 		}
-		const ambiguity = roundMatch[3]?.trim();
-		if (ambiguity) state.ambiguity = ambiguity;
+		const rawAmbiguity = roundMatch[3]?.trim();
+		const ambiguity = rawAmbiguity === "" || rawAmbiguity === undefined ? Number.NaN : Number(rawAmbiguity);
+		if (Number.isFinite(ambiguity) && ambiguity >= 0 && ambiguity <= 1) state.ambiguity = ambiguity;
 	}
 	if (/Round\s+0\s+\|\s+Topology confirmation/im.test(questionText)) {
 		state.round = 0;
@@ -115,91 +121,35 @@ function deepInterviewQuestionState(questionText: string): Record<string, unknow
 	return state;
 }
 
-function questionAnswerSchema(question: AskGateQuestion, labels: string[]): RpcJsonSchema {
-	const multi = question.multi ?? false;
-	const selectedItems: RpcJsonSchema = { type: "string", enum: labels };
-	const selectedBase: RpcJsonSchema = { type: "array", items: selectedItems, uniqueItems: true };
-	const selectedOnly: RpcJsonSchema = {
-		...selectedBase,
-		minItems: question.allowEmpty ? 0 : 1,
-		...(multi ? {} : { maxItems: 1 }),
-	};
-	const selectedWithOther: RpcJsonSchema = {
-		...selectedBase,
-		...(multi ? {} : { maxItems: 0 }),
-	};
-	return {
-		type: "object",
-		properties: {
-			selected: selectedBase,
-			other: { type: "boolean", description: "set true to provide a free-text answer in `custom`" },
-			custom: {
-				type: "string",
-				minLength: 1,
-				pattern: "\\S",
-				description: "free-text answer; required when `other` is true",
-			},
-			action: {
-				type: "string",
-				enum: ["answer", "clarify"],
-				description: "set to `clarify` to ask about the choices without answering the round",
-			},
-			question: {
-				type: "string",
-				minLength: 1,
-				pattern: "\\S",
-				description: "clarification question; required when action is `clarify`",
-			},
+/** Build and validate exact producer-compatible `stage_state` metadata for one ask question. */
+export function buildAskGateStageState(question: AskGateQuestion, labels: string[]): Record<string, unknown> {
+	return buildCanonicalAskGateStageState(
+		{
+			id: question.id,
+			multi: question.multi,
+			allowEmpty: question.allowEmpty,
+			navigationLabel: question.navigationLabel,
+			deepInterview: question.deepInterview,
+			fallbackState: deepInterviewQuestionState(question.question),
 		},
-		additionalProperties: false,
-		anyOf: [
-			{
-				type: "object",
-				properties: { selected: selectedOnly, other: { const: false }, action: { const: "answer" } },
-				required: ["selected"],
-				additionalProperties: false,
-			},
-			{
-				type: "object",
-				properties: {
-					selected: selectedWithOther,
-					other: { const: true },
-					custom: { type: "string", minLength: 1, pattern: "\\S" },
-					action: { const: "answer" },
-				},
-				required: ["selected", "other", "custom"],
-				additionalProperties: false,
-			},
-			{
-				type: "object",
-				properties: {
-					action: { const: "clarify" },
-					question: { type: "string", minLength: 1, pattern: "\\S" },
-				},
-				required: ["action", "question"],
-				additionalProperties: false,
-			},
-		],
-	};
-}
-
-/** Build `stage_state` round metadata from the structured param (authoritative when present). */
-function structuredDeepInterviewState(meta: AskGateDeepInterviewState): Record<string, unknown> {
-	const state: Record<string, unknown> = {
-		deep_interview_metadata: true,
-		round: meta.round,
-		component: meta.component,
-		dimension: meta.dimension,
-		ambiguity: meta.ambiguity,
-	};
-	if (meta.round_id !== undefined) state.round_id = meta.round_id;
-	return state;
+		labels,
+	);
 }
 
 /** Build the `workflow_gate` open-input for one ask question. */
 export function questionToGate(question: AskGateQuestion): OpenGateInput {
 	const labels = question.options.map(o => o.label);
-	const schema = questionAnswerSchema(question, labels);
+	const schema = buildAskGateAnswerSchema(
+		{
+			multi: question.multi,
+			allowEmpty: question.allowEmpty,
+			customMaxLength:
+				question.deepInterview || isDeepInterviewAskQuestion(question.question)
+					? MAX_USER_RESPONSE_LENGTH
+					: undefined,
+		},
+		labels,
+	);
 	return {
 		stage: question.workflowGate?.stage ?? "deep-interview",
 		kind: question.workflowGate?.kind ?? "question",
@@ -212,18 +162,7 @@ export function questionToGate(question: AskGateQuestion): OpenGateInput {
 		context: {
 			title: question.question,
 			prompt: question.question,
-			stage_state: {
-				question_id: question.id,
-				multi: question.multi ?? false,
-				options: labels,
-				other_option: GATE_OTHER_OPTION,
-				clarification_action: "clarify",
-				allow_empty: question.allowEmpty === true,
-				navigation_label: question.navigationLabel,
-				...(question.deepInterview
-					? structuredDeepInterviewState(question.deepInterview)
-					: deepInterviewQuestionState(question.question)),
-			},
+			stage_state: buildAskGateStageState(question, labels),
 		},
 	};
 }
@@ -305,6 +244,12 @@ export function gateAnswerToResult(question: AskGateQuestion, answer: unknown):
 	if (other && (answer.custom === undefined || answer.custom.trim() === "")) {
 		throw new DeepInterviewGateError("missing_custom", "custom text is required when `other` is true");
 	}
+	if (
+		other &&
+		(question.deepInterview || isDeepInterviewAskQuestion(question.question)) &&
+		answer.custom !== undefined
+	)
+		assertDeepInterviewInputWithinLimit(answer.custom, MAX_USER_RESPONSE_LENGTH, "user_response");
 	return {
 		id: question.id,
 		question: question.question,
@@ -337,6 +282,15 @@ export function classifyAskGateDisposition(
 		multi: (state as Record<string, unknown>).multi === true,
 		allowEmpty: (state as Record<string, unknown>).allow_empty === true,
 	};
+	if (
+		(state as Record<string, unknown>).deep_interview_metadata === true &&
+		typeof (answer as Record<string, unknown>)?.custom === "string"
+	)
+		assertDeepInterviewInputWithinLimit(
+			(answer as Record<string, unknown>).custom as string,
+			MAX_USER_RESPONSE_LENGTH,
+			"user_response",
+		);
 	if (typeof answer === "object" && answer !== null && (answer as Record<string, unknown>).action === "clarify") {
 		gateAnswerToResult(question, answer);
 		return "resolve_without_commit";

package/src/modes/shared/agent-wire/event-contract.ts

@@ -3,8 +3,8 @@
  * for AgentSession events and bounded owner observations.
  *
  * Two distinct consumer-facing shapes, deliberately NOT collapsed into one:
- * - `AgentWireEventPayload`: rich, full `AgentSessionEvent` for renderers
- *   (ACP SDK notifications, RPC/Bridge event frames).
+ * - `AgentWireEventPayload`: rich, full `AgentSessionEvent` for event
+ *   consumers on any agent-wire transport.
  * - `AgentWireOwnerObservation`: bounded/redacted owner evidence for control
  *   planes (Harness). Never carries assistant text, message deltas, raw tool
  *   args, raw command output, raw tool results, answers, or oversize strings.
@@ -45,14 +45,13 @@ const AGENT_SESSION_EVENT_TYPE_REGISTRY: Record<AgentWireEventType, true> = {
 	auto_compaction_end: true,
 	auto_retry_start: true,
 	auto_retry_end: true,
-	retry_fallback_applied: true,
-	retry_fallback_succeeded: true,
 	ttsr_triggered: true,
 	todo_reminder: true,
 	todo_auto_clear: true,
 	irc_message: true,
 	subagent_steer_message: true,
 	notice: true,
+	model_fallback_switched: true,
 	thinking_level_changed: true,
 	goal_updated: true,
 };
@@ -63,8 +62,8 @@ export const AGENT_WIRE_EVENT_TYPES: readonly AgentWireEventType[] = Object.keys
 ) as AgentWireEventType[];
 
 /**
- * Rich event payload. Carries the full `AgentSessionEvent` so renderers (ACP,
- * RPC, Bridge) can present message content, tool args/results, todo state, etc.
+ * Rich event payload. Carries the full `AgentSessionEvent` so event consumers
+ * can present message content, tool args/results, todo state, and related data.
  */
 export interface AgentWireEventPayload {
 	event_type: AgentWireEventType;
@@ -78,7 +77,7 @@ export type AgentWireCompactAssistantMessageEvent = AssistantMessageEvent extend
 
 export interface AgentWireCompactMessageUpdatePayload {
 	event_type: "message_update";
-	/** Compact RPC opt-in payload: delta-only update plus minimal routing metadata. */
+	/** Compact opt-in payload: delta-only update plus minimal routing metadata. */
 	compact: true;
 	message_id: string | null;
 	content_index: number | null;
@@ -120,7 +119,7 @@ export interface AgentWireOwnerObservation {
 	eventType?: AgentWireEventType;
 	/** Set when this observation derives from a non-event wire frame. */
 	frameType?: string;
-	/** Owner event kind (e.g. `rpc_tool_started`). */
+	/** Owner event kind (for example, a tool-started observation). */
 	kind: string;
 	/** Bounded observed signal, or null when the frame carries no signal. */
 	signal: AgentWireObservedSignal | null;

package/src/modes/shared/agent-wire/event-envelope.ts

@@ -5,8 +5,8 @@
  * every variant of the event union and calls `assertNever` in the default arm,
  * so a newly added event variant fails to compile until it is handled here.
  *
- * The canonical sequencer + frame builders live here; the historical `Bridge*`
- * names are retained as thin aliases for callers that have not yet migrated.
+ * The canonical sequencer + frame builders live here under `AgentWire*` names;
+ * this is the only event-frame surface (the historical `Bridge*` aliases were removed).
  */
 import { randomUUID } from "node:crypto";
 import type { AgentSessionEvent } from "../../../session/agent-session";
@@ -67,14 +67,13 @@ export function agentSessionEventType(event: AgentSessionEvent): AgentWireEventT
 		case "auto_compaction_end":
 		case "auto_retry_start":
 		case "auto_retry_end":
-		case "retry_fallback_applied":
-		case "retry_fallback_succeeded":
 		case "ttsr_triggered":
 		case "todo_reminder":
 		case "todo_auto_clear":
 		case "irc_message":
 		case "subagent_steer_message":
 		case "notice":
+		case "model_fallback_switched":
 		case "thinking_level_changed":
 		case "goal_updated":
 			return event.type;
@@ -127,10 +126,6 @@ export class AgentWireFrameSequencer {
 	}
 }
 
-/** Back-compat alias for {@link AgentWireFrameSequencer}. */
-export const BridgeFrameSequencer = AgentWireFrameSequencer;
-export type BridgeFrameSequencer = AgentWireFrameSequencer;
-
 /** Serialize a single `AgentSessionEvent` into a canonical `event` wire frame. */
 export function toAgentWireEventFrame(
 	event: AgentSessionEvent,
@@ -163,13 +158,13 @@ export interface AgentWireCompactMessageUpdateOptions {
 }
 
 /**
- * Stateful compact event serializer for opt-in RPC clients.
+ * Stateful compact event serializer for opt-in wire clients (e.g. the SDK).
  *
  * Only `message_update` changes shape: it carries the immutable provider delta
  * plus message/content identifiers, with periodic full-message checkpoints that
  * are cloned synchronously before the caller returns to the event loop. All other
- * event variants remain canonical full event frames so legacy bridge/RPC behavior
- * and terminal `message_end` reconstruction are unchanged.
+ * event variants remain canonical full event frames so downstream consumers and
+ * terminal `message_end` reconstruction are unchanged.
  */
 export class AgentWireCompactEventEncoder {
 	readonly #sequencer: AgentWireFrameSequencer;
@@ -206,18 +201,15 @@ export function toAgentWireCompactEventFrame(
 	return encoder.frame(event);
 }
 
-/** Back-compat alias for {@link toAgentWireEventFrame}. */
-export const toBridgeEventFrame = toAgentWireEventFrame;
-
 /**
  * Serialize a `workflow_gate` event into a sequenced wire frame (#321). The
  * gate_id is stamped as the correlation id so the answer (posted to the
  * ui-responses endpoint) can be matched, and the monotonic `seq` gives replay
  * while `frame_id` + gate_id give idempotency.
  */
-export function toBridgeWorkflowGateFrame(
-	gate: import("../../rpc/rpc-types").RpcWorkflowGate,
+export function toAgentWireWorkflowGateFrame(
+	gate: import("./workflow-gate-types").WorkflowGate,
 	sequencer: AgentWireFrameSequencer,
-): import("./protocol").BridgeWorkflowGateFrame {
+): AgentWireFrameEnvelope<"workflow_gate", import("./workflow-gate-types").WorkflowGate> {
 	return sequencer.next("workflow_gate", gate, gate.gate_id);
 }

package/src/modes/shared/agent-wire/event-observation.ts

@@ -197,14 +197,23 @@ export function observeAgentSessionEvent(event: AgentSessionEvent): AgentWireOwn
 				semantic: false,
 				coalesceKey: null,
 			});
-		case "retry_fallback_applied":
-		case "retry_fallback_succeeded":
+		case "model_fallback_switched":
 			return obs(event, {
-				kind: "rpc_retry_fallback",
+				kind: "rpc_model_fallback_switched",
 				signal: null,
-				evidence: { phase: event.type, role: str(event.role) ?? null },
-				severity: "warn",
-				semantic: false,
+				evidence: {
+					eventId: str(event.eventId) ?? null,
+					from: str(event.from) ?? null,
+					to: str(event.to) ?? null,
+					reason: str(event.reason) ?? null,
+					role: str(event.role) ?? null,
+					scope: str(event.scope) ?? null,
+					activeIndex: num(event.activeIndex) ?? null,
+					chainLength: num(event.chainLength) ?? null,
+					attemptsUsed: num(event.attemptsUsed) ?? null,
+				},
+				severity: "info",
+				semantic: true,
 				coalesceKey: null,
 			});
 		case "ttsr_triggered":
@@ -320,7 +329,7 @@ function ownerFrame(
  * frames delegate to {@link observeAgentWireEventPayload}; non-event frames are
  * mapped here so owners never re-parse protocol semantics privately.
  */
-export function observeRpcOutboundFrame(frame: Record<string, unknown>): AgentWireOwnerObservation | null {
+export function observeAgentWireFrame(frame: Record<string, unknown>): AgentWireOwnerObservation | null {
 	const type = str(frame.type);
 	if (!type || type === "ready") return null;