@gajae-code/coding-agent 0.12.0 → 0.12.2

package/src/sdk/bus/telegram-reference.ts

@@ -209,7 +209,12 @@ export function buildActionMarkdown(action: {
 	if (action.kind === "idle") {
 		return action.summary ? `🟢 Agent idle\n${action.summary}` : "🟢 Agent idle";
 	}
-	const heading = `❓ **${action.question ?? "Question"}**`;
+	const question = (action.question ?? "Question")
+		.split(/\r\n|\r|\n/)
+		.map(line => line.trimEnd())
+		.map(line => (line ? `**${line}**` : ""))
+		.join("  \n");
+	const heading = `❓ ${question}`;
 	const options = action.options ?? [];
 	const displayOptions = withRecommendedOptionLabel(options, action.recommendedIndex);
 	if (options.length === 0) return `${heading}\n\n(reply with text)`;
@@ -217,19 +222,43 @@ export function buildActionMarkdown(action: {
 	return `${heading}\n\n${list}`;
 }
 
+export type TelegramNotificationSound = "all" | "important" | "none";
+
+export type TelegramDeliveryLane = "ask" | "idle" | "live" | "finalized";
+
+/**
+ * Resolve Telegram's optional silent-delivery flag. `finalChunk` silences
+ * non-final actionable chunks under the `important` policy; `undefined`
+ * intentionally omits the field so Telegram uses its normal audible delivery
+ * behavior.
+ */
+export function telegramDisableNotification(
+	sound: TelegramNotificationSound | undefined,
+	lane: TelegramDeliveryLane,
+	finalChunk = true,
+): true | undefined {
+	if (sound === "none") return true;
+	if (sound !== "important") return undefined;
+	return (lane === "ask" || lane === "idle") && finalChunk ? undefined : true;
+}
+
 /** Send Telegram HTML text chunks sequentially so long messages preserve order. */
 export async function sendTelegramHtmlChunks(
 	send: TelegramSend,
 	chatId: string,
 	text: string,
 	inlineKeyboard?: InlineButton[][],
+	sound?: TelegramNotificationSound,
+	lane: TelegramDeliveryLane = "ask",
 ): Promise<void> {
 	const chunks = splitTelegramHtml(text);
 	for (let i = 0; i < chunks.length; i++) {
+		const disableNotification = telegramDisableNotification(sound, lane, i === chunks.length - 1);
 		await send("sendMessage", {
 			chat_id: chatId,
 			text: chunks[i]!,
 			parse_mode: TELEGRAM_PARSE_MODE,
+			...(disableNotification === true ? { disable_notification: true } : {}),
 			...(i === chunks.length - 1 && inlineKeyboard ? { reply_markup: { inline_keyboard: inlineKeyboard } } : {}),
 		});
 	}
@@ -348,6 +377,7 @@ export interface TelegramReferenceOptions {
 	endpointFile: string;
 	apiBase?: string;
 	fetchImpl?: typeof fetch;
+	sound?: TelegramNotificationSound;
 }
 
 /**
@@ -395,7 +425,14 @@ export async function runTelegramReferenceClient(opts: TelegramReferenceOptions)
 				controls: msg.controls,
 				summary: msg.summary,
 			});
-			await sendTelegramHtmlChunks(send, opts.chatId, rendered.text, rendered.inline_keyboard);
+			await sendTelegramHtmlChunks(
+				send,
+				opts.chatId,
+				rendered.text,
+				rendered.inline_keyboard,
+				opts.sound,
+				msg.kind ?? "ask",
+			);
 		} else if (msg.type === "action_unavailable") {
 			const requiredCapabilities = Array.isArray(msg.requiredCapabilities)
 				? msg.requiredCapabilities
@@ -416,7 +453,7 @@ export async function runTelegramReferenceClient(opts: TelegramReferenceOptions)
 			// session's forum topic; this reference shows the minimal handling.
 			const threaded = renderThreadedFrame(msg as never);
 			if (threaded?.text) {
-				await sendTelegramHtmlChunks(send, opts.chatId, threaded.text);
+				await sendTelegramHtmlChunks(send, opts.chatId, threaded.text, undefined, opts.sound, threaded.lane);
 			}
 		}
 	};

package/src/sdk/bus/threaded-render.ts

@@ -18,13 +18,13 @@ export interface ThreadedSend {
 	method: "sendMessage" | "sendPhoto" | "sendDocument";
 	/** Rate-limit lane for prioritisation/fairness. */
 	lane: RateLimitLane;
-	/** Message text (sendMessage) or photo caption (sendPhoto). */
+	/** Message text (sendMessage) or media caption (sendPhoto/sendDocument). */
 	text?: string;
 	/** Base64 image bytes for sendPhoto. */
 	photoBase64?: string;
 	/** Base64 file bytes for sendDocument. */
 	documentBase64?: string;
-	/** Image MIME type for sendPhoto. */
+	/** Uploaded media MIME type. */
 	mime?: string;
 	/** Suggested document filename. */
 	fileName?: string;
@@ -100,6 +100,40 @@ function str(v: unknown): string | undefined {
 	return typeof v === "string" && v.length > 0 ? v : undefined;
 }
 
+function baseMimeType(mime: string): string {
+	return mime.split(";", 1)[0]!.trim().toLowerCase();
+}
+
+export function supportsTelegramPhotoUpload(mime: string | undefined): boolean {
+	if (mime === undefined) return true;
+	const normalized = baseMimeType(mime);
+	return normalized === "image/jpeg" || normalized === "image/png";
+}
+
+function imageDocumentFileName(mime: string | undefined): string {
+	switch (mime === undefined ? "" : baseMimeType(mime)) {
+		case "image/webp":
+			return "image.webp";
+		case "image/gif":
+			return "image.gif";
+		case "image/svg+xml":
+			return "image.svg";
+		case "image/avif":
+			return "image.avif";
+		case "image/bmp":
+		case "image/x-ms-bmp":
+			return "image.bmp";
+		case "image/tiff":
+			return "image.tiff";
+		case "image/heic":
+			return "image.heic";
+		case "image/heif":
+			return "image.heif";
+		default:
+			return "image";
+	}
+}
+
 function isDotOnlyText(value: string): boolean {
 	return /^[.\s]+$/.test(value);
 }
@@ -244,11 +278,22 @@ export function renderThreadedFrame(frame: ThreadedFrame): ThreadedSend | undefi
 			const data = str(frame.data);
 			if (!data) return undefined;
 			const caption = str(frame.caption);
+			const mime = str(frame.mime);
+			if (!supportsTelegramPhotoUpload(mime)) {
+				return {
+					method: "sendDocument",
+					lane: "finalized",
+					documentBase64: data,
+					mime,
+					fileName: imageDocumentFileName(mime),
+					text: finalizeTelegramHtml(caption === undefined ? undefined : escapeHtml(caption)),
+				};
+			}
 			return {
 				method: "sendPhoto",
 				lane: "finalized",
 				photoBase64: data,
-				mime: str(frame.mime),
+				mime,
 				text: finalizeTelegramHtml(caption === undefined ? undefined : escapeHtml(caption)),
 			};
 		}

package/src/sdk/bus/topic-registry.ts

@@ -43,6 +43,8 @@ export interface TopicRecord {
 	creationLeaseEpoch?: number;
 	/** An uncertain delete fences future creation and inbound routing. */
 	authorityState?: "active" | "delete_pending";
+	/** Provenance for topics created by the user and adopted by GJC. Missing means daemon-created. */
+	topicOrigin?: "user_created";
 	/** Telegram chat and endpoint authority last proven to use this topic. */
 	chatId?: string;
 	/** Canonical endpoint tuple (URL + token) that currently holds the lease. */
@@ -234,6 +236,7 @@ export class TopicRegistry {
 				...(raw.authorityState === "delete_pending" || fenceSupersedesRecord
 					? { authorityState: "delete_pending" as const }
 					: {}),
+				...(raw.topicOrigin === "user_created" ? { topicOrigin: "user_created" as const } : {}),
 				...(isValidBindingString(raw.chatId) ? { chatId: raw.chatId } : {}),
 				...(isValidBindingString(raw.endpointKey) ? { endpointKey: raw.endpointKey } : {}),
 				...(isValidBindingString(raw.endpointDigest) ? { endpointDigest: raw.endpointDigest } : {}),
@@ -307,6 +310,21 @@ export class TopicRegistry {
 		const record = this.topics.get(sessionId);
 		return record?.authorityState !== "delete_pending" && this.byTopic.get(record?.topicId ?? "") === sessionId;
 	}
+	/**
+	 * Pure read-only availability check for user-topic adoption. Rejects invalid
+	 * ids and any id already committed, delete-pending/fenced, staged, or
+	 * ambiguous, without mutating maps, epochs, or persistence. Used inside the
+	 * {@link getOrCreateTopic} create callback to fail-closed before adopting a
+	 * user-created topic id.
+	 */
+	isTopicIdAvailable(topicId: string): boolean {
+		if (!isValidTopicId(topicId)) return false;
+		if (this.#ambiguousTopicIds.has(topicId)) return false;
+		if (this.byTopic.has(topicId)) return false;
+		for (const record of this.topics.values()) if (record.topicId === topicId) return false;
+		for (const record of this.staged.values()) if (record.topicId === topicId) return false;
+		return true;
+	}
 
 	/**
 	 * Resolve endpoint authority for identity-less replay. An endpoint may bootstrap
@@ -455,6 +473,7 @@ export class TopicRegistry {
 		binding?: TopicEndpointBinding,
 		commit?: () => Promise<void>,
 		transientClaimant?: object,
+		topicOrigin?: TopicRecord["topicOrigin"],
 	): Promise<TopicRecord> {
 		const existing = this.topics.get(sessionId);
 		if (existing?.authorityState === "delete_pending") throw new Error("topic authority is deletion-fenced");
@@ -491,6 +510,7 @@ export class TopicRegistry {
 						}
 					: {}),
 				...(revoked ? { authorityState: "delete_pending" as const } : {}),
+				...(topicOrigin === "user_created" ? { topicOrigin: "user_created" as const } : {}),
 			};
 			if (revoked) {
 				this.topics.set(sessionId, record);

package/src/sdk/host/query/revision-store.ts

@@ -2,6 +2,32 @@ import { createHash } from "node:crypto";
 import { chmod, mkdir, mkdtemp, open, readFile, rename, rm, unlink } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { postmortem } from "@gajae-code/utils";
+
+/**
+ * Spill directories this process created under the system temp dir.
+ *
+ * `close()` removes a store's own directory, but an abnormal exit never reaches
+ * it, and these hold real spilled snapshot data rather than a marker. The two
+ * sibling temp-artifact caches (`shell-snapshot`, `python-runner-artifact`)
+ * already register a postmortem sweep; this does the same.
+ *
+ * Only `mkdtemp` directories are tracked. A caller-supplied `storageDir` is
+ * durable session storage and must never be swept here.
+ */
+const processSpillDirectories = new Set<string>();
+
+/** Test seam: spill directories currently tracked for postmortem cleanup. */
+export function trackedSpillDirectoriesForTest(): string[] {
+	return [...processSpillDirectories];
+}
+
+postmortem.register("sdk-revision-store:spill", async () => {
+	for (const dir of [...processSpillDirectories]) {
+		processSpillDirectories.delete(dir);
+		await rm(dir, { recursive: true, force: true }).catch(() => undefined);
+	}
+});
 
 export const MAX_REVISIONS_PER_RESOURCE = 8;
 export const MAX_PINNED_REVISIONS = 128;
@@ -512,7 +538,10 @@ export class RevisionStore {
 			this.#memoryBytes = 0;
 			this.#chunkRefs.clear();
 			this.#manifestRefs.clear();
-			if (this.#directory) await rm(this.#directory, { recursive: true, force: true });
+			if (this.#directory) {
+				processSpillDirectories.delete(this.#directory);
+				await rm(this.#directory, { recursive: true, force: true });
+			}
 		})();
 		return this.#closePromise;
 	}
@@ -1040,7 +1069,12 @@ export class RevisionStore {
 	}
 
 	async #spillDirectory(): Promise<string> {
-		if (!this.#directory) this.#directory = await mkdtemp(join(tmpdir(), "gjc-sdk-snapshots-"));
+		if (!this.#directory) {
+			this.#directory = await mkdtemp(join(tmpdir(), "gjc-sdk-snapshots-"));
+			// Only temp spill directories are swept on abnormal exit; a caller-supplied
+			// storageDir is durable and never enters this set.
+			processSpillDirectories.add(this.#directory);
+		}
 		await mkdir(join(this.#directory, "objects"), { recursive: true, mode: 0o700 });
 		await mkdir(join(this.#directory, "manifests"), { recursive: true, mode: 0o700 });
 		await chmod(this.#directory, 0o700);

package/src/sdk/host/reverse-leases.ts

@@ -41,6 +41,8 @@ interface Outstanding {
 	leaseId: string;
 	resolve: (value: unknown) => void;
 	reject: (reason: Error) => void;
+	signal?: AbortSignal;
+	onAbort?: () => void;
 }
 
 export interface ReverseLeaseOptions {
@@ -188,7 +190,7 @@ export class ReverseLeaseRuntime {
 		this.#cancelForConnection(connectionId, "provider_disconnected");
 	}
 
-	request(capability: string, method: string, payload: unknown): Promise<unknown> {
+	request(capability: string, method: string, payload: unknown, signal?: AbortSignal): Promise<unknown> {
 		if (this.#disposing) throw new Error("reverse runtime is disposing");
 		this.#assertPayload(payload);
 		const lease = this.#liveLease(capability);
@@ -198,16 +200,42 @@ export class ReverseLeaseRuntime {
 				throw new ReverseLeaseError("lease_unavailable");
 			throw new ReverseLeaseError("provider_required");
 		}
+		if (signal?.aborted)
+			return Promise.reject(Object.assign(new Error("request_cancelled"), { name: "request_cancelled" }));
 		if (this.#outstanding.size >= MAX_REVERSE_OUTSTANDING) throw new ReverseLeaseError("too_many_outstanding");
 		const id = randomUUID();
 		return new Promise((resolve, reject) => {
-			this.#outstanding.set(id, {
+			const outstanding: Outstanding = {
 				connectionId: lease.connectionId,
 				capability,
 				leaseId: lease.leaseId,
 				resolve,
 				reject,
-			});
+				...(signal ? { signal } : {}),
+			};
+			this.#outstanding.set(id, outstanding);
+			if (signal) {
+				outstanding.onAbort = () => {
+					if (this.#takeOutstanding(id) !== outstanding) return;
+					try {
+						const cancellation = this.#sendFrame(lease.connectionId, {
+							type: "reverse_cancel",
+							id,
+							connectionId: lease.connectionId,
+							leaseId: lease.leaseId,
+						});
+						void Promise.resolve(cancellation).catch(() => {});
+					} catch {
+						// Cancellation is best effort; the caller is already settled locally.
+					}
+					reject(Object.assign(new Error("request_cancelled"), { name: "request_cancelled" }));
+				};
+				signal.addEventListener("abort", outstanding.onAbort, { once: true });
+				if (signal.aborted) {
+					outstanding.onAbort();
+					return;
+				}
+			}
 			let delivery: void | Promise<void>;
 			try {
 				delivery = this.#sendFrame(lease.connectionId, {
@@ -219,12 +247,12 @@ export class ReverseLeaseRuntime {
 					payload: { method, payload },
 				});
 			} catch (error) {
-				this.#outstanding.delete(id);
+				this.#takeOutstanding(id);
 				reject(error instanceof Error ? error : new Error(String(error)));
 				return;
 			}
 			Promise.resolve(delivery).catch(error => {
-				this.#outstanding.delete(id);
+				if (this.#takeOutstanding(id) !== outstanding) return;
 				reject(error instanceof Error ? error : new Error(String(error)));
 			});
 		});
@@ -242,7 +270,7 @@ export class ReverseLeaseRuntime {
 		if (!request) throw new ReverseLeaseError("unknown_request");
 		if (request.connectionId !== connectionId || request.leaseId !== leaseId)
 			throw new ReverseLeaseError("not_lease_owner");
-		this.#outstanding.delete(id);
+		this.#takeOutstanding(id);
 		if (error) {
 			const rejection = new Error(error.message);
 			rejection.name = error.code;
@@ -270,6 +298,8 @@ export class ReverseLeaseRuntime {
 		this.#installedCapabilities.clear();
 		this.#leases.clear();
 		this.#idempotency.clear();
+		for (const request of outstanding.map(([, request]) => request))
+			if (request.signal && request.onAbort) request.signal.removeEventListener("abort", request.onAbort);
 		for (const [id, request] of outstanding) {
 			request.reject(new Error("request_cancelled"));
 			try {
@@ -304,11 +334,18 @@ export class ReverseLeaseRuntime {
 	#cancelForConnection(connectionId: string, reason: "provider_disconnected" | "lease_released"): void {
 		for (const [id, request] of this.#outstanding)
 			if (request.connectionId === connectionId) {
-				this.#outstanding.delete(id);
+				this.#takeOutstanding(id);
 				request.reject(new Error("request_cancelled"));
 				this.#onCancel?.(id, reason);
 			}
 	}
+	#takeOutstanding(id: string): Outstanding | undefined {
+		const request = this.#outstanding.get(id);
+		if (!request) return undefined;
+		this.#outstanding.delete(id);
+		if (request.signal && request.onAbort) request.signal.removeEventListener("abort", request.onAbort);
+		return request;
+	}
 	#installDefinitionsFor(capability: string, definitions: unknown): void {
 		this.#installDefinitions?.(capability, definitions);
 		this.#installedCapabilities.add(capability);

package/src/sdk/prompt-status.ts

@@ -17,8 +17,10 @@
  *   prior outcome unknown — callers MUST NOT reuse a clientRef as a retry
  *   mechanism and MUST treat `unknown` as uncertainty, not proof of
  *   non-execution.
- * - The durability floor is the live session process: after restart or
- *   retained-record eviction, a lookup honestly reports `unknown`.
+ * - 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.
  * - 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.
@@ -38,8 +40,17 @@ export interface TurnPromptInput {
 	clientRef?: string;
 }
 
-/** Terminal outcome is preserved exactly; active records never age into terminal. */
+/**
+ * Terminal outcome is preserved exactly; active records never age into terminal. A
+ * 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.
+ */
 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";
+export type SdkPromptTerminalOutcome =
+	| { kind: "stopped"; reason: SdkPromptStopReason; provenance: "agent" | "client_cancel" }
+	| { kind: "failed"; code: SdkPromptFailureCode; message: string; provenance: "agent_failed" | "deadline" };
 
 /** Exactly one selector per lookup. */
 export type TurnPromptStatusSelector = { clientRef: string } | { commandId: string; turnId: string };
@@ -67,6 +78,7 @@ export interface TurnPromptReconciliationTerminalOk extends TurnPromptReconcilia
 	startedAt?: number;
 	/** Epoch milliseconds of the terminal transition. */
 	terminalAt: number;
+	outcome?: SdkPromptTerminalOutcome;
 }
 
 export interface TurnPromptReconciliationFailed extends TurnPromptReconciliationIdentity {
@@ -75,6 +87,7 @@ export interface TurnPromptReconciliationFailed extends TurnPromptReconciliation
 	terminalAt: number;
 	/** Bounded, sanitized failure detail (code safe-token ≤64, message ≤512). */
 	error: { code: string; message: string };
+	outcome?: SdkPromptTerminalOutcome;
 }
 
 export interface TurnPromptReconciliationUnknown {

package/src/sdk/protocol/operation-inventory.generated.json

@@ -2531,6 +2531,17 @@
 			"testIds": "not_applicable"
 		}
 	},
+	{
+		"sourceId": "agent_session:registerToolSessionCleanup",
+		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
+		"sourceKind": "agent_session",
+		"decision": "exclude",
+		"rationale": "internal tool lifecycle cleanup registration, not a user-facing SDK control seam",
+		"exclusionMetadata": {
+			"adapterMappings": "not_applicable",
+			"testIds": "not_applicable"
+		}
+	},
 	{
 		"sourceId": "agent_session:getAsyncJobSnapshot",
 		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
@@ -3656,6 +3667,17 @@
 			"packages/coding-agent/test/sdk-operation-inventory.test.ts"
 		]
 	},
+	{
+		"sourceId": "agent_session:abortPromptAndWait",
+		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
+		"sourceKind": "agent_session",
+		"decision": "exclude",
+		"rationale": "internal SDK prompt-terminalization resource fence over a host-captured run handle, not an independent public SDK control seam",
+		"exclusionMetadata": {
+			"adapterMappings": "not_applicable",
+			"testIds": "not_applicable"
+		}
+	},
 	{
 		"sourceId": "agent_session:cancelAndSubmit",
 		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
@@ -3852,6 +3874,17 @@
 			"testIds": "not_applicable"
 		}
 	},
+	{
+		"sourceId": "agent_session:resolveConfiguredDefaultModel",
+		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
+		"sourceKind": "agent_session",
+		"decision": "exclude",
+		"rationale": "internal accessor/plumbing, not a user-facing control seam",
+		"exclusionMetadata": {
+			"adapterMappings": "not_applicable",
+			"testIds": "not_applicable"
+		}
+	},
 	{
 		"sourceId": "agent_session:recordResumeDefaultModel",
 		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",