acrylblends 1.0.5 → 1.0.6

package/docs/framework/agents/index.md

@@ -50,7 +50,7 @@ npm install
 - `add driver-pty` puts the driver's row after the panel's in `blend.yaml` and registers it in `src/app.ts`.
 - A **run belongs to the app, not to the page**: when the page reloads (the door reloads it after a plugin change) the panel shows the question and the events so far and follows the run to its end; **Stop** is the only thing that cancels it.
 - **The panel's coding agents are yours.** `claude`, `codex` and `pi` run on the machine that runs the app, in the app folder, with the login of the person who started it: `claude` and `codex` use their own signed-in sessions, and `pi` is offered when `DEEPSEEK_API_KEY` is set or `pi` has stored a DeepSeek login (`~/.pi/agent/auth.json`, read from the `HOME` of the process that runs the app: an app started under another `HOME` does not see the login, and the panel then lists `pty:pi` but no chat `pi`). A program that is not installed, or is not logged in, is not offered; nothing is shared between machines, and a workshop laptop needs its own login. The panel's own `agent` (the offline scripted one) needs none.
-- `pi` has to be an executable on the `PATH`; a shell function that wraps the binary is fine as long as the binary itself is found by `which pi`.
+- `pi` has to be an executable on the `PATH`; a shell function that wraps the binary is fine as long as the binary itself is found by `which pi`. Install it with `npm i -g @earendil-works/pi-coding-agent` (the older `@mariozechner/pi-coding-agent` is deprecated). It reaches DeepSeek with `DEEPSEEK_API_KEY` in the environment of the app, or with the key it stored when its owner logged in (`~/.pi/agent/auth.json`, a `deepseek` entry); without one the panel does not offer it. On Windows an npm-installed `claude`, `codex` or `pi` is a `.cmd` shim: the panel reads the script the shim runs and starts it with Node (no shell, so the message is not passed through cmd.exe quoting), and Stop ends the whole process tree.
 - `driver-pty` brings `node-pty`, which ships prebuilt binaries for macOS, Windows and Linux. npm 11 and pnpm warn that its install script was not run (they ask you to approve dependency install scripts); you can ignore the warning. If no `pty:` terminal is offered and the app prints why at start, approve and rebuild: `npm approve-scripts node-pty`, then `npm rebuild node-pty` (pnpm: `pnpm approve-builds`).
 
 ## Checking that an agent can use the docs

package/lib/{audit-D5z9uwOP.d.ts → audit-GcLtvNLV.d.ts}

@@ -1,4 +1,4 @@
-import { _ as UiRequest, n as AuditEntry, r as ChannelToHost, v as UiResult } from "./protocol-C37gPePD.js";
+import { _ as UiRequest, n as AuditEntry, r as ChannelToHost, v as UiResult } from "./protocol-CR31M7K_.js";
 
 //#region ../../plugins/acryl-door/src/host/channel.d.ts
 /** The slice of a page's stream the channel needs, so tests can supply their own. */
@@ -18,7 +18,7 @@ declare class UiChannel {
    * Register a page's stream. A stream already open for the same window is closed first, and its calls settle as `disconnected`.
    * @returns the function to call when this stream ends.
    */
-  attach(windowId: string, focused: boolean, stream: PageStream): () => void;
+  attach(windowId: string, focused: boolean, stream: PageStream, shellWindow?: number): () => void;
   /** A message a page sent by POST. Only the window that was asked may answer a call, so another page cannot forge a result. */
   receive(windowId: string, message: ChannelToHost): void;
   /** True when at least one page is connected. */
@@ -27,6 +27,7 @@ declare class UiChannel {
   windows(): readonly {
     windowId: string;
     focused: boolean;
+    shellWindow?: number;
   }[];
   /**
    * Ask the current page to do something.
@@ -35,6 +36,7 @@ declare class UiChannel {
   call(request: UiRequest, options?: {
     signal?: AbortSignal;
     timeoutMs?: number;
+    window?: number;
   }): Promise<UiResult>;
   /**
    * A promise for the next time a page connects (a page that reloaded or moved opens a new stream). Ask for it BEFORE the call that makes the page leave, or a fast page is missed.

package/lib/cordis/door.d.ts

@@ -1,10 +1,87 @@
-import { f as UiActionResult, y as UiSnapshot } from "../protocol-C37gPePD.js";
-import { i as UiChannel, t as AuditLog } from "../audit-D5z9uwOP.js";
+import { f as UiActionResult, y as UiSnapshot } from "../protocol-CR31M7K_.js";
+import { i as UiChannel, r as PageStream, t as AuditLog } from "../audit-GcLtvNLV.js";
 import { Context } from "@deepseek-ai/cordis";
 import z from "@deepseek-ai/schemastery";
 
+//#region ../../plugins/acryl-door/src/shell/protocol.d.ts
+type ShellRequest = {
+  readonly op: 'window-list';
+} | {
+  readonly op: 'window-open';
+  readonly path?: string;
+} | {
+  readonly op: 'window-focus';
+  readonly id: number;
+} /** `force`: the window may be the last, and closing the last one ends the desktop app (and with it the server it started). */ | {
+  readonly op: 'window-close';
+  readonly id: number;
+  readonly force?: boolean;
+} | {
+  readonly op: 'window-resize';
+  readonly id: number;
+  readonly width: number;
+  readonly height: number;
+} | {
+  readonly op: 'menu-list';
+} /** `force`: the item may end the desktop app (Quit, or Close Window on the last window). */ | {
+  readonly op: 'menu-click';
+  readonly path: string;
+  readonly force?: boolean;
+};
+interface ShellWindow {
+  /** Electron's own window id: the number `window list` prints and `--window` takes. */
+  readonly id: number;
+  readonly title: string;
+  /** The path (with query) the window shows, never the origin. */
+  readonly path: string;
+  readonly focused: boolean;
+  readonly width: number;
+  readonly height: number;
+}
+interface ShellMenuItem {
+  /** Labels from the top of the menu, joined with `>`: `File>New Note`. */
+  readonly path: string;
+  readonly label: string;
+  readonly enabled: boolean;
+  /** True for an item that ends the desktop app (Quit, or Close Window): `menu click` presses it only with `force`. */
+  readonly ends?: boolean;
+}
+type ShellResult = {
+  readonly windows: readonly ShellWindow[];
+} | {
+  readonly items: readonly ShellMenuItem[];
+} | {
+  readonly ok: true;
+  readonly detail: string;
+  readonly id?: number;
+};
+type ShellErrorCode = 'invalid' | 'no-desktop' | 'no-such-window' | 'last-window' | 'no-such-menu-item' | 'disabled' | 'quits-app' | 'timeout' | 'disconnected' | 'unloaded' | 'aborted' | 'failed';
+//#endregion
+//#region ../../plugins/acryl-door/src/host/shell.d.ts
+declare class ShellChannel {
+  private current;
+  private readonly pending;
+  private nextId;
+  private closed;
+  private readonly attachWaiters;
+  get connected(): boolean;
+  /** @returns the function to call when this stream ends. */
+  attach(stream: PageStream): () => void;
+  /** A promise for the shell connecting (it reconnects after the dev server restarted). */
+  waitForShell(timeoutMs: number): Promise<boolean>;
+  receive(body: unknown): void;
+  /** @throws ShellError `no-desktop` when no shell is attached, else what the shell refused with. */
+  call(request: ShellRequest, options?: {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+  }): Promise<ShellResult>;
+  close(): void;
+  private failAll;
+  private settle;
+}
+//#endregion
 //#region ../../plugins/acryl-door/src/host/door.d.ts
-type DoorErrorCode = 'invalid' | 'unknown-verb' | 'unavailable' | 'not-exposed' | 'outside-app' | 'failed';
+type DoorErrorCode = 'invalid' | 'unknown-verb' | 'unavailable' | 'not-exposed' | 'outside-app' | 'failed' | ShellErrorCode;
 declare class DoorError extends Error {
   readonly code: DoorErrorCode;
   constructor(code: DoorErrorCode, message: string);
@@ -32,6 +109,8 @@ interface ToolsPort {
 }
 interface DoorDeps {
   readonly channel: UiChannel;
+  /** The desktop shell (the Electron main process of `npm run desktop`), when the app can have one. */
+  readonly shell?: ShellChannel;
   readonly audit: AuditLog;
   /** The app's name, folder and, when it listens, its address (what `brief` prints so an agent can curl the running app). */
   readonly app: {
@@ -67,6 +146,13 @@ declare class Door {
    * A second GET of the same path (a page is read-only); nothing when the app has no address or does not answer in time.
    */
   private statusAt;
+  /**
+   * The windows and the menu of the desktop app, through the shell. Every call is audited with the window it was about; a call with no shell attached answers one line that says what to run;
+   * closing the last window is refused unless the call says `force` (it ends the desktop app, and the session an agent works in with it).
+   */
+  private desktop;
+  /** `window` on look and act: the desktop window (the number `window list` prints) whose page the call is for; without it, the page used last. */
+  private windowOf;
   private parse;
   /** Run one call on the page and record it. The audit holds which control was touched and how it ended, never what was typed. */
   private callPage;
@@ -83,7 +169,7 @@ declare class Door {
  * MCP (`tools/list`) and the built-in chat (the `tools` registry). A verb added here is in all three, or the comparison test fails.
  */
 /** Every verb, in the order `brief` lists them. */
-declare const VERBS: readonly ["brief", "look", "act", "plugin-list", "plugin-add", "plugin-remove", "plugin-reload", "tool-list", "tool-call"];
+declare const VERBS: readonly ["brief", "look", "act", "plugin-list", "plugin-add", "plugin-remove", "plugin-reload", "tool-list", "tool-call", "window-list", "window-open", "window-focus", "window-close", "window-resize", "menu-list", "menu-click"];
 type Verb = (typeof VERBS)[number];
 /** The JSON Schema of a verb's arguments, as MCP lists it. */
 interface ArgumentsSchema {