@gajae-code/coding-agent 0.10.1 → 0.11.0

package/src/sdk/bus/slack-live-provider.ts

@@ -0,0 +1,380 @@
+import type {
+	SlackMessageSearchResult,
+	SlackPostedMessage,
+	SlackProviderClient,
+	SlackSocketEnvelope,
+} from "./slack-provider";
+
+const SLACK_API = "https://slack.com/api";
+const DEFAULT_RECONNECT_DELAY_MS = 1_000;
+const MAX_RECONNECT_DELAY_MS = 30_000;
+const MAX_RETRY_AFTER_MS = 60_000;
+const MAX_RATE_LIMIT_RETRIES = 1;
+
+export type SlackProviderErrorCode = "connection" | "protocol" | "web_api" | "rate_limited";
+
+/** A Slack transport failure whose fields are safe to surface without credentials. */
+export class SlackProviderError extends Error {
+	readonly retryable: boolean;
+
+	constructor(
+		readonly code: SlackProviderErrorCode,
+		readonly operation: string,
+		readonly status?: number,
+		readonly retryAfterMs?: number,
+		/** The server may have accepted the request before its response became unusable. */
+		readonly mayHaveBeenAccepted = false,
+	) {
+		super(`${operation} failed (${code})`);
+		this.name = "SlackProviderError";
+		this.retryable = code === "connection" || code === "rate_limited";
+	}
+}
+
+export interface SlackWebSocket {
+	readonly readyState: number;
+	onopen: ((event: Event) => void) | null;
+	onmessage: ((event: MessageEvent) => void) | null;
+	onclose: ((event: CloseEvent) => void) | null;
+	onerror: ((event: Event) => void) | null;
+	send(data: string): void;
+	close(): void;
+}
+
+export interface SlackLiveProviderOptions {
+	appToken: string;
+	botToken: string;
+	fetch?: (input: string, init?: RequestInit) => Promise<Response>;
+	webSocket?: (url: string) => SlackWebSocket;
+	now?: () => number;
+	sleep?: (milliseconds: number) => Promise<void>;
+	reconnectDelayMs?: number;
+	maxRateLimitRetries?: number;
+	maxRetryAfterMs?: number;
+	activityTimeoutMs?: number;
+}
+
+type SlackApiMessage = {
+	channel?: unknown;
+	ts?: unknown;
+	client_msg_id?: unknown;
+};
+
+type SlackApiResponse = {
+	ok?: unknown;
+	url?: unknown;
+	channel?: unknown;
+	ts?: unknown;
+	client_msg_id?: unknown;
+	message?: unknown;
+	messages?: unknown;
+	retry_after?: unknown;
+};
+
+function string(value: unknown): string | undefined {
+	return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function messages(value: unknown): SlackApiMessage[] {
+	return Array.isArray(value)
+		? value.filter((item): item is SlackApiMessage => !!item && typeof item === "object")
+		: [];
+}
+
+function retryAfterMilliseconds(response: Response, body: SlackApiResponse, maximum: number): number {
+	const header = Number(response.headers.get("retry-after"));
+	const bodyValue = typeof body.retry_after === "number" ? body.retry_after : Number(body.retry_after);
+	const seconds = Number.isFinite(header) && header >= 0 ? header : bodyValue;
+	return Math.min(Math.max(0, Number.isFinite(seconds) ? seconds * 1_000 : 1_000), maximum);
+}
+
+function socketFromGlobal(url: string): SlackWebSocket {
+	return new WebSocket(url);
+}
+
+/**
+ * Production Socket Mode and Web API client. It keeps all connection state in
+ * memory and deliberately never maintains a Slack cursor.
+ */
+export class SlackLiveProvider implements SlackProviderClient {
+	readonly #appToken: string;
+	readonly #botToken: string;
+	readonly #fetch: (input: string, init?: RequestInit) => Promise<Response>;
+	readonly #webSocket: (url: string) => SlackWebSocket;
+	readonly #now: () => number;
+	readonly #sleep: (milliseconds: number) => Promise<void>;
+	readonly #reconnectDelayMs: number;
+	readonly #maxRateLimitRetries: number;
+	readonly #maxRetryAfterMs: number;
+	readonly #activityTimeoutMs: number;
+	#socket: SlackWebSocket | undefined;
+	readonly #envelopeSockets = new Map<string, SlackWebSocket>();
+	#onEnvelope: ((envelope: SlackSocketEnvelope) => void | Promise<void>) | undefined;
+	#lastActivityAt: number | undefined;
+	#callbackHealthy = true;
+	#deliverySequence = 0;
+	#lastCallbackFailure = 0;
+	#stopped = true;
+	get transportHealthy(): boolean {
+		const socket = this.#socket;
+		if (this.#stopped || !socket || socket.readyState !== 1 || !this.#callbackHealthy) return false;
+		if (this.#lastActivityAt === undefined || this.#now() - this.#lastActivityAt <= this.#activityTimeoutMs)
+			return true;
+		socket.close();
+		return false;
+	}
+	#reconnectPending = false;
+	#lifecycleGeneration = 0;
+
+	constructor(options: SlackLiveProviderOptions) {
+		this.#appToken = options.appToken;
+		this.#botToken = options.botToken;
+		this.#fetch = options.fetch ?? fetch;
+		this.#webSocket = options.webSocket ?? socketFromGlobal;
+		this.#now = options.now ?? Date.now;
+		this.#sleep =
+			options.sleep ?? (async milliseconds => await new Promise<void>(resolve => setTimeout(resolve, milliseconds)));
+		this.#reconnectDelayMs = Math.max(0, options.reconnectDelayMs ?? DEFAULT_RECONNECT_DELAY_MS);
+		this.#maxRateLimitRetries = Math.max(0, options.maxRateLimitRetries ?? MAX_RATE_LIMIT_RETRIES);
+		this.#maxRetryAfterMs = Math.max(0, options.maxRetryAfterMs ?? MAX_RETRY_AFTER_MS);
+		this.#activityTimeoutMs = Math.max(1, options.activityTimeoutMs ?? 60_000);
+	}
+
+	async start(onEnvelope: (envelope: SlackSocketEnvelope) => void | Promise<void>): Promise<void> {
+		this.#lifecycleGeneration++;
+		this.#onEnvelope = onEnvelope;
+		this.#stopped = false;
+		this.#callbackHealthy = true;
+		this.#lastActivityAt = undefined;
+		this.#deliverySequence = 0;
+		this.#lastCallbackFailure = 0;
+		await this.#connect();
+	}
+
+	async stop(): Promise<void> {
+		this.#lifecycleGeneration++;
+		this.#stopped = true;
+		this.#onEnvelope = undefined;
+		this.#socket?.close();
+		this.#envelopeSockets.clear();
+		this.#socket = undefined;
+		this.#lastActivityAt = undefined;
+		this.#callbackHealthy = false;
+		this.#lastCallbackFailure = 0;
+	}
+
+	async ack(envelopeId: string): Promise<void> {
+		const socket = this.#envelopeSockets.get(envelopeId) ?? this.#socket;
+		if (!envelopeId || !socket || socket.readyState !== 1) {
+			throw new SlackProviderError("connection", "socket_ack");
+		}
+		socket.send(JSON.stringify({ envelope_id: envelopeId }));
+		this.#envelopeSockets.delete(envelopeId);
+	}
+
+	async postMessage(input: {
+		channel: string;
+		text: string;
+		threadTs?: string;
+		clientMsgId: string;
+	}): Promise<SlackPostedMessage> {
+		const response = await this.#api("chat.postMessage", {
+			channel: input.channel,
+			text: input.text,
+			thread_ts: input.threadTs,
+			client_msg_id: input.clientMsgId,
+		});
+		const message = this.#message(response);
+		// A successful HTTP response without a usable receipt can still represent a
+		// remote acceptance. The daemon must reconcile by client_msg_id before retrying.
+		if (!message) throw new SlackProviderError("protocol", "chat.postMessage", undefined, undefined, true);
+		return message;
+	}
+
+	async findMessageByClientMsgId(input: {
+		channel: string;
+		clientMsgId: string;
+		threadTs?: string;
+	}): Promise<SlackMessageSearchResult | null> {
+		const response = await this.#api("conversations.history", { channel: input.channel });
+		const fromHistory = this.#findMessage(response, input.clientMsgId, input.channel);
+		if (fromHistory || !input.threadTs) return fromHistory;
+		const replies = await this.#api("conversations.replies", { channel: input.channel, ts: input.threadTs });
+		return this.#findMessage(replies, input.clientMsgId, input.channel);
+	}
+
+	async #connect(generation = this.#lifecycleGeneration): Promise<void> {
+		const opened = await this.#openSocketUrl();
+		if (this.#stopped || generation !== this.#lifecycleGeneration) return;
+		await new Promise<void>((resolve, reject) => {
+			const socket = this.#webSocket(opened);
+			let openedConnection = false;
+			this.#socket = socket;
+			socket.onopen = () => {
+				openedConnection = true;
+				this.#lastActivityAt = this.#now();
+				this.#callbackHealthy = true;
+				this.#lastCallbackFailure = 0;
+				resolve();
+			};
+			socket.onmessage = event => this.#receive(socket, event.data);
+			socket.onerror = () => {
+				if (!openedConnection) {
+					reject(new SlackProviderError("connection", "socket_connect"));
+					return;
+				}
+				this.#callbackHealthy = false;
+				socket.close();
+			};
+			socket.onclose = () => {
+				if (this.#socket === socket) this.#socket = undefined;
+				if (!openedConnection) {
+					reject(new SlackProviderError("connection", "socket_connect"));
+					return;
+				}
+				if (!this.#stopped) void this.#reconnect();
+			};
+		});
+	}
+
+	async #reconnect(): Promise<void> {
+		if (this.#reconnectPending || this.#stopped) return;
+		this.#reconnectPending = true;
+		const generation = this.#lifecycleGeneration;
+		let failures = 0;
+		try {
+			while (!this.#stopped && generation === this.#lifecycleGeneration) {
+				const delay = Math.min(MAX_RECONNECT_DELAY_MS, this.#reconnectDelay(failures));
+				await this.#sleep(delay);
+				if (this.#stopped || generation !== this.#lifecycleGeneration) return;
+				try {
+					await this.#connect(generation);
+					return;
+				} catch {
+					// A dropped replacement connection may have accepted the open request.
+					// Keep retrying for this worker's lifetime with a bounded delay.
+					failures++;
+				}
+			}
+		} finally {
+			this.#reconnectPending = false;
+		}
+	}
+	#reconnectDelay(failures: number): number {
+		return Math.max(1, this.#reconnectDelayMs * 2 ** Math.min(failures, 30));
+	}
+
+	#receive(socket: SlackWebSocket, data: unknown): void {
+		if (typeof data !== "string") return;
+		try {
+			const decoded: unknown = JSON.parse(data);
+			if (!decoded || typeof decoded !== "object") return;
+			this.#lastActivityAt = this.#now();
+			const candidate = decoded as { envelope_id?: unknown; payload?: unknown };
+			const envelopeId = string(candidate.envelope_id);
+			if (!envelopeId) return;
+			this.#envelopeSockets.set(envelopeId, socket);
+			const sequence = ++this.#deliverySequence;
+			void this.#deliverEnvelope(socket, sequence, { envelope_id: envelopeId, payload: candidate.payload });
+		} catch {
+			// Socket Mode can safely ignore malformed frames; Slack redelivers unacknowledged envelopes.
+		}
+	}
+	async #deliverEnvelope(socket: SlackWebSocket, sequence: number, envelope: SlackSocketEnvelope): Promise<void> {
+		try {
+			await this.#onEnvelope?.(envelope);
+			if (this.#socket === socket && sequence > this.#lastCallbackFailure) this.#callbackHealthy = true;
+		} catch {
+			if (this.#socket !== socket) return;
+			// Callback failures are transport failures: retain the unhealthy state until a newer valid delivery or reconnect.
+			this.#lastCallbackFailure = sequence;
+			this.#callbackHealthy = false;
+		}
+	}
+
+	async #openSocketUrl(): Promise<string> {
+		const response = await this.#request("apps.connections.open", this.#appToken, {});
+		const url = string(response.url);
+		if (!url) throw new SlackProviderError("protocol", "apps.connections.open");
+		return url;
+	}
+
+	async #api(operation: string, body: Record<string, string | undefined>): Promise<SlackApiResponse> {
+		const result = await this.#request(operation, this.#botToken, body, true);
+		if (result.ok === true) return result;
+		throw new SlackProviderError("web_api", operation);
+	}
+
+	async #request(
+		operation: string,
+		token: string,
+		body: Record<string, string | undefined>,
+		retryRateLimit = false,
+	): Promise<SlackApiResponse> {
+		for (let attempt = 0; ; attempt++) {
+			let response: Response;
+			try {
+				response = await this.#fetch(`${SLACK_API}/${operation}`, {
+					method: "POST",
+					headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json; charset=utf-8" },
+					body: JSON.stringify(body),
+				});
+			} catch {
+				throw new SlackProviderError("connection", operation);
+			}
+			let parsed: unknown;
+			try {
+				parsed = await response.json();
+			} catch {
+				throw new SlackProviderError(
+					"protocol",
+					operation,
+					response.status,
+					undefined,
+					operation === "chat.postMessage" && response.ok,
+				);
+			}
+			const result = parsed && typeof parsed === "object" ? (parsed as SlackApiResponse) : {};
+			if (response.status !== 429) {
+				if (!response.ok) throw new SlackProviderError("web_api", operation, response.status);
+				return result;
+			}
+			const retryAfterMs = retryAfterMilliseconds(response, result, this.#maxRetryAfterMs);
+			if (!retryRateLimit || attempt >= this.#maxRateLimitRetries) {
+				throw new SlackProviderError("rate_limited", operation, response.status, retryAfterMs);
+			}
+			const startedAt = this.#now();
+			await this.#sleep(retryAfterMs);
+			if (this.#now() - startedAt > this.#maxRetryAfterMs) {
+				throw new SlackProviderError("rate_limited", operation, response.status, retryAfterMs);
+			}
+		}
+	}
+
+	#message(response: SlackApiResponse): SlackPostedMessage | undefined {
+		const direct: SlackApiMessage = {
+			channel: response.channel,
+			ts: response.ts,
+			client_msg_id: response.client_msg_id,
+		};
+		const nested = messages(response.message ? [response.message] : response.messages)[0];
+		const candidate = string(direct.channel) && string(direct.ts) ? direct : nested;
+		const channel = string(candidate?.channel);
+		const ts = string(candidate?.ts);
+		return channel && ts ? { channel, ts, client_msg_id: string(candidate.client_msg_id) } : undefined;
+	}
+
+	#findMessage(
+		response: SlackApiResponse,
+		clientMsgId: string,
+		requestedChannel: string,
+	): SlackMessageSearchResult | null {
+		for (const candidate of messages(response.messages)) {
+			const ts = string(candidate.ts);
+			if (ts && string(candidate.client_msg_id) === clientMsgId) {
+				return { channel: string(candidate.channel) ?? requestedChannel, ts, client_msg_id: clientMsgId };
+			}
+		}
+		return null;
+	}
+}

package/src/sdk/bus/slack-provider.ts

@@ -0,0 +1,76 @@
+export interface SlackSocketEnvelope {
+	envelope_id: string;
+	payload: unknown;
+}
+
+export interface SlackPostedMessage {
+	channel: string;
+	ts: string;
+	client_msg_id?: string;
+}
+
+export interface SlackMessageSearchResult {
+	channel: string;
+	ts: string;
+	client_msg_id?: string;
+}
+
+/** Minimal Socket Mode + Web API seam. Implementations may wrap the official Slack SDK. */
+export interface SlackProviderClient {
+	start(onEnvelope: (envelope: SlackSocketEnvelope) => void | Promise<void>): Promise<void>;
+	stop?(): Promise<void>;
+	ack(envelopeId: string): Promise<void>;
+	postMessage(input: {
+		channel: string;
+		text: string;
+		threadTs?: string;
+		clientMsgId: string;
+	}): Promise<SlackPostedMessage>;
+	findMessageByClientMsgId?(input: {
+		channel: string;
+		clientMsgId: string;
+		threadTs?: string;
+	}): Promise<SlackMessageSearchResult | null>;
+	readonly transportHealthy?: boolean;
+}
+
+/**
+ * Transport wrapper deliberately limited to Slack SDK operations. Keeping it injectable
+ * makes Socket Mode acknowledgement and Web API failure cases deterministic in tests.
+ */
+export class SlackProvider {
+	constructor(private readonly client: SlackProviderClient) {}
+
+	async start(onEnvelope: (envelope: SlackSocketEnvelope) => void | Promise<void>): Promise<void> {
+		await this.client.start(onEnvelope);
+	}
+
+	get transportHealthy(): boolean {
+		return this.client.transportHealthy ?? true;
+	}
+
+	async stop(): Promise<void> {
+		await this.client.stop?.();
+	}
+
+	async ack(envelopeId: string): Promise<void> {
+		await this.client.ack(envelopeId);
+	}
+
+	async postMessage(input: {
+		channel: string;
+		text: string;
+		threadTs?: string;
+		clientMsgId: string;
+	}): Promise<SlackPostedMessage> {
+		return await this.client.postMessage(input);
+	}
+
+	async findMessageByClientMsgId(input: {
+		channel: string;
+		clientMsgId: string;
+		threadTs?: string;
+	}): Promise<SlackMessageSearchResult | null> {
+		return (await this.client.findMessageByClientMsgId?.(input)) ?? null;
+	}
+}

package/src/{notifications → sdk/bus}/telegram-cli.ts

@@ -1,20 +1,20 @@
 #!/usr/bin/env bun
 /**
- * Reference CLI for the notifications SDK Telegram client.
+ * Reference CLI for the Gajae-Code SDK Telegram client.
  *
  * Bridges a running GJC session's notification endpoint to a Telegram bot so you
  * can answer asks / see idle pings from your phone — no RPC mode required. This
- * is an EXAMPLE/template (the SDK contract is in `docs/notifications-sdk.md`);
+ * is an EXAMPLE/template (the SDK contract is in `docs/sdk.md`);
  * Discord/Slack clients are written the same way.
  *
  * Usage:
- *   bun run packages/coding-agent/src/notifications/telegram-cli.ts \
+ *   bun run packages/coding-agent/src/sdk/bus/telegram-cli.ts \
  *     --bot-token <token> [--chat-id <id>] [--endpoint-file <path> | --session-id <id>] [--repo <dir>]
  *
  * Env fallbacks: GJC_TG_BOT_TOKEN, GJC_TG_CHAT_ID.
  * If --chat-id is omitted it is auto-resolved from getUpdates (message the bot once).
  * If neither --endpoint-file nor --session-id is given, the newest endpoint file
- * under <repo>/.gjc/state/notifications/ is used.
+ * under <repo>/.gjc/state/sdk/ is used.
  */
 
 import * as fs from "node:fs";
@@ -79,7 +79,7 @@ function printHelpAndExit(): never {
 			"  --bot-token <token>     Telegram bot token (or env GJC_TG_BOT_TOKEN)",
 			"  --chat-id <id>          Target chat id (or env GJC_TG_CHAT_ID; auto-resolved if omitted)",
 			"  --endpoint-file <path>  Session endpoint discovery file",
-			"  --session-id <id>       Resolve <repo>/.gjc/state/notifications/<id>.json",
+			"  --session-id <id>       Resolve <repo>/.gjc/state/sdk/<id>.json",
 			"  --repo <dir>            Repo root for endpoint discovery (default: cwd)",
 			"  --api-base <url>        Telegram API base (default: https://api.telegram.org)",
 			"  --force                 Bypass active daemon guard (debug only; may cause Telegram 409 conflicts)",
@@ -91,7 +91,7 @@ function printHelpAndExit(): never {
 
 /** Find the most recently modified endpoint discovery file under the repo. */
 function findLatestEndpoint(repo: string): string | undefined {
-	const dir = path.join(repo, ".gjc", "state", "notifications");
+	const dir = path.join(repo, ".gjc", "state", "sdk");
 	let entries: string[];
 	try {
 		entries = fs.readdirSync(dir).filter(f => f.endsWith(".json"));
@@ -166,11 +166,11 @@ async function main(): Promise<void> {
 
 	const endpointFile =
 		args.endpointFile ??
-		(args.sessionId ? path.join(args.repo, ".gjc", "state", "notifications", `${args.sessionId}.json`) : undefined) ??
+		(args.sessionId ? path.join(args.repo, ".gjc", "state", "sdk", `${args.sessionId}.json`) : undefined) ??
 		findLatestEndpoint(args.repo);
 	if (!endpointFile || !fs.existsSync(endpointFile)) {
 		process.stderr.write(
-			`error: no endpoint file found (looked under ${args.repo}/.gjc/state/notifications). Start a session with GJC_NOTIFICATIONS=1 first.\n`,
+			`error: no endpoint file found (looked under ${args.repo}/.gjc/state/sdk). Start a session with GJC_NOTIFICATIONS=1 first.\n`,
 		);
 		process.exit(2);
 	}