@gajae-code/coding-agent 0.13.2 → 0.14.0

package/src/sdk/prompt-deadline-manager.ts

@@ -0,0 +1,148 @@
+import type { KindAwareReconciliation } from "./bus/kind-aware-reconciliation";
+import type { InvocationCorrelation, InvocationReconciliation } from "./host/session-runtime";
+import {
+	createPromptDeadlineLease,
+	isAttributableProgressEventType,
+	type PromptDeadlineLease,
+	promptDeadlineAt,
+	recordAttributableProgress,
+} from "./prompt-deadline-lease";
+
+type DeadlineReconciliation = InvocationReconciliation | KindAwareReconciliation;
+export type PromptDeadlineOutcome = {
+	kind: "failed";
+	code: "prompt_deadline_exceeded";
+	message: string;
+	provenance: "deadline";
+};
+
+function leaseKey(correlation: InvocationCorrelation): string {
+	return `${correlation.commandId}:${correlation.turnId}`;
+}
+
+export class PromptDeadlineManager {
+	readonly #leases = new Map<string, PromptDeadlineLease>();
+	readonly #correlations = new Map<string, InvocationCorrelation>();
+	readonly #timers = new Map<string, ReturnType<typeof setTimeout>>();
+	readonly #reconciliation: DeadlineReconciliation;
+	readonly #getLeaseMs: () => number;
+	readonly #getMaxMs: () => number;
+	readonly #now: () => number;
+
+	constructor(options: {
+		reconciliation: DeadlineReconciliation;
+		getLeaseMs: () => number;
+		getMaxMs: () => number;
+		now?: () => number;
+	}) {
+		this.#reconciliation = options.reconciliation;
+		this.#getLeaseMs = options.getLeaseMs;
+		this.#getMaxMs = options.getMaxMs;
+		this.#now = options.now ?? Date.now;
+	}
+
+	#clearTimer(key: string): void {
+		const timer = this.#timers.get(key);
+		if (timer !== undefined) {
+			clearTimeout(timer);
+			this.#timers.delete(key);
+		}
+	}
+
+	#schedule(key: string): void {
+		const lease = this.#leases.get(key);
+		if (!lease) return;
+		this.#clearTimer(key);
+		const deadlineAt = promptDeadlineAt(lease);
+		const delayMs = Math.max(0, deadlineAt - this.#now());
+		const timer = setTimeout(() => {
+			void this.#onDeadline(key);
+		}, delayMs);
+		// Allow process to exit without waiting for deadline timer.
+		(timer as unknown as { unref?: () => void }).unref?.();
+		this.#timers.set(key, timer);
+	}
+
+	async #onDeadline(key: string): Promise<void> {
+		const correlation = this.#correlations.get(key);
+		const lease = this.#leases.get(key);
+		if (!correlation || !lease) return;
+		// Re-check deadline still due (monotonic, but handle clock skew).
+		if (this.#now() < promptDeadlineAt(lease)) {
+			this.#schedule(key);
+			return;
+		}
+		const lookup = this.#reconciliation.lookup("prompt", correlation) as { status: string };
+		if (lookup.status === "terminal_ok" || lookup.status === "failed") {
+			this.clear(correlation);
+			return;
+		}
+		const outcome: PromptDeadlineOutcome = {
+			kind: "failed",
+			code: "prompt_deadline_exceeded",
+			message: "Prompt deadline exceeded.",
+			provenance: "deadline",
+		};
+		try {
+			await this.#reconciliation.claimPendingOutcome("prompt", correlation, outcome);
+		} catch {
+			// claim may fail if already claimed (e.g., cancellation won); ignore.
+		}
+		try {
+			await this.#reconciliation.finalizeOutcome("prompt", correlation, outcome);
+		} catch {
+			// finalize may race with normal terminalization; ignore.
+		} finally {
+			this.clear(correlation);
+		}
+	}
+
+	onAccepted(correlation: InvocationCorrelation): void {
+		const key = leaseKey(correlation);
+		if (this.#leases.has(key)) return;
+		const now = this.#now();
+		const lease = createPromptDeadlineLease({ now, leaseMs: this.#getLeaseMs(), maxMs: this.#getMaxMs() });
+		this.#leases.set(key, lease);
+		this.#correlations.set(key, correlation);
+		this.#schedule(key);
+	}
+
+	onProgress(correlation: InvocationCorrelation, now = this.#now()): void {
+		const key = leaseKey(correlation);
+		const lease = this.#leases.get(key);
+		if (!lease) return;
+		const beforeDeadline = promptDeadlineAt(lease);
+		recordAttributableProgress(lease, now);
+		const afterDeadline = promptDeadlineAt(lease);
+		if (afterDeadline !== beforeDeadline) this.#schedule(key);
+	}
+
+	onAttributableEvent(correlation: InvocationCorrelation, eventType: string, now = this.#now()): void {
+		if (!isAttributableProgressEventType(eventType)) return;
+		this.onProgress(correlation, now);
+	}
+
+	clear(correlation: InvocationCorrelation): void {
+		const key = leaseKey(correlation);
+		this.#clearTimer(key);
+		this.#leases.delete(key);
+		this.#correlations.delete(key);
+	}
+
+	clearAll(): void {
+		for (const key of [...this.#timers.keys()]) this.#clearTimer(key);
+		this.#leases.clear();
+		this.#correlations.clear();
+	}
+
+	/** For tests: current deadline or undefined if no lease. */
+	deadlineAt(correlation: InvocationCorrelation): number | undefined {
+		const lease = this.#leases.get(leaseKey(correlation));
+		return lease ? promptDeadlineAt(lease) : undefined;
+	}
+
+	/** For tests: whether a lease exists. */
+	has(correlation: InvocationCorrelation): boolean {
+		return this.#leases.has(leaseKey(correlation));
+	}
+}

package/src/sdk/prompt-status.ts

@@ -1,5 +1,6 @@
 /**
- * Public DTO contract for Q26 `turn.prompt_status` and the `clientRef`
+ * Public prompt-result DTO contract for canonical Q26 `turn.result` with
+ * `kind: "prompt"`, plus the legacy `turn.prompt_status` alias and the `clientRef`
  * correlation field on `turn.prompt`.
  *
  * Semantics:
@@ -13,14 +14,14 @@
  * - The clientRef index is scoped to one live session runtime: identical refs
  *   may coexist in different sessions, lookups never cross sessions, a ref
  *   conflicts only while its record is retained (`client_ref_conflict`), and
- *   after terminal TTL/capacity eviction a ref may be admitted again with the
+ *   after terminal capacity eviction a ref may be admitted again with the
  *   prior outcome unknown — callers MUST NOT reuse a clientRef as a retry
  *   mechanism and MUST treat `unknown` as uncertainty, not proof of
  *   non-execution.
  * - Prompt records survive process restart: an active prompt is finalized from its
  *   durable pending outcome, or as `prompt_failed` when it has none. Only skill
  *   records settle as `process_restart`, and a lookup reports `unknown` only after
- *   retained-record TTL/capacity eviction.
+ *   retained-record capacity eviction.
  * - Q26 tracks prompts accepted through the SDK control surface (which always
  *   carries a requesting connection); submissions without a delivery owner are
  *   outside the reconciliation contract and hold no reservation.
@@ -51,6 +52,8 @@ export interface TurnPromptInput {
  * prompt that is active at process restart is finalized from its durable pending
  * outcome (or `prompt_failed` when it has none), so it never reports as unknown.
  */
+import type { ReceiptState } from "./receipt-state";
+
 export type PromptReconciliationStatus = "accepted" | "in_flight" | "terminal_ok" | "failed";
 export type SdkPromptStopReason = "end_turn" | "max_tokens" | "max_turn_requests" | "refusal" | "cancelled";
 export type SdkPromptFailureCode = "prompt_failed" | "prompt_deadline_exceeded";
@@ -71,16 +74,19 @@ interface TurnPromptReconciliationIdentity {
 
 export interface TurnPromptReconciliationAccepted extends TurnPromptReconciliationIdentity {
 	status: "accepted";
+	receiptState: Extract<ReceiptState, "absent">;
 }
 
 export interface TurnPromptReconciliationInFlight extends TurnPromptReconciliationIdentity {
 	status: "in_flight";
+	receiptState: Extract<ReceiptState, "absent">;
 	/** Epoch milliseconds of the agent_start transition. */
 	startedAt: number;
 }
 
 export interface TurnPromptReconciliationTerminalOk extends TurnPromptReconciliationIdentity {
 	status: "terminal_ok";
+	receiptState: Exclude<ReceiptState, "absent">;
 	startedAt?: number;
 	/** Epoch milliseconds of the terminal transition. */
 	terminalAt: number;
@@ -91,6 +97,7 @@ export interface TurnPromptReconciliationTerminalOk extends TurnPromptReconcilia
 
 export interface TurnPromptReconciliationFailed extends TurnPromptReconciliationIdentity {
 	status: "failed";
+	receiptState: Exclude<ReceiptState, "absent">;
 	startedAt?: number;
 	terminalAt: number;
 	/** Bounded, sanitized failure detail (code safe-token ≤64, message ≤512). */
@@ -100,6 +107,7 @@ export interface TurnPromptReconciliationFailed extends TurnPromptReconciliation
 
 export interface TurnPromptReconciliationUnknown {
 	status: "unknown";
+	receiptState: Extract<ReceiptState, "unknown">;
 }
 
 export type TurnPromptReconciliation =