@sayknow-cli/coding-agent 0.3.12 → 0.3.13

package/src/notifications/telegram-reference.ts

@@ -25,12 +25,30 @@ import {
 } from "./html-format";
 import { renderThreadedFrame } from "./threaded-render";
 
+/** `ask_controls_v1` is a protocol version 3 wire token. Keep this local because
+ * `telegram-daemon.ts` imports this reference client. */
+const REFERENCE_CLIENT_HELLO = {
+	type: "hello",
+	protocolVersion: 3,
+	capabilities: ["ask_controls_v1"],
+} as const;
+
 /** One inline-keyboard button. */
 export interface InlineButton {
 	text: string;
 	callback_data: string;
 }
 
+/** Typed action controls are protocol data, never inferred from option labels. */
+export interface TelegramActionControl {
+	id: "navigation_forward";
+	kind: "navigation";
+	label: "Next" | "Done";
+	enabled: boolean;
+}
+
+export type TelegramCallbackAnswer = number | string | { controlId: TelegramActionControl["id"] };
+
 /** A rendered Telegram message for an `action_needed`. */
 export interface RenderedMessage {
 	text: string;
@@ -51,10 +69,22 @@ export function decodeCallbackData(data: string): { id: string; index: number }
 	return { index: Number(m[1]), id: m[2]! };
 }
 
+/** Encode a typed control independently from option labels. */
+export function encodeControlCallbackData(actionId: string, controlId: TelegramActionControl["id"]): string {
+	const encoded = `c:${controlId === "navigation_forward" ? "n" : controlId}:${actionId}`;
+	if (Buffer.byteLength(encoded, "utf8") > 64) throw new Error("control callback data exceeded Telegram limit");
+	return encoded;
+}
+
+export function decodeControlCallbackData(data: string): { id: string; controlId: TelegramActionControl["id"] } | null {
+	const match = /^c:n:(.+)$/.exec(data);
+	return match ? { controlId: "navigation_forward", id: match[1]! } : null;
+}
+
 export interface CallbackRoute {
 	sessionId: string;
 	actionId: string;
-	answer: number | string;
+	answer: TelegramCallbackAnswer;
 }
 
 export interface SerializedAliasTable {
@@ -78,7 +108,11 @@ function isCallbackRoute(value: unknown): value is CallbackRoute {
 	return (
 		typeof route.sessionId === "string" &&
 		typeof route.actionId === "string" &&
-		(typeof route.answer === "string" || typeof route.answer === "number")
+		(typeof route.answer === "string" ||
+			typeof route.answer === "number" ||
+			(typeof route.answer === "object" &&
+				route.answer !== null &&
+				(route.answer as { controlId?: unknown }).controlId === "navigation_forward"))
 	);
 }
 
@@ -129,6 +163,7 @@ export function buildActionMessage(action: {
 	id: string;
 	question?: string;
 	options?: string[];
+	controls?: readonly TelegramActionControl[];
 	summary?: string;
 }): RenderedMessage {
 	if (action.kind === "idle") {
@@ -137,9 +172,15 @@ export function buildActionMessage(action: {
 	}
 	const text = `❓ ${bold(action.question ?? "Question")}`;
 	const options = action.options ?? [];
-	if (options.length === 0) return { text: `${text}\n\n(reply with text)` };
-	const body = `${text}\n\n${numberedOptionList(options)}`;
-	const inline_keyboard = buildCompactChoiceGrid(options, i => encodeCallbackData(action.id, i));
+	const controls = (action.controls ?? []).filter(control => control.enabled);
+	if (options.length === 0 && controls.length === 0) return { text: `${text}\n\n(reply with text)` };
+	const body = options.length ? `${text}\n\n${numberedOptionList(options)}` : text;
+	const inline_keyboard = [
+		...(options.length ? buildCompactChoiceGrid(options, i => encodeCallbackData(action.id, i)) : []),
+		...controls.map(control => [
+			{ text: control.label, callback_data: encodeControlCallbackData(action.id, control.id) },
+		]),
+	];
 	return { text: body, inline_keyboard };
 }
 
@@ -182,7 +223,7 @@ export async function sendTelegramHtmlChunks(
 export interface ReplyFrame {
 	type: "reply";
 	id: string;
-	answer: number | string;
+	answer: TelegramCallbackAnswer;
 	token: string;
 }
 
@@ -195,17 +236,15 @@ export function telegramUpdateToReply(
 	token: string,
 	latestPendingAskId: string | undefined,
 ): ReplyFrame | null {
-	const u = update as {
-		callback_query?: { data?: string };
-		message?: { text?: string };
-	};
+	const u = update as { callback_query?: { data?: string }; message?: { text?: string } };
 	if (u.callback_query?.data) {
 		const decoded = decodeCallbackData(u.callback_query.data);
 		if (decoded) return { type: "reply", id: decoded.id, answer: decoded.index, token };
+		const control = decodeControlCallbackData(u.callback_query.data);
+		if (control) return { type: "reply", id: control.id, answer: { controlId: control.controlId }, token };
 	}
-	if (u.message?.text && latestPendingAskId) {
+	if (u.message?.text && latestPendingAskId)
 		return { type: "reply", id: latestPendingAskId, answer: u.message.text, token };
-	}
 	return null;
 }
 
@@ -239,7 +278,10 @@ function updateChatId(update: TelegramUpdateShape): string | undefined {
 	return id === undefined || id === null ? undefined : String(id);
 }
 
-function routeWithAnswer(route: CallbackRoute | Omit<CallbackRoute, "answer">, answer: number | string): CallbackRoute {
+function routeWithAnswer(
+	route: CallbackRoute | Omit<CallbackRoute, "answer">,
+	answer: TelegramCallbackAnswer,
+): CallbackRoute {
 	return { sessionId: route.sessionId, actionId: route.actionId, answer };
 }
 
@@ -320,8 +362,10 @@ export async function runTelegramReferenceClient(opts: TelegramReferenceOptions)
 			id?: string;
 			question?: string;
 			options?: string[];
+			controls?: TelegramActionControl[];
 			summary?: string;
 			reason?: string;
+			requiredCapabilities?: unknown;
 		};
 		if (msg.type === "action_needed" && msg.id) {
 			if (msg.kind === "ask") latestPendingAskId = msg.id;
@@ -330,9 +374,22 @@ export async function runTelegramReferenceClient(opts: TelegramReferenceOptions)
 				id: msg.id,
 				question: msg.question,
 				options: msg.options,
+				controls: msg.controls,
 				summary: msg.summary,
 			});
 			await sendTelegramHtmlChunks(send, opts.chatId, rendered.text, rendered.inline_keyboard);
+		} else if (msg.type === "action_unavailable") {
+			const requiredCapabilities = Array.isArray(msg.requiredCapabilities)
+				? msg.requiredCapabilities
+						.filter((capability): capability is string => typeof capability === "string")
+						.slice(0, 4)
+						.map(capability => capability.slice(0, 64))
+				: [];
+			console.warn(
+				`Telegram reference client: server withheld a controlled ask because this client lacks requiredCapabilities=[${requiredCapabilities.join(", ") || "unspecified"}].`,
+			);
+			// Diagnostic only: never turn it into a Telegram prompt or option buttons.
+			return;
 		} else if (msg.type === "action_resolved" && msg.id === latestPendingAskId) {
 			latestPendingAskId = undefined;
 		} else {
@@ -347,6 +404,9 @@ export async function runTelegramReferenceClient(opts: TelegramReferenceOptions)
 	};
 
 	let messageQueue = Promise.resolve();
+	ws.addEventListener("open", () => {
+		if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify(REFERENCE_CLIENT_HELLO));
+	});
 	ws.addEventListener("message", ev => {
 		const data = String(ev.data);
 		messageQueue = messageQueue.catch(() => undefined).then(() => handleServerMessage(data));

package/src/notifications/topic-registry.ts

@@ -21,8 +21,16 @@ export interface TopicRecord {
 	identitySent: boolean;
 	/** Creation timestamp (ms epoch). */
 	createdAt: number;
-	/** Last applied topic title (for rename detection). */
+	/** Last applied or observed Telegram topic title. */
 	name?: string;
+	/** Naming authority. Missing values are legacy daemon-owned records. */
+	nameOwner?: "user";
+	/** Whether a user-owned name still needs a best-effort Telegram re-assert. */
+	nameReconcilePending?: boolean;
+	/** Last accepted Telegram update id for a user-owned name. */
+	userNameUpdateId?: number;
+	/** Stable repo/branch identity used when topic names are user-owned or customized. */
+	identityKey?: string;
 }
 
 /** Serialisable shape persisted to disk. */
@@ -48,13 +56,31 @@ export class TopicRegistry {
 	private readonly inflight = new Map<string, Promise<TopicRecord>>();
 
 	constructor(state: TopicRegistryState = emptyTopicRegistryState()) {
-		this.topics = new Map(Object.entries(state.topics ?? {}));
-		for (const [sessionId, record] of this.topics) this.byTopic.set(record.topicId, sessionId);
+		this.topics = new Map();
+		this.load(state);
 	}
 
-	/** Merge a serialized state into this registry, preserving all persisted fields. */
+	/** Merge serialized state and normalize authority fields from older releases. */
 	load(state: TopicRegistryState): void {
-		for (const [sessionId, record] of Object.entries(state.topics ?? {})) {
+		for (const [sessionId, raw] of Object.entries(state.topics ?? {})) {
+			if (!raw || typeof raw.topicId !== "string") continue;
+			const hasValidUserAuthority =
+				raw.nameOwner === "user" &&
+				typeof raw.name === "string" &&
+				raw.name.trim().length > 0 &&
+				typeof raw.userNameUpdateId === "number" &&
+				Number.isSafeInteger(raw.userNameUpdateId) &&
+				raw.userNameUpdateId >= 0;
+			const record: TopicRecord = {
+				topicId: raw.topicId,
+				identitySent: raw.identitySent === true,
+				createdAt: typeof raw.createdAt === "number" ? raw.createdAt : 0,
+				...(typeof raw.name === "string" ? { name: raw.name } : {}),
+				...(hasValidUserAuthority ? { nameOwner: "user" as const } : {}),
+				...(hasValidUserAuthority && raw.nameReconcilePending === true ? { nameReconcilePending: true } : {}),
+				...(hasValidUserAuthority ? { userNameUpdateId: raw.userNameUpdateId } : {}),
+				...(typeof raw.identityKey === "string" ? { identityKey: raw.identityKey } : {}),
+			};
 			this.topics.set(sessionId, record);
 			this.byTopic.set(record.topicId, sessionId);
 		}
@@ -120,16 +146,67 @@ export class TopicRegistry {
 		return record ? !record.identitySent : true;
 	}
 
-	/** Whether a known session topic's applied title differs from `name`. */
+	/** Remember stable repo/branch identity independently of the displayed name. */
+	markIdentityKey(sessionId: string, identityKey: string): boolean {
+		const record = this.topics.get(sessionId);
+		if (!record || record.identityKey === identityKey) return false;
+		record.identityKey = identityKey;
+		return true;
+	}
+
+	/** Whether daemon identity reconciliation should apply `name`. */
 	needsRename(sessionId: string, name: string): boolean {
 		const record = this.topics.get(sessionId);
-		return record !== undefined && record.name !== name;
+		return record !== undefined && record.nameOwner !== "user" && record.name !== name;
+	}
+
+	/** The user-owned name that must be preserved, when one exists. */
+	userOwnedName(sessionId: string): string | undefined {
+		const record = this.topics.get(sessionId);
+		return record?.nameOwner === "user" ? record.name : undefined;
+	}
+
+	/** A user-owned name whose Telegram reconciliation is still pending. */
+	userNameToReconcile(sessionId: string): string | undefined {
+		const record = this.topics.get(sessionId);
+		return record?.nameOwner === "user" && record.nameReconcilePending ? record.name : undefined;
+	}
+
+	/** Record an explicit Telegram-side user rename, rejecting stale update ids. */
+	markUserName(sessionId: string, name: string, updateId: number): "updated" | "duplicate" | "stale" {
+		const record = this.topics.get(sessionId);
+		if (!record) return "stale";
+		if (record.userNameUpdateId !== undefined && updateId < record.userNameUpdateId) return "stale";
+		if (record.userNameUpdateId === updateId) return "duplicate";
+		record.name = name;
+		record.nameOwner = "user";
+		record.nameReconcilePending = true;
+		record.userNameUpdateId = updateId;
+		return "updated";
+	}
+
+	/** Mark the matching preserved user name as reconciled with Telegram. */
+	markUserNameReconciled(sessionId: string, name: string): boolean {
+		const record = this.topics.get(sessionId);
+		if (record?.nameOwner !== "user" || record.name !== name || !record.nameReconcilePending) return false;
+		record.nameReconcilePending = false;
+		return true;
+	}
+
+	/** Restore retryable reconciliation after a failed pending-clear persistence. */
+	markUserNamePending(sessionId: string, name: string): boolean {
+		const record = this.topics.get(sessionId);
+		if (record?.nameOwner !== "user" || record.name !== name || record.nameReconcilePending) return false;
+		record.nameReconcilePending = true;
+		return true;
 	}
 
-	/** Commit a successfully-applied Telegram topic title. */
+	/** Commit a successfully-applied daemon topic title. */
 	markNameApplied(sessionId: string, name: string): void {
 		const record = this.topics.get(sessionId);
-		if (record) record.name = name;
+		if (!record || record.nameOwner === "user") return;
+		record.name = name;
+		record.nameReconcilePending = false;
 	}
 
 	/** Remove a session topic record after Telegram deletes the topic. */

package/src/prompts/system/irc-peer-roster.md

@@ -0,0 +1 @@
+<system-reminder>IRC peers: {{roster}}</system-reminder>

package/src/prompts/system/subagent-system-prompt.md

@@ -34,6 +34,7 @@ You can reach other live agents via the `irc` tool. Your id is `{{ircSelfId}}`.
 {{ircPeers}}
 
 Use `irc` only when you need a quick answer from a peer; do not use it for long-form content. Address peers by id or use `"all"` to broadcast.
+Use `irc` to DM `0-Main` on unexpected state instead of guessing; coordinate before changing shared files.
 {{/if}}
 [/COOP]
 

package/src/prompts/system/system-prompt.md

@@ -210,6 +210,7 @@ Delegate by default for multi-file changes, refactors, new features, tests, and
 {{#has tools "subagent"}}- Use `{{toolRefs.subagent}}` to list, inspect, await with `timeout_ms`, or cancel detached task subagents.{{/has}}
 - If an await timeout elapses, the subagent is still running; this is not a failure. Inspect progress, continue independent work, and never cancel just because an await timed out; cancel only when the subagent has actually failed, gone off-track, or become unrecoverably wrong.
 {{#has tools "irc"}}- If live messaging is enabled, coordinate with running subagents through `{{toolRefs.irc}}`; cancellation is not a message channel.{{/has}}
+{{#has tools "irc"}}- When a subagent's scope shifts or needs steering, check in through `{{toolRefs.irc}}` rather than guessing its state.{{/has}}
 {{#has tools "job"}}- `{{toolRefs.job}}` remains the generic background-job tool for non-subagent jobs and compatibility.{{/has}}
 </detached-subagents>
 {{/has}}

package/src/prompts/tools/irc.md

@@ -14,7 +14,7 @@ You SHOULD reach for `irc` proactively when continuing alone is wasteful or wron
 - **Unexpected state.** You hit something the original task did not describe — a missing file, a config that contradicts the assignment, an API behaving differently than you were told, a tool failing in a way that suggests the spec is wrong. DM `0-Main` (or the spawning agent) for guidance instead of guessing.
 - **Blocked by another agent.** A peer holds the file/branch/resource you need, has already started the change you are about to make, or owns a decision you depend on. DM that peer (or broadcast to discover who) before duplicating or stepping on work.
 - **Decision points outside your scope.** A genuine fork in the road that the assignment did not pre-decide (e.g. which of two viable APIs to use, whether to refactor adjacent code). Ask the requester rather than picking unilaterally.
-- **Coordination opportunities.** You realize a peer's in-flight work would benefit from yours, or vice-versa.
+- **Coordination opportunities.** Before editing a shared file or relying on another agent's in-flight API, message the relevant peer; proactively share state that affects their work.
 
 Do **not** use `irc` for: routine progress updates, things you can verify with a tool call, or questions whose answer is already in your assignment / repo / docs.
 </conditions>

package/src/registry/agent-registry.ts

@@ -16,6 +16,7 @@ export type AgentKind = "main" | "sub";
 export interface AgentRef {
 	id: string;
 	displayName: string;
+	rosterLabel?: string;
 	kind: AgentKind;
 	parentId?: string;
 	status: AgentStatus;
@@ -35,6 +36,7 @@ type RegistryListener = (event: RegistryEvent) => void;
 export interface RegisterInput {
 	id: string;
 	displayName: string;
+	rosterLabel?: string;
 	kind: AgentKind;
 	parentId?: string;
 	session: AgentSession | null;
@@ -65,6 +67,7 @@ export class AgentRegistry {
 		const ref: AgentRef = {
 			id: input.id,
 			displayName: input.displayName,
+			rosterLabel: input.rosterLabel,
 			kind: input.kind,
 			parentId: input.parentId,
 			status: input.status ?? "running",

package/src/sdk.ts

@@ -96,6 +96,7 @@ import { createNotificationsExtension } from "./notifications";
 import {
 	getNotificationConfig,
 	type NotificationConfig,
+	SPAWN_PROVENANCE_ENV,
 	shouldRegisterNotificationsExtension,
 } from "./notifications/config";
 import asyncResultTemplate from "./prompts/tools/async-result.md" with { type: "text" };
@@ -244,6 +245,28 @@ function buildMcpNotificationBatchMessage(entries: McpNotificationEntry[]): Agen
 	};
 }
 
+function sanitizeRosterLabel(value: string): string {
+	const normalized = value
+		.replace(/[\p{Cc}]/gu, " ")
+		.replace(/\s+/g, " ")
+		.trim();
+	return normalized.length > 48 ? `${normalized.slice(0, 47)}…` : normalized;
+}
+
+function humanizeAgentTaskId(id: string): string {
+	return id
+		.replace(/([a-z\d])([A-Z])/g, "$1 $2")
+		.replace(/[-_]+/g, " ")
+		.trim();
+}
+
+function resolveAgentRosterLabel(label: string | undefined, agentId: string, displayName: string): string {
+	return (
+		sanitizeRosterLabel(label ?? "") ||
+		sanitizeRosterLabel(humanizeAgentTaskId(agentId)) ||
+		sanitizeRosterLabel(displayName)
+	);
+}
 // Types
 export interface CreateAgentSessionOptions {
 	/** Working directory for project-local discovery. Default: getProjectDir() */
@@ -336,6 +359,8 @@ export interface CreateAgentSessionOptions {
 	agentId?: string;
 	/** Display name for the agent in IRC. Default: "main" or "sub". */
 	agentDisplayName?: string;
+	/** Compact task label for hidden IRC roster reminders. */
+	agentRosterLabel?: string;
 	/** Optional restricted bash command prefixes for read-only role agents. */
 	bashAllowedPrefixes?: string[];
 	/** Restriction policy paired with bashAllowedPrefixes. */
@@ -1273,7 +1298,19 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 	const resolvedAgentId = options.agentId ?? options.parentTaskPrefix ?? MAIN_AGENT_ID;
 	const isSubSession = taskDepth > 0 || Boolean(options.parentTaskPrefix) || Boolean(options.currentAgentType);
 	const resolvedAgentDisplayName = options.agentDisplayName ?? (isSubSession ? "sub" : "main");
+	const resolvedAgentRosterLabel = resolveAgentRosterLabel(
+		options.agentRosterLabel,
+		resolvedAgentId,
+		resolvedAgentDisplayName,
+	);
 	const evalKernelOwnerId = `agent-session:${Snowflake.next()}`;
+	let disposeLocalProtocolOverride: (() => void) | undefined;
+	let localProtocolOverrideReleased = false;
+	const releaseLocalProtocolOverride = (): void => {
+		if (localProtocolOverrideReleased) return;
+		localProtocolOverrideReleased = true;
+		disposeLocalProtocolOverride?.();
+	};
 
 	try {
 		const getActiveModelString = (): string | undefined => {
@@ -1403,7 +1440,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			if (asyncJobManager) AsyncJobManager.setInstance(asyncJobManager);
 		}
 		if (options.localProtocolOptions) {
-			LocalProtocolHandler.setOverride(options.localProtocolOptions);
+			disposeLocalProtocolOverride = LocalProtocolHandler.installOverride(options.localProtocolOptions);
 		}
 		toolSession.getArtifactsDir = getArtifactsDir;
 		toolSession.agentOutputManager = new AgentOutputManager(
@@ -1581,6 +1618,15 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		} catch {
 			notificationCfg = undefined;
 		}
+		// Consume the SKC spawn-provenance marker: read it once, then remove it
+		// from this process's env so it is never re-inherited by children this
+		// session later spawns (marker is per-spawn, not dynastic — each SKC child
+		// spawn site sets it explicitly). Suppression under `sessionScope=primary`
+		// keeps auto-spawned children (team workers, harness RPC owners) silent
+		// while explicit `/session_create` opt-in (SKC_NOTIFICATIONS=1) still wins.
+		const spawnProvenance = process.env[SPAWN_PROVENANCE_ENV];
+		const spawnedBySkc = typeof spawnProvenance === "string" && spawnProvenance.trim().length > 0;
+		delete process.env[SPAWN_PROVENANCE_ENV];
 		if (
 			shouldRegisterNotificationsExtension({
 				env: process.env,
@@ -1588,6 +1634,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				taskDepth,
 				parentTaskPrefix: options.parentTaskPrefix,
 				currentAgentType: options.currentAgentType,
+				spawnedBySkc,
 			})
 		) {
 			inlineExtensions.push(api => createNotificationsExtension(api, { settings }));
@@ -2061,6 +2108,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		agentRegistry.register({
 			id: resolvedAgentId,
 			displayName: resolvedAgentDisplayName,
+			rosterLabel: resolvedAgentRosterLabel,
 			kind: isSubSession ? "sub" : "main",
 			parentId: options.parentTaskPrefix,
 			session: null,
@@ -2385,6 +2433,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				} finally {
 					agentRegistry.unregister(resolvedAgentId);
 					unsubscribeCredentialDisabled?.();
+					releaseLocalProtocolOverride();
 				}
 			};
 		}
@@ -2549,6 +2598,8 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			logger.warn("Failed to clean up createAgentSession resources after startup error", {
 				error: cleanupError instanceof Error ? cleanupError.message : String(cleanupError),
 			});
+		} finally {
+			releaseLocalProtocolOverride();
 		}
 		throw error;
 	}

package/src/secrets/obfuscator.ts

@@ -1,5 +1,5 @@
 import type { Message, TextContent } from "@sayknow-cli/ai";
-import type { SessionContext } from "../session/session-manager";
+import { type SessionContext, transferSessionMessageIdentity } from "../session/session-manager";
 import { compileSecretRegex } from "./regex";
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -281,7 +281,9 @@ export function deobfuscateSessionContext(
 ): SessionContext {
 	if (!obfuscator?.hasSecrets()) return sessionContext;
 	const messages = obfuscator.deobfuscateObject(sessionContext.messages);
-	return messages === sessionContext.messages ? sessionContext : { ...sessionContext, messages };
+	if (messages === sessionContext.messages) return sessionContext;
+	transferSessionMessageIdentity(sessionContext.messages, messages);
+	return { ...sessionContext, messages };
 }
 
 // ═══════════════════════════════════════════════════════════════════════════