@picassohq/cli 1.0.6 → 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.
Files changed (42) hide show
  1. package/LICENSE +14 -0
  2. package/README.md +104 -0
  3. package/dist/build-info.json +1 -1
  4. package/dist/index.js +1955 -1530
  5. package/package.json +27 -5
  6. package/runtime/dsh/picasso-providers.patch.yml +49 -61
  7. package/runtime/dsh/picasso-runtime.cordis.yml +49 -61
  8. package/runtime/engine-manifest.json +18 -8
  9. package/runtime/packages/picasso-browser/cordis.patch.yml +4 -0
  10. package/runtime/packages/picasso-browser/index.js +915 -0
  11. package/runtime/packages/picasso-browser/package.json +29 -0
  12. package/runtime/packages/picasso-commands/index.js +51 -1
  13. package/runtime/packages/picasso-compaction/index.js +116 -1
  14. package/runtime/packages/picasso-computer/cordis.patch.yml +5 -0
  15. package/runtime/packages/picasso-computer/index.js +670 -0
  16. package/runtime/packages/picasso-computer/native-anthropic.js +212 -0
  17. package/runtime/packages/picasso-computer/package.json +30 -0
  18. package/runtime/packages/picasso-computer/support.js +95 -0
  19. package/runtime/packages/picasso-lean-context/index.js +751 -15
  20. package/runtime/packages/picasso-lean-context/timeline.js +3 -2
  21. package/runtime/packages/picasso-model-router/connections.js +1 -1
  22. package/runtime/packages/picasso-progress-reports/index.js +121 -3
  23. package/runtime/packages/picasso-sdk-server/browser-host.js +94 -0
  24. package/runtime/packages/picasso-sdk-server/index.js +23 -3
  25. package/runtime/plugins/picasso-browser/index.js +319 -22
  26. package/runtime/plugins/picasso-browser/package.json +1 -1
  27. package/runtime/plugins/picasso-commands/index.js +51 -1
  28. package/runtime/plugins/picasso-compaction/index.js +116 -1
  29. package/runtime/plugins/picasso-computer/index.js +670 -0
  30. package/runtime/plugins/picasso-computer/native-anthropic.js +212 -0
  31. package/runtime/plugins/picasso-computer/package.json +30 -0
  32. package/runtime/plugins/picasso-computer/support.js +95 -0
  33. package/runtime/plugins/picasso-lean-context/index.js +751 -15
  34. package/runtime/plugins/picasso-lean-context/timeline.js +3 -2
  35. package/runtime/plugins/picasso-model-router/connections.js +1 -1
  36. package/runtime/plugins/picasso-progress-reports/index.js +121 -3
  37. package/runtime/relay/main.mjs +5005 -2250
  38. package/runtime/relay/remote/index.html +10 -2
  39. package/runtime/relay/remote/remote.css +8 -1
  40. package/runtime/relay/remote/remote.js +78 -17
  41. package/runtime/relay/versions-routes.mjs +52 -37
  42. package/scripts/install-runtime.mjs +33 -7
@@ -29,8 +29,19 @@
29
29
  // referenced — never inlined — when the current model declares image input. The adapter is loaded with createRequire
30
30
  // anchored at `config.dshBin` (the realpath of the launched dsh bin, passed by the relay's generated patch). When it
31
31
  // cannot resolve, the same tools register text-only and browser_screenshot returns a text error.
32
+ //
33
+ // CLI host (`config.host: 'cli'`, the CLI's own engine sessions on every OS): the picasso-sdk-server hands each queued
34
+ // action to the CLI process (`browser/action`), which runs it on a headless Chromium (packages/core browser-host.ts).
35
+ // There the plugin keeps the person's site rules itself, as the Mac app does: localhost and files in the thread's
36
+ // folder open directly (no tool ask); a public site not yet allowed asks once through the engine's user-questions
37
+ // service (Allow once / Always allow <site> / Deny), so the TUI shows it in every permission mode; "Always allow"
38
+ // lands in `config.sitesFile` (`<picassoHome>/settings/browser-sites.json`, the list Picasso for Mac shares). Each
39
+ // action carries the thread's folder and allowed sites (`cwd`, `sites`) so the executor can refuse every other load.
40
+ import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from 'node:fs';
32
41
  import { createRequire } from 'node:module';
33
- import { pathToFileURL } from 'node:url';
42
+ import { homedir } from 'node:os';
43
+ import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
44
+ import { fileURLToPath, pathToFileURL } from 'node:url';
34
45
 
35
46
  export const name = 'picasso-browser';
36
47
  export const dshTarget = '0.2.2-rc.3';
@@ -48,6 +59,10 @@ export const TAKE_DEFAULT_MS = 25_000;
48
59
 
49
60
  export const APP_CLOSED = 'Browser tools need the Picasso Mac app open.';
50
61
  export const ACTION_TIMEOUT = "The Picasso preview didn't respond.";
62
+ /** CLI host: the terminal that runs this session's browser stopped polling (it quit or never started one). */
63
+ export const CLI_HOST_GONE = "This session's browser isn't running (the terminal that started the session is gone). Start the session again in Picasso.";
64
+ export const CLI_ACTION_TIMEOUT = "The browser didn't respond.";
65
+ export const FILE_OUTSIDE_REFUSAL = "Only files inside this thread's folder open in the Picasso browser.";
51
66
  export const PRIVATE_REFUSAL =
52
67
  'Private-network addresses never open in the Picasso browser. Only localhost dev servers and public sites the person allows open there.';
53
68
  export const UNSUPPORTED_REFUSAL =
@@ -356,9 +371,13 @@ export function needsAsk(exec) {
356
371
  return args.action === 'new' && typeof args.url === 'string' && args.url.trim() !== '';
357
372
  }
358
373
 
359
- /** The `tools/pre-execute` listener: ask for page-changing calls, delegate everything else. */
360
- export function preExecute(exec, next) {
374
+ /**
375
+ * The `tools/pre-execute` listener: ask for page-changing calls, delegate everything else. On the CLI host an address
376
+ * never asks as a tool: localhost and thread files open directly and a public site asks its own question (CliSites).
377
+ */
378
+ export function preExecute(exec, next, host) {
361
379
  if (!needsAsk(exec)) return next();
380
+ if (host === 'cli' && (exec.name === 'browser_navigate' || exec.name === 'browser_tabs')) return next();
362
381
  const reason = askReason(exec);
363
382
  return Promise.resolve({ kind: 'ask', reason, displayReason: { en: reason } });
364
383
  }
@@ -374,6 +393,8 @@ export class BrowserActions {
374
393
  this.now = options.now ?? Date.now;
375
394
  this.noPollerMs = options.noPollerMs ?? NO_POLLER_MS;
376
395
  this.actionTimeoutMs = options.actionTimeoutMs ?? ACTION_TIMEOUT_MS;
396
+ this.closedMessage = options.closedMessage ?? APP_CLOSED;
397
+ this.timeoutMessage = options.timeoutMessage ?? ACTION_TIMEOUT;
377
398
  this.queue = [];
378
399
  this.inflight = new Map();
379
400
  this.cancelledIds = [];
@@ -435,14 +456,14 @@ export class BrowserActions {
435
456
  * Queue one action for `sessionId` and wait for its outcome. Rejects fast when no poller is live, after the
436
457
  * per-action timeout, or when the tool call's signal aborts (the action is then listed in the next `cancelled`).
437
458
  */
438
- issue(sessionId, callId, tool, args, signal) {
439
- if (this.now() - this.lastPollAt > this.noPollerMs) return Promise.reject(new Error(APP_CLOSED));
459
+ issue(sessionId, callId, tool, args, signal, extra) {
460
+ if (this.now() - this.lastPollAt > this.noPollerMs) return Promise.reject(new Error(this.closedMessage));
440
461
  const actionId = `ba-${++this.seq}`;
441
- const action = { actionId, sessionId, callId, tool, args: isRecord(args) ? args : {}, issuedAt: this.now() };
462
+ const action = { actionId, sessionId, callId, tool, args: isRecord(args) ? args : {}, issuedAt: this.now(), ...(isRecord(extra) ? extra : {}) };
442
463
  const promise = new Promise((resolve, reject) => {
443
464
  action.resolve = resolve;
444
465
  action.reject = reject;
445
- action.timer = setTimeout(() => this.expire(actionId, new Error(ACTION_TIMEOUT)), this.actionTimeoutMs);
466
+ action.timer = setTimeout(() => this.expire(actionId, new Error(this.timeoutMessage)), this.actionTimeoutMs);
446
467
  action.timer.unref?.();
447
468
  if (signal) {
448
469
  action.signal = signal;
@@ -536,18 +557,243 @@ export function argProblem(tool, args) {
536
557
  * Run one tool call: validate, queue, await the Mac's outcome. Returns `{text, image?}` (normalized Mac value).
537
558
  * `exec.agent.id` is the session id (dsh's Agent id is the SessionId) — the action's routing key to the Mac.
538
559
  */
539
- export async function runAction(actions, exec) {
560
+ export async function runAction(actions, exec, cliHost) {
540
561
  const args = isRecord(exec.arguments) ? exec.arguments : {};
541
562
  const problem = argProblem(exec.name, args);
542
563
  if (problem) throw new Error(problem);
543
564
  const sessionId = exec.agent?.id;
544
565
  if (typeof sessionId !== 'string' || !sessionId) throw new Error('browser actions need an agent session');
545
- const { promise } = actions.issue(sessionId, String(exec.callId ?? ''), exec.name, args, exec.signal);
546
- return await promise;
566
+ const extra = cliHost === undefined ? undefined : await cliHost.admit(exec, args, sessionId);
567
+ const issued = actions.issue(sessionId, String(exec.callId ?? ''), exec.name, args, exec.signal, extra);
568
+ // No poller: `issue` answers with the rejected promise itself (its message is the model's reason).
569
+ if (typeof issued?.then === 'function') return await issued;
570
+ return await issued.promise;
571
+ }
572
+
573
+ // ── CLI host: the person's sites, kept by the plugin (the Mac app keeps them itself) ─────────────────────────
574
+
575
+ export const SITES_FILE_VERSION = 1;
576
+
577
+ /** The always-allowed sites in `<picassoHome>/settings/browser-sites.json` (`{version: 1, sites: [{site, addedAt}]}`). */
578
+ export function readAllowedSites(file) {
579
+ if (typeof file !== 'string' || file === '') return [];
580
+ try {
581
+ const stored = JSON.parse(readFileSync(file, 'utf8'));
582
+ const sites = Array.isArray(stored?.sites) ? stored.sites : [];
583
+ return [...new Set(sites.map((entry) => String(entry?.site ?? '').toLowerCase()).filter((site) => site !== ''))].sort();
584
+ } catch {
585
+ return [];
586
+ }
587
+ }
588
+
589
+ /** Add one site to the shared list (atomic write, sorted, earlier `addedAt` kept), as the Mac's Settings does. */
590
+ export function addAllowedSite(file, site, now = () => new Date()) {
591
+ const key = String(site ?? '').toLowerCase();
592
+ if (typeof file !== 'string' || file === '' || key === '') return false;
593
+ let previous = [];
594
+ try {
595
+ const stored = JSON.parse(readFileSync(file, 'utf8'));
596
+ previous = Array.isArray(stored?.sites) ? stored.sites.filter((entry) => typeof entry?.site === 'string' && entry.site !== '') : [];
597
+ } catch {
598
+ previous = [];
599
+ }
600
+ if (previous.some((entry) => entry.site.toLowerCase() === key)) return true;
601
+ // ISO 8601 without fractions, as the Mac's ISO8601DateFormatter writes it.
602
+ const stamp = now().toISOString().replace(/\.\d{3}Z$/, 'Z');
603
+ const sites = [...previous.map((entry) => ({ addedAt: typeof entry.addedAt === 'string' ? entry.addedAt : stamp, site: entry.site.toLowerCase() })), { addedAt: stamp, site: key }]
604
+ .sort((a, b) => a.site.localeCompare(b.site));
605
+ mkdirSync(dirname(file), { recursive: true });
606
+ const temp = `${file}.${process.pid}.${Date.now()}.tmp`;
607
+ writeFileSync(temp, `${JSON.stringify({ sites, version: SITES_FILE_VERSION }, null, 2)}\n`, { mode: 0o600 });
608
+ renameSync(temp, file);
609
+ return true;
610
+ }
611
+
612
+ /** Remove one site from the shared list (the Mac's Settings › Browser remove). True when it was listed. */
613
+ export function removeAllowedSite(file, site) {
614
+ const key = String(site ?? '').toLowerCase();
615
+ if (typeof file !== 'string' || file === '' || key === '') return false;
616
+ let stored;
617
+ try {
618
+ stored = JSON.parse(readFileSync(file, 'utf8'));
619
+ } catch {
620
+ return false;
621
+ }
622
+ const sites = Array.isArray(stored?.sites) ? stored.sites.filter((entry) => typeof entry?.site === 'string' && entry.site !== '') : [];
623
+ const kept = sites.filter((entry) => entry.site.toLowerCase() !== key);
624
+ if (kept.length === sites.length) return false;
625
+ const temp = `${file}.${process.pid}.${Date.now()}.tmp`;
626
+ writeFileSync(temp, `${JSON.stringify({ sites: kept, version: SITES_FILE_VERSION }, null, 2)}\n`, { mode: 0o600 });
627
+ renameSync(temp, file);
628
+ return true;
629
+ }
630
+
631
+ /** The site-question options, in the Mac card's order. */
632
+ export const SITE_ALLOW_ONCE = 'Allow once';
633
+ export const SITE_DENY = 'Deny';
634
+ export function siteAlwaysLabel(site) {
635
+ return `Always allow ${site}`;
636
+ }
637
+
638
+ /** The engine user-questions request that asks about one site (the TUI shows it as a question card). */
639
+ export function siteQuestion(site, url, exec) {
640
+ return {
641
+ questions: [
642
+ {
643
+ id: 'site',
644
+ header: 'Browser',
645
+ question: `Open ${site}?`,
646
+ detail: `The agent wants to open ${url} in its browser. Picasso hasn't opened ${site} before. Allow it in this thread only, or on every thread from now on.`,
647
+ options: [
648
+ { label: SITE_ALLOW_ONCE, description: 'This thread only, until Picasso quits.' },
649
+ { label: siteAlwaysLabel(site), description: 'Every thread from now on (Settings › Browser in Picasso for Mac lists it too).' },
650
+ { label: SITE_DENY, description: 'The agent is told you said no.' },
651
+ ],
652
+ },
653
+ ],
654
+ ...(exec?.agent !== undefined ? { agent: exec.agent } : {}),
655
+ ...(exec?.signal !== undefined ? { signal: exec.signal } : {}),
656
+ };
657
+ }
658
+
659
+ /** `once` | `always` | `deny` from the engine's answer batch; anything but a pick (a skip, own words) is a deny. */
660
+ export function siteAnswer(answer, site) {
661
+ const answers = Array.isArray(answer?.answers) ? answer.answers : Array.isArray(answer) ? answer : [];
662
+ const pick = answers.find((item) => item?.id === 'site') ?? answers[0];
663
+ const label = Array.isArray(pick?.selected) ? pick.selected.find((value) => typeof value === 'string') : undefined;
664
+ if (label === SITE_ALLOW_ONCE) return 'once';
665
+ if (label === siteAlwaysLabel(site)) return 'always';
666
+ return 'deny';
667
+ }
668
+
669
+ export function deniedSiteMessage(site) {
670
+ return `The person didn't allow ${site}. Don't retry it unless they ask; they can allow it with \`picasso browser sites add ${site}\` (or in Picasso for Mac, Settings › Browser).`;
671
+ }
672
+
673
+ export function unaskedSiteMessage(site) {
674
+ return `${site} isn't an allowed site yet, and no one could be asked in this session. Allow it with \`picasso browser sites add ${site}\` (or in Picasso for Mac, Settings › Browser), then try again.`;
675
+ }
676
+
677
+ /** The path a file address names (`/…`, `~/…`, `file:` URLs, or a relative path that exists in the thread folder). */
678
+ export function fileTarget(input, cwd) {
679
+ if (typeof input !== 'string') return undefined;
680
+ const text = input.trim();
681
+ if (text.startsWith('~')) return join(homedir(), text.slice(1).replace(/^[\\/]/, ''));
682
+ if (text.startsWith('/')) return text;
683
+ if (/^file:/i.test(text)) {
684
+ try {
685
+ return fileURLToPath(new URL(text));
686
+ } catch {
687
+ return undefined;
688
+ }
689
+ }
690
+ if (typeof cwd === 'string' && cwd !== '' && !/^[a-z][a-z0-9+.-]*:/i.test(text) && !/^:?\d{1,5}$/.test(text) && /[\\/]|\.[a-z0-9]+$/i.test(text)) {
691
+ const candidate = resolve(cwd, text.split(/[?#]/)[0]);
692
+ if (existsSync(candidate)) return candidate;
693
+ }
694
+ return undefined;
695
+ }
696
+
697
+ /** Whether `path` (resolved through symlinks where it exists) is inside the folder `cwd`. */
698
+ export function insideFolder(path, cwd) {
699
+ if (typeof path !== 'string' || typeof cwd !== 'string' || cwd === '' || !isAbsolute(path)) return false;
700
+ const real = (value) => {
701
+ try {
702
+ return realpathSync(value);
703
+ } catch {
704
+ return resolve(value);
705
+ }
706
+ };
707
+ const rel = relative(real(cwd), real(path));
708
+ return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel) && !rel.startsWith(`..${sep}`));
709
+ }
710
+
711
+ /**
712
+ * The CLI host's site rules. `admit(exec, args, sessionId)` runs before an action is queued: files outside the thread
713
+ * folder are refused, a public site not yet allowed asks the person once (deduplicated per thread and site), and the
714
+ * returned `{cwd, sites}` rides the action so the executor can refuse every other load.
715
+ */
716
+ export class CliSites {
717
+ constructor(options = {}) {
718
+ this.sitesFile = options.sitesFile;
719
+ this.questions = options.questions ?? (() => undefined);
720
+ this.cwdOf = options.cwdOf ?? (() => undefined);
721
+ this.once = new Map();
722
+ this.asking = new Map();
723
+ }
724
+
725
+ allowed(sessionId) {
726
+ return [...new Set([...readAllowedSites(this.sitesFile), ...(this.once.get(sessionId) ?? [])])].sort();
727
+ }
728
+
729
+ isAllowed(site, sessionId) {
730
+ const key = String(site).toLowerCase();
731
+ return this.once.get(sessionId)?.has(key) === true || readAllowedSites(this.sitesFile).includes(key);
732
+ }
733
+
734
+ grantOnce(sessionId, site) {
735
+ let sites = this.once.get(sessionId);
736
+ if (sites === undefined) this.once.set(sessionId, (sites = new Set()));
737
+ sites.add(String(site).toLowerCase());
738
+ }
739
+
740
+ /** The URL a navigate-like call opens, else undefined (snapshot, click, …). */
741
+ static target(exec, args) {
742
+ if (exec.name === 'browser_navigate') return args.url;
743
+ if (exec.name === 'browser_tabs' && args.action === 'new' && typeof args.url === 'string' && args.url.trim() !== '') return args.url;
744
+ return undefined;
745
+ }
746
+
747
+ async admit(exec, args, sessionId) {
748
+ const cwd = this.cwdOf(exec);
749
+ const input = CliSites.target(exec, args);
750
+ if (input !== undefined) {
751
+ const file = fileTarget(input, cwd);
752
+ if (file !== undefined) {
753
+ if (!insideFolder(file, cwd)) throw new Error(FILE_OUTSIDE_REFUSAL);
754
+ } else {
755
+ const target = classifyUrl(input);
756
+ if (target.kind === 'remote' && !this.isAllowed(target.site, sessionId)) await this.ask(exec, sessionId, target.site, target.url.href);
757
+ }
758
+ }
759
+ return { ...(typeof cwd === 'string' && cwd !== '' ? { cwd } : {}), sites: this.allowed(sessionId) };
760
+ }
761
+
762
+ async ask(exec, sessionId, site, href) {
763
+ const key = `${sessionId}\u0000${site}`;
764
+ let pending = this.asking.get(key);
765
+ if (pending === undefined) {
766
+ pending = this.askOnce(exec, sessionId, site, href).finally(() => this.asking.delete(key));
767
+ this.asking.set(key, pending);
768
+ }
769
+ await pending;
770
+ }
771
+
772
+ async askOnce(exec, sessionId, site, href) {
773
+ const questions = this.questions();
774
+ if (questions === undefined || typeof questions.ask !== 'function') throw new Error(unaskedSiteMessage(site));
775
+ let answer;
776
+ try {
777
+ answer = await questions.ask(siteQuestion(site, href, exec));
778
+ } catch (error) {
779
+ if (exec.signal?.aborted) throw error;
780
+ throw new Error(unaskedSiteMessage(site));
781
+ }
782
+ const choice = siteAnswer(answer, site);
783
+ if (choice === 'deny') throw new Error(deniedSiteMessage(site));
784
+ if (choice === 'always') {
785
+ try {
786
+ addAllowedSite(this.sitesFile, site);
787
+ } catch {
788
+ // The list could not be written: the site is still allowed in this thread.
789
+ }
790
+ }
791
+ this.grantOnce(sessionId, site);
792
+ }
547
793
  }
548
794
 
549
795
  /** The tool definitions registered on ctx.tools. `adapter` is createMcpToolDefinition, or undefined for text-only. */
550
- export function buildTools(ctx, adapter, actions) {
796
+ export function buildTools(ctx, adapter, actions, cliHost) {
551
797
  return TOOL_SPECS.map((spec) => {
552
798
  if (adapter !== undefined) {
553
799
  return adapter(ctx, {
@@ -556,7 +802,7 @@ export function buildTools(ctx, adapter, actions) {
556
802
  description: spec.description,
557
803
  inputSchema: spec.parameters,
558
804
  async call(_args, exec) {
559
- const result = await runAction(actions, exec);
805
+ const result = await runAction(actions, exec, cliHost);
560
806
  return {
561
807
  content: [
562
808
  { type: 'text', text: result.text },
@@ -576,7 +822,7 @@ export function buildTools(ctx, adapter, actions) {
576
822
  },
577
823
  async execute(_args, exec) {
578
824
  if (spec.name === 'browser_screenshot') throw new Error('Screenshots need this dsh build\u2019s image support; other browser tools still work.');
579
- const result = await runAction(actions, exec);
825
+ const result = await runAction(actions, exec, cliHost);
580
826
  return { text: result.image ? `${result.text}\n(image omitted: no image projection available)` : result.text };
581
827
  },
582
828
  };
@@ -589,21 +835,72 @@ export async function dshModule(dshBin, specifier) {
589
835
  return import(pathToFileURL(require.resolve(specifier)).href);
590
836
  }
591
837
 
838
+ /**
839
+ * Where to resolve dsh's bundled packages from: the configured bin (the relay passes its realpath), else the running
840
+ * engine's own entry (the CLI launches dsh, so `process.argv[1]` is its bin) and install dir, else the Homebrew bin.
841
+ */
842
+ export function dshBinCandidates(config, argv = process.argv, env = process.env) {
843
+ const out = [];
844
+ if (typeof config?.dshBin === 'string' && config.dshBin) out.push(config.dshBin);
845
+ if (typeof argv?.[1] === 'string' && argv[1]) {
846
+ try {
847
+ out.push(realpathSync(argv[1]));
848
+ } catch {
849
+ out.push(argv[1]);
850
+ }
851
+ }
852
+ if (typeof env?.PICASSO_DSH_INSTALL_DIR === 'string' && env.PICASSO_DSH_INSTALL_DIR) out.push(join(env.PICASSO_DSH_INSTALL_DIR, 'package.json'));
853
+ out.push('/opt/homebrew/bin/dsh');
854
+ return [...new Set(out)];
855
+ }
856
+
857
+ /** The working directory of the calling agent's session, best effort. */
858
+ function cwdFor(ctx, exec) {
859
+ const session = exec?.agent?.session;
860
+ try {
861
+ const service = ctx.get?.('workingDirectory') ?? ctx.workingDirectory;
862
+ const cwd = service?.get?.(session);
863
+ if (typeof cwd === 'string' && cwd) return cwd;
864
+ } catch {
865
+ // fall through to the session's own cwd
866
+ }
867
+ return typeof session?.cwd === 'string' && session.cwd ? session.cwd : undefined;
868
+ }
869
+
592
870
  export async function apply(ctx, config) {
593
- const actions = new BrowserActions();
871
+ const host = config?.host === 'cli' ? 'cli' : 'mac';
872
+ const actions = new BrowserActions(host === 'cli' ? { closedMessage: CLI_HOST_GONE, timeoutMessage: CLI_ACTION_TIMEOUT } : {});
594
873
  const service = actions;
595
874
  service.typertRemote = Object.freeze({ service, serviceKey: SERVICE_KEY, namespace: SERVICE_KEY });
596
875
  ctx.provide(SERVICE_KEY, service);
597
876
  let adapter;
598
- try {
599
- const module = await dshModule(config?.dshBin ?? '/opt/homebrew/bin/dsh', '@deepseek-ai/dsh-mcp-client');
600
- adapter = module.createMcpToolDefinition;
601
- if (typeof adapter !== 'function') throw new Error('no export');
602
- } catch (error) {
603
- console.warn(`${name}: image projection unavailable (${error instanceof Error ? error.message : String(error)}); registering text-only browser tools`);
877
+ const failures = [];
878
+ for (const bin of host === 'cli' ? dshBinCandidates(config) : [config?.dshBin ?? '/opt/homebrew/bin/dsh']) {
879
+ try {
880
+ const module = await dshModule(bin, '@deepseek-ai/dsh-mcp-client');
881
+ if (typeof module.createMcpToolDefinition !== 'function') throw new Error('no export');
882
+ adapter = module.createMcpToolDefinition;
883
+ break;
884
+ } catch (error) {
885
+ failures.push(error instanceof Error ? error.message : String(error));
886
+ }
604
887
  }
605
- for (const tool of buildTools(ctx, adapter, actions)) ctx.tools.register(tool);
606
- ctx.on('tools/pre-execute', (exec, next) => preExecute(exec, next));
888
+ if (adapter === undefined) console.warn(`${name}: image projection unavailable (${failures.join('; ')}); registering text-only browser tools`);
889
+ const cliHost = host === 'cli'
890
+ ? new CliSites({
891
+ sitesFile: typeof config?.sitesFile === 'string' ? config.sitesFile : undefined,
892
+ questions: () => {
893
+ try {
894
+ return ctx.get?.('userQuestions') ?? ctx.userQuestions;
895
+ } catch {
896
+ return undefined;
897
+ }
898
+ },
899
+ cwdOf: (exec) => cwdFor(ctx, exec),
900
+ })
901
+ : undefined;
902
+ for (const tool of buildTools(ctx, adapter, actions, cliHost)) ctx.tools.register(tool);
903
+ ctx.on('tools/pre-execute', (exec, next) => preExecute(exec, next, host));
607
904
  }
608
905
 
609
906
  Object.defineProperty(BrowserActions.prototype, REMOTE_METHOD_DESCRIPTOR, {
@@ -2,7 +2,7 @@
2
2
  "name": "@picasso/browser",
3
3
  "version": "0.1.0",
4
4
  "private": true,
5
- "description": "dsh cordis plugin: browser_* model tools executed by the Picasso Mac app on the thread's Preview pane (localhost, thread files and public sites the person allows), over the picassoBrowser/* Host Remote service the helper relay long-polls.",
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
6
  "type": "module",
7
7
  "main": "index.js",
8
8
  "exports": {
@@ -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',
@@ -102,6 +102,7 @@ const RULES = [
102
102
  '- Do NOT mention this summarization request or that the context was compacted.',
103
103
  '- Output only the checkpoint text: do not call any tool or take any other action.',
104
104
  '- A <compacted-summary> block in the material is an earlier checkpoint: keep its still-true facts, drop stale ones, and merge newer information into one consolidated summary.',
105
+ '- A <session-state> block is the session\'s live plan, goal and newest progress report: list every plan item with its exact status under Pending Jobs, and keep the goal and the progress percent in Critical Context.',
105
106
  ].join('\n');
106
107
 
107
108
  /** The instruction after the replayed history (single call: the engine's request shape). */
@@ -594,6 +595,119 @@ export function createSummarizer({ llm, stock, engineConfig = () => undefined, l
594
595
  };
595
596
  }
596
597
 
598
+ // ── Session state in the summary input ──────────────────────────────────────────────────────────────────────────
599
+ //
600
+ // Owner 2026-11-18 (session m0-d03430f0): neither compaction summary of a session with a 10-item plan named one item,
601
+ // so the model after `/compact` (and the models switched in after it) did not know a plan existed. The summarizer now
602
+ // gets the session's live state as one last user message after the history it condenses: the plan as last written
603
+ // with `todo_write` (every item and status), the active goal (and its contract file) and the newest progress report
604
+ // line, each folded from the session's durable log. It is appended after the replayed history, so the summary call
605
+ // keeps the conversation's cached prefix; it never reaches the conversation itself (only the summary does), and Tier 1
606
+ // is untouched. Lean-context re-states the plan after the compaction too (`plan-state`); this keeps it in the summary.
607
+
608
+ export const SESSION_STATE_SOURCE_KIND = 'picasso-session-state';
609
+ const SESSION_STATE_MAX_ITEMS = 60;
610
+ const SESSION_STATE_ITEM_MAX_CHARS = 400;
611
+ const SESSION_STATE_OBJECTIVE_MAX_CHARS = 2_000;
612
+ const TODO_DONE = new Set(['completed', 'cancelled', 'canceled', 'done', 'skipped']);
613
+ const PROGRESS_LINE_RE = /progress(?: report)?\b[^\n]*?\b\d{1,3}(?:\.\d+)?\s?%/iu;
614
+
615
+ const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
616
+ const oneLine = (value, max) => {
617
+ const flat = String(value ?? '').replace(/\s+/gu, ' ').trim();
618
+ return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
619
+ };
620
+
621
+ /** The session's plan, active goal (with its contract) and newest progress line, folded from its durable log. */
622
+ export function sessionStateOf(session) {
623
+ const state = { todos: [], goal: undefined, contracts: [], report: undefined };
624
+ if (typeof session?.eventAt !== 'function' || !Number.isSafeInteger(session?.seq)) return state;
625
+ for (let seq = 0; seq < session.seq; seq += 1) {
626
+ let event;
627
+ try {
628
+ event = session.eventAt(seq);
629
+ } catch {
630
+ event = undefined;
631
+ }
632
+ if (!isObject(event)) continue;
633
+ const data = isObject(event.data) ? event.data : {};
634
+ switch (event.type) {
635
+ case 'todo/write':
636
+ state.todos = (Array.isArray(data.todos) ? data.todos : []).filter(isObject).map((todo) => ({
637
+ content: typeof todo.content === 'string' ? todo.content : '',
638
+ status: typeof todo.status === 'string' ? todo.status : 'pending',
639
+ }));
640
+ break;
641
+ case 'goal/change':
642
+ if (data.operation === 'clear') state.goal = undefined;
643
+ else if (isObject(data.goal) && typeof data.goal.objective === 'string') {
644
+ state.goal = { id: data.goal.id, objective: data.goal.objective, phase: data.goal.phase };
645
+ }
646
+ break;
647
+ case 'plugin:picasso/goal-contract': {
648
+ const approval = isObject(data.event) ? data.event : undefined;
649
+ if (approval && typeof approval.objective === 'string' && typeof approval.contractPath === 'string') state.contracts.push(approval);
650
+ break;
651
+ }
652
+ case 'assistant/message': {
653
+ const blocks = Array.isArray(data.message?.content) ? data.message.content : [];
654
+ const textOf = blocks.map((block) => (block?.type === 'text' && typeof block.text === 'string' ? block.text : '')).join('\n');
655
+ const first = textOf.split('\n').find((line) => line.trim().length > 0);
656
+ if (first !== undefined && PROGRESS_LINE_RE.test(first)) state.report = first;
657
+ break;
658
+ }
659
+ default:
660
+ break;
661
+ }
662
+ }
663
+ return state;
664
+ }
665
+
666
+ /** The `<session-state>` text for the summarizer, or undefined when the session has no plan, goal or report. */
667
+ export function renderSessionState(state) {
668
+ const lines = [];
669
+ const goal = isObject(state?.goal) && state.goal.phase !== 'complete' && state.goal.phase !== 'completed' ? state.goal : undefined;
670
+ if (goal !== undefined) {
671
+ lines.push(`Goal (${typeof goal.phase === 'string' ? goal.phase : 'set'}): ${oneLine(goal.objective, SESSION_STATE_OBJECTIVE_MAX_CHARS)}`);
672
+ const contracts = Array.isArray(state.contracts) ? state.contracts : [];
673
+ const contract = [...contracts].reverse().find((entry) => entry.goalId === goal.id || (entry.goalId === undefined && entry.objective === goal.objective));
674
+ if (contract !== undefined) lines.push(`Goal contract: ${contract.contractPath}`);
675
+ }
676
+ const todos = Array.isArray(state?.todos) ? state.todos : [];
677
+ if (todos.length > 0) {
678
+ const done = todos.filter((todo) => TODO_DONE.has(todo.status)).length;
679
+ lines.push(`Plan (last todo_write), ${done} of ${todos.length} done:`);
680
+ for (const todo of todos.slice(0, SESSION_STATE_MAX_ITEMS)) lines.push(`- [${oneLine(todo.status, 24)}] ${oneLine(todo.content, SESSION_STATE_ITEM_MAX_CHARS)}`);
681
+ if (todos.length > SESSION_STATE_MAX_ITEMS) lines.push(`- … ${todos.length - SESSION_STATE_MAX_ITEMS} more`);
682
+ }
683
+ if (typeof state?.report === 'string') lines.push(`Newest progress report: ${oneLine(state.report, SESSION_STATE_ITEM_MAX_CHARS)}`);
684
+ if (lines.length === 0) return undefined;
685
+ return [
686
+ '<session-state>',
687
+ 'The live state of this session as Picasso records it (not part of the conversation). Keep all of it in the checkpoint: every plan item with its exact status, the goal, the progress.',
688
+ ...lines,
689
+ '</session-state>',
690
+ ].join('\n');
691
+ }
692
+
693
+ /** `input` with the session's state appended as a last user message (unchanged when there is none). */
694
+ export function withSessionState(input, agent) {
695
+ let text;
696
+ try {
697
+ text = renderSessionState(sessionStateOf(agent?.session));
698
+ } catch {
699
+ text = undefined;
700
+ }
701
+ if (text === undefined || !isObject(input) || !Array.isArray(input.messages)) return input;
702
+ const message = {
703
+ id: `${SESSION_STATE_SOURCE_KIND}-${Number.isSafeInteger(agent?.session?.seq) ? agent.session.seq : 0}`,
704
+ role: 'user',
705
+ content: [{ type: 'text', text }],
706
+ source: { kind: SESSION_STATE_SOURCE_KIND, form: 'reminder' },
707
+ };
708
+ return { ...input, messages: [...input.messages, message] };
709
+ }
710
+
597
711
  /** The service object behind cordis's tracing proxy (its own `summarize` must be set on the real instance). */
598
712
  function rawService(service) {
599
713
  if (service === undefined || service === null) return undefined;
@@ -751,7 +865,8 @@ export function installSummarizer(compaction, llm, log = () => undefined, deps =
751
865
  const notice = createNoticeWriter({ engine, llm, log, appendRecord: deps.appendRecord });
752
866
  const override = async function summarize(input, agent, signal) {
753
867
  await notice(agent, reasons.get(agent));
754
- return summarizer.summarize(input, agent, signal);
868
+ // The plan, goal and newest progress line ride along so the summary keeps them (`withSessionState`).
869
+ return summarizer.summarize(withSessionState(input, agent), agent, signal);
755
870
  };
756
871
  const installed = { summarize: override };
757
872
  // Shortening starts near the window, not at 80% of it (PRESSURE_RATIO). The engine reads its config at every check.