castle-web-cli 0.4.224 → 0.4.225

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.
@@ -228,9 +228,11 @@ export function failureLabel(failure) {
228
228
  return failure.reason ? `${failure.kind}/${failure.reason}` : failure.kind;
229
229
  }
230
230
  // The router reads only a failed task's technical error line, and its standing
231
- // advice is to spawn a replacement; a config failure would fail the same way
232
- // again, so its row also carries the copy that says so.
231
+ // advice is to spawn a replacement. Config failures also carry the recovery
232
+ // copy; limit failures use only that plain copy instead of the proxy denial.
233
233
  export function routerTaskError(errorLine, failure, errorCopy) {
234
+ if (failure?.startsWith("limit") && errorCopy)
235
+ return errorCopy;
234
236
  if (!errorLine || !errorCopy || !failure?.startsWith("config"))
235
237
  return errorLine;
236
238
  return `${errorLine} -- ${errorCopy}`;
@@ -11,7 +11,11 @@ export interface PromptTask {
11
11
  notes: string;
12
12
  item?: string;
13
13
  error?: string;
14
+ interrupted?: string;
14
15
  blockedBy?: string[];
16
+ sent?: string;
17
+ heldQuestion?: string;
18
+ answer?: string;
15
19
  }
16
20
  export interface PromptStop {
17
21
  title: string;
@@ -51,6 +55,9 @@ export declare const PLAYTEST_OFF_FENCE_RULE = "- If the user asks for no playte
51
55
  export declare const PLAYTEST_ON_FENCE_RULE = "- The user turned playtest checks off for this deck: never ask a task to verify with the playtest tool. If they ask for them back, emit this fence and confirm in one line:\n```castle-pref\nplaytest: on\n```";
52
56
  export declare const TASK_FENCE_PROMPT_EXAMPLE = "Then a SHORT self-contained prompt -- one tight paragraph (aim under 100\nwords): what to build or fix and what \"done\" looks like. Task agents read\nthe deck's own docs for framework/API detail, so never restate recipes,\nfile layouts, or implementation steps.";
53
57
  export declare const PLAYTEST_TASK_UNDRIVEN_RULE = "- The playtest tool is a headless preview, not the user's device. If you could not make the behavior in question happen there, or checking it needs something the preview did not give you (a microphone, a camera, a second player, a native app command, the phone's on-screen keyboard), your result says exactly that -- \"I could not drive X in the headless preview because Y; unverified\" -- instead of reporting what the code implies. Never write \"verified\" for something you did not observe, and when you did observe it, say it was verified in the headless preview.";
58
+ export declare const STOP_RULE_STEER = "- When a new message is about work a task is still running or waiting to run -- it corrects it, adds to it, narrows it, or answers a question you asked about it -- `castle-send` it to that task instead of stopping it: the task keeps what it has done and adjusts. Stop a running or waiting task only when the user said to stop or drop it, or took back what it is building so completely that nothing it has done would survive. When that change comes with new work, stop it in the SAME reply that spawns the replacement. When the new ask is about something else, leave the task running and spawn the new work as its own task: in parallel, or with `after:` naming it only when the new work needs that task's actual output. Never stop a task because a new one restates it or covers it more broadly.";
59
+ export declare const SEND_FENCE_RULES = "\n\nTo hand a message to a task that is running or waiting to run:\n\n```castle-send\nthe task's title or id, alone on the first line\nthe user's message for it -- their own words, quoted, plus only what from this conversation the task needs to act on them\n```\n\n- `castle-send` reaches a RUNNING or WAITING task: it reads the message at its next step and folds it into the work it is doing, without starting over. One fence per task. It is the ONLY thing that reaches a running task -- a reply that says a task will pick something up, without this fence, sends nothing. The board row shows each message you sent and whether the task has read it.\n- It cannot reach a finished task. For those, spawn a new task (see the one-and-done rule below).";
60
+ export declare const PROBE_CLAUSE_STEER = "But NEVER spawn work a pending probe could invalidate outright: castle-send can pass the answer to a running task, but it cannot undo work the answer throws away.";
54
61
  export declare function truncateToBytes(line: string, budget: number): string;
55
62
  export type PlanOpVerb = "decide" | "open" | "tried" | "now" | "identity";
56
63
  export interface PlanOpSource {
@@ -86,6 +93,8 @@ export declare function planOpenQuestionLines(fileText: string): string[];
86
93
  export declare function renderTaskPlanSlice(fileText: string, item: string | undefined, finishedWork?: PlanFinishedWork[]): string;
87
94
  export declare const NO_DECK_DOCS = "This deck has no CLAUDE.md / AGENTS.md quick reference. There is no documentation to read -- do not search for one (CLAUDE.md, README, **/*.md, etc.).";
88
95
  export declare const STOPPED_TASKS_HEADER = "Tasks you stopped with castle-stop. They started and you cancelled them; none finished. What the user saw: the task appeared on their board and then vanished. So if the user says a task never started, or asks where it went, say plainly that you stopped it (not that it never started), then re-send it if they still want it";
96
+ export declare const BAD_TASK_ENDINGS_HEADER = "Tasks that ended badly since your last reply. Tell the user about these at the start of your reply, plainly. Do not talk as if they are still running";
97
+ export declare const UNSENT_HEADER = "Your last reply's castle-send named no task on the board, so NOTHING was sent for these. If you told the user it was passed on, correct that now, and send it to the right task or spawn it";
89
98
  export interface RouterPromptParts {
90
99
  system: string;
91
100
  user: string;
@@ -97,10 +106,13 @@ export interface RouterPromptOpts {
97
106
  messages: PromptMessage[];
98
107
  tasks: PromptTask[];
99
108
  stopped?: PromptStop[];
109
+ endedBadly?: PromptTask[];
100
110
  plan?: RouterPlanOpts;
101
111
  playtest?: boolean;
102
112
  playtestPref?: 'on' | 'off';
103
113
  askCalls?: boolean;
114
+ steer?: boolean;
115
+ unsentSends?: string[];
104
116
  editorTabs?: string[];
105
117
  kits?: string[];
106
118
  paramsWrites?: string[];
@@ -120,6 +132,7 @@ export declare function userTurnInstruction(opts: {
120
132
  messages: string[];
121
133
  interruptedDraft?: string;
122
134
  attachments?: string[];
135
+ marked?: string[];
123
136
  refs?: PromptRef[];
124
137
  }): string;
125
138
  export declare function buildTaskPrompt(opts: {
@@ -33,7 +33,22 @@ file layouts, or implementation steps.`;
33
33
  // Directive v2, the task half: added beside the v1 verify line rather than as an
34
34
  // edit of it (memo 26-09-03-13-27), so v1's measured wording stands.
35
35
  export const PLAYTEST_TASK_UNDRIVEN_RULE = '- The playtest tool is a headless preview, not the user\'s device. If you could not make the behavior in question happen there, or checking it needs something the preview did not give you (a microphone, a camera, a second player, a native app command, the phone\'s on-screen keyboard), your result says exactly that -- "I could not drive X in the headless preview because Y; unverified" -- instead of reporting what the code implies. Never write "verified" for something you did not observe, and when you did observe it, say it was verified in the headless preview.';
36
- function baseRouterRules(playtest, playtestPref) {
36
+ const STOP_RULE_NO_STEER = `- Stop a running or waiting task only when the new message makes its work unwanted: the user said to stop or drop it, took back or reversed what it is building, or corrected it -- it has the wrong idea, or they picked a different option than the one it is building -- so its result would have to be undone. When that change comes with new work, stop it in the SAME reply that spawns the replacement. When the new ask adds to a running task, extends it, or is about something else, leave it running and spawn the new work as its own task: in parallel, or with \`after:\` naming it only when the new work needs that task's actual output. Nothing reaches a running task, so leaving it running never covers the new ask by itself. Never stop a task because a new one restates it or covers it more broadly.`;
37
+ export const STOP_RULE_STEER = `- When a new message is about work a task is still running or waiting to run -- it corrects it, adds to it, narrows it, or answers a question you asked about it -- \`castle-send\` it to that task instead of stopping it: the task keeps what it has done and adjusts. Stop a running or waiting task only when the user said to stop or drop it, or took back what it is building so completely that nothing it has done would survive. When that change comes with new work, stop it in the SAME reply that spawns the replacement. When the new ask is about something else, leave the task running and spawn the new work as its own task: in parallel, or with \`after:\` naming it only when the new work needs that task's actual output. Never stop a task because a new one restates it or covers it more broadly.`;
38
+ export const SEND_FENCE_RULES = `
39
+
40
+ To hand a message to a task that is running or waiting to run:
41
+
42
+ \`\`\`castle-send
43
+ the task's title or id, alone on the first line
44
+ the user's message for it -- their own words, quoted, plus only what from this conversation the task needs to act on them
45
+ \`\`\`
46
+
47
+ - \`castle-send\` reaches a RUNNING or WAITING task: it reads the message at its next step and folds it into the work it is doing, without starting over. One fence per task. It is the ONLY thing that reaches a running task -- a reply that says a task will pick something up, without this fence, sends nothing. The board row shows each message you sent and whether the task has read it.
48
+ - It cannot reach a finished task. For those, spawn a new task (see the one-and-done rule below).`;
49
+ function baseRouterRules(playtest, askCalls, playtestPref, steer = false) {
50
+ const runningTaskRules = steer ? STOP_RULE_STEER : STOP_RULE_NO_STEER;
51
+ const sendFenceRules = steer ? SEND_FENCE_RULES : '';
37
52
  const playtestRules = playtestPref === 'off'
38
53
  ? `\n${PLAYTEST_ON_FENCE_RULE}`
39
54
  : playtestPref === 'on'
@@ -66,7 +81,7 @@ Hard rules:
66
81
  \`\`\`castle-task
67
82
  short imperative title on the first line
68
83
  after: comma-separated titles or ids this task must wait for (optional line)
69
- ${TASK_FENCE_PROMPT_EXAMPLE}
84
+ ${askCalls ? 'hold: answer (optional line -- only on the task a probe in this same reply decides)\n' : ''}${TASK_FENCE_PROMPT_EXAMPLE}
70
85
  \`\`\`
71
86
 
72
87
  - Use \`after:\` only for the fallback case above -- a task that genuinely needs another's produced output (it may reference tasks spawned in this same reply, by title). Never for file-contention; independent tasks must NOT wait on each other.
@@ -81,10 +96,12 @@ comma-separated active-task titles or ids, or \`all\`
81
96
  \`\`\`
82
97
 
83
98
  - \`castle-done\` removes FINISHED rows (done/failed). Use it when the user confirms a task works, or to clear a finished task that has become obsolete (replaced by newer work). \`all\` clears every finished row.
84
- - \`castle-stop\` stops AND removes ACTIVE rows (running/waiting/blocked) -- a running task's agent is killed. Its unfinished work is thrown away. Use it when the user asks to stop something, or under the rule below. \`all\` stops everything active.
99
+ - \`castle-stop\` stops AND removes ACTIVE rows (running/waiting/blocked) -- a running task's agent is killed. Its unfinished work is thrown away. Use it when the user asks to stop something, or under the rule below. \`all\` stops everything active.${sendFenceRules}
85
100
  - When you spawn a task that fixes or redoes a FINISHED one, \`castle-done\` the earlier row in the SAME reply. Keep the board meaning "what to look at right now".
86
- - Stop a running or waiting task only when the new message makes its work unwanted: the user said to stop or drop it, took back or reversed what it is building, or corrected it -- it has the wrong idea, or they picked a different option than the one it is building -- so its result would have to be undone. When that change comes with new work, stop it in the SAME reply that spawns the replacement. When the new ask adds to a running task, extends it, or is about something else, leave it running and spawn the new work as its own task: in parallel, or with \`after:\` naming it only when the new work needs that task's actual output. Nothing reaches a running task, so leaving it running never covers the new ask by itself. Never stop a task because a new one restates it or covers it more broadly.
101
+ ${runningTaskRules}
87
102
  - A \`failed\` row carries an \`error:\` line -- why it failed. A \`blocked\` row waited on a dep that failed or was stopped, so its output never arrived and it will never start on its own -- \`blocked by:\` names that dep. When you see one, decide for the user: usually spawn a replacement task (or pipeline) that redoes the failed work, and in the SAME reply \`castle-stop\` the blocked row and \`castle-done\` the failed one, so the board stays clean.
103
+ - A failed row whose error is a usage limit -- the free-model daily allowance, credits, or a spending limit -- will fail the same way if respawned. Do not respawn it. Tell the user what ran out, when it resets if the row says, and that they can pick another model in settings (or get credits) to keep going. You cannot choose the model tasks run on.
104
+ - An interrupted row with an \`interrupted:\` platform reason was cut off, not stopped by you. Tell the user, and redo it only if they want it (their message may already ask); part of its work may already be on disk.
88
105
  - Do not mark a task done to imply YOU verified its quality -- the user playtests and confirms that. But DO keep the board tidy: clear finished work the user blessed, and remove anything clearly obsolete. When genuinely unsure, leave the row.
89
106
  - Never claim the board is cleared without actually emitting the fence.
90
107
  - Tasks are one-and-done -- when the user gives feedback on a finished task, spawn a new fix task (and \`castle-done\` the old row) rather than reopening it -- unless their words ask to go back to an earlier state, which is the version-history rule below.
@@ -119,7 +136,7 @@ const PROBE_CAP_RULE = `- At most ONE probe open at a time; none on spec, delega
119
136
  // askCallsEnabled in agent.ts). Off for everyone by default, so the plan rules
120
137
  // stay byte-identical to a prompt built before it existed.
121
138
  const ASK_CALLS_SPEC_RULE = `- CLEAR SPEC (mechanics named, a reference given, "like X but Y"): build what they said; never probe taste they already expressed.`;
122
- const ASK_CALLS_PROBE_CAP_RULE = `- At most ONE probe open at a time; none on delegation or conversation turns; never re-probe something answered. Before you close a task fence, find the one thing that task will have to settle on its own: a word of theirs that reads two ways, or a case their ask never mentions. Quote the word and ask which, as a probe, your reading as the first chip and the other as the second. The work spawns either way; the chip only tells the next task which way it went.`;
139
+ const ASK_CALLS_PROBE_CAP_RULE = `- At most ONE probe open at a time; none on delegation or conversation turns; never re-probe something answered. Before you close a task fence, find the one thing that task will have to settle on its own: a word of theirs that reads two ways, or a case their ask never mentions. Quote the word and ask which, as a probe, your reading as the first chip and the other as the second. Then split the work by that answer. Tasks the answer cannot change spawn now. The task it decides gets a \`hold: answer\` line: it waits on the board and starts with their reply appended, whichever chip they tap or whatever they type. When the answer decides everything they asked for, the probe and that held task are the whole reply -- a held task is still building. Before you close each unheld task fence, reread its brief: if it names or assumes any option of your probe -- even in passing, like a control scheme, a count, or which screen -- that task decides it too. Give it the \`hold: answer\` line, or move that choice out of it into the held task and write the rest so it works with either answer. When they tap a chip, the task you held for it starts on its own with their answer -- the board shows it running with that answer. Acknowledge it in one line; never spawn it again or stop it. A row still held means they typed instead: if their message answers the probe, castle-stop the held row and spawn it again with their answer; otherwise leave it held.`;
123
140
  // Appended to the rules above for a deck with the plan doc on -- see
124
141
  // planSession in agent.ts for which decks those are. One self-contained block,
125
142
  // so a deck without it gets the pre-plan prompt byte for byte.
@@ -128,7 +145,10 @@ const ASK_CALLS_PROBE_CAP_RULE = `- At most ONE probe open at a time; none on de
128
145
  // deliberately supersede rules in the block above (pairing a question with
129
146
  // task directives, and holding follow-up questions back), which is why they say
130
147
  // so out loud rather than quietly contradicting them.
131
- function planRules(askCalls) {
148
+ const PROBE_CLAUSE_NO_STEER = 'But NEVER spawn work a pending probe could invalidate: there is no telling a running task anything.';
149
+ export const PROBE_CLAUSE_STEER = 'But NEVER spawn work a pending probe could invalidate outright: castle-send can pass the answer to a running task, but it cannot undo work the answer throws away.';
150
+ function planRules(askCalls, steer = false) {
151
+ const probeRunningTaskClause = steer ? PROBE_CLAUSE_STEER : PROBE_CLAUSE_NO_STEER;
132
152
  return `Reading the user, fresh from EACH message -- the same user hands you a spec, then a fragment, then delegates:
133
153
  ${askCalls ? ASK_CALLS_SPEC_RULE : SPEC_RULE}
134
154
  - FRAGMENT ("something with ants", "a cozy game about tea?"): gaps they cannot name yet. Draw their taste out on the few dimensions that decide whether this feels like THEIRS -- while building, never instead of building.
@@ -143,7 +163,7 @@ Probing while you build. A probe is one short plain question plus 2-4 tappable o
143
163
  [[Guide them with trails]] [[Command each ant]] [[Just watch them live]]
144
164
 
145
165
  - Tapping one sends its text as the user's next message; they can ignore it and type anything else, and the build continues either way. Never phrase a probe as if an answer were required.
146
- - Spawn the work the answer cannot invalidate AND attach the probe in the same reply -- this supersedes the rules above against pairing a question with task directives. But NEVER spawn work a pending probe could invalidate: there is no telling a running task anything.
166
+ - Spawn the work the answer cannot invalidate AND attach the probe in the same reply -- this supersedes the rules above against pairing a question with task directives. ${probeRunningTaskClause}
147
167
  ${askCalls ? ASK_CALLS_PROBE_CAP_RULE : PROBE_CAP_RULE}
148
168
  - Chips NEVER stand on their own: a probe's question is the line right before them, and a probe is the only thing they are for. Alone they read as answers to a question nobody asked.
149
169
  - Praise is where the pull to offer something is strongest and most wrong: "oh nice, that works great" gets one plain sentence and nothing else. Vary it -- a compliment that always gets the same reply stops reading as one.
@@ -179,9 +199,9 @@ Promotion. Finished tasks leave notes worth keeping, listed above with the id of
179
199
 
180
200
  If the user asks you to ease off the questions or the plan upkeep, record that with a \`decide+\` quoting the ask, and honor it -- keep \`## Now\` current, quietly.`;
181
201
  }
182
- function routerRules(plan, playtest, askCalls, playtestPref) {
183
- const base = baseRouterRules(playtest, playtestPref);
184
- return plan ? `${base}\n\n${planRules(askCalls)}` : base;
202
+ function routerRules(plan, playtest, askCalls, playtestPref, steer = false) {
203
+ const base = baseRouterRules(playtest, askCalls, playtestPref, steer);
204
+ return plan ? `${base}\n\n${planRules(askCalls, steer)}` : base;
185
205
  }
186
206
  function renderTranscriptLine(m) {
187
207
  if (m.role === "user")
@@ -871,10 +891,19 @@ function renderTasks(tasks, showItems) {
871
891
  const item = showItems && t.item ? ` -- item: ${t.item}` : "";
872
892
  const notes = t.notes.trim() ? ` -- notes: ${t.notes.trim()}` : "";
873
893
  const error = t.error ? ` -- error: ${t.error}` : "";
894
+ const interrupted = t.interrupted ? ` -- interrupted: ${t.interrupted}` : "";
874
895
  const blockedBy = t.blockedBy && t.blockedBy.length > 0
875
896
  ? ` -- blocked by: ${t.blockedBy.join(", ")}`
876
897
  : "";
877
- return `- [${t.status} ${t.progress}%] ${t.title} (${t.id})${item}${notes}${error}${blockedBy}`;
898
+ const sent = t.sent ? ` -- messages you sent it: ${t.sent}` : "";
899
+ const row = `- [${t.status} ${t.progress}%] ${t.title} (${t.id})${item}${notes}${error}${interrupted}${blockedBy}${sent}`;
900
+ const held = t.status === "held" && t.heldQuestion !== undefined
901
+ ? `\n held -- waiting on the answer to: ${t.heldQuestion}`
902
+ : "";
903
+ const answered = (t.status === "waiting" || t.status === "running") && t.answer !== undefined
904
+ ? `\n started with their answer: "${t.answer}"`
905
+ : "";
906
+ return `${row}${held}${answered}`;
878
907
  })
879
908
  .join("\n");
880
909
  }
@@ -888,6 +917,8 @@ export const NO_DECK_DOCS = "This deck has no CLAUDE.md / AGENTS.md quick refere
888
917
  // Muse agreed with them until told how it looked from their side (memo
889
918
  // 26-09-25-20-55: 7/27 -> 17/27 true answers).
890
919
  export const STOPPED_TASKS_HEADER = "Tasks you stopped with castle-stop. They started and you cancelled them; none finished. What the user saw: the task appeared on their board and then vanished. So if the user says a task never started, or asks where it went, say plainly that you stopped it (not that it never started), then re-send it if they still want it";
920
+ export const BAD_TASK_ENDINGS_HEADER = "Tasks that ended badly since your last reply. Tell the user about these at the start of your reply, plainly. Do not talk as if they are still running";
921
+ export const UNSENT_HEADER = "Your last reply's castle-send named no task on the board, so NOTHING was sent for these. If you told the user it was passed on, correct that now, and send it to the right task or spawn it";
891
922
  export function buildRouterPromptParts(opts) {
892
923
  // Making the ABSENCE explicit, not just omitting the section, matters: a
893
924
  // router on a bare/greenfield deck otherwise has no way to tell "no docs
@@ -927,6 +958,18 @@ export function buildRouterPromptParts(opts) {
927
958
  })
928
959
  .join("\n")}`
929
960
  : "";
961
+ const endedBadly = opts.endedBadly?.length
962
+ ? `\n\n${BAD_TASK_ENDINGS_HEADER}:\n${opts.endedBadly
963
+ .map((task) => {
964
+ const reason = task.error ?? task.interrupted;
965
+ const status = task.interrupted ? "interrupted" : "failed";
966
+ return `- "${task.title}" (${task.id}): ${status} at ${task.progress}%${reason ? ` -- ${reason}` : ""}`;
967
+ })
968
+ .join("\n")}`
969
+ : "";
970
+ const unsent = opts.unsentSends?.length
971
+ ? `\n\n${UNSENT_HEADER}:\n${opts.unsentSends.map((target) => `- "${target}"`).join("\n")}`
972
+ : "";
930
973
  // Two parts, split for prompt caching. `system` holds what is the same from
931
974
  // one turn to the next within a serve -- the rules, the deck identity and
932
975
  // the file tree -- and is sent as system text, which is the prefix the
@@ -934,7 +977,7 @@ export function buildRouterPromptParts(opts) {
934
977
  // does not. `user` holds what changes every turn: the transcript, the plan,
935
978
  // the board and this instruction.
936
979
  return {
937
- system: `${routerRules(opts.plan !== undefined, opts.playtest === true, opts.askCalls === true, opts.playtestPref)}
980
+ system: `${routerRules(opts.plan !== undefined, opts.playtest === true, opts.askCalls === true, opts.playtestPref, opts.steer === true)}
938
981
 
939
982
  == deck ==
940
983
  ${opts.deckLabel}${quickReference}${editorTabs}${kits}${deckFiles}`,
@@ -942,7 +985,7 @@ ${opts.deckLabel}${quickReference}${editorTabs}${kits}${deckFiles}`,
942
985
  ${renderTranscript(opts.messages)}${plan}
943
986
 
944
987
  == background tasks ==
945
- ${renderTasks(opts.tasks, opts.plan !== undefined)}${stopped}${paramsWrites}
988
+ ${renderTasks(opts.tasks, opts.plan !== undefined)}${endedBadly}${stopped}${unsent}${paramsWrites}
946
989
 
947
990
  == now ==
948
991
  ${opts.instruction}
@@ -983,7 +1026,11 @@ export function userTurnInstruction(opts) {
983
1026
  .join("\n\n")}`);
984
1027
  }
985
1028
  if (opts.attachments && opts.attachments.length > 0) {
986
- parts.push(`The user attached image file(s), saved in the deck at: ${opts.attachments.join(", ")}. Open them with your read tool. Take them into account; pass the paths along to task agents that need them.`);
1029
+ const marked = opts.marked ?? [];
1030
+ const markNote = marked.length > 0
1031
+ ? ` ${marked.join(", ")} ${marked.length === 1 ? "carries" : "carry"} the user's marks drawn on top of the game in red; numbered pins match the numbered lines in their message.`
1032
+ : "";
1033
+ parts.push(`The user attached image file(s), saved in the deck at: ${opts.attachments.join(", ")}. Open them with your read tool. Take them into account; pass the paths along to task agents that need them.${markNote}`);
987
1034
  }
988
1035
  if (opts.refs && opts.refs.length > 0) {
989
1036
  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.`);
package/dist/agent.d.ts CHANGED
@@ -1,7 +1,10 @@
1
1
  import { type EffortLevel } from './effortSupport.js';
2
2
  import * as http from 'http';
3
3
  import { Duplex } from 'stream';
4
- import { type PlaytestToolResult } from './native/playtest.js';
4
+ import { type TaskDirective } from './routerFences.js';
5
+ import { type SendDirective, type TaskSteer } from './taskSteer.js';
6
+ import { type StopTarget } from './routerStops.js';
7
+ import { type PlaytestExecutor, type PlaytestToolResult } from './native/playtest.js';
5
8
  export declare const AGENT_WS_PATH = "/__castle/agent";
6
9
  export type ClaudeModel = 'sonnet' | 'opus' | 'fable' | 'openrouter';
7
10
  export type { EffortLevel };
@@ -25,7 +28,10 @@ export declare function taskPlaytestFor(deckDir: string): {
25
28
  tool: boolean;
26
29
  };
27
30
  export declare function playtestToolArgs(tool: boolean, deckDir: string, taskId: string | undefined): string[];
28
- type TaskStatus = 'waiting' | 'running' | 'blocked' | 'done' | 'failed' | 'interrupted';
31
+ export declare const TASK_TIMEOUT_MS: number;
32
+ export declare const WRAP_UP_TIMEOUT_MS: number;
33
+ export declare const RESUME_MAX_AGE_MS: number;
34
+ type TaskStatus = 'held' | 'waiting' | 'running' | 'blocked' | 'done' | 'failed' | 'interrupted';
29
35
  interface TaskUsage {
30
36
  input?: number;
31
37
  output?: number;
@@ -54,6 +60,12 @@ interface TaskRecord {
54
60
  finishedAt?: string;
55
61
  pid?: number;
56
62
  originMessageId?: string;
63
+ heldFor?: {
64
+ messageId: string;
65
+ question: string;
66
+ chips: string[];
67
+ };
68
+ answer?: string;
57
69
  playtestFrames?: string[];
58
70
  resultSummary?: string;
59
71
  account?: string;
@@ -64,6 +76,9 @@ interface TaskRecord {
64
76
  phase?: string;
65
77
  acknowledged?: boolean;
66
78
  rejected?: boolean;
79
+ interruptedFrom?: 'running' | 'waiting';
80
+ interruptedAt?: string;
81
+ resumeCount?: number;
67
82
  durable?: string;
68
83
  what?: string;
69
84
  files?: string[];
@@ -78,18 +93,61 @@ interface TaskRecord {
78
93
  numTurns?: number;
79
94
  usage?: TaskUsage;
80
95
  modelUsage?: Record<string, TaskModelUsage>;
96
+ steers?: TaskSteer[];
81
97
  }
82
98
  export declare function playtestEnabled(deckDir: string): boolean;
83
99
  export declare function playtestPrefFor(deckDir: string): 'on' | 'off' | undefined;
84
100
  export declare function setPlaytestPref(deckDir: string, value: 'on' | 'off'): boolean;
85
101
  export declare function askCallsEnabled(deckDir: string): boolean;
102
+ interface AgentRunHandle {
103
+ pid?: number | undefined;
104
+ exitCode: number | null;
105
+ spawnfile: string;
106
+ kill(signal?: NodeJS.Signals): boolean;
107
+ }
86
108
  export interface DepsState {
87
109
  kind: 'ready' | 'waiting' | 'blocked';
88
110
  blockedBy?: string[];
89
111
  }
90
112
  export declare function classifyDeps(tasks: Map<string, TaskRecord>, task: TaskRecord): DepsState;
113
+ interface TaskStore {
114
+ sorted(): TaskRecord[];
115
+ get(id: string): TaskRecord | undefined;
116
+ /** Persist + broadcast a record the caller mutated in place. */
117
+ touch(task: TaskRecord): void;
118
+ spawnFromDirective(directive: TaskDirective, originMessageId: string, originText?: string): string;
119
+ releaseHeld(answer: string): string[];
120
+ acknowledge(id: string, rejected: boolean): TaskRecord | undefined;
121
+ checkOff(tokens: string[]): void;
122
+ stop(tokens: string[]): StopTarget[];
123
+ send(directives: SendDirective[], originMessageId?: string): string[];
124
+ pendingDurables(): TaskRecord[];
125
+ clearPendingDurables(): void;
126
+ resumeRecovered(): void;
127
+ shutdown(): void;
128
+ }
129
+ export declare function createTaskStore(opts: {
130
+ deckDir: string;
131
+ deckLabel: string;
132
+ tasksDir: string;
133
+ children: Set<AgentRunHandle>;
134
+ claudeModel: () => ClaudeModel;
135
+ openrouterModel: () => string;
136
+ effort: () => EffortLevel;
137
+ playtest?: {
138
+ executor: PlaytestExecutor;
139
+ serveUrl: string;
140
+ };
141
+ onUpdate: (task: TaskRecord) => void;
142
+ onStarted: (task: TaskRecord) => void;
143
+ onFinished: (task: TaskRecord) => void;
144
+ onRetry: (task: TaskRecord, attempt: number) => void;
145
+ onFeed: (task: TaskRecord, entry: string) => void;
146
+ }): TaskStore;
91
147
  export declare function computeSettingsWarnings(settings: AgentSettings): Promise<SettingsWarnings>;
92
148
  export interface AgentServer {
149
+ /** Start tasks recovered from a restart; call once the serve is listening. */
150
+ resumeRecovered(): void;
93
151
  /** Attach the agent WebSocket if the upgrade targets the agent path. */
94
152
  handleUpgrade(req: http.IncomingMessage, socket: Duplex, head: Buffer): boolean;
95
153
  /** Serve attachment images. Returns true if it handled the request. */
@@ -106,6 +164,7 @@ export interface AgentServer {
106
164
  }): Promise<PlaytestToolResult>;
107
165
  shutdown(): void;
108
166
  }
167
+ export declare function taskBoardIdle(taskStore: Pick<TaskStore, 'sorted'>): boolean;
109
168
  export declare function createAgentServer(opts: {
110
169
  deckDir: string;
111
170
  deckLabel: string;