@gajae-code/coding-agent 0.3.2 → 0.4.1

package/src/modes/shared/agent-wire/unattended-run-controller.ts

@@ -0,0 +1,406 @@
+/**
+ * Unattended run controller (#318).
+ *
+ * The single required owner of negotiated unattended state. Entering unattended
+ * mode is fail-closed: a controller can only be created via {@link
+ * UnattendedRunController.negotiate}, which rejects a missing/partial budget, an
+ * invalid declaration, or a provider that cannot account for tokens/cost.
+ *
+ * The controller owns budget accounting across metrics and phases. Scope/action
+ * authorization (#319) and the durable audit trail (#320) layer onto the same
+ * controller; this slice wires the budget floor and abort coordination.
+ *
+ * Attended mode never constructs a controller, so by construction the attended
+ * path is unaffected by everything here.
+ */
+import type {
+	RpcActionDenied,
+	RpcBudgetExceeded,
+	RpcBudgetMetric,
+	RpcScopeDenied,
+	RpcUnattendedActionClass,
+	RpcUnattendedBudget,
+	RpcUnattendedDeclaration,
+	RpcUnattendedRefusalCode,
+} from "../../rpc/rpc-types";
+import type { BridgeCommandScope } from "./scopes";
+import { actionClassForScope, classifyBashAction } from "./unattended-action-policy";
+
+/** Coordinated abort surfaces invoked exactly once on a budget breach / abort. */
+export interface UnattendedAbortHooks {
+	abortModelStream?(): void | Promise<void>;
+	abortBash?(): void | Promise<void>;
+	cancelHostTools?(reason: string): void | Promise<void>;
+	cancelHostUris?(reason: string): void | Promise<void>;
+	stopWorkflow?(reason: string): void | Promise<void>;
+}
+
+export type UnattendedAuditEvent =
+	| { event: "unattended_negotiated"; run_id: string; actor: string }
+	| { event: "budget_exceeded"; payload: RpcBudgetExceeded }
+	| { event: "unattended_aborted"; run_id: string; reason: string }
+	| { event: "unattended_abort_settled"; run_id: string; status: "aborted" | "abort_failed"; failures: number }
+	| { event: "scope_denied"; payload: RpcScopeDenied }
+	| { event: "action_denied"; payload: RpcActionDenied };
+
+export interface NegotiateContext {
+	runId: string;
+	sessionId?: string;
+	audit?(event: UnattendedAuditEvent): void;
+	abortHooks?: UnattendedAbortHooks;
+	/**
+	 * Whether the active provider can report token usage and cost. Unattended
+	 * mode rejects providers without this accounting up front (fail-closed).
+	 */
+	providerSupportsTokenCostMetrics?: boolean;
+	/** Injectable clock for deterministic tests. Defaults to Date.now. */
+	now?(): number;
+}
+
+export class UnattendedNegotiationError extends Error {
+	constructor(
+		readonly code: RpcUnattendedRefusalCode,
+		message: string,
+	) {
+		super(message);
+		this.name = "UnattendedNegotiationError";
+	}
+}
+
+export class UnattendedBudgetExceededError extends Error {
+	constructor(readonly payload: RpcBudgetExceeded) {
+		super(`budget_exceeded: ${payload.metric} ${payload.observed}/${payload.limit} at ${payload.phase}`);
+		this.name = "UnattendedBudgetExceededError";
+	}
+}
+
+/** Thrown when a provider/tool reports a non-finite usage value (fail-closed). */
+export class UnattendedAccountingError extends Error {
+	constructor(
+		readonly metric: RpcBudgetMetric,
+		readonly phase: string,
+		value: unknown,
+	) {
+		super(`non-finite ${metric} usage (${String(value)}) at ${phase}`);
+		this.name = "UnattendedAccountingError";
+	}
+}
+
+/** Thrown when a command's coarse scope is outside the declared allowlist (#319). */
+export class ScopeDeniedError extends Error {
+	constructor(readonly payload: RpcScopeDenied) {
+		super(`scope_denied: ${payload.scope}${payload.command ? ` (${payload.command})` : ""}`);
+		this.name = "ScopeDeniedError";
+	}
+}
+
+/** Thrown when an action class is outside the declared allowlist (default-deny, #319). */
+export class ActionDeniedError extends Error {
+	constructor(readonly payload: RpcActionDenied) {
+		super(`action_denied: ${payload.action}${payload.command ? ` (${payload.command})` : ""}`);
+		this.name = "ActionDeniedError";
+	}
+}
+
+interface Usage {
+	tokens: number;
+	toolCalls: number;
+	costUsd: number;
+}
+
+function isPositiveFiniteNumber(v: unknown): v is number {
+	return typeof v === "number" && Number.isFinite(v) && v > 0;
+}
+
+function validateBudget(budget: unknown): RpcUnattendedBudget {
+	if (typeof budget !== "object" || budget === null) {
+		throw new UnattendedNegotiationError("incomplete_budget", "budget declaration is required for unattended mode");
+	}
+	const b = budget as Record<string, unknown>;
+	const fields: Array<keyof RpcUnattendedBudget> = [
+		"max_tokens",
+		"max_tool_calls",
+		"max_wall_time_ms",
+		"max_cost_usd",
+	];
+	for (const f of fields) {
+		if (!isPositiveFiniteNumber(b[f])) {
+			throw new UnattendedNegotiationError("incomplete_budget", `budget.${f} must be a positive finite number`);
+		}
+	}
+	return {
+		max_tokens: b.max_tokens as number,
+		max_tool_calls: b.max_tool_calls as number,
+		max_wall_time_ms: b.max_wall_time_ms as number,
+		max_cost_usd: b.max_cost_usd as number,
+	};
+}
+
+export class UnattendedRunController {
+	readonly runId: string;
+	readonly sessionId?: string;
+	readonly actor: string;
+	readonly budget: RpcUnattendedBudget;
+	readonly scopes: ReadonlySet<string>;
+	readonly actionAllowlist: ReadonlySet<string>;
+
+	private readonly usage: Usage = { tokens: 0, toolCalls: 0, costUsd: 0 };
+	private readonly startedAt: number;
+	private readonly now: () => number;
+	private readonly audit?: (event: UnattendedAuditEvent) => void;
+	private readonly abortHooks: UnattendedAbortHooks;
+	private aborted = false;
+	private abortPromise?: Promise<void>;
+
+	private constructor(declaration: RpcUnattendedDeclaration, ctx: NegotiateContext, budget: RpcUnattendedBudget) {
+		this.runId = ctx.runId;
+		this.sessionId = ctx.sessionId;
+		this.actor = declaration.actor;
+		this.budget = budget;
+		this.scopes = new Set(declaration.scopes);
+		this.actionAllowlist = new Set(declaration.action_allowlist);
+		this.now = ctx.now ?? Date.now;
+		this.audit = ctx.audit;
+		this.abortHooks = ctx.abortHooks ?? {};
+		this.startedAt = this.now();
+	}
+
+	/** Fail-closed entry: validate the declaration + budget, or throw. */
+	static negotiate(declaration: unknown, ctx: NegotiateContext): UnattendedRunController {
+		if (typeof declaration !== "object" || declaration === null) {
+			throw new UnattendedNegotiationError("invalid_unattended_declaration", "declaration is required");
+		}
+		const d = declaration as Record<string, unknown>;
+		if (typeof d.actor !== "string" || d.actor.trim() === "") {
+			throw new UnattendedNegotiationError("invalid_unattended_declaration", "declaration.actor is required");
+		}
+		if (!Array.isArray(d.scopes) || !d.scopes.every(s => typeof s === "string")) {
+			throw new UnattendedNegotiationError("invalid_unattended_declaration", "declaration.scopes must be string[]");
+		}
+		if (!Array.isArray(d.action_allowlist) || !d.action_allowlist.every(s => typeof s === "string")) {
+			throw new UnattendedNegotiationError(
+				"invalid_unattended_declaration",
+				"declaration.action_allowlist must be string[]",
+			);
+		}
+		const budget = validateBudget(d.budget);
+		// Reject providers that cannot account for tokens/cost (fail-closed): require
+		// an explicit positive capability signal — omitted/unknown is refused too.
+		if (ctx.providerSupportsTokenCostMetrics !== true) {
+			throw new UnattendedNegotiationError(
+				"unsupported_budget_metric",
+				"unattended mode requires an explicit provider token/cost accounting capability",
+			);
+		}
+		const controller = new UnattendedRunController(d as unknown as RpcUnattendedDeclaration, ctx, budget);
+		ctx.audit?.({ event: "unattended_negotiated", run_id: ctx.runId, actor: controller.actor });
+		return controller;
+	}
+
+	get isAborted(): boolean {
+		return this.aborted;
+	}
+
+	usageSnapshot(): Readonly<Usage> & { wallTimeMs: number } {
+		return { ...this.usage, wallTimeMs: this.now() - this.startedAt };
+	}
+
+	remainingWallTimeMs(): number {
+		return Math.max(0, this.budget.max_wall_time_ms - (this.now() - this.startedAt));
+	}
+
+	/**
+	 * Authorize a command's coarse scope against the declared allowlist. Throws
+	 * ScopeDeniedError (pre-side-effect) when the scope was not declared.
+	 */
+	authorizeScope(scope: BridgeCommandScope, command?: string): void {
+		if (this.scopes.has(scope)) return;
+		const payload: RpcScopeDenied = {
+			code: "scope_denied",
+			scope,
+			command,
+			run_id: this.runId,
+			session_id: this.sessionId,
+			pre_side_effect: true,
+		};
+		this.audit?.({ event: "scope_denied", payload });
+		throw new ScopeDeniedError(payload);
+	}
+
+	/**
+	 * Authorize an action class against the declared allowlist. Default-deny: any
+	 * class not explicitly declared is rejected with ActionDeniedError before the
+	 * side effect runs.
+	 */
+	authorizeAction(action: RpcUnattendedActionClass, command?: string): void {
+		if (this.actionAllowlist.has(action)) return;
+		const payload: RpcActionDenied = {
+			code: "action_denied",
+			action,
+			command,
+			run_id: this.runId,
+			session_id: this.sessionId,
+			pre_side_effect: true,
+		};
+		this.audit?.({ event: "action_denied", payload });
+		throw new ActionDeniedError(payload);
+	}
+
+	/**
+	 * Classify a bash command and authorize the resulting action class BEFORE the
+	 * command is executed. Returns the classified action class on success.
+	 */
+	authorizeBash(command: string): RpcUnattendedActionClass {
+		this.authorizeScope("bash", command);
+		const action = classifyBashAction(command);
+		this.authorizeAction(action, command);
+		return action;
+	}
+
+	/** Convenience: map a coarse scope to its `command.<scope>` action class. */
+	static actionClassForScope = actionClassForScope;
+
+	/** Pre-turn estimate: refuse to start a turn that would obviously breach. */
+	preTurnEstimate(estimate: { tokens?: number; costUsd?: number }): void {
+		this.checkWallTime("pre-turn estimate");
+		if (estimate.tokens !== undefined) {
+			if (!Number.isFinite(estimate.tokens)) {
+				void this.fireAbort("accounting:tokens");
+				throw new UnattendedAccountingError("tokens", "pre-turn estimate", estimate.tokens);
+			}
+			if (this.usage.tokens + estimate.tokens > this.budget.max_tokens) {
+				this.breach("tokens", this.budget.max_tokens, this.usage.tokens + estimate.tokens, "pre-turn estimate");
+			}
+		}
+		if (estimate.costUsd !== undefined) {
+			if (!Number.isFinite(estimate.costUsd)) {
+				void this.fireAbort("accounting:cost");
+				throw new UnattendedAccountingError("cost", "pre-turn estimate", estimate.costUsd);
+			}
+			if (this.usage.costUsd + estimate.costUsd > this.budget.max_cost_usd) {
+				this.breach("cost", this.budget.max_cost_usd, this.usage.costUsd + estimate.costUsd, "pre-turn estimate");
+			}
+		}
+	}
+
+	/** Reserve one tool-call unit BEFORE any side effect; breach if it would exceed. */
+	preflightToolCall(phase = "tool-call preflight"): void {
+		this.checkWallTime(phase);
+		if (this.usage.toolCalls + 1 > this.budget.max_tool_calls) {
+			this.breach("tool_calls", this.budget.max_tool_calls, this.usage.toolCalls + 1, phase);
+		}
+		this.usage.toolCalls += 1;
+	}
+
+	/** Post-turn reconciliation of actual token usage. Fails closed on non-finite. */
+	recordTokens(tokens: number, phase = "post-turn reconciliation"): void {
+		if (!Number.isFinite(tokens)) {
+			void this.fireAbort(`accounting:tokens`);
+			throw new UnattendedAccountingError("tokens", phase, tokens);
+		}
+		this.usage.tokens += Math.max(0, tokens);
+		if (this.usage.tokens > this.budget.max_tokens) {
+			this.breach("tokens", this.budget.max_tokens, this.usage.tokens, phase);
+		}
+	}
+
+	recordCost(costUsd: number, phase = "post-turn reconciliation"): void {
+		if (!Number.isFinite(costUsd)) {
+			void this.fireAbort(`accounting:cost`);
+			throw new UnattendedAccountingError("cost", phase, costUsd);
+		}
+		this.usage.costUsd += Math.max(0, costUsd);
+		if (this.usage.costUsd > this.budget.max_cost_usd) {
+			this.breach("cost", this.budget.max_cost_usd, this.usage.costUsd, phase);
+		}
+	}
+
+	/** Combined post-turn reconciliation. */
+	reconcile(actual: { tokens?: number; costUsd?: number }, phase = "post-turn reconciliation"): void {
+		if (actual.tokens !== undefined) this.recordTokens(actual.tokens, phase);
+		if (actual.costUsd !== undefined) this.recordCost(actual.costUsd, phase);
+	}
+
+	/** Wall-time check; call before/inside long operations. */
+	checkWallTime(phase = "wall-time"): void {
+		const elapsed = this.now() - this.startedAt;
+		if (elapsed > this.budget.max_wall_time_ms) {
+			this.breach("wall_time", this.budget.max_wall_time_ms, elapsed, phase);
+		}
+	}
+
+	private breach(metric: RpcBudgetMetric, limit: number, observed: number, phase: string): never {
+		// Initiate the (idempotent, awaitable) abort. breach() throws synchronously,
+		// so the payload reports `aborting`; the settled status (aborted/abort_failed)
+		// is emitted as an unattended_abort_settled audit event once hooks complete.
+		void this.fireAbort(`budget_exceeded:${metric}`);
+		const abortStatus: RpcBudgetExceeded["abort_status"] = "aborting";
+		const payload: RpcBudgetExceeded = {
+			code: "budget_exceeded",
+			metric,
+			limit,
+			observed,
+			phase,
+			run_id: this.runId,
+			session_id: this.sessionId,
+			abort_status: abortStatus,
+		};
+		this.audit?.({ event: "budget_exceeded", payload });
+		throw new UnattendedBudgetExceededError(payload);
+	}
+
+	/**
+	 * Idempotent abort: runs every abort hook at most once. Safe to call from the
+	 * synchronous breach path (which does not await) and from callers that do; both
+	 * share a single abort promise so hook completion can be awaited deterministically.
+	 */
+	async abort(reason: string): Promise<void> {
+		await this.fireAbort(reason);
+	}
+
+	/** Returns the in-flight/settled abort completion once aborting has begun. */
+	get abortCompletion(): Promise<void> | undefined {
+		return this.abortPromise;
+	}
+
+	private fireAbort(reason: string): Promise<void> {
+		if (this.abortPromise) return this.abortPromise;
+		this.aborted = true;
+		this.abortPromise = this.runAbortHooks().then(failures => {
+			this.audit?.({ event: "unattended_aborted", run_id: this.runId, reason });
+			this.audit?.({
+				event: "unattended_abort_settled",
+				run_id: this.runId,
+				status: failures === 0 ? "aborted" : "abort_failed",
+				failures,
+			});
+		});
+		return this.abortPromise;
+	}
+
+	/**
+	 * Invoke every configured abort hook exactly once with per-hook isolation, so a
+	 * failing hook never prevents the other cancellation surfaces from running.
+	 * Returns the number of hooks that rejected.
+	 */
+	private async runAbortHooks(): Promise<number> {
+		const calls: Array<Promise<unknown>> = [];
+		const run = (fn: (() => void | Promise<void>) | undefined) => {
+			if (!fn) return;
+			// Invoke synchronously so the hook's synchronous prefix runs immediately,
+			// but capture sync throws and async rejections so allSettled isolates them.
+			try {
+				calls.push(Promise.resolve(fn()));
+			} catch (err) {
+				calls.push(Promise.reject(err));
+			}
+		};
+		run(this.abortHooks.abortModelStream);
+		run(this.abortHooks.abortBash);
+		run(() => this.abortHooks.cancelHostTools?.("unattended abort"));
+		run(() => this.abortHooks.cancelHostUris?.("unattended abort"));
+		run(() => this.abortHooks.stopWorkflow?.("unattended abort"));
+		const results = await Promise.allSettled(calls);
+		return results.filter(r => r.status === "rejected").length;
+	}
+}

package/src/modes/shared/agent-wire/unattended-session.ts

@@ -0,0 +1,180 @@
+/**
+ * Session-level unattended control plane (#323 / G011 emission side).
+ *
+ * Bridges the gate EMISSION side (skill runtimes / ask tool emitting gates) to
+ * the gate ANSWER side (the external agent's `workflow_gate_response` over RPC):
+ *
+ *  - `emitGate(input)` opens a gate on the durable broker, emits the gate frame
+ *    to the transport, and returns a promise that resolves with the agent's
+ *    answer once it arrives.
+ *  - `resolveGate(response)` (called from RPC dispatch) validates + resolves the
+ *    gate on the broker; the broker's `advance` hook resolves the pending
+ *    `emitGate` promise with the answer.
+ *
+ * Also implements the dispatch-facing {@link RpcUnattendedControlPlane} so the
+ * RPC server can route `negotiate_unattended` + `workflow_gate_response` here.
+ */
+import type {
+	RpcCommand,
+	RpcUnattendedAccepted,
+	RpcUnattendedDeclaration,
+	RpcWorkflowGate,
+	RpcWorkflowGateResolution,
+	RpcWorkflowGateResponse,
+} from "../../rpc/rpc-types";
+import type { RpcUnattendedControlPlane } from "./command-dispatch";
+import { scopeForRpcCommand } from "./scopes";
+import {
+	type UnattendedAbortHooks,
+	type UnattendedAuditEvent,
+	UnattendedRunController,
+} from "./unattended-run-controller";
+import { type GateStore, MemoryGateStore, type OpenGateInput, WorkflowGateBroker } from "./workflow-gate-broker";
+
+/** Minimal surface a skill runtime / ask tool uses to emit a gate and await its answer. */
+export interface WorkflowGateEmitter {
+	/** True only when unattended mode has been negotiated. */
+	isUnattended(): boolean;
+	/** Open + emit a gate; resolves with the agent's answer (from workflow_gate_response). */
+	emitGate(input: OpenGateInput): Promise<unknown>;
+}
+
+export interface UnattendedSessionOptions {
+	runId: string;
+	sessionId?: string;
+	/** Emit a workflow_gate frame to the transport so the agent receives it. */
+	emitFrame: (gate: RpcWorkflowGate) => void;
+	/** Durable gate store; defaults to in-memory. */
+	store?: GateStore;
+	/** Audit sink for controller + gate events. */
+	audit?: (event: UnattendedAuditEvent | { event: string; [k: string]: unknown }) => void;
+	abortHooks?: UnattendedAbortHooks;
+	/** Whether the active provider reports token/cost usage (fail-closed when false/omitted). */
+	providerSupportsTokenCostMetrics?: boolean;
+	/** Snapshot live cumulative usage after a dispatch or turn, for budget reconciliation. */
+	getUsageSnapshot?: () => { tokens?: number; costUsd?: number };
+}
+
+export class UnattendedSessionControlPlane implements RpcUnattendedControlPlane, WorkflowGateEmitter {
+	#controller: UnattendedRunController | undefined;
+	#broker: WorkflowGateBroker | undefined;
+	readonly #pending = new Map<string, { resolve: (answer: unknown) => void; reject: (err: Error) => void }>();
+	readonly #earlyAnswers = new Map<string, unknown>();
+
+	constructor(private readonly opts: UnattendedSessionOptions) {}
+
+	isUnattended(): boolean {
+		return this.#controller !== undefined;
+	}
+
+	get controller(): UnattendedRunController | undefined {
+		return this.#controller;
+	}
+
+	negotiate(declaration: RpcUnattendedDeclaration): RpcUnattendedAccepted {
+		const controller = UnattendedRunController.negotiate(declaration, {
+			runId: this.opts.runId,
+			sessionId: this.opts.sessionId,
+			audit: this.opts.audit,
+			abortHooks: {
+				...this.opts.abortHooks,
+				// On abort (e.g. wall-time / budget breach) reject any gate still
+				// awaiting an answer, so emitGate cannot hang forever.
+				stopWorkflow: async reason => {
+					await this.opts.abortHooks?.stopWorkflow?.(reason);
+					this.#rejectAllPending(new Error(`unattended run aborted: ${reason}`));
+				},
+			},
+			providerSupportsTokenCostMetrics: this.opts.providerSupportsTokenCostMetrics ?? true,
+		});
+		this.#controller = controller;
+		this.#broker = new WorkflowGateBroker(this.opts.runId, this.opts.store ?? new MemoryGateStore(), {
+			emit: gate => this.opts.emitFrame(gate),
+			audit: e => this.opts.audit?.(e),
+			advance: (gate, answer) => {
+				const pending = this.#pending.get(gate.gate_id);
+				if (pending) {
+					this.#pending.delete(gate.gate_id);
+					pending.resolve(answer);
+					return;
+				}
+				// A controller may answer synchronously while emitFrame is still on the
+				// stack. Keep the accepted answer so emitGate can still resolve after
+				// openGate returns and the caller starts awaiting.
+				this.#earlyAnswers.set(gate.gate_id, answer);
+			},
+		});
+		return {
+			run_id: this.opts.runId,
+			actor: controller.actor,
+			budget: controller.budget,
+			scopes: [...controller.scopes],
+			action_allowlist: [...controller.actionAllowlist],
+			accepted_at: new Date().toISOString(),
+		};
+	}
+
+	preflightCommand(command: RpcCommand): void {
+		if (!this.#controller) return;
+		this.#controller.preflightToolCall(`${command.type} preflight`);
+		if (command.type === "bash") {
+			this.#controller.authorizeBash(command.command);
+			return;
+		}
+		const scope = scopeForRpcCommand(command.type);
+		this.#controller.authorizeScope(scope);
+		this.#controller.authorizeAction(UnattendedRunController.actionClassForScope(scope));
+	}
+
+	reconcileUsage(phase = "unattended usage reconciliation"): void {
+		const controller = this.#controller;
+		if (!controller) return;
+		controller.checkWallTime(phase);
+		const snapshot = this.opts.getUsageSnapshot?.();
+		if (!snapshot) return;
+		const current = controller.usageSnapshot();
+		const tokens = snapshot.tokens;
+		const costUsd = snapshot.costUsd;
+		controller.reconcile(
+			{
+				tokens: tokens !== undefined ? Math.max(0, tokens - current.tokens) : undefined,
+				costUsd: costUsd !== undefined ? Math.max(0, costUsd - current.costUsd) : undefined,
+			},
+			phase,
+		);
+	}
+
+	resolveGate(response: RpcWorkflowGateResponse): Promise<RpcWorkflowGateResolution> {
+		if (!this.#broker) {
+			return Promise.reject(new Error("workflow gates are not available until unattended mode is negotiated"));
+		}
+		return this.#broker.resolve(response);
+	}
+
+	emitGate(input: OpenGateInput): Promise<unknown> {
+		if (!this.#broker) {
+			return Promise.reject(new Error("cannot emit a workflow gate before unattended mode is negotiated"));
+		}
+		const gate = this.#broker.openGate(input);
+		if (this.#earlyAnswers.has(gate.gate_id)) {
+			const answer = this.#earlyAnswers.get(gate.gate_id);
+			this.#earlyAnswers.delete(gate.gate_id);
+			return Promise.resolve(answer);
+		}
+		const { promise, resolve, reject } = Promise.withResolvers<unknown>();
+		this.#pending.set(gate.gate_id, { resolve, reject });
+		return promise;
+	}
+
+	async recover(): Promise<void> {
+		await this.#broker?.recover();
+	}
+
+	#rejectAllPending(error: Error): void {
+		this.#earlyAnswers.clear();
+		for (const [gateId, pending] of this.#pending) {
+			this.#pending.delete(gateId);
+			pending.reject(error);
+		}
+	}
+}