feat: add model roles for small, implementer, and advisor

.changeset/model-roles.md

@@ -0,0 +1,5 @@
+---
+"@pythoughts/pythinker-code": minor
+---
+
+Add model roles: lock a model alias to the small, implementer, or advisor slot with `/model <role>`, list assignments with `/model roles`, and reference roles as `@small`, `@implementer`, or `@advisor` wherever a subagent model can be set; an assigned implementer role becomes the default model for subagents.

apps/pythinker-code/src/tui/commands/config.ts

@@ -41,7 +41,11 @@ import {
   openFileInExternalEditor,
   resolveEditorCommand,
 } from '#/utils/process/external-editor';
-import { LLM_NOT_SET_MESSAGE, NO_ACTIVE_SESSION_MESSAGE } from '../constant/pythinker-tui';
+import {
+  BUILT_IN_MODEL_ROLES,
+  LLM_NOT_SET_MESSAGE,
+  NO_ACTIVE_SESSION_MESSAGE,
+} from '#/tui/constant/pythinker-tui';
 import { formatErrorMessage } from '../utils/event-payload';
 import { showUsage } from './info';
 import { setExperimentalFeatures } from './experimental-flags';
@@ -480,6 +484,41 @@ function resolveWorkspaceConfigPath(input: string, workDir: string): string {
 
 export async function handleModelCommand(host: SlashCommandHost, args: string): Promise<void> {
   const requestedAlias = args.trim();
+  const tokens = requestedAlias.split(/\s+/u).filter(Boolean);
+  const config = await host.harness.getConfig({ reload: true });
+  const roles = [...new Set([...BUILT_IN_MODEL_ROLES, ...Object.keys(config.modelRoles ?? {})])]
+    .filter((role) => role.length > 0 && role !== 'default');
+
+  if (tokens.length === 1 && tokens[0] === 'roles') {
+    host.showNotice(
+      'Model roles',
+      roles
+        .map((role) => `${role}: ${config.modelRoles?.[role]?.trim() || '(not set)'}`)
+        .join('\n'),
+    );
+    return;
+  }
+
+  const role = tokens[0];
+  if (role !== undefined && roles.includes(role)) {
+    if (tokens.length === 2 && (tokens[1] === 'clear' || tokens[1] === 'none')) {
+      await host.harness.setConfig({ modelRoles: { [role]: '' } });
+      host.showStatus(`Cleared the ${role} model role.`, 'success');
+      return;
+    }
+    if (tokens.length === 1) {
+      const picker = showModelPicker(host, config.modelRoles?.[role], undefined, {
+        assignToRole: role,
+      });
+      if (picker !== undefined) {
+        void refreshModelsForOpenPicker(host, picker, config.modelRoles?.[role], {
+          assignToRole: role,
+        });
+      }
+      return;
+    }
+  }
+
   const normalized = normalizeModelChoices(host.state.appState.availableModels);
   const selectedValue =
     requestedAlias.length === 0
@@ -524,6 +563,7 @@ async function refreshModelsForOpenPicker(
   host: SlashCommandHost,
   picker: TabbedModelSelectorComponent,
   selectedValue: string | undefined,
+  options?: { assignToRole?: string },
 ): Promise<void> {
   const availableModels = host.state.appState.availableModels;
   const normalized = normalizeModelChoices(availableModels);
@@ -574,7 +614,7 @@ async function refreshModelsForOpenPicker(
     }
   }
 
-  showModelPicker(host, refreshedSelected, activeTabId);
+  showModelPicker(host, refreshedSelected, activeTabId, options);
 }
 
 async function applyEditorChoice(host: SlashCommandHost, value: string): Promise<void> {
@@ -615,6 +655,7 @@ export function showModelPicker(
   host: SlashCommandHost,
   selectedValue?: string,
   initialTabId?: string,
+  options?: { assignToRole?: string },
 ): TabbedModelSelectorComponent | undefined {
   const normalized = normalizeModelChoices(host.state.appState.availableModels);
   const entries = Object.entries(normalized.models);
@@ -646,6 +687,10 @@ export function showModelPicker(
     initialTabId,
     onSelect: ({ alias, effort }) => {
       host.restoreEditor();
+      if (options?.assignToRole !== undefined) {
+        void assignModelRole(host, options.assignToRole, alias);
+        return;
+      }
       void performModelSwitch(host, alias, effort);
     },
     onCancel: () => {
@@ -656,6 +701,17 @@ export function showModelPicker(
   return picker;
 }
 
+async function assignModelRole(host: SlashCommandHost, role: string, alias: string): Promise<void> {
+  // Model roles store aliases only; thinking effort stays with the active model.
+  try {
+    await host.harness.setConfig({ modelRoles: { [role]: alias } });
+  } catch (error) {
+    host.showError(`Failed to lock the ${role} model: ${formatErrorMessage(error)}`);
+    return;
+  }
+  host.showStatus(`Locked ${alias} as the ${role} model.`, 'success');
+}
+
 async function performModelSwitch(host: SlashCommandHost, alias: string, effort: string): Promise<void> {
   if (host.state.appState.streamingPhase !== 'idle') {
     host.showError('Cannot switch models while streaming — press Esc or Ctrl-C first.');

apps/pythinker-code/src/tui/commands/registry.ts

@@ -164,7 +164,7 @@ export const BUILTIN_SLASH_COMMANDS = [
   {
     name: 'model',
     aliases: [],
-    description: 'Switch LLM model',
+    description: 'Switch model; assign with /model <role>, clear it, or list /model roles',
     priority: 100,
     availability: 'always',
   },

apps/pythinker-code/src/tui/constant/pythinker-tui.ts

@@ -1,5 +1,8 @@
 export { OAUTH_LOGIN_REQUIRED_CODE, PRODUCT_NAME } from '#/constant/app';
 
+/** Canonical model roles offered by `/model <role>`, mirroring agent-core's list across the SDK package boundary. */
+export const BUILT_IN_MODEL_ROLES = ['small', 'implementer', 'advisor'] as const;
+
 export const LLM_NOT_SET_MESSAGE = 'LLM not set, send "/login" to login';
 export const NO_ACTIVE_SESSION_MESSAGE = 'No active session. Send /login to login.';
 export const CTRL_D_HINT = 'Press Ctrl+D again to exit';
@@ -8,4 +11,3 @@ export const MAIN_AGENT_ID = 'main';
 export const OAUTH_LOGIN_REQUIRED_STARTUP_NOTICE = 'OAuth login expired. Send /login to login.';
 export const EXIT_CONFIRM_WINDOW_MS = 1500;
 export const MCP_STATUS_TRANSIENT_DURATION_MS = 750;
-

apps/pythinker-code/test/tui/commands/model-roles.test.ts

@@ -0,0 +1,161 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { handleModelCommand } from '#/tui/commands/index';
+import type { SlashCommandHost } from '#/tui/commands/dispatch';
+
+const ENTER = '\r';
+
+interface TestPicker {
+  handleInput(data: string): void;
+}
+
+function model(name: string) {
+  return {
+    provider: 'test',
+    model: name,
+    maxContextSize: 200_000,
+    displayName: name,
+    capabilities: [],
+  };
+}
+
+function makeHost(options: {
+  currentModel?: string;
+  availableModels?: Record<string, ReturnType<typeof model>>;
+  modelRoles?: Record<string, string>;
+  setConfig?: ReturnType<typeof vi.fn>;
+} = {}) {
+  const session = {
+    setModel: vi.fn(async () => {}),
+    setThinking: vi.fn(async () => {}),
+  };
+  const getConfig = vi.fn(async () => ({
+    providers: {},
+    modelRoles: options.modelRoles,
+  }));
+  const setConfig = options.setConfig ?? vi.fn(async () => {});
+  const host = {
+    state: {
+      appState: {
+        model: options.currentModel ?? 'worker',
+        thinkingLevel: 'off',
+        streamingPhase: 'idle',
+        availableModels: options.availableModels ?? { worker: model('worker') },
+      },
+      editorContainer: { children: [] },
+    },
+    session,
+    harness: { getConfig, setConfig },
+    authFlow: {
+      refreshProviderModels: vi.fn(async () => ({ failed: [] })),
+    },
+    setAppState: vi.fn((patch: Record<string, unknown>) => Object.assign(host.state.appState, patch)),
+    showError: vi.fn(),
+    showStatus: vi.fn(),
+    showNotice: vi.fn(),
+    mountEditorReplacement: vi.fn(),
+    restoreEditor: vi.fn(),
+    track: vi.fn(),
+  } as unknown as SlashCommandHost;
+  return { host, session, setConfig };
+}
+
+function mountedPicker(host: SlashCommandHost, index = 0): TestPicker {
+  const mount = host.mountEditorReplacement as ReturnType<typeof vi.fn>;
+  return mount.mock.calls[index]?.[0] as TestPicker;
+}
+
+describe('/model roles', () => {
+  it('lists every built-in role as not set when no assignments exist', async () => {
+    const { host } = makeHost();
+
+    await handleModelCommand(host, 'roles');
+
+    expect(host.showNotice).toHaveBeenCalledWith(
+      'Model roles',
+      'small: (not set)\nimplementer: (not set)\nadvisor: (not set)',
+    );
+  });
+
+  it('locks a selected alias to a role without switching the session model', async () => {
+    const { host, session, setConfig } = makeHost();
+
+    await handleModelCommand(host, 'small');
+    expect(host.authFlow.refreshProviderModels).toHaveBeenCalledOnce();
+    mountedPicker(host).handleInput(ENTER);
+
+    await vi.waitFor(() => {
+      expect(setConfig).toHaveBeenCalledWith({ modelRoles: { small: 'worker' } });
+    });
+    expect(session.setModel).not.toHaveBeenCalled();
+  });
+
+  it('keeps role assignment active after the picker refreshes', async () => {
+    const { host, session, setConfig } = makeHost({
+      currentModel: 'parent',
+      availableModels: {
+        parent: model('parent'),
+        worker: model('worker'),
+      },
+      modelRoles: { small: 'worker' },
+    });
+    vi.mocked(host.mountEditorReplacement).mockImplementation((picker) => {
+      host.state.editorContainer.children[0] = picker;
+    });
+    vi.mocked(host.authFlow.refreshProviderModels).mockImplementation(async () => {
+      host.state.appState.availableModels['reviewer'] = model('reviewer');
+      return { changed: [], unchanged: [], failed: [] };
+    });
+
+    await handleModelCommand(host, 'small');
+    await vi.waitFor(() => {
+      expect(host.mountEditorReplacement).toHaveBeenCalledTimes(2);
+    });
+    mountedPicker(host, 1).handleInput(ENTER);
+
+    await vi.waitFor(() => {
+      expect(setConfig).toHaveBeenCalledWith({ modelRoles: { small: 'worker' } });
+    });
+    expect(session.setModel).not.toHaveBeenCalled();
+  });
+
+  it('reports a role persistence failure without showing success', async () => {
+    const setConfig = vi.fn(async () => {
+      throw new Error('disk full');
+    });
+    const { host } = makeHost({ setConfig });
+
+    await handleModelCommand(host, 'small');
+    mountedPicker(host).handleInput(ENTER);
+
+    await vi.waitFor(() => {
+      expect(host.showError).toHaveBeenCalledWith(expect.stringContaining('disk full'));
+    });
+    expect(host.showStatus).not.toHaveBeenCalled();
+  });
+
+  it('clears a role with an empty-string tombstone', async () => {
+    const { host, setConfig } = makeHost({ modelRoles: { small: 'worker' } });
+
+    await handleModelCommand(host, 'small clear');
+
+    expect(setConfig).toHaveBeenCalledWith({ modelRoles: { small: '' } });
+  });
+
+  it('keeps an existing model alias on the default switch path', async () => {
+    const { host, session } = makeHost({
+      currentModel: 'parent',
+      availableModels: {
+        parent: model('parent'),
+        worker: model('worker'),
+      },
+    });
+
+    await handleModelCommand(host, 'worker');
+    mountedPicker(host).handleInput(ENTER);
+
+    await vi.waitFor(() => {
+      expect(session.setModel).toHaveBeenCalledWith('worker');
+    });
+  });
+});

docs/configuration/config-files.md

@@ -76,6 +76,7 @@ Fields in the config file fall into two categories: **top-level scalars** that d
 | Field | Type | Default | Description |
 | --- | --- | --- | --- |
 | `default_model` | `string` | — | Default model alias; must be defined in `models` |
+| `model_roles` | `table` | — | Model role assignments → [`model_roles`](#model_roles) |
 | `default_thinking` | `boolean` | `false` | Whether new sessions enable Thinking (deep reasoning) mode by default; can be toggled from the model menu inside a session. Even when set to `true`, `[thinking].mode = "off"` will still force Thinking off |
 | `default_permission_mode` | `string` | `manual` | Default permission mode for new sessions; one of `manual` (prompt each time), `yolo` (auto-approve tool actions, but the agent may still ask questions), or `auto` (fully autonomous — the agent decides everything without asking, except a `DynamicWorkflow` call, which still shows its plan for approval) |
 | `default_plan_mode` | `boolean` | `false` | Whether new sessions start in Plan mode (produce a plan before executing) by default |
@@ -94,7 +95,7 @@ Fields in the config file fall into two categories: **top-level scalars** that d
 | `permission` | `table` | — | Initial permission rules → [`permission`](#permission) |
 | `hooks` | `array<table>` | — | Lifecycle hooks; see [Hooks](../customization/hooks.md) |
 
-The following sections cover each of the nested tables in turn: `providers`, `models`, `thinking`, `loop_control`, `background`, `experimental`, `services`, and `permission`.
+The following sections cover each of the nested tables in turn: `providers`, `models`, `model_roles`, `thinking`, `loop_control`, `background`, `experimental`, `services`, and `permission`.
 
 ## `providers`
 
@@ -155,6 +156,24 @@ max_context_size = 1047576
 
 You can also switch models temporarily without touching the config file — by setting `PYTHINKER_MODEL_*` environment variables, the CLI synthesizes a temporary provider in memory that does not persist after restart. See [Define a model from environment variables](./env-vars.md#define-a-model-from-environment-variables-pythinker_model).
 
+## `model_roles`
+
+Each entry in the `model_roles` table locks a model alias to a named role. The built-in roles are `small`, `implementer`, and `advisor`; any other key except the reserved `default` defines a custom role. Values must be aliases defined in `models`; an empty string clears the role.
+
+```toml
+[model_roles]
+small = "haiku"
+implementer = "worker-model"
+advisor = "reviewer-model"
+```
+
+Roles take effect in two places:
+
+- Wherever a subagent model alias is accepted (the `Agent` and `DynamicWorkflow` tool `model` arguments, and agent profile frontmatter), a `@<role>` reference such as `@small` resolves to the locked alias. An unassigned or unresolvable role falls back to the parent agent's model.
+- When `implementer` is assigned, it becomes the default model for subagents that do not set an explicit or profile model. Subagents of those subagents inherit the same default.
+
+Inside the TUI, `/model <role>` assigns a role from the model picker, `/model <role> clear` (or `/model <role> none`) removes it, and `/model roles` lists the current assignments. See [Slash commands](../reference/slash-commands.md).
+
 ## `thinking`
 
 `thinking` sets the global default behavior for Thinking mode. `mode = "off"` forces Thinking off even when the top-level `default_thinking = true`.

docs/reference/slash-commands.md

@@ -15,7 +15,7 @@ Some commands are only available in the idle state. Executing these commands whi
 | `/login` | — | Select an account or platform and log in: Pythinker Code uses OAuth device-code flow; Pythinker Platform uses API key login | No |
 | `/logout` | — | Clear credentials for the currently selected account | No |
 | `/provider` | — | Open the interactive provider manager to view, add, and remove configured providers. See [Platforms & Models — `/provider` and provider management](../configuration/providers.md#provider-interactive-provider-management) | Yes |
-| `/model` | — | Switch the LLM model used in the current session | Yes |
+| `/model` | — | Switch the LLM model used in the current session. `/model <role>` locks a model alias to a model role (`small`, `implementer`, or `advisor`), `/model <role> clear` (or `/model <role> none`) removes the lock, and `/model roles` lists the current assignments. See [Model roles](../configuration/config-files.md#model_roles) | Yes |
 | `/settings` | `/config` | Open the settings panel inside the TUI | Yes |
 | `/experiments` | `/experimental` | Open the experimental feature panel | Yes |
 | `/permission` | — | Select a permission mode | Yes |

packages/agent-core/src/config/index.ts

@@ -1,4 +1,5 @@
 export * from './merge';
+export * from './model-roles';
 export * from './path';
 export * from './resolve';
 export * from './schema';

packages/agent-core/src/config/model-roles.ts

@@ -0,0 +1,26 @@
+/** Built-in model roles a user can lock a model alias to. */
+export const BUILT_IN_MODEL_ROLES = ['small', 'implementer', 'advisor'] as const;
+export type BuiltInModelRole = (typeof BUILT_IN_MODEL_ROLES)[number];
+
+interface ModelRoleSource {
+  modelRoles?: Record<string, string>;
+  defaultModel?: string;
+}
+
+/** Resolve a role name to its locked model alias. Empty string means cleared. */
+export function resolveModelRoleAlias(
+  config: ModelRoleSource | undefined,
+  role: string,
+): string | undefined {
+  if (role === 'default') return config?.defaultModel;
+  const alias = config?.modelRoles?.[role]?.trim();
+  return alias === '' ? undefined : alias;
+}
+
+/** Expand a "@role" model reference; non-@ strings pass through unchanged. */
+export function expandModelRef(
+  config: ModelRoleSource | undefined,
+  ref: string,
+): string | undefined {
+  return ref.startsWith('@') ? resolveModelRoleAlias(config, ref.slice(1)) : ref;
+}