@sayknow-cli/coding-agent 0.3.7 → 0.3.8

package/src/notifications/index.ts

@@ -28,13 +28,13 @@ import type { ImageContent, TextContent } from "@sayknow-cli/ai";
 import { NotificationServer } from "@sayknow-cli/natives";
 import { logger, postmortem } from "@sayknow-cli/utils";
 import { Settings } from "../config/settings";
-import type { ExtensionCommandContext, ExtensionContext, ExtensionFactory } from "../extensibility/extensions";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "../extensibility/extensions";
 import { registerAskAnswerSource } from "../tools/ask-answer-registry";
 import { registerTelegramFileSink } from "./attachment-registry";
 import {
 	getNotificationConfig,
-	isGloballyConfigured,
 	isSessionNotificationsEnabled,
+	isTelegramConfigured,
 	type NotificationConfig,
 	sessionTag,
 } from "./config";
@@ -100,7 +100,7 @@ export interface SessionCloseFrame {
 	chatId: string;
 	token: string;
 	target: SessionCloseTarget;
-	/** Hard-kill even if a live pane is attached (SKC-managed only). */
+	/** Required force-only close flag; false/omitted is rejected by daemon policy. */
 	force?: boolean;
 }
 
@@ -336,6 +336,8 @@ interface SessionRuntime {
 	disposeAnswerSource: () => void;
 	/** Deregisters this session's Telegram file sink. */
 	disposeFileSink: () => void;
+	/** Deregisters this session's unattended workflow-gate listener. */
+	disposeGateListener: () => void;
 	redact: boolean;
 	verbosity: "lean" | "verbose";
 	sessionTag: string;
@@ -348,6 +350,12 @@ interface SessionRuntime {
 	/** Assistant text already flushed before an ask this turn (turn-scoped dedupe
 	 * so turn_end does not re-emit the pre-ask lead-in). Reset each turn. */
 	preAskFlushedText?: string;
+	/** Live streaming: opt-in flag, monotonic per-turn ref, and emit throttle state. */
+	stream: boolean;
+	turnSeq?: number;
+	liveRef?: string;
+	lastLiveAt?: number;
+	lastLiveText?: string;
 	/** Cancels the postmortem cleanup that emits `session_closed` on process teardown. */
 	cancelPostmortemCleanup: () => void;
 }
@@ -358,6 +366,8 @@ interface ResolvedSettings {
 	settingsAvailable: boolean;
 }
 
+const TELEGRAM_FILE_REDACTION_ERROR = "Telegram file attachments are disabled while notifications redaction is on.";
+
 const defaultConfig: NotificationConfig = {
 	enabled: false,
 	botToken: undefined,
@@ -379,7 +389,36 @@ export function notificationsEnabled(): boolean {
 	return process.env.SKC_NOTIFICATIONS === "1" || Boolean(process.env.SKC_NOTIFICATIONS_TOKEN);
 }
 
-function resolveSettings(): ResolvedSettings {
+// Live streaming (opt-in): emit throttled non-finalized `turn_stream` frames as
+// the assistant message streams so remote clients can edit ONE message live. The
+// finalized frame (turn_end) carries the same messageRef and stays authoritative,
+// so a dropped live frame self-heals. Off unless SKC_NOTIFICATIONS_STREAM=1.
+function streamingEnabled(): boolean {
+	return process.env.SKC_NOTIFICATIONS_STREAM === "1";
+}
+function streamIntervalMs(): number {
+	return Math.max(200, Number(process.env.SKC_NOTIFICATIONS_STREAM_INTERVAL_MS) || 500);
+}
+// Max chars of a turn's assistant text carried by the FINALIZED turn_stream (and
+// the pre-ask capture). Default 3500 keeps the mirror a glanceable per-turn
+// summary; a client that splits long messages (the Telegram daemon does so via
+// splitTelegramHtml, scheduling each chunk through the shared rate-limit pool so
+// the fan-out never bypasses the per-chat limit) can raise it with
+// SKC_NOTIFICATIONS_TURN_MAX to deliver full turns. The value is clamped to a
+// finite [280, TURN_TEXT_MAX_CEILING] range: a non-finite or non-positive env
+// (unset, NaN, Infinity, <= 0) falls back to the default, so the cap can never
+// be unbounded. Live frames are intentionally NOT raised — they stay one
+// editable preview message rather than fanning a long in-progress turn across
+// sends.
+const TURN_TEXT_MAX_CEILING = 40_000;
+function turnTextMax(): number {
+	const raw = Number(process.env.SKC_NOTIFICATIONS_TURN_MAX);
+	if (!Number.isFinite(raw) || raw <= 0) return 3500;
+	return Math.min(TURN_TEXT_MAX_CEILING, Math.max(280, raw));
+}
+function resolveSettings(settingsOverride?: Settings): ResolvedSettings {
+	if (settingsOverride)
+		return { settings: settingsOverride, cfg: getNotificationConfig(settingsOverride), settingsAvailable: true };
 	try {
 		const settings = Settings.instance;
 		return { settings, cfg: getNotificationConfig(settings), settingsAvailable: true };
@@ -491,7 +530,7 @@ function sessionIdFromFile(file: string | undefined): string | undefined {
 	return underscore >= 0 ? base.slice(underscore + 1) : undefined;
 }
 
-export const createNotificationsExtension: ExtensionFactory = api => {
+export function createNotificationsExtension(api: ExtensionAPI, options: { settings?: Settings } = {}): void {
 	const runtimes = new Map<string, SessionRuntime>();
 	const disabledSessions = new Set<string>();
 	const sessionId = (ctx: ExtensionContext): string => ctx.sessionManager.getSessionId();
@@ -503,9 +542,16 @@ export const createNotificationsExtension: ExtensionFactory = api => {
 		runtimes.delete(id);
 		try {
 			rt.cancelPostmortemCleanup();
+		} catch {}
+		try {
 			rt.disposeAnswerSource();
+		} catch {}
+		try {
 			rt.disposeFileSink();
 		} catch {}
+		try {
+			rt.disposeGateListener();
+		} 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();
@@ -529,10 +575,14 @@ export const createNotificationsExtension: ExtensionFactory = api => {
 		return isSessionNotificationsEnabled({ cfg, env: process.env, sessionDisabled: disabledSessions.has(id) });
 	}
 
+	function isNotificationEligibleContext(ctx: ExtensionContext): boolean {
+		return ctx.sessionMetadata?.kind !== "sub";
+	}
+
 	async function startSession(ctx: ExtensionContext): Promise<"started" | "already" | "disabled" | "failed"> {
 		const id = sessionId(ctx);
-		const { settings, cfg, settingsAvailable } = resolveSettings();
-		if (!isEnabledForSession(id, cfg)) return "disabled";
+		const { settings, cfg, settingsAvailable } = resolveSettings(options.settings);
+		if (!isNotificationEligibleContext(ctx) || !isEnabledForSession(id, cfg)) return "disabled";
 		if (runtimes.has(id)) return "already";
 
 		const stateRoot = path.join(ctx.cwd, ".skc", "state");
@@ -660,6 +710,10 @@ export const createNotificationsExtension: ExtensionFactory = api => {
 				tag,
 			);
 			const disposeFileSink = registerTelegramFileSink(id, async file => {
+				if (runtime?.redact ?? redact) {
+					return { ok: false, error: TELEGRAM_FILE_REDACTION_ERROR };
+				}
+
 				try {
 					const data = await fs.promises.readFile(file.path);
 					server.pushFrame(
@@ -683,9 +737,11 @@ export const createNotificationsExtension: ExtensionFactory = api => {
 				pendingInteractive,
 				disposeAnswerSource,
 				disposeFileSink,
+				disposeGateListener: () => {},
 				cancelPostmortemCleanup: () => {},
 				redact,
 				verbosity,
+				stream: streamingEnabled(),
 				sessionTag: tag,
 				busy: false,
 				pendingInbound: new Set<number>(),
@@ -702,7 +758,7 @@ export const createNotificationsExtension: ExtensionFactory = api => {
 			});
 			logger.info(`notifications: serving session ${id} at ${endpoint.url} (unattended=${unattended})`);
 
-			if (settingsAvailable && settings && isGloballyConfigured(cfg)) {
+			if (settingsAvailable && settings && isTelegramConfigured(cfg)) {
 				try {
 					await ensureTelegramDaemonRunning({ settings, cwd: ctx.cwd, sessionId: id });
 				} catch (e) {
@@ -726,7 +782,7 @@ export const createNotificationsExtension: ExtensionFactory = api => {
 
 			// Unattended: a real ask emits a workflow gate; register it repliable by gate_id.
 			if (unattended && gate?.onGateEmitted) {
-				gate.onGateEmitted(g => {
+				runtime.disposeGateListener = gate.onGateEmitted(g => {
 					const options = (g.options ?? []).map(o => String((o as { label?: unknown }).label ?? ""));
 					gateOptions.set(g.gate_id, options);
 					const promptCtx = g.context as { prompt?: unknown; title?: unknown } | undefined;
@@ -761,7 +817,7 @@ export const createNotificationsExtension: ExtensionFactory = api => {
 		async handler(args: string, ctx: ExtensionCommandContext): Promise<void> {
 			const id = sessionId(ctx);
 			const command = args.trim().split(/\s+/, 1)[0]?.toLowerCase() || "status";
-			const resolved = resolveSettings();
+			const resolved = resolveSettings(options.settings);
 			const enabledWithoutLocalOff = isSessionNotificationsEnabled({
 				cfg: resolved.cfg,
 				env: process.env,
@@ -781,6 +837,10 @@ export const createNotificationsExtension: ExtensionFactory = api => {
 			}
 
 			if (command === "on") {
+				if (!isNotificationEligibleContext(ctx)) {
+					ctx.ui.notify("Notifications are disabled for subagent sessions.", "warning");
+					return;
+				}
 				if (process.env.SKC_NOTIFICATIONS === "0") {
 					ctx.ui.notify(
 						"Notifications remain disabled: SKC_NOTIFICATIONS=0 is an authoritative opt-out.",
@@ -878,6 +938,10 @@ export const createNotificationsExtension: ExtensionFactory = api => {
 			rt.sessionTag,
 		);
 		rt.disposeFileSink = registerTelegramFileSink(newId, async file => {
+			if (rt.redact) {
+				return { ok: false, error: TELEGRAM_FILE_REDACTION_ERROR };
+			}
+
 			try {
 				const data = await fs.promises.readFile(file.path);
 				rt.server.pushFrame(
@@ -1033,7 +1097,15 @@ export const createNotificationsExtension: ExtensionFactory = api => {
 		if (!text || text === rt.preAskFlushedText) return;
 		rt.preAskFlushedText = text;
 		try {
-			rt.server.pushFrame(JSON.stringify({ type: "turn_stream", sessionId: id, phase: "finalized", text }));
+			rt.server.pushFrame(
+				JSON.stringify({
+					type: "turn_stream",
+					sessionId: id,
+					phase: "finalized",
+					text,
+					...(rt.liveRef ? { messageRef: rt.liveRef } : {}),
+				}),
+			);
 		} catch (e) {
 			logger.warn(`notifications: pushFrame (turn) failed: ${String(e)}`);
 		}
@@ -1057,12 +1129,43 @@ export const createNotificationsExtension: ExtensionFactory = api => {
 		const id = sessionId(ctx);
 		const rt = runtimes.get(id);
 		if (!rt) return;
-		const text = rt.redact ? undefined : summaryFromMessage(event.message, 3500);
+		const text = rt.redact ? undefined : summaryFromMessage(event.message, turnTextMax());
 		if (text) flushTurnText(rt, id, text);
 		// Reset per-turn streaming state so the next turn starts fresh and a later
 		// turn with identical text is not falsely deduped.
 		rt.currentTurnText = undefined;
 		rt.preAskFlushedText = undefined;
+		rt.liveRef = undefined;
+		rt.lastLiveAt = undefined;
+		rt.lastLiveText = undefined;
+	});
+
+	// Live streaming (opt-in): push throttled in-progress assistant text as
+	// non-finalized turn_stream frames so remote clients edit one message as the
+	// turn streams. The finalized frame (turn_end) carries the same messageRef and
+	// lands the authoritative text. Suppressed under redaction.
+	api.on("message_update", (event, ctx) => {
+		const id = sessionId(ctx);
+		const rt = runtimes.get(id);
+		if (!rt?.stream || rt.redact) return;
+		if ((event.message as { role?: unknown }).role !== "assistant") return;
+		if (rt.liveRef === undefined) {
+			rt.turnSeq = (rt.turnSeq ?? 0) + 1;
+			rt.liveRef = String(rt.turnSeq);
+		}
+		const now = Date.now();
+		if (now - (rt.lastLiveAt ?? 0) < streamIntervalMs()) return;
+		const text = summaryFromMessage(event.message, 3500);
+		if (!text || text === rt.lastLiveText) return;
+		rt.lastLiveAt = now;
+		rt.lastLiveText = text;
+		try {
+			rt.server.pushFrame(
+				JSON.stringify({ type: "turn_stream", sessionId: id, phase: "live", text, messageRef: rt.liveRef }),
+			);
+		} catch (e) {
+			logger.warn(`notifications: pushFrame (live) failed: ${String(e)}`);
+		}
 	});
 
 	// Stream agent-produced images (computer/browser/tool screenshots) as
@@ -1076,7 +1179,7 @@ export const createNotificationsExtension: ExtensionFactory = api => {
 		// flush can emit it before the ask prompt. Role-scoped: message_end also
 		// fires for the user prompt, which must never be mirrored back as turn output.
 		if ((event.message as { role?: unknown }).role === "assistant") {
-			const turnText = summaryFromMessage(event.message, 3500);
+			const turnText = summaryFromMessage(event.message, turnTextMax());
 			if (turnText) rt.currentTurnText = turnText;
 		}
 		for (const img of imageAttachmentsFromMessage(event.message)) {
@@ -1099,4 +1202,4 @@ export const createNotificationsExtension: ExtensionFactory = api => {
 	api.on("session_shutdown", async (_event, ctx) => {
 		await stopSession(sessionId(ctx));
 	});
-};
+}

package/src/notifications/lifecycle-commands.ts

@@ -15,6 +15,19 @@ import * as os from "node:os";
 import type { SessionCloseTarget, SessionCreateTarget, SessionLifecycleResponse, SessionResumeTarget } from "./index";
 
 export type LifecycleCommandVerb = "session_create" | "session_close" | "session_resume";
+function normalizeLifecycleCommandToken(
+	token: string,
+	ctx: { chatType?: string; botUsername?: string } = {},
+): string | undefined {
+	const at = token.indexOf("@");
+	const command = at === -1 ? token : token.slice(0, at);
+	if (!/^\/session_(create|close|resume|recent)\b/.test(command)) return undefined;
+	if (at === -1) return ctx.chatType === undefined || ctx.chatType === "private" ? command : undefined;
+
+	const botUsername = ctx.botUsername;
+	if (!botUsername || token.slice(at + 1).toLowerCase() !== botUsername.toLowerCase()) return undefined;
+	return command;
+}
 
 /** A parsed, validated lifecycle command (transport identity added by caller). */
 export type ParsedLifecycleCommand =
@@ -36,10 +49,24 @@ const USAGE = [
 	"/session_recent [create|resume]",
 ].join("\n");
 
-/** True when the text begins a /session_* command (cheap pre-gate). */
-export function isLifecycleCommandText(text: string | undefined): boolean {
+/** True when the text begins with any /session_* token, regardless of addressability. */
+export function isLifecycleCommandLikeText(text: string | undefined): boolean {
+	if (!text) return false;
+	const [token] = text.trim().split(/\s+/, 1);
+	if (!token) return false;
+	const at = token.indexOf("@");
+	const command = at === -1 ? token : token.slice(0, at);
+	return /^\/session_(create|close|resume|recent)\b/.test(command);
+}
+
+/** True when the text begins an addressable /session_* command (cheap pre-gate). */
+export function isLifecycleCommandText(
+	text: string | undefined,
+	ctx: { chatType?: string; botUsername?: string } = {},
+): boolean {
 	if (!text) return false;
-	return /^\/session_(create|close|resume|recent)\b/.test(text.trim());
+	const [rawCommand] = text.trim().split(/\s+/, 1);
+	return normalizeLifecycleCommandToken(rawCommand ?? "", ctx) !== undefined;
 }
 
 /**
@@ -50,9 +77,14 @@ export function isLifecycleCommandText(text: string | undefined): boolean {
  * The caller MUST have already enforced paired-chat authorization; this function
  * performs grammar + target validation only.
  */
-export function parseLifecycleCommand(text: string | undefined): ParsedLifecycleCommand {
-	if (!isLifecycleCommandText(text)) return { kind: "none" };
+export function parseLifecycleCommand(
+	text: string | undefined,
+	ctx: { chatType?: string; botUsername?: string } = {},
+): ParsedLifecycleCommand {
 	const raw = (text ?? "").trim();
+	const [rawCommand, ...args] = raw.split(/\s+/);
+	const command = normalizeLifecycleCommandToken(rawCommand ?? "", ctx);
+	if (command === undefined) return { kind: "none" };
 
 	// MVP: reject any initial-prompt separator outright (no prompt handling yet).
 	if (/\s--(\s|$)/.test(raw)) {
@@ -63,8 +95,6 @@ export function parseLifecycleCommand(text: string | undefined): ParsedLifecycle
 		};
 	}
 
-	const [command, ...args] = raw.split(/\s+/);
-
 	if (command === "/session_recent") {
 		const which = args[0];
 		if (which === undefined || which === "create" || which === "resume") {

package/src/notifications/lifecycle-orchestrator.ts

@@ -252,7 +252,17 @@ export async function handleLifecycleRequest(
 		return { status: "error", reason: "rate_limited", message: "create rate limit exceeded" };
 	}
 
-	// 4. Preallocate ids + write in_progress (fsynced) BEFORE any spawn.
+	// 4. Close is intentionally force-only until a graceful close contract exists.
+	if (frame.type === "session_close" && frame.force !== true) {
+		await deps.audit({ ...baseAudit, event: "rejected", reason: "invalid_target" });
+		return {
+			status: "error",
+			reason: "invalid_target",
+			message: "session_close requires force=true; graceful close is not supported",
+		};
+	}
+
+	// 5. Preallocate ids + write in_progress (fsynced) BEFORE any spawn.
 	const lifecycleRequestId = frame.type === "session_create" ? frame.lifecycleRequestId : deps.newLifecycleRequestId();
 	const intendedSessionId =
 		frame.type === "session_create" ? frame.intendedSessionId || deps.newSessionId() : deps.newSessionId();
@@ -344,15 +354,18 @@ export async function handleLifecycleRequest(
 		await deps.audit({ ...baseAudit, event: "success", sessionId: resumed.sessionId });
 		return { status: "ok", entry, mode: resumed.mode };
 	} catch (err) {
-		// A side effect may have occurred; do not auto-respawn. Mark terminal
-		// uncertain so a retry reconciles instead of duplicating.
+		// A side effect may have occurred; do not repeat it automatically. Mark
+		// terminal-uncertain so a retry reconciles instead of duplicating work.
+		let reason: LifecycleErrorReason = "terminal_uncertain";
+		if (frame.type === "session_create") reason = "spawn_failed";
+		if (frame.type === "session_close") reason = "close_refused";
 		Object.assign(entry, {
 			state: "terminal_uncertain",
 			updatedAt: deps.now(),
-			reason: "spawn_failed",
+			reason,
 		});
 		await deps.store.write(doc);
-		await deps.audit({ ...baseAudit, event: "terminal_uncertain", reason: "spawn_failed" });
-		return { status: "error", reason: "terminal_uncertain", message: `lifecycle effect failed: ${String(err)}` };
+		await deps.audit({ ...baseAudit, event: "terminal_uncertain", reason });
+		return { status: "error", reason: "terminal_uncertain", message: `${frame.type} effect failed: ${String(err)}` };
 	}
 }

package/src/notifications/telegram-daemon-control.ts

@@ -20,7 +20,7 @@ import type {
 	DaemonStatus,
 } from "../daemon/control-types";
 import { resolveSkcRuntimeSpawnInfo } from "../daemon/runtime";
-import { getNotificationConfig, isGloballyConfigured, tokenFingerprint } from "./config";
+import { getNotificationConfig, isTelegramConfigured, tokenFingerprint } from "./config";
 import {
 	daemonPaths,
 	isFreshLiveOwner,
@@ -159,7 +159,7 @@ export class TelegramDaemonController implements BuiltInDaemonController {
 	async status(): Promise<DaemonStatus> {
 		const runtime = this.runtimeInfo();
 		const cfg = getNotificationConfig(this.settings);
-		const configured = isGloballyConfigured(cfg) && Boolean(cfg.botToken) && Boolean(cfg.chatId);
+		const configured = isTelegramConfigured(cfg);
 		if (!configured) {
 			return { kind: this.kind, configured: false, health: "not_configured", runtime };
 		}
@@ -269,6 +269,7 @@ export class TelegramDaemonController implements BuiltInDaemonController {
 				{ settings: this.settings, roots, tokenFingerprint: fp, chatId },
 				this.spawnDeps(),
 			);
+			warnings.push(...spawned.warnings);
 			const after = await this.status();
 			return this.result(
 				action,
@@ -351,6 +352,7 @@ export class TelegramDaemonController implements BuiltInDaemonController {
 			{ settings: this.settings, roots, tokenFingerprint: fp, chatId },
 			this.spawnDeps(),
 		);
+		warnings.push(...spawned.warnings);
 		const after = await this.status();
 		if (spawned.result === "attached") {
 			// A live owner already exists; attaching to it is a valid running end-state.
@@ -360,7 +362,7 @@ export class TelegramDaemonController implements BuiltInDaemonController {
 		}
 		return this.result(
 			action,
-			spawned.result !== "disabled",
+			spawned.result !== "disabled" && spawned.result !== "blocked",
 			`reloaded telegram daemon (${spawned.result})`,
 			before,
 			after,