@sayknow-cli/coding-agent 0.3.16 → 0.4.1

package/src/sdk/bus/topic-registry.ts

@@ -0,0 +1,364 @@
+/**
+ * Per-session forum-topic registry for the threaded session surface.
+ *
+ * Each SKC session owns one active Telegram forum topic in the paired private
+ * DM. The topic is created via `createForumTopic`, reused while the session
+ * remains active, and removed from the registry when the daemon deletes it on
+ * shutdown. The registry also tracks whether the one-time identity header has
+ * already been pinned, so it is sent exactly once per active topic, even across
+ * reconnects.
+ *
+ * State is a plain serialisable map persisted beside the daemon state files;
+ * topic creation is injected so this module is pure and unit-testable without a
+ * live Bot API.
+ */
+
+/** Persisted record for one session's topic. */
+export interface TopicRecord {
+	/** Telegram forum topic id (message_thread_id). */
+	topicId: string;
+	/** Whether the one-time identity header has been sent/pinned. */
+	identitySent: boolean;
+	/** Creation timestamp (ms epoch). */
+	createdAt: number;
+	/** First positive observation that the owning endpoint is stale, dead, or missing. */
+	orphanedAt?: number;
+	/** 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;
+	/** Last SDK event generation durably consumed by the notification daemon. */
+	replayGeneration?: number;
+	/** Last SDK event sequence durably consumed within replayGeneration. */
+	replaySeq?: number;
+	/** Serialized authority epoch; a late create may commit only in its starting epoch. */
+	authorityEpoch?: number;
+	/** An uncertain delete fences future creation and inbound routing. */
+	authorityState?: "active" | "delete_pending";
+}
+
+/** Serialisable shape persisted to disk. */
+export interface TopicRegistryState {
+	/** sessionId -> record. */
+	topics: Record<string, TopicRecord>;
+	/** Durable deletion epochs retained after a definite delete. */
+	fences?: Record<string, number>;
+}
+
+function isValidTopicId(value: unknown): value is string {
+	return (
+		typeof value === "string" && /^[1-9]\d*$/.test(value) && Number.isSafeInteger(Number(value)) && Number(value) > 0
+	);
+}
+
+export function emptyTopicRegistryState(): TopicRegistryState {
+	return { topics: {} };
+}
+
+/**
+ * In-memory registry over a serialisable state. Topic creation is injected via
+ * `getOrCreateTopic`'s `create` callback (the daemon supplies a real
+ * `createForumTopic` call); reuse-on-resume is automatic when a record exists.
+ */
+export class TopicRegistry {
+	private readonly topics: Map<string, TopicRecord>;
+	/** Maps topicId -> sessionId for fast inbound routing. */
+	private readonly byTopic = new Map<string, string>();
+	/** Persisted collisions are ambiguous and must never authorize inbound routing. */
+	readonly #ambiguousTopicIds = new Set<string>();
+	/** In-flight create promises, keyed by session, to dedupe concurrent creates. */
+	private readonly inflight = new Map<string, Promise<TopicRecord>>();
+	/** Monotonic authority epochs, including deletion fences for absent records. */
+	private readonly epochs = new Map<string, number>();
+
+	constructor(state: TopicRegistryState = emptyTopicRegistryState()) {
+		this.topics = new Map();
+		this.load(state);
+	}
+
+	/** Merge serialized state and normalize authority fields from older releases. */
+	load(state: TopicRegistryState): void {
+		for (const [sessionId, epoch] of Object.entries(state.fences ?? {})) {
+			if (Number.isSafeInteger(epoch) && epoch >= 0) this.epochs.set(sessionId, epoch);
+		}
+
+		for (const [sessionId, raw] of Object.entries(state.topics ?? {})) {
+			if (!raw || !isValidTopicId(raw.topicId)) 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 hasValidReplayCursor =
+				typeof raw.replayGeneration === "number" &&
+				Number.isSafeInteger(raw.replayGeneration) &&
+				raw.replayGeneration >= 1 &&
+				typeof raw.replaySeq === "number" &&
+				Number.isSafeInteger(raw.replaySeq) &&
+				raw.replaySeq >= 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 } : {}),
+				...(typeof raw.orphanedAt === "number" && Number.isFinite(raw.orphanedAt) && raw.orphanedAt >= 0
+					? { orphanedAt: raw.orphanedAt }
+					: {}),
+				...(hasValidUserAuthority ? { nameOwner: "user" as const } : {}),
+				...(hasValidUserAuthority && raw.nameReconcilePending === true ? { nameReconcilePending: true } : {}),
+				...(hasValidUserAuthority ? { userNameUpdateId: raw.userNameUpdateId } : {}),
+				...(typeof raw.identityKey === "string" ? { identityKey: raw.identityKey } : {}),
+				...(hasValidReplayCursor ? { replayGeneration: raw.replayGeneration, replaySeq: raw.replaySeq } : {}),
+				...(Number.isSafeInteger(raw.authorityEpoch) && raw.authorityEpoch! >= 0
+					? { authorityEpoch: raw.authorityEpoch }
+					: {}),
+				...(raw.authorityState === "delete_pending" ? { authorityState: "delete_pending" as const } : {}),
+			};
+			this.epochs.set(sessionId, Math.max(this.epochs.get(sessionId) ?? 0, record.authorityEpoch ?? 0));
+
+			this.topics.set(sessionId, record);
+		}
+		this.rebuildInboundRoutes();
+	}
+
+	private rebuildInboundRoutes(): void {
+		this.byTopic.clear();
+		this.#ambiguousTopicIds.clear();
+		const activeByTopic = new Map<string, string>();
+
+		for (const [sessionId, record] of this.topics) {
+			if (record.authorityState === "delete_pending") {
+				this.#ambiguousTopicIds.add(record.topicId);
+				continue;
+			}
+			if (activeByTopic.has(record.topicId)) {
+				this.#ambiguousTopicIds.add(record.topicId);
+				continue;
+			}
+			activeByTopic.set(record.topicId, sessionId);
+		}
+
+		for (const [topicId, sessionId] of activeByTopic) {
+			if (!this.#ambiguousTopicIds.has(topicId)) this.byTopic.set(topicId, sessionId);
+		}
+	}
+
+	/** Resolve the owning session for a topic id (for fail-closed inbound routing). */
+	sessionForTopic(topicId: string): string | undefined {
+		return this.byTopic.get(topicId);
+	}
+
+	/** All session ids with a persisted topic record. */
+	sessionIds(): string[] {
+		return [...this.topics.keys()];
+	}
+
+	/** The existing topic record for a session, if any. */
+	get(sessionId: string): TopicRecord | undefined {
+		return this.topics.get(sessionId);
+	}
+
+	/**
+	 * Return the existing active topic for `sessionId`, or create one via
+	 * `create` (called only on first use).
+	 */
+	async getOrCreateTopic(
+		sessionId: string,
+		create: () => Promise<unknown>,
+		now: () => number = Date.now,
+		name?: string,
+	): Promise<TopicRecord> {
+		const existing = this.topics.get(sessionId);
+		if (existing?.authorityState === "delete_pending") throw new Error("topic authority is deletion-fenced");
+		if (existing) return existing;
+		const pending = this.inflight.get(sessionId);
+		if (pending) return pending;
+		const epoch = this.epochs.get(sessionId) ?? 0;
+		const promise = (async () => {
+			const topicId = await create();
+			if (!isValidTopicId(topicId)) throw new Error("createForumTopic: invalid message_thread_id");
+			const revoked = (this.epochs.get(sessionId) ?? 0) !== epoch;
+			const record: TopicRecord = {
+				topicId,
+				name,
+				identitySent: false,
+				createdAt: now(),
+				authorityEpoch: revoked ? (this.epochs.get(sessionId) ?? 0) : epoch,
+				...(revoked ? { authorityState: "delete_pending" as const } : {}),
+			};
+			this.topics.set(sessionId, record);
+			if (revoked) throw new Error("topic authority was revoked during creation");
+			if (this.#ambiguousTopicIds.has(topicId)) return record;
+			if (this.byTopic.has(topicId)) {
+				this.byTopic.delete(topicId);
+				this.#ambiguousTopicIds.add(topicId);
+				return record;
+			}
+			this.byTopic.set(topicId, sessionId);
+			return record;
+		})();
+		this.inflight.set(sessionId, promise);
+		try {
+			return await promise;
+		} finally {
+			this.inflight.delete(sessionId);
+		}
+	}
+
+	/** Mark the identity header as sent for a session. Idempotent. */
+	markIdentitySent(sessionId: string): void {
+		const record = this.topics.get(sessionId);
+		if (record) record.identitySent = true;
+	}
+
+	/** Whether the identity header still needs sending for this session. */
+	needsIdentity(sessionId: string): boolean {
+		const record = this.topics.get(sessionId);
+		return record ? !record.identitySent : true;
+	}
+
+	/** 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;
+	}
+	/** Start the orphan grace clock on the first positive liveness-loss observation. */
+	markOrphaned(sessionId: string, now: number): boolean {
+		const record = this.topics.get(sessionId);
+		if (!record || record.orphanedAt !== undefined) return false;
+		record.orphanedAt = now;
+		return true;
+	}
+
+	/** Clear a prior orphan observation after the endpoint is positively live again. */
+	clearOrphaned(sessionId: string): boolean {
+		const record = this.topics.get(sessionId);
+		if (!record || record.orphanedAt === undefined) return false;
+		delete record.orphanedAt;
+		return true;
+	}
+
+	/** Last durably consumed SDK event cursor for reconnect replay. */
+	replayCursor(sessionId: string): { generation: number; seq: number } | undefined {
+		const record = this.topics.get(sessionId);
+		return record?.replayGeneration !== undefined && record.replaySeq !== undefined
+			? { generation: record.replayGeneration, seq: record.replaySeq }
+			: undefined;
+	}
+
+	/** Advance the durable reconnect cursor without allowing stale responses to move it backwards. */
+	markReplayCursor(sessionId: string, generation: number, seq: number): boolean {
+		const record = this.topics.get(sessionId);
+		if (!record) return false;
+		const currentGeneration = record.replayGeneration ?? 0;
+		const currentSeq = record.replaySeq ?? 0;
+		if (generation < currentGeneration || (generation === currentGeneration && seq <= currentSeq)) return false;
+		record.replayGeneration = generation;
+		record.replaySeq = seq;
+		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.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 daemon topic title. */
+	markNameApplied(sessionId: string, name: string): void {
+		const record = this.topics.get(sessionId);
+		if (!record || record.nameOwner === "user") return;
+		record.name = name;
+		record.nameReconcilePending = false;
+	}
+
+	/** Fence new work before the remote delete starts, including an absent in-flight create. */
+	beginDelete(sessionId: string): TopicRecord | undefined {
+		const record = this.topics.get(sessionId);
+		const epoch = Math.max(this.epochs.get(sessionId) ?? 0, record?.authorityEpoch ?? 0) + 1;
+		this.epochs.set(sessionId, epoch);
+		if (!record) return undefined;
+		record.authorityEpoch = epoch;
+		record.authorityState = "delete_pending";
+		if (this.byTopic.get(record.topicId) === sessionId) this.byTopic.delete(record.topicId);
+		return record;
+	}
+
+	/** Wait for a revoked create to settle before admitting a later lifecycle epoch. */
+	async awaitInflight(sessionId: string): Promise<void> {
+		await this.inflight.get(sessionId)?.catch(() => undefined);
+	}
+
+	/** Remove only after a definite remote deletion; ambiguity deliberately retains its fence. */
+	settleDelete(sessionId: string, topicId: string): boolean {
+		const record = this.topics.get(sessionId);
+		if (!record || record.topicId !== topicId || record.authorityState !== "delete_pending") return false;
+		this.topics.delete(sessionId);
+		return true;
+	}
+
+	/** Remove a topic record immediately for local/test cleanup compatibility. */
+	delete(sessionId: string): boolean {
+		const record = this.topics.get(sessionId);
+		if (!record) return false;
+		this.epochs.set(sessionId, Math.max(this.epochs.get(sessionId) ?? 0, record.authorityEpoch ?? 0) + 1);
+		if (this.byTopic.get(record.topicId) === sessionId) this.byTopic.delete(record.topicId);
+		return this.topics.delete(sessionId);
+	}
+
+	/** Serialise for atomic persistence beside the daemon state. */
+	serialize(): TopicRegistryState {
+		return { topics: Object.fromEntries(this.topics), fences: Object.fromEntries(this.epochs) };
+	}
+}

package/src/sdk/cli/index.ts

@@ -0,0 +1 @@
+export * from "./session-cli";

package/src/sdk/cli/session-cli.ts

@@ -0,0 +1,275 @@
+import * as fs from "node:fs/promises";
+import { createInterface } from "node:readline/promises";
+import { getAgentDir } from "@sayknow-cli/utils";
+import { ensureBroker } from "../broker/ensure";
+import {
+	listSdkSessionEndpoints,
+	readSdkBrokerDiscovery,
+	readSdkSessionEndpoint,
+	SdkClient,
+	SdkClientError,
+	SdkDiscoveryError,
+} from "../client";
+import { validateAdapterControl } from "../protocol/adapter-validation";
+import { adapterDispositionError, findOperation, type OperationKind } from "../protocol/operation-registry";
+
+export type SdkSessionCliAction = "list" | "control" | "query" | "global";
+
+export interface SdkSessionCliArgs {
+	action?: string;
+	sessionId?: string;
+	operation?: string;
+	query?: string;
+	jsonInput?: string;
+	jsonInputFile?: string;
+	idempotencyKey?: string;
+	jsonInputStdin?: boolean;
+	confirm?: boolean;
+	cursor?: string;
+	showEndpointCredential?: boolean;
+	yes?: boolean;
+	repo?: string;
+	agentDir?: string;
+}
+
+type JsonRecord = Record<string, unknown>;
+const SECRET_FIELD = /(?:secret|token|password|credential|authorization|api[_-]?key)/i;
+
+class SdkSessionCliError extends Error {
+	constructor(
+		readonly code: string,
+		message: string,
+		readonly exitCode: 1 | 2,
+	) {
+		super(message);
+	}
+}
+
+function writeJson(value: unknown): void {
+	process.stdout.write(`${JSON.stringify(value)}\n`);
+}
+
+function parseInput(raw: string | undefined, source: string): JsonRecord {
+	if (raw === undefined) return {};
+	try {
+		const value: unknown = JSON.parse(raw);
+		if (!value || typeof value !== "object" || Array.isArray(value))
+			throw new SdkSessionCliError("invalid_input", `${source} must be a JSON object.`, 2);
+		return value as JsonRecord;
+	} catch (error) {
+		if (error instanceof SdkSessionCliError) throw error;
+		throw new SdkSessionCliError("invalid_json", `${source} must contain valid JSON.`, 2);
+	}
+}
+
+function containsSecretField(value: unknown): boolean {
+	if (Array.isArray(value)) return value.some(containsSecretField);
+	if (!value || typeof value !== "object") return false;
+	return Object.entries(value).some(([key, nested]) => SECRET_FIELD.test(key) || containsSecretField(nested));
+}
+
+async function inputFromArgs(args: SdkSessionCliArgs): Promise<JsonRecord> {
+	const sources = [
+		args.jsonInput !== undefined,
+		args.jsonInputFile !== undefined,
+		args.jsonInputStdin === true,
+	].filter(Boolean).length;
+	if (sources > 1) throw new SdkSessionCliError("usage", "Use only one JSON input source.", 2);
+	if (args.jsonInput !== undefined) {
+		const input = parseInput(args.jsonInput, "--json-input");
+		if (containsSecretField(input))
+			throw new SdkSessionCliError(
+				"secret_field_forbidden",
+				"Secret values must use --json-input-file or --json-input-stdin.",
+				2,
+			);
+		return input;
+	}
+	if (args.jsonInputFile !== undefined) {
+		let stat: Awaited<ReturnType<typeof fs.stat>>;
+		try {
+			stat = await fs.stat(args.jsonInputFile);
+		} catch {
+			throw new SdkSessionCliError("input_file_unavailable", "Unable to read --json-input-file.", 2);
+		}
+		if (!stat.isFile() || (stat.mode & 0o077) !== 0)
+			throw new SdkSessionCliError(
+				"input_file_permissions",
+				"--json-input-file must be a regular file with 0600 permissions.",
+				2,
+			);
+		try {
+			return parseInput(await fs.readFile(args.jsonInputFile, "utf8"), "--json-input-file");
+		} catch (error) {
+			if (error instanceof SdkSessionCliError) throw error;
+			throw new SdkSessionCliError("input_file_unavailable", "Unable to read --json-input-file.", 2);
+		}
+	}
+	return args.jsonInputStdin ? parseInput(await Bun.stdin.text(), "--json-input-stdin") : {};
+}
+
+function requireValue(value: string | undefined, flag: string): string {
+	if (!value) throw new SdkSessionCliError("usage", `${flag} is required.`, 2);
+	return value;
+}
+
+function isEndpointOperation(operation: string): boolean {
+	return operation === "session.get_endpoint";
+}
+
+function cliOperationError(kind: OperationKind, operation: string): { code: string; message: string } | undefined {
+	const row = findOperation(kind, operation);
+	const error = adapterDispositionError("daemonCli", kind, operation);
+	if (!error) return undefined;
+	if (row?.adapterDispositions.daemonCli === "prohibited")
+		return {
+			code: error.code,
+			message: `${operation} is unavailable through the ordinary CLI; provider mode is out of scope this phase.`,
+		};
+	return error;
+}
+
+function isLifecycleOperation(operation: string): boolean {
+	return (
+		operation === "session.create" ||
+		operation === "session.fork" ||
+		operation === "session.resume" ||
+		operation === "session.close" ||
+		operation === "session.delete"
+	);
+}
+
+async function confirmEndpointCredentialOutput(): Promise<boolean> {
+	const prompt = createInterface({ input: process.stdin, output: process.stderr });
+	try {
+		return (await prompt.question("Print the endpoint credential to stdout? [y/N] ")).trim().toLowerCase() === "y";
+	} finally {
+		prompt.close();
+	}
+}
+
+async function connectBroker(agentDir: string): Promise<SdkClient> {
+	await ensureBroker({ agentDir });
+	const discovery = await readSdkBrokerDiscovery(agentDir);
+	if (!discovery) throw new SdkSessionCliError("broker_unavailable", "SDK broker discovery is unavailable.", 1);
+	return await SdkClient.connect(discovery.url, discovery.token);
+}
+
+async function connectSession(repo: string, sessionId: string): Promise<SdkClient> {
+	const endpoint = await readSdkSessionEndpoint(repo, sessionId);
+	if (!endpoint)
+		throw new SdkSessionCliError("session_unavailable", `SDK endpoint for session ${sessionId} is unavailable.`, 1);
+	return await SdkClient.connect(endpoint.url, endpoint.token);
+}
+
+function brokerAbsent(error: unknown): boolean {
+	if (error instanceof SdkSessionCliError) return error.code === "broker_unavailable";
+	const details = error instanceof SdkClientError ? error.details : error;
+	const code = (details as { code?: unknown } | undefined)?.code;
+	return (
+		code === "ENOENT" ||
+		code === "ECONNREFUSED" ||
+		/(?:ENOENT|ECONNREFUSED|connection refused)/i.test(error instanceof Error ? error.message : "")
+	);
+}
+
+async function runList(repo: string, agentDir: string): Promise<unknown> {
+	try {
+		const client = await connectBroker(agentDir);
+		try {
+			return await client.global("session.list", {});
+		} finally {
+			await client.close();
+		}
+	} catch (error) {
+		if (!brokerAbsent(error)) throw error;
+		const { endpoints, warnings } = await listSdkSessionEndpoints(repo);
+		return {
+			sessions: endpoints.map(({ sessionId, path }) => ({ sessionId, path })),
+			warnings: [
+				{ code: "broker_unavailable", message: "Listed endpoint files because the broker is unavailable." },
+				...warnings,
+			],
+		};
+	}
+}
+
+/** Runs the pure-SDK `skc daemon session` command family. */
+export async function runSdkSessionCli(
+	args: SdkSessionCliArgs,
+	writeOutput: (value: unknown) => void = writeJson,
+	setExitCode: (exitCode: 1 | 2) => void = exitCode => {
+		process.exitCode = exitCode;
+	},
+): Promise<void> {
+	try {
+		const action = args.action;
+		if (action !== "list" && action !== "control" && action !== "query" && action !== "global")
+			throw new SdkSessionCliError("usage", "Expected one of: list, control, query, global.", 2);
+		const repo = args.repo ?? process.cwd();
+		const agentDir = args.agentDir ?? getAgentDir();
+		if (action === "list") {
+			writeOutput(await runList(repo, agentDir));
+			return;
+		}
+		const operation = action === "query" ? requireValue(args.query, "--query") : requireValue(args.operation, "--op");
+		const kind: OperationKind = action === "query" ? "query" : action === "global" ? "global" : "control";
+		const dispositionError = cliOperationError(kind, operation);
+		if (dispositionError) throw new SdkSessionCliError(dispositionError.code, dispositionError.message, 1);
+		if (isEndpointOperation(operation)) {
+			if (!args.showEndpointCredential)
+				throw new SdkSessionCliError(
+					"endpoint_credential_forbidden",
+					"session.get_endpoint requires --show-endpoint-credential.",
+					1,
+				);
+			if (process.stdout.isTTY && !args.yes && !(await confirmEndpointCredentialOutput()))
+				throw new SdkSessionCliError(
+					"endpoint_credential_confirmation_required",
+					"Endpoint credential output was not confirmed.",
+					1,
+				);
+		}
+		const input = await inputFromArgs(args);
+		if (kind === "control") {
+			const invalid = validateAdapterControl(operation, input);
+			if (invalid) throw new SdkSessionCliError(invalid.code, invalid.message, 2);
+		}
+		if (action === "global") {
+			const idempotencyKey = args.idempotencyKey;
+			if (isLifecycleOperation(operation) && !idempotencyKey)
+				throw new SdkSessionCliError("invalid_input", "--idempotency-key is required for lifecycle operations.", 2);
+			const client = await connectBroker(agentDir);
+			try {
+				writeOutput(await client.global(operation, input, { idempotencyKey }));
+			} finally {
+				await client.close();
+			}
+			return;
+		}
+		const sessionId = requireValue(args.sessionId, "<sessionId>");
+		const client = await connectSession(repo, sessionId);
+		try {
+			if (action === "control")
+				writeOutput(await client.control(operation, input, { confirm: args.confirm === true }));
+			else writeOutput(await client.query(operation, input, args.cursor));
+		} finally {
+			await client.close();
+		}
+	} catch (error) {
+		const cliError =
+			error instanceof SdkSessionCliError
+				? error
+				: error instanceof SdkClientError
+					? new SdkSessionCliError(error.code, error.message, 1)
+					: error instanceof SdkDiscoveryError
+						? new SdkSessionCliError(error.code, error.message, 1)
+						: new SdkSessionCliError(
+								"operation_failed",
+								error instanceof Error ? error.message : "SDK operation failed.",
+								1,
+							);
+		writeOutput({ ok: false, error: { code: cliError.code, message: cliError.message } });
+		setExitCode(cliError.exitCode);
+	}
+}

package/src/sdk/client/client.ts

@@ -0,0 +1 @@
+export * from "@sayknow-cli/bridge-client";