@gajae-code/coding-agent 0.12.21 → 0.13.0

package/src/commands/sdk.ts

@@ -24,6 +24,8 @@ import {
 	writeSessionLifecycleReady,
 } from "../sdk/broker/lifecycle";
 import { processIncarnation } from "../sdk/broker/process-incarnation";
+import { runSdkSessionCli } from "../sdk/cli";
+import { runSdkGuidesCli } from "../sdk/guides/cli";
 import { type CreateLifecycleAgentSessionResult, createLifecycleAgentSession } from "../sdk/lifecycle-session";
 import { listManagedSessionCandidates, resolveManagedSessionScope } from "../sdk/session-directory";
 import {
@@ -141,25 +143,31 @@ export const SESSION_HOST_FIRST_ATTACH_GRACE_MS = 60 * 60_000;
 const SESSION_HOST_ATTACHMENT_POLL_MS = 30_000;
 
 /**
- * Resolves once this host is provably abandoned: either it has been detached
- * from every client for the full idle grace, or nobody has come for it at all
- * for the full first-attach grace.
+ * Resolves once the host is provably abandoned: either it has been detached
+ * from every client for a full idle grace, or nobody has come for it at all
+ * for a full first-attach grace.
  *
  * `readAttachedClients` reports the host's own live client/socket subscription
- * count; `undefined` means the SDK endpoint publishes no such evidence yet and
- * is deliberately *not* treated as detachment, so a host can never be reaped on
- * missing evidence — only on observed absence of clients.
+ * count; `undefined` means the SDK endpoint publishes no such evidence — before
+ * startup, after teardown, or when every reader itself fails. That ambiguity is
+ * never instant detachment: it cannot reap on the poll that first sees it, it
+ * can only open a window. Which window depends on what was already observed. A
+ * host never seen attached accrues against the first-attach bound. A host that
+ * was seen attached and has since lost its evidence is in the *more* suspicious
+ * state — a runtime that retracted its registration during teardown looks
+ * exactly like this — so it accrues against the detached idle bound, alongside
+ * an observed count of zero. Every reachable state therefore carries a finite
+ * bound.
  *
  * `readWorkInFlight` reports whether the host is running agent work right now.
- * Work is positive proof that a client did come for this host: a prompt can
- * only arrive over the endpoint a client dialed. So for a host that has never
- * been *observed* attached — a client that connected, prompted and dropped
- * between two 30s polls, or a client count that is momentarily unreadable — the
- * first-attach window is measured from the last moment work was in flight
- * rather than from process start. That still bounds a host whose SDK runtime
- * never came up: with no transport it can never receive a prompt, so it never
- * reports work and its window keeps running from start. And any real turn ends,
- * after which the window resumes; live work defers the bound, never removes it.
+ * Work is positive proof a client did come for this host: a prompt can only
+ * arrive over an endpoint a client dialed. Live work therefore restarts both
+ * windows, which is what keeps a mid-prompt host alive whether its count reads
+ * zero or stops being readable at all. That still bounds a host whose SDK
+ * runtime never came up: with no transport it can never receive a prompt, so it
+ * never reports work and its window keeps running from process start. And any
+ * real turn ends, after which the window resumes; live work defers a bound, it
+ * never removes it.
  */
 export async function watchSessionHostClientAttachment(deps: {
 	readAttachedClients: () => number | undefined;
@@ -182,16 +190,18 @@ export async function watchSessionHostClientAttachment(deps: {
 	let unattendedSince = now();
 	for (;;) {
 		const attached = deps.readAttachedClients();
-		if (readWorkInFlight()) unattendedSince = now();
-		if (attached === undefined) {
-			// No endpoint evidence at all is ambiguity, not abandonment; it still
-			// accrues against the first-attach bound so a host whose SDK runtime
-			// never came up cannot outlive that bound either.
-			if (!everAttached && now() - unattendedSince >= firstAttachGraceMs) return;
-		} else if (attached > 0) {
+		if (readWorkInFlight()) {
+			unattendedSince = now();
+			detachedSince = null;
+		}
+		if (attached !== undefined && attached > 0) {
 			everAttached = true;
 			detachedSince = null;
 		} else if (everAttached) {
+			// An observed zero and no readable evidence at all are the same
+			// absence once a client has been seen: a runtime that retracted its
+			// registration stops publishing a count instead of reporting zero.
+			// Both accrue against the idle bound rather than running forever.
 			detachedSince ??= now();
 			if (now() - detachedSince >= idleGraceMs) return;
 		} else if (now() - unattendedSince >= firstAttachGraceMs) {
@@ -697,6 +707,18 @@ export function parseSdkInternalArgv(argv: readonly string[]): SdkInternalArgv {
 	throw new CliParseError("Invalid internal SDK invocation.");
 }
 
+function parsePositiveTimeout(raw: string | undefined, flagName: string): number | undefined {
+	if (raw === undefined) return undefined;
+	if (!/^[0-9]+$/.test(raw)) {
+		throw new CliParseError(`Expected ${flagName} to be a positive safe integer, got "${raw}"`);
+	}
+	const value = Number(raw);
+	if (!Number.isSafeInteger(value) || value <= 0) {
+		throw new CliParseError(`Expected ${flagName} to be a positive safe integer, got "${raw}"`);
+	}
+	return value;
+}
+
 class SdkServeHelp extends Command {
 	static description = "gjc sdk serve --stdio | --socket <path> [--session <id>] [--pending-ceiling <bytes>]";
 	static flags = {
@@ -708,16 +730,168 @@ class SdkServeHelp extends Command {
 	async run(): Promise<void> {}
 }
 
+class SdkSessionHelp extends Command {
+	static description =
+		"Manage SDK sessions: `gjc sdk session list|inspect|send|status|tail|elevate`, or the explicit raw hatch `gjc sdk session raw control|query|global`. The session CLI is broker-bound, credential-free by default, and elevation approval requires an attended operator.";
+	static args = {
+		verb: Args.string({
+			description: "Session verb",
+			required: false,
+			options: ["list", "inspect", "send", "status", "tail", "elevate", "raw"],
+		}),
+		target: Args.string({
+			description: "Session id (or the raw kind control|query|global for `raw`)",
+			required: false,
+		}),
+		opRef: Args.string({ description: "Operation reference to report on (status only)", required: false }),
+	};
+	static flags = {
+		"agent-dir": Flags.string({ description: "SDK broker state directory" }),
+		json: Flags.boolean({ description: "Emit JSON output (default for SDK session commands)" }),
+		repo: Flags.string({
+			description: "Workspace directory for saved-session resolution (default: current directory)",
+		}),
+		op: Flags.string({ description: "Raw control or global operation" }),
+		query: Flags.string({ description: "Raw query name" }),
+		kind: Flags.string({ description: "Elevation operation kind (control|global)", options: ["control", "global"] }),
+		"json-input": Flags.string({ description: "SDK request JSON object" }),
+		"json-input-file": Flags.string({ description: "Read SDK request JSON from a 0600 file" }),
+		"json-input-stdin": Flags.boolean({ description: "Read SDK request JSON from standard input" }),
+		"idempotency-key": Flags.string({ description: "Caller idempotency key required for SDK lifecycle globals" }),
+		"elevation-request-id": Flags.string({ description: "Approved elevation grant id for allowlisted raw controls" }),
+		confirm: Flags.boolean({ description: "Confirm a destructive SDK control operation" }),
+		cursor: Flags.string({
+			description:
+				"Raw query continuation cursor, or a saved checkpoint token to resume tail from (re-minted per connection)",
+		}),
+		"show-endpoint-credential": Flags.boolean({ description: "Allow session.get_endpoint secret output" }),
+		yes: Flags.boolean({ description: "Confirm endpoint credential output on a TTY" }),
+		text: Flags.string({ description: "Prompt text for send (alternative to --json-input)" }),
+		"op-ref": Flags.string({ description: "Operation reference for send (defaults to a generated ULID)" }),
+		wait: Flags.boolean({
+			description: "send --wait: poll turn.prompt_status until terminal or the wait window elapses (never cancels)",
+		}),
+		"timeout-ms": Flags.string({ description: "Wait window for send --wait, status, and live tail follow" }),
+		strict: Flags.boolean({ description: "tail --strict: fail closed (exit 1 retention_gap) on retention gaps" }),
+		"until-idle": Flags.boolean({
+			description: "tail --until-idle: exit once the observed event stream reaches a terminal turn state",
+		}),
+		"all-events": Flags.boolean({ description: "tail --all-events: include every event-ring kind" }),
+	};
+	async run(): Promise<void> {}
+}
+
+class SdkSessionCommand extends Command {
+	static description = SdkSessionHelp.description;
+	static args = SdkSessionHelp.args;
+	static flags = SdkSessionHelp.flags;
+	async run(): Promise<void> {
+		const { args, flags } = await this.parse(SdkSessionCommand);
+		const verb = args.verb;
+		const target = args.target;
+		const flagRec = flags as Record<string, unknown>;
+		const timeoutMs = parsePositiveTimeout(flagRec["timeout-ms"] as string | undefined, "--timeout-ms");
+		await runSdkSessionCli({
+			action: verb,
+			...(verb === "raw"
+				? {
+						rawAction: target,
+						sessionId: target === "control" || target === "query" ? args.opRef : undefined,
+					}
+				: { sessionId: verb === "list" ? undefined : target }),
+			opRef: verb === "status" ? args.opRef : (flagRec["op-ref"] as string | undefined),
+			operation: flagRec.op as string | undefined,
+			query: flagRec.query as string | undefined,
+			text: flagRec.text as string | undefined,
+			jsonInput: flagRec["json-input"] as string | undefined,
+			jsonInputFile: flagRec["json-input-file"] as string | undefined,
+			jsonInputStdin: Boolean(flagRec["json-input-stdin"]),
+			confirm: Boolean(flagRec.confirm),
+			idempotencyKey: flagRec["idempotency-key"] as string | undefined,
+			elevationRequestId: flagRec["elevation-request-id"] as string | undefined,
+			operationKind: flagRec.kind as "control" | "global" | undefined,
+			cursor: flagRec.cursor as string | undefined,
+			showEndpointCredential: Boolean(flagRec["show-endpoint-credential"]),
+			yes: Boolean(flagRec.yes),
+			wait: Boolean(flagRec.wait),
+			timeoutMs,
+			strict: Boolean(flagRec.strict),
+			untilIdle: Boolean(flagRec["until-idle"]),
+			allEvents: Boolean(flagRec["all-events"]),
+			agentDir: flagRec["agent-dir"] as string | undefined,
+			repo: flagRec.repo as string | undefined,
+		});
+	}
+}
+
+class SdkGuidesHelp extends Command {
+	static description = "Manage verified advisory SDK guides: refresh, list, show, status, or trust.";
+	static args = {
+		action: Args.string({ required: false, options: ["refresh", "list", "show", "status", "trust"] }),
+		guideId: Args.string({ required: false, description: "Guide id for show" }),
+	};
+	static flags = {
+		"agent-dir": Flags.string({ description: "SDK broker state directory" }),
+		url: Flags.string({ description: "HTTPS allowlisted manifest URL for refresh" }),
+		"timeout-ms": Flags.string({ description: "Bounded refresh timeout in milliseconds" }),
+	};
+	async run(): Promise<void> {}
+}
+
+class SdkGuidesCommand extends Command {
+	static description = SdkGuidesHelp.description;
+	static args = SdkGuidesHelp.args;
+	static flags = SdkGuidesHelp.flags;
+	async run(): Promise<void> {
+		const { args, flags } = await this.parse(SdkGuidesCommand);
+		const flagRec = flags as Record<string, unknown>;
+		await runSdkGuidesCli({
+			action: args.action,
+			guideId: args.guideId,
+			url: flagRec.url as string | undefined,
+			agentDir: flagRec["agent-dir"] as string | undefined,
+			timeoutMs: parsePositiveTimeout(flagRec["timeout-ms"] as string | undefined, "--timeout-ms"),
+		});
+	}
+}
+
 export default class Sdk extends Command {
-	static description = "gjc sdk serve --stdio | --socket <path> [--session <id>] [--pending-ceiling <bytes>]";
+	static description =
+		"gjc sdk serve --stdio | --socket <path> [--session <id>]; gjc sdk session list|inspect|send|status|tail; gjc sdk guides refresh|list|show|status|trust";
 	static hidden = false;
 	static delegateHelp = true;
-	static args = { action: Args.string({ required: false, options: ["serve"] }) };
+	static args = { action: Args.string({ required: false, options: ["serve", "session", "guides"] }) };
 	static flags = SdkServeHelp.flags;
 	async run(): Promise<void> {
 		const action = this.argv[0];
 		if (this.argv.includes("--help") || this.argv.includes("-h")) {
-			renderCommandHelp("gjc", action === "serve" ? "sdk serve" : "sdk", action === "serve" ? SdkServeHelp : Sdk);
+			const helpAction =
+				action === "serve"
+					? "sdk serve"
+					: action === "session"
+						? "sdk session"
+						: action === "guides"
+							? "sdk guides"
+							: "sdk";
+			const helpCommand =
+				action === "serve"
+					? SdkServeHelp
+					: action === "session"
+						? SdkSessionCommand
+						: action === "guides"
+							? SdkGuidesCommand
+							: Sdk;
+			renderCommandHelp("gjc", helpAction, helpCommand);
+			return;
+		}
+		if (action === "session") {
+			const instance = new SdkSessionCommand(this.argv.slice(1), this.config);
+			await instance.run();
+			return;
+		}
+		if (action === "guides") {
+			const instance = new SdkGuidesCommand(this.argv.slice(1), this.config);
+			await instance.run();
 			return;
 		}
 		if (action === "serve") {
@@ -725,7 +899,7 @@ export default class Sdk extends Command {
 			return;
 		}
 		if (action !== "broker-internal" && action !== "session-host-internal")
-			throw new CliParseError("Expected action to be serve.");
+			throw new CliParseError("Expected action to be serve, session, or guides.");
 		const internal = parseSdkInternalArgv(this.argv);
 		if (internal.action === "session-host-internal") {
 			await runSessionHost();

package/src/commands/setup.ts

@@ -50,10 +50,12 @@ export default class Setup extends Command {
 		"gjc-command": Flags.string({ description: "Command used to start `gjc mcp-serve coordinator`" }),
 		target: Flags.string({ description: "Hermes config file target for config-only install" }),
 		"profile-dir": Flags.string({ description: "Hermes profile directory for full setup install" }),
-		preset: Flags.string({ description: "Provider preset: minimax, minimax-cn, or glm" }),
+		preset: Flags.string({ description: "Provider preset id (run setup provider --help to list available presets)" }),
 		compat: Flags.string({ description: "Provider compatibility: openai or anthropic" }),
 		provider: Flags.string({ description: "Provider id to add to models.yml" }),
-		"base-url": Flags.string({ description: "Provider API base URL" }),
+		"base-url": Flags.string({
+			description: "Provider API base URL (required for proxy presets: litellm, openai-compatible-proxy)",
+		}),
 		"api-key-env": Flags.string({ description: "Read provider API key from this environment variable" }),
 		model: Flags.string({ description: "Model id to add (repeat or comma-separate)", multiple: true }),
 		"models-path": Flags.string({ description: "Override models config path" }),

package/src/config/file-lock-gc.ts

@@ -35,6 +35,8 @@ interface WalkState {
 export interface FileLocksGcCollectOptions {
 	/** Override per-root entry budget (tests). Defaults to {@link FILE_LOCK_GC_MAX_WALK_ENTRIES}. */
 	maxWalkEntries?: number;
+	/** Override global lock roots for isolated collection tests. */
+	roots?: readonly string[];
 }
 
 // Global, env-aware GJC lock roots. Per the approved scope this covers the
@@ -169,7 +171,8 @@ export async function collectFileLocksForGc(
 	const warnings: GcWarning[] = [];
 	const lockDirs = new Set<string>();
 
-	for (const root of knownFileLockRoots(ctx)) {
+	const roots = options.roots ?? knownFileLockRoots(ctx);
+	for (const root of Array.from(new Set(roots.map(root => path.resolve(root))))) {
 		// Fresh budget per root so a huge agent dir cannot starve config/spool.
 		const state: WalkState = { entries: 0, truncated: false };
 		await walkForLockDirs(root, 0, state, lockDirs, errors, maxWalkEntries);

package/src/config/model-equivalence.ts

@@ -24,6 +24,15 @@ export interface CanonicalModelIndex {
 	records: CanonicalModelRecord[];
 	byId: Map<string, CanonicalModelRecord>;
 	bySelector: Map<string, string>;
+	/**
+	 * Final-slash-segment lookup aliases: normalized alias key -> normalized
+	 * variant selectors ("provider/id") of every variant whose model id ends in
+	 * that segment. Variant-level: an alias never widens to sibling variants in
+	 * the same canonical record that end in a different segment. Multi-target
+	 * when distinct variants collide on the same segment. Built without
+	 * rewriting the canonical or runtime identity of any variant.
+	 */
+	aliases: Map<string, string[]>;
 }
 
 interface CanonicalReferenceData {
@@ -104,6 +113,22 @@ export function formatCanonicalVariantSelector(model: Model<Api>): string {
 	return `${model.provider}/${model.id}`;
 }
 
+/**
+ * Normalize a model id into its final-slash-segment alias key (trimmed and
+ * lowercased). A bare id without a slash yields the id itself; a multi-level
+ * id yields its last path segment. Returns undefined for empty ids.
+ */
+export function getFinalSlashSegmentAliasKey(modelId: string): string | undefined {
+	const normalized = modelId.trim();
+	if (!normalized) {
+		return undefined;
+	}
+	const slashIndex = normalized.lastIndexOf("/");
+	const segment = slashIndex >= 0 ? normalized.slice(slashIndex + 1) : normalized;
+	const key = segment.trim().toLowerCase();
+	return key || undefined;
+}
+
 /**
  * Compare equivalent provider variants using the caller's ranking policy.
  *
@@ -112,11 +137,16 @@ export function formatCanonicalVariantSelector(model: Model<Api>): string {
  * source, input plus cache-read cost, and original catalog order. Callers that
  * do not have a canonical index can omit those axes while retaining a stable,
  * total comparison.
+ *
+ * `providerRankFirst` swaps the first two axes so configured provider rank wins
+ * over vision support; canonical/alias resolution uses this order while every
+ * existing caller keeps the legacy vision-first order by default.
  */
 export function compareEquivalentModelVariants(
 	left: Model<Api>,
 	right: Model<Api>,
 	options: {
+		providerRankFirst?: boolean;
 		providerRank?: ReadonlyMap<string, number>;
 		canonicalId?: string;
 		leftSourceRank?: number;
@@ -128,17 +158,32 @@ export function compareEquivalentModelVariants(
 ): number {
 	const leftVisionRank = Number(!left.input.includes("image"));
 	const rightVisionRank = Number(!right.input.includes("image"));
-	if (leftVisionRank !== rightVisionRank) return leftVisionRank - rightVisionRank;
 
-	if (options.providerRank) {
+	const compareProviderRank = (): number => {
+		if (!options.providerRank) {
+			return 0;
+		}
 		const leftProviderRank = options.providerRank.get(left.provider.toLowerCase()) ?? Number.MAX_SAFE_INTEGER;
 		const rightProviderRank = options.providerRank.get(right.provider.toLowerCase()) ?? Number.MAX_SAFE_INTEGER;
-		if (leftProviderRank !== rightProviderRank) return leftProviderRank - rightProviderRank;
+		return leftProviderRank - rightProviderRank;
+	};
+
+	if (options.providerRankFirst) {
+		const providerRankDiff = compareProviderRank();
+		if (providerRankDiff !== 0) return providerRankDiff;
+		if (leftVisionRank !== rightVisionRank) return leftVisionRank - rightVisionRank;
+	} else {
+		if (leftVisionRank !== rightVisionRank) return leftVisionRank - rightVisionRank;
+		const providerRankDiff = compareProviderRank();
+		if (providerRankDiff !== 0) return providerRankDiff;
 	}
 
 	if (options.canonicalId) {
-		const leftExactRank = Number(left.id !== options.canonicalId);
-		const rightExactRank = Number(right.id !== options.canonicalId);
+		// Compare case-insensitively against the normalized exactness key so a
+		// mixed-case model id still matches the alias/canonical lookup key.
+		const normalizedExactnessKey = options.canonicalId.trim().toLowerCase();
+		const leftExactRank = Number(left.id.trim().toLowerCase() !== normalizedExactnessKey);
+		const rightExactRank = Number(right.id.trim().toLowerCase() !== normalizedExactnessKey);
 		if (leftExactRank !== rightExactRank) return leftExactRank - rightExactRank;
 	}
 
@@ -835,6 +880,8 @@ export function buildCanonicalModelIndex(
 	const compiledEquivalence = compileEquivalenceConfig(equivalence);
 	const byId = new Map<string, CanonicalModelRecord>();
 	const bySelector = new Map<string, string>();
+	const aliases = new Map<string, Set<string>>();
+	const ambiguousSelectors = new Set<string>();
 
 	const compiledWithCache = compiledEquivalence as CompiledEquivalenceConfigWithCache;
 	let modelCache = compiledWithCache[kModelResolutionCache];
@@ -865,7 +912,23 @@ export function buildCanonicalModelIndex(
 		};
 		nextRecord.variants.push(variant);
 		byId.set(canonicalKey, nextRecord);
-		bySelector.set(normalizeSelectorKey(selector), canonical.id);
+		const selectorKey = normalizeSelectorKey(selector);
+		if (bySelector.has(selectorKey) || ambiguousSelectors.has(selectorKey)) {
+			bySelector.delete(selectorKey);
+			ambiguousSelectors.add(selectorKey);
+		} else {
+			bySelector.set(selectorKey, canonical.id);
+		}
+		const aliasKey = getFinalSlashSegmentAliasKey(model.id);
+		if (aliasKey) {
+			const aliasSelector = selectorKey;
+			let targets = aliases.get(aliasKey);
+			if (!targets) {
+				targets = new Set<string>();
+				aliases.set(aliasKey, targets);
+			}
+			targets.add(aliasSelector);
+		}
 	}
 
 	const records = [...byId.values()].sort(compareCanonicalRecords);
@@ -873,5 +936,11 @@ export function buildCanonicalModelIndex(
 		record.variants.sort(compareCanonicalVariants);
 	}
 
-	return { records, byId, bySelector };
+	const aliasesByKey = new Map<string, string[]>();
+	for (const [aliasKey, targets] of aliases) {
+		for (const ambiguousSelector of ambiguousSelectors) targets.delete(ambiguousSelector);
+		if (targets.size > 0) aliasesByKey.set(aliasKey, [...targets]);
+	}
+
+	return { records, byId, bySelector, aliases: aliasesByKey };
 }