@picassohq/cli 1.0.8 → 1.0.9

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.
@@ -0,0 +1,29 @@
1
+ {
2
+ "name": "@picasso/browser",
3
+ "version": "0.1.0",
4
+ "private": true,
5
+ "description": "dsh cordis plugin: browser_* model tools executed by the Picasso Mac app on the thread's Preview pane, or by the CLI's headless browser (localhost, thread files and public sites the person allows), over the picassoBrowser/* Host Remote service the helper relay or the CLI's SDK server long-polls.",
6
+ "type": "module",
7
+ "main": "index.js",
8
+ "exports": {
9
+ ".": "./index.js",
10
+ "./cordis.patch.yml": "./cordis.patch.yml",
11
+ "./package.json": "./package.json"
12
+ },
13
+ "dshTarget": "0.2.2-rc.3",
14
+ "dsh": {
15
+ "bundle": {
16
+ "patch": "./cordis.patch.yml"
17
+ }
18
+ },
19
+ "scripts": {
20
+ "test": "node --import ../../test/setup/hermetic-preload.mjs --test test/*.test.mjs"
21
+ },
22
+ "files": [
23
+ "index.js",
24
+ "page",
25
+ "cordis.patch.yml",
26
+ "README.md"
27
+ ],
28
+ "license": "UNLICENSED"
29
+ }
@@ -2,7 +2,7 @@
2
2
  // in the dsh command registry (ctx.commands). Handlers acknowledge the command;
3
3
  // execution stays on the picasso surface (TUI/CLI/Mac app).
4
4
  // Generated from packages/commands/src/manifest.ts (dsh's own goal/plan excluded).
5
- // The `init` and `worktree` registrations below are hand-maintained: unlike the
5
+ // The `init`, `worktree`, `plan-clear` and `review` registrations below are hand-maintained: unlike the
6
6
  // generated rows their handlers do the work in-dsh (`init` writes AGENTS.md into
7
7
  // the session workspace; `worktree` drives the engine's `worktrees` service).
8
8
  import { existsSync, readFileSync, writeFileSync } from 'node:fs'
@@ -463,6 +463,50 @@ async function reviewHandler(ctx, invocation) {
463
463
  }
464
464
  }
465
465
 
466
+ // ---- hand-maintained: /plan-clear ----------------------------------------------------------------
467
+ // Clears the session's plan (its todo list) the way the model's own `todo_write` with an empty list does: one
468
+ // `todo/write` record with `todos: []` in the session log, marked `clearedBy: 'user'`. Every surface folds "the last
469
+ // todo/write" into the plan it shows (TUI, Mac, the plan reminders), so the plan stays cleared after a reopen. The TUI's
470
+ // `/plan clear`, `picasso plan clear --session <id>` and the Mac's "Clear plan" all run this command. Owner 2026-11-18:
471
+ // a 6/10 plan from an earlier task showed beside a 100% progress bar through every close and reopen.
472
+
473
+ export const PLAN_CLEAR_COMMAND = 'plan-clear'
474
+ export const PLAN_CLEAR_DESCRIPTION = "Clear this session's plan (its todo list), e.g. one left from an earlier task."
475
+ export const PLAN_CLEARED_TEXT = 'Plan cleared.'
476
+ export const NO_PLAN_TEXT = 'There is no plan to clear.'
477
+
478
+ /** The session's last todo list (the newest `todo/write`), or undefined when it never wrote one. */
479
+ export function lastTodoList(session) {
480
+ const length = Number.isSafeInteger(session?.seq) ? session.seq : 0
481
+ if (typeof session?.eventAt !== 'function') return undefined
482
+ for (let seq = length - 1; seq >= 0; seq -= 1) {
483
+ let event
484
+ try {
485
+ event = session.eventAt(seq)
486
+ } catch {
487
+ event = undefined
488
+ }
489
+ if (event?.type === 'todo/write') return Array.isArray(event.data?.todos) ? event.data.todos : []
490
+ }
491
+ return undefined
492
+ }
493
+
494
+ /** `/plan-clear`: appends the empty `todo/write`; a session with no plan (or an already empty one) is left as it is. */
495
+ export function planClearHandler(invocation) {
496
+ const session = invocation?.agent?.session
497
+ if (session === undefined || session === null || typeof session.append !== 'function') {
498
+ return { kind: 'error', text: '/plan-clear needs a session — there is no calling agent.' }
499
+ }
500
+ const last = lastTodoList(session)
501
+ if (last === undefined || last.length === 0) return { kind: 'success', text: NO_PLAN_TEXT }
502
+ const event = session.append('todo/write', { todos: [], clearedBy: 'user' })
503
+ return {
504
+ kind: 'success',
505
+ text: PLAN_CLEARED_TEXT,
506
+ ...(Number.isSafeInteger(event?.seq) && event.seq >= 0 ? { sourceEventSeq: event.seq } : {}),
507
+ }
508
+ }
509
+
466
510
  export function apply(ctx) {
467
511
  for (const cmd of COMMANDS) {
468
512
  ctx.commands.register({
@@ -487,6 +531,12 @@ export function apply(ctx) {
487
531
  input: { hint: '[<name>]' },
488
532
  handler: (invocation) => worktreeHandler(ctx, invocation),
489
533
  });
534
+ // Real engine-side handler: records the cleared plan in the session log (see planClearHandler).
535
+ ctx.commands.register({
536
+ name: PLAN_CLEAR_COMMAND,
537
+ description: PLAN_CLEAR_DESCRIPTION,
538
+ handler: (invocation) => planClearHandler(invocation),
539
+ });
490
540
  // Real engine-side handler: starts the reviewer subagents and returns the merged findings.
491
541
  ctx.commands.register({
492
542
  name: 'review',
@@ -3686,7 +3686,7 @@ export function refuseModelWorktree() {
3686
3686
  };
3687
3687
  }
3688
3688
 
3689
- const DEFERRED_TOOL_ALIASES = Object.freeze({
3689
+ export const DEFERRED_TOOL_ALIASES = Object.freeze({
3690
3690
  cron_create: "schedule_create",
3691
3691
  cron_delete: "schedule_edit",
3692
3692
  cron_list: "schedule_list",
@@ -4023,6 +4023,28 @@ function hiddenFromSearch(toolName, toolsSvc, agent) {
4023
4023
  return false;
4024
4024
  }
4025
4025
 
4026
+ /**
4027
+ * Whether `tool_call` would run `toolName` for this agent: registered on the runtime tools service (by name or alias
4028
+ * target, or through the subagent-control redirect), a gateway-local search, or a `<server>_call` MCP gateway for a
4029
+ * server this process discovered. `tool_search` lists only these, so a session never finds a deferred tool (a static
4030
+ * catalog entry such as `browser_*` or `computer_*` on a surface that did not mount its plugin) that it cannot call.
4031
+ * No tools service, a service without `get`, or a throwing lookup lists the tool (fail-open). Tier 2 only.
4032
+ */
4033
+ export function resolvesForAgent(toolName, toolsSvc, agent, mcpServerNames = new Set()) {
4034
+ if (toolsSvc === undefined || toolsSvc === null || typeof toolsSvc.get !== "function") return true;
4035
+ if (GATEWAY_LOCAL_TARGETS.includes(toolName)) return true;
4036
+ const resolved = DEFERRED_TOOL_ALIASES[toolName] ?? toolName;
4037
+ try {
4038
+ if (toolsSvc.get(toolName, agent) || toolsSvc.get(resolved, agent)) return true;
4039
+ const steer = SUBAGENT_CONTROL_REDIRECTS[resolved];
4040
+ if (steer !== undefined && toolsSvc.get(steer, agent)) return true;
4041
+ } catch {
4042
+ return true;
4043
+ }
4044
+ const gateway = /^([a-zA-Z0-9_-]+)_call$/.exec(toolName);
4045
+ return gateway !== null && toolName !== "tool_call" && mcpServerNames.has(gateway[1]);
4046
+ }
4047
+
4026
4048
  const STATIC_TOOL_NAME_SET = new Set(STATIC_TOOL_CATALOG.map((item) => item.name));
4027
4049
 
4028
4050
  /**
@@ -4838,6 +4860,14 @@ export function visibleSkillCatalogText(session) {
4838
4860
  // resumed session keeps its counts.
4839
4861
 
4840
4862
  export const STALE_TODOS_SOURCE_KIND = "stale-todos";
4863
+ /**
4864
+ * What to do with a plan that belongs to an earlier task (owner 2026-11-18, session m0-d03430f0: the plan-state reminder
4865
+ * re-stated a 6/10 plan for a finished deploy three times; both models had moved on to other work and ignored a list that
4866
+ * no longer matched it, so the stale plan stayed in every panel). Every plan reminder says: replace it, or mark finished
4867
+ * and obsolete items completed, or clear it with an empty list (the engine's todo_write accepts `todos: []`).
4868
+ */
4869
+ export const PLAN_REPLACE_OR_CLEAR_LINE =
4870
+ "If it no longer matches what you are working on now, replace it with todo_write for the current work, or mark finished and obsolete items completed. If the current task has no plan, clear it: todo_write with an empty list (todos: []).";
4841
4871
  export const STALE_TODOS_TOOL_CALLS = 20;
4842
4872
  export const STALE_TODOS_MAX_PER_WRITE = 2;
4843
4873
 
@@ -4950,7 +4980,7 @@ export function renderStaleTodosReminder(todos) {
4950
4980
  active >= 0
4951
4981
  ? `step ${active + 1} still in progress`
4952
4982
  : `${open} of ${list.length} step${list.length === 1 ? "" : "s"} still open`;
4953
- return `<system-reminder>\nYour task list hasn't changed in a while (${where}). If you've moved on, update it with todo_write; if it no longer fits, replace it.\n</system-reminder>`;
4983
+ return `<system-reminder>\nYour task list hasn't changed in a while (${where}). Update it with todo_write as items finish. ${PLAN_REPLACE_OR_CLEAR_LINE}\n</system-reminder>`;
4954
4984
  }
4955
4985
 
4956
4986
  /** A frozen sourced user-role reminder message carrying the nudge. */
@@ -5083,6 +5113,7 @@ export function planNudgeReminderMessage() {
5083
5113
 
5084
5114
  export const PLAN_STATE_SOURCE_KIND = "plan-state";
5085
5115
  export const PLAN_STATE_UPDATE_LINE = "Update it with todo_write as items finish.";
5116
+ // PLAN_REPLACE_OR_CLEAR_LINE (defined with the stale-todos nudge) follows it: the plan may be from an earlier task.
5086
5117
  /** Items listed in full; a longer list names how many more there are. */
5087
5118
  export const PLAN_STATE_MAX_ITEMS = 40;
5088
5119
  /** Characters of one item (or the goal objective) kept; a longer one ends in "…". */
@@ -5263,6 +5294,7 @@ export function renderPlanStateReminder({ todos = [], goal, contractPath } = {})
5263
5294
  }
5264
5295
  if (list.length > PLAN_STATE_MAX_ITEMS) lines.push(`- … ${list.length - PLAN_STATE_MAX_ITEMS} more`);
5265
5296
  lines.push(PLAN_STATE_UPDATE_LINE);
5297
+ lines.push(PLAN_REPLACE_OR_CLEAR_LINE);
5266
5298
  }
5267
5299
  lines.push("</system-reminder>");
5268
5300
  return lines.join("\n");
@@ -6087,6 +6119,7 @@ export function apply(ctx, config = {}, deps = {}) {
6087
6119
  for (const entry of allEntries) {
6088
6120
  if (seenNames.has(entry.name)) continue;
6089
6121
  if (entry.name.startsWith("mcp__")) continue; // MCP tools are searched via <server>_call
6122
+ if (!resolvesForAgent(entry.name, toolsSvc, exec?.agent, mcpServers)) continue; // cataloged, not registered here
6090
6123
  if (hiddenFromSearch(entry.name, toolsSvc, exec?.agent)) continue; // e.g. computer_* on a model that can't use them
6091
6124
  if (groupFilter && groupFilter !== "all" && entry.group !== groupFilter) continue;
6092
6125
 
@@ -6470,11 +6503,8 @@ export function apply(ctx, config = {}, deps = {}) {
6470
6503
  // approval and sandbox. Only a context with no tools service at all (nothing to
6471
6504
  // bypass) may invoke a recorded handler directly.
6472
6505
  if (toolsSvc !== undefined && toolsSvc !== null) {
6473
- const refusal = formatSchemaOnError(
6474
- targetName,
6475
- `Deferred tool "${targetName}" is not registered on the runtime tools service for this agent; it was not run.`,
6476
- cachedSchema,
6477
- );
6506
+ // Not an argument problem: the plain line goes back without the schema, so the model does not retry it.
6507
+ const refusal = `Tool "${targetName}" is not available in this session (it is not registered on the runtime tools service for this agent); it was not run. Use tool_search({ query }) to see the tools this session can call.`;
6478
6508
  return {
6479
6509
  ok: false,
6480
6510
  isError: true,
@@ -91,7 +91,7 @@ export function managedRetryBudgetMs(env = process.env) {
91
91
  }
92
92
 
93
93
  /** Managed refusals that answer the same way however often they are retried (never waited out). */
94
- const DETERMINISTIC_MANAGED_REFUSAL = /secret_exposure_blocked|secret_read_denied|daily_limit|access_blocked|scope_forbidden|not_allowed|policy_required|allowance_required|budget_exceeded|account_suspended/u;
94
+ const DETERMINISTIC_MANAGED_REFUSAL = /request_rejected|secret_exposure_blocked|secret_read_denied|daily_limit|access_blocked|scope_forbidden|not_allowed|policy_required|allowance_required|budget_exceeded|account_suspended/u;
95
95
  /** Sessions whose wait counters are kept (a subagent is a session of its own); the oldest are dropped past this. */
96
96
  const MAX_TRACKED_SESSIONS = 256;
97
97
  /** Test/dev override of the wait (`PICASSO_RATE_LIMIT_WAIT_MS`). */
@@ -148,6 +148,16 @@ function freshState() {
148
148
  reportPercentSincePlan: undefined,
149
149
  /** A plan-drift nudge is in history since the last `todo/write`. */
150
150
  driftNudged: false,
151
+ /** When the last `todo/write` landed (the engine's clock), undefined before any. */
152
+ planWrittenAt: undefined,
153
+ /** Turns a person opened (not goal rounds, mail or schedules) since the last `todo/write`, the current one included. */
154
+ personTurnsSincePlan: 0,
155
+ /** A progress report was written after the last `todo/write`. */
156
+ reportSincePlan: false,
157
+ /** The current turn was opened by a person's prompt that is not a continuation ("continue", "go on", …). */
158
+ turnIsNewTask: false,
159
+ /** An earlier-task nudge is in history since the last `todo/write`. */
160
+ earlierTaskNudged: false,
151
161
  };
152
162
  }
153
163
 
@@ -156,6 +166,35 @@ function todosFrom(data) {
156
166
  return list.filter(isRecord).map((todo) => ({ status: typeof todo.status === 'string' ? todo.status : 'pending' }));
157
167
  }
158
168
 
169
+ /** A prompt a person typed (not a goal round, mail, a schedule or a harness reminder). */
170
+ export function isPersonPrompt(message) {
171
+ if (message?.role !== undefined && message.role !== 'user') return false;
172
+ const kind = message?.source?.kind;
173
+ return kind === undefined || kind === 'user';
174
+ }
175
+
176
+ /** Phrases that carry on the work in hand whatever follows them ("continue where you left off, why did you stop?"). */
177
+ const CONTINUATION_PROMPT = /^(?:continue|keep going|keep at it|go on|go ahead|carry on|proceed|resume|pick up where|finish (?:it|up)|retry|try again)\b/iu;
178
+ /** Words that carry on only as the whole prompt ("go", "ok do it"): "GO. Fix ONLY the digests" is a new instruction. */
179
+ const BARE_CONTINUATION = /^(?:go|next|ok(?:ay)?|yes|yep|sure|do it|finish)\b/iu;
180
+ const BARE_CONTINUATION_MAX_WORDS = 3;
181
+ /** Longest prompt still read as "carry on" rather than a new task. */
182
+ export const CONTINUATION_MAX_CHARS = 160;
183
+
184
+ /** Whether a person's prompt continues the work in hand ("continue where you left off", "go on") instead of starting a task. */
185
+ export function isContinuationPrompt(text) {
186
+ const flat = String(text ?? '').replace(/\s+/gu, ' ').trim();
187
+ if (flat.length === 0 || flat.length > CONTINUATION_MAX_CHARS) return false;
188
+ if (CONTINUATION_PROMPT.test(flat)) return true;
189
+ return BARE_CONTINUATION.test(flat) && flat.split(' ').length <= BARE_CONTINUATION_MAX_WORDS;
190
+ }
191
+
192
+ /** What a turn's opening message says about the task: whether a person opened it, and whether as a new task. */
193
+ function openerFacts(message) {
194
+ const person = isPersonPrompt(message);
195
+ return { person, newTask: person && !isContinuationPrompt(textOf(message)) };
196
+ }
197
+
159
198
  /** Fold one durable session event into the timing state. */
160
199
  export function foldEvent(state, event) {
161
200
  if (!isRecord(event)) return state;
@@ -164,6 +203,7 @@ export function foldEvent(state, event) {
164
203
  case 'turn/start':
165
204
  state.turnStart = time;
166
205
  state.openerSeen = false;
206
+ state.turnIsNewTask = false;
167
207
  // A new turn is a new prompt (or goal round): no follow-up carries over into it.
168
208
  state.awaitingAnswer = false;
169
209
  state.followUpDue = false;
@@ -174,6 +214,9 @@ export function foldEvent(state, event) {
174
214
  state.openerSeen = true;
175
215
  // A goal round continues the run it belongs to; anything else (a prompt, mail, a schedule) starts one.
176
216
  if (!isGoalRound(message) || state.runStart === undefined) state.runStart = state.turnStart ?? time;
217
+ const opener = openerFacts(message);
218
+ if (opener.person) state.personTurnsSincePlan += 1;
219
+ state.turnIsNewTask = opener.newTask;
177
220
  }
178
221
  if (message?.source?.kind === SOURCE_KIND && time !== undefined) {
179
222
  state.lastReminder = time;
@@ -183,16 +226,22 @@ export function foldEvent(state, event) {
183
226
  state.followUpDue = false;
184
227
  }
185
228
  if (message?.source?.kind === DRIFT_SOURCE_KIND) state.driftNudged = true;
229
+ if (message?.source?.kind === EARLIER_TASK_SOURCE_KIND) state.earlierTaskNudged = true;
186
230
  break;
187
231
  }
188
232
  case 'todo/write':
189
233
  state.todos = todosFrom(event.data);
190
234
  state.reportPercentSincePlan = undefined;
191
235
  state.driftNudged = false;
236
+ state.planWrittenAt = time;
237
+ state.personTurnsSincePlan = 0;
238
+ state.reportSincePlan = false;
239
+ state.earlierTaskNudged = false;
192
240
  break;
193
241
  case 'assistant/message': {
194
242
  const report = parseProgressReport(textOf(event.data?.message));
195
243
  if (report !== undefined && report.percent !== undefined) state.reportPercentSincePlan = report.percent;
244
+ if (report !== undefined) state.reportSincePlan = true;
196
245
  if (time !== undefined && report !== undefined) {
197
246
  state.lastReport = time;
198
247
  if (!state.reminderPending) state.selfReporting = true;
@@ -370,7 +419,7 @@ export function renderPlanDrift(reported, todos) {
370
419
  const list = Array.isArray(todos) ? todos : [];
371
420
  const done = list.filter((todo) => todo?.status === 'completed').length;
372
421
  const plan = Math.round(planCompletion(list));
373
- return `<system-reminder>\nYour latest progress report says ${reported}% done, but your todo list shows ${plan}% (${done} of ${list.length} step${list.length === 1 ? '' : 's'} completed). Update it with todo_write so the plan matches the work, then keep going.\n</system-reminder>`;
422
+ return `<system-reminder>\nYour latest progress report says ${reported}% done, but your todo list shows ${plan}% (${done} of ${list.length} step${list.length === 1 ? '' : 's'} completed). Update it with todo_write so the plan matches the work; if it no longer matches what you are working on now, replace it for the current work, or clear it with todo_write and an empty list (todos: []). Then keep going.\n</system-reminder>`;
374
423
  }
375
424
 
376
425
  /** A frozen sourced user-role reminder carrying the plan-drift nudge. */
@@ -383,6 +432,67 @@ export function planDriftMessage(reported, todos) {
383
432
  });
384
433
  }
385
434
 
435
+ // ── Plan from an earlier task (Tier 2) ────────────────────────────────────────────────────────────────────────
436
+ //
437
+ // Owner 2026-11-18 (session m0-d03430f0): a 6/10 plan for the Kimi deploy (last todo_write 05:01Z) stayed in every panel
438
+ // through the Mythos hierarchy deploy, which the progress reports took to 100%. The person had started new tasks; the
439
+ // models (Fable, Gemini, DeepSeek) never touched a checklist that no longer matched their work, and nothing told them it
440
+ // belonged to an earlier task. So when a person starts a new task (a turn whose prompt is not a continuation) and the
441
+ // plan, still open, has gone untouched for more than PLAN_EARLIER_TASK_TURNS of their turns while progress reports moved
442
+ // on past it, that turn gets ONE sourced `<system-reminder>` at the tail: rewrite the plan for this task or clear it.
443
+ // Once per `todo/write`; top-level agents only; the text depends only on history (the write's time, its counts and the
444
+ // turn count), so identical history yields identical bytes. Tier 1 is never touched.
445
+
446
+ export const EARLIER_TASK_SOURCE_KIND = 'picasso-plan-earlier-task';
447
+ /** A plan untouched for MORE than this many person turns (and older than the newest report) is from an earlier task. */
448
+ export const PLAN_EARLIER_TASK_TURNS = 3;
449
+
450
+ const TODO_DONE = new Set(['completed', 'cancelled', 'canceled', 'done', 'skipped']);
451
+ const hasOpenTodos = (todos) => Array.isArray(todos) && todos.some((todo) => !TODO_DONE.has(String(todo?.status ?? 'pending')));
452
+
453
+ /**
454
+ * `{ writtenAt, turns }` when the earlier-task nudge is due, else undefined: an open plan, a person's new-task prompt
455
+ * opening this turn (`proposed` holds it on the turn's first step), more than PLAN_EARLIER_TASK_TURNS person turns since
456
+ * the plan's last write, a progress report since it, and no nudge yet for this write.
457
+ */
458
+ export function planEarlierTaskDue(state, proposed = []) {
459
+ if (!isRecord(state) || state.earlierTaskNudged === true || !hasOpenTodos(state.todos)) return undefined;
460
+ let turns = state.personTurnsSincePlan;
461
+ let newTask = state.turnIsNewTask === true;
462
+ if (!state.openerSeen) {
463
+ const opener = (Array.isArray(proposed) ? proposed : []).find((message) => message?.role === 'user');
464
+ const facts = opener === undefined ? { person: false, newTask: false } : openerFacts(opener);
465
+ if (facts.person) turns += 1;
466
+ newTask = facts.newTask;
467
+ }
468
+ if (!newTask || turns <= PLAN_EARLIER_TASK_TURNS || state.reportSincePlan !== true) return undefined;
469
+ return { ...(state.planWrittenAt === undefined ? {} : { writtenAt: state.planWrittenAt }), turns };
470
+ }
471
+
472
+ /** `2026-11-18 05:01 UTC`: UTC, so the same history gives the same bytes on every machine. */
473
+ function utcMinute(time) {
474
+ const iso = new Date(time).toISOString();
475
+ return `${iso.slice(0, 10)} ${iso.slice(11, 16)} UTC`;
476
+ }
477
+
478
+ /** The nudge text: when the plan was last written, its counts and how many turns it sat untouched. */
479
+ export function renderPlanEarlierTask({ writtenAt, turns } = {}, todos = []) {
480
+ const list = Array.isArray(todos) ? todos : [];
481
+ const done = list.filter((todo) => todo?.status === 'completed').length;
482
+ const when = Number.isFinite(writtenAt) ? `last updated ${utcMinute(writtenAt)}` : 'last updated in an earlier turn';
483
+ return `<system-reminder>\nYour plan is from an earlier task (${when}, ${done} of ${list.length} done, untouched for ${turns} turns while your progress reports moved on): rewrite it for this task with todo_write, or clear it with todo_write and an empty list (todos: []) if this task needs no plan.\n</system-reminder>`;
484
+ }
485
+
486
+ /** A frozen sourced user-role reminder carrying the earlier-task nudge. */
487
+ export function planEarlierTaskMessage(due, todos) {
488
+ return Object.freeze({
489
+ role: 'user',
490
+ content: Object.freeze([Object.freeze({ type: 'text', text: renderPlanEarlierTask(due, todos) })]),
491
+ source: Object.freeze({ kind: EARLIER_TASK_SOURCE_KIND, form: 'reminder' }),
492
+ id: randomUUID(),
493
+ });
494
+ }
495
+
386
496
  export function apply(ctx, config = {}, deps = {}) {
387
497
  const readSettings = deps.settings ?? settingsReader(config, deps.env ?? process.env);
388
498
  const clock = deps.now ?? Date.now;
@@ -396,9 +506,17 @@ export function apply(ctx, config = {}, deps = {}) {
396
506
  const session = agent?.session;
397
507
  if (!session || typeof session.eventAt !== 'function' || isChildAgent(agent)) return decision;
398
508
  const state = scanSession(states, session);
399
- // The plan-drift nudge reads only history; it is not the timed report reminder, so that setting does not gate it.
400
- const drift = decision.messages.some((message) => message?.source?.kind === DRIFT_SOURCE_KIND) ? undefined : planDriftDue(state, decision.messages);
509
+ // The plan nudges read only history; they are not the timed report reminder, so that setting does not gate them.
401
510
  const extra = [];
511
+ const earlier = decision.messages.some((message) => message?.source?.kind === EARLIER_TASK_SOURCE_KIND) ? undefined : planEarlierTaskDue(state, decision.messages);
512
+ if (earlier !== undefined) {
513
+ // Recorded now so a step that is rejected downstream cannot send it twice before its event lands. It says more
514
+ // than the percent drift nudge would about this plan, so that one is spent for this write too.
515
+ state.earlierTaskNudged = true;
516
+ state.driftNudged = true;
517
+ extra.push(planEarlierTaskMessage(earlier, state.todos));
518
+ }
519
+ const drift = earlier !== undefined || decision.messages.some((message) => message?.source?.kind === DRIFT_SOURCE_KIND) ? undefined : planDriftDue(state, decision.messages);
402
520
  if (drift !== undefined) {
403
521
  // Recorded now so a step that is rejected downstream cannot send it twice before its event lands.
404
522
  state.driftNudged = true;
@@ -0,0 +1,94 @@
1
+ // The CLI's browser host: hands the agent's queued `browser_*` actions to the Picasso client process.
2
+ //
3
+ // packages/picasso-browser queues each browser tool call on its Host Remote service (`picassoBrowser`). On the Mac the
4
+ // relay long-polls it and the app runs actions on the thread's Preview. A CLI engine session has no relay: when the
5
+ // client says it runs a browser (`picasso/capabilities` `client.browser`), this pump long-polls the same service in the
6
+ // engine process and sends every action to the client as a `browser/action` server request (the client runs it on its
7
+ // headless Chromium, packages/core browser-host.ts). The answer `{ok, value?, error?}` completes the action through
8
+ // `picassoBrowser/complete`; ids the plugin cancelled (tool-call abort, per-action timeout) go out as
9
+ // `browser.cancelled {actionIds}` so the client drops them. No browser plugin mounted (switched off): the pump stops.
10
+
11
+ export const BROWSER_ACTION_REQUEST = 'browser/action';
12
+ export const BROWSER_CANCELLED_NOTIFICATION = 'browser.cancelled';
13
+ /** The long-poll window; well inside the plugin's 30 s no-poller window. */
14
+ export const BROWSER_TAKE_MS = 25_000;
15
+
16
+ /**
17
+ * @param {object} deps
18
+ * @param {() => any} deps.service - the mounted `picassoBrowser` service, or undefined.
19
+ * @param {(method: string, params: object, signal?: AbortSignal) => Promise<any>} deps.request - server -> client request.
20
+ * @param {(method: string, params: object) => void} deps.notify - server -> client notification.
21
+ * @param {(ms: number) => Promise<void>} [deps.sleep]
22
+ */
23
+ export function createBrowserHostPump(deps) {
24
+ const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms).unref?.()));
25
+ let running = false;
26
+ let abort = new AbortController();
27
+
28
+ const complete = (service, action, ok, value, error) => {
29
+ try {
30
+ service.complete(action.actionId, ok, value, error, action.sessionId);
31
+ } catch {
32
+ // Already settled (cancelled, timed out): the plugin dropped it.
33
+ }
34
+ };
35
+
36
+ const run = async (service, action) => {
37
+ try {
38
+ const answer = await deps.request(BROWSER_ACTION_REQUEST, { action }, abort.signal);
39
+ if (answer?.ok === true) complete(service, action, true, answer.value ?? { text: '' }, undefined);
40
+ else complete(service, action, false, undefined, typeof answer?.error === 'string' && answer.error ? answer.error : 'The browser action failed.');
41
+ } catch (error) {
42
+ complete(service, action, false, undefined, error instanceof Error && error.message ? error.message : 'The browser action failed.');
43
+ }
44
+ };
45
+
46
+ const loop = async () => {
47
+ let backoff = 1_000;
48
+ while (running) {
49
+ const service = deps.service();
50
+ if (service === undefined || service === null || typeof service.take !== 'function') {
51
+ running = false;
52
+ return;
53
+ }
54
+ let batch;
55
+ try {
56
+ batch = await service.take(BROWSER_TAKE_MS, abort.signal);
57
+ } catch {
58
+ if (!running) return;
59
+ await sleep(backoff);
60
+ backoff = Math.min(backoff * 2, 30_000);
61
+ continue;
62
+ }
63
+ backoff = 1_000;
64
+ if (!running) return;
65
+ const cancelled = (batch?.cancelled ?? []).filter((id) => typeof id === 'string');
66
+ if (cancelled.length > 0) {
67
+ try {
68
+ deps.notify(BROWSER_CANCELLED_NOTIFICATION, { actionIds: cancelled });
69
+ } catch {
70
+ // the client went away; its actions fail on their own timeout
71
+ }
72
+ }
73
+ for (const action of batch?.actions ?? []) {
74
+ if (action && typeof action.actionId === 'string' && typeof action.sessionId === 'string') void run(service, action);
75
+ }
76
+ }
77
+ };
78
+
79
+ return {
80
+ get running() {
81
+ return running;
82
+ },
83
+ start() {
84
+ if (running) return;
85
+ running = true;
86
+ abort = new AbortController();
87
+ void loop();
88
+ },
89
+ stop() {
90
+ running = false;
91
+ abort.abort();
92
+ },
93
+ };
94
+ }
@@ -67,6 +67,7 @@ import { createInstructions, INSTRUCTIONS_METHODS } from './instructions.js';
67
67
  import { createProviderReload, PROVIDER_RELOAD_METHODS } from './provider-reload.js';
68
68
  import { APPROVAL_NOTE_METHODS, createApprovalNotes } from './approval-notes.js';
69
69
  import { CONTINUE_METHODS, createCrashContinue } from './crash-continue.js';
70
+ import { BROWSER_ACTION_REQUEST, BROWSER_CANCELLED_NOTIFICATION, createBrowserHostPump } from './browser-host.js';
70
71
 
71
72
  /** An approval a hooks.json decision hook asked for (packages/picasso-hooks decisions.js HOOK_ASK_REASON). */
72
73
  const HOOK_ASK_REASON = /^Hook "[^"\n]+" asks: /u;
@@ -190,7 +191,22 @@ export function apply(ctx, config = {}) {
190
191
  });
191
192
 
192
193
  /** Client-announced capabilities (picasso/capabilities params.client). */
193
- const client = { approvals: false, questions: false, deltas: false };
194
+ const client = { approvals: false, questions: false, deltas: false, browser: false };
195
+ /**
196
+ * The CLI's browser host (browser-host.js): with `client.browser`, the agent's queued `browser_*` actions go to the
197
+ * client as `browser/action` requests and run on its headless Chromium instead of waiting for a Mac app.
198
+ */
199
+ const browserPump = createBrowserHostPump({
200
+ service: () => {
201
+ try {
202
+ return ctx.get?.('picassoBrowser');
203
+ } catch {
204
+ return undefined;
205
+ }
206
+ },
207
+ request: (method, params, signal) => transport.request(method, params, signal),
208
+ notify: (method, params) => transport.notify(method, params),
209
+ });
194
210
  /** Session-scoped "allow for session" grants (session-grants.js). */
195
211
  const grants = createSessionGrants();
196
212
  /** Pending server->client asks that `approval/respond` / `question/respond` may settle out of band. */
@@ -764,11 +780,14 @@ export function apply(ctx, config = {}) {
764
780
  client.approvals = params?.client?.approvals === true;
765
781
  client.questions = params?.client?.questions === true;
766
782
  client.deltas = params?.client?.deltas === true;
783
+ client.browser = params?.client?.browser === true;
784
+ if (client.browser) browserPump.start();
785
+ else browserPump.stop();
767
786
  return {
768
787
  server: name,
769
788
  methods: [...PICASSO_SDK_METHODS],
770
- notifications: [SESSION_DELTA_METHOD, QUEUE_NOTIFICATION],
771
- serverRequests: ['approval/request', 'question/request'],
789
+ notifications: [SESSION_DELTA_METHOD, QUEUE_NOTIFICATION, BROWSER_CANCELLED_NOTIFICATION],
790
+ serverRequests: ['approval/request', 'question/request', BROWSER_ACTION_REQUEST],
772
791
  client: { ...client },
773
792
  };
774
793
  },
@@ -920,6 +939,7 @@ export function apply(ctx, config = {}) {
920
939
  let exitTask;
921
940
  const disposeAndExit = () => {
922
941
  exitTask ??= (async () => {
942
+ browserPump.stop();
923
943
  await Promise.allSettled([Promise.resolve().then(() => transport.flush())]);
924
944
  await Promise.allSettled([Promise.resolve().then(() => rootFiber.dispose())]);
925
945
  exit(0);