@gajae-code/coding-agent 0.3.2 → 0.4.0

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

@@ -0,0 +1,222 @@
+/**
+ * Deep-interview gate mapping (#316).
+ *
+ * Converts deep-interview `ask`-tool questions into machine-addressable
+ * `workflow_gate` { kind: "question" } events (option set + free-text shape
+ * encoded in `schema`/`options`) and decodes a `workflow_gate_response` answer
+ * 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.
+ */
+import type { RpcJsonSchema } 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)";
+
+export interface AskGateQuestion {
+	id: string;
+	question: string;
+	options: Array<{ label: string }>;
+	multi?: boolean;
+	recommended?: number;
+}
+
+export interface AskGateResult {
+	id: string;
+	question: string;
+	options: string[];
+	multi: boolean;
+	selectedOptions: string[];
+	customInput?: string;
+}
+
+/**
+ * The answer shape an agent returns for a deep-interview question gate.
+ *
+ * `selected` are picked option labels; free text is conveyed by `other: true`
+ * plus `custom`, encoded separately from `selected` so a real option whose label
+ * happens to equal the display sentinel can never collide with the free-text path.
+ */
+export interface DeepInterviewGateAnswer {
+	selected: string[];
+	other?: boolean;
+	custom?: string;
+}
+
+export class DeepInterviewGateError extends Error {
+	constructor(
+		readonly code:
+			| "invalid_answer_shape"
+			| "unknown_option"
+			| "multi_not_allowed"
+			| "missing_custom"
+			| "empty_selection"
+			| "duplicate_selection",
+		message: string,
+	) {
+		super(message);
+		this.name = "DeepInterviewGateError";
+	}
+}
+
+function deepInterviewQuestionState(questionText: string): Record<string, unknown> {
+	const roundMatch = /^Round\s+(\d+)\s+\|\s+([^|]+?)\s+\|\s+Ambiguity:\s*(.+?)\s*$/im.exec(questionText);
+	const state: Record<string, unknown> = {};
+	if (roundMatch) {
+		const round = Number(roundMatch[1]);
+		if (Number.isFinite(round)) state.round = round;
+		const mode = roundMatch[2]?.trim();
+		if (mode) {
+			state.mode = mode;
+			const normalized = mode.toLowerCase();
+			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;
+	}
+	if (/Round\s+0\s+\|\s+Topology confirmation/im.test(questionText)) {
+		state.round = 0;
+		state.mode = "Topology confirmation";
+		state.topology_gate = true;
+	}
+	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: 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, description: "free-text answer; required when `other` is true" },
+		},
+		required: ["selected"],
+		additionalProperties: false,
+		anyOf: [
+			{
+				type: "object",
+				properties: { selected: selectedOnly, other: { const: false } },
+				required: ["selected"],
+				additionalProperties: false,
+			},
+			{
+				type: "object",
+				properties: {
+					selected: selectedWithOther,
+					other: { const: true },
+					custom: { type: "string", minLength: 1 },
+				},
+				required: ["selected", "other", "custom"],
+				additionalProperties: false,
+			},
+		],
+	};
+}
+
+/** Build the `workflow_gate` open-input for one deep-interview question. */
+export function questionToGate(question: AskGateQuestion): OpenGateInput {
+	const labels = question.options.map(o => o.label);
+	const schema = questionAnswerSchema(question, labels);
+	return {
+		stage: "deep-interview",
+		kind: "question",
+		schema,
+		options: question.options.map((o, i) => ({
+			value: o.label,
+			label: o.label,
+			description: i === question.recommended ? "recommended" : undefined,
+		})),
+		context: {
+			title: question.question,
+			prompt: question.question,
+			stage_state: {
+				question_id: question.id,
+				multi: question.multi ?? false,
+				options: labels,
+				other_option: GATE_OTHER_OPTION,
+				...deepInterviewQuestionState(question.question),
+			},
+		},
+	};
+}
+
+function isAnswer(value: unknown): value is DeepInterviewGateAnswer {
+	if (typeof value !== "object" || value === null) return false;
+	const v = value as DeepInterviewGateAnswer;
+	return (
+		Array.isArray(v.selected) &&
+		v.selected.every(s => typeof s === "string") &&
+		(v.other === undefined || typeof v.other === "boolean") &&
+		(v.custom === undefined || typeof v.custom === "string")
+	);
+}
+
+/**
+ * Decode a gate answer into the QuestionResult the interactive path produces.
+ * Selections are de-duplicated (the interactive UI stores them in a Set), and
+ * free text is taken from `other`/`custom`. Throws DeepInterviewGateError on a
+ * semantically invalid answer.
+ */
+export function gateAnswerToResult(question: AskGateQuestion, answer: unknown): AskGateResult {
+	if (!isAnswer(answer)) {
+		throw new DeepInterviewGateError(
+			"invalid_answer_shape",
+			"answer must be { selected: string[]; other?: boolean; custom?: string }",
+		);
+	}
+	const labels = question.options.map(o => o.label);
+	const multi = question.multi ?? false;
+	const valid = new Set(labels);
+	for (const sel of answer.selected) {
+		if (!valid.has(sel)) throw new DeepInterviewGateError("unknown_option", `unknown option: ${sel}`);
+	}
+	// Mirror the interactive UI, which stores selections in a Set (no duplicates).
+	const deduped = [...new Set(answer.selected)];
+	if (deduped.length !== answer.selected.length) {
+		throw new DeepInterviewGateError("duplicate_selection", "selected options must be unique");
+	}
+	const other = answer.other === true;
+	const totalPicks = deduped.length + (other ? 1 : 0);
+	if (totalPicks === 0) {
+		throw new DeepInterviewGateError(
+			"empty_selection",
+			"at least one option (or the free-text other) must be selected",
+		);
+	}
+	if (!multi && totalPicks > 1) {
+		throw new DeepInterviewGateError("multi_not_allowed", "this question accepts a single selection");
+	}
+	if (other && (answer.custom === undefined || answer.custom.trim() === "")) {
+		throw new DeepInterviewGateError("missing_custom", "custom text is required when `other` is true");
+	}
+	return {
+		id: question.id,
+		question: question.question,
+		options: labels,
+		multi,
+		selectedOptions: deduped,
+		customInput: other ? answer.custom : undefined,
+	};
+}
+
+/** Convenience: map a batch of ask questions to gate open-inputs. */
+export function questionsToGates(questions: AskGateQuestion[]): OpenGateInput[] {
+	return questions.map(questionToGate);
+}

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

@@ -106,3 +106,16 @@ export function toBridgeEventFrame(event: AgentSessionEvent, sequencer: BridgeFr
 		event,
 	});
 }
+
+/**
+ * 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,
+	sequencer: BridgeFrameSequencer,
+): import("./protocol").BridgeWorkflowGateFrame {
+	return sequencer.next("workflow_gate", gate, gate.gate_id);
+}

package/src/modes/shared/agent-wire/handshake.ts

@@ -1,3 +1,4 @@
+import type { RpcUnattendedDeclaration } from "../../rpc/rpc-types";
 import { BRIDGE_PROTOCOL_VERSION, type BridgeFrameType } from "./protocol";
 import type { BridgeCommandScope } from "./scopes";
 
@@ -13,7 +14,8 @@ export type BridgeCapability =
 	| "host_uri"
 	| "client_bridge.read_text_file"
 	| "client_bridge.write_text_file"
-	| "client_bridge.create_terminal";
+	| "client_bridge.create_terminal"
+	| "workflow_gate";
 
 export interface BridgeProtocolRange {
 	min: number;
@@ -25,6 +27,8 @@ export interface BridgeHandshakeRequest {
 	capabilities: BridgeCapability[];
 	requested_scopes: BridgeCommandScope[];
 	last_seq?: number;
+	/** Optional unattended declaration (budget + scope + action allowlist) for #318/#319. */
+	unattended?: RpcUnattendedDeclaration;
 }
 
 export interface BridgeEndpointDescriptor {
@@ -46,6 +50,10 @@ export interface BridgeHandshakeAccepted {
 	unsupported: BridgeCapability[];
 	endpoints: BridgeEndpointDescriptor;
 	frame_types: BridgeFrameType[];
+	/** Echoed unattended declaration when one was supplied and accepted (#321). */
+	accepted_unattended?: RpcUnattendedDeclaration;
+	/** Server-side accepted unattended mode after live negotiation, not just declaration echo. */
+	unattended_active?: boolean;
 }
 
 export interface BridgeHandshakeRejected {
@@ -55,6 +63,29 @@ export interface BridgeHandshakeRejected {
 }
 
 export type BridgeHandshakeResponse = BridgeHandshakeAccepted | BridgeHandshakeRejected;
+
+/** Shape-validate an optional unattended declaration carried on the handshake. */
+export function isUnattendedDeclarationShape(value: unknown): value is RpcUnattendedDeclaration {
+	if (!value || typeof value !== "object") return false;
+	const d = value as Record<string, unknown>;
+	const b = d.budget as Record<string, unknown> | undefined;
+	const budgetOk =
+		!!b &&
+		typeof b === "object" &&
+		// Match UnattendedRunController fail-closed validation: positive finite budgets.
+		["max_tokens", "max_tool_calls", "max_wall_time_ms", "max_cost_usd"].every(
+			k => typeof b[k] === "number" && Number.isFinite(b[k] as number) && (b[k] as number) > 0,
+		);
+	return (
+		typeof d.actor === "string" &&
+		d.actor.trim() !== "" &&
+		budgetOk &&
+		Array.isArray(d.scopes) &&
+		d.scopes.every(s => typeof s === "string") &&
+		Array.isArray(d.action_allowlist) &&
+		d.action_allowlist.every(s => typeof s === "string")
+	);
+}
 export function isBridgeHandshakeRequest(value: unknown): value is BridgeHandshakeRequest {
 	if (!value || typeof value !== "object") return false;
 	const request = value as {
@@ -62,6 +93,7 @@ export function isBridgeHandshakeRequest(value: unknown): value is BridgeHandsha
 		capabilities?: unknown;
 		requested_scopes?: unknown;
 		last_seq?: unknown;
+		unattended?: unknown;
 	};
 	const range = request.protocol_version_range as { min?: unknown; max?: unknown } | undefined;
 	return (
@@ -74,7 +106,9 @@ export function isBridgeHandshakeRequest(value: unknown): value is BridgeHandsha
 		request.capabilities.every(capability => typeof capability === "string") &&
 		Array.isArray(request.requested_scopes) &&
 		request.requested_scopes.every(scope => typeof scope === "string") &&
-		(request.last_seq === undefined || (typeof request.last_seq === "number" && Number.isInteger(request.last_seq)))
+		(request.last_seq === undefined ||
+			(typeof request.last_seq === "number" && Number.isInteger(request.last_seq))) &&
+		(request.unattended === undefined || isUnattendedDeclarationShape(request.unattended))
 	);
 }
 
@@ -86,6 +120,7 @@ export function negotiateBridgeHandshake(
 		scopes: readonly BridgeCommandScope[];
 		endpoints: BridgeEndpointDescriptor;
 		frameTypes: readonly BridgeFrameType[];
+		acceptedUnattended?: RpcUnattendedDeclaration;
 	},
 ): BridgeHandshakeResponse {
 	if (
@@ -104,7 +139,7 @@ export function negotiateBridgeHandshake(
 	const unsupported = request.capabilities.filter(capability => !acceptedSet.has(capability));
 	const serverScopes = new Set(server.scopes);
 	const acceptedScopes = request.requested_scopes.filter(scope => serverScopes.has(scope));
-	return {
+	const accepted: BridgeHandshakeAccepted = {
 		status: "accepted",
 		protocol_version: BRIDGE_PROTOCOL_VERSION,
 		session_id: server.sessionId,
@@ -114,4 +149,9 @@ export function negotiateBridgeHandshake(
 		endpoints: server.endpoints,
 		frame_types: [...server.frameTypes],
 	};
+	if (server.acceptedUnattended !== undefined && acceptedSet.has("workflow_gate")) {
+		accepted.accepted_unattended = server.acceptedUnattended;
+		accepted.unattended_active = true;
+	}
+	return accepted;
 }

package/src/modes/shared/agent-wire/protocol.ts

@@ -64,6 +64,7 @@ export type BridgeFrameType =
 	| "host_tool_call"
 	| "host_uri_request"
 	| "reset"
+	| "workflow_gate"
 	| "error";
 
 /**
@@ -94,3 +95,9 @@ export interface BridgeEventPayload {
 
 /** An `AgentSessionEvent` serialized into a versioned wire frame. */
 export type BridgeEventFrame = BridgeFrameEnvelope<"event", BridgeEventPayload>;
+
+/** A `workflow_gate` event serialized into a versioned wire frame (#321). */
+export type BridgeWorkflowGateFrame = BridgeFrameEnvelope<
+	"workflow_gate",
+	import("../../rpc/rpc-types").RpcWorkflowGate
+>;

package/src/modes/shared/agent-wire/responses.ts

@@ -12,6 +12,6 @@ export function rpcSuccess<T extends RpcCommand["type"]>(
 	return { id, type: "response", command, success: true, data } as RpcResponse;
 }
 
-export function rpcError(id: string | undefined, command: string, message: string): RpcResponse {
-	return { id, type: "response", command, success: false, error: message };
+export function rpcError(id: string | undefined, command: string, error: string | object): RpcResponse {
+	return { id, type: "response", command, success: false, error } as RpcResponse;
 }

package/src/modes/shared/agent-wire/scopes.ts

@@ -71,6 +71,8 @@ const RPC_COMMAND_SCOPE_REGISTRY: Record<RpcCommandType, BridgeCommandScope> = {
 	get_messages: "message:read",
 	get_login_providers: "admin",
 	login: "admin",
+	negotiate_unattended: "control",
+	workflow_gate_response: "prompt",
 };
 
 export const RPC_COMMAND_TYPES: readonly RpcCommandType[] = Object.keys(RPC_COMMAND_SCOPE_REGISTRY) as RpcCommandType[];