@gajae-code/coding-agent 0.17.1 → 0.17.4

package/src/sdk/client/client.ts

@@ -67,6 +67,8 @@ export interface SdkClientOptions {
 	timeoutMs?: number;
 	/** Absolute wall-clock deadline shared by connect, hello, retry, and request work. */
 	deadline?: number;
+	/** Optional client capabilities sent in the protocol hello handshake. */
+	capabilities?: readonly string[];
 
 	reconnectAttempts?: number;
 	reconnectBackoffMs?: number;
@@ -288,6 +290,7 @@ export class SdkClient {
 	 */
 	readonly #closeGraceMs: number;
 	readonly #deadline?: number;
+	readonly #capabilities?: readonly string[];
 	#currentSocketRecord: Incarnation | null = null;
 	#opening: Cycle | null = null;
 	#cycleGeneration = 0;
@@ -309,6 +312,7 @@ export class SdkClient {
 		this.#closeGraceMs = Math.max(1, Math.min(this.#timeoutMs, 1_000));
 		this.#deadline =
 			typeof options.deadline === "number" && Number.isFinite(options.deadline) ? options.deadline : undefined;
+		this.#capabilities = options.capabilities;
 
 		this.#reconnectAttempts = options.reconnectAttempts ?? 3;
 		this.#reconnectBackoffMs = options.reconnectBackoffMs ?? 25;
@@ -831,6 +835,20 @@ export class SdkClient {
 					incarnation.resolveOpen = undefined;
 					incarnation.rejectOpen = undefined;
 					this.#beginHello(incarnation);
+					if (this.#capabilities !== undefined) {
+						try {
+							socket.send(
+								JSON.stringify({
+									type: "hello",
+									protocolVersion: 3,
+									capabilities: [...this.#capabilities],
+								}),
+							);
+						} catch (error) {
+							this.#onSocketFailure(incarnation, error as Event);
+							return;
+						}
+					}
 					const earlyHello = incarnation.earlyHello;
 					if (earlyHello) {
 						incarnation.earlyHello = undefined;

package/src/sdk/guides/catalog.ts

@@ -241,13 +241,13 @@ export async function fetchGuideManifestOnline(params: {
  */
 const BUNDLED_GUIDE_MANIFEST_ID = "gajae-code-advisory-bundled";
 const BUNDLED_GUIDE_SIGNATURE_HEX =
-	"682028a6834dfd2b39db57fb6cc185b9e2bdf21a3256d907fbbb8ddb20a0ce285f3a21b970df7d4055acfb2aede13d8f69931249c6d27fc092bfa2b60e936303";
+	"62715b7716b30d3ea7b6ef41dfd7848c82dffed972a8729e4a5b8e3a9ee05d8cbcefeabc27b8796b1754622672a8fd2698a7ab638ca205c202f7479c34763c00";
 
 const bundledGuideAdvisoryTexts: Readonly<Record<string, string>> = {
 	"getting-started":
 		"GJC ships a small set of signed advisory guides with the client so `gjc sdk guides list` and `gjc sdk guides show <guideId>` work offline on a fresh install. Guides are advisory text only: they are rendered for reading and never executed or applied as configuration. To receive newer guides, run `gjc sdk guides refresh --url <https manifest url>`. The manifest must come from the allowlisted HTTPS host and must be signed by a pinned Ed25519 key; a rejected refresh falls back to the last verified cache, then to the bundled seed, and any rejection is reported in the warnings list.",
 	"sdk/session-cli":
-		"`gjc sdk session` is the broker-bound command family for operating live GJC SDK sessions from the terminal: `list` enumerates managed sessions, `inspect` shows session details, `send` submits a prompt turn, `status` reports session health, and `tail` follows the event stream. The explicit `raw` hatch dispatches one SDK operation as `control`, `query`, or `global`. Authority resolves through the local broker and endpoint credentials are never rendered by the CLI.",
+		"`gjc sdk session` is the broker-bound command family for operating live GJC SDK sessions from the terminal: `list` enumerates managed sessions, `inspect` shows session details, `send` submits a prompt turn, `status` reports session health, `tail` follows the event stream, and `close` ends the current live host generation. The explicit `raw` hatch dispatches one SDK operation as `control`, `query`, or `global`. Authority resolves through the local broker and endpoint credentials are never rendered by the CLI.",
 	"troubleshooting/sdk-connection":
 		"When an SDK connection fails, first check that the session host is alive and healthy: `gjc sdk session status` reports readiness and liveness. If the broker is gone, restart it and re-list sessions; detached hosts are reaped after a bounded absence grace. Fetch-boundary failures (offline host, allowlisted URL violations, signature rejections) are reported as typed errors with exit code 1 so scripts can fail closed instead of silently serving unverified content.",
 };

package/src/sdk/guides/cli.ts

@@ -1,4 +1,5 @@
 import { getAgentDir } from "@gajae-code/utils";
+import { normalizePublicCommandFailure, PublicCommandFailure } from "../../cli/public-command-errors";
 import { readGuideCache } from "./cache";
 import { BUNDLED_GUIDE_MANIFESTS, GuideCatalog, guideFetchPolicy, isGuideFetchUrlAllowed } from "./catalog";
 import { GUIDE_CLIENT_VERSION, GUIDE_PINNED_KEYS } from "./verify";
@@ -39,50 +40,20 @@ export interface SdkGuidesCliArgs {
 
 const GUIDE_CLI_ACTIONS: readonly string[] = ["refresh", "list", "show", "status", "trust"];
 
-class SdkGuidesCliError 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 usageFailure(message: string): SdkGuidesCliError {
-	return new SdkGuidesCliError("usage", message, 2);
+function usageFailure(): PublicCommandFailure {
+	return new PublicCommandFailure({ kind: "usage", proof: "pre-effect" });
 }
 
-function operationalFailure(code: string, message: string): SdkGuidesCliError {
-	return new SdkGuidesCliError(code, message, 1);
+function operationalFailure(): PublicCommandFailure {
+	return new PublicCommandFailure({ kind: "operation_failed", proof: "unknown" });
 }
 
-/**
- * Usage-shaped errors (bad verb, missing argument, URL outside the allowlist)
- * exit 2; every verification/operational failure exits 1. Fail-closed codes
- * from the verification pipeline map to exit 1 so scripts observe a hard
- * failure on tamper, unknown key, rollback, expiry, or corrupt cache.
- */
-function toCliError(error: unknown): SdkGuidesCliError {
-	if (error instanceof SdkGuidesCliError) return error;
-	const code = error instanceof Error && "code" in error ? String((error as { code: unknown }).code) : undefined;
-	const message = error instanceof Error ? error.message : String(error);
-	switch (code) {
-		case "usage":
-		case "invalid_input":
-		case "fetch_forbidden":
-			return new SdkGuidesCliError(code ?? "operation_failed", message, 2);
-		default:
-			return operationalFailure(code ?? "operation_failed", message);
-	}
+function writeJson(value: unknown): void {
+	process.stdout.write(`${JSON.stringify(value)}\n`);
 }
 
-function requireValue(value: string | undefined, flag: string): string {
-	if (value === undefined || value.length === 0) throw usageFailure(`${flag} is required.`);
+function requireValue(value: string | undefined): string {
+	if (value === undefined || value.length === 0) throw usageFailure();
 	return value;
 }
 
@@ -105,8 +76,8 @@ function manifestSummary(manifest: {
 }
 
 async function runRefresh(agentDir: string, args: SdkGuidesCliArgs): Promise<unknown> {
-	const url = requireValue(args.url, "--url");
-	if (!isGuideFetchUrlAllowed(url)) throw usageFailure(`--url ${url} is outside the HTTPS allowlist.`);
+	const url = requireValue(args.url);
+	if (!isGuideFetchUrlAllowed(url)) throw usageFailure();
 	const catalog = new GuideCatalog({
 		agentDir,
 		onlineUrl: url,
@@ -114,15 +85,9 @@ async function runRefresh(agentDir: string, args: SdkGuidesCliArgs): Promise<unk
 		fetchImpl: args.fetchImpl,
 	});
 	const result = await catalog.refresh();
-	if (!result.ok) throw operationalFailure(result.error.code, result.error.message);
+	if (!result.ok) throw operationalFailure();
 	const selection = result.value;
-	if (selection.source !== "online") {
-		const reasons = selection.warnings.length > 0 ? ` ${selection.warnings.join("; ")}` : "";
-		throw operationalFailure(
-			"online_refresh_failed",
-			`Online refresh did not select an online source (selected ${selection.source} instead)${reasons}.`,
-		);
-	}
+	if (selection.source !== "online") throw operationalFailure();
 	return {
 		source: selection.source,
 		manifest: manifestSummary(selection.manifest),
@@ -134,7 +99,7 @@ async function runRefresh(agentDir: string, args: SdkGuidesCliArgs): Promise<unk
 async function runList(agentDir: string): Promise<unknown> {
 	const catalog = new GuideCatalog({ agentDir });
 	const result = await catalog.load();
-	if (!result.ok) throw operationalFailure(result.error.code, result.error.message);
+	if (!result.ok) throw operationalFailure();
 	const selection = result.value;
 	return {
 		source: selection.source,
@@ -145,10 +110,10 @@ async function runList(agentDir: string): Promise<unknown> {
 }
 
 async function runShow(agentDir: string, args: SdkGuidesCliArgs): Promise<unknown> {
-	const guideId = requireValue(args.guideId, "<guideId>");
+	const guideId = requireValue(args.guideId);
 	const catalog = new GuideCatalog({ agentDir });
 	const result = await catalog.advisory(guideId);
-	if (!result.ok) throw operationalFailure(result.error.code, result.error.message);
+	if (!result.ok) throw operationalFailure();
 	return {
 		source: result.value.source,
 		guideId: result.value.guideId,
@@ -194,21 +159,16 @@ function runTrust(): unknown {
 
 /**
  * Runs the `gjc sdk guides` command family. Exported for command routing from
- * `src/commands/sdk.ts` and for direct service use; the injected `write` /
- * `setExitCode` hooks keep the surface testable without touching stdout or
- * the process exit code.
+ * `src/commands/sdk.ts` and for direct service use. Only successful results are
+ * written here; typed failures belong to the outer public family writer.
  */
 export async function runSdkGuidesCli(
 	args: SdkGuidesCliArgs,
 	writeOutput: (value: unknown) => void = writeJson,
-	setExitCode: (exitCode: 1 | 2) => void = exitCode => {
-		process.exitCode = exitCode;
-	},
 ): Promise<void> {
 	try {
 		const action = args.action;
-		if (action === undefined || !GUIDE_CLI_ACTIONS.includes(action))
-			throw usageFailure(`Expected one of: ${GUIDE_CLI_ACTIONS.join(", ")}.`);
+		if (action === undefined || !GUIDE_CLI_ACTIONS.includes(action)) throw usageFailure();
 		const agentDir = args.agentDir ?? getAgentDir();
 		switch (action) {
 			case "refresh":
@@ -228,8 +188,6 @@ export async function runSdkGuidesCli(
 				return;
 		}
 	} catch (error) {
-		const cliError = toCliError(error);
-		writeOutput({ ok: false, error: { code: cliError.code, message: cliError.message } });
-		setExitCode(cliError.exitCode);
+		throw normalizePublicCommandFailure(error);
 	}
 }

package/src/sdk/guides/verify.ts

@@ -21,6 +21,8 @@ export interface GuidePinnedKey {
 	/** DER-encoded SPKI public key, hex. */
 	spkiDerHex: string;
 	source: "bundled";
+	/** Optional retirement bound for old bundled signers. */
+	validUntil?: number;
 }
 
 /**
@@ -30,10 +32,20 @@ export interface GuidePinnedKey {
  * Private key material is never shipped; manifests are signed out-of-band.
  */
 const guidePinnedKeys: GuidePinnedKey[] = [
+	// Bundled advisory seed signer for the current offline catalog. The previous
+	// key remains trusted below until the current seed's 2036 expiry so already-
+	// cached manifests do not lose authority during a bundled-guide refresh.
+	{
+		keyId: "71efa9f212e39350e34f88aed5ab7242854e7e20ea91455e8861c973a6fc2eaf",
+		spkiDerHex: "302a300506032b657003210062c441fc5953cdc67d0c46f09b814dcb30de1465dcafb385092dbdcf9844cfeb",
+		source: "bundled",
+		validUntil: Date.UTC(2036, 0, 1),
+	},
 	{
 		keyId: "6c4b134ff9fb86a52d55cb6bb7c2fab938405b53b4148afc4249a2cb6f504bce",
 		spkiDerHex: "302a300506032b6570032100ef665d05c6795341dfc893866d8fe5be4b48891c0ed0d125940d7032de37723e",
 		source: "bundled",
+		validUntil: Date.UTC(2036, 0, 1),
 	},
 ];
 export const GUIDE_PINNED_KEYS: readonly GuidePinnedKey[] = Object.freeze(
@@ -125,6 +137,8 @@ export function verifyGuideManifest(params: {
 	}
 	if (!valid)
 		return guideFailure("invalid_signature", "Detached signature does not match the canonical manifest bytes.");
+	if (pinned.validUntil !== undefined && now > pinned.validUntil)
+		return guideFailure("expired", `Guide signer ${pinned.keyId} expired before this manifest was read.`);
 	if (!Number.isSafeInteger(now) || now < manifest.issuedAt)
 		return guideFailure("not_yet_valid", "Guide manifest is not authoritative until its issuedAt instant.");
 	if (now > manifest.expiresAt)

package/src/sdk/host/host.ts

@@ -103,9 +103,18 @@ export interface SessionSdkHostOptions extends HostEndpointAdapters {
  *  must see the same capability-gated event kinds on both legs, or live and
  *  replay delivery diverge for the same subscriber. */
 export const TOOL_ACTIVITY_CAPABILITY = "tool_activity_v2";
+/** Capability for non-replayable streamed turn content. */
+export const TURN_STREAM_CAPABILITY = "turn_stream";
+/** Capability used by notification adapters that observe a host without owning its work. */
+export const SESSION_HOST_OBSERVER_CAPABILITY = "session_host_observer_v1";
 export const CAP_GATED_FRAME_KINDS: ReadonlySet<string> = new Set(["tool_activity", "reasoning_summary"]);
 const EMPTY_CAPABILITIES: ReadonlySet<string> = new Set();
 
+/** Keep live delivery and replay on one capability gate. */
+export function canDeliverSdkEvent(kind: string, capabilities: ReadonlySet<string> | undefined): boolean {
+	return !CAP_GATED_FRAME_KINDS.has(kind) || capabilities?.has(TOOL_ACTIVITY_CAPABILITY) === true;
+}
+
 /** Safe, identifier-free explanations for every refused activation status. */
 const ACTIVATION_MESSAGES: Record<
 	Exclude<SessionActivationOutcome, "activated" | "already"> | "session_mismatch",
@@ -210,6 +219,9 @@ export class SessionSdkHost {
 	#stopPromise?: Promise<"stopped">;
 	#unsubscribe?: () => void;
 	#registration?: { writer: BrokerIndexWriter; generation: number };
+	#reportedActivityState?: "active" | "idle";
+	/** Serializes durable activity transitions so a later state cannot be lost. */
+	#activityReportTail: Promise<void> = Promise.resolve();
 	/** The generation whose readiness signal has already been published. */
 	#readyGeneration?: number;
 	/** Serializes activation attempts so a concurrent pair cannot both publish. */
@@ -276,6 +288,7 @@ export class SessionSdkHost {
 
 	async start(): Promise<"started" | "already"> {
 		if (this.#started) return "already";
+		this.#reportedActivityState = undefined;
 		this.events.restart();
 		if (isAutoroutingInactive(this)) this.emitAutoroutingInactiveNotice();
 		if (this.#options.readiness !== "deferred") this.#publishReadiness();
@@ -298,6 +311,9 @@ export class SessionSdkHost {
 					stateRoot: this.#options.stateRoot,
 					endpointGeneration: this.events.generation,
 				});
+			void this.reportActivity("idle").catch(error =>
+				logger.warn(`sdk: initial idle activity checkpoint failed: ${String(error)}`),
+			);
 			return "started";
 		} catch (error) {
 			this.#unsubscribe?.();
@@ -364,7 +380,9 @@ export class SessionSdkHost {
 		return "activated";
 	}
 
-	async stop(options: { allowLockContention?: boolean } = {}): Promise<"stopped" | "already"> {
+	async stop(
+		options: { allowLockContention?: boolean; unregisterReason?: "detached_idle" } = {},
+	): Promise<"stopped" | "already"> {
 		if (this.#stopPromise) return this.#stopPromise;
 		if (!this.#started) return "already";
 		const stopPromise = this.#stopStartedHost(options);
@@ -376,7 +394,10 @@ export class SessionSdkHost {
 		}
 	}
 
-	async #stopStartedHost(options: { allowLockContention?: boolean }): Promise<"stopped"> {
+	async #stopStartedHost(options: {
+		allowLockContention?: boolean;
+		unregisterReason?: "detached_idle";
+	}): Promise<"stopped"> {
 		// Fence before the first await: everything after this point is teardown,
 		// and no in-flight activation may publish readiness across it.
 		this.#stopping = true;
@@ -388,6 +409,7 @@ export class SessionSdkHost {
 					sessionId: this.#options.sessionId,
 					stateRoot: this.#options.stateRoot,
 					endpointGeneration: this.events.generation,
+					...(options.unregisterReason === undefined ? {} : { reason: options.unregisterReason }),
 				});
 			} catch (error) {
 				// A live broker may hold the shared session-index lock beyond the
@@ -415,6 +437,30 @@ export class SessionSdkHost {
 				stateRoot: this.#options.stateRoot,
 				endpointGeneration: this.events.generation,
 			});
+		if (this.#started)
+			void this.reportActivity("idle").catch(error =>
+				logger.warn(`sdk: initial idle activity checkpoint failed: ${String(error)}`),
+			);
+	}
+
+	/** Persist the host's observable activity for broker/session-list consumers. */
+	async reportActivity(state: "active" | "idle", at = Date.now()): Promise<void> {
+		const registration = this.#registration;
+		if (!this.#started || this.#stopping || !registration?.writer.heartbeat) return;
+		if (!Number.isFinite(at)) at = Date.now();
+		const write = async (): Promise<void> => {
+			if (this.#reportedActivityState === state) return;
+			await registration.writer.heartbeat!({
+				sessionId: this.#options.sessionId,
+				stateRoot: this.#options.stateRoot,
+				endpointGeneration: this.events.generation,
+				activity: { state, at },
+			});
+			this.#reportedActivityState = state;
+		};
+		const report = this.#activityReportTail.then(write, write);
+		this.#activityReportTail = report.catch(() => undefined);
+		await report;
 	}
 
 	async #send(connectionId: string, frame: SdkFrame): Promise<"written" | "dropped"> {
@@ -563,9 +609,7 @@ export class SessionSdkHost {
 					const sinceSeq = rawSeq;
 					const replay = this.events.replay(sinceSeq, sinceGeneration);
 					const capabilities = this.#options.connectionCapabilities?.(connectionId) ?? EMPTY_CAPABILITIES;
-					const events = replay.events.filter(
-						event => !CAP_GATED_FRAME_KINDS.has(String(event.kind)) || capabilities.has(TOOL_ACTIVITY_CAPABILITY),
-					);
+					const events = replay.events.filter(event => canDeliverSdkEvent(String(event.kind), capabilities));
 					await this.#send(connectionId, {
 						type: "event_replay_result",
 						id,