castle-web-cli 0.4.256 → 0.4.258

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/agent.js CHANGED
@@ -24,6 +24,7 @@ import { isSameOriginUpgrade } from './wsOrigin.js';
24
24
  import { resolveDeckPath } from './ide.js';
25
25
  import { lineRange, uniqueLocators } from './deckLocatorShape.js';
26
26
  import { supportedEffort } from './effortSupport.js';
27
+ import { appendFeedEntry, retryNoticeFor } from './retryNotice.js';
27
28
  import * as fs from 'fs';
28
29
  import * as os from 'os';
29
30
  import * as path from 'path';
@@ -40,11 +41,13 @@ import { accountForRun, closingMessageOf } from './taskAccount.js';
40
41
  import { atomicWriteFileSync } from './atomicFile.js';
41
42
  import { AGENT_ATTACHMENT_PREFIX, AGENT_PLAYTEST_PREFIX, PLAN_FILE } from './localPaths.js';
42
43
  import { readGitIncomingNote, removeGitIncoming } from './gitIncoming.js';
43
- import { applyPlanOps, buildRouterPromptParts, buildTaskPrompt, parsePlanOps, userTurnInstruction, CLAUDE_TASK_SYSTEM_REMINDER, modelTaskAddendum, isMuseModel, } from './agent-prompts.js';
44
+ import { applyPlanOps, buildRouterPromptParts, buildTaskPrompt, parsePlanOps, userTurnInstruction, CLAUDE_TASK_SYSTEM_REMINDER, modelTaskAddendum, } from './agent-prompts.js';
45
+ import { defaultEffortFor, defaultSettings, EFFORT_ROLES, normalizeClaudeModel, normalizeEffort, normalizeOpenrouterModel, resolveAgentSettings, serializeAgentSettings, } from './agentSettings.js';
46
+ import { EXPERIMENT_EVENTS, createFallbackNotice, effectiveModelExperiment, experimentArm, fellBackToFree, paidExperimentDefault, } from './modelExperiment.js';
44
47
  import { readCastleJson } from './castleJson.js';
45
48
  import { checkOpenrouterKey, checkOpenrouterModel, primeOpenrouterCatalog, } from './openrouter-catalog.js';
46
- import { classifyProviderError, failureCopy, failureLabel, routerTaskError, routerTurnRetryable, routerTurnErrorText, setReaderTimeZone, } from './agent-failures.js';
47
- import { castleCreditsExhausted, createBudgetRefreshRetry, createRefreshQueue, fetchAiCredits, fetchBudget, freeRolesFor, freeTierForRoles, meteringHeaders, modelIsFree, newAgentSessionId, spendableMicros, withCustomHeaders, } from './metering.js';
49
+ import { classifyProviderError, failureCopy, failureOffersCredits, failureLabel, routerTaskError, routerTurnRetryable, routerTurnErrorText, setReaderTimeZone, } from './agent-failures.js';
50
+ import { castleCreditsExhausted, createBudgetRefreshRetry, createRefreshQueue, fetchAiCredits, fetchAiModelExperiment, sendAiModelExperimentEvent, fetchBudget, freeRolesFor, freeTierForRoles, meteringHeaders, modelIsFree, newAgentSessionId, spendableMicros, withCustomHeaders, } from './metering.js';
48
51
  import { anthropicKeyHelperCommand, resolveAnthropicAuth, userKey, ANTHROPIC_CREDENTIAL_ENV, ANTHROPIC_PROXY_ENV, CASTLE_USER_KEYS_PATH, } from './byo-auth.js';
49
52
  import { accountsSnapshot, loginProviderFor, watchCredentials, writeCredential, } from './byo-accounts.js';
50
53
  import { cancelLogin, logout, startLogin, submitLoginCode } from './byo-login.js';
@@ -57,78 +60,6 @@ import { createServeGitHooks, createServeMarkerPoll } from './cloudGitServe.js';
57
60
  import { deckCollaborators, reportDeckEditorPresence, } from './api.js';
58
61
  export const AGENT_WS_PATH = '/__castle/agent';
59
62
  const PRESENCE_INTERVAL_MS = 15_000;
60
- const DEFAULT_SETTINGS = {
61
- // Both roles run the claude CLI routed through OpenRouter at the slug below.
62
- // Note this takes the Anthropic credential out of play entirely: a role on
63
- // "openrouter" resolves OpenRouter auth, so a user's `claude /login` or
64
- // ANTHROPIC_API_KEY no longer applies (see buildAgentInvocation) -- which is
65
- // exactly why a user who HAS one defaults to ANTHROPIC_DEFAULT_MODELS below.
66
- routerClaudeModel: 'openrouter',
67
- tasksClaudeModel: 'openrouter',
68
- // Free-form -- change to any OpenRouter slug. Both roles default to the
69
- // model Castle pays for (the proxy's freeModelPrefixes list), so an editor
70
- // that has never touched settings costs the user nothing and never runs into
71
- // a credit balance -- see freeTierForRoles / the free-model skip in
72
- // castleSpendRefusal. Picking any other slug puts that role back on credits.
73
- routerOpenrouterModel: 'meta/muse-spark-1.3-contributor',
74
- tasksOpenrouterModel: 'meta/muse-spark-1.3-contributor',
75
- routerEffort: 'medium',
76
- tasksEffort: 'medium',
77
- };
78
- // What the two claude-model defaults become once the user has an Anthropic
79
- // credential of their own -- a key or a claude.ai login, which
80
- // resolveAnthropicAuth already treats as one question. Signing in has to move
81
- // these or it buys the user nothing: the openrouter default never resolves
82
- // Anthropic auth, so an account added in the Accounts modal would sit unused
83
- // (and the runs stay metered) until the user also found the model picker.
84
- const ANTHROPIC_DEFAULT_MODELS = {
85
- routerClaudeModel: 'opus',
86
- tasksClaudeModel: 'sonnet',
87
- };
88
- // Resolved per read rather than captured once: the credential this asks about
89
- // appears and disappears mid-session (the Accounts modal, `claude /login` in
90
- // the terminal panel, a hand-edited user-keys.json), and
91
- // refreshDefaultedSettings re-reads it when it does.
92
- // The effort a role starts at for a given model. Tasks on a muse model start
93
- // at low: castle-agent-evals/muse-tune measured medium as slower with more api
94
- // guessing. The operator stays at medium on every model, and claude models
95
- // stay at medium for both roles. A level the user picks is stored and stands.
96
- function defaultEffortFor(role, claudeModel, openrouterModel) {
97
- return role === 'tasks' && claudeModel === 'openrouter' && isMuseModel(openrouterModel) ? 'low' : 'medium';
98
- }
99
- const EFFORT_ROLES = [
100
- { role: 'router', label: 'operator', claude: 'routerClaudeModel', slug: 'routerOpenrouterModel', effort: 'routerEffort' },
101
- { role: 'tasks', label: 'tasks', claude: 'tasksClaudeModel', slug: 'tasksOpenrouterModel', effort: 'tasksEffort' },
102
- ];
103
- function defaultSettings() {
104
- const models = resolveAnthropicAuth().mode === 'proxy'
105
- ? { ...DEFAULT_SETTINGS }
106
- : { ...DEFAULT_SETTINGS, ...ANTHROPIC_DEFAULT_MODELS };
107
- return {
108
- ...models,
109
- routerEffort: defaultEffortFor('router', models.routerClaudeModel, models.routerOpenrouterModel),
110
- tasksEffort: defaultEffortFor('tasks', models.tasksClaudeModel, models.tasksOpenrouterModel),
111
- };
112
- }
113
- // Bump to force every deck onto the current DEFAULT_SETTINGS once, discarding
114
- // what users had chosen: a stored file below this epoch has ALL of its setting
115
- // fields dropped on load (see loadAgentSettings). Bump ONLY when a default
116
- // change is meant to override existing choices -- an ordinary one needs no
117
- // bump, since sparse storage already reaches anyone who never set that field.
118
- // The wipe is also what retires older file shapes, so a migration for one is
119
- // only worth writing if it must survive the epoch that introduces it.
120
- //
121
- // 2: the OpenRouter default moved to the model Castle pays for. Deliberately a
122
- // bump rather than an ordinary default change -- decks that had already stored
123
- // a slug (including the one that was the default when they stored it) would
124
- // otherwise keep spending credits on a metered model while every user around
125
- // them runs free.
126
- const SETTINGS_EPOCH = 2;
127
- function normalizeClaudeModel(value) {
128
- return value === 'sonnet' || value === 'opus' || value === 'fable' || value === 'openrouter'
129
- ? value
130
- : null;
131
- }
132
63
  // A claude run is spawned with an alias (`--model fable`) but reaches the proxy
133
64
  // as a concrete id (`claude-fable-5`), and it is the ids the proxy refuses. This
134
65
  // is the one place that knows both, so the model picker and the pre-flight
@@ -146,111 +77,15 @@ function claudeModelBlocked(model, budget) {
146
77
  return false;
147
78
  return budget.blockedModelPrefixes.some((p) => p.startsWith(id) || id.startsWith(p));
148
79
  }
149
- // Free-form, so validation is just "non-empty, not absurdly long" (guards
150
- // against a stray huge paste landing in settings.json / the CLI argv).
151
- const OPENROUTER_MODEL_MAX_LEN = 200;
152
- function normalizeOpenrouterModel(value) {
153
- if (typeof value !== 'string')
154
- return null;
155
- const trimmed = value.trim();
156
- return trimmed && trimmed.length <= OPENROUTER_MODEL_MAX_LEN ? trimmed : null;
157
- }
158
- function normalizeEffort(value) {
159
- return value === 'low' ||
160
- value === 'medium' ||
161
- value === 'high' ||
162
- value === 'xhigh' ||
163
- value === 'max'
164
- ? value
165
- : null;
166
- }
167
- // Every setting's validator, keyed the same as AgentSettings, so load and save
168
- // iterate one list rather than repeating the field names per direction.
169
- const SETTING_NORMALIZERS = {
170
- routerClaudeModel: normalizeClaudeModel,
171
- tasksClaudeModel: normalizeClaudeModel,
172
- routerOpenrouterModel: normalizeOpenrouterModel,
173
- tasksOpenrouterModel: normalizeOpenrouterModel,
174
- routerEffort: normalizeEffort,
175
- tasksEffort: normalizeEffort,
176
- };
177
- const SETTING_KEYS = Object.keys(SETTING_NORMALIZERS);
178
- // Sparse ON PURPOSE: only fields that DIFFER from the current defaults are
179
- // stored, so "absent" means "follow the default" and a later default change
180
- // reaches every deck that never set that field. Writing the full object
181
- // instead (as this once did) froze every setting the first time a user
182
- // touched any one of them, pinning models nobody had chosen.
183
- //
184
- // The flip side, accepted: re-selecting the value that is currently the
185
- // default stores nothing, so that deck moves when the default moves. Nothing
186
- // is lost relative to the old behavior -- applyAgentSettings already
187
- // early-returns on a no-op change, so that click never persisted anything.
188
- // Since defaultSettings() reads the Anthropic credential, "the default moves"
189
- // now includes signing out: a role left on what was the signed-in default
190
- // falls back to openrouter rather than sitting on a claude alias with no
191
- // Anthropic account behind it.
192
- function serializeAgentSettings(settings) {
193
- const defaults = defaultSettings();
194
- const out = { settingsEpoch: SETTINGS_EPOCH };
195
- for (const key of SETTING_KEYS) {
196
- if (settings[key] !== defaults[key])
197
- out[key] = settings[key];
198
- }
199
- // Effort's default follows the role's stored model, not the default model.
200
- for (const role of EFFORT_ROLES) {
201
- const value = settings[role.effort];
202
- if (value === defaultEffortFor(role.role, settings[role.claude], settings[role.slug])) {
203
- delete out[role.effort];
204
- }
205
- else {
206
- out[role.effort] = value;
207
- }
208
- }
209
- return JSON.stringify(out, null, 2) + '\n';
210
- }
211
- function loadAgentSettings(settingsPath) {
212
- const defaults = defaultSettings();
213
- const stored = readJsonFile(settingsPath);
214
- const storedEpoch = typeof stored?.settingsEpoch === 'number' ? stored.settingsEpoch : 0;
215
- // A stale file is ignored, not rewritten: leaving it means the wipe is a
216
- // pure read-side decision that repeats harmlessly until the user's next real
217
- // change overwrites it in the sparse shape. A newer epoch (a downgraded CLI
218
- // reading a file from a newer one) is honored rather than wiped.
219
- if (!stored || storedEpoch < SETTINGS_EPOCH)
220
- return defaults;
221
- const overrides = {};
222
- for (const key of SETTING_KEYS) {
223
- if (!(key in stored))
224
- continue;
225
- const value = SETTING_NORMALIZERS[key](stored[key]);
226
- if (value !== null)
227
- overrides[key] = value;
228
- }
229
- const merged = { ...defaults, ...overrides };
230
- for (const role of EFFORT_ROLES) {
231
- if (role.effort in overrides) {
232
- continue;
233
- }
234
- merged[role.effort] = defaultEffortFor(role.role, merged[role.claude], merged[role.slug]);
235
- }
236
- return merged;
237
- }
238
- // Re-resolve the defaults into the live settings object after a credential
239
- // change, in place because every consumer (the router queue, the task store)
240
- // holds this same object. Only fields the stored file leaves unset can move --
241
- // loadAgentSettings layers it back over the new defaults -- so a choice the
242
- // user actually made is never overwritten. Returns whether anything moved, so
243
- // the caller only broadcasts a real change.
244
- function refreshDefaultedSettings(settings, settingsPath) {
245
- const next = loadAgentSettings(settingsPath);
246
- let changed = false;
247
- for (const key of SETTING_KEYS) {
248
- if (settings[key] === next[key])
249
- continue;
250
- Object.assign(settings, { [key]: next[key] });
251
- changed = true;
80
+ // Re-resolve into the object shared by the router and task store whenever
81
+ // credentials or the experiment default move.
82
+ function refreshDefaultedSettings(settings, settingsPath, proxied, paidDefault) {
83
+ const next = resolveAgentSettings(readJsonFile(settingsPath), proxied, paidDefault);
84
+ if (Object.keys(next).every((key) => settings[key] === next[key])) {
85
+ return false;
252
86
  }
253
- return changed;
87
+ Object.assign(settings, next);
88
+ return true;
254
89
  }
255
90
  // Base for OpenRouter's Anthropic-compatible endpoint (confirmed current, 2026: it
256
91
  // accepts the standard Anthropic Messages API shape -- text/tool-use/extended-thinking
@@ -1109,6 +944,7 @@ function createAgentStreamState() {
1109
944
  needsGap: false,
1110
945
  pendingTools: new Map(),
1111
946
  resultMark: 0,
947
+ retryShowing: false,
1112
948
  };
1113
949
  }
1114
950
  function parseCliUsage(raw) {
@@ -1209,12 +1045,34 @@ function logAgentUsage(label, usage) {
1209
1045
  const output = formatTokenCount(usage.output_tokens);
1210
1046
  console.error(`[agent usage] ${label}: input=${input} cache_read=${read} cache_created=${created} output=${output}`);
1211
1047
  }
1048
+ // Exported for scripts/tests/agent-retry-activity.mjs: the activity calls a
1049
+ // sequence of claude stream-json events produces.
1050
+ export function claudeActivityTrace(events, labelUnknownTools = false) {
1051
+ const trace = [];
1052
+ const handle = makeAgentEventHandler({
1053
+ cwd: '',
1054
+ command: '',
1055
+ args: [],
1056
+ env: {},
1057
+ timeoutMs: 0,
1058
+ children: new Set(),
1059
+ labelUnknownTools,
1060
+ onActivity: (activity) => trace.push(activity),
1061
+ }, createAgentStreamState());
1062
+ for (const ev of events)
1063
+ handle(ev);
1064
+ return trace;
1065
+ }
1212
1066
  // Build the per-run stdout event handler over a shared mutable parser state.
1213
1067
  // Splitting the stream decoding out of runAgentCli keeps each within the
1214
1068
  // max-lines budget. A tool_use block streams its input JSON by block index,
1215
1069
  // accumulated in pendingTools so content_block_stop can label it with the
1216
1070
  // real file / command (and drop progress-file writes).
1217
1071
  function makeAgentEventHandler(opts, state) {
1072
+ const setActivity = (activity, retry = false) => {
1073
+ state.retryShowing = retry;
1074
+ opts.onActivity?.(activity);
1075
+ };
1218
1076
  const emitDelta = (rawDelta) => {
1219
1077
  let delta = rawDelta;
1220
1078
  if (state.needsGap) {
@@ -1225,15 +1083,22 @@ function makeAgentEventHandler(opts, state) {
1225
1083
  }
1226
1084
  state.accumulated += delta;
1227
1085
  opts.onDelta?.(delta);
1228
- opts.onActivity?.(null);
1086
+ setActivity(null);
1229
1087
  };
1230
1088
  const handleClaudeEvent = (ev) => {
1231
1089
  if (ev.type === 'system' && ev.subtype === 'init' && typeof ev.session_id === 'string') {
1232
1090
  state.sessionId = ev.session_id;
1233
1091
  }
1092
+ else if (ev.type === 'system' && ev.subtype === 'api_retry') {
1093
+ setActivity(retryNoticeFor(ev), true);
1094
+ }
1234
1095
  else if (ev.type === 'stream_event') {
1235
1096
  const e = ev.event;
1236
- if (e?.type === 'content_block_start') {
1097
+ if (e?.type === 'message_start') {
1098
+ if (state.retryShowing)
1099
+ setActivity(null);
1100
+ }
1101
+ else if (e?.type === 'content_block_start') {
1237
1102
  if (e.content_block?.type === 'tool_use') {
1238
1103
  state.needsGap = true;
1239
1104
  const name = String(e.content_block.name ?? '');
@@ -1241,7 +1106,7 @@ function makeAgentEventHandler(opts, state) {
1241
1106
  // line isn't stuck on the prior state while the tool runs; the
1242
1107
  // concrete label (with the file) refines it at content_block_stop.
1243
1108
  if (opts.labelUnknownTools)
1244
- opts.onActivity?.(genericClaudeToolLabel(name));
1109
+ setActivity(genericClaudeToolLabel(name));
1245
1110
  // Hold the concrete label until content_block_stop, once the input
1246
1111
  // (file / command) has streamed in, so we can name it concretely.
1247
1112
  state.pendingTools.set(e.index ?? -1, { name, buf: '' });
@@ -1250,7 +1115,7 @@ function makeAgentEventHandler(opts, state) {
1250
1115
  state.needsGap = true;
1251
1116
  // Surface extended thinking as the activity line. The next text delta
1252
1117
  // clears it via emitDelta's onActivity(null); a tool block relabels it.
1253
- opts.onActivity?.('Thinking');
1118
+ setActivity('Thinking');
1254
1119
  }
1255
1120
  }
1256
1121
  else if (e?.type === 'content_block_delta') {
@@ -1282,7 +1147,7 @@ function makeAgentEventHandler(opts, state) {
1282
1147
  }
1283
1148
  const label = claudeToolFeedLabel(pending.name, input);
1284
1149
  if (label)
1285
- opts.onActivity?.(label);
1150
+ setActivity(label);
1286
1151
  }
1287
1152
  }
1288
1153
  }
@@ -1777,23 +1642,40 @@ function blockedClaudeModels(budget) {
1777
1642
  return [];
1778
1643
  return PICKER_CLAUDE_MODELS.filter((m) => claudeModelBlocked(m, budget));
1779
1644
  }
1780
- function usageFrame(budget, credits, settings) {
1781
- if (!budget)
1645
+ function effectiveExperiment(experiment) {
1646
+ return effectiveModelExperiment(experiment, runIsCastlePaid('opus', null), runIsCastlePaid('openrouter', null));
1647
+ }
1648
+ function usageFrame(budget, credits, settings, experiment, experimentFallback) {
1649
+ if (!budget && !experiment?.inExperiment && experimentArm(experiment) === 'control')
1782
1650
  return null;
1651
+ const prefixes = budget?.freeModelPrefixes ?? [];
1783
1652
  return {
1784
- usedMicros: budget.usedMicros,
1785
- limitMicros: budget.limitMicros,
1786
- spendableMicros: spendableMicros(budget),
1787
- resetAtMs: budget.resetAtMs,
1788
- blocked: budget.blocked,
1653
+ usedMicros: budget?.usedMicros ?? 0,
1654
+ limitMicros: budget?.limitMicros ?? null,
1655
+ spendableMicros: budget ? spendableMicros(budget) : null,
1656
+ resetAtMs: budget?.resetAtMs ?? 0,
1657
+ blocked: budget?.blocked ?? false,
1789
1658
  credits,
1790
- creditsExhausted: castleCreditsExhausted(budget, credits),
1791
- blockedClaudeModels: blockedClaudeModels(budget),
1792
- freeTier: freeTierForRoles(roleSpends(settings), budget.freeModelPrefixes),
1793
- freeModel: runIsCastlePaid('openrouter', null)
1794
- ? (budget.freeModelPrefixes[0] ?? null)
1795
- : null,
1796
- freeRoles: freeRolesFor(roleSpends(settings), budget.freeModelPrefixes),
1659
+ creditsExhausted: budget ? castleCreditsExhausted(budget, credits) : false,
1660
+ blockedClaudeModels: budget ? blockedClaudeModels(budget) : [],
1661
+ freeTier: Boolean(budget) && freeTierForRoles(roleSpends(settings), prefixes),
1662
+ freeModel: runIsCastlePaid('openrouter', null) ? (prefixes[0] ?? null) : null,
1663
+ freeRoles: freeRolesFor(roleSpends(settings), prefixes),
1664
+ experiment,
1665
+ experimentFallback,
1666
+ };
1667
+ }
1668
+ // Keep event properties bounded and take the deck ID from the served deck.
1669
+ function experimentProperties(value) {
1670
+ if (!value || typeof value !== 'object')
1671
+ return {};
1672
+ const { model, role, surface, source } = value;
1673
+ return {
1674
+ model: normalizeOpenrouterModel(model) ?? undefined,
1675
+ role: role === 'router' || role === 'tasks' ? role : undefined,
1676
+ surface: surface === 'web' || surface === 'app' ? surface : undefined,
1677
+ source: source === 'composer' || source === 'failure' || source === 'fallback' || source === 'popover'
1678
+ ? source : undefined,
1797
1679
  };
1798
1680
  }
1799
1681
  /**
@@ -1802,12 +1684,8 @@ function usageFrame(budget, credits, settings) {
1802
1684
  * Outside a sandbox fetchBudget answers null forever, so nothing is ever sent
1803
1685
  * and the shell simply has no bar to show.
1804
1686
  *
1805
- * Null is a value here, not just "no answer yet": a user running on their own
1806
- * credential is told nothing about Castle's budget, because none of their
1807
- * runs spend it and none of them are gated on it -- showing the bar (worse, a
1808
- * spent-out red one) would describe a limit that doesn't apply to them. It has
1809
- * to be broadcast rather than merely withheld, so the bar clears when a
1810
- * credential appears mid-session.
1687
+ * The control arm clears the meter when a credential covers every role.
1688
+ * Experiment state is effective only while both routes use Castle credentials.
1811
1689
  */
1812
1690
  function createUsageFeed(opts) {
1813
1691
  let latest = null;
@@ -1815,33 +1693,29 @@ function createUsageFeed(opts) {
1815
1693
  let budget = null;
1816
1694
  let budgetPolls = 0;
1817
1695
  let stopped = false;
1696
+ let experiment = null;
1697
+ let experimentRevision = 0;
1698
+ let pendingEvents = Promise.resolve();
1699
+ const fallback = createFallbackNotice();
1818
1700
  async function readUsage(refreshCredits = false, allowFollowUp = true) {
1819
- const settings = opts.settings();
1820
- // Cached credits and budget survive a spell on the user's own keys: when a
1821
- // role comes back to Castle's, recompute() can publish a credits-plan frame
1822
- // at once instead of the legacy daily meter, and the refresh reconciles.
1823
- if (!anyRoleIsCastlePaid(settings)) {
1824
- return { usage: null, refreshAfterMs: null, allowFollowUp };
1825
- }
1826
- // Budget is the authoritative spendable amount and its read can force a
1827
- // stale proxy gate to sync after a purchase. Read credits second so the
1828
- // descriptive fields (plan, rate, reload state) describe that same or a
1829
- // newer account snapshot instead of racing ahead of the gate refresh.
1830
- // Only a full credit-state refresh asks the host to sync its held budget. Cheap polls and
1831
- // spend preflight stay local to the proxy, so control-plane health cannot delay a run.
1832
- const nextBudget = await fetchBudget(refreshCredits);
1833
- if (nextBudget)
1834
- budget = nextBudget;
1835
- if (refreshCredits) {
1836
- const nextCredits = await fetchAiCredits();
1837
- // Once the richer field has loaded, a transient GraphQL failure should
1838
- // not erase it and fall the UI back to the legacy daily presentation.
1839
- if (nextCredits)
1840
- credits = nextCredits;
1841
- }
1701
+ const revision = experimentRevision;
1702
+ // Started eagerly by the feed's initial refresh, independently of dispatch.
1703
+ // A send always uses the settings already in force while this is pending.
1704
+ const experimentRead = refreshCredits ? fetchAiModelExperiment() : Promise.resolve(undefined);
1705
+ async function readBudgetAndCredits() {
1706
+ // Read the budget first so the descriptive fields reflect that snapshot
1707
+ // or a newer one. Cheap polls keep using the proxy's held budget.
1708
+ const nextBudget = await fetchBudget(refreshCredits);
1709
+ return { budget: nextBudget, credits: refreshCredits ? await fetchAiCredits() : undefined };
1710
+ }
1711
+ const castlePaid = anyRoleIsCastlePaid(opts.settings());
1712
+ const usageRead = castlePaid ? readBudgetAndCredits() : undefined;
1713
+ const nextExperiment = await experimentRead;
1714
+ const read = usageRead ?? { budget: null };
1842
1715
  return {
1843
- usage: usageFrame(nextBudget, credits, settings),
1844
- refreshAfterMs: nextBudget?.refreshAfterMs ?? null,
1716
+ ...await read,
1717
+ experiment: nextExperiment,
1718
+ experimentRevision: revision,
1845
1719
  allowFollowUp,
1846
1720
  };
1847
1721
  }
@@ -1851,28 +1725,59 @@ function createUsageFeed(opts) {
1851
1725
  latest = next;
1852
1726
  opts.broadcast({ type: 'usage', usage: next });
1853
1727
  }
1854
- function publishRead(read) {
1728
+ function recompute(frameBudget = budget) {
1855
1729
  if (stopped)
1856
1730
  return;
1857
- publishUsage(read.usage);
1858
- if (!read.allowFollowUp || read.refreshAfterMs === null)
1859
- return;
1860
- budgetRetry.schedule(read.refreshAfterMs);
1731
+ const settings = opts.settings();
1732
+ const showBudget = anyRoleIsCastlePaid(settings);
1733
+ publishUsage(usageFrame(showBudget ? frameBudget : null, showBudget ? credits : null, settings, effectiveExperiment(experiment), fallback.pending()));
1861
1734
  }
1862
- function recompute() {
1735
+ function syncDefaults(frameBudget = budget) {
1863
1736
  if (stopped)
1864
1737
  return;
1865
- const settings = opts.settings();
1866
- if (!anyRoleIsCastlePaid(settings)) {
1867
- publishUsage(null);
1738
+ const spendable = credits?.plan === 'credits' && budget ? spendableMicros(budget) : null;
1739
+ const effective = effectiveExperiment(experiment);
1740
+ const updated = opts.updateDefaults(effective, spendable);
1741
+ if (updated.fellBack)
1742
+ fallback.begin();
1743
+ if (spendable !== 0 || experimentArm(effective) !== 'paid_default' ||
1744
+ opts.settings().routerClaudeModel !== 'openrouter')
1745
+ fallback.clear();
1746
+ recompute(frameBudget);
1747
+ if (updated.changed)
1748
+ opts.broadcast({ type: 'settings', settings: opts.settings() });
1749
+ }
1750
+ function publishRead(read) {
1751
+ if (stopped)
1868
1752
  return;
1869
- }
1870
- if (!budget)
1753
+ if (read.budget)
1754
+ budget = read.budget;
1755
+ // Keep the last credits-plan fields through a transient GraphQL failure.
1756
+ if (read.credits)
1757
+ credits = read.credits;
1758
+ if (read.experiment !== undefined && read.experimentRevision === experimentRevision) {
1759
+ experiment = read.experiment;
1760
+ }
1761
+ syncDefaults(read.budget);
1762
+ const retryAfter = read.budget?.refreshAfterMs;
1763
+ if (read.allowFollowUp && retryAfter != null)
1764
+ budgetRetry.schedule(retryAfter);
1765
+ }
1766
+ function event(eventName, properties = {}) {
1767
+ if (stopped || !effectiveExperiment(experiment)?.inExperiment)
1871
1768
  return;
1872
- // Settings-dependent fields must not wait on the network: the client
1873
- // renders both the picker and the credits guard from them, and a settings
1874
- // frame is about to follow this usage frame.
1875
- publishUsage(usageFrame(budget, credits, settings));
1769
+ // Keep shown/tapped and reply events in order. A poll that started before
1770
+ // an event response must not undo its fresh nudge state.
1771
+ pendingEvents = pendingEvents.then(async () => {
1772
+ if (stopped || !effectiveExperiment(experiment)?.inExperiment)
1773
+ return;
1774
+ const next = await sendAiModelExperimentEvent(eventName, { ...properties, deckId: opts.deckId() });
1775
+ if (stopped || next === undefined)
1776
+ return;
1777
+ experimentRevision += 1;
1778
+ experiment = next;
1779
+ syncDefaults();
1780
+ }).catch(() => { });
1876
1781
  }
1877
1782
  // Focus, host relay, popover-open and run-finished can all arrive together.
1878
1783
  const refreshQueue = createRefreshQueue({ read: readUsage, publish: publishRead });
@@ -1896,10 +1801,20 @@ function createUsageFeed(opts) {
1896
1801
  refresh();
1897
1802
  return {
1898
1803
  latest: () => latest,
1804
+ fallbackShown: (id, properties) => {
1805
+ if (stopped || !effectiveExperiment(experiment)?.inExperiment)
1806
+ return;
1807
+ if (!fallback.acknowledge(id))
1808
+ return;
1809
+ // Clear the shared hello/usage frame before queuing the single event.
1810
+ recompute();
1811
+ event('fallback_to_free_shown', properties);
1812
+ },
1899
1813
  // The budget outlives a switch to the user's own OpenRouter key; the chip
1900
1814
  // stops saying Muse then (usageFrame's freeModel), so the router must too.
1901
1815
  freeModelPrefixes: () => runIsCastlePaid('openrouter', null) ? (budget?.freeModelPrefixes ?? []) : [],
1902
- recompute,
1816
+ syncDefaults,
1817
+ event,
1903
1818
  refresh,
1904
1819
  stop: () => {
1905
1820
  stopped = true;
@@ -2072,7 +1987,7 @@ const TASK_OPTIONAL_STRINGS = [
2072
1987
  const TASK_OPTIONAL_NUMBERS = ['pid', 'costUsd', 'durationApiMs', 'numTurns', 'resumeCount'];
2073
1988
  const TASK_OPTIONAL_OBJECTS = ['usage', 'modelUsage'];
2074
1989
  const TASK_OPTIONAL_BOOLEANS = [
2075
- 'acknowledged', 'rejected', 'durablePending', 'resultSummaryStartsMidWord', 'handoffNoDeckFiles',
1990
+ 'acknowledged', 'rejected', 'durablePending', 'offersCredits', 'resultSummaryStartsMidWord', 'handoffNoDeckFiles',
2076
1991
  ];
2077
1992
  const TASK_OPTIONAL_STRING_LISTS = ['playtestFrames', 'files', 'knobs', 'blockedBy'];
2078
1993
  const isStringList = (v) => Array.isArray(v) && v.every((s) => typeof s === 'string');
@@ -3750,6 +3665,7 @@ function startTask(ctx, task) {
3750
3665
  willRetry: false,
3751
3666
  });
3752
3667
  task.errorDetail = failure.detail || result.error;
3668
+ task.offersCredits = failureOffersCredits(failure) || undefined;
3753
3669
  task.failure = failureLabel(failure);
3754
3670
  console.error(`[task ${task.id}] failed (${task.failure}): ${failure.verbose ?? task.errorDetail}`);
3755
3671
  }
@@ -4415,6 +4331,7 @@ function asClientTask(task, signPath) {
4415
4331
  rejected: task.rejected,
4416
4332
  errorCopy: task.errorCopy,
4417
4333
  errorDetail: task.errorDetail,
4334
+ offersCredits: task.offersCredits,
4418
4335
  playtestFrames: (task.playtestFrames ?? []).map((rel) => clientUrl(`${AGENT_PLAYTEST_PREFIX}${task.id}/${path.basename(rel)}`, signPath)),
4419
4336
  steers: task.steers?.length
4420
4337
  ? task.steers.map(({ id, text, state, at, reason, sentOnAs }) => ({ id, text, state, at, reason, sentOnAs }))
@@ -4468,9 +4385,7 @@ function createTaskFeeds(broadcast, tasksDir) {
4468
4385
  }
4469
4386
  if (feed[feed.length - 1] === entry)
4470
4387
  return;
4471
- feed.push(entry);
4472
- if (feed.length > TASK_FEED_CAP)
4473
- feed.splice(0, feed.length - TASK_FEED_CAP);
4388
+ map.set(task.id, appendFeedEntry(feed, entry, TASK_FEED_CAP));
4474
4389
  broadcast({ type: 'task-feed', id: task.id, entry });
4475
4390
  }
4476
4391
  return { map, push, persist };
@@ -4892,13 +4807,19 @@ function runRouterTurnIn(ctx, instruction) {
4892
4807
  let lastActivity = 'Thinking';
4893
4808
  ctx.broadcast({ type: 'message-activity', id: message.id, activity: 'Thinking' });
4894
4809
  const prompt = routerTurnPrompt(ctx, instruction, message.id, readPlanSnapshot(ctx.deckDir));
4810
+ const claudeModel = ctx.claudeModel();
4811
+ const openrouterModel = ctx.openrouterModel();
4812
+ // Classified when the reply lands, not here: a send no longer waits for the
4813
+ // usage feed, so the free-model prefixes may not be loaded yet at start.
4814
+ const freeReply = () => claudeModel === 'openrouter' &&
4815
+ modelIsFree(openrouterModel, ctx.freeModelPrefixes());
4895
4816
  void runAgentTurn({
4896
4817
  role: 'router',
4897
4818
  playtestTool: false,
4898
4819
  prompt: prompt.user,
4899
4820
  systemPrompt: prompt.system,
4900
- claudeModel: ctx.claudeModel(),
4901
- openrouterModel: ctx.openrouterModel(),
4821
+ claudeModel,
4822
+ openrouterModel,
4902
4823
  effort: ctx.effort(),
4903
4824
  cwd: ctx.deckDir,
4904
4825
  timeoutMs: ROUTER_TIMEOUT_MS,
@@ -4994,6 +4915,7 @@ function runRouterTurnIn(ctx, instruction) {
4994
4915
  message.text = routerTurnErrorText(cleaned, textIsProviderError, copy);
4995
4916
  message.status = 'error';
4996
4917
  message.errorDetail = failure.detail || result.error || 'unknown failure';
4918
+ message.offersCredits = failureOffersCredits(failure) || undefined;
4997
4919
  errorVerbose = failure.verbose;
4998
4920
  console.error(`[router] turn failed (${failureLabel(failure)}): ${failure.verbose ?? message.errorDetail}`);
4999
4921
  }
@@ -5007,6 +4929,7 @@ function runRouterTurnIn(ctx, instruction) {
5007
4929
  status: message.status,
5008
4930
  taskIds: message.taskIds ?? [],
5009
4931
  errorDetail: message.errorDetail,
4932
+ offersCredits: message.offersCredits,
5010
4933
  planUpdated: message.planUpdated,
5011
4934
  // Broadcast-only, never persisted: the client console.errors this so
5012
4935
  // the whole provider response is inspectable without leaving the
@@ -5015,6 +4938,8 @@ function runRouterTurnIn(ctx, instruction) {
5015
4938
  // messages.json or a replayed transcript.
5016
4939
  errorVerbose,
5017
4940
  });
4941
+ if (result.ok && !stale && freeReply())
4942
+ ctx.onFreeReply(openrouterModel);
5018
4943
  }
5019
4944
  catch (err) {
5020
4945
  // Surface the failure in the UI instead of silently hanging: mark the
@@ -5098,9 +5023,18 @@ function applyAgentSettings(incoming, ctx) {
5098
5023
  changes.push(`${role.label} effort -> ${value} (default for this model)`);
5099
5024
  }
5100
5025
  }
5026
+ // In paid_default, reselecting the current model can create a durable pin
5027
+ // even when no live setting changes.
5028
+ if (changes.length === 0 && ctx.arm !== 'paid_default')
5029
+ return;
5030
+ const stored = readJsonFile(ctx.settingsPath);
5031
+ const serialized = serializeAgentSettings(settings, stored, incoming, ctx.defaults, ctx.arm);
5032
+ if (changes.length === 0 &&
5033
+ serialized === serializeAgentSettings(settings, stored, {}, ctx.defaults, ctx.arm))
5034
+ return;
5035
+ atomicWriteFileSync(ctx.settingsPath, serialized);
5101
5036
  if (changes.length === 0)
5102
5037
  return;
5103
- atomicWriteFileSync(ctx.settingsPath, serializeAgentSettings(settings));
5104
5038
  // Publish recomputed usage first. Muse -> OpenRouter stays Muse while the old
5105
5039
  // slug still equals the free model, then the settings frame flips it;
5106
5040
  // OpenRouter -> Muse flips at once through freeRoles, and settings agrees.
@@ -5443,6 +5377,7 @@ function startRouterTurn(ctx, instruction) {
5443
5377
  taskOpenrouterModel: () => ctx.settings.tasksOpenrouterModel,
5444
5378
  taskEffort: () => ctx.settings.tasksEffort,
5445
5379
  freeModelPrefixes: ctx.freeModelPrefixes,
5380
+ onFreeReply: ctx.onFreeReply,
5446
5381
  canAutoRetry: () => !ctx.state.autoRetryUsed && ctx.state.pendingSends.length === 0,
5447
5382
  onSettled: (retryable) => onRouterQueueSettled(ctx, retryable),
5448
5383
  }, instruction);
@@ -5918,22 +5853,36 @@ export function createAgentServer(opts) {
5918
5853
  // Which CLI backs the router and the task agents -- independently
5919
5854
  // switchable from the settings popover, persisted next to the chat state.
5920
5855
  const settingsPath = path.join(agentDir, 'settings.json');
5921
- const settings = loadAgentSettings(settingsPath);
5856
+ let proxied = resolveAnthropicAuth().mode === 'proxy';
5857
+ let paidDefault = null;
5858
+ const settings = resolveAgentSettings(readJsonFile(settingsPath), proxied, paidDefault);
5922
5859
  const usageFeed = createUsageFeed({
5923
5860
  broadcast,
5924
5861
  hasClients: () => clients.size > 0,
5925
5862
  settings: () => settings,
5863
+ deckId: () => readCastleJson(deckDir)?.deckId,
5864
+ updateDefaults: (experiment, spendable) => {
5865
+ const nextProxied = resolveAnthropicAuth().mode === 'proxy';
5866
+ const nextPaidDefault = paidExperimentDefault(experiment, nextProxied, spendable);
5867
+ let changed = false;
5868
+ let fellBack = false;
5869
+ if (nextProxied !== proxied || nextPaidDefault !== paidDefault) {
5870
+ const previousRouter = settings.routerClaudeModel;
5871
+ changed = refreshDefaultedSettings(settings, settingsPath, nextProxied, nextPaidDefault);
5872
+ if (fellBackToFree(paidDefault, previousRouter, settings.routerClaudeModel, experiment, nextProxied, spendable)) {
5873
+ fellBack = true;
5874
+ }
5875
+ proxied = nextProxied;
5876
+ paidDefault = nextPaidDefault;
5877
+ }
5878
+ return { changed, fellBack };
5879
+ },
5926
5880
  });
5927
5881
  const accountsFeed = createAccountsFeed({
5928
5882
  broadcast,
5929
5883
  hasClients: () => clients.size > 0,
5930
5884
  onCredentialChange: () => {
5931
- // Signing in moves the claude-model default (see defaultSettings), and
5932
- // nothing else pushes a settings frame -- without this the popover keeps
5933
- // showing the model the page loaded with until a reload.
5934
- if (refreshDefaultedSettings(settings, settingsPath)) {
5935
- broadcast({ type: 'settings', settings });
5936
- }
5885
+ usageFeed.syncDefaults();
5937
5886
  usageFeed.refresh();
5938
5887
  },
5939
5888
  });
@@ -5941,9 +5890,20 @@ export function createAgentServer(opts) {
5941
5890
  applyAgentSettings(incoming, {
5942
5891
  settings,
5943
5892
  settingsPath,
5893
+ defaults: defaultSettings(resolveAnthropicAuth().mode === 'proxy', paidDefault),
5894
+ arm: experimentArm(usageFeed.latest()?.experiment),
5944
5895
  broadcast,
5945
- onChanged: () => usageFeed.recompute(),
5896
+ onChanged: () => usageFeed.syncDefaults(),
5946
5897
  });
5898
+ for (const { role, claude, slug } of EFFORT_ROLES) {
5899
+ if (!normalizeClaudeModel(incoming[claude]) && !normalizeOpenrouterModel(incoming[slug]))
5900
+ continue;
5901
+ const alias = settings[claude];
5902
+ const model = alias === 'openrouter' ? settings[slug] : alias;
5903
+ if (alias === 'openrouter' && modelIsFree(model, usageFeed.freeModelPrefixes()))
5904
+ continue;
5905
+ usageFeed.event('paid_model_selected', { model, role });
5906
+ }
5947
5907
  // The synchronous recompute makes settings-derived fields immediate; the
5948
5908
  // network read still reconciles the balance and dedups an unchanged frame.
5949
5909
  usageFeed.refresh();
@@ -5992,6 +5952,7 @@ export function createAgentServer(opts) {
5992
5952
  const routerQueue = createRouterQueue({
5993
5953
  deckDir,
5994
5954
  freeModelPrefixes: usageFeed.freeModelPrefixes,
5955
+ onFreeReply: (model) => usageFeed.event('free_model_reply', { role: 'router', model }),
5995
5956
  deckLabel,
5996
5957
  agentDir,
5997
5958
  attachmentsDir,
@@ -6073,6 +6034,7 @@ export function createAgentServer(opts) {
6073
6034
  }
6074
6035
  function attachClient(socket) {
6075
6036
  clients.add(socket);
6037
+ let exposed = false;
6076
6038
  const hello = {
6077
6039
  type: 'hello',
6078
6040
  messages: messages
@@ -6160,6 +6122,21 @@ export function createAgentServer(opts) {
6160
6122
  if (setPlaytestPref(deckDir, msg.value))
6161
6123
  broadcast(deckPrefsFrame(deckDir));
6162
6124
  }
6125
+ else if (msg.type === 'experiment-fallback-shown') {
6126
+ usageFeed.fallbackShown(msg.fallbackId, experimentProperties(msg.properties));
6127
+ }
6128
+ else if (msg.type === 'experiment-event') {
6129
+ const event = EXPERIMENT_EVENTS.find((name) => name === msg.event);
6130
+ if (!event || event === 'free_model_reply' || event === 'fallback_to_free_shown' ||
6131
+ !usageFeed.latest()?.experiment?.inExperiment)
6132
+ return;
6133
+ if (event === 'exposure') {
6134
+ if (exposed)
6135
+ return;
6136
+ exposed = true;
6137
+ }
6138
+ usageFeed.event(event, experimentProperties(msg.properties));
6139
+ }
6163
6140
  else if (msg.type === 'refresh-usage') {
6164
6141
  usageFeed.refresh();
6165
6142
  }