castle-web-cli 0.4.219 → 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.
- package/dist/agent.js +11 -1
- package/dist/api.d.ts +3 -1
- package/dist/api.js +16 -5
- package/dist/castle-host/host.js +58 -41
- package/dist/cloudGit.d.ts +7 -0
- package/dist/cloudGit.js +13 -1
- package/dist/cloudGitServe.d.ts +25 -0
- package/dist/cloudGitServe.js +62 -21
- package/dist/get-deck.d.ts +17 -0
- package/dist/get-deck.js +149 -0
- package/dist/index.js +15 -2
- package/dist/init.js +1 -1
- package/dist/save-deck.d.ts +6 -1
- package/dist/save-deck.js +66 -6
- package/dist/webSourceSync.d.ts +83 -0
- package/dist/webSourceSync.js +229 -0
- package/kits/base/CLAUDE.md +1 -1
- package/kits/base/castle.json +1 -1
- package/kits/base/package-lock.json +1 -1
- package/kits/base/sdk/README.md +15 -8
- package/kits/base/sdk/agent.js +10 -7
- package/kits/base/sdk/commands.d.ts +1 -1
- package/kits/base/sdk/commands.js +1 -1
- package/kits/base/sdk/server/platformHandle.d.ts +2 -0
- package/kits/base/sdk/server/wrapper.d.ts +34 -0
- package/kits/base/sdk/server/wrapper.js +154 -6
- package/package.json +1 -1
package/dist/agent.js
CHANGED
|
@@ -47,7 +47,7 @@ import { createPlaywrightPlaytestExecutor } from './native/playtest-executor.js'
|
|
|
47
47
|
import { createRemotePlaytestExecutor } from './native/playtest-remote.js';
|
|
48
48
|
import { runPlaytest, } from './native/playtest.js';
|
|
49
49
|
import { AGENT_ROLE_ENV, cloudGitMode } from './cloudGit.js';
|
|
50
|
-
import { createServeGitHooks } from './cloudGitServe.js';
|
|
50
|
+
import { createServeGitHooks, createServeMarkerPoll } from './cloudGitServe.js';
|
|
51
51
|
export const AGENT_WS_PATH = '/__castle/agent';
|
|
52
52
|
const DEFAULT_SETTINGS = {
|
|
53
53
|
// Both roles run the claude CLI routed through OpenRouter at the slug below.
|
|
@@ -4158,6 +4158,15 @@ export function createAgentServer(opts) {
|
|
|
4158
4158
|
routerBusy: () => routerQueue.isRunning(),
|
|
4159
4159
|
enqueueInstruction: (text) => routerQueue.handleUserMessage(text, undefined, undefined, undefined, true),
|
|
4160
4160
|
});
|
|
4161
|
+
// Markers that need no git (the saved copy of the deck is newer than this folder) become
|
|
4162
|
+
// router turns with git off too; with git on, the hooks above consume them.
|
|
4163
|
+
const markerPoll = gitHooks
|
|
4164
|
+
? null
|
|
4165
|
+
: createServeMarkerPoll({
|
|
4166
|
+
deckDir,
|
|
4167
|
+
addLog,
|
|
4168
|
+
enqueueInstruction: (text) => routerQueue.handleUserMessage(text, undefined, undefined, undefined, true),
|
|
4169
|
+
});
|
|
4161
4170
|
const taskStore = createTaskStore({
|
|
4162
4171
|
deckDir,
|
|
4163
4172
|
deckLabel,
|
|
@@ -4378,6 +4387,7 @@ export function createAgentServer(opts) {
|
|
|
4378
4387
|
}
|
|
4379
4388
|
function shutdown() {
|
|
4380
4389
|
gitHooks?.stop();
|
|
4390
|
+
markerPoll?.stop();
|
|
4381
4391
|
taskStore.shutdown();
|
|
4382
4392
|
for (const child of [...taskChildren, ...routerChildren]) {
|
|
4383
4393
|
try {
|
package/dist/api.d.ts
CHANGED
|
@@ -166,6 +166,8 @@ export declare function saveCauldronServerBundle(deckId: string, uploadId: strin
|
|
|
166
166
|
export interface WebDeckSource {
|
|
167
167
|
deckId: string;
|
|
168
168
|
archiveUrl: string;
|
|
169
|
+
/** Unique per saved version: every save mints a new one (webSourceSync.ts compares it). */
|
|
170
|
+
s3Key: string;
|
|
169
171
|
updatedAt: string;
|
|
170
172
|
}
|
|
171
173
|
export interface DeckMeta {
|
|
@@ -177,7 +179,7 @@ export interface DeckMeta {
|
|
|
177
179
|
}
|
|
178
180
|
export declare function deckMeta(deckId: string): Promise<DeckMeta | null>;
|
|
179
181
|
export declare function webDeckSource(deckId: string): Promise<WebDeckSource | null>;
|
|
180
|
-
export declare function saveWebDeckSource(deckId: string, uploadId: string): Promise<WebDeckSource>;
|
|
182
|
+
export declare function saveWebDeckSource(deckId: string, uploadId: string, expectedS3Key?: string | null): Promise<WebDeckSource>;
|
|
181
183
|
export type CloudDeckKit = 'PHYSICS_2D' | 'PHYSICS_3D' | 'MULTIPLAYER_2D' | 'MULTIPLAYER_3D' | 'TURN_BASED' | 'NONE';
|
|
182
184
|
export interface RegisteredCloudDeck {
|
|
183
185
|
deckId: string;
|
package/dist/api.js
CHANGED
|
@@ -286,18 +286,29 @@ export async function deckMeta(deckId) {
|
|
|
286
286
|
export async function webDeckSource(deckId) {
|
|
287
287
|
const data = await graphql(`query($deckId: ID!) {
|
|
288
288
|
webDeckSource(deckId: $deckId) {
|
|
289
|
-
deckId archiveUrl updatedAt
|
|
289
|
+
deckId archiveUrl s3Key updatedAt
|
|
290
290
|
}
|
|
291
291
|
}`, { deckId });
|
|
292
292
|
handleAPIError(data);
|
|
293
293
|
return pickData(data, 'webDeckSource');
|
|
294
294
|
}
|
|
295
|
-
|
|
296
|
-
|
|
295
|
+
// `expectedS3Key` is the save precondition: omitted (undefined) means no check, null means
|
|
296
|
+
// "there must be no saved source yet", and a key means "the saved source must still be this
|
|
297
|
+
// one" -- otherwise Ghost refuses with WEB_DECK_SOURCE_STALE. The argument is left out of the
|
|
298
|
+
// document entirely when omitted, so the request is exactly what older CLIs sent.
|
|
299
|
+
export async function saveWebDeckSource(deckId, uploadId, expectedS3Key) {
|
|
300
|
+
const checked = expectedS3Key !== undefined;
|
|
301
|
+
const data = await graphql(checked
|
|
302
|
+
? `mutation($deckId: ID!, $uploadId: ID!, $expectedS3Key: String) {
|
|
303
|
+
saveWebDeckSource(deckId: $deckId, uploadId: $uploadId, expectedS3Key: $expectedS3Key) {
|
|
304
|
+
deckId archiveUrl s3Key updatedAt
|
|
305
|
+
}
|
|
306
|
+
}`
|
|
307
|
+
: `mutation($deckId: ID!, $uploadId: ID!) {
|
|
297
308
|
saveWebDeckSource(deckId: $deckId, uploadId: $uploadId) {
|
|
298
|
-
deckId archiveUrl updatedAt
|
|
309
|
+
deckId archiveUrl s3Key updatedAt
|
|
299
310
|
}
|
|
300
|
-
}`, { deckId, uploadId });
|
|
311
|
+
}`, checked ? { deckId, uploadId, expectedS3Key } : { deckId, uploadId });
|
|
301
312
|
handleAPIError(data);
|
|
302
313
|
return pickData(data, 'saveWebDeckSource');
|
|
303
314
|
}
|
package/dist/castle-host/host.js
CHANGED
|
@@ -1448,42 +1448,41 @@ const DECKS_PLAYLISTS_QUERY = `
|
|
|
1448
1448
|
// ---------------------------------------------------------------------------
|
|
1449
1449
|
// Agent chat.
|
|
1450
1450
|
//
|
|
1451
|
-
// The
|
|
1452
|
-
//
|
|
1453
|
-
//
|
|
1454
|
-
//
|
|
1455
|
-
//
|
|
1456
|
-
//
|
|
1457
|
-
|
|
1458
|
-
|
|
1459
|
-
//
|
|
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
|
|
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
|
|
1472
|
+
const request = agentChatRequest(params);
|
|
1471
1473
|
if (!caps.oracleStream) {
|
|
1472
|
-
return { status: "unavailable", reason: "This host has no route to the
|
|
1474
|
+
return { status: "unavailable", reason: "This host has no route to the deck-agent service." };
|
|
1473
1475
|
}
|
|
1474
1476
|
try {
|
|
1475
|
-
|
|
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
|
|
1486
|
-
//
|
|
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
|
-
|
|
1497
|
-
|
|
1498
|
-
|
|
1499
|
-
|
|
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.
|
|
1504
|
+
request.toolChoice = toolChoice;
|
|
1507
1505
|
}
|
|
1508
1506
|
const maxTokens = asOptionalNumber(params.maxTokens);
|
|
1509
1507
|
if (maxTokens !== null) {
|
|
1510
|
-
request.
|
|
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(
|
|
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
|
|
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(
|
|
1589
|
+
finish({ status: "error", reason: "The model stream ended before the reply finished." });
|
|
1590
1590
|
},
|
|
1591
1591
|
fail(status, text) {
|
|
1592
|
-
finish(
|
|
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
|
|
1615
|
-
//
|
|
1616
|
-
|
|
1617
|
-
|
|
1618
|
-
|
|
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
|
-
|
|
1623
|
-
|
|
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
|
-
|
|
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
|
-
//
|
|
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/cloudGit.d.ts
CHANGED
|
@@ -33,8 +33,15 @@ export declare const HISTORY_RECOVERED_FILE: string;
|
|
|
33
33
|
export declare const RECOVERED_COMMIT_MESSAGE = "Edits restored after lost history";
|
|
34
34
|
/** Written with it, once: the notice and instruction the serve turns into an agent turn. */
|
|
35
35
|
export declare const HISTORY_LOST_MARKER_FILE: string;
|
|
36
|
+
/**
|
|
37
|
+
* Written by `source-status --notify` when the deck's saved copy is newer than this folder
|
|
38
|
+
* (webSourceSync.ts). Not a git marker: the serve consumes it with git off too.
|
|
39
|
+
*/
|
|
40
|
+
export declare const WEB_SOURCE_NEWER_MARKER_FILE: string;
|
|
36
41
|
/** Every marker the serve turns into an agent turn. */
|
|
37
42
|
export declare const AGENT_MARKER_FILES: readonly string[];
|
|
43
|
+
/** The markers the serve consumes whether or not git is on (CASTLE_GIT). */
|
|
44
|
+
export declare const UNGATED_AGENT_MARKER_FILES: readonly string[];
|
|
38
45
|
/** The serve's note that task agents (or the router) are working in the deck; see deckBusy. */
|
|
39
46
|
export declare const BUSY_FILE: string;
|
|
40
47
|
/** The remote has (or may have) work that waits to be merged until the deck is idle. */
|
package/dist/cloudGit.js
CHANGED
|
@@ -82,8 +82,20 @@ export const HISTORY_RECOVERED_FILE = path.join('.castle', 'agent', 'git-history
|
|
|
82
82
|
export const RECOVERED_COMMIT_MESSAGE = 'Edits restored after lost history';
|
|
83
83
|
/** Written with it, once: the notice and instruction the serve turns into an agent turn. */
|
|
84
84
|
export const HISTORY_LOST_MARKER_FILE = path.join('.castle', 'agent', 'git-history-lost.json');
|
|
85
|
+
/**
|
|
86
|
+
* Written by `source-status --notify` when the deck's saved copy is newer than this folder
|
|
87
|
+
* (webSourceSync.ts). Not a git marker: the serve consumes it with git off too.
|
|
88
|
+
*/
|
|
89
|
+
export const WEB_SOURCE_NEWER_MARKER_FILE = path.join('.castle', 'agent', 'web-source-newer.json');
|
|
85
90
|
/** Every marker the serve turns into an agent turn. */
|
|
86
|
-
export const AGENT_MARKER_FILES = [
|
|
91
|
+
export const AGENT_MARKER_FILES = [
|
|
92
|
+
CONFLICT_MARKER_FILE,
|
|
93
|
+
ADOPTED_MARKER_FILE,
|
|
94
|
+
HISTORY_LOST_MARKER_FILE,
|
|
95
|
+
WEB_SOURCE_NEWER_MARKER_FILE,
|
|
96
|
+
];
|
|
97
|
+
/** The markers the serve consumes whether or not git is on (CASTLE_GIT). */
|
|
98
|
+
export const UNGATED_AGENT_MARKER_FILES = [WEB_SOURCE_NEWER_MARKER_FILE];
|
|
87
99
|
/** The serve's note that task agents (or the router) are working in the deck; see deckBusy. */
|
|
88
100
|
export const BUSY_FILE = path.join('.castle', 'agent', 'git-busy.json');
|
|
89
101
|
/** The remote has (or may have) work that waits to be merged until the deck is idle. */
|
package/dist/cloudGitServe.d.ts
CHANGED
|
@@ -37,5 +37,30 @@ export declare function runCastleWeb(args: string[], cwd: string, env?: NodeJS.P
|
|
|
37
37
|
code: number;
|
|
38
38
|
output: string;
|
|
39
39
|
}>;
|
|
40
|
+
type MarkerSink = Pick<ServeGitHooksOptions, 'addLog' | 'enqueueInstruction'>;
|
|
41
|
+
/**
|
|
42
|
+
* One `.castle/agent/*.json` marker `{ notice?, instruction }` becomes a chat line and a hidden
|
|
43
|
+
* router turn. The file is deleted before anything else, so a throw can never turn one marker
|
|
44
|
+
* into a loop of turns. True when a turn was queued.
|
|
45
|
+
*/
|
|
46
|
+
export declare function consumeAgentMarker(deckDir: string, rel: string, sink: MarkerSink, beforeTurn?: () => void): boolean;
|
|
47
|
+
export interface ServeMarkerPoll {
|
|
48
|
+
/** Check for markers now (the poll does this on its own). */
|
|
49
|
+
check(): void;
|
|
50
|
+
stop(): void;
|
|
51
|
+
}
|
|
52
|
+
/**
|
|
53
|
+
* The marker poll for a serve without git (createServeGitHooks returns null): the markers that
|
|
54
|
+
* need no git (UNGATED_AGENT_MARKER_FILES, e.g. the saved-copy-is-newer notice) still become
|
|
55
|
+
* router turns. With git on, the git hooks' own poll consumes these along with the git ones, so
|
|
56
|
+
* exactly one poll runs either way. A file rather than an env var because a reused serve never
|
|
57
|
+
* sees new env, and the first check runs at start for a marker left while the serve was down.
|
|
58
|
+
*/
|
|
59
|
+
export declare function createServeMarkerPoll(opts: MarkerSink & {
|
|
60
|
+
deckDir: string;
|
|
61
|
+
pollMs?: number;
|
|
62
|
+
files?: readonly string[];
|
|
63
|
+
}): ServeMarkerPoll;
|
|
40
64
|
/** Null unless the serve runs with CASTLE_GIT=on. Whether the deck is attached is asked per commit. */
|
|
41
65
|
export declare function createServeGitHooks(opts: ServeGitHooksOptions): ServeGitHooks | null;
|
|
66
|
+
export {};
|
package/dist/cloudGitServe.js
CHANGED
|
@@ -2,7 +2,7 @@ import { spawn } from 'child_process';
|
|
|
2
2
|
import * as fs from 'fs';
|
|
3
3
|
import * as path from 'path';
|
|
4
4
|
import { fileURLToPath } from 'url';
|
|
5
|
-
import { AGENT_MARKER_FILES, cloudGitModeAsync, CONFLICT_MARKER_FILE, DEADLINE_ENV, EXIT_CONFLICT, EXIT_NOT_ENABLED, mergeWaiting, readLeavePending, readMergeState, setDeckBusy, } from './cloudGit.js';
|
|
5
|
+
import { AGENT_MARKER_FILES, cloudGitModeAsync, CONFLICT_MARKER_FILE, DEADLINE_ENV, EXIT_CONFLICT, EXIT_NOT_ENABLED, mergeWaiting, readLeavePending, readMergeState, setDeckBusy, UNGATED_AGENT_MARKER_FILES, } from './cloudGit.js';
|
|
6
6
|
// The serve's half of git in the cloud sandbox (castle-sandboxes docs/git-remotes-phase2.md):
|
|
7
7
|
// - `commit --reason turn` when the router settles with the task board idle,
|
|
8
8
|
// - `commit --reason task` when the task board goes idle,
|
|
@@ -110,6 +110,61 @@ function taskMessage(titles) {
|
|
|
110
110
|
const more = titles.length > MAX_TITLES_IN_MESSAGE ? ` (+${titles.length - MAX_TITLES_IN_MESSAGE} more)` : '';
|
|
111
111
|
return `${titles.length === 1 ? 'Task' : 'Tasks'}: ${shown}${more}`;
|
|
112
112
|
}
|
|
113
|
+
/**
|
|
114
|
+
* One `.castle/agent/*.json` marker `{ notice?, instruction }` becomes a chat line and a hidden
|
|
115
|
+
* router turn. The file is deleted before anything else, so a throw can never turn one marker
|
|
116
|
+
* into a loop of turns. True when a turn was queued.
|
|
117
|
+
*/
|
|
118
|
+
export function consumeAgentMarker(deckDir, rel, sink, beforeTurn) {
|
|
119
|
+
const file = path.join(deckDir, rel);
|
|
120
|
+
let report;
|
|
121
|
+
try {
|
|
122
|
+
report = JSON.parse(fs.readFileSync(file, 'utf-8'));
|
|
123
|
+
}
|
|
124
|
+
catch (e) {
|
|
125
|
+
if (e.code !== 'ENOENT')
|
|
126
|
+
fs.rmSync(file, { force: true });
|
|
127
|
+
return false;
|
|
128
|
+
}
|
|
129
|
+
fs.rmSync(file, { force: true });
|
|
130
|
+
if (typeof report.instruction !== 'string' || !report.instruction)
|
|
131
|
+
return false;
|
|
132
|
+
sink.addLog(typeof report.notice === 'string' && report.notice ? report.notice : CONFLICT_NOTICE);
|
|
133
|
+
beforeTurn?.();
|
|
134
|
+
sink.enqueueInstruction(report.instruction);
|
|
135
|
+
return true;
|
|
136
|
+
}
|
|
137
|
+
/**
|
|
138
|
+
* The marker poll for a serve without git (createServeGitHooks returns null): the markers that
|
|
139
|
+
* need no git (UNGATED_AGENT_MARKER_FILES, e.g. the saved-copy-is-newer notice) still become
|
|
140
|
+
* router turns. With git on, the git hooks' own poll consumes these along with the git ones, so
|
|
141
|
+
* exactly one poll runs either way. A file rather than an env var because a reused serve never
|
|
142
|
+
* sees new env, and the first check runs at start for a marker left while the serve was down.
|
|
143
|
+
*/
|
|
144
|
+
export function createServeMarkerPoll(opts) {
|
|
145
|
+
const files = opts.files ?? UNGATED_AGENT_MARKER_FILES;
|
|
146
|
+
const check = () => {
|
|
147
|
+
for (const rel of files) {
|
|
148
|
+
try {
|
|
149
|
+
consumeAgentMarker(opts.deckDir, rel, opts);
|
|
150
|
+
}
|
|
151
|
+
catch (err) {
|
|
152
|
+
console.error(`[serve] could not read the agent marker ${rel}: ${String(err)}`);
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
};
|
|
156
|
+
const poll = setInterval(check, opts.pollMs ?? CONFLICT_POLL_MS);
|
|
157
|
+
poll.unref();
|
|
158
|
+
// Not synchronously: the caller wires the router queue up after creating this.
|
|
159
|
+
const first = setImmediate(check);
|
|
160
|
+
return {
|
|
161
|
+
check,
|
|
162
|
+
stop() {
|
|
163
|
+
clearInterval(poll);
|
|
164
|
+
clearImmediate(first);
|
|
165
|
+
},
|
|
166
|
+
};
|
|
167
|
+
}
|
|
113
168
|
/** Null unless the serve runs with CASTLE_GIT=on. Whether the deck is attached is asked per commit. */
|
|
114
169
|
export function createServeGitHooks(opts) {
|
|
115
170
|
const env = opts.env ?? process.env;
|
|
@@ -190,26 +245,12 @@ export function createServeGitHooks(opts) {
|
|
|
190
245
|
drain();
|
|
191
246
|
}
|
|
192
247
|
function consumeMarker(rel) {
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
if (e.code !== 'ENOENT')
|
|
200
|
-
fs.rmSync(file, { force: true });
|
|
201
|
-
return;
|
|
202
|
-
}
|
|
203
|
-
// Consumed first, so a throw below can never turn one marker into a loop of turns.
|
|
204
|
-
fs.rmSync(file, { force: true });
|
|
205
|
-
if (typeof report.instruction !== 'string' || !report.instruction)
|
|
206
|
-
return;
|
|
207
|
-
opts.addLog(typeof report.notice === 'string' && report.notice ? report.notice : CONFLICT_NOTICE);
|
|
208
|
-
if (rel === CONFLICT_MARKER_FILE) {
|
|
209
|
-
resolverInFlight = true;
|
|
210
|
-
lastRaisedAt = now();
|
|
211
|
-
}
|
|
212
|
-
opts.enqueueInstruction(report.instruction);
|
|
248
|
+
consumeAgentMarker(opts.deckDir, rel, opts, () => {
|
|
249
|
+
if (rel === CONFLICT_MARKER_FILE) {
|
|
250
|
+
resolverInFlight = true;
|
|
251
|
+
lastRaisedAt = now();
|
|
252
|
+
}
|
|
253
|
+
});
|
|
213
254
|
}
|
|
214
255
|
function checkConflict() {
|
|
215
256
|
for (const rel of AGENT_MARKER_FILES)
|
package/dist/get-deck.d.ts
CHANGED
|
@@ -1,4 +1,21 @@
|
|
|
1
1
|
export declare function getDeck(dir: string, options?: {
|
|
2
2
|
deckId?: string;
|
|
3
3
|
force?: boolean;
|
|
4
|
+
side?: boolean;
|
|
5
|
+
json?: boolean;
|
|
4
6
|
}): Promise<void>;
|
|
7
|
+
/** A save time as a folder name: `20260818-132107` (UTC), or null if unparseable. */
|
|
8
|
+
export declare function savedSourceStamp(updatedAt: string): string | null;
|
|
9
|
+
/**
|
|
10
|
+
* The saved-source root inside `deckDir`, created if needed, or an error naming why it is not
|
|
11
|
+
* safe to write into: `.castle`, `.castle/agent`, `.castle/agent/saved-source` and every stamped
|
|
12
|
+
* copy must be real directories (never symlinks), and the root must resolve inside the deck.
|
|
13
|
+
* The folder is written by whatever runs in the deck, so a link here could aim the replace and
|
|
14
|
+
* the prune at files outside it.
|
|
15
|
+
*/
|
|
16
|
+
export declare function prepareSavedSourceRoot(deckDir: string): string;
|
|
17
|
+
/**
|
|
18
|
+
* Removes all but the `keep` newest stamped copies; returns what it removed. Only real
|
|
19
|
+
* directories named like a stamp are candidates: anything else there is left alone.
|
|
20
|
+
*/
|
|
21
|
+
export declare function pruneSavedSources(root: string, keep?: number): string[];
|
package/dist/get-deck.js
CHANGED
|
@@ -6,6 +6,7 @@ import * as api from './api.js';
|
|
|
6
6
|
import { normalizeDeckPackageJson } from './normalize.js';
|
|
7
7
|
import { archiveSource, downloadSourceArchive, runTar, SOURCE_ARCHIVE_EXCLUDES, } from './save-deck.js';
|
|
8
8
|
import { readCastleJson } from './castleJson.js';
|
|
9
|
+
import { SAVED_SOURCE_DIR, SAVED_SOURCE_KEEP, writeSyncMarker } from './webSourceSync.js';
|
|
9
10
|
// Refreshing a deck already in the target replaces its source, so a file deleted
|
|
10
11
|
// upstream actually disappears here -- untarring over the old tree would leave it
|
|
11
12
|
// behind. What survives is exactly what the source archive doesn't carry, and it
|
|
@@ -48,6 +49,10 @@ function newestSourceMtime(dir) {
|
|
|
48
49
|
//
|
|
49
50
|
// Deps are left to `castle-web install`, like a git pull leaves them to you.
|
|
50
51
|
export async function getDeck(dir, options = {}) {
|
|
52
|
+
if (options.side) {
|
|
53
|
+
await getDeckSide(dir, options);
|
|
54
|
+
return;
|
|
55
|
+
}
|
|
51
56
|
const targetDir = path.resolve(dir);
|
|
52
57
|
const localDeckId = readCastleJson(targetDir)?.deckId;
|
|
53
58
|
const deckId = options.deckId ?? localDeckId;
|
|
@@ -113,8 +118,152 @@ export async function getDeck(dir, options = {}) {
|
|
|
113
118
|
}
|
|
114
119
|
catch { /* nothing to clean */ }
|
|
115
120
|
}
|
|
121
|
+
// The folder's lineage is now exactly this saved version (webSourceSync.ts).
|
|
122
|
+
writeSyncMarker(targetDir, deckId, source, 'get-deck');
|
|
116
123
|
if (normalizeDeckPackageJson(targetDir)) {
|
|
117
124
|
console.log(`Repointed package.json at this machine's sdk/cli`);
|
|
118
125
|
}
|
|
119
126
|
console.log(`${refreshing ? 'Updated' : 'Extracted to'} ${targetDir}`);
|
|
120
127
|
}
|
|
128
|
+
/** A save time as a folder name: `20260818-132107` (UTC), or null if unparseable. */
|
|
129
|
+
export function savedSourceStamp(updatedAt) {
|
|
130
|
+
const ms = Date.parse(updatedAt);
|
|
131
|
+
if (!Number.isFinite(ms))
|
|
132
|
+
return null;
|
|
133
|
+
return new Date(ms).toISOString().slice(0, 19).replace(/[-:]/g, '').replace('T', '-');
|
|
134
|
+
}
|
|
135
|
+
const STAMP_RE = /^\d{8}-\d{6}$/;
|
|
136
|
+
function lstatIfPresent(file) {
|
|
137
|
+
try {
|
|
138
|
+
return fs.lstatSync(file);
|
|
139
|
+
}
|
|
140
|
+
catch (e) {
|
|
141
|
+
if (e.code === 'ENOENT')
|
|
142
|
+
return null;
|
|
143
|
+
throw e;
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
/**
|
|
147
|
+
* The saved-source root inside `deckDir`, created if needed, or an error naming why it is not
|
|
148
|
+
* safe to write into: `.castle`, `.castle/agent`, `.castle/agent/saved-source` and every stamped
|
|
149
|
+
* copy must be real directories (never symlinks), and the root must resolve inside the deck.
|
|
150
|
+
* The folder is written by whatever runs in the deck, so a link here could aim the replace and
|
|
151
|
+
* the prune at files outside it.
|
|
152
|
+
*/
|
|
153
|
+
export function prepareSavedSourceRoot(deckDir) {
|
|
154
|
+
let current = deckDir;
|
|
155
|
+
for (const part of SAVED_SOURCE_DIR.split(path.sep)) {
|
|
156
|
+
current = path.join(current, part);
|
|
157
|
+
const stat = lstatIfPresent(current);
|
|
158
|
+
if (!stat) {
|
|
159
|
+
fs.mkdirSync(current);
|
|
160
|
+
continue;
|
|
161
|
+
}
|
|
162
|
+
if (stat.isSymbolicLink() || !stat.isDirectory()) {
|
|
163
|
+
throw new Error(`Refusing to use ${current}: it is ${stat.isSymbolicLink() ? 'a symlink' : 'not a directory'}.`);
|
|
164
|
+
}
|
|
165
|
+
}
|
|
166
|
+
const realDeck = fs.realpathSync(deckDir);
|
|
167
|
+
const realRoot = fs.realpathSync(current);
|
|
168
|
+
if (path.relative(realDeck, realRoot).startsWith('..') || path.isAbsolute(path.relative(realDeck, realRoot))) {
|
|
169
|
+
throw new Error(`Refusing to use ${current}: it resolves outside the deck (${realRoot}).`);
|
|
170
|
+
}
|
|
171
|
+
for (const name of fs.readdirSync(current)) {
|
|
172
|
+
if (!STAMP_RE.test(name))
|
|
173
|
+
continue;
|
|
174
|
+
const stat = fs.lstatSync(path.join(current, name));
|
|
175
|
+
if (stat.isSymbolicLink() || !stat.isDirectory()) {
|
|
176
|
+
throw new Error(`Refusing to use ${path.join(current, name)}: it is ${stat.isSymbolicLink() ? 'a symlink' : 'not a directory'}.`);
|
|
177
|
+
}
|
|
178
|
+
}
|
|
179
|
+
return current;
|
|
180
|
+
}
|
|
181
|
+
/**
|
|
182
|
+
* Removes all but the `keep` newest stamped copies; returns what it removed. Only real
|
|
183
|
+
* directories named like a stamp are candidates: anything else there is left alone.
|
|
184
|
+
*/
|
|
185
|
+
export function pruneSavedSources(root, keep = SAVED_SOURCE_KEEP) {
|
|
186
|
+
let names;
|
|
187
|
+
try {
|
|
188
|
+
names = fs.readdirSync(root).filter((name) => {
|
|
189
|
+
if (!STAMP_RE.test(name))
|
|
190
|
+
return false;
|
|
191
|
+
const stat = lstatIfPresent(path.join(root, name));
|
|
192
|
+
return stat !== null && stat.isDirectory() && !stat.isSymbolicLink();
|
|
193
|
+
});
|
|
194
|
+
}
|
|
195
|
+
catch {
|
|
196
|
+
return [];
|
|
197
|
+
}
|
|
198
|
+
const removed = names.sort().reverse().slice(keep);
|
|
199
|
+
for (const name of removed)
|
|
200
|
+
fs.rmSync(path.join(root, name), { recursive: true, force: true });
|
|
201
|
+
return removed;
|
|
202
|
+
}
|
|
203
|
+
// `get-deck <dir> --side`: the deck's current saved source, fetched beside the folder into
|
|
204
|
+
// `.castle/agent/saved-source/<stamp>/` for comparing -- not installed, not served, and nothing
|
|
205
|
+
// of the folder's own (its source files, its sync marker) is touched. Excluded from the source
|
|
206
|
+
// archive and kept by deck persistence, like the rest of `.castle/agent/`.
|
|
207
|
+
async function getDeckSide(dir, options) {
|
|
208
|
+
const targetDir = path.resolve(dir);
|
|
209
|
+
const localDeckId = readCastleJson(targetDir)?.deckId;
|
|
210
|
+
if (!fs.existsSync(targetDir) || !fs.statSync(targetDir).isDirectory()) {
|
|
211
|
+
console.error(`--side fetches the saved copy beside an existing deck folder; ${targetDir} does not exist.`);
|
|
212
|
+
process.exit(1);
|
|
213
|
+
}
|
|
214
|
+
const deckId = options.deckId ?? localDeckId;
|
|
215
|
+
if (!deckId) {
|
|
216
|
+
console.error(`No deckId. Either pass --deck-id <id> or run from a directory whose castle.json has one.`);
|
|
217
|
+
process.exit(1);
|
|
218
|
+
}
|
|
219
|
+
if (localDeckId && deckId !== localDeckId) {
|
|
220
|
+
console.error(`This directory holds deck ${localDeckId}, but --deck-id ${deckId} was passed.`);
|
|
221
|
+
process.exit(1);
|
|
222
|
+
}
|
|
223
|
+
const source = await api.webDeckSource(deckId);
|
|
224
|
+
if (!source) {
|
|
225
|
+
console.error(`No source archive on server for deck ${deckId}.`);
|
|
226
|
+
process.exit(1);
|
|
227
|
+
}
|
|
228
|
+
const stamp = savedSourceStamp(source.updatedAt);
|
|
229
|
+
if (!stamp) {
|
|
230
|
+
console.error(`Unreadable save time from the server (${source.updatedAt}).`);
|
|
231
|
+
process.exit(1);
|
|
232
|
+
}
|
|
233
|
+
// With --json, stdout is the one result line.
|
|
234
|
+
const log = options.json ? (line) => console.error(line) : (line) => console.log(line);
|
|
235
|
+
let root;
|
|
236
|
+
try {
|
|
237
|
+
root = prepareSavedSourceRoot(targetDir);
|
|
238
|
+
}
|
|
239
|
+
catch (e) {
|
|
240
|
+
console.error(e instanceof Error ? e.message : String(e));
|
|
241
|
+
process.exit(1);
|
|
242
|
+
}
|
|
243
|
+
const dest = path.join(root, stamp);
|
|
244
|
+
const tmpFile = await downloadSourceArchive(source, 'castle-side', log);
|
|
245
|
+
// Extracted beside the destination and renamed in, so a failed extract never leaves a
|
|
246
|
+
// half-written copy under a real stamp (and tmp may be another filesystem).
|
|
247
|
+
const staging = path.join(root, `.partial-${nanoid(8)}`);
|
|
248
|
+
try {
|
|
249
|
+
fs.mkdirSync(staging, { recursive: true });
|
|
250
|
+
await runTar(['-xzf', tmpFile, '-C', staging]);
|
|
251
|
+
fs.rmSync(dest, { recursive: true, force: true });
|
|
252
|
+
fs.renameSync(staging, dest);
|
|
253
|
+
}
|
|
254
|
+
finally {
|
|
255
|
+
fs.rmSync(staging, { recursive: true, force: true });
|
|
256
|
+
try {
|
|
257
|
+
fs.unlinkSync(tmpFile);
|
|
258
|
+
}
|
|
259
|
+
catch { /* nothing to clean */ }
|
|
260
|
+
}
|
|
261
|
+
for (const name of pruneSavedSources(root))
|
|
262
|
+
log(`Removed the older saved copy ${name}`);
|
|
263
|
+
if (options.json) {
|
|
264
|
+
console.log(JSON.stringify({ path: dest, s3Key: source.s3Key, updatedAt: source.updatedAt }));
|
|
265
|
+
}
|
|
266
|
+
else {
|
|
267
|
+
console.log(`Saved copy (saved ${source.updatedAt}) fetched to ${dest}`);
|
|
268
|
+
}
|
|
269
|
+
}
|