@saadnvd1/agent-os 0.3.470 → 0.3.472

package/lib/models/plan-step.ts

@@ -0,0 +1,94 @@
+/**
+ * A task's plan step: its first turn runs on the planning model and writes
+ * the implementation plan to a file in the worktree; when that turn ends,
+ * the same conversation switches to the implementation model (Claude Code
+ * keeps the transcript across a model change, and a resume takes a new
+ * model) and is told to follow the plan.
+ */
+
+import fs from "fs";
+import path from "path";
+import { db, type Session } from "../db";
+import { enqueue } from "../chat/queued";
+import { applySessionModel } from "./session-model";
+import {
+  resolveRole,
+  sessionWorkspace,
+  setSessionModel,
+  taskOverride,
+} from "./resolve";
+import { ANTHROPIC } from "./roles";
+
+export const PLAN_FILE = ".agentos/plan.md";
+
+export function planPrompt(task: string): string {
+  return `${task}
+
+---
+Plan first. This turn, only read and plan: write the implementation plan for the task above to \`${PLAN_FILE}\` in this worktree (what to change, file by file; the tests; how you'll verify it; anything ambiguous and the call you'd make). Change no other file, and don't commit, push or open a PR. End the turn once the plan is written: the implementation model takes over this conversation next and follows it.`;
+}
+
+export function implementPrompt(planned: boolean): string {
+  return planned
+    ? `The plan is in \`${PLAN_FILE}\`. Implement it now, finishing the task as its instructions above say. Where the plan turns out wrong, do what's right and say so.`
+    : `No plan was written to \`${PLAN_FILE}\`. Plan briefly, then implement the task, finishing it as its instructions above say.`;
+}
+
+// The worktree's plan folder, kept out of git by its own .gitignore.
+export function preparePlanDir(worktree: string): void {
+  const dir = path.join(worktree, path.dirname(PLAN_FILE));
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, ".gitignore"), "*\n");
+}
+
+export const implementMessageId = (sessionId: string) =>
+  `implement-${sessionId}`;
+
+// Called when a chat goes idle. A task whose plan turn has ended (it has a
+// recorded plan turn) moves to implementing, once, and the implementation
+// message is queued under a fixed id, which a restart sends rather than
+// repeats.
+export async function handoffAfterPlan(
+  sessionId: string,
+  send: (sessionId: string, id: string) => Promise<void>
+): Promise<boolean> {
+  const planned = db
+    .prepare(
+      `SELECT 1 FROM chat_turns WHERE session_id = ? AND role = 'plan' LIMIT 1`
+    )
+    .get(sessionId);
+  if (!planned) return false;
+  const s = db.prepare(`SELECT * FROM sessions WHERE id = ?`).get(sessionId) as
+    | Session
+    | undefined;
+  if (s?.plan_phase !== "planning" || !s.worktree_path) return false;
+  const routed = resolveRole("implement", {
+    workspaceId: sessionWorkspace(s),
+    override: taskOverride(s),
+  });
+  const id = implementMessageId(sessionId);
+  // The phase, the model and the message in one go: a restart part-way
+  // finds either none of them or all, and sends the message on the new model.
+  const claimed = db.transaction(() => {
+    const changed = db
+      .prepare(
+        `UPDATE sessions SET plan_phase = 'implementing'
+         WHERE id = ? AND plan_phase = 'planning' AND task_status = 'running'`
+      )
+      .run(sessionId).changes;
+    if (!changed) return false;
+    setSessionModel(sessionId, routed);
+    enqueue(sessionId, {
+      id,
+      text: implementPrompt(
+        fs.existsSync(path.join(s.worktree_path!, PLAN_FILE))
+      ),
+      origin: { kind: "decision", label: "Plan step" },
+    });
+    return true;
+  })();
+  if (!claimed) return false;
+  await applySessionModel(sessionId, s.model_provider ?? ANTHROPIC, routed);
+  await send(sessionId, id);
+  return true;
+}

package/lib/models/providers.ts

@@ -0,0 +1,163 @@
+/**
+ * Where a model runs. A provider is config: Anthropic through the Claude
+ * login (no key), or an Anthropic- or OpenAI-compatible endpoint with a base
+ * URL, a reference to its key and its model names. The key itself is never
+ * here: only where to fetch it from at launch (lib/models/secrets).
+ * Imported by the browser too, so no Node modules here.
+ */
+
+import { ANTHROPIC } from "./roles";
+
+// Where a provider's key lives. Never the key.
+export type SecretRef =
+  | { kind: "tokenvault"; project: string; desc?: string }
+  | { kind: "keychain"; service: string; account?: string }
+  | { kind: "env"; name: string };
+
+export type ProviderApi = "anthropic" | "openai";
+
+export interface ModelTiers {
+  opus?: string;
+  sonnet?: string;
+  haiku?: string;
+}
+
+export interface ModelProvider {
+  id: string;
+  label: string;
+  api: ProviderApi;
+  // Absent for Anthropic itself, which uses the Claude login.
+  baseUrl?: string;
+  auth?: SecretRef;
+  // How the key is sent: Authorization: Bearer, or x-api-key.
+  authHeader?: "bearer" | "x-api-key";
+  models: string[];
+  // Claude Code's tiers mapped to this provider's models, so subagents and
+  // background work (which ask for "haiku" or "sonnet") route here too.
+  tiers?: ModelTiers;
+  // Plain settings the endpoint wants (a longer timeout, say). Never a key.
+  env?: Record<string, string>;
+  enabled: boolean;
+}
+
+export interface ModelPrice {
+  input: number;
+  cacheWrite: number;
+  cacheRead: number;
+  output: number;
+}
+
+export const ANTHROPIC_PROVIDER: ModelProvider = {
+  id: ANTHROPIC,
+  label: "Anthropic (Claude login)",
+  api: "anthropic",
+  models: [
+    "claude-opus-5-5",
+    "claude-sonnet-5-5",
+    "claude-haiku-4-5-20251001",
+    "claude-fable-5-1",
+  ],
+  enabled: true,
+};
+
+// Checked against each provider's docs on 2026-10-11: DeepSeek
+// (api-docs.deepseek.com/guides/anthropic_api) and Z.ai
+// (docs.z.ai/devpack/tool/claude). Off until a key reference is set.
+export const PROVIDER_PRESETS: ModelProvider[] = [
+  ANTHROPIC_PROVIDER,
+  {
+    id: "deepseek",
+    label: "DeepSeek",
+    api: "anthropic",
+    baseUrl: "https://api.deepseek.com/anthropic",
+    authHeader: "x-api-key",
+    models: ["deepseek-v4-pro", "deepseek-flash"],
+    tiers: {
+      opus: "deepseek-v4-pro",
+      sonnet: "deepseek-flash",
+      haiku: "deepseek-flash",
+    },
+    enabled: false,
+  },
+  {
+    id: "zai",
+    label: "Z.ai (GLM)",
+    api: "anthropic",
+    baseUrl: "https://api.z.ai/api/anthropic",
+    authHeader: "bearer",
+    models: ["glm-5.3", "glm-5.3-flash"],
+    tiers: { opus: "glm-5.3", sonnet: "glm-5.3", haiku: "glm-5.3-flash" },
+    env: { API_TIMEOUT_MS: "3000000" },
+    enabled: false,
+  },
+];
+
+// Dollars per million tokens, from each provider's price page on
+// 2026-10-11. DeepSeek and GLM have no cache-write price (a write costs
+// what input does), and DeepSeek's are its peak prices.
+export const DEFAULT_PRICES: Record<string, ModelPrice> = {
+  "anthropic/claude-opus-5-5": {
+    input: 4,
+    cacheWrite: 5,
+    cacheRead: 0.2,
+    output: 20,
+  },
+  "anthropic/claude-sonnet-5-5": {
+    input: 2,
+    cacheWrite: 2.5,
+    cacheRead: 0.1,
+    output: 10,
+  },
+  "anthropic/claude-haiku-4-5-20251001": {
+    input: 1,
+    cacheWrite: 1.25,
+    cacheRead: 0.1,
+    output: 5,
+  },
+  "anthropic/claude-fable-5-1": {
+    input: 10,
+    cacheWrite: 12.5,
+    cacheRead: 0.25,
+    output: 50,
+  },
+  "deepseek/deepseek-v4-pro": {
+    input: 1.32,
+    cacheWrite: 1.32,
+    cacheRead: 0.044,
+    output: 3.96,
+  },
+  "deepseek/deepseek-flash": {
+    input: 0.3,
+    cacheWrite: 0.3,
+    cacheRead: 0.006,
+    output: 1.2,
+  },
+  "zai/glm-5.3": { input: 1.4, cacheWrite: 1.4, cacheRead: 0.26, output: 4.4 },
+  "zai/glm-5.3-flash": {
+    input: 0.15,
+    cacheWrite: 0.15,
+    cacheRead: 0.03,
+    output: 0.5,
+  },
+};
+
+// Claude Code's family aliases, priced as the model each stands for.
+export const ANTHROPIC_ALIASES: Record<string, string> = {
+  opus: "claude-opus-5-5",
+  sonnet: "claude-sonnet-5-5",
+  haiku: "claude-haiku-4-5-20251001",
+  fable: "claude-fable-5-1",
+};
+
+// Anthropic is billed by the plan, not per token: a turn there costs a share
+// of the plan's window, and its dollars are what the API would have charged.
+export const isMetered = (providerId: string) => providerId !== ANTHROPIC;
+
+export function describeSecretRef(ref: SecretRef | undefined): string {
+  if (!ref) return "no key";
+  if (ref.kind === "tokenvault")
+    return `tokenvault ${ref.project}${ref.desc ? ` "${ref.desc}"` : ""}`;
+  if (ref.kind === "keychain")
+    return `Keychain ${ref.service}${ref.account ? ` (${ref.account})` : ""}`;
+  return `$${ref.name}`;
+}

package/lib/models/resolve.ts

@@ -0,0 +1,246 @@
+/**
+ * Which model a piece of work runs on, and what its agent needs to reach
+ * it. The most specific setting wins: the task's own override, then its
+ * workspace's, then Settings, then AGENTOS_REVIEW_MODEL or
+ * AGENTOS_TITLE_MODEL, then the default (lib/models/roles).
+ */
+
+import { db, type Session } from "../db";
+import { getProject } from "../projects";
+import {
+  effectiveModels,
+  roleMapSchema,
+  savedModelSettings,
+  workspaceModels,
+  type EffectiveModels,
+  type RoleMap,
+} from "./config";
+import { ANTHROPIC_PROVIDER, type ModelProvider } from "./providers";
+import {
+  ANTHROPIC,
+  DEFAULT_ROLE_MODELS,
+  GATE_ROLES,
+  formatModelRef,
+  isModelRole,
+  parseModelRef,
+  sessionRole,
+  type ModelRole,
+} from "./roles";
+import {
+  resolveSecret,
+  secretShellExpansion,
+  type SecretCommand,
+} from "./secrets";
+
+export type RoleSource = "task" | "workspace" | "settings" | "env" | "default";
+
+// The server's own environment can still stand in for a role's default:
+// what AgentOS read before model routing existed.
+const ENV_ROLE_MODELS: Partial<Record<ModelRole, string>> = {
+  review: "AGENTOS_REVIEW_MODEL",
+  scope: "AGENTOS_REVIEW_MODEL",
+  helper: "AGENTOS_TITLE_MODEL",
+};
+
+const envModel = (role: ModelRole): string | undefined => {
+  const name = ENV_ROLE_MODELS[role];
+  return (name && process.env[name]?.trim()) || undefined;
+};
+
+export interface RoutedModel {
+  role: ModelRole;
+  ref: string;
+  provider: ModelProvider;
+  model: string;
+  source: RoleSource;
+}
+
+// A task's override: one model for all its roles, or a model per role.
+export type ModelOverride = string | RoleMap;
+
+export function parseOverride(value: unknown): ModelOverride | null {
+  if (value == null || value === "") return null;
+  if (typeof value === "string") {
+    const ref = value.trim();
+    providerFor(parseModelRef(ref).provider);
+    return ref.includes("/") ? ref : formatModelRef(parseModelRef(ref));
+  }
+  const got = roleMapSchema.safeParse(value);
+  const gate = got.success && GATE_ROLES.find((r) => got.data[r]);
+  if (gate)
+    throw new Error(
+      `model: a task can't pick its own ${gate} model; set it in Settings or the workspace`
+    );
+  if (!got.success)
+    throw new Error(
+      `model: give "provider/model", or a map of role to "provider/model"`
+    );
+  for (const ref of Object.values(got.data))
+    if (ref) providerFor(parseModelRef(ref).provider);
+  return Object.keys(got.data).length ? got.data : null;
+}
+
+const overrideFor = (o: ModelOverride | null | undefined, role: ModelRole) =>
+  GATE_ROLES.includes(role) ? undefined : typeof o === "string" ? o : o?.[role];
+
+// The provider by id, or throws why it can't be used.
+export function providerFor(
+  id: string,
+  models: EffectiveModels = effectiveModels()
+): ModelProvider {
+  if (id === ANTHROPIC) return ANTHROPIC_PROVIDER;
+  const p = models.providers.find((x) => x.id === id);
+  if (!p) throw new Error(`No model provider "${id}" (Settings > Models)`);
+  if (!p.enabled) throw new Error(`The ${p.label} provider is turned off`);
+  if (!p.baseUrl || !p.auth)
+    throw new Error(`The ${p.label} provider needs a base URL and a key`);
+  if (p.api !== "anthropic")
+    throw new Error(
+      `${p.label} speaks the OpenAI API; Claude Code needs an Anthropic-compatible endpoint`
+    );
+  return p;
+}
+
+export function resolveRole(
+  role: ModelRole,
+  opts: { workspaceId?: string | null; override?: ModelOverride | null } = {},
+  models: EffectiveModels = effectiveModels()
+): RoutedModel {
+  const task = overrideFor(opts.override, role);
+  const ws = opts.workspaceId
+    ? workspaceModels(opts.workspaceId).roles?.[role]
+    : undefined;
+  const saved = models.roles[role];
+  // The variable stands in only where Settings names nothing for the role.
+  const env =
+    saved === DEFAULT_ROLE_MODELS[role] && !savedModelSettings().roles?.[role]
+      ? envModel(role)
+      : undefined;
+  const [ref, source]: [string, RoleSource] = task
+    ? [task, "task"]
+    : ws
+      ? [ws, "workspace"]
+      : saved !== DEFAULT_ROLE_MODELS[role]
+        ? [saved, "settings"]
+        : env
+          ? [env, "env"]
+          : [saved, "default"];
+  const parsed = parseModelRef(ref);
+  return {
+    role,
+    ref: formatModelRef(parsed),
+    provider: providerFor(parsed.provider, models),
+    model: parsed.model,
+    source,
+  };
+}
+
+// The role's built-in model on the Claude login: what work falls back to
+// when the provider it's routed to can't be used.
+export function defaultRoute(role: ModelRole): RoutedModel {
+  const parsed = parseModelRef(DEFAULT_ROLE_MODELS[role]);
+  return {
+    role,
+    ref: formatModelRef(parsed),
+    provider: ANTHROPIC_PROVIDER,
+    model: parsed.model,
+    source: "default",
+  };
+}
+
+export function resolveRoleOrDefault(
+  role: ModelRole,
+  opts: { workspaceId?: string | null } = {}
+): RoutedModel {
+  try {
+    return resolveRole(role, opts);
+  } catch {
+    return defaultRoute(role);
+  }
+}
+
+// A session's workspace: an orchestrator's own, or its project's.
+export function sessionWorkspace(
+  session: Pick<Session, "workspace_id" | "project_id">
+): string | null {
+  if (session.workspace_id) return session.workspace_id;
+  return session.project_id
+    ? (getProject(session.project_id)?.workspace_id ?? null)
+    : null;
+}
+
+export function taskOverride(
+  session: Pick<Session, "model_overrides">
+): ModelOverride | null {
+  if (!session.model_overrides) return null;
+  try {
+    return parseOverride(JSON.parse(session.model_overrides));
+  } catch {
+    return null;
+  }
+}
+
+// What the agent's environment needs beyond the model name, with the key
+// fetched now. Nothing for Anthropic: the Claude login is the default.
+export async function providerEnv(
+  provider: ModelProvider,
+  model: string,
+  exec?: SecretCommand
+): Promise<Record<string, string>> {
+  if (provider.id === ANTHROPIC) return {};
+  const key = await resolveSecret(provider.auth!, exec);
+  return { ...routingEnv(provider, model), [authVar(provider)]: key };
+}
+
+// The same for a terminal launch: the plain settings, and shell text that
+// sets the key from its reference inside the agent's shell.
+export function providerShellEnv(
+  provider: ModelProvider,
+  model: string
+): { env: Record<string, string>; exportKey: string } {
+  if (provider.id === ANTHROPIC) return { env: {}, exportKey: "" };
+  return {
+    env: routingEnv(provider, model),
+    exportKey: `export ${authVar(provider)}=${secretShellExpansion(provider.auth!)};`,
+  };
+}
+
+const authVar = (p: ModelProvider) =>
+  p.authHeader === "x-api-key" ? "ANTHROPIC_API_KEY" : "ANTHROPIC_AUTH_TOKEN";
+
+// The endpoint, Claude Code's tiers mapped to its models (so subagents and
+// background calls asking for "haiku" stay on it), and the other key
+// variable emptied so a key in AgentOS's own environment isn't sent there.
+function routingEnv(p: ModelProvider, model: string): Record<string, string> {
+  const other =
+    authVar(p) === "ANTHROPIC_API_KEY"
+      ? "ANTHROPIC_AUTH_TOKEN"
+      : "ANTHROPIC_API_KEY";
+  return {
+    ...p.env,
+    ANTHROPIC_BASE_URL: p.baseUrl!,
+    [other]: "",
+    ANTHROPIC_DEFAULT_OPUS_MODEL: p.tiers?.opus ?? model,
+    ANTHROPIC_DEFAULT_SONNET_MODEL: p.tiers?.sonnet ?? model,
+    ANTHROPIC_DEFAULT_HAIKU_MODEL: p.tiers?.haiku ?? model,
+    CLAUDE_CODE_SUBAGENT_MODEL: p.tiers?.sonnet ?? model,
+  };
+}
+
+// Records what a session runs on: the model its CLI is given, and its
+// provider (NULL for Anthropic).
+export function setSessionModel(sessionId: string, routed: RoutedModel): void {
+  db.prepare(
+    `UPDATE sessions SET model = ?, model_provider = ? WHERE id = ?`
+  ).run(
+    routed.model,
+    routed.provider.id === ANTHROPIC ? null : routed.provider.id,
+    sessionId
+  );
+}
+
+export const sessionModelRef = (
+  s: Pick<Session, "model" | "model_provider">
+): string => `${s.model_provider ?? ANTHROPIC}/${s.model}`;
+
+export { isModelRole, sessionRole };

package/lib/models/resume.ts

@@ -0,0 +1,99 @@
+/**
+ * Resuming a task on another model: its conversation and worktree carry on,
+ * only the model (and maybe the provider) under it changes. The choice is
+ * kept as the task's own override, so later turns and restarts stay on it.
+ */
+
+import { db, type Session } from "../db";
+import { chatState, sendChat } from "../chat/runner";
+import { launchPending } from "../tasks/launch-gate";
+import { killTmux } from "../tasks/start";
+import { launchClaude } from "../agents/launch";
+import { switchSessionModel } from "./session-model";
+import {
+  parseOverride,
+  resolveRole,
+  sessionWorkspace,
+  setSessionModel,
+  taskOverride,
+  type ModelOverride,
+} from "./resolve";
+import { sessionRole } from "./roles";
+
+export const RESUME_MESSAGE =
+  "You were paused. Carry on where you left off: check the worktree and the conversation above for where things stand, then finish the task.";
+
+// A per-role map adds to the one it has; one model replaces it.
+export function mergeOverride(
+  before: ModelOverride | null,
+  next: ModelOverride
+): ModelOverride {
+  if (typeof next === "string" || !before) return next;
+  if (typeof before === "string") return next;
+  return { ...before, ...next };
+}
+
+export interface ResumeResult {
+  ref: string;
+  // Whether a message went to its agent now: a task still setting up, or
+  // held, starts on the new model by itself.
+  resumed: boolean;
+}
+
+export async function resumeOnModel(
+  sessionId: string,
+  model: unknown,
+  message = RESUME_MESSAGE
+): Promise<ResumeResult> {
+  const s = db.prepare(`SELECT * FROM sessions WHERE id = ?`).get(sessionId) as
+    | Session
+    | undefined;
+  if (!s?.task_status) throw new Error("No such task");
+  if (s.task_status !== "running")
+    throw new Error(
+      `That task is ${s.task_status}; only a running one resumes`
+    );
+  const next = parseOverride(model);
+  if (!next) throw new Error("Pick a model");
+  const override = mergeOverride(taskOverride(s), next);
+  const routed = resolveRole(sessionRole(s), {
+    workspaceId: sessionWorkspace(s),
+    override,
+  });
+  const state = s.view === "chat" ? chatState(sessionId) : null;
+  if (state === "running" || state === "waiting")
+    throw new Error(
+      "It's mid-turn: stop it first, or wait for the turn to end"
+    );
+  db.prepare(`UPDATE sessions SET model_overrides = ? WHERE id = ?`).run(
+    JSON.stringify(override),
+    sessionId
+  );
+  if (launchPending(sessionId)) {
+    setSessionModel(sessionId, routed);
+    return { ref: routed.ref, resumed: false };
+  }
+  if (s.view === "chat") {
+    await switchSessionModel(sessionId, routed);
+    await sendChat(sessionId, {
+      text: message,
+      origin: { kind: "decision", label: `Resumed on ${routed.ref}` },
+    });
+    return { ref: routed.ref, resumed: true };
+  }
+  if (!s.claude_session_id || !s.worktree_path)
+    throw new Error("Its terminal conversation can't be resumed");
+  setSessionModel(sessionId, routed);
+  await killTmux(s.tmux_name);
+  await launchClaude({
+    sessionId,
+    tmuxName: s.tmux_name,
+    cwd: s.worktree_path,
+    model: routed.model,
+    provider: routed.provider.id === "anthropic" ? null : routed.provider.id,
+    prompt: message,
+    brief: s.task_brief ?? undefined,
+    resume: s.claude_session_id,
+  });
+  return { ref: routed.ref, resumed: true };
+}

package/lib/models/roles.ts

@@ -0,0 +1,98 @@
+/**
+ * The kinds of work AgentOS launches agents for, and the model each runs on
+ * unless Settings, a workspace or the task says otherwise. A model is named
+ * by a reference, "provider/model": the provider is one of lib/models/
+ * providers, and the model is that provider's own id. Imported by the
+ * browser too, so no Node modules here.
+ */
+
+export const MODEL_ROLES = [
+  "plan",
+  "implement",
+  "orchestrator",
+  "review",
+  "scope",
+  "interactive",
+  "helper",
+] as const;
+
+export type ModelRole = (typeof MODEL_ROLES)[number];
+
+export const ROLE_LABELS: Record<ModelRole, { label: string; hint: string }> = {
+  plan: {
+    label: "Task planning",
+    hint: "A task's plan step, written to a file before any code changes",
+  },
+  implement: {
+    label: "Task implementation",
+    hint: "A task's agent, following the plan in its worktree",
+  },
+  orchestrator: { label: "Orchestrator", hint: "A workspace's orchestrator" },
+  review: {
+    label: "Gate review",
+    hint: "The independent review a PR passes before it merges",
+  },
+  scope: { label: "Scope check", hint: "Whether a diff stays in its card" },
+  interactive: {
+    label: "Interactive sessions",
+    hint: "Sessions you start and talk to yourself",
+  },
+  helper: {
+    label: "Chat & summary helpers",
+    hint: "Titles, summaries and digests",
+  },
+};
+
+export const ANTHROPIC = "anthropic";
+const OPUS = `${ANTHROPIC}/claude-opus-5-5`;
+const SONNET = `${ANTHROPIC}/claude-sonnet-5-5`;
+const HAIKU = `${ANTHROPIC}/claude-haiku-4-5-20251001`;
+
+// Claude stays the default for every role: another provider is opt-in.
+export const DEFAULT_ROLE_MODELS: Record<ModelRole, string> = {
+  plan: OPUS,
+  review: OPUS,
+  implement: SONNET,
+  orchestrator: SONNET,
+  scope: SONNET,
+  interactive: OPUS,
+  helper: HAIKU,
+};
+
+// The roles that gate a task's merge: only Settings and its workspace pick
+// their model, never the task (or the orchestrator that started it), so
+// work can't choose its own reviewer.
+export const GATE_ROLES: readonly ModelRole[] = ["review", "scope"];
+export const TASK_ROLES = MODEL_ROLES.filter((r) => !GATE_ROLES.includes(r));
+
+export const isModelRole = (v: unknown): v is ModelRole =>
+  typeof v === "string" && (MODEL_ROLES as readonly string[]).includes(v);
+
+export interface ModelRef {
+  provider: string;
+  model: string;
+}
+
+// "provider/model", split at the first slash (a model id may hold more).
+// A bare model ("opus", "claude-sonnet-5-5") is Anthropic's.
+export function parseModelRef(ref: string): ModelRef {
+  const s = ref.trim();
+  const at = s.indexOf("/");
+  if (at <= 0) return { provider: ANTHROPIC, model: s };
+  return { provider: s.slice(0, at), model: s.slice(at + 1) };
+}
+
+export const formatModelRef = (r: ModelRef) => `${r.provider}/${r.model}`;
+
+export const REF_PATTERN = /^[a-z0-9][a-z0-9_-]*\/[\w.:@/-]+$/i;
+
+// The role a session's next turn runs as.
+export function sessionRole(session: {
+  role?: string | null;
+  task_status?: string | null;
+  plan_phase?: string | null;
+}): ModelRole {
+  if (session.role === "orchestrator") return "orchestrator";
+  if (!session.task_status) return "interactive";
+  return session.plan_phase === "planning" ? "plan" : "implement";
+}