castle-web-cli 0.4.257 → 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.d.ts CHANGED
@@ -5,18 +5,11 @@ import { Duplex } from 'stream';
5
5
  import { extractDirectives, type AnswerDirective, type TaskDirective } from './routerFences.js';
6
6
  import { type SendDirective, type TaskSteer } from './taskSteer.js';
7
7
  import { type StopNote, type StopTarget } from './routerStops.js';
8
+ import { type AgentSettings, type ClaudeModel } from './agentSettings.js';
8
9
  import { type PlaytestExecutor, type PlaytestToolResult } from './native/playtest.js';
9
10
  export declare const AGENT_WS_PATH = "/__castle/agent";
10
- export type ClaudeModel = 'sonnet' | 'opus' | 'fable' | 'openrouter';
11
+ export type { ClaudeModel } from './agentSettings.js';
11
12
  export type { EffortLevel };
12
- interface AgentSettings {
13
- routerClaudeModel: ClaudeModel;
14
- tasksClaudeModel: ClaudeModel;
15
- routerOpenrouterModel: string;
16
- tasksOpenrouterModel: string;
17
- routerEffort: EffortLevel;
18
- tasksEffort: EffortLevel;
19
- }
20
13
  type OpenrouterSlugKey = 'routerOpenrouterModel' | 'tasksOpenrouterModel';
21
14
  type SettingsWarnings = Partial<Record<OpenrouterSlugKey, {
22
15
  model: string;
@@ -209,6 +202,7 @@ interface RouterCtx {
209
202
  taskOpenrouterModel: () => string;
210
203
  taskEffort: () => EffortLevel;
211
204
  freeModelPrefixes: () => readonly string[];
205
+ onFreeReply: (model: string) => void;
212
206
  canAutoRetry: () => boolean;
213
207
  onSettled: (retryable?: boolean) => void;
214
208
  }
package/dist/agent.js CHANGED
@@ -41,11 +41,13 @@ import { accountForRun, closingMessageOf } from './taskAccount.js';
41
41
  import { atomicWriteFileSync } from './atomicFile.js';
42
42
  import { AGENT_ATTACHMENT_PREFIX, AGENT_PLAYTEST_PREFIX, PLAN_FILE } from './localPaths.js';
43
43
  import { readGitIncomingNote, removeGitIncoming } from './gitIncoming.js';
44
- 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';
45
47
  import { readCastleJson } from './castleJson.js';
46
48
  import { checkOpenrouterKey, checkOpenrouterModel, primeOpenrouterCatalog, } from './openrouter-catalog.js';
47
49
  import { classifyProviderError, failureCopy, failureOffersCredits, failureLabel, routerTaskError, routerTurnRetryable, routerTurnErrorText, setReaderTimeZone, } from './agent-failures.js';
48
- import { castleCreditsExhausted, createBudgetRefreshRetry, createRefreshQueue, fetchAiCredits, fetchBudget, freeRolesFor, freeTierForRoles, meteringHeaders, modelIsFree, newAgentSessionId, spendableMicros, withCustomHeaders, } from './metering.js';
50
+ import { castleCreditsExhausted, createBudgetRefreshRetry, createRefreshQueue, fetchAiCredits, fetchAiModelExperiment, sendAiModelExperimentEvent, fetchBudget, freeRolesFor, freeTierForRoles, meteringHeaders, modelIsFree, newAgentSessionId, spendableMicros, withCustomHeaders, } from './metering.js';
49
51
  import { anthropicKeyHelperCommand, resolveAnthropicAuth, userKey, ANTHROPIC_CREDENTIAL_ENV, ANTHROPIC_PROXY_ENV, CASTLE_USER_KEYS_PATH, } from './byo-auth.js';
50
52
  import { accountsSnapshot, loginProviderFor, watchCredentials, writeCredential, } from './byo-accounts.js';
51
53
  import { cancelLogin, logout, startLogin, submitLoginCode } from './byo-login.js';
@@ -58,78 +60,6 @@ import { createServeGitHooks, createServeMarkerPoll } from './cloudGitServe.js';
58
60
  import { deckCollaborators, reportDeckEditorPresence, } from './api.js';
59
61
  export const AGENT_WS_PATH = '/__castle/agent';
60
62
  const PRESENCE_INTERVAL_MS = 15_000;
61
- const DEFAULT_SETTINGS = {
62
- // Both roles run the claude CLI routed through OpenRouter at the slug below.
63
- // Note this takes the Anthropic credential out of play entirely: a role on
64
- // "openrouter" resolves OpenRouter auth, so a user's `claude /login` or
65
- // ANTHROPIC_API_KEY no longer applies (see buildAgentInvocation) -- which is
66
- // exactly why a user who HAS one defaults to ANTHROPIC_DEFAULT_MODELS below.
67
- routerClaudeModel: 'openrouter',
68
- tasksClaudeModel: 'openrouter',
69
- // Free-form -- change to any OpenRouter slug. Both roles default to the
70
- // model Castle pays for (the proxy's freeModelPrefixes list), so an editor
71
- // that has never touched settings costs the user nothing and never runs into
72
- // a credit balance -- see freeTierForRoles / the free-model skip in
73
- // castleSpendRefusal. Picking any other slug puts that role back on credits.
74
- routerOpenrouterModel: 'meta/muse-spark-1.3-contributor',
75
- tasksOpenrouterModel: 'meta/muse-spark-1.3-contributor',
76
- routerEffort: 'medium',
77
- tasksEffort: 'medium',
78
- };
79
- // What the two claude-model defaults become once the user has an Anthropic
80
- // credential of their own -- a key or a claude.ai login, which
81
- // resolveAnthropicAuth already treats as one question. Signing in has to move
82
- // these or it buys the user nothing: the openrouter default never resolves
83
- // Anthropic auth, so an account added in the Accounts modal would sit unused
84
- // (and the runs stay metered) until the user also found the model picker.
85
- const ANTHROPIC_DEFAULT_MODELS = {
86
- routerClaudeModel: 'opus',
87
- tasksClaudeModel: 'sonnet',
88
- };
89
- // Resolved per read rather than captured once: the credential this asks about
90
- // appears and disappears mid-session (the Accounts modal, `claude /login` in
91
- // the terminal panel, a hand-edited user-keys.json), and
92
- // refreshDefaultedSettings re-reads it when it does.
93
- // The effort a role starts at for a given model. Tasks on a muse model start
94
- // at low: castle-agent-evals/muse-tune measured medium as slower with more api
95
- // guessing. The operator stays at medium on every model, and claude models
96
- // stay at medium for both roles. A level the user picks is stored and stands.
97
- function defaultEffortFor(role, claudeModel, openrouterModel) {
98
- return role === 'tasks' && claudeModel === 'openrouter' && isMuseModel(openrouterModel) ? 'low' : 'medium';
99
- }
100
- const EFFORT_ROLES = [
101
- { role: 'router', label: 'operator', claude: 'routerClaudeModel', slug: 'routerOpenrouterModel', effort: 'routerEffort' },
102
- { role: 'tasks', label: 'tasks', claude: 'tasksClaudeModel', slug: 'tasksOpenrouterModel', effort: 'tasksEffort' },
103
- ];
104
- function defaultSettings() {
105
- const models = resolveAnthropicAuth().mode === 'proxy'
106
- ? { ...DEFAULT_SETTINGS }
107
- : { ...DEFAULT_SETTINGS, ...ANTHROPIC_DEFAULT_MODELS };
108
- return {
109
- ...models,
110
- routerEffort: defaultEffortFor('router', models.routerClaudeModel, models.routerOpenrouterModel),
111
- tasksEffort: defaultEffortFor('tasks', models.tasksClaudeModel, models.tasksOpenrouterModel),
112
- };
113
- }
114
- // Bump to force every deck onto the current DEFAULT_SETTINGS once, discarding
115
- // what users had chosen: a stored file below this epoch has ALL of its setting
116
- // fields dropped on load (see loadAgentSettings). Bump ONLY when a default
117
- // change is meant to override existing choices -- an ordinary one needs no
118
- // bump, since sparse storage already reaches anyone who never set that field.
119
- // The wipe is also what retires older file shapes, so a migration for one is
120
- // only worth writing if it must survive the epoch that introduces it.
121
- //
122
- // 2: the OpenRouter default moved to the model Castle pays for. Deliberately a
123
- // bump rather than an ordinary default change -- decks that had already stored
124
- // a slug (including the one that was the default when they stored it) would
125
- // otherwise keep spending credits on a metered model while every user around
126
- // them runs free.
127
- const SETTINGS_EPOCH = 2;
128
- function normalizeClaudeModel(value) {
129
- return value === 'sonnet' || value === 'opus' || value === 'fable' || value === 'openrouter'
130
- ? value
131
- : null;
132
- }
133
63
  // A claude run is spawned with an alias (`--model fable`) but reaches the proxy
134
64
  // as a concrete id (`claude-fable-5`), and it is the ids the proxy refuses. This
135
65
  // is the one place that knows both, so the model picker and the pre-flight
@@ -147,111 +77,15 @@ function claudeModelBlocked(model, budget) {
147
77
  return false;
148
78
  return budget.blockedModelPrefixes.some((p) => p.startsWith(id) || id.startsWith(p));
149
79
  }
150
- // Free-form, so validation is just "non-empty, not absurdly long" (guards
151
- // against a stray huge paste landing in settings.json / the CLI argv).
152
- const OPENROUTER_MODEL_MAX_LEN = 200;
153
- function normalizeOpenrouterModel(value) {
154
- if (typeof value !== 'string')
155
- return null;
156
- const trimmed = value.trim();
157
- return trimmed && trimmed.length <= OPENROUTER_MODEL_MAX_LEN ? trimmed : null;
158
- }
159
- function normalizeEffort(value) {
160
- return value === 'low' ||
161
- value === 'medium' ||
162
- value === 'high' ||
163
- value === 'xhigh' ||
164
- value === 'max'
165
- ? value
166
- : null;
167
- }
168
- // Every setting's validator, keyed the same as AgentSettings, so load and save
169
- // iterate one list rather than repeating the field names per direction.
170
- const SETTING_NORMALIZERS = {
171
- routerClaudeModel: normalizeClaudeModel,
172
- tasksClaudeModel: normalizeClaudeModel,
173
- routerOpenrouterModel: normalizeOpenrouterModel,
174
- tasksOpenrouterModel: normalizeOpenrouterModel,
175
- routerEffort: normalizeEffort,
176
- tasksEffort: normalizeEffort,
177
- };
178
- const SETTING_KEYS = Object.keys(SETTING_NORMALIZERS);
179
- // Sparse ON PURPOSE: only fields that DIFFER from the current defaults are
180
- // stored, so "absent" means "follow the default" and a later default change
181
- // reaches every deck that never set that field. Writing the full object
182
- // instead (as this once did) froze every setting the first time a user
183
- // touched any one of them, pinning models nobody had chosen.
184
- //
185
- // The flip side, accepted: re-selecting the value that is currently the
186
- // default stores nothing, so that deck moves when the default moves. Nothing
187
- // is lost relative to the old behavior -- applyAgentSettings already
188
- // early-returns on a no-op change, so that click never persisted anything.
189
- // Since defaultSettings() reads the Anthropic credential, "the default moves"
190
- // now includes signing out: a role left on what was the signed-in default
191
- // falls back to openrouter rather than sitting on a claude alias with no
192
- // Anthropic account behind it.
193
- function serializeAgentSettings(settings) {
194
- const defaults = defaultSettings();
195
- const out = { settingsEpoch: SETTINGS_EPOCH };
196
- for (const key of SETTING_KEYS) {
197
- if (settings[key] !== defaults[key])
198
- out[key] = settings[key];
199
- }
200
- // Effort's default follows the role's stored model, not the default model.
201
- for (const role of EFFORT_ROLES) {
202
- const value = settings[role.effort];
203
- if (value === defaultEffortFor(role.role, settings[role.claude], settings[role.slug])) {
204
- delete out[role.effort];
205
- }
206
- else {
207
- out[role.effort] = value;
208
- }
209
- }
210
- return JSON.stringify(out, null, 2) + '\n';
211
- }
212
- function loadAgentSettings(settingsPath) {
213
- const defaults = defaultSettings();
214
- const stored = readJsonFile(settingsPath);
215
- const storedEpoch = typeof stored?.settingsEpoch === 'number' ? stored.settingsEpoch : 0;
216
- // A stale file is ignored, not rewritten: leaving it means the wipe is a
217
- // pure read-side decision that repeats harmlessly until the user's next real
218
- // change overwrites it in the sparse shape. A newer epoch (a downgraded CLI
219
- // reading a file from a newer one) is honored rather than wiped.
220
- if (!stored || storedEpoch < SETTINGS_EPOCH)
221
- return defaults;
222
- const overrides = {};
223
- for (const key of SETTING_KEYS) {
224
- if (!(key in stored))
225
- continue;
226
- const value = SETTING_NORMALIZERS[key](stored[key]);
227
- if (value !== null)
228
- overrides[key] = value;
229
- }
230
- const merged = { ...defaults, ...overrides };
231
- for (const role of EFFORT_ROLES) {
232
- if (role.effort in overrides) {
233
- continue;
234
- }
235
- merged[role.effort] = defaultEffortFor(role.role, merged[role.claude], merged[role.slug]);
236
- }
237
- return merged;
238
- }
239
- // Re-resolve the defaults into the live settings object after a credential
240
- // change, in place because every consumer (the router queue, the task store)
241
- // holds this same object. Only fields the stored file leaves unset can move --
242
- // loadAgentSettings layers it back over the new defaults -- so a choice the
243
- // user actually made is never overwritten. Returns whether anything moved, so
244
- // the caller only broadcasts a real change.
245
- function refreshDefaultedSettings(settings, settingsPath) {
246
- const next = loadAgentSettings(settingsPath);
247
- let changed = false;
248
- for (const key of SETTING_KEYS) {
249
- if (settings[key] === next[key])
250
- continue;
251
- Object.assign(settings, { [key]: next[key] });
252
- 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;
253
86
  }
254
- return changed;
87
+ Object.assign(settings, next);
88
+ return true;
255
89
  }
256
90
  // Base for OpenRouter's Anthropic-compatible endpoint (confirmed current, 2026: it
257
91
  // accepts the standard Anthropic Messages API shape -- text/tool-use/extended-thinking
@@ -1808,23 +1642,40 @@ function blockedClaudeModels(budget) {
1808
1642
  return [];
1809
1643
  return PICKER_CLAUDE_MODELS.filter((m) => claudeModelBlocked(m, budget));
1810
1644
  }
1811
- function usageFrame(budget, credits, settings) {
1812
- 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')
1813
1650
  return null;
1651
+ const prefixes = budget?.freeModelPrefixes ?? [];
1814
1652
  return {
1815
- usedMicros: budget.usedMicros,
1816
- limitMicros: budget.limitMicros,
1817
- spendableMicros: spendableMicros(budget),
1818
- resetAtMs: budget.resetAtMs,
1819
- 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,
1820
1658
  credits,
1821
- creditsExhausted: castleCreditsExhausted(budget, credits),
1822
- blockedClaudeModels: blockedClaudeModels(budget),
1823
- freeTier: freeTierForRoles(roleSpends(settings), budget.freeModelPrefixes),
1824
- freeModel: runIsCastlePaid('openrouter', null)
1825
- ? (budget.freeModelPrefixes[0] ?? null)
1826
- : null,
1827
- 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,
1828
1679
  };
1829
1680
  }
1830
1681
  /**
@@ -1833,12 +1684,8 @@ function usageFrame(budget, credits, settings) {
1833
1684
  * Outside a sandbox fetchBudget answers null forever, so nothing is ever sent
1834
1685
  * and the shell simply has no bar to show.
1835
1686
  *
1836
- * Null is a value here, not just "no answer yet": a user running on their own
1837
- * credential is told nothing about Castle's budget, because none of their
1838
- * runs spend it and none of them are gated on it -- showing the bar (worse, a
1839
- * spent-out red one) would describe a limit that doesn't apply to them. It has
1840
- * to be broadcast rather than merely withheld, so the bar clears when a
1841
- * 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.
1842
1689
  */
1843
1690
  function createUsageFeed(opts) {
1844
1691
  let latest = null;
@@ -1846,33 +1693,29 @@ function createUsageFeed(opts) {
1846
1693
  let budget = null;
1847
1694
  let budgetPolls = 0;
1848
1695
  let stopped = false;
1696
+ let experiment = null;
1697
+ let experimentRevision = 0;
1698
+ let pendingEvents = Promise.resolve();
1699
+ const fallback = createFallbackNotice();
1849
1700
  async function readUsage(refreshCredits = false, allowFollowUp = true) {
1850
- const settings = opts.settings();
1851
- // Cached credits and budget survive a spell on the user's own keys: when a
1852
- // role comes back to Castle's, recompute() can publish a credits-plan frame
1853
- // at once instead of the legacy daily meter, and the refresh reconciles.
1854
- if (!anyRoleIsCastlePaid(settings)) {
1855
- return { usage: null, refreshAfterMs: null, allowFollowUp };
1856
- }
1857
- // Budget is the authoritative spendable amount and its read can force a
1858
- // stale proxy gate to sync after a purchase. Read credits second so the
1859
- // descriptive fields (plan, rate, reload state) describe that same or a
1860
- // newer account snapshot instead of racing ahead of the gate refresh.
1861
- // Only a full credit-state refresh asks the host to sync its held budget. Cheap polls and
1862
- // spend preflight stay local to the proxy, so control-plane health cannot delay a run.
1863
- const nextBudget = await fetchBudget(refreshCredits);
1864
- if (nextBudget)
1865
- budget = nextBudget;
1866
- if (refreshCredits) {
1867
- const nextCredits = await fetchAiCredits();
1868
- // Once the richer field has loaded, a transient GraphQL failure should
1869
- // not erase it and fall the UI back to the legacy daily presentation.
1870
- if (nextCredits)
1871
- credits = nextCredits;
1872
- }
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 };
1873
1715
  return {
1874
- usage: usageFrame(nextBudget, credits, settings),
1875
- refreshAfterMs: nextBudget?.refreshAfterMs ?? null,
1716
+ ...await read,
1717
+ experiment: nextExperiment,
1718
+ experimentRevision: revision,
1876
1719
  allowFollowUp,
1877
1720
  };
1878
1721
  }
@@ -1882,28 +1725,59 @@ function createUsageFeed(opts) {
1882
1725
  latest = next;
1883
1726
  opts.broadcast({ type: 'usage', usage: next });
1884
1727
  }
1885
- function publishRead(read) {
1728
+ function recompute(frameBudget = budget) {
1886
1729
  if (stopped)
1887
1730
  return;
1888
- publishUsage(read.usage);
1889
- if (!read.allowFollowUp || read.refreshAfterMs === null)
1890
- return;
1891
- 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()));
1892
1734
  }
1893
- function recompute() {
1735
+ function syncDefaults(frameBudget = budget) {
1894
1736
  if (stopped)
1895
1737
  return;
1896
- const settings = opts.settings();
1897
- if (!anyRoleIsCastlePaid(settings)) {
1898
- 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)
1899
1752
  return;
1900
- }
1901
- 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)
1902
1768
  return;
1903
- // Settings-dependent fields must not wait on the network: the client
1904
- // renders both the picker and the credits guard from them, and a settings
1905
- // frame is about to follow this usage frame.
1906
- 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(() => { });
1907
1781
  }
1908
1782
  // Focus, host relay, popover-open and run-finished can all arrive together.
1909
1783
  const refreshQueue = createRefreshQueue({ read: readUsage, publish: publishRead });
@@ -1927,10 +1801,20 @@ function createUsageFeed(opts) {
1927
1801
  refresh();
1928
1802
  return {
1929
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
+ },
1930
1813
  // The budget outlives a switch to the user's own OpenRouter key; the chip
1931
1814
  // stops saying Muse then (usageFrame's freeModel), so the router must too.
1932
1815
  freeModelPrefixes: () => runIsCastlePaid('openrouter', null) ? (budget?.freeModelPrefixes ?? []) : [],
1933
- recompute,
1816
+ syncDefaults,
1817
+ event,
1934
1818
  refresh,
1935
1819
  stop: () => {
1936
1820
  stopped = true;
@@ -4923,13 +4807,19 @@ function runRouterTurnIn(ctx, instruction) {
4923
4807
  let lastActivity = 'Thinking';
4924
4808
  ctx.broadcast({ type: 'message-activity', id: message.id, activity: 'Thinking' });
4925
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());
4926
4816
  void runAgentTurn({
4927
4817
  role: 'router',
4928
4818
  playtestTool: false,
4929
4819
  prompt: prompt.user,
4930
4820
  systemPrompt: prompt.system,
4931
- claudeModel: ctx.claudeModel(),
4932
- openrouterModel: ctx.openrouterModel(),
4821
+ claudeModel,
4822
+ openrouterModel,
4933
4823
  effort: ctx.effort(),
4934
4824
  cwd: ctx.deckDir,
4935
4825
  timeoutMs: ROUTER_TIMEOUT_MS,
@@ -5048,6 +4938,8 @@ function runRouterTurnIn(ctx, instruction) {
5048
4938
  // messages.json or a replayed transcript.
5049
4939
  errorVerbose,
5050
4940
  });
4941
+ if (result.ok && !stale && freeReply())
4942
+ ctx.onFreeReply(openrouterModel);
5051
4943
  }
5052
4944
  catch (err) {
5053
4945
  // Surface the failure in the UI instead of silently hanging: mark the
@@ -5131,9 +5023,18 @@ function applyAgentSettings(incoming, ctx) {
5131
5023
  changes.push(`${role.label} effort -> ${value} (default for this model)`);
5132
5024
  }
5133
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);
5134
5036
  if (changes.length === 0)
5135
5037
  return;
5136
- atomicWriteFileSync(ctx.settingsPath, serializeAgentSettings(settings));
5137
5038
  // Publish recomputed usage first. Muse -> OpenRouter stays Muse while the old
5138
5039
  // slug still equals the free model, then the settings frame flips it;
5139
5040
  // OpenRouter -> Muse flips at once through freeRoles, and settings agrees.
@@ -5476,6 +5377,7 @@ function startRouterTurn(ctx, instruction) {
5476
5377
  taskOpenrouterModel: () => ctx.settings.tasksOpenrouterModel,
5477
5378
  taskEffort: () => ctx.settings.tasksEffort,
5478
5379
  freeModelPrefixes: ctx.freeModelPrefixes,
5380
+ onFreeReply: ctx.onFreeReply,
5479
5381
  canAutoRetry: () => !ctx.state.autoRetryUsed && ctx.state.pendingSends.length === 0,
5480
5382
  onSettled: (retryable) => onRouterQueueSettled(ctx, retryable),
5481
5383
  }, instruction);
@@ -5951,22 +5853,36 @@ export function createAgentServer(opts) {
5951
5853
  // Which CLI backs the router and the task agents -- independently
5952
5854
  // switchable from the settings popover, persisted next to the chat state.
5953
5855
  const settingsPath = path.join(agentDir, 'settings.json');
5954
- const settings = loadAgentSettings(settingsPath);
5856
+ let proxied = resolveAnthropicAuth().mode === 'proxy';
5857
+ let paidDefault = null;
5858
+ const settings = resolveAgentSettings(readJsonFile(settingsPath), proxied, paidDefault);
5955
5859
  const usageFeed = createUsageFeed({
5956
5860
  broadcast,
5957
5861
  hasClients: () => clients.size > 0,
5958
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
+ },
5959
5880
  });
5960
5881
  const accountsFeed = createAccountsFeed({
5961
5882
  broadcast,
5962
5883
  hasClients: () => clients.size > 0,
5963
5884
  onCredentialChange: () => {
5964
- // Signing in moves the claude-model default (see defaultSettings), and
5965
- // nothing else pushes a settings frame -- without this the popover keeps
5966
- // showing the model the page loaded with until a reload.
5967
- if (refreshDefaultedSettings(settings, settingsPath)) {
5968
- broadcast({ type: 'settings', settings });
5969
- }
5885
+ usageFeed.syncDefaults();
5970
5886
  usageFeed.refresh();
5971
5887
  },
5972
5888
  });
@@ -5974,9 +5890,20 @@ export function createAgentServer(opts) {
5974
5890
  applyAgentSettings(incoming, {
5975
5891
  settings,
5976
5892
  settingsPath,
5893
+ defaults: defaultSettings(resolveAnthropicAuth().mode === 'proxy', paidDefault),
5894
+ arm: experimentArm(usageFeed.latest()?.experiment),
5977
5895
  broadcast,
5978
- onChanged: () => usageFeed.recompute(),
5896
+ onChanged: () => usageFeed.syncDefaults(),
5979
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
+ }
5980
5907
  // The synchronous recompute makes settings-derived fields immediate; the
5981
5908
  // network read still reconciles the balance and dedups an unchanged frame.
5982
5909
  usageFeed.refresh();
@@ -6025,6 +5952,7 @@ export function createAgentServer(opts) {
6025
5952
  const routerQueue = createRouterQueue({
6026
5953
  deckDir,
6027
5954
  freeModelPrefixes: usageFeed.freeModelPrefixes,
5955
+ onFreeReply: (model) => usageFeed.event('free_model_reply', { role: 'router', model }),
6028
5956
  deckLabel,
6029
5957
  agentDir,
6030
5958
  attachmentsDir,
@@ -6106,6 +6034,7 @@ export function createAgentServer(opts) {
6106
6034
  }
6107
6035
  function attachClient(socket) {
6108
6036
  clients.add(socket);
6037
+ let exposed = false;
6109
6038
  const hello = {
6110
6039
  type: 'hello',
6111
6040
  messages: messages
@@ -6193,6 +6122,21 @@ export function createAgentServer(opts) {
6193
6122
  if (setPlaytestPref(deckDir, msg.value))
6194
6123
  broadcast(deckPrefsFrame(deckDir));
6195
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
+ }
6196
6140
  else if (msg.type === 'refresh-usage') {
6197
6141
  usageFeed.refresh();
6198
6142
  }