dsh-browser-plus 0.0.0-stage → 0.5.0

package/lib/browser-electron/task-summary.d.ts

@@ -0,0 +1,2 @@
+/** Return a page-safe task location without path, query, or fragment data. */
+export declare function taskSummaryUrl(raw: string): string;

package/lib/browser-electron/task-summary.js

@@ -0,0 +1,12 @@
+/** Return a page-safe task location without path, query, or fragment data. */
+export function taskSummaryUrl(raw) {
+    if (raw === '')
+        return '';
+    try {
+        const origin = new URL(raw).origin;
+        return origin === 'null' ? '' : origin;
+    }
+    catch {
+        return '';
+    }
+}

package/lib/browser-electron/task-thumbnail.d.ts

@@ -0,0 +1,11 @@
+export declare const TASK_THUMBNAIL_WIDTH = 288;
+export declare const TASK_THUMBNAIL_JPEG_QUALITY = 58;
+export declare const MAX_TASK_THUMBNAIL_BYTES: number;
+export interface ThumbnailImage {
+    resize(options: {
+        width: number;
+    }): {
+        toJPEG(quality: number): Buffer;
+    };
+}
+export declare function taskThumbnailDataUrl(image: ThumbnailImage): string | undefined;

package/lib/browser-electron/task-thumbnail.js

@@ -0,0 +1,9 @@
+export const TASK_THUMBNAIL_WIDTH = 288;
+export const TASK_THUMBNAIL_JPEG_QUALITY = 58;
+export const MAX_TASK_THUMBNAIL_BYTES = 180 * 1024;
+export function taskThumbnailDataUrl(image) {
+    const jpeg = image.resize({ width: TASK_THUMBNAIL_WIDTH }).toJPEG(TASK_THUMBNAIL_JPEG_QUALITY);
+    if (jpeg.length === 0 || jpeg.length > MAX_TASK_THUMBNAIL_BYTES)
+        return undefined;
+    return `data:image/jpeg;base64,${jpeg.toString('base64')}`;
+}

package/lib/browser-electron/write-guard.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Write-path admission for browser-produced files (screenshots, downloads).
+ *
+ * The provider — not the host — owns this guard so one implementation covers
+ * the self-hosted Electron host and desktop-shell handles alike, and so it can
+ * be exercised without Electron. Roots are resolved through the deepest
+ * existing ancestor, which keeps a symlinked or `..`-laden target from
+ * escaping a root it only appears to sit inside.
+ * @module dsh-browser-plus/browser-electron/write-guard
+ */
+/**
+ * Roots a browser write may target when the config does not name any: the
+ * DSH workspace (the process working directory) and the OS temp directory.
+ * This mirrors the DSH file sandbox's "write inside the workspace" boundary.
+ */
+export declare function defaultWriteRoots(): string[];
+/**
+ * Whether a path would be admitted by {@link resolveWritePath}, without
+ * throwing. Exposed for focused tests and for callers that want to probe.
+ * @param candidate - the path to test.
+ * @param roots - the allowed roots.
+ */
+export declare function isWithinRoots(candidate: string, roots: readonly string[]): boolean;
+/**
+ * Resolve a write target and admit it only when it lands inside one of the
+ * allowed roots. Returns the absolute path to write.
+ * @param savePath - the caller-supplied path.
+ * @param roots - the allowed roots; an empty list denies every write.
+ * @throws BrowserError `BROWSER_WRITE_PATH_DENIED` when the path is unusable or outside every root.
+ */
+export declare function resolveWritePath(savePath: string, roots: readonly string[]): string;
+/**
+ * Resolve a file the browser is about to hand to a page and admit it only when
+ * it lands inside one of the allowed roots. Unlike a write target the file must
+ * already exist, so the path itself is realpath'd: a symlink to a permitted
+ * file is admitted, a symlink that leaves the roots is not.
+ * @param filePath - the caller-supplied path.
+ * @param roots - the allowed roots; an empty list denies every read.
+ * @throws BrowserError `BROWSER_READ_PATH_DENIED` when the path is unusable, missing, or outside every root.
+ */
+export declare function resolveReadPath(filePath: string, roots: readonly string[]): string;

package/lib/browser-electron/write-guard.js

@@ -0,0 +1,123 @@
+/**
+ * Write-path admission for browser-produced files (screenshots, downloads).
+ *
+ * The provider — not the host — owns this guard so one implementation covers
+ * the self-hosted Electron host and desktop-shell handles alike, and so it can
+ * be exercised without Electron. Roots are resolved through the deepest
+ * existing ancestor, which keeps a symlinked or `..`-laden target from
+ * escaping a root it only appears to sit inside.
+ * @module dsh-browser-plus/browser-electron/write-guard
+ */
+import { realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join, resolve, sep } from 'node:path';
+import { BrowserError } from "../browser/types.js";
+/**
+ * Roots a browser write may target when the config does not name any: the
+ * DSH workspace (the process working directory) and the OS temp directory.
+ * This mirrors the DSH file sandbox's "write inside the workspace" boundary.
+ */
+export function defaultWriteRoots() {
+    return [process.cwd(), tmpdir()];
+}
+/** Windows paths compare case-insensitively; POSIX paths do not. */
+function comparable(value) {
+    return process.platform === 'win32' ? value.toLowerCase() : value;
+}
+/**
+ * Resolve symlinks on the deepest ancestor that exists, then re-append the
+ * segments that do not. A save target usually does not exist yet, so the
+ * target itself cannot be realpath'd — but its parent usually can.
+ */
+function realpathOfNearestAncestor(target) {
+    let current = target;
+    const tail = [];
+    for (;;) {
+        try {
+            const real = realpathSync.native(current);
+            return tail.length === 0 ? real : join(real, ...[...tail].reverse());
+        }
+        catch {
+            const parent = dirname(current);
+            // Reached the filesystem root without finding anything real: fall back
+            // to the lexical path rather than denying a legitimate write.
+            if (parent === current)
+                return target;
+            tail.push(basename(current));
+            current = parent;
+        }
+    }
+}
+/** True when `candidate` is `root` itself or lives beneath it. */
+function within(candidate, root) {
+    if (candidate === root)
+        return true;
+    return candidate.startsWith(root.endsWith(sep) ? root : root + sep);
+}
+/** Real, comparable forms of both sides; roots are normalized exactly once per call. */
+function resolvedPair(candidate, roots) {
+    return {
+        target: comparable(realpathOfNearestAncestor(resolve(candidate))),
+        roots: roots.map(root => comparable(realpathOfNearestAncestor(resolve(root)))),
+    };
+}
+/**
+ * Whether a path would be admitted by {@link resolveWritePath}, without
+ * throwing. Exposed for focused tests and for callers that want to probe.
+ * @param candidate - the path to test.
+ * @param roots - the allowed roots.
+ */
+export function isWithinRoots(candidate, roots) {
+    const { target, roots: resolved } = resolvedPair(candidate, roots);
+    return resolved.some(root => within(target, root));
+}
+/**
+ * Resolve a write target and admit it only when it lands inside one of the
+ * allowed roots. Returns the absolute path to write.
+ * @param savePath - the caller-supplied path.
+ * @param roots - the allowed roots; an empty list denies every write.
+ * @throws BrowserError `BROWSER_WRITE_PATH_DENIED` when the path is unusable or outside every root.
+ */
+export function resolveWritePath(savePath, roots) {
+    if (typeof savePath !== 'string' || savePath.trim() === '') {
+        throw new BrowserError('browser: refusing to write without a save path', 'BROWSER_WRITE_PATH_DENIED');
+    }
+    const absolute = resolve(savePath);
+    if (!isWithinRoots(absolute, roots)) {
+        // This message reaches the model context and, through a task's error field,
+        // the page itself — so it never names an absolute path.
+        const hint = roots.length === 0 ? ' (none configured)' : '';
+        throw new BrowserError(`browser: refusing to write "${savePath}" outside the allowed roots${hint}; `
+            + 'add the directory to the browser-electron "writeRoots" config to allow it', 'BROWSER_WRITE_PATH_DENIED');
+    }
+    return absolute;
+}
+/**
+ * Resolve a file the browser is about to hand to a page and admit it only when
+ * it lands inside one of the allowed roots. Unlike a write target the file must
+ * already exist, so the path itself is realpath'd: a symlink to a permitted
+ * file is admitted, a symlink that leaves the roots is not.
+ * @param filePath - the caller-supplied path.
+ * @param roots - the allowed roots; an empty list denies every read.
+ * @throws BrowserError `BROWSER_READ_PATH_DENIED` when the path is unusable, missing, or outside every root.
+ */
+export function resolveReadPath(filePath, roots) {
+    if (typeof filePath !== 'string' || filePath.trim() === '') {
+        throw new BrowserError('browser: refusing to read without a file path', 'BROWSER_READ_PATH_DENIED');
+    }
+    const absolute = resolve(filePath);
+    let real;
+    try {
+        real = realpathSync.native(absolute);
+    }
+    catch {
+        throw new BrowserError(`browser: refusing to read "${filePath}": the file does not exist`, 'BROWSER_READ_PATH_DENIED');
+    }
+    const allowed = roots.map(root => comparable(realpathOfNearestAncestor(resolve(root))));
+    if (!allowed.some(root => within(comparable(real), root))) {
+        const hint = roots.length === 0 ? ' (none configured)' : '';
+        throw new BrowserError(`browser: refusing to read "${filePath}" outside the allowed roots${hint}; `
+            + 'add the directory to the browser-electron "readRoots" config to allow it', 'BROWSER_READ_PATH_DENIED');
+    }
+    return absolute;
+}

package/lib/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * dsh-browser-plus plugin entry: aggregates the shared-browser capability
+ * pieces. The cordis.patch.yml rows reference subpath exports:
+ *   - `dsh-browser-plus/browser`          -> the ctx.browser seam (Service)
+ *   - `dsh-browser-plus/browser-electron` -> the Electron CDP provider
+ *   - `dsh-browser-plus/tool-browser`     -> the model-facing browser_* tools
+ * This root entry only re-exports for programmatic use; the loader rows are
+ * the composition surface.
+ * @module dsh-browser-plus
+ */
+export { BrowserError } from './browser/types.ts';
+export type { BrowserChallenge, BrowserContentFormat, BrowserControlOwner, BrowserContentRequest, BrowserContentResult, BrowserDragRequest, BrowserDragResult, BrowserExecuteRequest, BrowserPointerResult, BrowserPointerTarget, BrowserExecuteResult, BrowserFillField, BrowserFillRequest, BrowserFillResult, BrowserHandoffState, BrowserNavigateRequest, BrowserOpenRequest, BrowserProvider, BrowserRefRequest, BrowserScreenshotRequest, BrowserScrollIntoViewRequest, BrowserScrollRequest, BrowserScrollResult, BrowserScreenshotResult, BrowserSessionId, BrowserSnapshotElement, BrowserSnapshotResult, BrowserTab, BrowserTaskInfo, BrowserTaskStatus, BrowserTaskUpdate, BrowserTypeRequest, ExportedCookie, } from './browser/types.ts';
+export { BrowserRuntime } from './browser/runtime.ts';
+export { ElectronBrowserProvider } from './browser-electron/provider.ts';
+export type { ElectronBrowserViewHost, ElectronViewHandle } from './browser-electron/provider.ts';
+export { RemoteElectronViewHost, defaultHostMainPath } from './browser-electron/remote-host.ts';

package/lib/index.js

@@ -0,0 +1,14 @@
+/**
+ * dsh-browser-plus plugin entry: aggregates the shared-browser capability
+ * pieces. The cordis.patch.yml rows reference subpath exports:
+ *   - `dsh-browser-plus/browser`          -> the ctx.browser seam (Service)
+ *   - `dsh-browser-plus/browser-electron` -> the Electron CDP provider
+ *   - `dsh-browser-plus/tool-browser`     -> the model-facing browser_* tools
+ * This root entry only re-exports for programmatic use; the loader rows are
+ * the composition surface.
+ * @module dsh-browser-plus
+ */
+export { BrowserError } from "./browser/types.js";
+export { BrowserRuntime } from "./browser/runtime.js";
+export { ElectronBrowserProvider } from "./browser-electron/provider.js";
+export { RemoteElectronViewHost, defaultHostMainPath } from "./browser-electron/remote-host.js";

package/lib/tool-browser/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Model-facing browser tools over `ctx.browser`: `browser_open`,
+ * `browser_snapshot`, `browser_execute`, `browser_content`,
+ * `browser_screenshot`, and tab management (`browser_list_tabs`,
+ * `browser_switch_tab`, `browser_close_tab`, `browser_reset`).
+ *
+ * The tool layer owns only the model-facing schema, argument validation, and
+ * result formatting — never provider selection or page driving, which belong
+ * to the seam. Session lifecycle is owned here at the plugin level: each
+ * calling task (a DSH session) gets its own browser session — the first
+ * `browser_open` (or any tool when no session exists) opens it, and later
+ * tools in the same task reuse it. Concurrent tasks therefore never fight
+ * over tabs, history, or navigation state.
+ * @module dsh-browser-plus/tool-browser
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Plugin name used by loader diagnostics. */
+export declare const name = "tool-browser";
+/** The tool registry, browser seam, and system-prompt registry this tool layer consumes. */
+export declare const inject: string[];
+/** Plugin config: tool timeouts and session defaults. */
+export interface Config {
+    /** Cooperative tool-call budget in ms. Default 60000. */
+    readonly timeoutMs?: number;
+    /** Whether to offer tab-management tools. Default true. */
+    readonly tabTools?: boolean;
+    /** Optional initial allow-list of browser tool names; other tools are refused. */
+    readonly allowedActions?: readonly string[];
+}
+/** Register all browser tools with `ctx.tools`. */
+export declare function apply(ctx: Context, config?: Config): void;