castle-web-cli 0.4.177 → 0.4.179

package/dist/agent-failures.js

@@ -206,15 +206,15 @@ export function failureCopy(opts) {
             return `${configCopy(opts.failure)}${tasksNote}`;
         case "limit":
             if (opts.failure.castleCreditsInsufficient) {
-                return `Not enough Castle AI credits for this request — get more at castle.xyz/credits${tasksNote}`;
+                return `Not enough Operator credits for this request — get more at castle.xyz/credits${tasksNote}`;
             }
             if (opts.failure.castleCreditsExhausted) {
-                return `Out of Castle AI credits — get more at castle.xyz/credits${tasksNote}`;
+                return `Out of Operator credits — get more at castle.xyz/credits${tasksNote}`;
             }
             if (opts.failure.castleSpendLimit) {
-                return `Castle AI spending limit reached — check your balance at castle.xyz/credits${tasksNote}`;
+                return `Operator spending limit reached — check your balance at castle.xyz/credits${tasksNote}`;
             }
-            return `Daily Castle AI limit reached${resetsClause(opts.failure.resetAtMs)}. Runs on your own API key or login aren't limited.${tasksNote}`;
+            return `Daily Operator limit reached${resetsClause(opts.failure.resetAtMs)}. Runs on your own API key or login aren't limited.${tasksNote}`;
         case "transient":
             return `OpenRouter is busy right now and I couldn't get through. Send that again in a moment.${tasksNote}`;
         case "no-work":

package/dist/agent-prompts.d.ts

@@ -92,11 +92,19 @@ export interface RouterPromptOpts {
 }
 export declare function buildRouterPromptParts(opts: RouterPromptOpts): RouterPromptParts;
 export declare function buildRouterPrompt(opts: RouterPromptOpts): string;
+export interface PromptRef {
+    path: string;
+    line?: number;
+    endLine?: number;
+    view?: "params";
+    field?: string;
+    fragment?: string;
+}
 export declare function userTurnInstruction(opts: {
     messages: string[];
     interruptedDraft?: string;
     attachments?: string[];
-    files?: string[];
+    refs?: PromptRef[];
 }): string;
 export declare function buildTaskPrompt(opts: {
     deckLabel: string;

package/dist/agent-prompts.js

@@ -871,6 +871,19 @@ export function buildRouterPrompt(opts) {
     const parts = buildRouterPromptParts(opts);
     return `${parts.system}\n\n${parts.user}`;
 }
+function refPhrase(ref) {
+    if (ref.line !== undefined) {
+        return ref.endLine !== undefined
+            ? `lines ${ref.line} to ${ref.endLine} of ${ref.path}`
+            : `line ${ref.line} of ${ref.path}`;
+    }
+    if (ref.view === "params") {
+        return ref.field
+            ? `the ${ref.field} param in ${ref.path}'s PARAMS`
+            : `the PARAMS of ${ref.path}`;
+    }
+    return ref.fragment ? `${ref.path} (at ${ref.fragment})` : ref.path;
+}
 export function userTurnInstruction(opts) {
     const parts = [];
     if (opts.interruptedDraft?.trim()) {
@@ -891,8 +904,8 @@ export function userTurnInstruction(opts) {
         // while the CLI backends open the saved files themselves.
         parts.push(`The user attached image file(s), saved in the deck at: ${opts.attachments.join(", ")}. If the images are not already visible in this message, open them with your read tool. Take them into account; pass the paths along to task agents that need them.`);
     }
-    if (opts.files && opts.files.length > 0) {
-        parts.push(`The user pointed at these deck files: ${opts.files.join(", ")}. Read them with your read tool if you need them to reply. When you spawn a task one of these files concerns, name that path in that task's prompt so the agent reads it; do not mention it to tasks it does not concern.`);
+    if (opts.refs && opts.refs.length > 0) {
+        parts.push(`The user pointed at: ${opts.refs.map(refPhrase).join(", ")}. Read them with your read tool if you need them to reply. When you spawn a task one of these concerns, name it the same way in that task's prompt -- the path and the lines, or the path and the param -- so the agent reads that place; do not mention it to tasks it does not concern.`);
     }
     return parts.join("\n\n");
 }

package/dist/agent.js

@@ -19,6 +19,7 @@ import { quickReferenceFor } from './platformDoc.js';
 import { IMPORTS_DIR } from './imports.js';
 import { isSameOriginUpgrade } from './wsOrigin.js';
 import { resolveDeckPath } from './ide.js';
+import { lineRange, uniqueLocators } from './deckLocatorShape.js';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
@@ -638,9 +639,9 @@ const RESULT_SUMMARY_CHARS = 600;
 // TRANSCRIPT_BYTE_BUDGET in agent-prompts.ts), so this term needs its own bound.
 const PLAN_BYTE_BUDGET = 8 * 1024;
 const MAX_ATTACHMENTS = 6;
-// @-mentioned files are path references, so the only cost is instruction bytes
-// -- but a client is not the one to decide how many the router is told about.
-const MAX_MESSAGE_FILES = 12;
+// @-mentioned places are references, so the only cost is instruction bytes --
+// but a client is not the one to decide how many the router is told about.
+const MAX_MESSAGE_REFS = 12;
 const MAX_ATTACHMENT_BYTES = 8 * 1024 * 1024;
 const TERMINAL_STATUSES = ['done', 'failed', 'interrupted'];
 function nowIso() {
@@ -2040,13 +2041,13 @@ async function castleSpendRefusal(backend, claudeModel, orAuth) {
     if (castleCreditsExhausted(budget, credits)) {
         return {
             kind: 'limit',
-            detail: 'Out of Castle AI credits — get more at castle.xyz/credits',
+            detail: 'Out of Operator credits — get more at castle.xyz/credits',
             castleCreditsExhausted: true,
         };
     }
     return {
         kind: 'limit',
-        detail: 'daily Castle AI limit reached',
+        detail: 'daily Operator limit reached',
         resetAtMs: budget.resetAtMs || undefined,
     };
 }
@@ -2268,6 +2269,8 @@ function persistTaskFile(tasksDir, task) {
 // written whether or not the deck has the plan doc switched on: it is a disk
 // receipt, never injected into a prompt, so it costs an off deck nothing.
 const TASK_INDEX_FILE = 'index.md';
+const TASK_FEED_FILE = 'feed.json';
+const TASK_FEED_CAP = 80;
 const TASK_INDEX_HEADER = '# tasks\n# <task-id> | <item> | <title> | <created> | <status> | <touching>\n';
 // A pipe-delimited row can't carry a pipe. Titles come from the router's fence
 // and can hold anything.
@@ -3047,19 +3050,85 @@ function saveAttachments(attachmentsDir, messageId, images) {
     }
     return saved;
 }
-// Deck-relative paths a client @-mentioned, keeping only the ones that name a
-// real place in this deck. Nothing is read here: the paths travel as references
-// and whoever needs the contents opens them.
-function validMessageFiles(deckDir, files) {
-    if (!Array.isArray(files))
-        return [];
-    const kept = [];
-    for (const entry of files.slice(0, MAX_MESSAGE_FILES)) {
-        const resolved = resolveDeckPath(deckDir, entry);
-        if (resolved.ok && !kept.includes(resolved.rel))
-            kept.push(resolved.rel);
+function isExistingFile(abs) {
+    try {
+        return fs.statSync(abs).isFile();
     }
-    return kept;
+    catch {
+        return false;
+    }
+}
+// Past this a line number goes through unclamped, rather than reading a file
+// that size to count lines nobody hand-edits by number.
+const MAX_CLAMP_BYTES = 2 * 1024 * 1024;
+function lineCountOf(abs) {
+    try {
+        if (fs.statSync(abs).size > MAX_CLAMP_BYTES)
+            return null;
+        const bytes = fs.readFileSync(abs);
+        let lines = 1;
+        for (let i = bytes.indexOf(10); i !== -1; i = bytes.indexOf(10, i + 1))
+            lines++;
+        return lines;
+    }
+    catch {
+        return null;
+    }
+}
+function isPositiveInteger(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value > 0;
+}
+// A `ParamSlot.id` (shell/paramsFile.ts): `speed`, or `player.speed` in a group.
+const PARAM_FIELD_RE = /^[\w$]+(?:\.[\w$]+)*$/;
+const MAX_FRAGMENT_CHARS = 200;
+// One place a client @-mentioned, or null when it names no file this deck has.
+// A part that does not hold up -- a line that is not a positive integer, a field
+// that is not a field name -- is dropped and the file still stands. Whether a
+// params field exists is not checked: that means parsing the file, and the
+// router reads it anyway.
+function validMessageRef(deckDir, entry, lineCounts) {
+    if (!entry || typeof entry !== 'object')
+        return null;
+    const raw = entry;
+    const resolved = resolveDeckPath(deckDir, raw.path);
+    if (!resolved.ok || !isExistingFile(resolved.abs))
+        return null;
+    const path = resolved.rel;
+    if (isPositiveInteger(raw.line)) {
+        if (!lineCounts.has(path))
+            lineCounts.set(path, lineCountOf(resolved.abs));
+        const lines = lineCounts.get(path) ?? null;
+        const clamp = (n) => (lines === null ? n : Math.min(n, lines));
+        const end = isPositiveInteger(raw.endLine) ? clamp(raw.endLine) : undefined;
+        return { path, ...lineRange(clamp(raw.line), end) };
+    }
+    if (raw.view === 'params') {
+        const field = typeof raw.field === 'string' && PARAM_FIELD_RE.test(raw.field) ? raw.field : null;
+        return field ? { path, view: 'params', field } : { path, view: 'params' };
+    }
+    const fragment = typeof raw.fragment === 'string' ? raw.fragment : '';
+    if (fragment && fragment.length <= MAX_FRAGMENT_CHARS)
+        return { path, fragment };
+    return { path };
+}
+// The places a client @-mentioned, keeping only the ones that name a real place
+// in this deck. Nothing is read here but a line count: the refs travel as
+// references and whoever needs the contents opens them.
+function validMessageRefs(deckDir, refs) {
+    if (!Array.isArray(refs))
+        return [];
+    const lineCounts = new Map();
+    const valid = refs
+        .slice(0, MAX_MESSAGE_REFS)
+        .map((entry) => validMessageRef(deckDir, entry, lineCounts))
+        .filter((ref) => ref !== null);
+    return uniqueLocators(valid);
+}
+// A client, or a queue mirror, from before refs replaced `files` sends bare paths.
+function refsOrLegacyFiles(carrier) {
+    if (carrier.refs !== undefined || !Array.isArray(carrier.files))
+        return carrier.refs;
+    return carrier.files.map((path) => ({ path }));
 }
 // Cap on the failure detail shown in a board row -- just enough for the
 // router to reason about what went wrong, not the full crash dump.
@@ -3157,8 +3226,27 @@ function asClientMessage(message, signPath) {
         attachments: message.attachments.map((name) => clientUrl(`${AGENT_ATTACHMENT_PREFIX}${name}`, signPath)),
     };
 }
-function createTaskFeeds(broadcast) {
+function loadTaskFeeds(tasksDir) {
     const map = new Map();
+    for (const entry of fs.existsSync(tasksDir) ? fs.readdirSync(tasksDir) : []) {
+        const loaded = readJsonFile(path.join(tasksDir, entry, TASK_FEED_FILE));
+        if (!Array.isArray(loaded))
+            continue;
+        const lines = loaded.filter((line) => typeof line === 'string');
+        if (lines.length === 0)
+            continue;
+        map.set(entry, lines.slice(-TASK_FEED_CAP));
+    }
+    return map;
+}
+function createTaskFeeds(broadcast, tasksDir) {
+    const map = loadTaskFeeds(tasksDir);
+    function persist(task) {
+        const feed = map.get(task.id);
+        if (!feed || feed.length === 0)
+            return;
+        atomicWriteFileSync(path.join(tasksDir, task.id, TASK_FEED_FILE), JSON.stringify(feed, null, 2) + '\n');
+    }
     function push(task, entry) {
         let feed = map.get(task.id);
         if (!feed) {
@@ -3168,11 +3256,11 @@ function createTaskFeeds(broadcast) {
         if (feed[feed.length - 1] === entry)
             return;
         feed.push(entry);
-        if (feed.length > 80)
-            feed.splice(0, feed.length - 80);
+        if (feed.length > TASK_FEED_CAP)
+            feed.splice(0, feed.length - TASK_FEED_CAP);
         broadcast({ type: 'task-feed', id: task.id, entry });
     }
-    return { map, push };
+    return { map, push, persist };
 }
 function createMessageThinking(broadcast) {
     const map = new Map();
@@ -3881,11 +3969,11 @@ function loadRecoverableSends(deckDir, pendingPath, committedIds) {
                 id: item.id,
                 text: item.text,
                 attachments: item.attachments.filter((a) => typeof a === 'string'),
-                // Re-validated rather than trusted: enqueue is where a path earns its
+                // Re-validated rather than trusted: enqueue is where a ref earns its
                 // place, and a mirror on disk is not evidence it ever did. A build that
-                // predates @-mentions wrote no files at all, which is a send worth
+                // predates @-mentions wrote none at all, which is a send worth
                 // recovering for its words, not a malformed one.
-                files: validMessageFiles(deckDir, item.files),
+                refs: validMessageRefs(deckDir, refsOrLegacyFiles(item)),
             });
         }
     }
@@ -3980,7 +4068,7 @@ function startRouterTurn(ctx, instruction, attachments = []) {
 function commitDrainedSends(drained, log) {
     const texts = [];
     const attachmentPaths = [];
-    const filePaths = [];
+    const refs = [];
     for (const item of drained) {
         if (!item.logged) {
             const message = {
@@ -3992,8 +4080,8 @@ function commitDrainedSends(drained, log) {
             };
             if (item.attachments.length > 0)
                 message.attachments = item.attachments;
-            if (item.files.length > 0)
-                message.files = item.files;
+            if (item.refs.length > 0)
+                message.refs = item.refs;
             log.add(message);
         }
         if (item.text.trim())
@@ -4001,12 +4089,9 @@ function commitDrainedSends(drained, log) {
         for (const name of item.attachments) {
             attachmentPaths.push(path.join('.castle', 'agent', 'attachments', name));
         }
-        for (const file of item.files) {
-            if (!filePaths.includes(file))
-                filePaths.push(file);
-        }
+        refs.push(...item.refs);
     }
-    return { texts, attachmentPaths, filePaths };
+    return { texts, attachmentPaths, refs: uniqueLocators(refs) };
 }
 // Drain the queue into the log as real user messages and start one follow-up
 // turn addressing them all (a burst batches into a single turn). A pending
@@ -4022,7 +4107,7 @@ function maybeStartRouterQueueTurn(ctx) {
     // Kept so a fold or manual interrupt of THIS turn can hand these sends back
     // to reclaimInFlightSends if it dies before producing anything visible.
     state.inFlightSends = drained;
-    const { texts, attachmentPaths, filePaths } = commitDrainedSends(drained, ctx.log);
+    const { texts, attachmentPaths, refs } = commitDrainedSends(drained, ctx.log);
     // The queue is now committed to messages.json; clear its durable mirror.
     persistPendingSends(ctx);
     const draft = state.pendingInterruptedDraft;
@@ -4033,7 +4118,7 @@ function maybeStartRouterQueueTurn(ctx) {
         messages: texts,
         interruptedDraft: draft || undefined,
         attachments: attachmentPaths,
-        files: filePaths,
+        refs,
     }), attachmentPaths);
 }
 // The turn settled: clear the busy flag, broadcast it, then flush anything
@@ -4082,7 +4167,7 @@ function safeClientMessageId(clientId) {
         return null;
     return /^[A-Za-z0-9_-]{1,32}$/.test(clientId) ? clientId : null;
 }
-function handleQueueUserMessage(ctx, text, images, files, clientId) {
+function handleQueueUserMessage(ctx, text, images, refs, clientId) {
     const { state } = ctx;
     // Mid-run: queue (don't interrupt). It shows as a queued row in the
     // composer and flushes when the current turn settles. Idle: start now.
@@ -4109,7 +4194,7 @@ function handleQueueUserMessage(ctx, text, images, files, clientId) {
         id,
         text,
         attachments,
-        files: validMessageFiles(ctx.deckDir, files),
+        refs: validMessageRefs(ctx.deckDir, refs),
     });
     persistPendingSends(ctx);
     if (state.routerRunning) {
@@ -4195,7 +4280,7 @@ function createRouterQueue(deps) {
     persistPendingSends(ctx);
     maybeStartRouterQueueTurn(ctx);
     return {
-        handleUserMessage: (text, images, files, clientId) => handleQueueUserMessage(ctx, text, images, files, clientId),
+        handleUserMessage: (text, images, refs, clientId) => handleQueueUserMessage(ctx, text, images, refs, clientId),
         interruptRouter: () => interruptRouterQueue(ctx),
         cancelQueued: (index) => cancelQueuedSend(ctx, index),
         isRunning: () => ctx.state.routerRunning,
@@ -4335,7 +4420,7 @@ export function createAgentServer(opts) {
         // Castle's), so the bar follows the change instead of the poll.
         usageFeed.refresh();
     };
-    const taskFeeds = createTaskFeeds(broadcast);
+    const taskFeeds = createTaskFeeds(broadcast, tasksDir);
     const messageThinking = createMessageThinking(broadcast);
     const taskStore = createTaskStore({
         deckDir,
@@ -4357,7 +4442,7 @@ export function createAgentServer(opts) {
         onUpdate: (task) => broadcast({ type: 'task-update', task: asClientTask(task, opts.signPath) }),
         onStarted: () => undefined,
         onRetry: (task, attempt) => addLog(`agent died, retrying (${attempt}/${MAX_TASK_ATTEMPTS}): ${task.title}`),
-        onFinished: (task) => taskFeeds.map.delete(task.id),
+        onFinished: (task) => taskFeeds.persist(task),
         onFeed: (task, entry) => taskFeeds.push(task, entry),
     });
     // The mid-run send queue (queue-by-default, "send now"/Stop interrupt, epoch
@@ -4474,7 +4559,7 @@ export function createAgentServer(opts) {
                 if (!duplicate) {
                     if (clientId !== null)
                         rememberClientId(clientId);
-                    routerQueue.handleUserMessage(typeof msg.text === 'string' ? msg.text.trim() : '', msg.images, msg.files, clientId ?? undefined);
+                    routerQueue.handleUserMessage(typeof msg.text === 'string' ? msg.text.trim() : '', msg.images, refsOrLegacyFiles(msg), clientId ?? undefined);
                 }
                 if (clientId !== null) {
                     if (socket.readyState === socket.OPEN) {

package/dist/deckLocatorShape.d.ts

@@ -0,0 +1,16 @@
+export interface DeckLocator {
+    path: string;
+    line?: number;
+    /** Inclusive; only with `line`, and always greater than it. */
+    endLine?: number;
+    view?: 'params';
+    field?: string;
+    /** The fragment as written, when it meant nothing to the shell. */
+    fragment?: string;
+}
+export declare function lineRange(line: number, endLine?: number): {
+    line: number;
+    endLine?: number;
+};
+export declare function formatLocator(loc: DeckLocator): string;
+export declare function uniqueLocators(locs: DeckLocator[]): DeckLocator[];

package/dist/deckLocatorShape.js

@@ -0,0 +1,28 @@
+// A place in the deck, as both ends of a link see it: the shell parses and
+// follows one, the serve validates the ones a user's message points at. Apart
+// from shell/deckLocator.ts so the serve can use it without the shell's
+// browser modules.
+export function lineRange(line, endLine) {
+    if (endLine === undefined || endLine === line)
+        return { line };
+    return endLine > line ? { line, endLine } : { line: endLine, endLine: line };
+}
+export function formatLocator(loc) {
+    if (loc.line !== undefined) {
+        const end = loc.endLine === undefined ? '' : `-${loc.endLine}`;
+        return `${loc.path}#L${loc.line}${end}`;
+    }
+    if (loc.view === 'params') {
+        return loc.field ? `${loc.path}#params:${loc.field}` : `${loc.path}#params`;
+    }
+    return loc.fragment ? `${loc.path}#${loc.fragment}` : loc.path;
+}
+export function uniqueLocators(locs) {
+    const byKey = new Map();
+    for (const loc of locs) {
+        const key = formatLocator(loc);
+        if (!byKey.has(key))
+            byKey.set(key, loc);
+    }
+    return [...byKey.values()];
+}

package/dist/editorConfig.d.ts

@@ -17,6 +17,7 @@ export interface FileTypeConfig {
     editor?: string;
     data?: boolean | DataMode;
     unsupported?: string;
+    width?: number;
 }
 export type DataMode = 'json' | 'text';
 export declare function dataModeOf(type: {