@gajae-code/coding-agent 0.11.10 → 0.12.0

package/src/sdk/bus/kind-aware-reconciliation.ts

@@ -0,0 +1,242 @@
+/**
+ * Kind-aware invocation reconciliation (prompt | skill) with optional durable store.
+ * Preserves Q26 admit/first-terminal/capacity/TTL semantics; indexes and caps are per-kind.
+ */
+import {
+	PROMPT_RECONCILIATION_ACTIVE_CAPACITY,
+	PROMPT_RECONCILIATION_TERMINAL_CAPACITY,
+	PROMPT_RECONCILIATION_TERMINAL_TTL_MS,
+	type PromptCorrelation,
+	type PromptReconciliationStatus,
+	sanitizePromptFailure,
+	type TurnPromptReconciliation,
+} from "./prompt-reconciliation";
+import type { DurableReconciliationRecord, ReconciliationKind, ReconciliationStore } from "./reconciliation-store";
+
+export type { ReconciliationKind };
+
+export interface KindCorrelation extends PromptCorrelation {
+	kind: ReconciliationKind;
+}
+
+export interface KindAwareReconciliation {
+	admit(kind: ReconciliationKind, clientRef?: string): void;
+	releaseAdmission(kind: ReconciliationKind, clientRef?: string): void;
+	noteAccepted(
+		kind: ReconciliationKind,
+		correlation: PromptCorrelation,
+		clientRef?: string,
+		extra?: { skillName?: string },
+	): Promise<void>;
+	noteTransition(
+		kind: ReconciliationKind,
+		correlation: PromptCorrelation | undefined,
+		frame: { type: "agent_start" | "agent_end" } | { type: "agent_failed"; error: unknown },
+	): Promise<void>;
+	lookup(
+		kind: ReconciliationKind,
+		selector: { commandId?: string; turnId?: string; clientRef?: string },
+	): TurnPromptReconciliation;
+	cleanup(): void;
+	activeCount(kind: ReconciliationKind): number;
+	/** Hydrate from durable store (call once at session host start). */
+	hydrateFromStore(): Promise<void>;
+}
+
+export function createKindAwareReconciliation(
+	options: { now?: () => number; store?: ReconciliationStore | null } = {},
+): KindAwareReconciliation {
+	const now = options.now ?? Date.now;
+	const store = options.store ?? null;
+	const records = new Map<string, DurableReconciliationRecord>();
+	const clientRefIndex = new Map<string, string>(); // `${kind}\0${clientRef}` -> key
+	const reservedClientRefs = new Map<ReconciliationKind, Set<string>>();
+	const reservations: Array<{ kind: ReconciliationKind; clientRef?: string }> = [];
+
+	const keyOf = (kind: ReconciliationKind, correlation: PromptCorrelation) =>
+		`${kind}:${correlation.commandId}:${correlation.turnId}`;
+	const refKey = (kind: ReconciliationKind, clientRef: string) => `${kind}\0${clientRef}`;
+
+	const reservedFor = (kind: ReconciliationKind) => {
+		let set = reservedClientRefs.get(kind);
+		if (!set) {
+			set = new Set();
+			reservedClientRefs.set(kind, set);
+		}
+		return set;
+	};
+
+	const remove = (key: string) => {
+		const record = records.get(key);
+		if (!record) return;
+		records.delete(key);
+		if (record.clientRef !== undefined) {
+			const rk = refKey(record.kind, record.clientRef);
+			if (clientRefIndex.get(rk) === key) clientRefIndex.delete(rk);
+		}
+	};
+
+	const cleanup = () => {
+		const at = now();
+		for (const [key, record] of records)
+			if (record.terminalAt !== undefined && record.terminalAt + PROMPT_RECONCILIATION_TERMINAL_TTL_MS <= at)
+				remove(key);
+		for (const kind of ["prompt", "skill"] as const) {
+			const terminalEntries = [...records.entries()].filter(
+				([, record]) => record.kind === kind && record.terminalAt !== undefined,
+			);
+			if (terminalEntries.length <= PROMPT_RECONCILIATION_TERMINAL_CAPACITY) continue;
+			terminalEntries.sort((a, b) => (a[1].terminalAt as number) - (b[1].terminalAt as number));
+			for (const [key] of terminalEntries.slice(0, terminalEntries.length - PROMPT_RECONCILIATION_TERMINAL_CAPACITY))
+				remove(key);
+		}
+	};
+
+	const activeCount = (kind: ReconciliationKind) => {
+		let count = 0;
+		for (const record of records.values()) if (record.kind === kind && record.terminalAt === undefined) count++;
+		return count;
+	};
+
+	const reservationCount = (kind: ReconciliationKind) => reservations.filter(r => r.kind === kind).length;
+
+	const consumeReservation = (kind: ReconciliationKind, clientRef?: string) => {
+		const index = reservations.findIndex(r => r.kind === kind && r.clientRef === clientRef);
+		if (index === -1) return;
+		reservations.splice(index, 1);
+		if (clientRef !== undefined && !reservations.some(r => r.kind === kind && r.clientRef === clientRef))
+			reservedFor(kind).delete(clientRef);
+	};
+
+	const persist = async () => {
+		if (!store) return;
+		await store.transact(() => [...records.values()].map(r => ({ ...r })));
+	};
+
+	const admit = (kind: ReconciliationKind, clientRef?: string) => {
+		cleanup();
+		const reserved = reservedFor(kind);
+		if (clientRef !== undefined && (clientRefIndex.has(refKey(kind, clientRef)) || reserved.has(clientRef)))
+			throw Object.assign(
+				new Error("A submission with this clientRef is already retained; never reuse a clientRef for retry."),
+				{ code: "client_ref_conflict" },
+			);
+		if (activeCount(kind) + reservationCount(kind) >= PROMPT_RECONCILIATION_ACTIVE_CAPACITY)
+			throw Object.assign(new Error("Too many active submissions; reconcile or await terminal state."), {
+				code: "reconciliation_capacity",
+			});
+		reservations.push({ kind, clientRef });
+		if (clientRef !== undefined) reserved.add(clientRef);
+	};
+
+	const releaseAdmission = (kind: ReconciliationKind, clientRef?: string) => {
+		consumeReservation(kind, clientRef);
+	};
+
+	const noteAccepted = async (
+		kind: ReconciliationKind,
+		correlation: PromptCorrelation,
+		clientRef?: string,
+		extra?: { skillName?: string },
+	) => {
+		cleanup();
+		consumeReservation(kind, clientRef);
+		const at = now();
+		const key = keyOf(kind, correlation);
+		const record: DurableReconciliationRecord = {
+			kind,
+			commandId: correlation.commandId,
+			turnId: correlation.turnId,
+			...(clientRef !== undefined ? { clientRef } : {}),
+			status: "accepted",
+			acceptedAt: at,
+			...(extra?.skillName ? { skillName: extra.skillName } : {}),
+		};
+		records.set(key, record);
+		if (clientRef !== undefined) clientRefIndex.set(refKey(kind, clientRef), key);
+		await persist();
+	};
+
+	const noteTransition = async (
+		kind: ReconciliationKind,
+		correlation: PromptCorrelation | undefined,
+		frame: { type: "agent_start" | "agent_end" } | { type: "agent_failed"; error: unknown },
+	) => {
+		if (!correlation) return;
+		const record = records.get(keyOf(kind, correlation));
+		if (!record || record.terminalAt !== undefined) return;
+		if (frame.type === "agent_start") {
+			if (record.status === "accepted") {
+				record.status = "in_flight";
+				record.startedAt = now();
+				await persist();
+			}
+			return;
+		}
+		record.terminalAt = now();
+		if (frame.type === "agent_failed") {
+			record.status = "failed";
+			record.error = sanitizePromptFailure(frame.error);
+		} else {
+			record.status = "terminal_ok";
+		}
+		cleanup();
+		await persist();
+	};
+
+	const lookup = (
+		kind: ReconciliationKind,
+		selector: { commandId?: string; turnId?: string; clientRef?: string },
+	): TurnPromptReconciliation => {
+		cleanup();
+		const key =
+			selector.clientRef !== undefined
+				? clientRefIndex.get(refKey(kind, selector.clientRef))
+				: selector.commandId !== undefined && selector.turnId !== undefined
+					? keyOf(kind, { commandId: selector.commandId, turnId: selector.turnId })
+					: undefined;
+		const record = key === undefined ? undefined : records.get(key);
+		if (!record) return { status: "unknown" };
+		const identity = {
+			commandId: record.commandId,
+			turnId: record.turnId,
+			...(record.clientRef !== undefined ? { clientRef: record.clientRef } : {}),
+			acceptedAt: record.acceptedAt,
+		};
+		if (record.status === "accepted") return { status: "accepted", ...identity };
+		if (record.status === "in_flight")
+			return { status: "in_flight", ...identity, startedAt: record.startedAt as number };
+		const terminal = {
+			...identity,
+			...(record.startedAt !== undefined ? { startedAt: record.startedAt } : {}),
+			terminalAt: record.terminalAt as number,
+		};
+		if (record.status === "terminal_ok") return { status: "terminal_ok", ...terminal };
+		return { status: "failed", ...terminal, error: record.error ?? sanitizePromptFailure(undefined) };
+	};
+
+	const hydrateFromStore = async () => {
+		if (!store) return;
+		const loaded = await store.load();
+		records.clear();
+		clientRefIndex.clear();
+		for (const record of loaded) {
+			const key = keyOf(record.kind, record);
+			records.set(key, record);
+			if (record.clientRef !== undefined) clientRefIndex.set(refKey(record.kind, record.clientRef), key);
+		}
+	};
+
+	return {
+		admit,
+		releaseAdmission,
+		noteAccepted,
+		noteTransition,
+		lookup,
+		cleanup,
+		activeCount,
+		hydrateFromStore,
+	};
+}
+
+export type { PromptReconciliationStatus };

package/src/sdk/bus/prompt-reconciliation.ts

@@ -12,7 +12,8 @@
  * - Terminal records are retained for TERMINAL_TTL_MS and bounded to
  *   TERMINAL_CAPACITY, evicted oldest-terminal-first by terminalAt; only then
  *   does a lookup honestly report `unknown`.
- * - The durability floor is the live session process: restart means `unknown`.
+ * - Process-local durability floor is the live session process: restart means `unknown`.
+ *   Session-scoped durable retention (kind-aware store) is provided by reconciliation-store.ts (#3032).
  * - The clientRef index is session-runtime scoped; a ref conflicts only while
  *   retained and must never be reused as a retry mechanism.
  * - Terminal transitions settle once: the first terminal outcome wins.

package/src/sdk/bus/rate-limit-pool.ts

@@ -116,6 +116,14 @@ export class RateLimitPool<T = unknown> {
 		return total;
 	}
 
+	/** Whether any queued item currently matches the predicate. */
+	someQueued(predicate: (item: RateLimitItem<T>) => boolean): boolean {
+		for (const queue of this.lanes.values()) {
+			if (queue.some(entry => predicate(entry.item))) return true;
+		}
+		return false;
+	}
+
 	/** Current available token count (after refill at `now`). */
 	availableTokens(nowMs: number = this.now()): number {
 		this.refill(nowMs);

package/src/sdk/bus/reconciliation-store.ts

@@ -0,0 +1,224 @@
+/**
+ * Session-scoped durable store for kind-aware invocation reconciliation (#3032/#3035).
+ *
+ * Path is always a private sibling of the transcript, never under artifactsDir:
+ *   <dirname(sessionFile)>/.sdk-reconciliation/<safeSessionId>.json
+ *
+ * Safe session ids only: /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/
+ * Atomic write: temp + fsync + rename + 0600. Corrupt → quarantine + empty.
+ * Non-terminal records settle to failed/process_restart on bootstrap (recon incomplete).
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { PromptCorrelation, PromptReconciliationStatus } from "./prompt-reconciliation";
+
+export const RECONCILIATION_STORE_VERSION = 1;
+export const RECONCILIATION_SESSION_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+export const RECONCILIATION_DIR_NAME = ".sdk-reconciliation";
+
+export type ReconciliationKind = "prompt" | "skill";
+
+export interface DurableReconciliationRecord extends PromptCorrelation {
+	kind: ReconciliationKind;
+	clientRef?: string;
+	status: PromptReconciliationStatus;
+	error?: { code: string; message: string };
+	acceptedAt: number;
+	startedAt?: number;
+	terminalAt?: number;
+	/** Skill-only safe token; never skill args bodies. */
+	skillName?: string;
+}
+
+export interface ReconciliationStoreDocument {
+	version: typeof RECONCILIATION_STORE_VERSION;
+	sessionId: string;
+	records: DurableReconciliationRecord[];
+}
+
+export interface ReconciliationStoreFs {
+	mkdir(directory: string, options: { recursive: true; mode: number }): Promise<unknown>;
+	readFile(file: string, encoding: "utf8"): Promise<string>;
+	writeFile(file: string, data: string, options: { mode: number }): Promise<void>;
+	rename(from: string, to: string): Promise<void>;
+	unlink(file: string): Promise<void>;
+	open(
+		file: string,
+		flags: string,
+	): Promise<{
+		sync(): Promise<void>;
+		close(): Promise<void>;
+		writeFile(data: string, encoding: "utf8"): Promise<void>;
+	}>;
+}
+
+const nodeFs: ReconciliationStoreFs = {
+	mkdir: fs.mkdir,
+	readFile: fs.readFile,
+	writeFile: fs.writeFile,
+	rename: fs.rename,
+	unlink: fs.unlink,
+	open: fs.open as ReconciliationStoreFs["open"],
+};
+
+export function isSafeReconciliationSessionId(sessionId: string): boolean {
+	return RECONCILIATION_SESSION_ID_PATTERN.test(sessionId);
+}
+
+/** Derive private store path; throws if sessionId is unsafe (path escape). */
+export function reconciliationStorePath(sessionFile: string, sessionId: string): string {
+	if (!isSafeReconciliationSessionId(sessionId))
+		throw Object.assign(new Error("Unsafe session id for reconciliation store path."), {
+			code: "invalid_input",
+		});
+	return path.join(path.dirname(sessionFile), RECONCILIATION_DIR_NAME, `${sessionId}.json`);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function parseDocument(raw: string, expectedSessionId: string): ReconciliationStoreDocument {
+	const value = JSON.parse(raw) as unknown;
+	if (!isRecord(value) || value.version !== RECONCILIATION_STORE_VERSION)
+		throw new Error("invalid reconciliation store version");
+	if (value.sessionId !== expectedSessionId) throw new Error("session id mismatch");
+	if (!Array.isArray(value.records)) throw new Error("invalid records");
+	return value as unknown as ReconciliationStoreDocument;
+}
+
+/**
+ * Settle non-terminal durable records after process death: failed/process_restart.
+ * Meaning: reconciliation incomplete — not proof of agent failure.
+ */
+export function settleProcessRestart(
+	records: DurableReconciliationRecord[],
+	now: number,
+): DurableReconciliationRecord[] {
+	return records.map(record => {
+		if (record.terminalAt !== undefined) return record;
+		return {
+			...record,
+			status: "failed",
+			terminalAt: now,
+			error: { code: "process_restart", message: "Reconciliation incomplete after process restart." },
+		};
+	});
+}
+
+export interface ReconciliationStore {
+	readonly path: string | null;
+	readonly sessionId: string;
+	/** Serialize mutations; reload not required for single-process host (in-memory + write). */
+	transact(mutator: (records: DurableReconciliationRecord[]) => DurableReconciliationRecord[]): Promise<void>;
+	load(): Promise<DurableReconciliationRecord[]>;
+	/** Snapshot currently held in memory after last load/transact. */
+	snapshot(): DurableReconciliationRecord[];
+	delete(): Promise<void>;
+}
+
+export function createReconciliationStore(options: {
+	sessionFile: string | null | undefined;
+	sessionId: string;
+	fs?: ReconciliationStoreFs;
+	now?: () => number;
+}): ReconciliationStore {
+	const fileFs = options.fs ?? nodeFs;
+	const now = options.now ?? Date.now;
+	const sessionId = options.sessionId;
+	const filePath =
+		options.sessionFile && isSafeReconciliationSessionId(sessionId)
+			? reconciliationStorePath(options.sessionFile, sessionId)
+			: null;
+
+	let memory: DurableReconciliationRecord[] = [];
+	let chain: Promise<void> = Promise.resolve();
+
+	const writeAtomic = async (document: ReconciliationStoreDocument): Promise<void> => {
+		if (!filePath) return;
+		const directory = path.dirname(filePath);
+		await fileFs.mkdir(directory, { recursive: true, mode: 0o700 });
+		const temporary = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+		try {
+			await fileFs.writeFile(temporary, `${JSON.stringify(document)}\n`, { mode: 0o600 });
+			try {
+				const handle = await fileFs.open(temporary, "r+");
+				try {
+					await handle.sync();
+				} finally {
+					await handle.close();
+				}
+			} catch {
+				// fsync optional on some fs seams
+			}
+			await fileFs.rename(temporary, filePath);
+		} catch (error) {
+			await fileFs.unlink(temporary).catch(() => {});
+			throw Object.assign(error instanceof Error ? error : new Error("reconciliation persist failed"), {
+				code: "reconciliation_persist_failed",
+			});
+		}
+	};
+
+	const load = async (): Promise<DurableReconciliationRecord[]> => {
+		if (!filePath) {
+			memory = [];
+			return memory;
+		}
+		try {
+			const raw = await fileFs.readFile(filePath, "utf8");
+			const document = parseDocument(raw, sessionId);
+			memory = settleProcessRestart(document.records, now());
+			// Persist settled state so restart is sticky.
+			if (memory.some((r, i) => r !== document.records[i]))
+				await writeAtomic({ version: RECONCILIATION_STORE_VERSION, sessionId, records: memory });
+			return memory;
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+				memory = [];
+				return memory;
+			}
+			// Corrupt → quarantine
+			try {
+				await fileFs.rename(filePath, `${filePath}.corrupt.${now()}`);
+			} catch {
+				// ignore
+			}
+			memory = [];
+			return memory;
+		}
+	};
+
+	const transact = async (
+		mutator: (records: DurableReconciliationRecord[]) => DurableReconciliationRecord[],
+	): Promise<void> => {
+		const run = async () => {
+			const next = mutator(memory.map(r => ({ ...r })));
+			memory = next;
+			await writeAtomic({ version: RECONCILIATION_STORE_VERSION, sessionId, records: memory });
+		};
+		const pending = chain.then(run, run);
+		chain = pending.then(
+			() => undefined,
+			() => undefined,
+		);
+		await pending;
+	};
+
+	const deleteStore = async (): Promise<void> => {
+		memory = [];
+		if (!filePath) return;
+		await fileFs.unlink(filePath).catch(error => {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+		});
+	};
+
+	return {
+		path: filePath,
+		sessionId,
+		transact,
+		load,
+		snapshot: () => memory.map(r => ({ ...r })),
+		delete: deleteStore,
+	};
+}

package/src/sdk/bus/telegram-daemon-contract.ts

@@ -39,12 +39,14 @@ export const NOTIFICATION_PROTOCOL_VERSION = 3;
  * Generation 28 rejects special files before retained native authority opens.
  * Generation 29 adds serving-epoch compatibility, sidecar heartbeat, root GC,
  * and Bot API cooldown structural fixes (#2956, #2960, #3048).
+ * Generation 30 adds opt-in tool activity delivery, closed lifecycle phases,
+ * and capability-versioned mixed-host compatibility.
  */
-export const DAEMON_GENERATION = 29;
+export const DAEMON_GENERATION = 30;
 
 /**
  * Serving-compatibility boundary for daemon lifecycle requests. Epoch 1 covers
- * all builds published before this field existed; bump this to force serving
- * convergence and reload of compatible live predecessors.
+ * all builds published before this field existed; epoch 2 covered generation 29;
+ * bump this to force serving convergence and reload of compatible live predecessors.
  */
-export const SERVING_EPOCH = 2;
+export const SERVING_EPOCH = 3;