castle-web-cli 0.4.220 → 0.4.221

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.
@@ -1448,42 +1448,41 @@ const DECKS_PLAYLISTS_QUERY = `
1448
1448
  // ---------------------------------------------------------------------------
1449
1449
  // Agent chat.
1450
1450
  //
1451
- // The oracle is Castle's proxy to OpenRouter. It answers with a server-sent
1452
- // event stream: its own `{ castle }` header, a heartbeat event every 15
1453
- // seconds, OpenRouter's chunks, and `[DONE]`. The executor reads the stream as
1454
- // it arrives, passes text, reasoning and finished tool calls on to the deck,
1455
- // and resolves with the whole message. The oracle does not refuse a non-admin;
1456
- // it swaps in its own model. The admin check is made here, before the request.
1457
- const ORACLE_CHAT_URL = "https://oracle-server.castle.xyz/chat/completions";
1458
- const AGENT_DEFAULT_MODEL = "meta/muse-spark-1.3";
1459
- // Three missed heartbeats; the oracle sends one every 15 seconds.
1451
+ // The deck-agent service is Castle's proxy to OpenRouter for decks. It decides
1452
+ // who may call a model (Castle admins, for now), picks the default model, and
1453
+ // charges each call to the player's daily play allowance, which Castle funds.
1454
+ // It refuses before streaming with a status: 403 for a player it will not
1455
+ // serve, 429 once the allowance is spent. Otherwise it answers with a
1456
+ // server-sent event stream: OpenRouter's chunks, a heartbeat event every 15
1457
+ // seconds, and `[DONE]`. The executor reads the stream as it arrives, passes
1458
+ // text, reasoning and finished tool calls on to the deck, and resolves with
1459
+ // the whole message.
1460
+ const DECK_AGENT_CHAT_URL = "https://deck-agent.castle.xyz/chat/completions";
1461
+ // Three missed heartbeats; the service sends one every 15 seconds.
1460
1462
  const ORACLE_SILENCE_MS = 45_000;
1461
1463
  // Text and reasoning pieces are sent to the deck in batches this far apart. A
1462
1464
  // model sends a piece every few milliseconds, and each post to a mobile deck
1463
1465
  // is a call into its WebView.
1464
1466
  const DELTA_BATCH_MS = 40;
1465
- // The oracle's own admin test. `me.isAdmin` is moderator status, a wider group.
1467
+ // The Castle admin test. `me.isAdmin` is moderator status, a wider group.
1466
1468
  const AGENT_ADMIN_QUERY = `
1467
1469
  query { me { castleUserGroups { isAdmin } } }
1468
1470
  `;
1469
1471
  async function agentChat(ctx, params, caps, options) {
1470
- const openrouter = agentChatRequest(params);
1472
+ const request = agentChatRequest(params);
1471
1473
  if (!caps.oracleStream) {
1472
- return { status: "unavailable", reason: "This host has no route to the Castle oracle." };
1474
+ return { status: "unavailable", reason: "This host has no route to the deck-agent service." };
1473
1475
  }
1474
1476
  try {
1475
- if (!(await isCastleAdmin(caps.graphqlFetch, "agent.chat"))) {
1476
- return { status: "refused", reason: "Agent.chat is limited to Castle admins." };
1477
- }
1478
- const body = { openrouter, castle: { mode: "deck-agent", deckId: ctx.deckId } };
1477
+ const body = { request, deckId: ctx.deckId };
1479
1478
  return await streamAgentReply(caps.oracleStream, JSON.stringify(body), options);
1480
1479
  }
1481
1480
  catch (error) {
1482
1481
  return { status: "error", reason: error instanceof Error ? error.message : String(error) };
1483
1482
  }
1484
1483
  }
1485
- // The OpenRouter body. The oracle raises `max_tokens` to its own ceiling for
1486
- // admins, whatever is sent.
1484
+ // The request as the deck-agent service takes it. The service picks the model
1485
+ // when the deck names none, and applies its own limits.
1487
1486
  function agentChatRequest(params) {
1488
1487
  const command = "agent.chat";
1489
1488
  if (!Array.isArray(params.messages) || params.messages.length === 0) {
@@ -1492,22 +1491,21 @@ function agentChatRequest(params) {
1492
1491
  if (params.tools !== undefined && params.tools !== null && !Array.isArray(params.tools)) {
1493
1492
  throw new HostCommandError("INVALID_ARGUMENT", "agent.chat tools must be an array.", command);
1494
1493
  }
1495
- const request = {
1496
- model: asOptionalString(params.model) ?? AGENT_DEFAULT_MODEL,
1497
- messages: params.messages,
1498
- stream: true,
1499
- usage: { include: true },
1500
- };
1494
+ const request = { messages: params.messages };
1495
+ const model = asOptionalString(params.model);
1496
+ if (model !== null) {
1497
+ request.model = model;
1498
+ }
1501
1499
  if (Array.isArray(params.tools) && params.tools.length > 0) {
1502
1500
  request.tools = params.tools;
1503
1501
  }
1504
1502
  const toolChoice = params.toolChoice;
1505
1503
  if (typeof toolChoice === "string" || (typeof toolChoice === "object" && toolChoice !== null)) {
1506
- request.tool_choice = toolChoice;
1504
+ request.toolChoice = toolChoice;
1507
1505
  }
1508
1506
  const maxTokens = asOptionalNumber(params.maxTokens);
1509
1507
  if (maxTokens !== null) {
1510
- request.max_tokens = Math.floor(maxTokens);
1508
+ request.maxTokens = Math.floor(maxTokens);
1511
1509
  }
1512
1510
  const effort = params.reasoning?.effort;
1513
1511
  if (effort === "minimal" || effort === "low" || effort === "medium" || effort === "high") {
@@ -1563,7 +1561,7 @@ function streamAgentReply(oracleStream, body, options) {
1563
1561
  }
1564
1562
  signal?.addEventListener("abort", onAbort);
1565
1563
  restartSilence();
1566
- const abort = oracleStream(ORACLE_CHAT_URL, body, {
1564
+ const abort = oracleStream(DECK_AGENT_CHAT_URL, body, {
1567
1565
  event(name, data) {
1568
1566
  if (settled) {
1569
1567
  return;
@@ -1574,7 +1572,7 @@ function streamAgentReply(oracleStream, body, options) {
1574
1572
  }
1575
1573
  else if (name === "message") {
1576
1574
  applyOracleEvent(reply, outbox, parseOracleEvent(data));
1577
- // The oracle ends the body after an error chunk, with no `[DONE]`. A
1575
+ // The service ends the body after an error chunk, with no `[DONE]`. A
1578
1576
  // host whose stream cannot report the end of the body would wait
1579
1577
  // out ORACLE_SILENCE_MS.
1580
1578
  if (reply.error) {
@@ -1585,11 +1583,13 @@ function streamAgentReply(oracleStream, body, options) {
1585
1583
  sendKeepalive(outbox);
1586
1584
  }
1587
1585
  },
1586
+ // A reply is whole only once `[DONE]` arrives; an earlier end of the
1587
+ // body is a cut connection, even after the model's finish reason.
1588
1588
  end() {
1589
- finish(agentChatResult(reply, outbox));
1589
+ finish({ status: "error", reason: "The model stream ended before the reply finished." });
1590
1590
  },
1591
1591
  fail(status, text) {
1592
- finish({ status: "error", reason: oracleErrorReason(status, text) });
1592
+ finish(failedAgentReply(status, text));
1593
1593
  },
1594
1594
  });
1595
1595
  // The sink can finish before oracleStream returns, on a request that fails
@@ -1611,28 +1611,45 @@ function parseOracleEvent(data) {
1611
1611
  return null;
1612
1612
  }
1613
1613
  }
1614
- // The oracle's own failures are JSON with an `error` string: a bad token, no
1615
- // credits left, or the model provider failing before the stream began.
1616
- function oracleErrorReason(status, text) {
1617
- if (status === 0) {
1618
- return `Could not reach the Castle oracle: ${text}`;
1619
- }
1614
+ // The service's refusals come before the stream, as a status and a JSON body
1615
+ // with an `error` string: 403 for a player it will not serve, 429 once the
1616
+ // player's play allowance for the day is spent, 503 when it cannot reach what
1617
+ // it needs. Status 0 is a request that never got a response.
1618
+ function failedAgentReply(status, text) {
1619
+ let error = null;
1620
+ let message = null;
1620
1621
  try {
1621
1622
  const body = JSON.parse(text);
1622
- if (typeof body.error === "string") {
1623
- return `oracle ${status}: ${body.error}`;
1624
- }
1623
+ error = typeof body.error === "string" ? body.error : null;
1624
+ message = typeof body.message === "string" ? body.message : null;
1625
1625
  }
1626
1626
  catch {
1627
1627
  // not JSON
1628
1628
  }
1629
- return `oracle ${status}`;
1629
+ if (status === 403) {
1630
+ return { status: "refused", reason: "Agent.chat is limited to Castle admins." };
1631
+ }
1632
+ if (status === 429 && error === "allowance_exhausted") {
1633
+ return {
1634
+ status: "allowance_exhausted",
1635
+ reason: "The player's play allowance for today is used up.",
1636
+ };
1637
+ }
1638
+ if (status === 0) {
1639
+ return { status: "unavailable", reason: `Could not reach the deck-agent service: ${text}` };
1640
+ }
1641
+ if (status === 503) {
1642
+ return { status: "unavailable", reason: "The deck-agent service is unavailable." };
1643
+ }
1644
+ const detail = message ?? error;
1645
+ const reason = detail ? `deck-agent ${status}: ${detail}` : `deck-agent ${status}`;
1646
+ return { status: "error", reason };
1630
1647
  }
1631
1648
  function applyOracleEvent(reply, outbox, event) {
1632
1649
  if (!event) {
1633
1650
  return;
1634
1651
  }
1635
- // The oracle's header comes first, before the model has said anything.
1652
+ // A `{ castle }` header, which the oracle sent before the model said anything.
1636
1653
  if (event.castle) {
1637
1654
  sendKeepalive(outbox);
1638
1655
  return;
package/dist/init.js CHANGED
@@ -54,7 +54,7 @@ if (!(await mountEditorRoute())) startGame(initCard());
54
54
  // Registry version of castle-web-sdk to inject when scaffolding from a
55
55
  // globally-installed castle-web (not from inside the workspace). Bumped
56
56
  // alongside cli/sdk version bumps.
57
- const PUBLISHED_SDK_VERSION = '0.4.40';
57
+ const PUBLISHED_SDK_VERSION = '0.4.41';
58
58
  // Range, not a pin: `castle-web-fonts` is its own package precisely so a tenth
59
59
  // face can ship without a cli release, and a caret range means an existing
60
60
  // deck's next install picks it up. Nothing here has to move when it does.
@@ -15,7 +15,7 @@ that framework provides. This one is true either way.
15
15
  <!-- Injected into Castle's create assistant every turn; keep this compact and factual. -->
16
16
 
17
17
  - `import { setup, initCard } from 'castle-web-sdk'`. Call `setup()` first, once; `initCard()` returns the element to render into (a React tree mounted at `#root` needs no `initCard`). Castle services — `Store`, `Leaderboard`, `Time`, `User`, `Haptics`, `Pass`, `Snapshot`, `Portal`, `Multiplayer`, `Lifecycle` — come from the same package. `Store` is how a deck saves anything; the older `Storage`/`SharedStorage` still work but should not be used in new decks; the full reference is `imports/castle.base/sdk/README.md`.
18
- - `Agent.chat({ messages, tools?, toolChoice?, model?, maxTokens?, reasoning?, onDelta?, signal? })` gets one chat completion from a language model (OpenAI message and tool format, default model `meta/muse-spark-1.3`) through Castle's oracle on the player's account. `onDelta` streams text and reasoning pieces and each finished tool call; `signal` cancels; `reasoning: { effort: 'minimal' | 'low' | 'medium' | 'high' }` sets how hard the model thinks, and minimal answers soonest. It resolves with the whole `message`: the deck runs any `tool_calls` itself, appends the message and the `tool` results, and calls again. Admin only: other players get `refused`.
18
+ - `Agent.chat({ messages, tools?, toolChoice?, model?, maxTokens?, reasoning?, onDelta?, signal? })` gets one chat completion from a language model (OpenAI message and tool format, default model `meta/muse-spark-1.3-contributor`; also `meta/muse-spark-1.3` or `openai/gpt-4.1-mini`) through Castle's deck-agent service, paid from the player's daily play allowance that characters share. `onDelta` streams text and reasoning pieces and each finished tool call; `signal` cancels; `reasoning: { effort: 'minimal' | 'low' | 'medium' | 'high' }` sets how hard the model thinks, and minimal answers soonest. It resolves with the whole `message`: the deck runs any `tool_calls` itself, appends the message and the `tool` results, and calls again. Admin only: other players get `refused`; a player whose allowance for the day is spent gets `allowance_exhausted` (it resets at midnight UTC).
19
19
  - `Decks.mine({ limit? })` and `Decks.saved({ limit? })` list decks a portal can lead to (the player's published decks; their bookmarks and playlists) as `{ deckId, title, creator, coverUrl }`, with `coverUrl` a `data:` url. Use them to offer a portal destination picker. Admin only: other players get a `PERMISSION_DENIED` error.
20
20
  - What each service cannot do is in that README beside the service: `Store` / `Storage` size caps (no media in storage), the Castle app build a command needs (older builds reject it with `UNKNOWN_COMMAND`), no clipboard command, no call that sets the deck's cover. Read it before telling someone a service can or cannot do something.
21
21
  - The SDK is a file of this import, not an npm package: `castle-web-sdk` resolves here. Nothing needs installing, and nothing in a deck's `package.json` names it.
@@ -82,7 +82,7 @@
82
82
  "title": "base",
83
83
  "deckId": "yRcmH4_aYllE",
84
84
  "cardId": "zkFdingmIm3m",
85
- "publishedVersion": "2026-09-27T19:36:03.837Z",
85
+ "publishedVersion": "2026-09-27T20:21:21.082Z",
86
86
  "provides": [
87
87
  "castle-web-sdk"
88
88
  ]
@@ -14,7 +14,7 @@
14
14
  },
15
15
  "../../sdk": {
16
16
  "name": "castle-web-sdk",
17
- "version": "0.4.40",
17
+ "version": "0.4.41",
18
18
  "dev": true,
19
19
  "devDependencies": {
20
20
  "eslint": "^9.0.0",
@@ -731,9 +731,11 @@ be coalesced, so it's safe to call on frequent events.
731
731
  ## Agent
732
732
 
733
733
  `Agent` asks a language model for one chat completion. The host sends it
734
- through Castle's oracle on the player's own Castle account, so the deck
735
- holds no key. Agent.chat is limited to Castle admins for now; every other
736
- player gets `'refused'`.
734
+ through Castle's deck-agent service, so the deck holds no key. Castle pays
735
+ for each player's calls out of a daily play allowance, which Castle
736
+ characters draw from too; once a player has used it up, calls resolve
737
+ `'allowance_exhausted'` until it resets at midnight UTC. Agent.chat is
738
+ limited to Castle admins for now; every other player gets `'refused'`.
737
739
 
738
740
  ### `Agent.chat(params): Promise<AgentChatResult>`
739
741
 
@@ -745,9 +747,11 @@ player gets `'refused'`.
745
747
  - `tools` — optional function tools, in the OpenAI function-tool schema.
746
748
  - `toolChoice` — optional: `'auto'` (the default), `'none'`, `'required'`,
747
749
  or `{ type: 'function', function: { name } }` to force one tool.
748
- - `model` — optional OpenRouter model id. Defaults to
749
- `'meta/muse-spark-1.3'`.
750
- - `maxTokens` — optional cap on the reply's length.
750
+ - `model` — optional OpenRouter model id: `'meta/muse-spark-1.3-contributor'`
751
+ (the default), `'meta/muse-spark-1.3'` or `'openai/gpt-4.1-mini'`. Any
752
+ other model resolves `'error'`.
753
+ - `maxTokens` — optional cap on the reply's length. Defaults to 4096; the
754
+ service caps it at 16384.
751
755
  - `reasoning` — optional `{ effort: 'minimal' | 'low' | 'medium' | 'high' }`,
752
756
  how hard the model thinks before it answers. Lower effort answers sooner.
753
757
  Left out, the model uses its own default. Muse can't turn reasoning off;
@@ -819,9 +823,12 @@ for (let round = 0; round < 8; round++) {
819
823
  `'tool_calls'` or `'length'`. `usage` carries `prompt_tokens`,
820
824
  `completion_tokens` and `total_tokens`.
821
825
  - `'refused'` — the player is not a Castle admin. The model was not called.
822
- - `'unavailable'` — this host has no route to the oracle.
826
+ - `'allowance_exhausted'` — the player's play allowance for the day is used
827
+ up. The model was not called. It resets at midnight UTC.
828
+ - `'unavailable'` — this host has no route to the deck-agent service, or
829
+ the service is down.
823
830
  - `'cancelled'` — the call's `signal` was aborted.
824
- - `'error'` — the oracle or the model failed; `reason` says how.
831
+ - `'error'` — the service or the model failed; `reason` says how.
825
832
 
826
833
  Every status but `'ok'` carries a `reason`.
827
834
 
@@ -1,12 +1,15 @@
1
- // Agent — one chat completion from a language model, run by the host through
2
- // Castle's oracle with the player's own Castle account. Messages and tools
3
- // follow the OpenAI chat completions format. The reply streams: `onDelta` gets
4
- // text and reasoning as they arrive and each tool call once its arguments are
5
- // complete, and the promise resolves with the whole message. A deck runs any
6
- // tool calls itself and calls Agent.chat again with the results.
1
+ // Agent — one chat completion from a language model, run through Castle's
2
+ // deck-agent service. Castle funds each player's calls from a daily play
3
+ // allowance that characters share. Messages and tools follow the OpenAI chat
4
+ // completions format. The reply streams: `onDelta` gets text and reasoning as
5
+ // they arrive and each tool call once its arguments are complete, and the
6
+ // promise resolves with the whole message. A deck runs any tool calls itself
7
+ // and calls Agent.chat again with the results.
7
8
  //
8
9
  // Agent.chat is limited to Castle admins for now: every other player gets
9
- // `refused`. A host with no route to the oracle answers `unavailable`.
10
+ // `refused`. A player whose allowance for the day is spent gets
11
+ // `allowance_exhausted`. A host with no route to the service answers
12
+ // `unavailable`.
10
13
  import { CastleError } from "./errors";
11
14
  import { hostRequest } from "./transport";
12
15
  async function chat(params) {
@@ -255,7 +255,7 @@ export type AgentChatResult = {
255
255
  finishReason: string | null;
256
256
  usage?: AgentUsage;
257
257
  } | {
258
- status: "unavailable" | "refused" | "error" | "cancelled";
258
+ status: "unavailable" | "refused" | "allowance_exhausted" | "error" | "cancelled";
259
259
  reason: string;
260
260
  };
261
261
  export interface DeckSummary {
@@ -15,7 +15,7 @@ export const COMMAND_TIMEOUTS_MS = {
15
15
  "decks.saved": 30_000,
16
16
  };
17
17
  // Once a host streams a command, each stream envelope restarts the wait at this
18
- // length instead. The oracle sends a heartbeat every 15 seconds, and the host
18
+ // length instead. The deck-agent service sends a heartbeat every 15 seconds, and the host
19
19
  // passes each one on.
20
20
  export const STREAM_IDLE_TIMEOUT_MS = 60_000;
21
21
  export function isResponseEnvelope(value) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "castle-web-cli",
3
- "version": "0.4.220",
3
+ "version": "0.4.221",
4
4
  "repository": {
5
5
  "type": "git",
6
6
  "url": "git+https://github.com/castle-xyz/castle-experimental-web.git"