@gajae-code/coding-agent 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## [Unreleased]
 
+## [0.3.2] - 2026-06-05
+
+### Added
+
+- Added model profiles with a `--mpreset <profile>` CLI flag and a `/model` selector "Profiles" section that activate a named profile's default model plus per-agent-role model overrides in one step, validating required-provider credentials before applying and surfacing a custom provider onboarding wizard for missing API-compatible providers.
+- Integrated `ai-slop-cleaner` as an internal Ultragoal sub-skill fragment that runs as the mandatory completion-gate cleanup sweep over a story's changed files, reporting blocking and advisory findings without editing code or mutating `.gjc/` state.
+
+### Fixed
+
+- Reconciled native Ultragoal commands with workflow mode-state and the HUD: `gjc ultragoal create-goals`, `complete-goals`, `checkpoint`, steering, review-blocker recording, and status now sync `.gjc/state/ultragoal-state.json` plus `skill-active-state.json` from the durable `.gjc/ultragoal` plan/ledger, clearing stale active HUD chips after all goals complete.
+- Forwarded the parent session id when task subagents validate configured role-agent model overrides, preventing session-scoped OAuth providers from being misread as unauthenticated and falling back to the parent chat model.
+- Removed unintended public memory-tool guidance and registration: Hindsight retain/recall/reflect helpers are now compatibility-only, local memory prompt injection no longer advertises `memory://` reads, and regression tests guard the public tool surface.
+- Fixed `read` hashline anchors drifting on truncated reads so the `line+hash` anchors consumed by `edit`/`apply_patch` stay correct when a file is read past the truncation boundary.
+
 ## [0.3.1] - 2026-06-05
 ### Added
 

package/README.md

@@ -17,7 +17,7 @@ The agent supports three mutually-exclusive memory backends, selected via the `m
 
 - `off` (default) — no memory subsystem runs.
 - `local` — existing rollout-summarisation pipeline; writes `memory_summary.md` and consolidated artifacts under the agent dir.
-- `hindsight` — talks to a [Hindsight](https://hindsight.vectorize.io) server (Cloud or self-hosted Docker), retains transcripts every Nth user turn, recalls memories on the first turn of a session, and exposes `retain`, `recall`, and `reflect`.
+- `hindsight` — talks to a [Hindsight](https://hindsight.vectorize.io) server (Cloud or self-hosted Docker). Hindsight uses private backend lifecycle hooks to retain transcripts and recall context; compatibility-only internals remain for legacy backend calls, but GJC does not expose public coding-harness memory tools such as `retain`, `recall`, or `reflect`.
 
 ### Hindsight quickstart
 

package/dist/types/cli/args.d.ts

@@ -11,6 +11,8 @@ export interface Args {
     smol?: string;
     slow?: string;
     plan?: string;
+    mpreset?: string;
+    default?: boolean;
     apiKey?: string;
     systemPrompt?: string;
     appendSystemPrompt?: string;

package/dist/types/commands/launch.d.ts

@@ -25,6 +25,12 @@ export default class Index extends Command {
         plan: import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
             description: string;
         };
+        mpreset: import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+        };
+        default: import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+        };
         provider: import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
             description: string;
         };

package/dist/types/config/model-profile-activation.d.ts

@@ -0,0 +1,30 @@
+import type { ThinkingLevel } from "@gajae-code/agent-core";
+import type { Api, Model } from "@gajae-code/ai";
+import type { AgentSession } from "../session/agent-session";
+import { type ModelRegistry } from "./model-registry";
+import type { Settings } from "./settings";
+export interface PrepareModelProfileActivationOptions {
+    session: Pick<AgentSession, "model" | "thinkingLevel" | "sessionId">;
+    modelRegistry: Pick<ModelRegistry, "getModelProfile" | "getModelProfiles" | "getAvailableModelProfileNames" | "getApiKeyForProvider" | "getAll" | "resolveCanonicalModel" | "getCanonicalVariants" | "getCanonicalId">;
+    settings: Pick<Settings, "get">;
+    profileName: string;
+}
+export interface PreparedModelProfileActivation {
+    profileName: string;
+    session: Pick<AgentSession, "model" | "thinkingLevel" | "sessionId" | "setModelTemporary">;
+    settings: Pick<Settings, "get" | "override" | "set" | "flush">;
+    previousModel: Model<Api> | undefined;
+    previousThinkingLevel: ThinkingLevel | undefined;
+    previousAgentModelOverrides: Record<string, string>;
+    defaultModel: Model<Api> | undefined;
+    defaultThinkingLevel: ThinkingLevel | undefined;
+    agentModelOverrides: Record<string, string>;
+}
+export declare function formatModelProfileCredentialError(profileName: string, providers: readonly string[]): string;
+export declare function prepareModelProfileActivation(options: PrepareModelProfileActivationOptions): Promise<PreparedModelProfileActivation>;
+export declare function applyPreparedModelProfileActivation(prepared: PreparedModelProfileActivation, options?: {
+    persistDefault?: boolean;
+}): Promise<void>;
+export declare function activateModelProfile(options: PrepareModelProfileActivationOptions, applyOptions?: {
+    persistDefault?: boolean;
+}): Promise<void>;

package/dist/types/config/model-profiles.d.ts

@@ -0,0 +1,19 @@
+import type { GjcModelAssignmentTargetId } from "./model-registry";
+import type { ModelsConfig } from "./models-config-schema";
+export type ModelProfileRole = GjcModelAssignmentTargetId;
+export interface ModelProfileDefinition {
+    name: string;
+    requiredProviders: string[];
+    modelMapping: Partial<Record<ModelProfileRole, string>>;
+    source: "builtin" | "user";
+}
+export interface ResolvedProfileBinding {
+    defaultSelector?: string;
+    agentModelOverrides: Partial<Record<Exclude<ModelProfileRole, "default">, string>>;
+}
+export declare function deriveModelProfileMappedProviders(definition: Pick<ModelProfileDefinition, "modelMapping">): string[];
+export declare function aggregateModelProfileRequiredProviders(requiredProviders: readonly string[], definition: Pick<ModelProfileDefinition, "modelMapping">): string[];
+export declare const BUILTIN_MODEL_PROFILES: readonly ModelProfileDefinition[];
+export declare function mergeModelProfiles(userProfiles?: ModelsConfig["profiles"]): Map<string, ModelProfileDefinition>;
+export declare function resolveProfileBindings(definition: ModelProfileDefinition): ResolvedProfileBinding;
+export declare function formatAvailableProfileNames(profiles: ReadonlyMap<string, ModelProfileDefinition>): string;

package/dist/types/config/model-registry.d.ts

@@ -4,6 +4,7 @@ import { type ThemeColor } from "../modes/theme/theme";
 import type { AuthStorage } from "../session/auth-storage";
 import { type ConfigError, ConfigFile } from "./config-file";
 import { type CanonicalModelIndex, type CanonicalModelRecord, type CanonicalModelVariant, type ModelEquivalenceConfig } from "./model-equivalence";
+import { type ModelProfileDefinition } from "./model-profiles";
 import { type Settings } from "./settings";
 export type { CanonicalModelIndex, CanonicalModelRecord, CanonicalModelVariant, ModelEquivalenceConfig };
 export declare const kNoAuth = "N/A";
@@ -244,6 +245,10 @@ export declare const ModelsConfigFile: ConfigFile<{
         overrides?: Record<string, string> | undefined;
         exclude?: string[] | undefined;
     } | undefined;
+    profiles?: Record<string, {
+        required_providers: string[];
+        model_mapping: Partial<Record<"architect" | "critic" | "default" | "executor" | "planner", string>>;
+    }> | undefined;
 }>;
 /** Provider override config (baseUrl, headers, apiKey, compat, transport) without custom models */
 interface ProviderOverride {
@@ -306,6 +311,9 @@ export declare class ModelRegistry {
      * Get any error from loading models.json (undefined if no error).
      */
     getError(): ConfigError | undefined;
+    getModelProfiles(): Map<string, ModelProfileDefinition>;
+    getModelProfile(name: string): ModelProfileDefinition | undefined;
+    getAvailableModelProfileNames(): string[];
     applyConfiguredModelBindings(targetSettings: Settings): void;
     /**
      * Get all models (built-in + custom).

package/dist/types/config/model-resolver.d.ts

@@ -128,7 +128,7 @@ export declare function resolveModelOverride(modelPatterns: string[], modelRegis
  * primary resolution unchanged so the existing error path still surfaces
  * a meaningful failure downstream.
  */
-export declare function resolveModelOverrideWithAuthFallback(modelPatterns: string[], parentActiveModelPattern: string | undefined, modelRegistry: ModelLookupRegistry & Pick<ModelRegistry, "getApiKey">, settings?: Settings): Promise<{
+export declare function resolveModelOverrideWithAuthFallback(modelPatterns: string[], parentActiveModelPattern: string | undefined, modelRegistry: ModelLookupRegistry & Pick<ModelRegistry, "getApiKey">, settings?: Settings, sessionId?: string): Promise<{
     model?: Model<Api>;
     thinkingLevel?: ThinkingLevel;
     explicitThinkingLevel: boolean;

package/dist/types/config/models-config-schema.d.ts

@@ -53,6 +53,41 @@ export declare const OpenAICompatSchema: z.ZodObject<{
         none: "none";
     }>>;
 }, z.core.$strip>;
+export declare const ProfileRoleSchema: z.ZodEnum<{
+    architect: "architect";
+    critic: "critic";
+    default: "default";
+    executor: "executor";
+    planner: "planner";
+}>;
+export declare const ProfileModelSelectorSchema: z.ZodString;
+export declare const ProfileModelMappingSchema: z.ZodRecord<z.ZodEnum<{
+    architect: "architect";
+    critic: "critic";
+    default: "default";
+    executor: "executor";
+    planner: "planner";
+}> & z.core.$partial, z.ZodString>;
+export declare const ProfileDefinitionSchema: z.ZodObject<{
+    required_providers: z.ZodArray<z.ZodString>;
+    model_mapping: z.ZodRecord<z.ZodEnum<{
+        architect: "architect";
+        critic: "critic";
+        default: "default";
+        executor: "executor";
+        planner: "planner";
+    }> & z.core.$partial, z.ZodString>;
+}, z.core.$strict>;
+export declare const ProfilesSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    required_providers: z.ZodArray<z.ZodString>;
+    model_mapping: z.ZodRecord<z.ZodEnum<{
+        architect: "architect";
+        critic: "critic";
+        default: "default";
+        executor: "executor";
+        planner: "planner";
+    }> & z.core.$partial, z.ZodString>;
+}, z.core.$strict>>;
 export declare const ModelOverrideSchema: z.ZodObject<{
     name: z.ZodOptional<z.ZodString>;
     reasoning: z.ZodOptional<z.ZodBoolean>;
@@ -547,5 +582,17 @@ export declare const ModelsConfigSchema: z.ZodObject<{
         overrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>;
+    profiles: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        required_providers: z.ZodArray<z.ZodString>;
+        model_mapping: z.ZodRecord<z.ZodEnum<{
+            architect: "architect";
+            critic: "critic";
+            default: "default";
+            executor: "executor";
+            planner: "planner";
+        }> & z.core.$partial, z.ZodString>;
+    }, z.core.$strict>>>;
 }, z.core.$strict>;
 export type ModelsConfig = z.infer<typeof ModelsConfigSchema>;
+export type ModelProfileConfig = z.infer<typeof ProfileDefinitionSchema>;
+export type ModelProfilesConfig = z.infer<typeof ProfilesSchema>;

package/dist/types/config/settings-schema.d.ts

@@ -189,6 +189,16 @@ export declare const SETTINGS_SCHEMA: {
         readonly type: "record";
         readonly default: Record<string, string>;
     };
+    readonly "modelProfile.default": {
+        readonly type: "string";
+        readonly default: undefined;
+        readonly ui: {
+            readonly tab: "model";
+            readonly label: "Default Model Profile";
+            readonly description: "Model profile applied automatically at startup";
+            readonly options: "runtime";
+        };
+    };
     readonly modelTags: {
         readonly type: "record";
         readonly default: ModelTagsSettings;

package/dist/types/gjc-runtime/ultragoal-runtime.d.ts

@@ -1,4 +1,4 @@
-import type { WorkflowHudSummary } from "../skill-state/active-state";
+import { type WorkflowHudSummary } from "../skill-state/active-state";
 export type UltragoalGjcGoalMode = "aggregate" | "per-story";
 export type UltragoalGoalStatus = "pending" | "active" | "complete" | "failed" | "blocked" | "review_blocked" | "superseded";
 export interface UltragoalGoal {
@@ -94,6 +94,7 @@ export declare function computeUltragoalPlanGeneration(input: {
 export declare function readUltragoalPlan(cwd: string): Promise<UltragoalPlan | null>;
 export declare function getUltragoalStatus(cwd: string): Promise<UltragoalStatusSummary>;
 export declare function buildUltragoalHudSummary(summary: UltragoalStatusSummary, latestLedger?: UltragoalLedgerEvent): WorkflowHudSummary;
+export declare function syncUltragoalWorkflowState(cwd: string): Promise<void>;
 export declare function createUltragoalPlan(input: {
     cwd: string;
     brief: string;

package/dist/types/main.d.ts

@@ -24,10 +24,19 @@ export interface AcpSessionFactoryOptions {
     sessionDir?: string;
     authStorage: AuthStorage;
     modelRegistry: ModelRegistry;
-    parsedArgs: Pick<Args, "apiKey">;
+    parsedArgs: Pick<Args, "apiKey" | "default" | "model" | "mpreset" | "thinking">;
     rawArgs: string[];
     createSession: (options: CreateAgentSessionOptions) => Promise<CreateAgentSessionResult>;
 }
+export declare function applyStartupModelProfiles(args: {
+    session: AgentSession;
+    settings: Settings;
+    modelRegistry: ModelRegistry;
+    parsedArgs: Pick<Args, "default" | "model" | "mpreset" | "thinking">;
+    startupModel?: CreateAgentSessionOptions["model"];
+    startupThinkingLevel?: CreateAgentSessionOptions["thinkingLevel"];
+}): Promise<void>;
+export declare function applyStartupModelProfilesOrExit(args: Parameters<typeof applyStartupModelProfiles>[0]): Promise<void>;
 /**
  * Build the per-`session/new` factory used by ACP mode.
  *

package/dist/types/modes/components/custom-provider-wizard.d.ts

@@ -0,0 +1,10 @@
+import { Container } from "@gajae-code/tui";
+import type { ProviderSetupInput } from "../../setup/provider-onboarding";
+export type CustomProviderCredentialSource = "env" | "literal";
+export type CustomProviderWizardSubmit = ProviderSetupInput;
+export declare class CustomProviderWizardComponent extends Container {
+    #private;
+    constructor(onSubmit: (input: CustomProviderWizardSubmit) => void, onCancel: () => void, onRender?: () => void);
+    setSubmitError(error: string): void;
+    handleInput(keyData: string): void;
+}

package/dist/types/modes/components/model-selector.d.ts

@@ -23,8 +23,12 @@ export type ModelSelectorSelection = {
     selector: string;
     preset: ModelAssignmentPreset;
     assignments: Record<GjcModelAssignmentTargetId, ThinkingLevel>;
+} | {
+    kind: "profile";
+    profileName: string;
+    setDefault: boolean;
 };
-type RoleSelectCallback = (selection: ModelSelectorSelection) => void;
+type RoleSelectCallback = (selection: ModelSelectorSelection) => void | Promise<void>;
 /**
  * Component that renders a canonical model selector with provider tabs.
  * - Tab/Arrow Left/Right: Switch between provider tabs
@@ -40,5 +44,6 @@ export declare class ModelSelectorComponent extends Container {
     });
     handleInput(keyData: string): void;
     getSearchInput(): Input;
+    __testSelectProfile(profileName: string, setDefault: boolean): Promise<void>;
 }
 export {};

package/dist/types/modes/components/provider-onboarding-selector.d.ts

@@ -1,5 +1,5 @@
 import { Container } from "@gajae-code/tui";
-export type ProviderOnboardingAction = "oauth-login" | "api-guide";
+export type ProviderOnboardingAction = "custom-provider-wizard" | "oauth-login" | "api-guide";
 export declare class ProviderOnboardingSelectorComponent extends Container {
     #private;
     constructor(onSelect: (action: ProviderOnboardingAction) => void, onCancel: () => void);

package/dist/types/modes/controllers/selector-controller.d.ts

@@ -15,6 +15,7 @@ export declare class SelectorController {
         focus: Component;
     }): void;
     showProviderOnboarding(): void;
+    showCustomProviderWizard(): void;
     showSettingsSelector(): void;
     showThemeSelector(): void;
     showHistorySearch(): void;

package/dist/types/modes/types.d.ts

@@ -123,6 +123,7 @@ export interface InteractiveModeContext {
     }): void;
     showError(message: string): void;
     showWarning(message: string): void;
+    notifyConfigChanged?: () => Promise<void> | void;
     showNewVersionNotification(newVersion: string): void;
     clearEditor(): void;
     updatePendingMessagesDisplay(): void;

package/dist/types/sdk.d.ts

@@ -95,7 +95,7 @@ export interface CreateAgentSessionOptions {
     taskDepth?: number;
     /** Current role-agent type/name for nested task sessions. */
     currentAgentType?: string;
-    /** Parent Hindsight state to alias for subagent memory tools. */
+    /** Parent Hindsight state to alias for subagent private memory backend compatibility. */
     parentHindsightSessionState?: HindsightSessionState;
     /** Pre-allocated agent identity for IRC routing. Default: "0-Main" for top-level, parentTaskPrefix-derived for sub. */
     agentId?: string;

package/dist/types/task/executor.d.ts

@@ -37,6 +37,7 @@ export interface ExecutorOptions {
      * if the resolved subagent model has no working credentials. See #985.
      */
     parentActiveModelPattern?: string;
+    parentSessionId?: string;
     thinkingLevel?: ThinkingLevel;
     outputSchema?: unknown;
     /** Parent task recursion depth (0 = top-level, 1 = first child, etc.) */

package/dist/types/tools/hindsight-recall.d.ts

@@ -14,8 +14,6 @@ export declare class HindsightRecallTool implements AgentTool<typeof hindsightRe
         query: z.ZodString;
     }, z.core.$strip>;
     readonly strict = true;
-    readonly loadMode = "discoverable";
-    readonly summary = "Search hindsight memory for relevant prior context";
     constructor(session: ToolSession);
     static createIf(session: ToolSession): HindsightRecallTool | null;
     execute(_id: string, params: HindsightRecallParams, signal?: AbortSignal): Promise<AgentToolResult>;

package/dist/types/tools/hindsight-reflect.d.ts

@@ -16,8 +16,6 @@ export declare class HindsightReflectTool implements AgentTool<typeof hindsightR
         context: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     readonly strict = true;
-    readonly loadMode = "discoverable";
-    readonly summary = "Reflect on recent work and write hindsight memory";
     constructor(session: ToolSession);
     static createIf(session: ToolSession): HindsightReflectTool | null;
     execute(_id: string, params: HindsightReflectParams, signal?: AbortSignal): Promise<AgentToolResult>;

package/dist/types/tools/hindsight-retain.d.ts

@@ -20,8 +20,6 @@ export declare class HindsightRetainTool implements AgentTool<typeof hindsightRe
         }, z.core.$strip>>;
     }, z.core.$strip>;
     readonly strict = true;
-    readonly loadMode = "discoverable";
-    readonly summary = "Store important facts in hindsight memory";
     constructor(session: ToolSession);
     static createIf(session: ToolSession): HindsightRetainTool | null;
     execute(_id: string, params: HindsightRetainParams): Promise<AgentToolResult>;

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

@@ -37,9 +37,6 @@ export * from "./debug";
 export * from "./eval";
 export * from "./find";
 export * from "./gh";
-export * from "./hindsight-recall";
-export * from "./hindsight-reflect";
-export * from "./hindsight-retain";
 export * from "./image-gen";
 export * from "./inspect-image";
 export * from "./irc";
@@ -245,7 +242,10 @@ export declare const DEFAULT_ESSENTIAL_TOOL_NAMES: readonly string[];
 export declare function computeEssentialBuiltinNames(settings: Settings): string[];
 /**
  * Public callable factory map. External callers may invoke `BUILTIN_TOOLS.read(session)` or
- * `BUILTIN_TOOLS[name](session)` to construct a tool directly.
+ * `BUILTIN_TOOLS[name](session)` to construct a public coding-harness tool directly.
+ *
+ * Hindsight memory helpers are intentionally excluded: memory is a private backend
+ * integration, not a public gajae-code tool surface.
  */
 export declare const BUILTIN_TOOLS: Record<string, ToolFactory>;
 export declare const HIDDEN_TOOLS: Record<string, ToolFactory>;

package/package.json

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

package/src/cli/args.ts

@@ -17,6 +17,8 @@ export interface Args {
 	smol?: string;
 	slow?: string;
 	plan?: string;
+	mpreset?: string;
+	default?: boolean;
 	apiKey?: string;
 	systemPrompt?: string;
 	appendSystemPrompt?: string;
@@ -127,6 +129,10 @@ export function parseArgs(args: string[]): Args {
 			result.slow = args[++i];
 		} else if (arg === "--plan" && i + 1 < args.length) {
 			result.plan = args[++i];
+		} else if (arg === "--mpreset" && i + 1 < args.length) {
+			result.mpreset = args[++i];
+		} else if (arg === "--default") {
+			result.default = true;
 		} else if (arg === "--api-key" && i + 1 < args.length) {
 			result.apiKey = args[++i];
 		} else if (arg === "--system-prompt" && i + 1 < args.length) {
@@ -199,6 +205,10 @@ export function parseArgs(args: string[]): Args {
 		}
 	}
 
+	if (result.default && !result.mpreset) {
+		throw new Error("--default requires --mpreset <name>");
+	}
+
 	return result;
 }
 

package/src/commands/launch.ts

@@ -36,6 +36,12 @@ export default class Index extends Command {
 		plan: Flags.string({
 			description: "Plan model for architectural planning (or GJC_PLAN_MODEL env)",
 		}),
+		mpreset: Flags.string({
+			description: "Model profile preset to activate for this session",
+		}),
+		default: Flags.boolean({
+			description: "Persist --mpreset as the default model profile",
+		}),
 		provider: Flags.string({
 			description: "Provider to use (legacy; prefer --model)",
 		}),
@@ -136,6 +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`,
 		`# Export a session file to HTML\n  ${APP_NAME} --export ~/.gjc/agent/sessions/--path--/session.jsonl`,
 	];
 

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

@@ -0,0 +1,157 @@
+import type { ThinkingLevel } from "@gajae-code/agent-core";
+import type { Api, Model } from "@gajae-code/ai";
+import type { AgentSession } from "../session/agent-session";
+import {
+	aggregateModelProfileRequiredProviders,
+	formatAvailableProfileNames,
+	resolveProfileBindings,
+} from "./model-profiles";
+import { type GjcModelAssignmentTargetId, isAuthenticated, type ModelRegistry } from "./model-registry";
+import { resolveModelRoleValue } from "./model-resolver";
+import type { Settings } from "./settings";
+
+export interface PrepareModelProfileActivationOptions {
+	session: Pick<AgentSession, "model" | "thinkingLevel" | "sessionId">;
+	modelRegistry: Pick<
+		ModelRegistry,
+		| "getModelProfile"
+		| "getModelProfiles"
+		| "getAvailableModelProfileNames"
+		| "getApiKeyForProvider"
+		| "getAll"
+		| "resolveCanonicalModel"
+		| "getCanonicalVariants"
+		| "getCanonicalId"
+	>;
+	settings: Pick<Settings, "get">;
+	profileName: string;
+}
+
+export interface PreparedModelProfileActivation {
+	profileName: string;
+	session: Pick<AgentSession, "model" | "thinkingLevel" | "sessionId" | "setModelTemporary">;
+	settings: Pick<Settings, "get" | "override" | "set" | "flush">;
+	previousModel: Model<Api> | undefined;
+	previousThinkingLevel: ThinkingLevel | undefined;
+	previousAgentModelOverrides: Record<string, string>;
+	defaultModel: Model<Api> | undefined;
+	defaultThinkingLevel: ThinkingLevel | undefined;
+	agentModelOverrides: Record<string, string>;
+}
+
+export function formatModelProfileCredentialError(profileName: string, providers: readonly string[]): string {
+	return `Model profile "${profileName}" requires credentials for: ${providers.join(", ")}. Run /login and configure the missing provider(s), then retry.`;
+}
+
+export async function prepareModelProfileActivation(
+	options: PrepareModelProfileActivationOptions,
+): Promise<PreparedModelProfileActivation> {
+	const profile = options.modelRegistry.getModelProfile(options.profileName);
+	if (!profile) {
+		const available = formatAvailableProfileNames(options.modelRegistry.getModelProfiles());
+		throw new Error(`Unknown model profile "${options.profileName}". Available profiles: ${available}`);
+	}
+
+	const missingProviders: string[] = [];
+	for (const provider of aggregateModelProfileRequiredProviders(profile.requiredProviders, profile)) {
+		const apiKey = await options.modelRegistry.getApiKeyForProvider(provider, options.session.sessionId);
+		if (!isAuthenticated(apiKey)) {
+			missingProviders.push(provider);
+		}
+	}
+	if (missingProviders.length > 0) {
+		throw new Error(formatModelProfileCredentialError(options.profileName, missingProviders));
+	}
+
+	const availableModels = options.modelRegistry.getAll();
+	const bindings = resolveProfileBindings(profile);
+	const resolvedDefault = bindings.defaultSelector
+		? resolveModelRoleValue(bindings.defaultSelector, availableModels, {
+				settings: options.settings as Settings,
+				modelRegistry: options.modelRegistry,
+			})
+		: undefined;
+	if (bindings.defaultSelector && !resolvedDefault?.model) {
+		throw new Error(
+			`Model profile "${options.profileName}" default selector did not resolve: ${bindings.defaultSelector}`,
+		);
+	}
+
+	const agentModelOverrides: Record<string, string> = {};
+	for (const [role, selector] of Object.entries(bindings.agentModelOverrides) as [
+		GjcModelAssignmentTargetId,
+		string,
+	][]) {
+		const resolved = resolveModelRoleValue(selector, availableModels, {
+			settings: options.settings as Settings,
+			modelRegistry: options.modelRegistry,
+		});
+		if (!resolved.model) {
+			throw new Error(`Model profile "${options.profileName}" ${role} selector did not resolve: ${selector}`);
+		}
+		agentModelOverrides[role] = selector;
+	}
+
+	return {
+		profileName: options.profileName,
+		session: options.session as PreparedModelProfileActivation["session"],
+		settings: options.settings as PreparedModelProfileActivation["settings"],
+		previousModel: options.session.model,
+		previousThinkingLevel: options.session.thinkingLevel,
+		previousAgentModelOverrides: { ...options.settings.get("task.agentModelOverrides") },
+		defaultModel: resolvedDefault?.model,
+		defaultThinkingLevel: resolvedDefault?.thinkingLevel,
+		agentModelOverrides,
+	};
+}
+
+export async function applyPreparedModelProfileActivation(
+	prepared: PreparedModelProfileActivation,
+	options: { persistDefault?: boolean } = {},
+): Promise<void> {
+	const previousModel = prepared.previousModel;
+	const previousThinkingLevel = prepared.previousThinkingLevel;
+	const previousAgentModelOverrides = prepared.previousAgentModelOverrides;
+	const previousPersistedDefault = prepared.settings.get("modelProfile.default");
+	let modelChanged = false;
+	let overridesChanged = false;
+	let defaultChanged = false;
+
+	try {
+		if (prepared.defaultModel) {
+			await prepared.session.setModelTemporary(prepared.defaultModel, prepared.defaultThinkingLevel);
+			modelChanged = true;
+		}
+		if (Object.keys(prepared.agentModelOverrides).length > 0) {
+			prepared.settings.override("task.agentModelOverrides", {
+				...prepared.settings.get("task.agentModelOverrides"),
+				...prepared.agentModelOverrides,
+			});
+			overridesChanged = true;
+		}
+		if (options.persistDefault) {
+			prepared.settings.set("modelProfile.default", prepared.profileName);
+			defaultChanged = true;
+			await prepared.settings.flush();
+		}
+	} catch (error) {
+		if (defaultChanged) {
+			prepared.settings.set("modelProfile.default", previousPersistedDefault);
+		}
+		if (overridesChanged) {
+			prepared.settings.override("task.agentModelOverrides", previousAgentModelOverrides);
+		}
+		if (modelChanged && previousModel) {
+			await prepared.session.setModelTemporary(previousModel, previousThinkingLevel);
+		}
+		throw error;
+	}
+}
+
+export async function activateModelProfile(
+	options: PrepareModelProfileActivationOptions,
+	applyOptions: { persistDefault?: boolean } = {},
+): Promise<void> {
+	const prepared = await prepareModelProfileActivation(options);
+	await applyPreparedModelProfileActivation(prepared, applyOptions);
+}