A local-first multi-agent app development platform, built on PenguinHarness
/**
* Pure logic for the conversation-time thinking-level pickers (chat draft + active session).
*
* Two variants share these levels and labels, and both list only concrete levels — there is
* no "follow config" row anywhere:
* - Draft view: backed by the **Agent settings** (`system_config.model.thinking_level`) —
* shows the selected Agent's current level and writes a picked level straight through to
* the Agent config, so the session created on first send runs with it and it becomes the
* Agent's new default (switch-becomes-default).
* - Active session: the level is a **per-turn override**. The picker's displayed value
* initializes to the Agent config's level and auto-follows it while the user hasn't
* picked (internally the "" state remains as "untouched": tasks then omit the level, so
* the server/core fallback applies and config edits keep taking effect); an explicit pick
* sticks for the session and rides on every subsequent task as `thinkingLevel`, never
* writing through to the Agent config.
* Per review: the menus list the levels with short names only (no descriptions, no
* "default" row) under a title bar naming the control — and they do **not** offer "none"
* (many models cannot disable thinking): "none" stays a valid stored/wire value, so a
* legacy config or trace that carries it still displays via the label table below.
*
* The name comes in two variants, split by surface: `S.chat.thinkingLevelNames` is the plain
* tier name and belongs on anything DISPLAYING a settled level (trigger, tooltip, switch
* dialog, toasts, the Project read-only row), while `S.chat.thinkingLevelMenuName` composes
* the dropdown-row variant that also names the wire value being picked. Only zh actually
* differs between the two — an English name already is its wire value.
*/
/** All stored/wire levels, for display lookup (mirrors core's ThinkingLevelName). */
export const THINKING_LEVELS = ["none", "low", "medium", "high", "xhigh", "max"] as const;
/**
* The levels the picker offers, in menu order: "none" is deliberately excluded (many models
* don't support disabling thinking) — it can still be displayed (a stored legacy value) but
* never picked. "max" carries no such caveat: every AgentHub client maps it onto the deepest
* effort its vendor accepts and degrades silently where there is no such tier, so it is
* offered like any other tier.
*/
export const SELECTABLE_THINKING_LEVELS = ["low", "medium", "high", "xhigh", "max"] as const;
/**
* Effective thinking level for the draft picker's DISPLAY — the SAME chain core resolves
* when a Session is created (core/src/agent.ts `configuredThinkingLevel`, the single rule):
* the Agent's explicit `model.thinking_level` > the Project's `default_chat.thinking_level`
* > the built-in "medium". Keep the two sites in sync. `agentLevel` is the raw agent-config
* value ("" = no explicit override); `projectDefault` is `default_chat.thinking_level`
* (undefined when the Project sets none). The picker shows this effective value; picking
* still writes through to the AGENT config only — the project default is a fallback, never
* overwritten by the picker.
*/
export function effectiveThinkingLevel(
agentLevel: string,
projectDefault: string | undefined,
): string {
return agentLevel || (projectDefault ?? "medium");
}
/**
* Plain display label for a level from the localized name table (S.chat.thinkingLevelNames) —
* the variant for surfaces that show a level already chosen, so it carries no wire-value
* annotation; a dropdown row wraps this through `S.chat.thinkingLevelMenuName` instead.
* Covers every stored level including "none" (so a legacy value displays sanely instead
* of being rewritten or hidden). Returns null for anything else — including "" (an Agent
* without an explicit override) and session_meta's "default" — so callers can render a
* placeholder on the trigger and hide the session read-only tag instead of showing a raw
* internal value.
*/
export function thinkingLevelLabel(
names: Readonly<Record<string, string>>,
level: string | null | undefined,
): string | null {
return level && (THINKING_LEVELS as readonly string[]).includes(level)
? (names[level] ?? level)
: null;
}
/**
* The level the ACTIVE-SESSION picker displays, and the one its sends carry.
*
* `pinned` is the Session's own stored level (`SessionInfo.thinkingLevel`, written by the
* picker through PATCH — durable, so it survives a reload and a second tab); "" = never
* pinned, and the picker then auto-follows `agentLevel`, the Agent config's level, exactly
* as a brand-new session does. A pin wins from then on: later Agent-config edits no longer
* move a session whose level the user chose explicitly.
*/
export function sessionThinkingLevel(pinned: string, agentLevel: string): string {
return pinned || agentLevel;
}
/** One dropdown row of the agent-settings thinking-level menu (shape of OptionMenuChoice<string>). */
export interface ThinkingLevelOptionRow {
value: string;
/** Compact text on the trigger button. */
triggerLabel: string;
/** Panel row title. */
label: string;
/** Panel row description. */
description: string;
}
/**
* Assembles the agent-settings thinking-level dropdown rows from the dictionary's
* [value, description] pairs, composing both review decisions:
* - the "" (inherit) row is **filtered** — the menu offers only concrete tiers, the user
* picks explicitly; an unset value shows the OptionMenu's (default) placeholder and the
* reset link next to the menu rewinds a local pick back to it;
* - `none` is no longer offered (many models cannot disable thinking) but stays a valid
* stored value: when the **persisted** config already carries it, a display-only row is
* appended — the trigger shows the real stored state and nothing is silently rewritten.
* Gating on the persisted value (not the local edit state) means a misclick onto another
* tier keeps the row until the change is actually saved, so the user can always click
* back to the value still stored on disk.
*/
export function thinkingLevelOptionsFor(
options: ReadonlyArray<readonly [string, string]>,
noneKeptDescription: string,
storedLevel: string | undefined,
): ThinkingLevelOptionRow[] {
const rows = options
.filter(([value]) => value !== "")
.map(([value, description]) => ({
value,
triggerLabel: value,
label: value,
description,
}));
if (storedLevel === "none") {
rows.push({
value: "none",
triggerLabel: "none",
label: "none",
description: noneKeptDescription,
});
}
return rows;
}
/**
* Structural subset of a stream ChatItem that the mid-chat switch guard inspects: the
* item kind plus the compaction items' outcome fields (`running`/`status` — string unions
* on the real items, so `ChatItem[]` is assignable as-is).
*/
export interface ThinkingSwitchItem {
kind: string;
running?: boolean;
status?: string;
}
/**
* Reads the end of a transcript: the trailing run of housekeeping rows — compaction banners,
* the model-change marker of a model switch, and the MCP connect row of a context whose
* servers had to be connected again. `compacted` says the context in effect is a new one with
* nothing said on it yet: a compaction in that run completed (a failed retry after it changed
* nothing), or a model switch opened it — a switch away from a context that had not answered
* runs no compaction and leaves the marker alone. A compaction that failed or is still running
* leaves the old context in effect. `before` counts the items ahead of the run.
*/
export function trailingCompaction(items: ReadonlyArray<ThinkingSwitchItem>): {
compacted: boolean;
before: number;
} {
let last = items.length - 1;
let compacted = false;
while (last >= 0 && ["compaction", "model_change", "mcp_connect"].includes(items[last]!.kind)) {
const c = items[last]!;
if (c.kind === "model_change") compacted = true;
if (c.kind === "compaction" && !c.running && c.status === "completed") compacted = true;
last--;
}
return { compacted, before: last + 1 };
}
/**
* Whether the loaded transcript indicates provider-side history whose prefix cache a
* thinking-level change would invalidate (issue #310): some providers implement the
* thinking level as a prompt prefix injected at the very FRONT of the chat template, so
* changing it mid-conversation re-bills the entire history as uncached input on the next
* request.
*
* - An empty transcript (brand-new session, nothing sent yet) is free to switch.
* - Items only need to be the LIVE TAIL window (stream model): a non-empty session always
* has a non-empty tail, and the trailing-compaction check below only looks at the tail.
* - A transcript that ENDS in a settled successful compaction is also free to switch: the
* provider context was just rewritten to a short summary, so the user who followed the
* "compact first, then switch" advice is not warned a second time. So is one that ends in a
* model switch: the context that switch opened has not been sent yet (see
* `trailingCompaction` for what counts).
*/
export function prefixCacheAtRisk(items: ReadonlyArray<ThinkingSwitchItem>): boolean {
const { compacted, before } = trailingCompaction(items);
// Nothing but (at most) housekeeping rows: no billable history to protect.
return before > 0 && !compacted;
}
/**
* Gate for the ACTIVE-SESSION picker's pick (the draft picker never confirms — there is no
* session, so no provider cache yet): true = stage the pick behind the confirm dialog
* instead of applying it.
*
* `currentLevel` is the level the picker currently DISPLAYS (the user's session pick, else
* the Agent config's level; "" = unknown — config unset or still loading). Re-picking the
* displayed level changes nothing provider-visible (it merely pins the level for the
* session), so it never confirms; an unknown current level confirms whenever history is at
* risk — a needless dialog costs one click, a silently invalidated prefix cache costs real
* money.
*/
export function needsThinkingSwitchConfirm(
items: ReadonlyArray<ThinkingSwitchItem>,
currentLevel: string,
nextLevel: string,
): boolean {
if (currentLevel !== "" && nextLevel === currentLevel) return false;
return prefixCacheAtRisk(items);
}
/**
* Settled compaction attempts visible in the transcript, and how many of them completed.
* Snapshotted when the user picks "compact, then switch" so the wait below can tell OUR
* compaction's outcome from the ones that were already on record.
*/
export interface CompactionTally {
settled: number;
completed: number;
}
/** Counts settled (not still running) compaction items and the completed subset. */
export function compactionTally(items: ReadonlyArray<ThinkingSwitchItem>): CompactionTally {
let settled = 0;
let completed = 0;
for (const item of items) {
if (item.kind !== "compaction" || item.running === true) continue;
settled++;
if (item.status === "completed") completed++;
}
return { settled, completed };
}
/**
* The dialog's "compact, then switch" choice, held while the compaction runs.
*
* `POST /compact` answers **202** — it only starts the compaction, whose outcome arrives
* later over the stream — so the pick cannot be applied on the request promise. It is held
* here until compactionSettledSince below reports the compaction over.
*
* The pick is applied either way once that happens (a failed compaction is reported, not
* silently swallowed): holding it is about ORDER, not about a veto — a level applied while
* the compaction is still running would ride on anything sent in between (a queued
* follow-up auto-starts the moment the session goes idle) and invalidate the very cache
* the compaction is there to shrink.
*/
export type StagedThinkingSwitch =
/** The dialog is open on this pick. */
| { phase: "ask"; level: string }
/** A compaction was started; the pick lands when it settles (see compactionSettledSince). */
| { phase: "compacting"; level: string; baseline: CompactionTally }
/** The compaction never started (the server refused it): release the pick on the next pass. */
| { phase: "settle"; level: string };
/**
* Whether a compaction has finished since the tally was taken, and how it ended:
* - `"completed"` — one completed: the provider context is now the short summary. Reported
* even if items were appended after it (a queued follow-up may have started), because the
* compaction the user asked for did happen.
* - `"failed"` — one settled without completing (failed / aborted): the old context is still
* in effect, and the caller says so while still applying the pick.
* - `"pending"` — nothing has settled yet, keep waiting.
*
* Counting rather than matching item ids keeps this correct across a stream reconnect
* (history is rebuilt and ids restart); the worst case is a stalled `"pending"`.
*/
export function compactionSettledSince(
items: ReadonlyArray<ThinkingSwitchItem>,
baseline: CompactionTally,
): "pending" | "completed" | "failed" {
const now = compactionTally(items);
if (now.completed > baseline.completed) return "completed";
if (now.settled > baseline.settled) return "failed";
return "pending";
}
/**
* What the page owes a staged switch right now — the whole decision, so the rule stays
* testable instead of living in an effect:
* - `"wait"` — the dialog is still open, or the compaction is still running.
* - `"apply"` with a notice — release the pick. **The pick is applied whichever way the
* compaction ended**: a failed one only means the context was not rewritten (so the
* switch does cost cache hits), never that the user's choice is dropped.
* - `"compacted"`: the compaction completed, the cheap path worked out;
* - `"compaction-failed"`: it ended without completing — say so alongside the switch;
* - `"none"`: it never started (the server refused it and already said why).
*/
export type HeldThinkingSwitch =
| { act: "wait" }
| { act: "apply"; level: string; notice: "compacted" | "compaction-failed" | "none" };
export function heldThinkingSwitch(
staged: StagedThinkingSwitch,
items: ReadonlyArray<ThinkingSwitchItem>,
): HeldThinkingSwitch {
if (staged.phase === "ask") return { act: "wait" };
if (staged.phase === "settle") return { act: "apply", level: staged.level, notice: "none" };
const outcome = compactionSettledSince(items, staged.baseline);
if (outcome === "pending") return { act: "wait" };
return {
act: "apply",
level: staged.level,
notice: outcome === "completed" ? "compacted" : "compaction-failed",
};
}