@sayknow-cli/coding-agent 0.3.15 → 0.4.0

package/src/sdk/bus/chat-effect-journal.ts

@@ -0,0 +1,363 @@
+import { isDeepStrictEqual } from "node:util";
+
+import {
+	type ConversationRecord,
+	ConversationStore,
+	type ConversationStoreFs,
+	conversationStorePath,
+} from "./conversation-store";
+
+export const CHAT_EFFECT_JOURNAL_VERSION = 1;
+export const MAX_TERMINAL_CHAT_EFFECTS = 128;
+
+export function chatEffectJournalPath(agentDir: string, transport: "discord" | "slack"): string {
+	return conversationStorePath(agentDir, transport, "effects.json");
+}
+
+export type ChatEffectState = "pending" | "leased" | "accepted" | "uncertain" | "terminal";
+
+/** Provider receipts are identifiers/status only. Never put request or response bodies here. */
+export interface ChatEffectReceipt {
+	provider?: string;
+	messageId?: string;
+	channelId?: string;
+	threadId?: string;
+	timestamp?: string;
+	status?: string;
+}
+
+/**
+ * A protected, generation-bound provider-visible effect. Payload is deliberately
+ * owned by this journal; conversation mappings may retain only `effectId`.
+ */
+export interface ChatEffect<TPayload = unknown> extends ConversationRecord {
+	id: string;
+	kind: string;
+	transport: "discord" | "slack";
+	sessionId?: string;
+	endpointGeneration: number;
+	payload: TPayload;
+	state: ChatEffectState;
+	owner?: string;
+	leaseExpiresAt?: number;
+	epoch: number;
+	createdAt: number;
+	updatedAt: number;
+	receipt?: ChatEffectReceipt;
+}
+
+export interface EnqueueChatEffect<TPayload> {
+	id: string;
+	kind: string;
+	transport: "discord" | "slack";
+	sessionId?: string;
+	endpointGeneration: number;
+	payload: TPayload;
+	receipt?: ChatEffectReceipt;
+}
+
+export interface ChatEffectLease {
+	owner: string;
+	epoch: number;
+}
+
+type EffectReferenceMapping = ConversationRecord & Record<string, unknown>;
+
+function hasImmutableEnqueueIdentity<TPayload>(
+	effect: ChatEffect<TPayload>,
+	input: EnqueueChatEffect<TPayload>,
+): boolean {
+	return (
+		effect.transport === input.transport &&
+		effect.kind === input.kind &&
+		effect.sessionId === input.sessionId &&
+		effect.endpointGeneration === input.endpointGeneration &&
+		isDeepStrictEqual(effect.payload, input.payload)
+	);
+}
+
+function requireImmutableEnqueueIdentity<TPayload>(
+	effect: ChatEffect<TPayload>,
+	input: EnqueueChatEffect<TPayload>,
+): void {
+	if (!hasImmutableEnqueueIdentity(effect, input))
+		throw new Error(`Chat effect ${input.id} already exists with a different immutable identity`);
+}
+
+function collectEffectReferences(value: unknown, references: Set<string>): void {
+	if (Array.isArray(value)) {
+		for (const entry of value) collectEffectReferences(entry, references);
+		return;
+	}
+	if (!value || typeof value !== "object") return;
+	for (const [key, candidate] of Object.entries(value)) {
+		if ((key === "effectId" || key.endsWith("EffectId")) && typeof candidate === "string") references.add(candidate);
+		else collectEffectReferences(candidate, references);
+	}
+}
+
+function nonEmpty(value: string, name: string): void {
+	if (!value) throw new Error(`Chat effect ${name} is required`);
+}
+
+function canClaim(effect: ChatEffect, now: number): boolean {
+	return (
+		effect.state === "pending" ||
+		effect.state === "accepted" ||
+		(effect.state === "uncertain" && !effect.kind.includes(".inbound.")) ||
+		(effect.state === "leased" && (effect.leaseExpiresAt ?? 0) <= now)
+	);
+}
+
+/**
+ * One journal per transport. It uses the same 0600, fsynced atomic persistence
+ * and cross-process exclusive locking as mappings, but stores payloads in a
+ * separate protected file (`effects.json`). Terminal history is compacted only
+ * after terminal state is durably recorded; nonterminal effects are never evicted.
+ */
+export class ChatEffectJournal {
+	readonly #store: ConversationStore<ChatEffect>;
+	readonly #mappings: ConversationStore<EffectReferenceMapping>;
+	readonly #maxTerminalEffects: number;
+
+	readonly #now: () => number;
+
+	constructor(input: {
+		agentDir: string;
+		transport: "discord" | "slack";
+		fs?: ConversationStoreFs;
+		now?: () => number;
+		pid?: number;
+		pidAlive?: (pid: number) => boolean;
+		pidIncarnation?: (pid: number) => string | undefined;
+		sleep?: (ms: number) => Promise<void>;
+		lockTimeoutMs?: number;
+		maxTerminalEffects?: number;
+	}) {
+		this.#store = new ConversationStore<ChatEffect>({ ...input, kind: input.transport, fileName: "effects.json" });
+		this.#mappings = new ConversationStore<EffectReferenceMapping>({ ...input, kind: input.transport });
+
+		if (
+			input.maxTerminalEffects !== undefined &&
+			(!Number.isSafeInteger(input.maxTerminalEffects) || input.maxTerminalEffects < 1)
+		)
+			throw new Error("Chat effect terminal retention must be a positive safe integer");
+		this.#maxTerminalEffects = input.maxTerminalEffects ?? MAX_TERMINAL_CHAT_EFFECTS;
+		this.#now = input.now ?? Date.now;
+	}
+
+	get filePath(): string {
+		return this.#store.filePath;
+	}
+
+	async read<TPayload = unknown>(id: string): Promise<ChatEffect<TPayload> | undefined> {
+		return (await this.#store.read(id)) as ChatEffect<TPayload> | undefined;
+	}
+
+	async list(): Promise<ChatEffect[]> {
+		return Object.values((await this.#store.load()).conversations);
+	}
+
+	async replayable(transport: "discord" | "slack", endpointGeneration: number): Promise<ChatEffect[]> {
+		const now = this.#now();
+		return (await this.list()).filter(
+			effect =>
+				effect.transport === transport && effect.endpointGeneration === endpointGeneration && canClaim(effect, now),
+		);
+	}
+
+	async enqueue<TPayload>(input: EnqueueChatEffect<TPayload>): Promise<ChatEffect<TPayload>> {
+		nonEmpty(input.id, "id");
+		nonEmpty(input.kind, "kind");
+		const existing = await this.read<TPayload>(input.id);
+		if (existing) {
+			requireImmutableEnqueueIdentity(existing, input);
+			return existing;
+		}
+
+		const now = this.#now();
+		const effect: ChatEffect<TPayload> = {
+			...input,
+			generation: 1,
+			state: "pending",
+			epoch: 0,
+			createdAt: now,
+			updatedAt: now,
+		};
+		if (await this.#store.write(input.id, undefined, effect)) return effect;
+		const raced = await this.read<TPayload>(input.id);
+		if (!raced) throw new Error(`Unable to enqueue chat effect ${input.id}`);
+		requireImmutableEnqueueIdentity(raced, input);
+		return raced;
+	}
+
+	/**
+	 * Inserts an effect directly into a live lease. Recovery can never observe a
+	 * newly persisted effect as claimable before its owner has authority to act.
+	 * Existing effects are left untouched and report no acquired lease.
+	 */
+	async enqueueAndClaim<TPayload>(
+		input: EnqueueChatEffect<TPayload>,
+		owner: string,
+		leaseMs: number,
+	): Promise<ChatEffect<TPayload> | undefined> {
+		nonEmpty(input.id, "id");
+		nonEmpty(input.kind, "kind");
+		nonEmpty(owner, "owner");
+		if (!Number.isFinite(leaseMs) || leaseMs <= 0) throw new Error("Chat effect lease duration must be positive");
+		let claimed: ChatEffect<TPayload> | undefined;
+		const now = this.#now();
+		await this.#store.transact(input.id, current => {
+			if (current) {
+				requireImmutableEnqueueIdentity(current as ChatEffect<TPayload>, input);
+				return current;
+			}
+
+			claimed = {
+				...input,
+				generation: 1,
+				state: "leased",
+				owner,
+				epoch: 1,
+				leaseExpiresAt: now + leaseMs,
+				createdAt: now,
+				updatedAt: now,
+			};
+			return claimed;
+		});
+		return claimed;
+	}
+
+	async claim<TPayload = unknown>(
+		id: string,
+		owner: string,
+		leaseMs: number,
+	): Promise<ChatEffect<TPayload> | undefined> {
+		nonEmpty(owner, "owner");
+		if (!Number.isFinite(leaseMs) || leaseMs <= 0) throw new Error("Chat effect lease duration must be positive");
+		let claimed: ChatEffect<TPayload> | undefined;
+		const now = this.#now();
+		await this.#store.transact(id, current => {
+			if (!current || !canClaim(current, now)) return current;
+			claimed = {
+				...current,
+				generation: current.generation + 1,
+				state: "leased",
+				owner,
+				epoch: current.epoch + 1,
+				leaseExpiresAt: now + leaseMs,
+				updatedAt: now,
+			} as ChatEffect<TPayload>;
+			return claimed;
+		});
+		return claimed;
+	}
+
+	async renew<TPayload = unknown>(
+		id: string,
+		lease: ChatEffectLease,
+		leaseMs: number,
+	): Promise<ChatEffect<TPayload> | undefined> {
+		if (!Number.isFinite(leaseMs) || leaseMs <= 0) throw new Error("Chat effect lease duration must be positive");
+		let renewed: ChatEffect<TPayload> | undefined;
+		const now = this.#now();
+		await this.#store.transact(id, current => {
+			if (current?.state !== "leased" || current.owner !== lease.owner || current.epoch !== lease.epoch)
+				return current;
+			renewed = {
+				...current,
+				generation: current.generation + 1,
+				leaseExpiresAt: now + leaseMs,
+				updatedAt: now,
+			} as ChatEffect<TPayload>;
+			return renewed;
+		});
+		return renewed;
+	}
+
+	/** Persists provider progress without releasing the owner/epoch fence. */
+	async recordReceipt<TPayload = unknown>(
+		id: string,
+		lease: ChatEffectLease,
+		receipt: ChatEffectReceipt,
+	): Promise<ChatEffect<TPayload> | undefined> {
+		let recorded: ChatEffect<TPayload> | undefined;
+		const now = this.#now();
+		await this.#store.transact(id, current => {
+			if (current?.state !== "leased" || current.owner !== lease.owner || current.epoch !== lease.epoch)
+				return current;
+			recorded = {
+				...current,
+				generation: current.generation + 1,
+				receipt,
+				updatedAt: now,
+			} as ChatEffect<TPayload>;
+			return recorded;
+		});
+		return recorded;
+	}
+
+	async record<TPayload = unknown>(
+		id: string,
+		lease: ChatEffectLease,
+		state: Exclude<ChatEffectState, "pending" | "leased">,
+		receipt?: ChatEffectReceipt,
+	): Promise<ChatEffect<TPayload> | undefined> {
+		let recorded: ChatEffect<TPayload> | undefined;
+		const now = this.#now();
+		await this.#store.transact(id, current => {
+			if (current?.state !== "leased" || current.owner !== lease.owner || current.epoch !== lease.epoch)
+				return current;
+			recorded = {
+				...current,
+				generation: current.generation + 1,
+				state,
+				owner: undefined,
+				leaseExpiresAt: undefined,
+				receipt,
+				updatedAt: now,
+			} as ChatEffect<TPayload>;
+			return recorded;
+		});
+		if (recorded?.state === "terminal") await this.#pruneTerminal();
+		return recorded;
+	}
+
+	/** Irreversibly rejects an effect whose mapping never accepted its authority. */
+	async terminalize(id: string, receipt: ChatEffectReceipt, lease?: ChatEffectLease): Promise<ChatEffect | undefined> {
+		let terminalized: ChatEffect | undefined;
+		const now = this.#now();
+		await this.#store.transact(id, current => {
+			if (!current || current.state === "terminal") return current;
+			if (current.state === "leased" && (!lease || current.owner !== lease.owner || current.epoch !== lease.epoch))
+				return current;
+
+			terminalized = {
+				...current,
+				generation: current.generation + 1,
+				state: "terminal",
+				owner: undefined,
+				leaseExpiresAt: undefined,
+				receipt,
+				updatedAt: now,
+			};
+			return terminalized;
+		});
+		if (terminalized) await this.#pruneTerminal();
+		return terminalized;
+	}
+
+	async #pruneTerminal(): Promise<void> {
+		const terminal = (await this.list())
+			.filter(effect => effect.state === "terminal")
+			.sort((left, right) => left.updatedAt - right.updatedAt);
+		if (terminal.length <= this.#maxTerminalEffects) return;
+
+		const referenced = new Set<string>();
+		for (const mapping of Object.values((await this.#mappings.load()).conversations))
+			collectEffectReferences(mapping, referenced);
+		for (const effect of terminal.slice(0, terminal.length - this.#maxTerminalEffects)) {
+			if (!referenced.has(effect.id)) await this.#store.delete(effect.id, effect.generation);
+		}
+	}
+}

package/src/sdk/bus/config-commands.ts

@@ -0,0 +1,192 @@
+/**
+ * In-thread configuration slash commands for the threaded session surface.
+ *
+ * Replies are thread-native now (the old `/answer <sessionId> …` command is
+ * removed), but the user can still adjust per-surface behaviour from inside a
+ * session thread with small slash commands:
+ *
+ * - `/verbose`            switch the mirror to bounded tool-owned summaries + provider-displayable reasoning summaries
+ * - `/lean`               switch back to lean (assistant text + tool names)
+ * - `/verbosity lean|verbose`
+ * - `/redact on|off`      toggle redaction of streamed content
+ *
+ * This parser is pure so the command grammar is unit-testable; the daemon maps
+ * the returned change onto a `config_command` frame / settings update.
+ */
+
+/** A parsed in-thread configuration change. */
+export interface ConfigCommandChange {
+	verbosity?: "lean" | "verbose";
+	redact?: boolean;
+}
+
+export type TelegramControlCommandName = "reasoning" | "usage" | "context" | "compact" | "model";
+
+export type TelegramControlCommand =
+	| { name: "reasoning"; action: "cycle" | "status" | "set" | "show" | "hide"; level?: string; global?: boolean }
+	| { name: "usage" }
+	| { name: "context" }
+	| { name: "compact"; instructions?: string }
+	| { name: "model"; action: "list" | "set"; selector?: string };
+
+export type TelegramControlCommandParseResult =
+	| { kind: "none" }
+	| { kind: "ignored"; commandName: TelegramControlCommandName }
+	| { kind: "command"; command: TelegramControlCommand }
+	| { kind: "invalid"; commandName: TelegramControlCommandName; usage: string };
+
+const TELEGRAM_CONTROL_COMMANDS = new Set<TelegramControlCommandName>([
+	"reasoning",
+	"usage",
+	"context",
+	"compact",
+	"model",
+]);
+const TELEGRAM_REASONING_LEVELS = new Set(["inherit", "off", "minimal", "low", "medium", "high", "xhigh", "max"]);
+
+function splitTelegramBotSuffix(rawCommand: string): { name: string; suffix?: string } {
+	const [name, suffix] = rawCommand.toLowerCase().split("@", 2);
+	return suffix ? { name, suffix } : { name };
+}
+
+export function telegramControlCommandUsage(commandName: TelegramControlCommandName): string {
+	switch (commandName) {
+		case "reasoning":
+			return "Usage: /reasoning [cycle|inherit|reset|off|none|minimal|low|medium|high|xhigh|max|show|hide] [--global for set/reset/show/hide]";
+		case "usage":
+			return "Usage: /usage";
+		case "context":
+			return "Usage: /context";
+		case "compact":
+			return "Usage: /compact [instructions]";
+		case "model":
+			return "Usage: /model [provider/model]";
+	}
+}
+
+/** Parse deterministic Telegram session-control commands. Recognised roots fail closed. */
+export function parseTelegramControlCommand(text: string, botUsername?: string): TelegramControlCommandParseResult {
+	const trimmed = text.trim();
+	if (!trimmed.startsWith("/")) return { kind: "none" };
+	const [rawRoot, ...rest] = trimmed.slice(1).split(/\s+/);
+	if (!rawRoot) return { kind: "none" };
+	const { name: root, suffix } = splitTelegramBotSuffix(rawRoot);
+	if (!TELEGRAM_CONTROL_COMMANDS.has(root as TelegramControlCommandName)) return { kind: "none" };
+	const commandName = root as TelegramControlCommandName;
+	if (suffix && (!botUsername || suffix !== botUsername.toLowerCase())) return { kind: "ignored", commandName };
+	const usage = telegramControlCommandUsage(commandName);
+
+	switch (commandName) {
+		case "usage":
+		case "context":
+			return rest.length === 0
+				? { kind: "command", command: { name: commandName } }
+				: { kind: "invalid", commandName, usage };
+		case "compact": {
+			const instructions = trimmed.slice(rawRoot.length + 1).trim();
+			return { kind: "command", command: instructions ? { name: "compact", instructions } : { name: "compact" } };
+		}
+		case "reasoning": {
+			if (rest.length === 0) return { kind: "command", command: { name: "reasoning", action: "status" } };
+			const action = rest[0]!.toLowerCase();
+			if (action === "cycle") {
+				return rest.length === 1
+					? { kind: "command", command: { name: "reasoning", action: "cycle" } }
+					: { kind: "invalid", commandName, usage };
+			}
+			const global = rest[1]?.toLowerCase() === "--global";
+			if (rest.length > 2 || (rest.length === 2 && !global)) return { kind: "invalid", commandName, usage };
+			if (action === "show" || action === "hide") {
+				return {
+					kind: "command",
+					command: { name: "reasoning", action, ...(global ? { global: true } : {}) },
+				};
+			}
+			const level = action === "none" ? "off" : action === "reset" ? "inherit" : action;
+			if (TELEGRAM_REASONING_LEVELS.has(level)) {
+				return {
+					kind: "command",
+					command: { name: "reasoning", action: "set", level, ...(global ? { global: true } : {}) },
+				};
+			}
+			return { kind: "invalid", commandName, usage };
+		}
+		case "model":
+			if (rest.length === 0) return { kind: "command", command: { name: "model", action: "list" } };
+			return rest.length === 1
+				? { kind: "command", command: { name: "model", action: "set", selector: rest[0]! } }
+				: { kind: "invalid", commandName, usage };
+	}
+}
+
+/**
+ * Parse an in-thread config command. Returns the requested change, or
+ * `undefined` when the text is not a recognised config command (so the daemon
+ * can fall through to treating it as a free-text injection).
+ */
+export function parseInThreadConfigCommand(text: string): ConfigCommandChange | undefined {
+	const trimmed = text.trim();
+	if (!trimmed.startsWith("/")) return undefined;
+	const [rawCommand, ...rest] = trimmed.slice(1).split(/\s+/);
+	const command = rawCommand?.toLowerCase();
+	const arg = rest[0]?.toLowerCase();
+
+	switch (command) {
+		case "verbose":
+			return rest.length === 0 ? { verbosity: "verbose" } : undefined;
+		case "lean":
+			return rest.length === 0 ? { verbosity: "lean" } : undefined;
+		case "verbosity":
+			if (rest.length === 1 && (arg === "lean" || arg === "verbose")) return { verbosity: arg };
+			return undefined;
+		case "redact":
+			if (rest.length !== 1) return undefined;
+			if (arg === "on" || arg === "true" || arg === "1") return { redact: true };
+			if (arg === "off" || arg === "false" || arg === "0") return { redact: false };
+			return undefined;
+		default:
+			return undefined;
+	}
+}
+
+/**
+ * Parse a `/rich on|off` toggle. Returns `true`/`false` for a recognised
+ * on/off argument, or `undefined` otherwise (not a `/rich` command, or `/rich`
+ * with a missing/invalid argument). This is intentionally SEPARATE from
+ * `parseInThreadConfigCommand`: `/verbose`/`/redact` are producer/session config
+ * forwarded over the WS, whereas rich is Telegram-daemon delivery policy handled
+ * daemon-locally, so it never becomes a `config_command` frame or a user turn.
+ */
+export function parseRichToggleCommand(text: string): boolean | undefined {
+	const trimmed = text.trim();
+	if (!trimmed.startsWith("/")) return undefined;
+	const [rawCommand, ...rest] = trimmed.slice(1).split(/\s+/);
+	// Accept the "/rich@botname" form Telegram appends in group chats.
+	if (rawCommand?.toLowerCase().split("@")[0] !== "rich") return undefined;
+	const arg = rest[0]?.toLowerCase();
+	if (arg === "on" || arg === "true" || arg === "1") return true;
+	if (arg === "off" || arg === "false" || arg === "0") return false;
+	return undefined;
+}
+
+/**
+ * Parse a `/toolactivity on|off` toggle for Telegram tool-activity delivery.
+ *
+ * This is daemon-local delivery policy rather than a host-session config
+ * command, so it works without a connected session and persists globally.
+ * Addressed commands are accepted only for the exact current bot username.
+ */
+export function parseToolActivityToggleCommand(text: string, botUsername?: string): boolean | undefined {
+	const trimmed = text.trim();
+	if (!trimmed.startsWith("/")) return undefined;
+	const [rawCommand, ...rest] = trimmed.slice(1).split(/\s+/);
+	if (!rawCommand || rest.length !== 1) return undefined;
+	if (rawCommand.endsWith("@") || rawCommand.indexOf("@") !== rawCommand.lastIndexOf("@")) return undefined;
+	const { name, suffix } = splitTelegramBotSuffix(rawCommand);
+	if (name !== "toolactivity") return undefined;
+	if (suffix && (!botUsername || suffix !== botUsername.toLowerCase())) return undefined;
+	const arg = rest[0]!.toLowerCase();
+	if (arg === "on" || arg === "true" || arg === "1") return true;
+	if (arg === "off" || arg === "false" || arg === "0") return false;
+	return undefined;
+}