@gajae-code/coding-agent 0.4.5 → 0.5.0

package/dist/types/thinking-metadata.d.ts

@@ -0,0 +1,16 @@
+export type ThinkingLevelValue = "inherit" | "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+/**
+ * Metadata used to render thinking selector values in the coding-agent UI.
+ *
+ * This module is intentionally provider/native-free so schema generation can
+ * import settings metadata before native addons have been built in CI.
+ */
+export interface ThinkingLevelMetadata {
+    value: ThinkingLevelValue;
+    label: string;
+    description: string;
+}
+/**
+ * Returns display metadata for a thinking selector.
+ */
+export declare function getThinkingLevelMetadata(level: ThinkingLevelValue): ThinkingLevelMetadata;

package/dist/types/thinking.d.ts

@@ -1,14 +1,7 @@
 import { type ResolvedThinkingLevel, ThinkingLevel } from "@gajae-code/agent-core/thinking";
 import { type Effort } from "@gajae-code/ai/model-thinking";
 import type { Model } from "@gajae-code/ai/types";
-/**
- * Metadata used to render thinking selector values in the coding-agent UI.
- */
-export interface ThinkingLevelMetadata {
-    value: ThinkingLevel;
-    label: string;
-    description: string;
-}
+export { getThinkingLevelMetadata, type ThinkingLevelMetadata } from "./thinking-metadata";
 /**
  * Parses a provider-facing effort value.
  */
@@ -17,10 +10,6 @@ export declare function parseEffort(value: string | null | undefined): Effort |
  * Parses an agent-local thinking selector.
  */
 export declare function parseThinkingLevel(value: string | null | undefined): ThinkingLevel | undefined;
-/**
- * Returns display metadata for a thinking selector.
- */
-export declare function getThinkingLevelMetadata(level: ThinkingLevel): ThinkingLevelMetadata;
 /**
  * Converts an agent-local selector into the effort sent to providers.
  */
@@ -29,3 +18,5 @@ export declare function toReasoningEffort(level: ThinkingLevel | undefined): Eff
  * Resolves a selector against the current model while preserving explicit "off".
  */
 export declare function resolveThinkingLevelForModel(model: Model | undefined, level: ThinkingLevel | undefined): ResolvedThinkingLevel | undefined;
+export declare function clampExplicitThinkingLevelForModel(model: Model | undefined, level: ThinkingLevel | undefined): ThinkingLevel | undefined;
+export declare function formatClampedModelSelector(selector: string, model: Model | undefined): string;

package/dist/types/tools/index.d.ts

@@ -193,6 +193,8 @@ export interface ToolSession {
     getToolChoiceQueue?(): ToolChoiceQueue;
     /** Build a model-provider-specific ToolChoice that targets the named tool, or undefined if unsupported. */
     buildToolChoice?(toolName: string): ToolChoice | undefined;
+    /** Build a named tool-choice decision, preserving whether exact named forcing survived capability degradation. */
+    buildToolChoiceResult?(toolName: string): import("../utils/tool-choice").NamedToolChoiceResult;
     /** Steer a hidden custom message into the conversation (e.g. a preview reminder). */
     steer?(message: {
         customType: string;

package/dist/types/tools/resolve.d.ts

@@ -21,16 +21,6 @@ export interface ResolveToolDetails {
     label?: string;
     sourceResultDetails?: unknown;
 }
-/**
- * Queue a resolve-protocol handler on the tool-choice queue. Forces the next
- * LLM call to invoke the hidden `resolve` tool, wraps the caller's apply/reject
- * callbacks into an onInvoked closure that matches the resolve schema, and
- * steers a preview reminder so the model understands why.
- *
- * This is the canonical entry point for any tool that wants preview/apply
- * semantics. No session-level abstraction is needed: callers pass their
- * apply/reject functions directly.
- */
 export declare function queueResolveHandler(session: ToolSession, options: {
     label: string;
     sourceToolName: string;

package/dist/types/utils/tool-choice.d.ts

@@ -1,7 +1,20 @@
-import type { Api, Model, ToolChoice } from "@gajae-code/ai";
+import type { Api, Model, ResolveToolChoiceResult, ToolChoice } from "@gajae-code/ai";
 /**
  * Build a provider-aware tool choice that targets one specific tool when supported.
  * Providers that only expose required/any forcing may still honor named choices by
  * narrowing their request tool list before transport.
  */
+export interface NamedToolChoiceResult {
+    choice: ToolChoice | undefined;
+    exactNamed: boolean;
+    resolved?: ResolveToolChoiceResult;
+}
+export declare function buildNamedToolChoiceResult(toolName: string, model?: Model<Api>): NamedToolChoiceResult;
+/**
+ * Legacy capability-aware wrapper. May return a lossy `"required"` when named
+ * forcing degrades (e.g. Google APIs, or compat `toolChoiceSupport: "required"`),
+ * which forces *some* tool rather than `toolName` specifically. Queue directives
+ * that need exact tool identity (resolve / todo_write / yield) MUST use
+ * `buildNamedToolChoiceResult` and gate on `exactNamed` instead.
+ */
 export declare function buildNamedToolChoice(toolName: string, model?: Model<Api>): ToolChoice | undefined;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/coding-agent",
-	"version": "0.4.5",
+	"version": "0.5.0",
 	"description": "Gajae Code CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://gaebal-gajae.dev",
 	"author": "Yeachan-Heo",
@@ -51,12 +51,12 @@
 		"@agentclientprotocol/sdk": "0.21.0",
 		"@babel/parser": "^7.29.3",
 		"@mozilla/readability": "^0.6.0",
-		"@gajae-code/stats": "0.4.5",
-		"@gajae-code/agent-core": "0.4.5",
-		"@gajae-code/ai": "0.4.5",
-		"@gajae-code/natives": "0.4.5",
-		"@gajae-code/tui": "0.4.5",
-		"@gajae-code/utils": "0.4.5",
+		"@gajae-code/stats": "0.5.0",
+		"@gajae-code/agent-core": "0.5.0",
+		"@gajae-code/ai": "0.5.0",
+		"@gajae-code/natives": "0.5.0",
+		"@gajae-code/tui": "0.5.0",
+		"@gajae-code/utils": "0.5.0",
 		"@puppeteer/browsers": "^2.13.0",
 		"@types/turndown": "5.0.6",
 		"@xterm/headless": "^6.0.0",

package/src/cli.ts

@@ -5,11 +5,15 @@
  * lightweight CLI runner from pi-utils.
  */
 import { Args, type CliConfig, Command, type CommandEntry, Flags, run } from "@gajae-code/utils/cli";
-import { APP_NAME, MIN_BUN_VERSION, VERSION } from "@gajae-code/utils/dirs";
+import { APP_NAME, formatBunRuntimeError, MIN_BUN_VERSION, VERSION } from "@gajae-code/utils/dirs";
 
 if (Bun.semver.order(Bun.version, MIN_BUN_VERSION) < 0) {
 	process.stderr.write(
-		`error: Bun runtime must be >= ${MIN_BUN_VERSION} (found v${Bun.version}). Please upgrade: bun upgrade\n`,
+		formatBunRuntimeError({
+			currentVersion: Bun.version,
+			minVersion: MIN_BUN_VERSION,
+			execPath: process.execPath,
+		}),
 	);
 	process.exit(1);
 }
@@ -130,8 +134,8 @@ class RootHelpCommand extends Command {
 		`# Launch in a sibling git worktree\n  ${APP_NAME} --worktree`,
 		`# Use different model (fuzzy matching)\n  ${APP_NAME} --model opus "Help me refactor this code"`,
 		`# Limit model cycling to specific models\n  ${APP_NAME} --models claude-sonnet,claude-haiku,gpt-4o`,
-		`# Activate a model profile for this session\n  ${APP_NAME} --mpreset codex-standard`,
-		`# Persist a model profile as the default\n  ${APP_NAME} --mpreset opencode-go-pro --default`,
+		`# Activate a model profile for this session\n  ${APP_NAME} --mpreset codex-medium`,
+		`# Persist a model profile as the default\n  ${APP_NAME} --mpreset opencodego --default`,
 		`# Export a session file to HTML\n  ${APP_NAME} --export ~/.gjc/agent/sessions/--path--/session.jsonl`,
 	];
 	static strict = false;

package/src/commands/harness.ts

@@ -11,16 +11,18 @@
 import { execFileSync } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
+import * as path from "node:path";
 import { Args, Command, Flags } from "@gajae-code/utils/cli";
 import { resolveGjcTmuxCommand, sanitizeTmuxToken } from "../gjc-runtime/tmux-common";
 import { classifyRecovery } from "../harness-control-plane/classifier";
 import { callEndpoint, EndpointUnreachableError } from "../harness-control-plane/control-endpoint";
 import { type ResolvedOwner, RuntimeOwner, resolveOwner } from "../harness-control-plane/owner";
 import { preserveDirtyWorktree } from "../harness-control-plane/preserve";
+import { RECEIPT_SPOOL_DIR_ENV } from "../harness-control-plane/receipt-spool";
 import { buildReceipt, requiresVanishBeforeAction, type VanishEvidence } from "../harness-control-plane/receipts";
 import { GajaeCodeRpc } from "../harness-control-plane/rpc-adapter";
 import { classifyLeaseStatus, readLease } from "../harness-control-plane/session-lease";
-import { buildResponse, buildStateView } from "../harness-control-plane/state-machine";
+import { buildResponse, buildStateView, submitUnavailableReason } from "../harness-control-plane/state-machine";
 import {
 	canonicalWorkspacePath,
 	generateSessionId,
@@ -513,6 +515,9 @@ export default class Harness extends Command {
 		cursor: Flags.string({ description: "Event cursor for events --follow (exclusive)", default: "0" }),
 		follow: Flags.boolean({ description: "Tail the owner-written event log", default: false }),
 		json: Flags.boolean({ char: "j", description: "Emit machine-readable JSON", default: true }),
+		"receipt-spool-dir": Flags.string({
+			description: "Append persisted ReceiptEnvelope records to spool.jsonl under this directory",
+		}),
 	};
 
 	static examples = [
@@ -527,6 +532,11 @@ export default class Harness extends Command {
 		const verb = String(args.verb);
 		let root = resolveHarnessRoot();
 		try {
+			const receiptSpoolDir = flags["receipt-spool-dir"];
+			if (receiptSpoolDir !== undefined) {
+				if (!receiptSpoolDir.trim()) throw new Error("receipt_spool_dir_empty");
+				process.env[RECEIPT_SPOOL_DIR_ENV] = path.resolve(receiptSpoolDir.trim());
+			}
 			const input = parseInput(flags.input);
 			const promptFile = flags["prompt-file"];
 			if (promptFile !== undefined) {
@@ -676,6 +686,9 @@ export default class Harness extends Command {
 		}
 		const sessionName = deterministicHarnessTmuxSessionName(sessionId);
 		const envAssignments = [`GJC_HARNESS_STATE_ROOT=${shellQuote(root)}`];
+		if (process.env[RECEIPT_SPOOL_DIR_ENV]) {
+			envAssignments.push(`${RECEIPT_SPOOL_DIR_ENV}=${shellQuote(process.env[RECEIPT_SPOOL_DIR_ENV])}`);
+		}
 		if (process.env.GJC_HARNESS_RPC_COMMAND) {
 			envAssignments.push(`GJC_HARNESS_RPC_COMMAND=${shellQuote(process.env.GJC_HARNESS_RPC_COMMAND)}`);
 		}
@@ -715,6 +728,9 @@ export default class Harness extends Command {
 			env: {
 				...process.env,
 				GJC_HARNESS_STATE_ROOT: root,
+				...(process.env[RECEIPT_SPOOL_DIR_ENV]
+					? { [RECEIPT_SPOOL_DIR_ENV]: process.env[RECEIPT_SPOOL_DIR_ENV] }
+					: {}),
 				...(process.env.GJC_HARNESS_TEST_NODE_MODULES
 					? { GJC_HARNESS_TEST_NODE_MODULES: process.env.GJC_HARNESS_TEST_NODE_MODULES }
 					: {}),
@@ -878,7 +894,9 @@ export default class Harness extends Command {
 	): Promise<boolean> {
 		const owner = await resolveOwner(root, sessionId);
 		if (!owner.live || !owner.socketPath) return false;
+		const priorSpoolDir = input[RECEIPT_SPOOL_DIR_ENV];
 		try {
+			if (process.env[RECEIPT_SPOOL_DIR_ENV]) input[RECEIPT_SPOOL_DIR_ENV] = process.env[RECEIPT_SPOOL_DIR_ENV];
 			const res = (await callEndpoint(owner.socketPath, { verb, input })) as { ok?: boolean };
 			writeJson(res);
 			if (res?.ok === false) process.exitCode = 1;
@@ -886,6 +904,9 @@ export default class Harness extends Command {
 		} catch (error) {
 			if (error instanceof EndpointUnreachableError) return false;
 			throw error;
+		} finally {
+			if (priorSpoolDir === undefined) delete input[RECEIPT_SPOOL_DIR_ENV];
+			else input[RECEIPT_SPOOL_DIR_ENV] = priorSpoolDir;
 		}
 	}
 
@@ -978,8 +999,21 @@ export default class Harness extends Command {
 
 	async #submit(root: string, input: Record<string, unknown>, flagSession: string | undefined): Promise<void> {
 		const sessionId = requireSessionId(input, flagSession);
-		if (await this.#tryOwnerRoute(root, sessionId, "submit", { ...input, sessionId })) return;
 		let state = await loadState(root, sessionId);
+		const noOwnerGate = submitUnavailableReason(state.lifecycle, false);
+		if (!noOwnerGate || noOwnerGate === "owner-not-live") {
+			if (await this.#tryOwnerRoute(root, sessionId, "submit", { ...input, sessionId })) return;
+			state = await loadState(root, sessionId);
+		}
+		const blockedByOwnerLiveness = state.blockers.some(
+			blocker => isOwnerLivenessBlocker(blocker) || blocker === OWNER_STARTUP_BLOCKER,
+		);
+		const lifecycleGate = submitUnavailableReason(state.lifecycle, false);
+		if (lifecycleGate && lifecycleGate !== "owner-not-live" && !blockedByOwnerLiveness) {
+			writeJson(buildResponse(state, false, { accepted: false, submitted: false, reason: lifecycleGate }, false));
+			process.exitCode = 1;
+			return;
+		}
 		// No live owner: submission is blocked (never echoed-as-accepted). Surface owner exit
 		// evidence + explicit recovery guidance so the caller is not left with a bare gate.
 		const ownerExit = await buildOwnerExitEvidence(root, state);

package/src/commands/launch.ts

@@ -142,8 +142,8 @@ export default class Index extends Command {
 		`# Launch in a sibling git worktree\n  ${APP_NAME} --worktree`,
 		`# Use different model (fuzzy matching)\n  ${APP_NAME} --model opus "Help me refactor this code"`,
 		`# Limit model cycling to specific models\n  ${APP_NAME} --models claude-sonnet,claude-haiku,gpt-4o`,
-		`# Activate a model profile for this session\n  ${APP_NAME} --mpreset codex-standard`,
-		`# Persist a model profile as the default\n  ${APP_NAME} --mpreset opencode-go-pro --default`,
+		`# Activate a model profile for this session\n  ${APP_NAME} --mpreset codex-medium`,
+		`# Persist a model profile as the default\n  ${APP_NAME} --mpreset opencodego --default`,
 		`# Export a session file to HTML\n  ${APP_NAME} --export ~/.gjc/agent/sessions/--path--/session.jsonl`,
 	];
 

package/src/commands/session.ts

@@ -18,7 +18,9 @@ function writeText(lines: string[]): void {
 function writeJsonFailure(error: unknown): void {
 	const message = error instanceof Error ? error.message : String(error);
 	const [reason = "session_error"] = message.split(":");
-	writeJson({ ok: false, reason });
+	const hintIndex = message.indexOf(" — ");
+	const detail = hintIndex >= 0 ? message.slice(hintIndex + " — ".length).trim() : "";
+	writeJson(detail ? { ok: false, reason, detail } : { ok: false, reason });
 }
 
 interface SessionJsonDto {

package/src/config/model-profile-activation.ts

@@ -1,6 +1,7 @@
 import type { ThinkingLevel } from "@gajae-code/agent-core";
 import type { Api, Model } from "@gajae-code/ai";
 import type { AgentSession } from "../session/agent-session";
+import { formatClampedModelSelector } from "../thinking";
 import {
 	aggregateModelProfileRequiredProviders,
 	formatAvailableProfileNames,
@@ -10,8 +11,14 @@ import { type GjcModelAssignmentTargetId, isAuthenticated, type ModelRegistry }
 import { resolveModelRoleValue } from "./model-resolver";
 import type { Settings } from "./settings";
 
+type ModelProfileActivationSession = Pick<AgentSession, "model" | "thinkingLevel" | "sessionId"> & {
+	setModelTemporary?: AgentSession["setModelTemporary"];
+	setActiveModelProfile?: (name: string | undefined) => void;
+	getActiveModelProfile?: () => string | undefined;
+};
+
 export interface PrepareModelProfileActivationOptions {
-	session: Pick<AgentSession, "model" | "thinkingLevel" | "sessionId">;
+	session: ModelProfileActivationSession;
 	modelRegistry: Pick<
 		ModelRegistry,
 		| "getModelProfile"
@@ -29,7 +36,7 @@ export interface PrepareModelProfileActivationOptions {
 
 export interface PreparedModelProfileActivation {
 	profileName: string;
-	session: Pick<AgentSession, "model" | "thinkingLevel" | "sessionId" | "setModelTemporary">;
+	session: ModelProfileActivationSession & { setModelTemporary: AgentSession["setModelTemporary"] };
 	settings: Pick<Settings, "get" | "override" | "set" | "flush">;
 	previousModel: Model<Api> | undefined;
 	previousThinkingLevel: ThinkingLevel | undefined;
@@ -37,6 +44,7 @@ export interface PreparedModelProfileActivation {
 	defaultModel: Model<Api> | undefined;
 	defaultThinkingLevel: ThinkingLevel | undefined;
 	agentModelOverrides: Record<string, string>;
+	previousActiveModelProfile: string | undefined;
 }
 
 export function formatModelProfileCredentialError(profileName: string, providers: readonly string[]): string {
@@ -89,7 +97,7 @@ export async function prepareModelProfileActivation(
 		if (!resolved.model) {
 			throw new Error(`Model profile "${options.profileName}" ${role} selector did not resolve: ${selector}`);
 		}
-		agentModelOverrides[role] = selector;
+		agentModelOverrides[role] = formatClampedModelSelector(selector, resolved.model);
 	}
 
 	return {
@@ -102,6 +110,7 @@ export async function prepareModelProfileActivation(
 		defaultModel: resolvedDefault?.model,
 		defaultThinkingLevel: resolvedDefault?.thinkingLevel,
 		agentModelOverrides,
+		previousActiveModelProfile: options.session.getActiveModelProfile?.(),
 	};
 }
 
@@ -113,6 +122,7 @@ export async function applyPreparedModelProfileActivation(
 	const previousThinkingLevel = prepared.previousThinkingLevel;
 	const previousAgentModelOverrides = prepared.previousAgentModelOverrides;
 	const previousPersistedDefault = prepared.settings.get("modelProfile.default");
+	const previousActiveModelProfile = prepared.previousActiveModelProfile;
 	let modelChanged = false;
 	let overridesChanged = false;
 	let defaultChanged = false;
@@ -134,6 +144,7 @@ export async function applyPreparedModelProfileActivation(
 			defaultChanged = true;
 			await prepared.settings.flush();
 		}
+		prepared.session.setActiveModelProfile?.(prepared.profileName);
 	} catch (error) {
 		if (defaultChanged) {
 			prepared.settings.set("modelProfile.default", previousPersistedDefault);
@@ -141,6 +152,7 @@ export async function applyPreparedModelProfileActivation(
 		if (overridesChanged) {
 			prepared.settings.override("task.agentModelOverrides", previousAgentModelOverrides);
 		}
+		prepared.session.setActiveModelProfile?.(previousActiveModelProfile);
 		if (modelChanged && previousModel) {
 			await prepared.session.setModelTemporary(previousModel, previousThinkingLevel);
 		}