@gajae-code/coding-agent 0.15.5 → 0.16.0

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

@@ -2,24 +2,39 @@ import { randomBytes } from "node:crypto";
 import * as fsSync from "node:fs";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
+import { replaceTabs, truncateToWidth } from "@gajae-code/tui";
 import { getAgentDir } from "@gajae-code/utils";
 import { repo as resolveGitRepository } from "../../utils/git";
 import { ensureBroker } from "../broker/ensure";
+import { resolveSessionLocator } from "../broker/session-index";
+import {
+	resolveScopeRequest,
+	type ScopeNameV1,
+	type ScopeRequestV1,
+	type SdkSearchResultV1,
+	type SdkSearchRowV1,
+} from "../broker/session-scope";
 import { lifecycleRequestTimeoutMs } from "../broker/startup-budget";
-import { SdkClientError } from "../client";
+import { readSdkBrokerDiscovery, SdkClient, SdkClientError } from "../client";
 import { createBrokerSessionLifecycleService } from "../lifecycle/broker-client";
 import type {
 	SessionLifecycleMutationRequest,
 	SessionLifecycleOperation,
 	SessionLifecycleSavedSession,
 	SessionLifecycleSavedSessionIdentity,
+	SessionLifecycleService,
 	SessionReconcileUncertainTarget,
 } from "../lifecycle/service";
 import { PROMPT_CLIENT_REF_MAX_LENGTH } from "../prompt-status";
-import { validateAdapterControl, validateAdapterSecretFields } from "../protocol/adapter-validation";
+import {
+	validateAdapterControl,
+	validateAdapterSecretFields,
+	validateRequiredPromptText,
+} from "../protocol/adapter-validation";
 import { adapterDispositionError, findOperation, type OperationKind } from "../protocol/operation-registry";
 import { type SessionAttachment, SessionRouter, SessionRouterError, type SessionRouterFrame } from "../router";
 import { SessionListTraversalError, sessionListPageFromResponse, traverseSessionList } from "../session-list";
+import { SESSION_REQUEST_TIMEOUT_MS } from "../session-reconnect";
 import {
 	type SdkCheckpointRecordV1,
 	type SdkRetentionGapV1,
@@ -35,6 +50,7 @@ import {
 
 export type SdkSessionCliAction =
 	| "list"
+	| "search"
 	| "inspect"
 	| "send"
 	| "status"
@@ -60,7 +76,6 @@ export interface SdkSessionCliArgs {
 	jsonInputFile?: string;
 	jsonInputStdin?: boolean;
 	idempotencyKey?: string;
-	scope?: string;
 	confirm?: boolean;
 	cursor?: string;
 	wait?: boolean;
@@ -69,6 +84,10 @@ export interface SdkSessionCliArgs {
 	untilIdle?: boolean;
 	allEvents?: boolean;
 	repo?: string;
+	scope?: string;
+	limit?: number;
+	json?: boolean;
+
 	agentDir?: string;
 }
 
@@ -91,6 +110,9 @@ const TAIL_OFFLINE_MAX_SCAN_BYTES = 4 * 1024 * 1024;
 const TAIL_OFFLINE_MAX_SCANNED_LINES = 4_096;
 const TAIL_OFFLINE_MAX_LINE_BYTES = 256 * 1024;
 const transcriptDecoder = new TextDecoder("utf-8", { fatal: true });
+const SEARCH_PROBE_TIMEOUT_MS = 2_000;
+const SEARCH_PROBE_MAX_ROWS = 100;
+const SEARCH_TEXT_WIDTH = 80;
 
 const TERMINAL_TURN_KINDS = new Set(["turn_end", "agent_end"]);
 const START_TURN_KINDS = new Set(["turn_start", "agent_start"]);
@@ -210,6 +232,10 @@ function isEndpointOperation(operation: string): boolean {
 	return operation === "session.get_endpoint";
 }
 
+function isRawSpawnOperation(kind: OperationKind, operation: string): boolean {
+	return kind === "global" && operation === "session.spawn";
+}
+
 function isLifecycleOperation(operation: string): operation is LifecycleMutationOperation {
 	return (
 		operation === "session.create" ||
@@ -253,9 +279,11 @@ async function withRouter<T>(
 	agentDir: string,
 	action: (router: SessionRouter) => Promise<T>,
 	onFrame?: (attachment: SessionAttachment, frame: SessionRouterFrame) => void,
+	sessionIds?: readonly string[],
 ): Promise<T> {
 	const router = new SessionRouter({
 		agentDir,
+		...(sessionIds === undefined ? {} : { sessionIds }),
 		...(onFrame === undefined ? {} : { deps: { onFrame } }),
 	});
 	let result!: T;
@@ -363,6 +391,145 @@ async function sessionRows(agentDir: string): Promise<SessionRows> {
 	});
 }
 
+function searchScopeRequest(scope: ScopeNameV1, locator: { cwd: string; worktreeRoot: string | null }): ScopeRequestV1 {
+	return { version: 1, requested: scope, requestAnchor: { cwd: locator.cwd, worktreeRoot: locator.worktreeRoot } };
+}
+
+function searchProbe(row: SdkSearchRowV1, router: SessionRouter): Promise<SdkSearchRowV1> {
+	if (!row.live) return Promise.resolve({ ...row, probe: "stale" });
+	return (async () => {
+		try {
+			const attachment = router.attachment(row.id);
+			if (!attachment) return { ...row, probe: "unreachable" };
+			const response = await router.request(
+				row.id,
+				{ type: "query_request", query: "session.checkpoint", input: {} },
+				attachment.generation,
+				attachment,
+				{ timeoutMs: SEARCH_PROBE_TIMEOUT_MS },
+			);
+			return { ...row, probe: response.ok === true ? "reachable" : "unreachable" };
+		} catch {
+			return { ...row, probe: "unreachable" };
+		}
+	})();
+}
+
+export function mergeProbedSearchRows(
+	rows: readonly SdkSearchRowV1[],
+	probedRows: readonly SdkSearchRowV1[],
+): readonly SdkSearchRowV1[] {
+	return [...probedRows, ...rows.slice(probedRows.length)];
+}
+
+async function probeSearchRows(agentDir: string, result: SdkSearchResultV1): Promise<SdkSearchResultV1> {
+	if (result.status === "unavailable" || result.status === "not-in-git-worktree" || result.rows.length === 0)
+		return result;
+	const rows = result.rows.slice(0, SEARCH_PROBE_MAX_ROWS);
+	try {
+		const probes = await withRouter(
+			agentDir,
+			async router => await Promise.all(rows.map(row => searchProbe(row, router))),
+			undefined,
+			rows.map(row => row.id),
+		);
+		return { ...result, rows: mergeProbedSearchRows(result.rows, probes) };
+	} catch {
+		return {
+			...result,
+			rows: mergeProbedSearchRows(
+				result.rows,
+				rows.map(row => ({ ...row, probe: row.live ? "unreachable" : "stale" })),
+			),
+		};
+	}
+}
+
+/** Resolves, lists, and probes only the exact rows selected by the Broker-scoped search. */
+export async function runSdkSearch(
+	args: Pick<SdkSessionCliArgs, "agentDir" | "repo" | "scope" | "limit" | "cursor">,
+	createService: (agentDir: string) => SessionLifecycleService = createBrokerSessionLifecycleService,
+	probe: (agentDir: string, result: SdkSearchResultV1) => Promise<SdkSearchResultV1> = probeSearchRows,
+): Promise<{ result: SdkSearchResultV1; exitCode: 0 | 1 }> {
+	const agentDir = args.agentDir ?? getAgentDir();
+	const locator = await resolveSessionLocator(args.repo ?? process.cwd(), agentDir);
+	const scope: ScopeNameV1 =
+		args.scope === undefined || args.scope === "repo" || args.scope === "pwd" || args.scope === "global"
+			? ((args.scope ?? "repo") as ScopeNameV1)
+			: (() => {
+					throw new SdkSessionCliError(
+						"usage",
+						`Invalid search scope "${args.scope}". Expected repo, pwd, or global.`,
+						2,
+					);
+				})();
+	const request = searchScopeRequest(scope, locator);
+	const resolved = await resolveScopeRequest(request);
+	const outcome = await createService(agentDir).scopedList(request, args.limit, args.cursor);
+	if (outcome.ok) {
+		if ("rows" in outcome.result) {
+			if (outcome.result.status === "not-in-git-worktree") return { result: outcome.result, exitCode: 0 };
+			if (outcome.result.status === "unavailable") return { result: outcome.result, exitCode: 1 };
+			return { result: await probe(agentDir, outcome.result), exitCode: 0 };
+		}
+		return {
+			result: {
+				version: 1,
+				scope: resolved,
+				status: "unavailable",
+				observedAt: new Date().toISOString(),
+				rows: [],
+				warnings: [],
+				error: { code: "malformed_response", message: "broker search returned an unscoped result" },
+			},
+			exitCode: 1,
+		};
+	}
+	if (!outcome.ok && outcome.result?.status === "unavailable") return { result: outcome.result, exitCode: 1 };
+	return {
+		result: {
+			version: 1,
+			scope: resolved,
+			status: "unavailable",
+			observedAt: new Date().toISOString(),
+			rows: [],
+			warnings: [],
+			error: { code: outcome.error.code, message: outcome.error.message },
+		},
+		exitCode: 1,
+	};
+}
+
+function searchScopeLabel(result: SdkSearchResultV1): string {
+	const resolved = result.scope.resolved;
+	if (resolved === null) return "not-in-git-worktree";
+	if (resolved.kind === "repo") return resolved.worktreeRoot;
+	if (resolved.kind === "pwd") return resolved.cwd;
+	return resolved.visibility;
+}
+
+function safeSearchText(value: string): string {
+	return truncateToWidth(replaceTabs(value).replaceAll(/[\r\n]/g, " "), SEARCH_TEXT_WIDTH);
+}
+
+/** Renders a credential-free scope/status preamble and bounded search table. */
+export function renderSdkSearchTable(result: SdkSearchResultV1): string {
+	const lines = [
+		`Scope requested: ${result.scope.requested}`,
+		`Scope resolved: ${safeSearchText(searchScopeLabel(result))}`,
+		`Status: ${result.status}`,
+		`Observed at: ${result.observedAt}`,
+		...(result.cursor === undefined ? [] : [`Continuation cursor: ${safeSearchText(result.cursor)}`]),
+	];
+	if (result.rows.length === 0) return lines.join("\n");
+	lines.push("ID  PROBE        LIVE  CWD");
+	for (const row of result.rows)
+		lines.push(
+			`${safeSearchText(row.id).padEnd(20)}  ${(row.probe ?? "-").padEnd(11)}  ${String(row.live).padEnd(4)}  ${safeSearchText(row.locator.cwd)}`,
+		);
+	return lines.join("\n");
+}
+
 const SESSION_LIST_SCOPES: readonly SdkSessionListScope[] = ["repo", "cwd", "worktree", "all"];
 /** Row workspaces whose locator cannot be canonicalized still get one deterministic identity. */
 const WORKSPACE_IDENTITY_CACHE_LIMIT = 4096;
@@ -483,7 +650,7 @@ export async function filterSessionRowsByScope(
 	const warnings: string[] = [];
 	const sessions: SdkSessionRowV1[] = [];
 	for (const row of rows) {
-		const identity = await workspaceIdentity(row.locator.repo);
+		const identity = await workspaceIdentity(row.locator.cwd);
 		let keep: boolean;
 		if (scope === "cwd") keep = identity.canonicalPath === selection.selection.canonicalPath;
 		else if (scope === "worktree")
@@ -492,7 +659,7 @@ export async function filterSessionRowsByScope(
 		if (keep) sessions.push(row);
 		else if (identity.repoRoot === null && identity.commonDir === null)
 			warnings.push(
-				`Session ${row.sessionId} workspace "${row.locator.repo}" is outside Git; excluded by scope ${scope}.`,
+				`Session ${row.sessionId} workspace "${row.locator.cwd}" is outside Git; excluded by scope ${scope}.`,
 			);
 	}
 	return { sessions, warnings };
@@ -559,7 +726,7 @@ async function requestControl(
 	const attachment = attachmentFor(router, sessionId);
 	const response = await router.request(
 		sessionId,
-		{ type: "control_request", operation, input, confirm: args.confirm === true },
+		controlRequestFrame(operation, input, args),
 		attachment.generation,
 		attachment,
 		args.timeoutMs === undefined ? undefined : { timeoutMs: args.timeoutMs },
@@ -568,6 +735,81 @@ async function requestControl(
 	return response;
 }
 
+/** Builds the public CLI control envelope without leaking envelope fields into operation input. */
+export function controlRequestFrame(
+	operation: string,
+	input: JsonRecord,
+	args: Pick<SdkSessionCliArgs, "confirm" | "idempotencyKey">,
+): JsonRecord {
+	return {
+		type: "control_request",
+		operation,
+		input,
+		confirm: args.confirm === true,
+		...(args.idempotencyKey ? { idempotencyKey: args.idempotencyKey } : {}),
+	};
+}
+
+const BROKER_OPERATOR_ABORT_FIELDS = new Set(["mode", "scope", "operator"]);
+
+export function operatorAbortBrokerRequest(
+	sessionId: string,
+	operation: string,
+	input: JsonRecord,
+	args: Pick<SdkSessionCliArgs, "confirm" | "idempotencyKey">,
+): JsonRecord | undefined {
+	if (!Object.hasOwn(input, "operator")) return undefined;
+	if (operation !== "turn.abort")
+		throw new SdkSessionCliError("invalid_input", "operator is only available for terminal turn.abort.", 2);
+	if (input.operator !== true)
+		throw new SdkSessionCliError("invalid_input", "turn.abort operator must be true when provided.", 2);
+	if (input.mode !== "terminal")
+		throw new SdkSessionCliError("invalid_input", 'operator turn.abort requires mode:"terminal".', 2);
+	for (const key of Object.keys(input))
+		if (!BROKER_OPERATOR_ABORT_FIELDS.has(key))
+			throw new SdkSessionCliError(`invalid_input`, `Unknown turn.abort terminal field: ${key}`, 2);
+	if (input.scope !== undefined && input.scope !== "turn" && input.scope !== "owned")
+		throw new SdkSessionCliError("invalid_input", 'operator turn.abort scope must be "turn" or "owned".', 2);
+	if (args.confirm !== true)
+		throw new SdkSessionCliError("invalid_input", "operator terminal abort requires --confirm.", 2);
+	if (!args.idempotencyKey)
+		throw new SdkSessionCliError("invalid_input", "operator terminal abort requires --idempotency-key.", 2);
+	return { sessionId, operation: "turn.abort", input, confirm: true };
+}
+
+async function requestBrokerOperatorAbort(
+	agentDir: string,
+	request: JsonRecord,
+	args: SdkSessionCliArgs,
+): Promise<JsonRecord> {
+	const idempotencyKey = args.idempotencyKey;
+	if (!idempotencyKey)
+		throw new SdkSessionCliError("invalid_input", "operator terminal abort requires --idempotency-key.", 2);
+	const discovery = await readSdkBrokerDiscovery(agentDir);
+	if (!discovery) throw new SdkSessionCliError("session_unavailable", "SDK broker discovery is unavailable.", 1);
+	const timeoutMs = args.timeoutMs ?? SESSION_REQUEST_TIMEOUT_MS;
+	const client = await SdkClient.connect(discovery.url, discovery.token, {
+		timeoutMs,
+		reconnectAttempts: 0,
+	});
+	try {
+		const response = await client.global("session.control", request, {
+			idempotencyKey,
+			timeoutMs,
+		});
+		const result = object(response);
+		if (!result) throw new SdkClientError("protocol_error", "SDK broker returned a malformed control response.");
+		throwResponseFailure(result);
+		return result;
+	} finally {
+		await client.close().catch(error => {
+			process.stderr.write(
+				`SDK broker control cleanup failed: ${error instanceof Error ? error.message : String(error)}\n`,
+			);
+		});
+	}
+}
+
 async function requestQuery(
 	router: SessionRouter,
 	sessionId: string,
@@ -654,6 +896,8 @@ async function runSend(agentDir: string, sessionId: string, args: SdkSessionCliA
 	if (args.text !== undefined && Object.keys(input).length > 0)
 		throw new SdkSessionCliError("usage", "Use either --text or one JSON input source for the prompt, not both.", 2);
 	const promptInput: JsonRecord = args.text === undefined ? { ...input } : { text: args.text };
+	const promptError = validateRequiredPromptText("turn.prompt", promptInput);
+	if (promptError) throw new SdkSessionCliError(promptError.code, promptError.message, 2);
 	const inputRef = clientRefFromInput(promptInput);
 	const clientRef = inputRef ?? args.opRef?.trim() ?? createOperationRef();
 	if (args.opRef !== undefined && inputRef !== undefined && inputRef !== args.opRef.trim())
@@ -914,6 +1158,11 @@ function publicationSequence(publicationId: string): number | undefined {
 
 function tailItemFromRouterFrame(frame: SessionRouterFrame): SdkTailItemV1 | undefined {
 	if (frame.name === undefined) return undefined;
+	// The replay response is an out-of-band control frame, not an event-ring
+	// item. Its generation/lastSeq metadata is a response position, and it
+	// intentionally has no event `seq`; projecting it as a tail item would make
+	// the strict event-position validator reject every otherwise valid tail.
+	if (frame.name === "event_replay_result") return undefined;
 	const seq = frame.publicationId === undefined ? undefined : publicationSequence(frame.publicationId);
 	return toTailItemV1(
 		{
@@ -1110,6 +1359,12 @@ async function offlineTailReplay(
 	});
 	if (!outcome.ok)
 		throw new SdkSessionCliError(outcome.error.code, outcome.error.message, 1, { certainty: outcome.certainty });
+	if ("rows" in outcome.result)
+		throw new SdkSessionCliError(
+			"malformed_response",
+			"broker returned a scoped result for retained transcript replay",
+			1,
+		);
 	const savedSession = outcome.result.savedSession;
 	if (!savedSession)
 		throw new SdkSessionCliError(
@@ -1402,6 +1657,8 @@ async function runRawControl(
 	const invalid = validateAdapterControl(operation, input);
 	if (invalid) throw new SdkSessionCliError(invalid.code, invalid.message, 2);
 	await ensureBroker({ agentDir });
+	const operatorRequest = operatorAbortBrokerRequest(sessionId, operation, input, args);
+	if (operatorRequest) return await requestBrokerOperatorAbort(agentDir, operatorRequest, args);
 	return await withRouter(agentDir, async router => await requestControl(router, sessionId, operation, input, args));
 }
 
@@ -1495,6 +1752,7 @@ export async function runSdkSessionCli(
 		const action = args.action;
 		if (
 			action !== "list" &&
+			action !== "search" &&
 			action !== "inspect" &&
 			action !== "send" &&
 			action !== "status" &&
@@ -1515,6 +1773,12 @@ export async function runSdkSessionCli(
 			writeOutput(stripSecretFields(await runList(agentDir, args)));
 			return;
 		}
+		if (action === "search") {
+			const search = await runSdkSearch(args);
+			writeOutput(args.json === true ? search.result : renderSdkSearchTable(search.result));
+			if (search.exitCode !== 0) setExitCode(search.exitCode);
+			return;
+		}
 		if (action === "inspect") {
 			writeOutput(stripSecretFields(await runInspect(agentDir, requireValue(args.sessionId, "<sessionId>"))));
 			return;
@@ -1566,6 +1830,12 @@ export async function runSdkSessionCli(
 		const kind = rawKind(requireValue(action, "<verb>"), args);
 		if (!kind) throw new SdkSessionCliError("usage", "raw requires one of: control, query, global.", 2);
 		const operation = kind === "query" ? requireValue(args.query, "--query") : requireValue(args.operation, "--op");
+		if (isRawSpawnOperation(kind, operation))
+			throw new SdkSessionCliError(
+				"adapter_operation_prohibited",
+				"session.spawn is unavailable through the SDK session CLI.",
+				1,
+			);
 		const dispositionError = cliOperationError(kind, operation);
 		if (dispositionError) throw new SdkSessionCliError(dispositionError.code, dispositionError.message, 1);
 		if (isEndpointOperation(operation))

package/src/sdk/client/client.ts

@@ -116,13 +116,13 @@ export interface SdkDispatchContext {
 	readonly generation: number;
 }
 
-/** Request identity retained after an uncertain send for lifecycle reconciliation. */
-
+/** Request identity retained after an uncertain send. */
 export interface SdkSentRecord {
 	readonly id: string;
 	readonly operation?: string;
 	readonly idempotencyKey?: string;
-	readonly fingerprint: string;
+	/** Present for lifecycle lookups; `session.spawn` replays through its idempotency key. */
+	readonly fingerprint?: string;
 }
 
 export type SdkFrameHandler = (frame: SdkFrame) => void;
@@ -473,8 +473,10 @@ export class SdkClient {
 		const sentOperation = typeof serializedFrame.operation === "string" ? serializedFrame.operation : undefined;
 		const sentIdempotencyKey =
 			typeof serializedFrame.idempotencyKey === "string" ? serializedFrame.idempotencyKey : undefined;
-		const sentFingerprint =
-			typeof serializedFrame.operation === "string"
+		const isSpawn = sentOperation === "session.spawn";
+		const sentFingerprint = isSpawn
+			? undefined
+			: typeof serializedFrame.operation === "string"
 				? lifecycleFingerprint(serializedFrame.operation, serializedFrame.input ?? {})
 				: inputFingerprint(serializedFrame.input ?? {});
 		const deferred = Promise.withResolvers<unknown>();
@@ -571,11 +573,15 @@ export class SdkClient {
 		// nothing reached the transport, so the request stays retryable and
 		// non-uncertain with no record retained.
 		pending.sent = true;
+		// A spawn claim replays only through its caller-provided idempotency key;
+		// it deliberately has no lifecycle fingerprint. Retain the common sent
+		// record anyway so an uncertain transport result tells the caller which
+		// key can join that durable claim.
 		this.#rememberSentRecord({
 			id,
-			operation: sentOperation,
-			idempotencyKey: sentIdempotencyKey,
-			fingerprint: sentFingerprint,
+			...(sentOperation === undefined ? {} : { operation: sentOperation }),
+			...(sentIdempotencyKey === undefined ? {} : { idempotencyKey: sentIdempotencyKey }),
+			...(sentFingerprint === undefined ? {} : { fingerprint: sentFingerprint }),
 		});
 		try {
 			incarnation.socket.send(serializedRequest);

package/src/sdk/client/discovery.ts

@@ -35,7 +35,7 @@ export class SdkDiscoveryError extends Error {
 
 export type SdkSessionEndpointScope = "default" | "chat";
 
-function endpointDirectory(repo: string, scope: SdkSessionEndpointScope = "default"): string {
+export function endpointDirectory(repo: string, scope: SdkSessionEndpointScope = "default"): string {
 	return scope === "chat" ? path.join(repo, ".gjc", "state", "chat", "sdk") : path.join(repo, ".gjc", "state", "sdk");
 }
 function isUsableSessionId(sessionId: string): boolean {
@@ -132,6 +132,8 @@ export async function readSdkSessionEndpoint(
 	if (!isUsableSessionId(sessionId)) return null;
 	const file = path.join(endpointDirectory(repo, scope), `${sessionId}.json`);
 	try {
+		const stat = await fs.lstat(file);
+		if (!stat.isFile()) return null;
 		return parseEndpoint(sessionId, file, JSON.parse(await fs.readFile(file, "utf8")));
 	} catch (error) {
 		if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;