@sayknow-cli/coding-agent 0.4.6 → 0.5.0

package/src/sdk/bus/config.ts

@@ -170,7 +170,7 @@ export function parseNotificationSettingsSnapshot(rawConfig?: unknown): Notifica
 				enabled: notificationSettingsBoolean(richDraft.enabled, false),
 			},
 			toolActivity: {
-				enabled: notificationSettingsBoolean(toolActivity.enabled, true),
+				enabled: notificationSettingsBoolean(toolActivity.enabled, false),
 			},
 			streaming: {
 				enabled: notificationSettingsBoolean(streaming.enabled, true),
@@ -540,6 +540,8 @@ export interface RedactableAction {
 	question?: string;
 	options?: string[];
 	summary?: string;
+	/** Optional zero-based recommendation into the authoritative raw options. */
+	recommendedIndex?: number;
 }
 
 /**
@@ -563,6 +565,12 @@ export function buildRedactedAction(
 	// Asks stay fully readable/answerable even under redaction.
 	if (action.kind === "ask") return action;
 
-	const { summary: _summary, question: _question, options: _options, ...base } = action;
+	const {
+		summary: _summary,
+		question: _question,
+		options: _options,
+		recommendedIndex: _recommendedIndex,
+		...base
+	} = action;
 	return base;
 }

package/src/sdk/bus/control-drain-lease.ts

@@ -0,0 +1,104 @@
+/**
+ * Ordering seam for an in-band SDK identity transition.
+ *
+ * A request arrives through predecessor A, so a successful terminal response cannot
+ * be published until successor B is ready. Native builds may provide a true
+ * send-only connection lease; source/dev builds use the conservative fallback in
+ * which the predecessor server remains alive until the terminal write completes.
+ */
+
+export type TerminalSendOutcome = "written" | "disconnected" | "write_failed";
+
+/** Fence/capability hooks may return false to reject; undefined means ok. */
+export type IdentityControlGateResult = boolean | undefined;
+export type IdentityControlGate = () => IdentityControlGateResult | Promise<IdentityControlGateResult>;
+
+export interface IdentityControlSuccessPathInput {
+	/** Fence predecessor inbound work. The fence must not close its response writer. */
+	fence: IdentityControlGate;
+	/** Optional explicit proof that the predecessor writer is still usable. */
+	ensurePredecessorSendCapable?: IdentityControlGate;
+	/** Start successor B and resolve only after its public endpoint is ready. */
+	startSuccessor: () => Promise<void>;
+	/** Write and flush either the success or non-success terminal response. */
+	sendTerminal: () => Promise<TerminalSendOutcome>;
+	/** Release predecessor A after the terminal response has settled. */
+	stopPredecessor: () => Promise<void>;
+	/** Set only when a caller cannot use the retained-writer fallback. */
+	requireNativeControlDrain?: boolean;
+}
+
+export interface IdentityControlTerminalPathInput {
+	fenceInbound: IdentityControlGate;
+	ensurePredecessorSendCapable?: IdentityControlGate;
+	startSuccessorReady: () => Promise<void>;
+	sendTerminal: () => Promise<TerminalSendOutcome>;
+	stopPredecessor: () => Promise<void>;
+	requireNativeControlDrain?: boolean;
+}
+
+/**
+ * Probe the loaded native addon, never an environment flag or a TypeScript shim.
+ * Older/source installs intentionally report false so callers can select the
+ * retained-writer fallback or fail closed when detach is mandatory.
+ */
+export function isNativeControlDrainAvailable(): boolean {
+	try {
+		// Keep the addon lazy: importing the bus must continue to work without a
+		// compiled native artifact (tests and source distributions do that often).
+		// eslint-disable-next-line @typescript-eslint/no-require-imports
+		const natives = require("@sayknow-cli/natives") as {
+			NotificationServer?: {
+				prototype?: Record<string, unknown>;
+			};
+		};
+		const prototype = natives.NotificationServer?.prototype;
+		return (
+			typeof prototype?.acquireControlDrain === "function" &&
+			typeof prototype?.sendTerminalAndWait === "function" &&
+			typeof prototype?.closeControlDrain === "function"
+		);
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Run the only safe ordering for a successful identity-control response.
+ *
+ * The `finally` is deliberately around both successor startup and terminal
+ * delivery: a failed startup must not leave the fenced predecessor alive, and a
+ * failed/disconnected terminal write must still release it. When native detach
+ * is unavailable the caller is expected to keep A's server up (not call
+ * `stopAndWait`) until `sendTerminal` settles.
+ */
+export async function runIdentityControlSuccessPath(
+	input: IdentityControlSuccessPathInput,
+): Promise<TerminalSendOutcome> {
+	if (input.requireNativeControlDrain && !isNativeControlDrainAvailable())
+		throw new Error("SDK identity control requires the native control-drain lease.");
+
+	if ((await input.fence()) === false) throw new Error("SDK identity control predecessor fence was not acquired.");
+	if ((await input.ensurePredecessorSendCapable?.()) === false)
+		throw new Error("SDK identity control predecessor writer is not send-capable.");
+	try {
+		await input.startSuccessor();
+		return await input.sendTerminal();
+	} finally {
+		await input.stopPredecessor();
+	}
+}
+
+/** Compatibility spelling used by the host wiring design notes. */
+export async function runIdentityControlTerminalPath(
+	input: IdentityControlTerminalPathInput,
+): Promise<TerminalSendOutcome> {
+	return runIdentityControlSuccessPath({
+		fence: input.fenceInbound,
+		ensurePredecessorSendCapable: input.ensurePredecessorSendCapable,
+		startSuccessor: input.startSuccessorReady,
+		sendTerminal: input.sendTerminal,
+		stopPredecessor: input.stopPredecessor,
+		requireNativeControlDrain: input.requireNativeControlDrain,
+	});
+}

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

@@ -92,6 +92,7 @@ export class ConversationStore<T extends ConversationRecord> {
 	readonly #pidAlive: (pid: number) => boolean;
 	readonly #sleep: (ms: number) => Promise<void>;
 	readonly #lockTimeoutMs: number;
+	readonly #platform: NodeJS.Platform;
 
 	constructor(input: {
 		agentDir: string;
@@ -104,6 +105,7 @@ export class ConversationStore<T extends ConversationRecord> {
 		pidAlive?: (pid: number) => boolean;
 		sleep?: (ms: number) => Promise<void>;
 		lockTimeoutMs?: number;
+		platform?: NodeJS.Platform;
 	}) {
 		this.#file = conversationStorePath(input.agentDir, input.kind, input.fileName);
 		this.#directory = path.dirname(this.#file);
@@ -114,6 +116,7 @@ export class ConversationStore<T extends ConversationRecord> {
 		this.#pidAlive = input.pidAlive ?? defaultPidAlive;
 		this.#sleep = input.sleep ?? (async ms => await Bun.sleep(ms));
 		this.#lockTimeoutMs = input.lockTimeoutMs ?? 1_000;
+		this.#platform = input.platform ?? process.platform;
 	}
 
 	get filePath(): string {
@@ -325,12 +328,7 @@ export class ConversationStore<T extends ConversationRecord> {
 				await handle.close();
 			}
 			await this.#fs.rename(temporary, this.#file);
-			const directory = await this.#fs.open(this.#directory, "r");
-			try {
-				await directory.sync();
-			} finally {
-				await directory.close();
-			}
+			await syncParentDirectory(this.#fs, this.#directory, this.#platform);
 		} catch (error) {
 			await this.#fs.unlink(temporary).catch(() => undefined);
 			throw error;
@@ -342,6 +340,42 @@ function isMissing(error: unknown): error is NodeJS.ErrnoException {
 	return isRecord(error) && error.code === "ENOENT";
 }
 
+async function syncParentDirectory(
+	fs: ConversationStoreFs,
+	directory: string,
+	platform: NodeJS.Platform,
+): Promise<void> {
+	let handle: ConversationStoreFileHandle;
+	try {
+		handle = await fs.open(directory, "r");
+	} catch (error) {
+		if (platform === "win32" && isUnsupportedDirectoryBarrierError(error)) return;
+		throw error;
+	}
+	let syncError: unknown;
+	try {
+		await handle.sync();
+	} catch (error) {
+		if (!(platform === "win32" && isUnsupportedDirectoryBarrierError(error))) syncError = error;
+	}
+	let closeError: unknown;
+	try {
+		await handle.close();
+	} catch (error) {
+		closeError = error;
+	}
+	if (syncError && closeError)
+		throw new AggregateError([syncError, closeError], "Parent directory sync and close failed");
+	if (syncError) throw syncError;
+	if (closeError) throw closeError;
+}
+
+function isUnsupportedDirectoryBarrierError(error: unknown): boolean {
+	return (
+		isRecord(error) &&
+		(error.code === "EINVAL" || error.code === "ENOTSUP" || error.code === "EOPNOTSUPP" || error.code === "EPERM")
+	);
+}
 function isAlreadyExists(error: unknown): error is NodeJS.ErrnoException {
 	return isRecord(error) && error.code === "EEXIST";
 }

package/src/sdk/bus/daemon-paths.ts

@@ -12,6 +12,7 @@ export interface DaemonPaths {
 	dir: string;
 	lock: string;
 	state: string;
+	heartbeat: string;
 	ownership: string;
 	roots: string;
 	steal: string;
@@ -26,6 +27,7 @@ export function daemonPaths(agentDir: string): DaemonPaths {
 		lock: path.join(dir, "telegram-daemon.lock"),
 		state: path.join(dir, "telegram-daemon.state.json"),
 		ownership: path.join(dir, "telegram-daemon.ownership"),
+		heartbeat: path.join(dir, "telegram-daemon.heartbeat.json"),
 		roots: path.join(dir, "telegram-daemon.roots.json"),
 		steal: path.join(dir, "telegram-daemon.steal"),
 		aliases: path.join(dir, "telegram-callback-aliases.json"),