@gajae-code/coding-agent 0.3.2 → 0.4.1

package/src/modes/rpc/rpc-types.ts

@@ -72,7 +72,13 @@ export type RpcCommand =
 
 	// Login
 	| { id?: string; type: "get_login_providers" }
-	| { id?: string; type: "login"; providerId: string };
+	| { id?: string; type: "login"; providerId: string }
+
+	// Unattended control plane (#318/#319 declaration handled here at #315 contract level)
+	| { id?: string; type: "negotiate_unattended"; declaration: RpcUnattendedDeclaration }
+
+	// Workflow gate answer (inbound response to a workflow_gate event)
+	| ({ id?: string; type: "workflow_gate_response" } & RpcWorkflowGateResponse);
 
 // ============================================================================
 // RPC State
@@ -209,8 +215,18 @@ export type RpcResponse =
 	  }
 	| { id?: string; type: "response"; command: "login"; success: true; data: { providerId: string } }
 
+	// Unattended + workflow gates
+	| { id?: string; type: "response"; command: "negotiate_unattended"; success: true; data: RpcUnattendedAccepted }
+	| {
+			id?: string;
+			type: "response";
+			command: "workflow_gate_response";
+			success: true;
+			data: RpcWorkflowGateResolution;
+	  }
+
 	// Error response (any command can fail)
-	| { id?: string; type: "response"; command: string; success: false; error: string };
+	| { id?: string; type: "response"; command: string; success: false; error: string | object };
 
 // ============================================================================
 // Extension UI Events (stdout)
@@ -376,3 +392,209 @@ export type RpcExtensionUIResponse =
 // ============================================================================
 
 export type RpcCommandType = RpcCommand["type"];
+
+// ============================================================================
+// Workflow Gate Contract (#315)
+// ============================================================================
+
+/**
+ * Lifecycle stages that emit machine-addressable gates. v1 is single-agent;
+ * `team` parallel execution over RPC is deferred, so it is intentionally absent
+ * from this union. Gate construction rejects any other stage value.
+ */
+export type RpcWorkflowStage = "deep-interview" | "ralplan" | "ultragoal";
+
+/** Reserved stage names that are explicitly not part of the v1 contract. */
+export const RESERVED_WORKFLOW_STAGES: readonly string[] = ["team"];
+
+export type RpcWorkflowGateKind = "question" | "approval" | "execution";
+
+/**
+ * The documented JSON Schema 2020-12 subset supported by the gate validator.
+ * Schemas containing any keyword outside this shape are rejected at gate
+ * construction time so the server never advertises a schema it cannot validate.
+ */
+export interface RpcJsonSchema {
+	type?: "string" | "number" | "integer" | "boolean" | "object" | "array" | "null";
+	enum?: unknown[];
+	const?: unknown;
+	properties?: Record<string, RpcJsonSchema>;
+	required?: string[];
+	additionalProperties?: boolean | RpcJsonSchema;
+	items?: RpcJsonSchema;
+	minLength?: number;
+	maxLength?: number;
+	minItems?: number;
+	maxItems?: number;
+	uniqueItems?: boolean;
+	minimum?: number;
+	maximum?: number;
+	title?: string;
+	description?: string;
+	oneOf?: RpcJsonSchema[];
+	anyOf?: RpcJsonSchema[];
+}
+
+export interface RpcWorkflowGateOption {
+	value: unknown;
+	label: string;
+	description?: string;
+}
+
+export interface RpcWorkflowGateContext {
+	title?: string;
+	prompt?: string;
+	summary?: string;
+	stage_state?: Record<string, unknown>;
+	artifact_refs?: Array<{ kind: string; path?: string; sha256?: string }>;
+	language?: string;
+}
+
+/** Outbound event: a machine-addressable workflow gate awaiting an answer. */
+export interface RpcWorkflowGate {
+	type: "workflow_gate";
+	/** Run-scoped, monotonic, stable id (e.g. `wg_<run>_<stage>_000001`). */
+	gate_id: string;
+	stage: RpcWorkflowStage;
+	kind: RpcWorkflowGateKind;
+	schema: RpcJsonSchema;
+	/** Canonical hash of `schema`; advertised hash must equal server validation hash. */
+	schema_hash: string;
+	options?: RpcWorkflowGateOption[];
+	context: RpcWorkflowGateContext;
+	created_at: string;
+	required: true;
+}
+
+/** Inbound: the agent's answer to a workflow gate. */
+export interface RpcWorkflowGateResponse {
+	gate_id: string;
+	answer: unknown;
+	/** Optional idempotency key; same key + body returns the cached resolution. */
+	idempotency_key?: string;
+}
+
+/** Outcome of resolving a gate, surfaced back to the answering client. */
+export interface RpcWorkflowGateResolution {
+	gate_id: string;
+	status: "accepted" | "rejected";
+	answer_hash: string;
+	resolved_at: string;
+	/** Present only when `status === "rejected"`. */
+	error?: RpcWorkflowGateValidationError;
+}
+
+/** Typed error shape for schema validation failures (#315 acceptance). */
+export interface RpcWorkflowGateValidationError {
+	code: "invalid_workflow_gate_answer";
+	gate_id: string;
+	schema_hash: string;
+	errors: Array<{ path: string; keyword: string; message: string; expected?: unknown }>;
+}
+
+// ============================================================================
+// Unattended Declaration Contract (#318/#319 — declared at #315 boundary)
+// ============================================================================
+
+export interface RpcUnattendedBudget {
+	max_tokens: number;
+	max_tool_calls: number;
+	max_wall_time_ms: number;
+	max_cost_usd: number;
+}
+
+export interface RpcUnattendedDeclaration {
+	/** Identity of the operating external agent, recorded in the audit trail. */
+	actor: string;
+	budget: RpcUnattendedBudget;
+	/** Coarse command scopes the agent may use (maps to BridgeCommandScope). */
+	scopes: string[];
+	/** Action classes the agent is allowed to perform (default-deny otherwise). */
+	action_allowlist: string[];
+}
+
+export interface RpcUnattendedAccepted {
+	run_id: string;
+	actor: string;
+	budget: RpcUnattendedBudget;
+	scopes: string[];
+	action_allowlist: string[];
+	accepted_at: string;
+}
+
+export type RpcBudgetMetric = "tokens" | "tool_calls" | "wall_time" | "cost";
+
+/** Typed payload emitted when a declared budget cap is breached (#318). */
+export interface RpcBudgetExceeded {
+	code: "budget_exceeded";
+	metric: RpcBudgetMetric;
+	limit: number;
+	observed: number;
+	/** The accounting phase that detected the breach. */
+	phase: string;
+	run_id: string;
+	session_id?: string;
+	/** `aborting` = breach detected, async abort initiated; settled status follows in audit. */
+	abort_status: "aborting" | "aborted" | "abort_failed";
+}
+
+export type RpcUnattendedRefusalCode =
+	| "unattended_not_negotiated"
+	| "incomplete_budget"
+	| "unsupported_budget_metric"
+	| "invalid_unattended_declaration"
+	| "unattended_aborted";
+
+/** Typed refusal emitted when unattended mode cannot start or continue (fail-closed). */
+export interface RpcUnattendedRefused {
+	code: RpcUnattendedRefusalCode;
+	message: string;
+}
+
+// ============================================================================
+// Unattended Action Authorization Contract (#319)
+// ============================================================================
+
+/** v1 action taxonomy: every authorized operation maps to one of these classes. */
+export type RpcUnattendedActionClass =
+	| "command.prompt"
+	| "command.control"
+	| "command.bash"
+	| "command.export"
+	| "command.session"
+	| "command.model"
+	| "command.message_read"
+	| "command.host_tools"
+	| "command.host_uri"
+	| "command.admin"
+	| "bash.readonly"
+	| "bash.mutating"
+	| "bash.destructive"
+	| "git.force_push"
+	| "file.delete"
+	| "file.write"
+	| "host_tool.invoke"
+	| "host_uri.read"
+	| "host_uri.write"
+	| "auth.login";
+
+/** Typed error when a command's coarse scope is not in the declared allowlist. */
+export interface RpcScopeDenied {
+	code: "scope_denied";
+	scope: string;
+	command?: string;
+	run_id: string;
+	session_id?: string;
+	/** Always true: enforcement happens before the side effect runs. */
+	pre_side_effect: true;
+}
+
+/** Typed error when an action class is not in the declared allowlist (default-deny). */
+export interface RpcActionDenied {
+	code: "action_denied";
+	action: string;
+	command?: string;
+	run_id: string;
+	session_id?: string;
+	pre_side_effect: true;
+}

package/src/modes/shared/agent-wire/approval-gate.ts

@@ -0,0 +1,151 @@
+/**
+ * Ralplan approval + ultragoal execution gate mapping (#317).
+ *
+ * Maps the two human-gated lifecycle decisions onto `workflow_gate` events:
+ *  - ralplan `pending approval` -> `workflow_gate` { kind: "approval" } whose
+ *    answer is one of approve / request-changes / reject (+ optional comments);
+ *  - ultragoal execution sign-off -> `workflow_gate` { kind: "execution" } whose
+ *    answer is approve / decline (+ optional reason).
+ *
+ * Gates remain mandatory; the external agent substitutes for the human at the
+ * answer boundary only. Declining / requesting changes is honored and is NEVER
+ * silently treated as approval.
+ *
+ * This is the pure mapping primitive; routing ralplan/ultragoal through it when
+ * an unattended controller + gate broker are attached is wired with the transport
+ * in #321 and exercised end-to-end by #323.
+ */
+import type { RpcJsonSchema, RpcWorkflowGateContext } from "../../rpc/rpc-types";
+import type { OpenGateInput } from "./workflow-gate-broker";
+
+export type ApprovalDecision = "approve" | "request-changes" | "reject";
+export type ExecutionDecision = "approve" | "decline";
+
+export interface ApprovalGateAnswer {
+	decision: ApprovalDecision;
+	comments?: string;
+}
+
+export interface ExecutionGateAnswer {
+	decision: ExecutionDecision;
+	reason?: string;
+}
+
+export interface ApprovalGateResult {
+	approved: boolean;
+	decision: ApprovalDecision;
+	comments?: string;
+}
+
+export interface ExecutionGateResult {
+	approved: boolean;
+	decision: ExecutionDecision;
+	reason?: string;
+}
+
+export class ApprovalGateError extends Error {
+	constructor(
+		readonly code: "invalid_answer_shape" | "unknown_decision" | "missing_comments",
+		message: string,
+	) {
+		super(message);
+		this.name = "ApprovalGateError";
+	}
+}
+
+const APPROVAL_DECISIONS: ApprovalDecision[] = ["approve", "request-changes", "reject"];
+const EXECUTION_DECISIONS: ExecutionDecision[] = ["approve", "decline"];
+
+/** Build the ralplan `pending approval` -> `workflow_gate { kind: "approval" }` open-input. */
+export function approvalGate(context: RpcWorkflowGateContext = {}): OpenGateInput {
+	const schema: RpcJsonSchema = {
+		type: "object",
+		properties: {
+			decision: { type: "string", enum: APPROVAL_DECISIONS },
+			comments: { type: "string", description: "required when requesting changes" },
+		},
+		required: ["decision"],
+		additionalProperties: false,
+	};
+	return {
+		stage: "ralplan",
+		kind: "approval",
+		schema,
+		options: APPROVAL_DECISIONS.map(d => ({ value: d, label: d })),
+		context: { title: context.title ?? "Approve the plan?", ...context },
+	};
+}
+
+/** Build the ultragoal execution sign-off -> `workflow_gate { kind: "execution" }` open-input. */
+export function executionGate(context: RpcWorkflowGateContext = {}): OpenGateInput {
+	const schema: RpcJsonSchema = {
+		type: "object",
+		properties: {
+			decision: { type: "string", enum: EXECUTION_DECISIONS },
+			reason: { type: "string", description: "optional rationale; required when declining" },
+		},
+		required: ["decision"],
+		additionalProperties: false,
+	};
+	return {
+		stage: "ultragoal",
+		kind: "execution",
+		schema,
+		options: EXECUTION_DECISIONS.map(d => ({ value: d, label: d })),
+		context: { title: context.title ?? "Approve execution?", ...context },
+	};
+}
+
+function decisionField(answer: unknown): string {
+	if (typeof answer !== "object" || answer === null) {
+		throw new ApprovalGateError("invalid_answer_shape", "answer must be an object with a `decision` field");
+	}
+	const decision = (answer as { decision?: unknown }).decision;
+	if (typeof decision !== "string") {
+		throw new ApprovalGateError("invalid_answer_shape", "answer.decision must be a string");
+	}
+	return decision;
+}
+
+/**
+ * Decode a ralplan approval answer. `request-changes` requires comments and is
+ * NEVER treated as approval; only an explicit `approve` advances.
+ */
+export function decodeApproval(answer: unknown): ApprovalGateResult {
+	const decision = decisionField(answer);
+	if (!APPROVAL_DECISIONS.includes(decision as ApprovalDecision)) {
+		throw new ApprovalGateError("unknown_decision", `unknown approval decision: ${decision}`);
+	}
+	const comments = (answer as { comments?: unknown }).comments;
+	if (comments !== undefined && typeof comments !== "string") {
+		throw new ApprovalGateError("invalid_answer_shape", "answer.comments must be a string");
+	}
+	if (decision === "request-changes" && (comments === undefined || comments.trim() === "")) {
+		throw new ApprovalGateError("missing_comments", "comments are required when requesting changes");
+	}
+	return {
+		approved: decision === "approve",
+		decision: decision as ApprovalDecision,
+		comments: comments as string | undefined,
+	};
+}
+
+/**
+ * Decode an ultragoal execution answer. Only an explicit `approve` advances;
+ * `decline` is honored and never silently approved.
+ */
+export function decodeExecution(answer: unknown): ExecutionGateResult {
+	const decision = decisionField(answer);
+	if (!EXECUTION_DECISIONS.includes(decision as ExecutionDecision)) {
+		throw new ApprovalGateError("unknown_decision", `unknown execution decision: ${decision}`);
+	}
+	const reason = (answer as { reason?: unknown }).reason;
+	if (reason !== undefined && typeof reason !== "string") {
+		throw new ApprovalGateError("invalid_answer_shape", "answer.reason must be a string");
+	}
+	return {
+		approved: decision === "approve",
+		decision: decision as ExecutionDecision,
+		reason: reason as string | undefined,
+	};
+}

package/src/modes/shared/agent-wire/command-dispatch.ts

@@ -10,8 +10,19 @@ import type {
 	RpcHostUriSchemeDefinition,
 	RpcResponse,
 	RpcSessionState,
+	RpcUnattendedAccepted,
+	RpcUnattendedDeclaration,
+	RpcWorkflowGateResolution,
+	RpcWorkflowGateResponse,
 } from "../../rpc/rpc-types";
 import { rpcError, rpcSuccess } from "./responses";
+import {
+	ActionDeniedError,
+	ScopeDeniedError,
+	UnattendedBudgetExceededError,
+	UnattendedNegotiationError,
+} from "./unattended-run-controller";
+import { WorkflowGateBrokerError } from "./workflow-gate-broker";
 
 export type RpcCommandDispatchOutput = (obj: RpcResponse | RpcExtensionUIRequest | object) => void;
 
@@ -23,12 +34,28 @@ export interface RpcHostUriRegistry {
 	setSchemes(schemes: RpcHostUriSchemeDefinition[]): string[];
 }
 
+/**
+ * Optional unattended control plane wired into RPC dispatch (#318/#319/#323).
+ * When present, `negotiate_unattended` and `workflow_gate_response` route here
+ * instead of falling through to the unknown-command path.
+ */
+export interface RpcUnattendedControlPlane {
+	/** Enter unattended mode (fail-closed); throws an Error on refusal. */
+	negotiate(declaration: RpcUnattendedDeclaration): RpcUnattendedAccepted;
+	/** Resolve a pending workflow gate with the agent's answer. */
+	resolveGate(response: RpcWorkflowGateResponse): Promise<RpcWorkflowGateResolution>;
+	isUnattended?(): boolean;
+	preflightCommand?(command: RpcCommand): void;
+	reconcileUsage?(phase?: string): void;
+}
+
 export interface RpcCommandDispatchContext {
 	session: AgentSession;
 	output: RpcCommandDispatchOutput;
 	hostToolRegistry: RpcHostToolRegistry;
 	hostUriRegistry: RpcHostUriRegistry;
 	createUiContext: () => Pick<ExtensionUIContext, "notify">;
+	unattendedControlPlane?: RpcUnattendedControlPlane;
 }
 
 export function normalizeHostToolDefinitions(tools: RpcHostToolDefinition[]): RpcHostToolDefinition[] {
@@ -55,12 +82,50 @@ export function normalizeHostToolDefinitions(tools: RpcHostToolDefinition[]): Rp
 	});
 }
 
+function serializeRpcDispatchError(err: unknown): string | object {
+	if (
+		err instanceof ScopeDeniedError ||
+		err instanceof ActionDeniedError ||
+		err instanceof UnattendedBudgetExceededError
+	) {
+		return err.payload;
+	}
+	if (err instanceof UnattendedNegotiationError) {
+		return { code: err.code, message: err.message };
+	}
+	if (err instanceof WorkflowGateBrokerError) {
+		return { code: err.code, message: err.message };
+	}
+	return err instanceof Error ? err.message : String(err);
+}
+
 export async function dispatchRpcCommand(
 	command: RpcCommand,
 	context: RpcCommandDispatchContext,
 ): Promise<RpcResponse> {
-	const { session, output, hostToolRegistry, hostUriRegistry, createUiContext } = context;
+	const { session, output, hostToolRegistry, hostUriRegistry, createUiContext, unattendedControlPlane } = context;
 	const id = command.id;
+	const typedError = (cmd: string, err: unknown): RpcResponse => rpcError(id, cmd, serializeRpcDispatchError(err));
+	const preflight = (): RpcResponse | undefined => {
+		if (!unattendedControlPlane?.isUnattended?.() || command.type === "negotiate_unattended") return undefined;
+		try {
+			unattendedControlPlane.preflightCommand?.(command);
+			return undefined;
+		} catch (err) {
+			return typedError(command.type, err);
+		}
+	};
+	const reconcile = (phase = `${command.type} post-dispatch`): RpcResponse | undefined => {
+		if (!unattendedControlPlane?.isUnattended?.()) return undefined;
+		try {
+			unattendedControlPlane.reconcileUsage?.(phase);
+			return undefined;
+		} catch (err) {
+			return typedError(command.type, err);
+		}
+	};
+	const denied = preflight();
+	if (denied) return denied;
 
 	switch (command.type) {
 		case "prompt": {
@@ -69,8 +134,8 @@ export async function dispatchRpcCommand(
 					images: command.images,
 					streamingBehavior: command.streamingBehavior,
 				})
-				.catch(e => output(rpcError(id, "prompt", e.message)));
-			return rpcSuccess(id, "prompt");
+				.catch(e => output(rpcError(id, "prompt", serializeRpcDispatchError(e))));
+			return reconcile() ?? rpcSuccess(id, "prompt");
 		}
 
 		case "steer": {
@@ -223,7 +288,7 @@ export async function dispatchRpcCommand(
 
 		case "bash": {
 			const result = await session.executeBash(command.command);
-			return rpcSuccess(id, "bash", result);
+			return reconcile() ?? rpcSuccess(id, "bash", result);
 		}
 
 		case "abort_bash": {
@@ -333,6 +398,34 @@ export async function dispatchRpcCommand(
 			}
 		}
 
+		case "negotiate_unattended": {
+			if (!unattendedControlPlane) {
+				return rpcError(id, "negotiate_unattended", "unattended mode is not available on this session");
+			}
+			try {
+				const accepted = unattendedControlPlane.negotiate(command.declaration);
+				return rpcSuccess(id, "negotiate_unattended", accepted);
+			} catch (err) {
+				return typedError("negotiate_unattended", err);
+			}
+		}
+
+		case "workflow_gate_response": {
+			if (!unattendedControlPlane) {
+				return rpcError(id, "workflow_gate_response", "workflow gates are not available on this session");
+			}
+			try {
+				const resolution = await unattendedControlPlane.resolveGate({
+					gate_id: command.gate_id,
+					answer: command.answer,
+					idempotency_key: command.idempotency_key,
+				});
+				return rpcSuccess(id, "workflow_gate_response", resolution);
+			} catch (err) {
+				return typedError("workflow_gate_response", err);
+			}
+		}
+
 		default: {
 			const unknownCommand = command as { type: string };
 			return rpcError(undefined, unknownCommand.type, `Unknown command: ${unknownCommand.type}`);

package/src/modes/shared/agent-wire/command-validation.ts

@@ -17,7 +17,7 @@ function stringField(value: Record<string, unknown>, key: string): boolean {
 	return typeof value[key] === "string";
 }
 
-const THINKING_LEVELS = new Set(["inherit", "off", "minimal", "low", "medium", "high", "xhigh"]);
+const THINKING_LEVELS = new Set(["inherit", "off", "minimal", "low", "medium", "high", "xhigh", "max"]);
 const TODO_STATUSES = new Set(["pending", "in_progress", "completed", "abandoned"]);
 
 function optionalBoolean(value: unknown): boolean {
@@ -61,6 +61,26 @@ function hostUriScheme(value: unknown): boolean {
 	);
 }
 
+function unattendedBudget(value: unknown): boolean {
+	return (
+		isRecord(value) &&
+		typeof value.max_tokens === "number" &&
+		typeof value.max_tool_calls === "number" &&
+		typeof value.max_wall_time_ms === "number" &&
+		typeof value.max_cost_usd === "number"
+	);
+}
+
+function unattendedDeclaration(value: unknown): boolean {
+	return (
+		isRecord(value) &&
+		typeof value.actor === "string" &&
+		unattendedBudget(value.budget) &&
+		stringArray(value.scopes) &&
+		stringArray(value.action_allowlist)
+	);
+}
+
 export function isRpcCommand(value: unknown): value is RpcCommand {
 	if (!isRecord(value) || !optionalString(value.id) || !isRpcCommandType(value.type)) return false;
 	switch (value.type) {
@@ -127,5 +147,9 @@ export function isRpcCommand(value: unknown): value is RpcCommand {
 			return optionalString(value.customInstructions);
 		case "login":
 			return stringField(value, "providerId");
+		case "negotiate_unattended":
+			return unattendedDeclaration(value.declaration);
+		case "workflow_gate_response":
+			return stringField(value, "gate_id") && "answer" in value && optionalString(value.idempotency_key);
 	}
 }