@sayknow-cli/coding-agent 0.3.0 → 0.3.2

package/src/notifications/index.ts

@@ -12,7 +12,7 @@
  * - `ask` (unattended/RPC): observes emitted workflow gates and resolves the real
  *   gate on a remote reply via `ctx.workflowGate`.
  * - `turn_end` -> `action_needed` (kind `idle`, deduped per turn).
- * - `session_shutdown` -> stop the server + deregister the answer source.
+ * - `session_shutdown` -> `session_closed` frame, stop server, deregister answer source.
  *
  * Enable with Settings notifications config, `SKC_NOTIFICATIONS=1` (a token is
  * generated), or `SKC_NOTIFICATIONS_TOKEN`.
@@ -24,11 +24,13 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { promisify } from "node:util";
+import type { ImageContent, TextContent } from "@sayknow-cli/ai";
 import { NotificationServer } from "@sayknow-cli/natives";
 import { logger } from "@sayknow-cli/utils";
 import { Settings } from "../config/settings";
 import type { ExtensionCommandContext, ExtensionContext, ExtensionFactory } from "../extensibility/extensions";
 import { registerAskAnswerSource } from "../tools/ask-answer-registry";
+import { registerTelegramFileSink } from "./attachment-registry";
 import {
 	getNotificationConfig,
 	isGloballyConfigured,
@@ -39,6 +41,193 @@ import {
 import { imageAttachmentsFromMessage, notificationActionPayload, summaryFromMessage } from "./helpers";
 import { ensureTelegramDaemonRunning } from "./telegram-daemon";
 
+// ===========================================================================
+// Session lifecycle control protocol (TypeScript mirror of the Rust wire
+// contract in `crates/skc-notifications/src/lifecycle.rs`).
+//
+// These describe the frames exchanged over the daemon-owned, session-independent
+// control endpoint for remote session create / close / resume. Field names are
+// camelCase on the wire; `type`/`kind` discriminators are snake_case. The Rust
+// ingress authenticates and forwards; the daemon (TypeScript) owns all policy,
+// spawn orchestration, idempotency, rate limiting, audit, and UX.
+// ===========================================================================
+
+/** Where a `session_create` should run. Discriminated by `kind`. */
+export type SessionCreateTarget =
+	| { kind: "existing_path"; path: string }
+	| { kind: "worktree"; repo: string; branch: string }
+	| { kind: "plain_dir"; path: string };
+
+/** Identifies the session a `session_close` targets. */
+export interface SessionCloseTarget {
+	sessionId: string;
+	/** Expected SKC-managed tmux session name (defense-in-depth match). */
+	tmuxSession?: string;
+	/** Expected `@skc-session-state-file` tag (defense-in-depth match). */
+	sessionStateFile?: string;
+}
+
+/** Identifies the session a `session_resume` targets. */
+export interface SessionResumeTarget {
+	sessionIdOrPrefix: string;
+	/** Optional repo/working-dir hint to disambiguate matches. */
+	path?: string;
+}
+
+/** Create a new session. */
+export interface SessionCreateFrame {
+	type: "session_create";
+	requestId: string;
+	/** Deterministic lifecycle marker preallocated by the daemon before spawn. */
+	lifecycleRequestId: string;
+	/** Session id the daemon preallocated and propagates to the child. */
+	intendedSessionId: string;
+	/** Telegram update id (idempotency key on the daemon side). */
+	updateId: number;
+	chatId: string;
+	/** Control-endpoint token authorizing this frame. */
+	token: string;
+	target: SessionCreateTarget;
+	/** Reference to the daemon-written, once-consumed startup-prompt file. */
+	startupPromptRef?: string;
+}
+
+/** Close (hard-kill, history preserved) a session. */
+export interface SessionCloseFrame {
+	type: "session_close";
+	requestId: string;
+	updateId: number;
+	chatId: string;
+	token: string;
+	target: SessionCloseTarget;
+	/** Hard-kill even if a live pane is attached (SKC-managed only). */
+	force?: boolean;
+}
+
+/** Resume a session (reattach if alive, else cold-restart from history). */
+export interface SessionResumeFrame {
+	type: "session_resume";
+	requestId: string;
+	updateId: number;
+	chatId: string;
+	token: string;
+	target: SessionResumeTarget;
+	startupPromptRef?: string;
+}
+
+/** Any client -> ingress lifecycle request frame. */
+export type SessionLifecycleRequest = SessionCreateFrame | SessionCloseFrame | SessionResumeFrame;
+
+/** Terminal status of a lifecycle request. */
+export type LifecycleStatus = "ok" | "error";
+
+/** A connected session's per-session endpoint, returned to the control client. */
+export interface LifecycleEndpoint {
+	url: string;
+	token: string;
+}
+
+/** The Telegram topic/thread a session is surfaced in. */
+export interface LifecycleTopic {
+	chatId: string;
+	threadId: string;
+}
+
+/** How a create request was correlated to its spawned session. */
+export type MatchedBy = "spawn_marker" | "session_ready";
+
+/** Response to a successful `session_create`. */
+export interface SessionCreateResponseFrame {
+	type: "session_create_response";
+	requestId: string;
+	status: LifecycleStatus;
+	lifecycleRequestId: string;
+	sessionId: string;
+	matchedBy: MatchedBy;
+	endpoint: LifecycleEndpoint;
+	topic: LifecycleTopic;
+	target: SessionCreateTarget;
+}
+
+/** Response to a successful `session_close`. */
+export interface SessionCloseResponseFrame {
+	type: "session_close_response";
+	requestId: string;
+	status: LifecycleStatus;
+	sessionId: string;
+	processGone: boolean;
+	historyPreserved: boolean;
+	endpointStale: boolean;
+}
+
+/** Whether a resume reattached to a live session or cold-restarted a dead one. */
+export type ResumeMode = "reattached" | "cold_restarted";
+
+/** Response to a successful `session_resume`. */
+export interface SessionResumeResponseFrame {
+	type: "session_resume_response";
+	requestId: string;
+	status: LifecycleStatus;
+	sessionId: string;
+	mode: ResumeMode;
+	endpoint: LifecycleEndpoint;
+	topic: LifecycleTopic;
+}
+
+/** Machine-readable reason a lifecycle request failed. */
+export type LifecycleErrorReason =
+	| "unauthorized"
+	| "rate_limited"
+	| "duplicate_conflict"
+	| "invalid_target"
+	| "ambiguous_target"
+	| "spawn_failed"
+	| "discovery_timeout"
+	| "readiness_timeout"
+	| "close_refused"
+	| "not_found"
+	| "terminal_uncertain";
+
+/** A candidate returned with an `ambiguous_target` resume error. */
+export interface ResumeCandidate {
+	sessionId: string;
+	path?: string;
+	/** Last-activity epoch-millis (session history file mtime), if known. */
+	mtimeMs?: number;
+}
+
+/** A structured lifecycle error frame. */
+export interface SessionLifecycleErrorFrame {
+	type: "session_lifecycle_error";
+	requestId: string;
+	status: LifecycleStatus;
+	reason: LifecycleErrorReason;
+	message: string;
+	candidates?: ResumeCandidate[];
+}
+
+/** Any ingress -> client lifecycle response frame. */
+export type SessionLifecycleResponse =
+	| SessionCreateResponseFrame
+	| SessionCloseResponseFrame
+	| SessionResumeResponseFrame
+	| SessionLifecycleErrorFrame;
+
+/**
+ * Replayable per-session readiness signal (mirror of the Rust `session_ready`
+ * frame). Buffered and replayed to late clients so WS-open alone never implies
+ * the session is live and surfaced.
+ */
+export interface SessionReadyFrame {
+	type: "session_ready";
+	sessionId: string;
+	lifecycleRequestId?: string;
+	startupPromptRef?: string;
+	repo?: string;
+	branch?: string;
+	title?: string;
+}
+
 /** Resolve the git dir for `cwd`, handling worktrees where `.git` is a file. */
 function gitDir(cwd: string): string | undefined {
 	const dot = path.join(cwd, ".git");
@@ -136,7 +325,10 @@ interface SessionRuntime {
 	pendingInteractive: Map<string, PendingInteractiveAsk>;
 	/** Deregisters this session's ask answer source. */
 	disposeAnswerSource: () => void;
+	/** Deregisters this session's Telegram file sink. */
+	disposeFileSink: () => void;
 	redact: boolean;
+	verbosity: "lean" | "verbose";
 	sessionTag: string;
 	/** Whether the agent loop is currently running (drives the typing indicator). */
 	busy: boolean;
@@ -157,6 +349,16 @@ interface ResolvedSettings {
 
 const defaultConfig: NotificationConfig = {
 	enabled: false,
+	botToken: undefined,
+	chatId: undefined,
+	discord: {
+		botToken: undefined,
+		channelId: undefined,
+	},
+	slack: {
+		botToken: undefined,
+		channelId: undefined,
+	},
 	redact: false,
 	verbosity: "lean",
 	idleTimeoutMs: 60_000,
@@ -228,21 +430,81 @@ function mapAnswerToGate(
 	return { selected: [] };
 }
 
+/** Register the interactive `ask` answer source for a session (the ask tool
+ * races the local UI against a remote reply). Returns the deregister disposer. */
+function registerInteractiveAnswerSource(
+	id: string,
+	server: NotificationServer,
+	pendingInteractive: Map<string, PendingInteractiveAsk>,
+	getRedact: () => boolean,
+	tag: string,
+): () => void {
+	return registerAskAnswerSource(id, {
+		awaitAnswer(question, options, signal) {
+			if (signal?.aborted) return Promise.resolve(undefined);
+			const askId = `ask:${crypto.randomUUID()}`;
+			try {
+				server.registerAsk(
+					JSON.stringify(
+						notificationActionPayload(
+							{ id: askId, kind: "ask", sessionId: id, question, options },
+							{ redact: getRedact(), sessionTag: tag },
+						),
+					),
+					true,
+				);
+			} catch (e) {
+				logger.warn(`notifications: registerAsk failed: ${String(e)}`);
+				return Promise.resolve(undefined);
+			}
+			return new Promise<string | undefined>(resolve => {
+				pendingInteractive.set(askId, { resolve, options });
+				signal?.addEventListener("abort", () => {
+					if (!pendingInteractive.delete(askId)) return;
+					// Local UI answered: mark the remote action resolved-locally.
+					try {
+						server.resolveLocal(askId, undefined);
+					} catch {}
+					resolve(undefined);
+				});
+			});
+		},
+	});
+}
+
+/** Extract the session id from a `<timestamp>_<uuid>.jsonl` session file path. */
+function sessionIdFromFile(file: string | undefined): string | undefined {
+	if (!file) return undefined;
+	const base = path.basename(file).replace(/\.jsonl$/, "");
+	const underscore = base.indexOf("_");
+	return underscore >= 0 ? base.slice(underscore + 1) : undefined;
+}
+
 export const createNotificationsExtension: ExtensionFactory = api => {
 	const runtimes = new Map<string, SessionRuntime>();
 	const disabledSessions = new Set<string>();
 	const sessionId = (ctx: ExtensionContext): string => ctx.sessionManager.getSessionId();
+	const sleep = (ms: number): Promise<void> => new Promise(resolve => setTimeout(resolve, ms));
 
-	function stopSession(id: string): boolean {
+	async function stopSession(id: string): Promise<boolean> {
 		const rt = runtimes.get(id);
 		if (!rt) return false;
 		runtimes.delete(id);
 		try {
 			rt.disposeAnswerSource();
+			rt.disposeFileSink();
 		} catch {}
 		// Resolve any still-pending interactive asks so the ask tool is not left hanging.
 		for (const pending of rt.pendingInteractive.values()) pending.resolve(undefined);
 		rt.pendingInteractive.clear();
+		let closeFrameSent = false;
+		try {
+			rt.server.pushFrame(JSON.stringify({ type: "session_closed", sessionId: id }));
+			closeFrameSent = true;
+		} catch (e) {
+			logger.warn(`notifications: session_closed failed: ${String(e)}`);
+		}
+		if (closeFrameSent) await sleep(100);
 		try {
 			rt.server.stop();
 		} catch (e) {
@@ -271,6 +533,8 @@ export const createNotificationsExtension: ExtensionFactory = api => {
 		const pendingInteractive = new Map<string, PendingInteractiveAsk>();
 		const tag = sessionTag(id);
 		const redact = cfg.redact;
+		const verbosity = cfg.verbosity;
+		let runtime: SessionRuntime | undefined;
 
 		// The SDK can always answer now (interactive via the answer source, or the
 		// unattended gate), so the endpoint advertises a resolver.
@@ -317,23 +581,58 @@ export const createNotificationsExtension: ExtensionFactory = api => {
 		// thread (forwarded by the daemon over the WS, fail-closed at the daemon).
 		server.onInbound((err, inbound) => {
 			if (err || !inbound) return;
-			if (inbound.kind === "user_message" && inbound.text) {
+			if (inbound.kind === "user_message") {
 				// Inject as a user turn (steers/continues the agent; the resulting
 				// turn streams back via the turn_end handler even when not idle).
 				// Record the update id so it can be acked as "consumed" on the next
 				// turn_start, and steer (vs start a fresh turn) when already busy.
-				const rt = runtimes.get(id);
-				if (rt && typeof inbound.updateId === "number") rt.pendingInbound.add(inbound.updateId);
+				const text = inbound.text ?? "";
+				const images = inbound.images ?? [];
+				if (!text && images.length === 0) return;
+				if (runtime && typeof inbound.updateId === "number") runtime.pendingInbound.add(inbound.updateId);
+				const content: string | (TextContent | ImageContent)[] =
+					images.length > 0
+						? [
+								...(text ? [{ type: "text", text } as TextContent] : []),
+								...images.map(
+									img =>
+										({ type: "image", data: img.data, mimeType: img.mime ?? "image/jpeg" }) as ImageContent,
+								),
+							]
+						: text;
 				try {
-					api.sendUserMessage(inbound.text, rt?.busy ? { deliverAs: "steer" } : undefined);
+					api.sendUserMessage(content, runtime?.busy ? { deliverAs: "steer" } : undefined);
 				} catch (e) {
 					logger.warn(`notifications: sendUserMessage failed: ${String(e)}`);
 				}
 				return;
 			}
 			if (inbound.kind === "config_command") {
-				const rt = runtimes.get(id);
-				if (rt && typeof inbound.redact === "boolean") rt.redact = inbound.redact;
+				if (!runtime) return;
+				const update: {
+					type: "config_update";
+					sessionId: string;
+					verbosity?: "lean" | "verbose";
+					redact?: boolean;
+				} = {
+					type: "config_update",
+					sessionId: id,
+				};
+				if (inbound.verbosity === "lean" || inbound.verbosity === "verbose") {
+					runtime.verbosity = inbound.verbosity;
+					update.verbosity = inbound.verbosity;
+				}
+				if (typeof inbound.redact === "boolean") {
+					runtime.redact = inbound.redact;
+					update.redact = inbound.redact;
+				}
+				if (update.verbosity !== undefined || update.redact !== undefined) {
+					try {
+						runtime.server.pushFrame(JSON.stringify(update));
+					} catch (e) {
+						logger.warn(`notifications: config_update failed: ${String(e)}`);
+					}
+				}
 			}
 		});
 
@@ -341,48 +640,44 @@ export const createNotificationsExtension: ExtensionFactory = api => {
 			const endpoint = await server.start();
 
 			// Interactive answer source: the ask tool races the local UI against this.
-			const disposeAnswerSource = registerAskAnswerSource(id, {
-				awaitAnswer(question, options, signal) {
-					if (signal?.aborted) return Promise.resolve(undefined);
-					const askId = `ask:${crypto.randomUUID()}`;
-					try {
-						server.registerAsk(
-							JSON.stringify(
-								notificationActionPayload(
-									{ id: askId, kind: "ask", sessionId: id, question, options },
-									{ redact, sessionTag: tag },
-								),
-							),
-							true,
-						);
-					} catch (e) {
-						logger.warn(`notifications: registerAsk failed: ${String(e)}`);
-						return Promise.resolve(undefined);
-					}
-					return new Promise<string | undefined>(resolve => {
-						pendingInteractive.set(askId, { resolve, options });
-						signal?.addEventListener("abort", () => {
-							if (!pendingInteractive.delete(askId)) return;
-							// Local UI answered: mark the remote action resolved-locally.
-							try {
-								server.resolveLocal(askId, undefined);
-							} catch {}
-							resolve(undefined);
-						});
-					});
-				},
+			const disposeAnswerSource = registerInteractiveAnswerSource(
+				id,
+				server,
+				pendingInteractive,
+				() => runtime?.redact ?? redact,
+				tag,
+			);
+			const disposeFileSink = registerTelegramFileSink(id, async file => {
+				try {
+					const data = await fs.promises.readFile(file.path);
+					server.pushFrame(
+						JSON.stringify({
+							type: "file_attachment",
+							sessionId: id,
+							name: path.basename(file.path),
+							data: data.toString("base64"),
+							caption: file.caption,
+						}),
+					);
+					return { ok: true };
+				} catch (e) {
+					return { ok: false, error: e instanceof Error ? e.message : String(e) };
+				}
 			});
 
-			runtimes.set(id, {
+			runtime = {
 				server,
 				idleSeq: 0,
 				pendingInteractive,
 				disposeAnswerSource,
+				disposeFileSink,
 				redact,
+				verbosity,
 				sessionTag: tag,
 				busy: false,
 				pendingInbound: new Set<number>(),
-			});
+			};
+			runtimes.set(id, runtime);
 			logger.info(`notifications: serving session ${id} at ${endpoint.url} (unattended=${unattended})`);
 
 			if (settingsAvailable && settings && isGloballyConfigured(cfg)) {
@@ -453,7 +748,7 @@ export const createNotificationsExtension: ExtensionFactory = api => {
 
 			if (command === "off") {
 				disabledSessions.add(id);
-				const stopped = stopSession(id);
+				const stopped = await stopSession(id);
 				ctx.ui.notify(
 					stopped
 						? "Notifications disabled for this session."
@@ -501,8 +796,9 @@ export const createNotificationsExtension: ExtensionFactory = api => {
 			const running = runtimes.has(id);
 			const locallyDisabled = disabledSessions.has(id);
 			const enabled = isEnabledForSession(id, resolved.cfg);
+			const runtime = runtimes.get(id);
 			ctx.ui.notify(
-				`Notifications ${running ? "running" : enabled ? "enabled" : "disabled"} for this session; redaction ${resolved.cfg.redact ? "on" : "off"}${locallyDisabled ? "; locally off" : ""}.`,
+				`Notifications ${running ? "running" : enabled ? "enabled" : "disabled"} for this session; redaction ${(runtime?.redact ?? resolved.cfg.redact) ? "on" : "off"}; verbosity ${runtime?.verbosity ?? resolved.cfg.verbosity}${locallyDisabled ? "; locally off" : ""}.`,
 				"info",
 			);
 		},
@@ -512,6 +808,82 @@ export const createNotificationsExtension: ExtensionFactory = api => {
 		await startSession(ctx);
 	});
 
+	// A session id change within the same process needs reason-aware handling.
+	// `/new` and fork CONTINUE the same terminal thread (e.g. plan "approve and
+	// execute" clears into a fresh session), so re-key the existing runtime
+	// old→new WITHOUT recreating the NotificationServer: the server, its endpoint
+	// discovery file, and the daemon's forum topic are all keyed by the original
+	// session id and the daemon routes by socket, so the existing topic is reused
+	// and the next identity frame renames it in place instead of spawning a new
+	// thread. `resume`, by contrast, loads a DIFFERENT, already-persisted session
+	// that owns its own topic — tear the previous runtime down and start fresh
+	// under the resumed id so the daemon attaches to (or recreates) that
+	// session's own discovery + topic rather than hijacking this terminal's.
+	api.on("session_switch", async (event, ctx) => {
+		const newId = sessionId(ctx);
+		const prevId = sessionIdFromFile(event.previousSessionFile);
+		if (!prevId || prevId === newId) return;
+
+		if (event.reason === "resume") {
+			stopSession(prevId);
+			await startSession(ctx);
+			return;
+		}
+
+		// `/new` / fork: re-key in place and rename the existing topic.
+		if (disabledSessions.delete(prevId)) disabledSessions.add(newId);
+		const rt = runtimes.get(prevId);
+		if (!rt || runtimes.has(newId)) return;
+		runtimes.delete(prevId);
+		runtimes.set(newId, rt);
+		// Re-bind the interactive ask answer source: the ask tool resolves the
+		// source by the current session id, which just changed.
+		try {
+			rt.disposeAnswerSource();
+			rt.disposeFileSink();
+		} catch {}
+		rt.disposeAnswerSource = registerInteractiveAnswerSource(
+			newId,
+			rt.server,
+			rt.pendingInteractive,
+			() => rt.redact,
+			rt.sessionTag,
+		);
+		rt.disposeFileSink = registerTelegramFileSink(newId, async file => {
+			try {
+				const data = await fs.promises.readFile(file.path);
+				rt.server.pushFrame(
+					JSON.stringify({
+						type: "file_attachment",
+						sessionId: newId,
+						name: path.basename(file.path),
+						data: data.toString("base64"),
+						caption: file.caption,
+					}),
+				);
+				return { ok: true };
+			} catch (e) {
+				return { ok: false, error: e instanceof Error ? e.message : String(e) };
+			}
+		});
+		// Rename the existing topic now when the new session already has a name; a
+		// fresh unnamed session is renamed on its next agent_end re-assert, which
+		// avoids a transient rename to bare "repo/branch".
+		if (ctx.sessionManager.getSessionName()) {
+			try {
+				rt.server.pushFrame(
+					JSON.stringify({
+						type: "identity_header",
+						sessionId: newId,
+						...buildIdentity(ctx.cwd, ctx.sessionManager.getSessionName()),
+					}),
+				);
+			} catch (e) {
+				logger.warn(`notifications: identity_header (switch) failed: ${String(e)}`);
+			}
+		}
+	});
+
 	// Drive the live typing indicator: mark busy when the agent loop starts so
 	// the daemon shows "typing…" in the thread while the agent is thinking,
 	// before any turn output exists. Cleared on `agent_end` below.
@@ -593,7 +965,7 @@ export const createNotificationsExtension: ExtensionFactory = api => {
 		// On idle, stream a context update with metadata (token/model usage +
 		// working-tree diff) unless redaction is on. The agent's last message is
 		// NOT repeated here — it is already streamed once via `turn_stream`.
-		if (!rt.redact) {
+		if (!rt.redact && rt.verbosity === "verbose") {
 			const usage = (
 				ctx as { getContextUsage?: () => { tokens: number | null; contextWindow: number } | undefined }
 			).getContextUsage?.();
@@ -694,7 +1066,7 @@ export const createNotificationsExtension: ExtensionFactory = api => {
 		}
 	});
 
-	api.on("session_shutdown", (_event, ctx) => {
-		stopSession(sessionId(ctx));
+	api.on("session_shutdown", async (_event, ctx) => {
+		await stopSession(sessionId(ctx));
 	});
 };