craftdriver 1.7.0 → 1.9.0

package/CHANGELOG.md

@@ -1,3 +1,27 @@
+# [1.9.0](https://github.com/dtopuzov/craftdriver/compare/v1.8.0...v1.9.0) (2026-07-24)
+
+
+### Features
+
+* add open Shadow DOM support ([#49](https://github.com/dtopuzov/craftdriver/issues/49)) ([fadd962](https://github.com/dtopuzov/craftdriver/commit/fadd962c6d1a583501d9efb7c8117d42ce3710a6)), closes [#40](https://github.com/dtopuzov/craftdriver/issues/40)
+
+# [1.8.0](https://github.com/dtopuzov/craftdriver/compare/v1.7.0...v1.8.0) (2026-07-21)
+
+
+### Features
+
+* **agent CLI:** add a persistent browser exploration workflow with semantic snapshots, safe temporary refs, live-validated durable locators, manual QA actions, console/network evidence, mocks, traces, and reusable login state ([2a0f079](https://github.com/dtopuzov/craftdriver/commit/2a0f079b327ffd1545fa0f1919e06045e89422dc))
+* **auth state:** restore cookies and multi-origin localStorage before the first navigation on BiDi launch and contexts, with path/object inputs and one-time hydration that preserves later application writes
+* **sessions:** isolate browsers, cookies, pages, refs, and artifacts in named sessions under a project-scoped daemon
+* **MCP:** add a validated stdio tool server with automatic post-action snapshot diffs, bounded responses, and quota-controlled file artifacts for token-efficient context
+* **skill:** add a safe project-local CraftDriver skill installer that teaches coding agents to explore first and turn runtime evidence into maintainable tests
+
+### Bug Fixes
+
+* **agent reliability:** fail closed on malformed CLI input, recover failed browser launches, reset browser-owned state on quit, and bound large results, errors, screenshots, and artifact storage
+* **auth state:** validate every restore before mutation, quarantine internal hydration pages from public APIs and telemetry, serialize per-context overlays, reject partial Classic launch restores, and make direct state saves atomic and owner-restricted
+* **pages:** preserve the active page when closing background tabs and cover page activation/closing in BiDi-enabled non-default contexts
+
 # [1.7.0](https://github.com/dtopuzov/craftdriver/compare/v1.6.0...v1.7.0) (2026-07-18)
 
 
@@ -38,17 +62,6 @@
 
 * make traces Playwright and Vibium compatible ([c6c0746](https://github.com/dtopuzov/craftdriver/commit/c6c0746dcecc671d1d6d6cd26badf6a8432a7f37))
 
-## Unreleased
-
-### Bug Fixes
-
-* **wait:** evaluate wait conditions once even when the timeout is zero
-
-### Features
-
-* **tracing:** export Vibium Player compatible zips from the library and MCP server
-* **visual:** add `browser.expectScreenshot()` — a retrying screenshot assertion against a committed PNG baseline, with per-channel RGB tolerance, max different-pixel count/percentage, optional anti-alias ignoring, and a typed `VisualMismatchError` carrying the final actual + diff PNG buffers (also exposes the low-level `compareScreenshots()` buffer comparator). Baselines are managed for you: a missing baseline is captured until it settles (or the timeout elapses), written, and passes (`result.baseline === 'created'`); an intentional change is accepted by re-running with `CRAFTDRIVER_UPDATE_VISUAL_BASELINES=true`, which overwrites a differing baseline instead of failing (`'updated'`). Writes are atomic and a present-but-corrupt baseline is never overwritten; behaviour is identical locally and in CI, with every create/update reported to stderr. New runtime dependency: pinned `pngjs@7.0.0` (pure JS, no native addon/WASM/transitive runtime deps)
-
 # [1.2.0](https://github.com/dtopuzov/craftdriver/compare/v1.1.1...v1.2.0) (2026-07-10)
 
 
@@ -208,7 +221,7 @@ Fixes: https://github.com/dtopuzov/craftdriver/issues/20
 
 # [0.1.0](https://github.com/dtopuzov/craftdriver/compare/v0.0.3...v0.1.0) (2026-02-08)
 
-## Unreleased
+### Changes
 
 - docs: refresh the README as a product front door, add a VitePress documentation site with GitHub Pages deployment, add proof pages/launch kit/social card, and add contribution files (issue forms, PR template, code of conduct).
 - **breaking** (pre-1.0): BiDi console/error log capture is lazy by default. Messages emitted before the first `browser.logs` / `onConsole` / `onError` / `waitForConsole` touch are no longer captured unless `Browser.launch({ captureLogs: true })` is used to arm logging at launch.

package/README.md

@@ -27,7 +27,7 @@ CraftDriver is for writing boringly reliable automation against real browsers, w
 - 🧾 **Trace evidence** - capture actions, console output, errors, network events, and screenshots.
 - ☁️ **Remote WebDriver** - use the Browser API with a self-hosted Selenium Grid or a cloud provider like [BrowserStack](https://www.browserstack.com/).
 - ⚛️ **Electron apps** - drive packaged Electron desktop apps and mock native OS dialogs (open/save, message boxes).
-- 🤖 **Agent-friendly** - CLI, MCP, and assistant rules when coding agents need the browser.
+- 🤖 **Agent-friendly** - CLI, a project-local skill, and optional MCP when coding agents need the browser.
 
 ## Choose Your Path
 
@@ -60,13 +60,17 @@ No separate chromedriver or geckodriver setup for normal use. CraftDriver resolv
 
 ## AI Agent Bonus
 
-If your coding agent can use a shell or MCP, CraftDriver can give it a real browser too. Same selectors, same behavior, same error codes as the library API.
+If your coding agent can use a shell, CraftDriver can give it a real browser
+for exploring the app before it writes tests. Install the project-local skill;
+it never changes repository instruction files.
 
 ```bash
-npx craftdriver init agents
-claude mcp add craftdriver -- npx -y craftdriver mcp
+npx craftdriver init codex
 ```
 
+MCP is optional. `npx craftdriver init codex --mcp` prints a project-pinned
+manual configuration snippet without reading or changing Codex config.
+
 See the [AI agent guide](https://dtopuzov.github.io/craftdriver/agents) when you need the full setup.
 
 ## What It Can Do
@@ -85,17 +89,22 @@ await browser.network.mock('**/api/users', {
 });
 
 // Save and reuse login state
-await browser.saveState('./session.json');
+await browser.saveState('.auth/session.json');
 
 await Browser.launch({
   browserName: 'chrome',
-  storageState: './session.json',
+  storageState: '.auth/session.json',
 });
 
 // Built-in accessibility checks via axe-core
 await browser.a11y.check();
 ```
 
+Launch-time state restores cookies plus multi-origin localStorage on supported
+WebDriver BiDi sessions (Chrome/Chromium and Firefox). WebDriver Classic has an
+explicit single-active-origin fallback after navigation; see
+[Session management](https://dtopuzov.github.io/craftdriver/session-management#browser-and-transport-support).
+
 ## Feature Guide
 
 | Area                 | What you get                                                                       | Learn more                                                                                                                                 |
@@ -104,6 +113,7 @@ await browser.a11y.check();
 | Driver management    | Zero-config driver resolution, cache behavior, env vars, offline mode              | [Driver configuration](https://dtopuzov.github.io/craftdriver/driver-configuration)                                                        |
 | Browser control      | Navigation, tabs, popups, iframes, content helpers, evaluate, init scripts         | [Browser API](https://dtopuzov.github.io/craftdriver/browser-api)                                                                          |
 | Locators             | CSS, XPath, text, role, label, test id, and composable `locator()` chains          | [Selectors](https://dtopuzov.github.io/craftdriver/selectors)                                                                              |
+| Open Shadow DOM      | Explicit lazy `shadowRoot()` boundaries over WebDriver Classic and BiDi            | [Shadow DOM](https://dtopuzov.github.io/craftdriver/selectors#open-shadow-dom)                                                             |
 | Element actions      | Click, fill, upload, inspect, and interact through element handles                 | [Element API](https://dtopuzov.github.io/craftdriver/element-api)                                                                          |
 | Assertions           | Built-in `expect(...)`, retries, visibility, text, attributes, and timing behavior | [Assertions](https://dtopuzov.github.io/craftdriver/assertions)                                                                            |
 | Input                | Low-level key presses, mouse movement, hover, drag, and pointer input              | [Keyboard and mouse](https://dtopuzov.github.io/craftdriver/keyboard-mouse)                                                                |

package/dist/cli/agentSession.d.ts

@@ -0,0 +1,62 @@
+import { Browser, type LaunchOptions } from '../lib/browser.js';
+import { type BrowserHandle, type DispatchContext } from './dispatcher.js';
+import { type SnapshotShape } from './snapshot.js';
+export interface AgentCommand {
+    cmd: string;
+    args?: Record<string, unknown>;
+}
+export type AgentResult = unknown;
+/**
+ * A command's result plus the one post-action snapshot it earned.
+ *
+ * Transports that show the agent what changed (MCP, the CLI's pretty
+ * mode) read `delta`; everything else uses {@link AgentSession.run} and
+ * ignores it.
+ */
+export interface AgentDetailedResult {
+    value: AgentResult;
+    /** Rendered diff (or full snapshot on a document change). */
+    delta?: string;
+    snapshot?: SnapshotShape | null;
+}
+export type AgentDispatcher = (ctx: DispatchContext, cmd: string, args?: Record<string, unknown>) => Promise<AgentResult>;
+export interface AgentSessionRunner {
+    run(command: AgentCommand): Promise<AgentResult>;
+    runDetailed(command: AgentCommand): Promise<AgentDetailedResult>;
+    close(): Promise<void>;
+}
+interface AgentSessionOptions {
+    launchOptions: LaunchOptions;
+    /** Safe name for session-owned artifacts such as the implicit screenshot. */
+    artifactName?: string;
+    launch?: () => Promise<Browser>;
+    dispatcher?: AgentDispatcher;
+    /** Internal lifecycle seam used by transport/session tests. */
+    handle?: BrowserHandle;
+    /** Set false to suppress automatic post-action snapshots. */
+    autoSnapshot?: boolean;
+}
+/** A lazy browser session whose accepted commands execute in FIFO order. */
+export declare class AgentSession implements AgentSessionRunner {
+    private readonly ctx;
+    private readonly journal;
+    private readonly dispatcher;
+    private readonly autoSnapshot;
+    private tail;
+    private state;
+    private closePromise;
+    constructor(options: AgentSessionOptions);
+    run(command: AgentCommand): Promise<AgentResult>;
+    /**
+     * Execute a command and, for a successful mutation, capture the one
+     * post-action snapshot in the *same* queue slot.
+     *
+     * Action and snapshot are deliberately one operation: if they were two,
+     * a concurrent command could land between them and the agent would be
+     * shown a diff attributed to the wrong action.
+     */
+    runDetailed(command: AgentCommand): Promise<AgentDetailedResult>;
+    close(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=agentSession.d.ts.map

package/dist/cli/agentSession.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentSession.d.ts","sourceRoot":"","sources":["../../src/cli/agentSession.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEhE,OAAO,EAKL,KAAK,aAAa,EAClB,KAAK,eAAe,EACrB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAA6C,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AAG9F,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,MAAM,WAAW,GAAG,OAAO,CAAC;AAElC;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,WAAW,CAAC;IACnB,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;CACjC;AAED,MAAM,MAAM,eAAe,GAAG,CAC5B,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC3B,OAAO,CAAC,WAAW,CAAC,CAAC;AAE1B,MAAM,WAAW,kBAAkB;IACjC,GAAG,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IACjD,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACjE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,UAAU,mBAAmB;IAC3B,aAAa,EAAE,aAAa,CAAC;IAC7B,6EAA6E;IAC7E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAChC,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B,+DAA+D;IAC/D,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,6DAA6D;IAC7D,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,4EAA4E;AAC5E,qBAAa,YAAa,YAAW,kBAAkB;IACrD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAkB;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;IACzC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAkB;IAC7C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAU;IACvC,OAAO,CAAC,IAAI,CAAoC;IAChD,OAAO,CAAC,KAAK,CAAyC;IACtD,OAAO,CAAC,YAAY,CAA8B;gBAEtC,OAAO,EAAE,mBAAmB;IAwBxC,GAAG,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IAIhD;;;;;;;OAOG;IACH,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAyChE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAoBvB"}

package/dist/cli/agentSession.js

@@ -0,0 +1,100 @@
+import { Browser } from '../lib/browser.js';
+import { CraftdriverError, ErrorCode } from '../lib/errors.js';
+import { createBrowserHandle, dispatch, isMutating, resetBrowserOwnedState, } from './dispatcher.js';
+import { takeSnapshot, peekDialog, SnapshotTracker } from './snapshot.js';
+import { SessionJournal } from './journal.js';
+/** A lazy browser session whose accepted commands execute in FIFO order. */
+export class AgentSession {
+    ctx;
+    journal;
+    dispatcher;
+    autoSnapshot;
+    tail = Promise.resolve();
+    state = 'open';
+    closePromise = null;
+    constructor(options) {
+        const baseLaunch = options.launch ?? (() => Browser.launch(options.launchOptions));
+        const journal = new SessionJournal();
+        // Attach inside the launch step, not after the first command: the handle
+        // must never hand out a browser whose console and network events are
+        // already going unrecorded. Events during the first navigation are the
+        // ones an agent most often asks about.
+        const launch = async () => {
+            const browser = await baseLaunch();
+            journal.attach(browser);
+            return browser;
+        };
+        this.journal = journal;
+        this.ctx = {
+            handle: options.handle ?? createBrowserHandle(launch),
+            launchOptions: options.launchOptions,
+            artifactName: options.artifactName,
+            tracker: new SnapshotTracker(),
+            journal,
+        };
+        this.dispatcher = options.dispatcher ?? dispatch;
+        this.autoSnapshot = options.autoSnapshot !== false;
+    }
+    run(command) {
+        return this.runDetailed(command).then((detailed) => detailed.value);
+    }
+    /**
+     * Execute a command and, for a successful mutation, capture the one
+     * post-action snapshot in the *same* queue slot.
+     *
+     * Action and snapshot are deliberately one operation: if they were two,
+     * a concurrent command could land between them and the agent would be
+     * shown a diff attributed to the wrong action.
+     */
+    runDetailed(command) {
+        if (this.state !== 'open') {
+            return Promise.reject(new CraftdriverError(ErrorCode.STATE_INVALID, 'AgentSession is closing or closed; it cannot accept new commands'));
+        }
+        const result = this.tail.then(async () => {
+            const value = await this.dispatcher(this.ctx, command.cmd, command.args ?? {});
+            if (!this.autoSnapshot || !isMutating(command.cmd))
+                return { value };
+            // Only if a browser is actually up: a fake dispatcher (or a command
+            // that never needed a browser) must not cause a launch here.
+            const browser = this.ctx.handle.peek();
+            if (!browser)
+                return { value };
+            // A modal dialog blocks script execution, so snapshotting behind one
+            // stalls for the full WebDriver script timeout (measured: 60s) and
+            // then fails anyway. Probing costs ~2ms and tells the agent the one
+            // thing it actually needs to know here.
+            const dialog = await peekDialog(browser);
+            if (dialog !== null) {
+                return {
+                    value,
+                    delta: `dialog open: ${dialog}\n(snapshot skipped — accept or dismiss it first)`,
+                };
+            }
+            const snap = await takeSnapshot(browser, this.ctx.tracker.minRef);
+            // A failed command threw above, so the baseline only ever advances
+            // on success.
+            const delta = this.ctx.tracker.advance(snap);
+            return { value, ...(delta ? { delta } : {}), snapshot: snap };
+        });
+        this.tail = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    close() {
+        if (this.closePromise)
+            return this.closePromise;
+        this.state = 'closing';
+        this.closePromise = this.tail.then(() => this.ctx.handle.close()).then(() => {
+            this.state = 'closed';
+            // Same teardown `quit` performs: releases journal listeners and any
+            // caller blocked in a wait, which would otherwise sit out its full
+            // timeout against a dead browser, and drops trace and mock metadata
+            // that described the browser just closed.
+            resetBrowserOwnedState(this.ctx);
+        }, (error) => {
+            this.closePromise = null;
+            throw error;
+        });
+        return this.closePromise;
+    }
+}
+//# sourceMappingURL=agentSession.js.map

package/dist/cli/agentSession.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentSession.js","sourceRoot":"","sources":["../../src/cli/agentSession.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAsB,MAAM,mBAAmB,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,EACL,mBAAmB,EACnB,QAAQ,EACR,UAAU,EACV,sBAAsB,GAGvB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,eAAe,EAAsB,MAAM,eAAe,CAAC;AAC9F,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AA+C9C,4EAA4E;AAC5E,MAAM,OAAO,YAAY;IACN,GAAG,CAAkB;IACrB,OAAO,CAAiB;IACxB,UAAU,CAAkB;IAC5B,YAAY,CAAU;IAC/B,IAAI,GAAkB,OAAO,CAAC,OAAO,EAAE,CAAC;IACxC,KAAK,GAAkC,MAAM,CAAC;IAC9C,YAAY,GAAyB,IAAI,CAAC;IAElD,YAAY,OAA4B;QACtC,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC;QACnF,MAAM,OAAO,GAAG,IAAI,cAAc,EAAE,CAAC;QACrC,yEAAyE;QACzE,qEAAqE;QACrE,uEAAuE;QACvE,uCAAuC;QACvC,MAAM,MAAM,GAAG,KAAK,IAAsB,EAAE;YAC1C,MAAM,OAAO,GAAG,MAAM,UAAU,EAAE,CAAC;YACnC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YACxB,OAAO,OAAO,CAAC;QACjB,CAAC,CAAC;QACF,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,GAAG,GAAG;YACT,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,mBAAmB,CAAC,MAAM,CAAC;YACrD,aAAa,EAAE,OAAO,CAAC,aAAa;YACpC,YAAY,EAAE,OAAO,CAAC,YAAY;YAClC,OAAO,EAAE,IAAI,eAAe,EAAE;YAC9B,OAAO;SACR,CAAC;QACF,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,QAAQ,CAAC;QACjD,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,YAAY,KAAK,KAAK,CAAC;IACrD,CAAC;IAED,GAAG,CAAC,OAAqB;QACvB,OAAO,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IACtE,CAAC;IAED;;;;;;;OAOG;IACH,WAAW,CAAC,OAAqB;QAC/B,IAAI,IAAI,CAAC,KAAK,KAAK,MAAM,EAAE,CAAC;YAC1B,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,gBAAgB,CACxC,SAAS,CAAC,aAAa,EACvB,kEAAkE,CACnE,CAAC,CAAC;QACL,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,IAAkC,EAAE;YACrE,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;YAC/E,IAAI,CAAC,IAAI,CAAC,YAAY,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC;gBAAE,OAAO,EAAE,KAAK,EAAE,CAAC;YACrE,oEAAoE;YACpE,6DAA6D;YAC7D,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;YACvC,IAAI,CAAC,OAAO;gBAAE,OAAO,EAAE,KAAK,EAAE,CAAC;YAE/B,qEAAqE;YACrE,mEAAmE;YACnE,oEAAoE;YACpE,wCAAwC;YACxC,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,OAAO,CAAC,CAAC;YACzC,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;gBACpB,OAAO;oBACL,KAAK;oBACL,KAAK,EAAE,gBAAgB,MAAM,mDAAmD;iBACjF,CAAC;YACJ,CAAC;YAED,MAAM,IAAI,GAAG,MAAM,YAAY,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YAClE,mEAAmE;YACnE,cAAc;YACd,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YAC7C,OAAO,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;QAChE,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CACrB,GAAG,EAAE,CAAC,SAAS,EACf,GAAG,EAAE,CAAC,SAAS,CAChB,CAAC;QACF,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,KAAK;QACH,IAAI,IAAI,CAAC,YAAY;YAAE,OAAO,IAAI,CAAC,YAAY,CAAC;QAEhD,IAAI,CAAC,KAAK,GAAG,SAAS,CAAC;QACvB,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,CACpE,GAAG,EAAE;YACH,IAAI,CAAC,KAAK,GAAG,QAAQ,CAAC;YACtB,oEAAoE;YACpE,mEAAmE;YACnE,oEAAoE;YACpE,0CAA0C;YAC1C,sBAAsB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACnC,CAAC,EACD,CAAC,KAAc,EAAE,EAAE;YACjB,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;YACzB,MAAM,KAAK,CAAC;QACd,CAAC,CACF,CAAC;QACF,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;CACF"}

package/dist/cli/artifactPaths.d.ts

@@ -0,0 +1,42 @@
+export declare const MAX_ARTIFACT_NAME = 64;
+export declare function validateArtifactName(raw: unknown, kind: string, root: string): string;
+/**
+ * Full path for `<name><suffix>` inside `root`, proven to stay there.
+ *
+ * Creates the root (mode 0700) as a side effect so readers and writers agree
+ * on where it is even on a first run.
+ */
+export declare function resolveArtifactPath(opts: {
+    root: string;
+    name: string;
+    /** `.json` for state; empty for a trace directory. */
+    suffix?: string;
+    /** Used in error messages: `state`, `trace`. */
+    kind: string;
+}): Promise<string>;
+/**
+ * Prepare a temp path next to `target`, pre-created with owner-only
+ * permissions.
+ *
+ * Opened `wx` (`O_EXCL`), which is what makes the mode guarantee real: plain
+ * `w` follows an existing symlink and ignores the mode argument, so a
+ * leftover or planted entry would silently redirect the write and leave the
+ * mode unset. The random suffix keeps concurrent writers from colliding.
+ */
+export declare function prepareTempPath(target: string): Promise<string>;
+/** Move a fully written temp file into place. */
+export declare function commitFile(tmp: string, target: string): Promise<void>;
+/** Best-effort cleanup for a failed write. */
+export declare function discardTempFile(tmp: string): Promise<void>;
+/**
+ * Root for a CLI-owned artifact kind, overridable by env.
+ *
+ * Anchored to the project root rather than `process.cwd()`. The daemon is a
+ * long-lived process with its own working directory, so resolving from `cwd`
+ * meant saved state and traces landed wherever the daemon happened to be
+ * started — and, before the socket was project-scoped, in a different project
+ * entirely. Anchoring also makes a run from a subdirectory address the same
+ * artifacts as one from the repository root.
+ */
+export declare function artifactRoot(kind: 'state' | 'traces' | 'screenshots', envVar: string, env?: NodeJS.ProcessEnv): string;
+//# sourceMappingURL=artifactPaths.d.ts.map

package/dist/cli/artifactPaths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifactPaths.d.ts","sourceRoot":"","sources":["../../src/cli/artifactPaths.ts"],"names":[],"mappings":"AA0BA,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAEpC,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CA6BrF;AA4BD;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CAAC,MAAM,CAAC,CAsBlB;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAKrE;AAED,iDAAiD;AACjD,wBAAsB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ3E;AAED,8CAA8C;AAC9C,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEhE;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAKnI"}

package/dist/cli/artifactPaths.js

@@ -0,0 +1,144 @@
+/**
+ * Shared path safety for CLI-owned artifact directories.
+ *
+ * Saved login state and traces both write files a name chooses, under a root
+ * craftdriver owns. The rules are identical and security-relevant — a name is
+ * never a path, and a symlink must not widen the root — so they live here once
+ * rather than being reimplemented per artifact kind. The one place this
+ * codebase already copied helpers between modules (`locatorCandidates` from
+ * `snapshot`) is recorded as a mistake because the copies then diverged.
+ *
+ * Callers supply the root and the kind label; the rules do not vary.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { CraftdriverError, ErrorCode } from '../lib/errors.js';
+import { projectRoot } from './defaults.js';
+/**
+ * Accepted artifact names.
+ *
+ * Deliberately narrower than "a valid filename": with no `.`, `/` or `\` a
+ * name cannot traverse or hide, and a required leading alphanumeric means it
+ * can never be read as a flag.
+ */
+const ARTIFACT_NAME = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+export const MAX_ARTIFACT_NAME = 64;
+export function validateArtifactName(raw, kind, root) {
+    if (typeof raw !== 'string' || raw.length === 0) {
+        throw new CraftdriverError(ErrorCode.INVALID_ARGUMENT, `${kind}: a name is required`, {
+            hint: `pass a bare name, e.g. \`${kind} save alice\``,
+        });
+    }
+    // Reported apart from the charset rule: a caller passing a path is making a
+    // different mistake than one passing "my file", and the fix differs.
+    if (raw.includes('/') || raw.includes('\\') || raw.includes('.')) {
+        throw new CraftdriverError(ErrorCode.INVALID_ARGUMENT, `${kind}: ${JSON.stringify(raw)} is a name, not a path`, {
+            detail: { root },
+            hint: `pass a bare name like \`alice\`; files are kept under the ${kind} root`,
+        });
+    }
+    if (raw.length > MAX_ARTIFACT_NAME || !ARTIFACT_NAME.test(raw)) {
+        throw new CraftdriverError(ErrorCode.INVALID_ARGUMENT, `${kind}: invalid name ${JSON.stringify(raw)}`, {
+            detail: { maxLength: MAX_ARTIFACT_NAME },
+            hint: `must start with a letter or digit and use only letters, digits, "-" and "_" (max ${MAX_ARTIFACT_NAME} chars)`,
+        });
+    }
+    return raw;
+}
+function isInside(root, target) {
+    const rel = path.relative(root, target);
+    return rel.length > 0 && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+/**
+ * Resolve the real path of the deepest ancestor of `target` that exists.
+ *
+ * Checking `realpath(target)` alone is not enough: the target usually does not
+ * exist yet when writing, and a symlinked *directory* in the middle of the
+ * path is exactly the escape this guards against.
+ */
+async function realpathOfExistingAncestor(target) {
+    let current = target;
+    for (;;) {
+        try {
+            return await fs.realpath(current);
+        }
+        catch {
+            const parent = path.dirname(current);
+            // Reached the filesystem root without finding anything that exists.
+            if (parent === current)
+                return current;
+            current = parent;
+        }
+    }
+}
+/**
+ * Full path for `<name><suffix>` inside `root`, proven to stay there.
+ *
+ * Creates the root (mode 0700) as a side effect so readers and writers agree
+ * on where it is even on a first run.
+ */
+export async function resolveArtifactPath(opts) {
+    const { root, kind } = opts;
+    const validated = validateArtifactName(opts.name, kind, root);
+    const target = path.join(root, `${validated}${opts.suffix ?? ''}`);
+    await fs.mkdir(root, { recursive: true, mode: 0o700 });
+    const realRoot = await fs.realpath(root);
+    const realAncestor = await realpathOfExistingAncestor(target);
+    // Either the root itself (target not created yet) or the target, which must
+    // resolve to something inside the root.
+    if (realAncestor !== realRoot && !isInside(realRoot, realAncestor)) {
+        throw new CraftdriverError(ErrorCode.INVALID_ARGUMENT, `${kind}: ${JSON.stringify(opts.name)} resolves outside the ${kind} root`, {
+            detail: { root: realRoot },
+            hint: `a symlink in the ${kind} directory points elsewhere; remove it`,
+        });
+    }
+    return target;
+}
+/**
+ * Prepare a temp path next to `target`, pre-created with owner-only
+ * permissions.
+ *
+ * Opened `wx` (`O_EXCL`), which is what makes the mode guarantee real: plain
+ * `w` follows an existing symlink and ignores the mode argument, so a
+ * leftover or planted entry would silently redirect the write and leave the
+ * mode unset. The random suffix keeps concurrent writers from colliding.
+ */
+export async function prepareTempPath(target) {
+    const tmp = `${target}.tmp-${process.pid}-${randomBytes(6).toString('hex')}`;
+    const handle = await fs.open(tmp, 'wx', 0o600);
+    await handle.close();
+    return tmp;
+}
+/** Move a fully written temp file into place. */
+export async function commitFile(tmp, target) {
+    try {
+        await fs.chmod(tmp, 0o600);
+        await fs.rename(tmp, target);
+    }
+    catch (err) {
+        await fs.rm(tmp, { force: true }).catch(() => { });
+        throw err;
+    }
+}
+/** Best-effort cleanup for a failed write. */
+export async function discardTempFile(tmp) {
+    await fs.rm(tmp, { force: true }).catch(() => { });
+}
+/**
+ * Root for a CLI-owned artifact kind, overridable by env.
+ *
+ * Anchored to the project root rather than `process.cwd()`. The daemon is a
+ * long-lived process with its own working directory, so resolving from `cwd`
+ * meant saved state and traces landed wherever the daemon happened to be
+ * started — and, before the socket was project-scoped, in a different project
+ * entirely. Anchoring also makes a run from a subdirectory address the same
+ * artifacts as one from the repository root.
+ */
+export function artifactRoot(kind, envVar, env = process.env) {
+    const override = env[envVar];
+    return override && override.length > 0
+        ? path.resolve(override)
+        : path.resolve(projectRoot(), '.craftdriver', kind);
+}
+//# sourceMappingURL=artifactPaths.js.map

package/dist/cli/artifactPaths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifactPaths.js","sourceRoot":"","sources":["../../src/cli/artifactPaths.ts"],"names":[],"mappings":"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"}

package/dist/cli/bounds.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Transport-neutral output bounds for the agent surface.
+ *
+ * Bounded, token-efficient output is a product contract, not an MCP feature.
+ * It was only ever enforced on the MCP envelope, so the same `eval` that
+ * produced a 32 KB-capped MCP result produced a ~1 MB daemon response, read
+ * into an unbounded client buffer, printed in full. The bound belongs where
+ * the value is produced, so every transport inherits it.
+ *
+ * Truncation is always visible: a shortened value carries `truncated` and the
+ * byte counts, so an agent can tell a short answer from a shortened one.
+ * Cuts land on code-point boundaries — splitting a multi-byte sequence would
+ * emit a replacement character, or an unparseable frame.
+ */
+/** Cap on a single command result. */
+export declare const DEFAULT_MAX_RESULT_BYTES: number;
+/** Cap on `--ephemeral` stdin, which is read whole into memory. */
+export declare const MAX_STDIN_BYTES: number;
+/** Largest `--limit` a list-returning command will honour. */
+export declare const MAX_LIST_LIMIT = 1000;
+/**
+ * Largest `--limit` a *character*-limited command will honour.
+ *
+ * Separate from the list cap because they count different things: `text`
+ * takes a character budget whose default is already 2000, so clamping it to
+ * the row cap silently halved it. The result is still bounded by
+ * `resolveMaxResultBytes` regardless of what is asked for here.
+ */
+export declare const MAX_TEXT_CHARS = 100000;
+export declare function resolveMaxResultBytes(env?: NodeJS.ProcessEnv): number;
+export declare function utf8Bytes(text: string): number;
+/**
+ * Truncate to at most `maxBytes` of UTF-8, never splitting a character.
+ *
+ * Iterates code points (so a surrogate pair is kept whole) and stops before
+ * the budget is exceeded. A string already within budget is returned as-is.
+ */
+export declare function truncateUtf8(text: string, maxBytes: number): string;
+export interface BoundedValue {
+    value: unknown;
+    truncated: true;
+    /** Bytes the full value would have occupied once serialized. */
+    totalBytes: number;
+    /** Bytes actually retained. */
+    retainedBytes: number;
+}
+/**
+ * Bound one command result value.
+ *
+ * A string is truncated in place, which keeps the common case (`eval`
+ * returning a long string, `text` on a large element) readable. Anything else
+ * is serialized and replaced by a bounded preview, because trimming an
+ * arbitrary object structurally would produce something that still looks like
+ * a complete answer.
+ */
+export declare function boundValue(value: unknown, maxBytes?: number): unknown | BoundedValue;
+/**
+ * Clamp a caller-supplied list limit.
+ *
+ * A negative limit silently returned nothing and a huge one defeated the
+ * paging that keeps list output bounded, so both are pulled into range rather
+ * than rejected — the agent asked for a list, and one it can read is a better
+ * answer than an error.
+ */
+export declare function clampLimit(raw: number, fallback: number, max?: number): number;
+/**
+ * One bounded string result.
+ *
+ * `text`, `attr` and `value` all return a string that the page controls, and
+ * all three reported it differently once bounding was added — a bare string
+ * under budget, a nested object over it. This keeps the shape identical
+ * either way, so a caller reads `.value` and checks `.truncated` without
+ * having to type-test first.
+ */
+export interface BoundedString {
+    value: string | null;
+    truncated: boolean;
+    /** Length in characters of the untruncated string. */
+    total: number;
+}
+export interface BoundStringOptions {
+    /** Transport-neutral byte ceiling. */
+    maxBytes?: number;
+    /** Optional caller-visible character limit, such as `text --limit`. */
+    maxChars?: number;
+}
+export declare function boundString(raw: string | null, options?: BoundStringOptions): BoundedString;
+//# sourceMappingURL=bounds.d.ts.map

package/dist/cli/bounds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bounds.d.ts","sourceRoot":"","sources":["../../src/cli/bounds.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,sCAAsC;AACtC,eAAO,MAAM,wBAAwB,QAAY,CAAC;AAElD,mEAAmE;AACnE,eAAO,MAAM,eAAe,QAAc,CAAC;AAE3C,8DAA8D;AAC9D,eAAO,MAAM,cAAc,OAAO,CAAC;AAEnC;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,SAAU,CAAC;AAEtC,wBAAgB,qBAAqB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAOlF;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAanE;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,IAAI,CAAC;IAChB,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;IACnB,+BAA+B;IAC/B,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,SAA0B,GAAG,OAAO,GAAG,YAAY,CA4BrG;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,SAAiB,GAAG,MAAM,CAKtF;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;IACnB,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,EAAE,OAAO,GAAE,kBAAuB,GAAG,aAAa,CAO/F"}