@gajae-code/coding-agent 0.2.2 → 0.2.4

package/src/sdk.ts

@@ -12,6 +12,7 @@ import {
 	type CredentialDisabledEvent,
 	type Message,
 	type Model,
+	type ProviderSessionState,
 	type SimpleStreamOptions,
 	streamSimple,
 } from "@gajae-code/ai";
@@ -82,7 +83,7 @@ import {
 	obfuscateMessages,
 	SecretObfuscator,
 } from "./secrets";
-import { AgentSession } from "./session/agent-session";
+import { AgentSession, type ForkContextSeed } from "./session/agent-session";
 import { resolveAuthBrokerConfig } from "./session/auth-broker-config";
 import { AuthBrokerClient, AuthStorage, RemoteAuthCredentialStore } from "./session/auth-storage";
 import { type CustomMessage, convertToLlm } from "./session/messages";
@@ -320,6 +321,10 @@ export interface CreateAgentSessionOptions {
 	 * `@opentelemetry/api` package returns a no-op tracer in that case.
 	 */
 	telemetry?: AgentTelemetryConfig;
+	/** Optional fork-context seed used to initialize a child session before its first prompt. */
+	forkContextSeed?: ForkContextSeed;
+	/** Optional provider state override. Fork-context children should omit this by default. */
+	providerSessionState?: Map<string, ProviderSessionState>;
 }
 
 /** Result from createAgentSession */
@@ -861,7 +866,8 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		logger.time("sessionManager", () =>
 			SessionManager.create(cwd, SessionManager.getDefaultSessionDir(cwd, agentDir)),
 		);
-	const providerSessionId = options.providerSessionId ?? sessionManager.getSessionId();
+	const logicalSessionId = sessionManager.getSessionId();
+	const providerSessionId = options.providerSessionId ?? options.forkContextSeed?.cacheIdentity ?? logicalSessionId;
 	const modelApiKeyAvailability = new Map<string, boolean>();
 	const getModelAvailabilityKey = (candidate: Model): string =>
 		`${candidate.provider}\u0000${candidate.baseUrl ?? ""}`;
@@ -1153,7 +1159,12 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			trackEvalExecution: (execution, abortController) =>
 				session ? session.trackEvalExecution(execution, abortController) : execution,
 			getSessionId: () => sessionManager.getSessionId?.() ?? null,
+			getActiveSkillState: () => session?.getActiveSkillState(),
+			getActiveSkillPhase: () => session?.getActiveSkillPhase(),
 			getHindsightSessionState: () => session?.getHindsightSessionState(),
+			get model() {
+				return agent?.state.model ?? model;
+			},
 			getAgentId: () => resolvedAgentId,
 			getToolByName: name => session?.getToolByName(name),
 			agentRegistry,
@@ -1195,6 +1206,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 					attribution: "agent",
 					timestamp: Date.now(),
 				}),
+			sendCustomMessage: (msg, opts) => session.sendCustomMessage(msg, opts),
 			peekQueueInvoker: () => session.peekQueueInvoker(),
 			peekStandingResolveHandler: () => session.peekStandingResolveHandler(),
 			setStandingResolveHandler: handler => session.setStandingResolveHandler(handler),
@@ -1210,6 +1222,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			authStorage,
 			modelRegistry,
 			getTelemetry: () => agent?.telemetry,
+			buildForkContextSeed: forkOptions => session.buildForkContextSeed(forkOptions),
 		};
 
 		// Wire process-wide internal URL singletons owned by their real classes.
@@ -1719,6 +1732,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		const preferOpenAICodexWebsockets =
 			openaiWebsocketSetting === "on" ? true : openaiWebsocketSetting === "off" ? false : undefined;
 		const serviceTierSetting = settings.get("serviceTier");
+		const retrySettings = settings.getGroup("retry");
 
 		const initialServiceTier = hasServiceTierEntry
 			? existingSession.serviceTier
@@ -1726,17 +1740,43 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				? undefined
 				: serviceTierSetting;
 
+		const appendOnlyContext =
+			model && resolveAppendOnlyMode(settings.get("provider.appendOnlyContext"), model.provider)
+				? new AppendOnlyContextManager()
+				: undefined;
+		if (appendOnlyContext && options.forkContextSeed && !hasExistingSession) {
+			if (options.forkContextSeed.appendOnlyPrefixSnapshot) {
+				(
+					appendOnlyContext.prefix as typeof appendOnlyContext.prefix & {
+						importSnapshot(
+							snapshot: NonNullable<ForkContextSeed["appendOnlyPrefixSnapshot"]>,
+							options: { intentTracing: boolean },
+						): void;
+					}
+				).importSnapshot(options.forkContextSeed.appendOnlyPrefixSnapshot, { intentTracing: !!intentField });
+			}
+			(
+				appendOnlyContext as AppendOnlyContextManager & {
+					seedNormalizedMessages(messages: readonly Message[]): void;
+				}
+			).seedNormalizedMessages(options.forkContextSeed.messages);
+		}
+
 		agent = new Agent({
 			initialState: {
 				systemPrompt,
 				model,
 				thinkingLevel: toReasoningEffort(thinkingLevel),
 				tools: initialTools,
+				...(options.forkContextSeed && !hasExistingSession
+					? { messages: options.forkContextSeed.agentMessages }
+					: {}),
 			},
 			convertToLlm: convertToLlmFinal,
 			onPayload,
 			onResponse,
-			sessionId: providerSessionId,
+			sessionId: logicalSessionId,
+			providerSessionId,
 			transformContext,
 			steeringMode: settings.get("steeringMode") ?? "one-at-a-time",
 			followUpMode: settings.get("followUpMode") ?? "one-at-a-time",
@@ -1750,19 +1790,23 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			repetitionPenalty: settings.get("repetitionPenalty") >= 0 ? settings.get("repetitionPenalty") : undefined,
 			serviceTier: initialServiceTier,
 			hideThinkingSummary: settings.get("hideThinkingBlock"),
+			maxRetryDelayMs: retrySettings.maxDelayMs,
+			requestMaxRetries: retrySettings.requestMaxRetries,
+			streamMaxRetries: retrySettings.streamMaxRetries,
 			kimiApiFormat: settings.get("providers.kimiApiFormat") ?? "anthropic",
 			preferWebsockets: preferOpenAICodexWebsockets,
 			getToolContext: tc => toolContextStore.getContext(tc),
 			getApiKey: async provider => {
 				// Read agent.sessionId at call time so credential selection stays aligned
 				// with metadataResolver after /new, fork, resume, or branch switches.
-				const key = await modelRegistry.getApiKeyForProvider(provider, agent.sessionId);
+				const key = await modelRegistry.getApiKeyForProvider(provider, agent.providerSessionId ?? agent.sessionId);
 				if (!key) {
 					throw new Error(`No API key found for provider "${provider}"`);
 				}
 				return key;
 			},
-			getAuthCredentialType: provider => modelRegistry.getSessionCredentialType(provider, agent.sessionId),
+			getAuthCredentialType: provider =>
+				modelRegistry.getSessionCredentialType(provider, agent.providerSessionId ?? agent.sessionId),
 			streamFn: (streamModel, context, streamOptions) =>
 				streamSimple(streamModel, context, {
 					...streamOptions,
@@ -1793,11 +1837,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			intentTracing: !!intentField,
 			getToolChoice: () => session?.nextToolChoice(),
 			telemetry: options.telemetry,
-			appendOnlyContext: model
-				? resolveAppendOnlyMode(settings.get("provider.appendOnlyContext"), model.provider)
-					? new AppendOnlyContextManager()
-					: undefined
-				: undefined,
+			appendOnlyContext,
 		});
 
 		cursorEventEmitter = event => agent.emitExternalEvent(event);
@@ -1836,6 +1876,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			skillWarnings,
 			skillsSettings: settings.getGroup("skills"),
 			modelRegistry,
+			taskDepth,
 			toolRegistry,
 			transformContext,
 			onPayload,
@@ -1868,6 +1909,9 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			agentId: resolvedAgentId,
 			agentRegistry,
 			providerSessionId: options.providerSessionId,
+			providerCacheSessionId: providerSessionId,
+			forkContextSeed: options.forkContextSeed,
+			providerSessionState: options.providerSessionState,
 		});
 		hasSession = true;
 		if (asyncJobManager) {

package/src/session/agent-session.ts

@@ -28,8 +28,10 @@ import {
 	type AgentTool,
 	AppendOnlyContextManager,
 	resolveTelemetry,
+	type StablePrefixSnapshot,
 	ThinkingLevel,
 } from "@gajae-code/agent-core";
+import { normalizeMessagesForProvider } from "@gajae-code/agent-core/agent-loop";
 import {
 	AUTO_HANDOFF_THRESHOLD_FOCUS,
 	CompactionCancelledError,
@@ -75,6 +77,33 @@ import {
 	resolveServiceTier,
 	streamSimple,
 } from "@gajae-code/ai";
+
+export interface ForkContextSeedMetadata {
+	sourceSessionId: string;
+	parentMessageCount: number;
+	includedMessages: number;
+	skippedMessages: number;
+	approximateTokens: number;
+	maxMessages: number;
+	maxTokens: number;
+	skippedReasons: Record<string, number>;
+}
+
+export interface ForkContextSeed {
+	messages: Message[];
+	agentMessages: AgentMessage[];
+	metadata: ForkContextSeedMetadata;
+	cacheIdentity?: string;
+	appendOnlyPrefixSnapshot?: StablePrefixSnapshot;
+}
+
+export interface ForkContextSeedOptions {
+	maxMessages: number;
+	maxTokens: number;
+	cacheIdentity?: string;
+	signal?: AbortSignal;
+}
+
 import { MacOSPowerAssertion } from "@gajae-code/natives";
 import {
 	extractRetryHint,
@@ -168,7 +197,7 @@ import {
 } from "../runtime-mcp/discoverable-tool-metadata";
 import { deobfuscateSessionContext, type SecretObfuscator } from "../secrets/obfuscator";
 import { formatNoCredentialOnboardingError, formatNoModelOnboardingError } from "../setup/model-onboarding-guidance";
-import { isCanonicalGjcWorkflowSkill, syncSkillActiveState } from "../skill-state/active-state";
+import { isCanonicalGjcWorkflowSkill } from "../skill-state/active-state";
 import { assertDeepInterviewMutationAllowed } from "../skill-state/deep-interview-mutation-guard";
 import { invalidateHostMetadata } from "../ssh/connection-manager";
 import { resolveThinkingLevelForModel, toReasoningEffort } from "../thinking";
@@ -246,6 +275,13 @@ export type AgentSessionEvent =
 	| { type: "thinking_level_changed"; thinkingLevel: ThinkingLevel | undefined }
 	| { type: "goal_updated"; goal: Goal | null; state?: GoalModeState };
 
+/**
+ * Safe path component pattern used to validate session-id segments before
+ * joining them into `.gjc/state` paths. Mirrors the regex used by the
+ * `gjc state` runtime selector resolver.
+ */
+const SAFE_PATH_COMPONENT = /^[A-Za-z0-9_-][A-Za-z0-9._-]{0,63}$/;
+
 /** Listener function for agent session events */
 export type AgentSessionEventListener = (event: AgentSessionEvent) => void;
 export type AsyncJobSnapshotItem = Pick<AsyncJob, "id" | "type" | "status" | "label" | "startTime">;
@@ -283,6 +319,8 @@ export interface AgentSessionConfig {
 	skillsSettings?: SkillsSettings;
 	/** Model registry for API key resolution and model discovery */
 	modelRegistry: ModelRegistry;
+	/** Task recursion depth for nested sessions. Top-level sessions use 0. */
+	taskDepth?: number;
 	/** Tool registry for LSP and settings */
 	toolRegistry?: Map<string, AgentTool>;
 	/** Current session pre-LLM message transform pipeline */
@@ -331,6 +369,10 @@ export interface AgentSessionConfig {
 	 * **MUST NOT** dispose it on their own teardown.
 	 */
 	ownedAsyncJobManager?: AsyncJobManager;
+	/** Optional fork-context seed used to initialize a child session before its first prompt. */
+	forkContextSeed?: ForkContextSeed;
+	/** Optional provider state override. Fork-context children should omit this by default. */
+	providerSessionState?: Map<string, ProviderSessionState>;
 	/** Agent identity (registry id like "0-Main" or "3-Alice") used for IRC routing. */
 	agentId?: string;
 	/** Shared agent registry (for forwarding IRC observations to the main session UI). */
@@ -342,6 +384,8 @@ export interface AgentSessionConfig {
 	 * so that credential sticky selection is consistent with the session's streaming calls.
 	 */
 	providerSessionId?: string;
+	/** Optional provider-facing cache identity, distinct from logical session identity. */
+	providerCacheSessionId?: string;
 }
 
 /** Options for AgentSession.prompt() */
@@ -749,6 +793,7 @@ export class AgentSession {
 	readonly agent: Agent;
 	readonly sessionManager: SessionManager;
 	readonly settings: Settings;
+	readonly taskDepth: number;
 	readonly yieldQueue: YieldQueue;
 
 	#powerAssertion: MacOSPowerAssertion | undefined;
@@ -836,6 +881,7 @@ export class AgentSession {
 	#agentId: string | undefined;
 	#agentRegistry: AgentRegistry | undefined;
 	#providerSessionId: string | undefined;
+	#providerCacheSessionId: string | undefined;
 	#isDisposed = false;
 	// Extension system
 	#extensionRunner: ExtensionRunner | undefined = undefined;
@@ -1007,6 +1053,7 @@ export class AgentSession {
 		this.agent = config.agent;
 		this.sessionManager = config.sessionManager;
 		this.settings = config.settings;
+		this.taskDepth = config.taskDepth ?? 0;
 		// Power assertions are taken per turn (see #beginInFlight); nothing acquired here.
 		this.#evalKernelOwnerId = config.evalKernelOwnerId ?? `agent-session:${Snowflake.next()}`;
 		this.#ownedAsyncJobManager = config.ownedAsyncJobManager;
@@ -1020,6 +1067,9 @@ export class AgentSession {
 		this.#customCommands = config.customCommands ?? [];
 		this.#skillsSettings = config.skillsSettings;
 		this.#modelRegistry = config.modelRegistry;
+		if (config.providerSessionState) {
+			this.#providerSessionState = config.providerSessionState;
+		}
 		this.#validateRetryFallbackChains();
 		this.#toolRegistry = config.toolRegistry ?? new Map();
 		this.#requestedToolNames = config.requestedToolNames;
@@ -1099,6 +1149,7 @@ export class AgentSession {
 		this.#agentId = config.agentId;
 		this.#agentRegistry = config.agentRegistry;
 		this.#providerSessionId = config.providerSessionId;
+		this.#providerCacheSessionId = config.providerCacheSessionId;
 		this.agent.setAssistantMessageEventInterceptor((message, assistantMessageEvent) => {
 			const event: AgentEvent = {
 				type: "message_update",
@@ -1196,6 +1247,46 @@ export class AgentSession {
 		return this.#toolChoiceQueue;
 	}
 
+	/** Current skill prompt executing in this session, if any. */
+	getActiveSkillState(): { skill: string; session_id?: string } | undefined {
+		if (!this.#activeSkillState) return undefined;
+		return {
+			skill: this.#activeSkillState.skill,
+			...(this.#activeSkillState.sessionId ? { session_id: this.#activeSkillState.sessionId } : {}),
+		};
+	}
+
+	/** Best-effort accessor for the active skill's `current_phase` field from
+	 *  its persisted mode-state file. Used by the `skill` tool to enforce the
+	 *  terminal-phase chain guard. Returns undefined when no active skill is
+	 *  recorded or the mode-state file is missing/unreadable; callers should
+	 *  treat undefined as a non-terminal phase (refuses to chain). */
+	getActiveSkillPhase(): string | undefined {
+		const active = this.#activeSkillState;
+		if (!active) return undefined;
+		// Path safety: refuse to read mode-state files when the skill or
+		// session-id are not safe path components. The `skill` tool
+		// interprets undefined as a non-terminal phase, so chaining is
+		// refused — there is no risk of bypassing the guard via a custom
+		// skill name with `..` or a session-id with separators.
+		if (!isCanonicalGjcWorkflowSkill(active.skill)) return undefined;
+		if (active.sessionId !== undefined && !SAFE_PATH_COMPONENT.test(active.sessionId)) {
+			return undefined;
+		}
+		try {
+			const stateDir = path.join(this.sessionManager.getCwd(), ".gjc", "state");
+			const segments = active.sessionId
+				? [stateDir, "sessions", encodeURIComponent(active.sessionId).replaceAll(".", "%2E")]
+				: [stateDir];
+			const filePath = path.join(...segments, `${active.skill}-state.json`);
+			const raw = fs.readFileSync(filePath, "utf-8");
+			const parsed = JSON.parse(raw) as { current_phase?: unknown };
+			return typeof parsed.current_phase === "string" ? parsed.current_phase : undefined;
+		} catch {
+			return undefined;
+		}
+	}
+
 	/** Peek the in-flight directive's invocation handler for use by the resolve tool. */
 	peekQueueInvoker(): ((input: unknown) => Promise<unknown> | unknown) | undefined {
 		return this.#toolChoiceQueue.peekInFlightInvoker();
@@ -1219,6 +1310,100 @@ export class AgentSession {
 		return this.#providerSessionState;
 	}
 
+	async buildForkContextSeed(options: ForkContextSeedOptions): Promise<ForkContextSeed> {
+		const transformedMessages = await this.#transformContext([...this.messages], options.signal);
+		const convertedMessages = await this.#convertToLlm(transformedMessages);
+		const providerMessages = this.model
+			? normalizeMessagesForProvider(convertedMessages, this.model)
+			: convertedMessages;
+		const maxMessages = Math.min(500, Math.max(0, Math.trunc(options.maxMessages)));
+		const maxTokens = Math.max(0, Math.trunc(options.maxTokens));
+		const selected: Message[] = [];
+		const skippedReasons: Record<string, number> = {};
+		let skippedMessages = 0;
+		let approximateTokens = 0;
+
+		const recordSkip = (reason: string) => {
+			skippedMessages++;
+			skippedReasons[reason] = (skippedReasons[reason] ?? 0) + 1;
+		};
+
+		const sanitizeMessage = (message: Message): Message | undefined => {
+			if (message.role === "developer") {
+				recordSkip("developer-role");
+				return undefined;
+			}
+			if (message.role === "toolResult") {
+				recordSkip("tool-result-role");
+				return undefined;
+			}
+			if (message.role !== "user" && message.role !== "assistant") {
+				recordSkip("unsupported-role");
+				return undefined;
+			}
+			const cloned = structuredClone(message) as Message;
+			if ("providerPayload" in cloned) {
+				delete (cloned as { providerPayload?: unknown }).providerPayload;
+			}
+			if (Array.isArray(cloned.content)) {
+				const sanitizedContent: TextContent[] = [];
+				for (const block of cloned.content) {
+					if (block.type === "text") {
+						sanitizedContent.push(block);
+					} else if (block.type === "image") {
+						sanitizedContent.push({ type: "text", text: "[Image omitted from fork-context seed]" });
+					} else if (block.type !== "thinking") {
+						recordSkip(`unsupported-content-${block.type}`);
+					}
+				}
+				return { ...cloned, content: sanitizedContent } as Message;
+			}
+			return cloned;
+		};
+
+		for (let i = providerMessages.length - 1; i >= 0; i--) {
+			if (selected.length >= maxMessages) {
+				recordSkip("message-limit");
+				continue;
+			}
+			const sanitized = sanitizeMessage(providerMessages[i]!);
+			if (!sanitized) continue;
+			const messageTokens = estimateTokens(sanitized);
+			if (maxTokens > 0 && approximateTokens + messageTokens > maxTokens) {
+				recordSkip("token-limit");
+				continue;
+			}
+			selected.unshift(sanitized);
+			approximateTokens += messageTokens;
+		}
+
+		const messages = selected;
+		let appendOnlyPrefixSnapshot: StablePrefixSnapshot | undefined;
+		const appendOnly = this.agent.appendOnlyContext;
+		if (appendOnly) {
+			if (!appendOnly.prefix.built) {
+				appendOnly.prefix.build(this.agent.state, { intentTracing: this.agent.intentTracing });
+			}
+			appendOnlyPrefixSnapshot = appendOnly.prefix.exportSnapshot() ?? undefined;
+		}
+		return {
+			messages,
+			agentMessages: messages.map(message => structuredClone(message) as AgentMessage),
+			metadata: {
+				sourceSessionId: this.sessionId,
+				parentMessageCount: providerMessages.length,
+				includedMessages: messages.length,
+				skippedMessages,
+				approximateTokens,
+				maxMessages,
+				maxTokens,
+				skippedReasons,
+			},
+			cacheIdentity: options.cacheIdentity ?? this.sessionId,
+			appendOnlyPrefixSnapshot,
+		};
+	}
+
 	getHindsightSessionState(): HindsightSessionState | undefined {
 		return this.#hindsightSessionState;
 	}
@@ -1555,11 +1740,7 @@ export class AgentSession {
 									}
 
 									const targetAssistantIndex = this.#findTtsrAssistantIndex(targetMessageTimestamp);
-									if (
-										!this.#ttsrAbortPending ||
-										this.#promptGeneration !== generation ||
-										targetAssistantIndex === -1
-									) {
+									if (!this.#ttsrAbortPending || this.#promptGeneration !== generation) {
 										this.#ttsrAbortPending = false;
 										this.#pendingTtsrInjections = [];
 										this.#perToolTtsrInjections.clear();
@@ -1569,8 +1750,8 @@ export class AgentSession {
 									this.#ttsrAbortPending = false;
 									this.#perToolTtsrInjections.clear();
 									const ttsrSettings = this.#ttsrManager?.getSettings();
-									if (ttsrSettings?.contextMode === "discard") {
-										// Remove the partial/aborted assistant turn from agent state
+									if (ttsrSettings?.contextMode === "discard" && targetAssistantIndex !== -1) {
+										// Remove the partial/aborted assistant turn from agent state when it was persisted.
 										this.agent.replaceMessages(this.agent.state.messages.slice(0, targetAssistantIndex));
 									}
 									// Inject TTSR rules as system reminder before retry
@@ -2757,6 +2938,7 @@ export class AgentSession {
 	#syncAgentSessionId(sessionId?: string): void {
 		const sid = this.#providerSessionId ?? sessionId ?? this.sessionManager.getSessionId();
 		this.agent.sessionId = sid;
+		this.agent.providerSessionId = this.#providerCacheSessionId ?? sid;
 		this.agent.setMetadataResolver((provider: string) =>
 			buildSessionMetadata(sid, provider, this.#modelRegistry.authStorage),
 		);
@@ -4092,18 +4274,19 @@ export class AgentSession {
 		const details = message.details;
 		if (!details || typeof details !== "object") return;
 		const name = (details as { name?: unknown }).name;
-		if (typeof name !== "string" || !isCanonicalGjcWorkflowSkill(name)) return;
-		const cwd = this.sessionManager.getCwd();
+		if (typeof name !== "string" || !name.trim()) return;
+		const skill = name.trim();
 		const sessionId = this.sessionManager.getSessionId();
-		await syncSkillActiveState({
-			cwd,
-			skill: name,
-			active,
-			phase: active ? "running" : "complete",
-			sessionId,
-			source: "skill-prompt",
-		});
-		this.#activeSkillState = active ? { skill: name, sessionId } : undefined;
+		// Canonical GJC workflow skills (deep-interview, ralplan, ultragoal, team)
+		// own their `.gjc/state/skill-active-state.json` row through the
+		// `gjc state handoff` and `gjc state clear` runtime verbs. The prompt
+		// observer here used to overwrite the row with `phase: running` and
+		// later remove it with `active:false`, which clobbered handoff lineage
+		// (`handoff_from`/`handoff_at`) and made the HUD inconsistent with
+		// mode-state. The observational filesystem write is now skipped for
+		// canonical skills; the in-memory `#activeSkillState` tracking below
+		// keeps `getActiveSkillState` accurate for the chain guard.
+		this.#activeSkillState = active ? { skill, sessionId } : undefined;
 	}
 
 	async #syncSkillPromptActiveStateSafely(
@@ -6147,7 +6330,7 @@ export class AgentSession {
 
 	#closeCodexProviderSessionsForHistoryRewrite(): void {
 		const currentModel = this.model;
-		if (!currentModel || currentModel.api !== "openai-codex-responses") return;
+		if (currentModel?.api !== "openai-codex-responses") return;
 		this.#closeProviderSessionsForModelSwitch(currentModel, currentModel);
 	}
 
@@ -8228,7 +8411,7 @@ export class AgentSession {
 		const previousSessionFile = this.sessionFile;
 		const selectedEntry = this.sessionManager.getEntry(entryId);
 
-		if (!selectedEntry || selectedEntry.type !== "message" || selectedEntry.message.role !== "user") {
+		if (selectedEntry?.type !== "message" || selectedEntry.message.role !== "user") {
 			throw new Error("Invalid entry ID for branching");
 		}
 

package/src/session/session-manager.ts

@@ -176,6 +176,8 @@ export interface SessionInitEntry extends SessionEntryBase {
 	tools: string[];
 	/** Output schema if structured output was requested */
 	outputSchema?: unknown;
+	/** Fork-context seed metadata for subagent debugging/replay. */
+	forkContext?: unknown;
 }
 
 /** Mode change entry - tracks agent mode transitions (e.g. plan mode). */
@@ -2714,7 +2716,13 @@ export class SessionManager {
 	}
 
 	/** Append session init metadata (for subagent debugging/replay). Returns entry id. */
-	appendSessionInit(init: { systemPrompt: string; task: string; tools: string[]; outputSchema?: unknown }): string {
+	appendSessionInit(init: {
+		systemPrompt: string;
+		task: string;
+		tools: string[];
+		outputSchema?: unknown;
+		forkContext?: unknown;
+	}): string {
 		const entry: SessionInitEntry = {
 			type: "session_init",
 			id: generateId(this.#byId),

package/src/setup/model-onboarding-guidance.ts

@@ -1,5 +1,6 @@
 export const MODEL_ONBOARDING_API_PROVIDER_COMMAND =
 	"/provider add --compat <openai|anthropic> --provider <id> --base-url <url> --api-key-env <ENV> --model <model>";
+export const MODEL_ONBOARDING_PROVIDER_PRESET_COMMAND = "/provider add --preset <minimax|minimax-cn|glm>";
 
 export const MODEL_ONBOARDING_SETUP_COMMAND = "gjc setup provider";
 export const MODEL_ONBOARDING_OAUTH_COMMAND = "/provider login [provider-id] or /login [provider-id]";
@@ -9,14 +10,15 @@ export function formatModelOnboardingGuidance(): string {
 		"Model selection only shows configured providers.",
 		"Assignment targets are DEFAULT plus the GJC role agents: EXECUTOR, ARCHITECT, PLANNER, and CRITIC.",
 		"Legacy model-role aliases are compatibility-only and are not shown as assignment targets.",
-		`API-compatible providers: ${MODEL_ONBOARDING_API_PROVIDER_COMMAND} (or ${MODEL_ONBOARDING_SETUP_COMMAND}).`,
+		`Provider presets: ${MODEL_ONBOARDING_PROVIDER_PRESET_COMMAND} (or ${MODEL_ONBOARDING_SETUP_COMMAND} --preset <preset>).`,
+		`API-compatible custom providers: ${MODEL_ONBOARDING_API_PROVIDER_COMMAND}.`,
 		`OAuth/subscription providers: ${MODEL_ONBOARDING_OAUTH_COMMAND}.`,
 		"Then run /model to select a configured model or assign it to a target.",
 	].join("\n");
 }
 
 export function formatModelOnboardingInlineHint(): string {
-	return `Add API-compatible providers with ${MODEL_ONBOARDING_API_PROVIDER_COMMAND} (or ${MODEL_ONBOARDING_SETUP_COMMAND}); OAuth/subscription with ${MODEL_ONBOARDING_OAUTH_COMMAND}; then run /model for DEFAULT, EXECUTOR, ARCHITECT, PLANNER, and CRITIC.`;
+	return `Add MiniMax/GLM presets with ${MODEL_ONBOARDING_PROVIDER_PRESET_COMMAND}; custom API providers with ${MODEL_ONBOARDING_API_PROVIDER_COMMAND} (or ${MODEL_ONBOARDING_SETUP_COMMAND}); OAuth/subscription with ${MODEL_ONBOARDING_OAUTH_COMMAND}; then run /model for DEFAULT, EXECUTOR, ARCHITECT, PLANNER, and CRITIC.`;
 }
 
 export function formatNoModelOnboardingError(): string {
@@ -27,7 +29,8 @@ export function formatNoCredentialOnboardingError(providerId: string): string {
 	return [
 		`No credentials found for ${providerId}.`,
 		"",
-		`For API-compatible providers, configure credentials with ${MODEL_ONBOARDING_API_PROVIDER_COMMAND} (or ${MODEL_ONBOARDING_SETUP_COMMAND}).`,
+		`For MiniMax/GLM presets, configure credentials with ${MODEL_ONBOARDING_PROVIDER_PRESET_COMMAND} (or ${MODEL_ONBOARDING_SETUP_COMMAND} --preset <preset>).`,
+		`For custom API-compatible providers, use ${MODEL_ONBOARDING_API_PROVIDER_COMMAND}.`,
 		`For OAuth/subscription providers, use ${MODEL_ONBOARDING_OAUTH_COMMAND}.`,
 		"Then run /model to select a configured model or assign it to DEFAULT, EXECUTOR, ARCHITECT, PLANNER, or CRITIC.",
 	].join("\n");