tuna-agent 0.1.0 → 0.1.2

package/dist/browser/types.d.ts

@@ -0,0 +1,429 @@
+/**
+ * Policy for controlling which URLs browser navigation is allowed to reach.
+ * Defaults to trusted-network mode (private/internal addresses allowed).
+ * Set `dangerouslyAllowPrivateNetwork: false` to enforce strict public-only checks.
+ */
+export interface SsrfPolicy {
+    /**
+     * Allow navigation to private/internal network addresses.
+     * Default: `true` (trusted-network mode). Set to `false` for strict public-only enforcement.
+     */
+    dangerouslyAllowPrivateNetwork?: boolean;
+    /**
+     * Allow navigation to private/internal network addresses.
+     * @deprecated Use `dangerouslyAllowPrivateNetwork` instead.
+     */
+    allowPrivateNetwork?: boolean;
+    /** Hostnames explicitly allowed even if they resolve to private addresses */
+    allowedHostnames?: string[];
+    /** Alias for allowedHostnames */
+    hostnameAllowlist?: string[];
+}
+/** Supported browser types that can be detected and launched. */
+export type ChromeKind = 'chrome' | 'brave' | 'edge' | 'chromium' | 'canary' | 'custom';
+/** A detected browser executable on the system. */
+export interface ChromeExecutable {
+    /** The type of browser (chrome, brave, edge, etc.) */
+    kind: ChromeKind;
+    /** Absolute path to the browser executable */
+    path: string;
+}
+/** A running Chrome instance managed by browserclaw. */
+export interface RunningChrome {
+    /** Process ID of the Chrome process */
+    pid: number;
+    /** The browser executable that was launched */
+    exe: ChromeExecutable;
+    /** Path to the Chrome user data directory */
+    userDataDir: string;
+    /** CDP (Chrome DevTools Protocol) port number */
+    cdpPort: number;
+    /** Unix timestamp (ms) when the browser was started */
+    startedAt: number;
+    /** The child process handle */
+    proc: import('node:child_process').ChildProcess;
+}
+/** Options for launching a new browser instance. */
+export interface LaunchOptions {
+    /** Run in headless mode (no visible window). Default: `false` */
+    headless?: boolean;
+    /** Path to a specific browser executable. Auto-detected if omitted. */
+    executablePath?: string;
+    /** CDP port to use. Default: `9222` */
+    cdpPort?: number;
+    /** Disable Chrome's sandbox (needed in some Docker/CI environments). Default: `false` */
+    noSandbox?: boolean;
+    /** Custom user data directory. Auto-generated if omitted. */
+    userDataDir?: string;
+    /** Chrome profile directory name (e.g. 'Profile 74'). Uses 'Default' if omitted. */
+    profileDirectory?: string;
+    /** Profile name shown in the Chrome title bar. Default: `'browserclaw'` */
+    profileName?: string;
+    /** Profile accent color as a hex string (e.g. `'#FF4500'`). Default: `'#FF4500'` */
+    profileColor?: string;
+    /** Additional Chrome command-line arguments (e.g. `['--start-maximized']`). */
+    chromeArgs?: string[];
+    /**
+     * SSRF policy controlling which URLs navigation is allowed to reach.
+     * Defaults to trusted-network mode (private/internal addresses allowed).
+     * Set `dangerouslyAllowPrivateNetwork: false` to enforce strict public-only checks.
+     */
+    ssrfPolicy?: SsrfPolicy;
+    /**
+     * Allow navigation to internal/loopback addresses (localhost, 127.x, private IPs).
+     * @deprecated Use `ssrfPolicy: { dangerouslyAllowPrivateNetwork: true }` instead.
+     */
+    allowInternal?: boolean;
+}
+/** Options for connecting to an existing browser instance. */
+export interface ConnectOptions {
+    /**
+     * SSRF policy controlling which URLs navigation is allowed to reach.
+     * Defaults to trusted-network mode (private/internal addresses allowed).
+     * Set `dangerouslyAllowPrivateNetwork: false` to enforce strict public-only checks.
+     */
+    ssrfPolicy?: SsrfPolicy;
+    /**
+     * Allow navigation to internal/loopback addresses (localhost, 127.x, private IPs).
+     * @deprecated Use `ssrfPolicy: { dangerouslyAllowPrivateNetwork: true }` instead.
+     */
+    allowInternal?: boolean;
+    /**
+     * Bearer token for authenticating with the CDP endpoint.
+     * Required when connecting to a browser instance that has auth enabled
+     * (e.g. OpenClaw browser control with gateway.auth.token).
+     */
+    authToken?: string;
+}
+/**
+ * Describes a single interactive element found during a snapshot.
+ * Used to resolve refs (e.g. `e1`) back to Playwright locators.
+ */
+export interface RoleRefInfo {
+    /** ARIA role of the element (e.g. `'button'`, `'textbox'`, `'link'`) */
+    role: string;
+    /** Accessible name of the element */
+    name?: string;
+    /** Disambiguation index when multiple elements share the same role + name */
+    nth?: number;
+}
+/** Map of ref IDs (e.g. `'e1'`, `'e2'`) to their element information. */
+export type RoleRefs = Record<string, RoleRefInfo>;
+/**
+ * Metadata about the source of untrusted external content.
+ * Used by consumers (e.g. OpenClaw) to wrap browser outputs with
+ * structured external-content markers for prompt-injection mitigation.
+ */
+export interface UntrustedContentMeta {
+    /** The source URL of the content at the time of capture */
+    sourceUrl?: string;
+    /** Content type identifier (e.g. `'browser-snapshot'`, `'browser-aria-tree'`) */
+    contentType: string;
+    /** ISO 8601 timestamp of when the content was captured */
+    capturedAt: string;
+}
+/** Result of taking a page snapshot. */
+export interface SnapshotResult {
+    /** AI-readable text representation of the page with numbered refs */
+    snapshot: string;
+    /** Map of ref IDs to element information for targeting actions */
+    refs: RoleRefs;
+    /** Statistics about the snapshot */
+    stats?: SnapshotStats;
+    /**
+     * Indicates this content originates from an untrusted external source (the web page).
+     * AI agents should treat snapshot content as potentially adversarial
+     * (e.g. prompt injection via page text). Always `true` for browser snapshots.
+     */
+    untrusted?: true;
+    /** Structured metadata about the untrusted content source */
+    contentMeta?: UntrustedContentMeta;
+}
+/** Statistics about a snapshot's content. */
+export interface SnapshotStats {
+    /** Number of lines in the snapshot text */
+    lines: number;
+    /** Number of characters in the snapshot text */
+    chars: number;
+    /** Total number of refs assigned */
+    refs: number;
+    /** Number of interactive element refs (buttons, links, inputs, etc.) */
+    interactive: number;
+}
+/** Options for controlling snapshot output. */
+export interface SnapshotOptions {
+    /** Only include interactive elements (buttons, links, inputs, etc.) */
+    interactive?: boolean;
+    /** Remove structural containers that don't contain interactive elements */
+    compact?: boolean;
+    /** Maximum tree depth to include */
+    maxDepth?: number;
+    /** Maximum character count before truncation (aria mode only) */
+    maxChars?: number;
+    /** CSS selector to scope the snapshot to a specific element (role mode only — throws in aria mode) */
+    selector?: string;
+    /** Frame selector for snapshotting inside iframes (role mode only — throws in aria mode) */
+    frameSelector?: string;
+    /**
+     * Snapshot strategy:
+     * - `'aria'` (default) — uses Playwright's `_snapshotForAI()`, produces refs like `e1`
+     * - `'role'` — uses Playwright's `ariaSnapshot()` + `getByRole()` resolution
+     */
+    mode?: 'role' | 'aria';
+    /** Timeout in milliseconds for the snapshot operation (role mode only, default: 5000) */
+    timeoutMs?: number;
+    /**
+     * How refs are stored for role-mode snapshots.
+     * - `'role'` (default) — refs resolved via `getByRole()`
+     * - `'aria'` — refs resolved via aria snapshot index
+     * Only applies when `mode: 'role'`.
+     */
+    refsMode?: 'role' | 'aria';
+}
+/** A node in the raw ARIA accessibility tree. */
+export interface AriaNode {
+    /** Ref ID for this node (e.g. `'ax1'`) */
+    ref: string;
+    /** ARIA role (e.g. `'button'`, `'heading'`, `'generic'`) */
+    role: string;
+    /** Accessible name */
+    name: string;
+    /** Current value (for inputs, sliders, etc.) */
+    value?: string;
+    /** Accessible description */
+    description?: string;
+    /** Backend DOM node ID (for CDP operations) */
+    backendDOMNodeId?: number;
+    /** Depth in the accessibility tree (0 = root) */
+    depth: number;
+}
+/** Result of a raw ARIA tree snapshot. */
+export interface AriaSnapshotResult {
+    /** Flat list of accessibility tree nodes */
+    nodes: AriaNode[];
+    /**
+     * Indicates this content originates from an untrusted external source (the web page).
+     * AI agents should treat snapshot content as potentially adversarial. Always `true`.
+     */
+    untrusted?: true;
+    /** Structured metadata about the untrusted content source */
+    contentMeta?: UntrustedContentMeta;
+}
+/** A form field to fill as part of a batch `fill()` operation. */
+export interface FormField {
+    /** Ref ID of the form field (e.g. `'e3'`) */
+    ref: string;
+    /** Field type: `'text'`, `'checkbox'`, `'radio'`, etc. */
+    type?: string;
+    /** Value to set. Booleans for checkboxes, strings for text fields. */
+    value?: string | number | boolean;
+}
+/** Options for click actions. */
+export interface ClickOptions {
+    /** Double-click instead of single click */
+    doubleClick?: boolean;
+    /** Mouse button to use */
+    button?: 'left' | 'right' | 'middle';
+    /** Modifier keys to hold during click */
+    modifiers?: ('Alt' | 'Control' | 'ControlOrMeta' | 'Meta' | 'Shift')[];
+    /** Timeout in milliseconds. Default: `8000` */
+    timeoutMs?: number;
+}
+/** Options for type actions. */
+export interface TypeOptions {
+    /** Press Enter after typing */
+    submit?: boolean;
+    /** Type character-by-character with delay (75ms per key) instead of instant fill */
+    slowly?: boolean;
+    /** Timeout in milliseconds. Default: `8000` */
+    timeoutMs?: number;
+}
+/**
+ * Options for waiting on various conditions.
+ * Multiple conditions can be combined — they are checked in order.
+ */
+export interface WaitOptions {
+    /** Wait for a fixed duration (milliseconds) */
+    timeMs?: number;
+    /** Wait until text appears on the page */
+    text?: string;
+    /** Wait until text disappears from the page */
+    textGone?: string;
+    /** Wait until a CSS selector matches a visible element */
+    selector?: string;
+    /** Wait until the URL matches a pattern (supports `**` wildcards) */
+    url?: string;
+    /** Wait for a specific page load state */
+    loadState?: 'load' | 'domcontentloaded' | 'networkidle';
+    /** Wait until a JavaScript function returns truthy (evaluated in browser context) */
+    fn?: string;
+    /** Timeout for each condition in milliseconds. Default: `20000` */
+    timeoutMs?: number;
+}
+/** Options for screenshot capture. */
+export interface ScreenshotOptions {
+    /** Capture the full scrollable page instead of just the viewport */
+    fullPage?: boolean;
+    /** Capture a specific element by ref ID */
+    ref?: string;
+    /** Capture a specific element by CSS selector */
+    element?: string;
+    /** Image format. Default: `'png'` */
+    type?: 'png' | 'jpeg';
+    /** Enable labeled screenshot mode (used internally by screenshotWithLabels) */
+    labels?: boolean;
+}
+/** A console message captured from the browser page. */
+export interface ConsoleMessage {
+    /** Message type: `'log'`, `'info'`, `'warning'`, `'error'`, `'debug'` */
+    type: string;
+    /** The message text */
+    text: string;
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** Source location where the message was logged */
+    location?: {
+        url?: string;
+        lineNumber?: number;
+        columnNumber?: number;
+    };
+}
+/** An uncaught error from the browser page. */
+export interface PageError {
+    /** Error message */
+    message: string;
+    /** Error name (e.g. `'TypeError'`) */
+    name?: string;
+    /** Stack trace */
+    stack?: string;
+    /** ISO 8601 timestamp */
+    timestamp: string;
+}
+/** A network request captured from the browser page. */
+export interface NetworkRequest {
+    /** Internal request ID (e.g. `'r1'`, `'r2'`) */
+    id: string;
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** HTTP method (e.g. `'GET'`, `'POST'`) */
+    method: string;
+    /** Request URL */
+    url: string;
+    /** Resource type (e.g. `'document'`, `'xhr'`, `'fetch'`, `'image'`) */
+    resourceType: string;
+    /** HTTP status code (set when response is received) */
+    status?: number;
+    /** Whether the response status was 2xx */
+    ok?: boolean;
+    /** Error text if the request failed */
+    failureText?: string;
+}
+/** Web storage type. */
+export type StorageKind = 'local' | 'session';
+/** Cookie data for setting a browser cookie. */
+export interface CookieData {
+    /** Cookie name */
+    name: string;
+    /** Cookie value */
+    value: string;
+    /** URL to associate the cookie with (alternative to domain+path) */
+    url?: string;
+    /** Cookie domain */
+    domain?: string;
+    /** Cookie path */
+    path?: string;
+    /** Expiration as Unix timestamp in seconds */
+    expires?: number;
+    /** HTTP-only flag */
+    httpOnly?: boolean;
+    /** Secure flag */
+    secure?: boolean;
+    /** SameSite attribute */
+    sameSite?: 'Strict' | 'Lax' | 'None';
+}
+/** Information about an open browser tab. */
+export interface BrowserTab {
+    /** CDP target ID (used to identify this tab in API calls) */
+    targetId: string;
+    /** Page title */
+    title: string;
+    /** Current URL */
+    url: string;
+    /** Target type (usually `'page'`) */
+    type: string;
+}
+/** Result of a download operation. */
+export interface DownloadResult {
+    /** The URL that initiated the download */
+    url: string;
+    /** Filename suggested by the server */
+    suggestedFilename: string;
+    /** Local path where the file was saved */
+    path: string;
+}
+/** Options for arming a dialog handler. */
+export interface DialogOptions {
+    /** Whether to accept or dismiss the dialog */
+    accept: boolean;
+    /** Text to enter in a prompt dialog */
+    promptText?: string;
+    /** Timeout for waiting for the dialog. Default: `30000` */
+    timeoutMs?: number;
+}
+/** Result of intercepting a response body. */
+export interface ResponseBodyResult {
+    /** The response URL */
+    url: string;
+    /** HTTP status code */
+    status?: number;
+    /** Response headers */
+    headers?: Record<string, string>;
+    /** Response body text */
+    body: string;
+    /** Whether the body was truncated due to maxChars */
+    truncated?: boolean;
+}
+/** Options for starting a Playwright trace. */
+export interface TraceStartOptions {
+    /** Capture screenshots during tracing */
+    screenshots?: boolean;
+    /** Capture DOM snapshots during tracing */
+    snapshots?: boolean;
+    /** Include source files in the trace */
+    sources?: boolean;
+}
+/** Color scheme for media emulation. */
+export type ColorScheme = 'dark' | 'light' | 'no-preference' | null;
+/** Options for geolocation emulation. */
+export interface GeolocationOptions {
+    /** Latitude in degrees */
+    latitude?: number;
+    /** Longitude in degrees */
+    longitude?: number;
+    /** Accuracy in meters */
+    accuracy?: number;
+    /** Origin to grant geolocation permission for (e.g. `'https://example.com'`) */
+    origin?: string;
+    /** Clear geolocation override */
+    clear?: boolean;
+}
+/** HTTP credentials for authentication. */
+export interface HttpCredentials {
+    /** Username for HTTP authentication */
+    username?: string;
+    /** Password for HTTP authentication */
+    password?: string;
+    /** Clear HTTP credentials */
+    clear?: boolean;
+}
+/** @internal */
+export interface PageState {
+    console: ConsoleMessage[];
+    errors: PageError[];
+    requests: NetworkRequest[];
+    requestIds: WeakMap<object, string>;
+    nextRequestId: number;
+    roleRefs?: RoleRefs;
+    roleRefsFrameSelector?: string;
+    roleRefsMode?: 'role' | 'aria';
+}

package/dist/browser/types.js

@@ -0,0 +1,2 @@
+// ── SSRF Policy ──
+export {};

package/dist/cli/commands/extension.d.ts

@@ -0,0 +1,10 @@
+/**
+ * List all Chrome extensions paired with this machine.
+ * Usage: tuna-agent extension list
+ */
+export declare function extensionList(): Promise<void>;
+/**
+ * Pair this machine with a Chrome extension using its pairing code.
+ * Usage: tuna-agent extension connect TUNA-XXXX-XXXX
+ */
+export declare function extensionConnect(code: string): Promise<void>;

package/dist/cli/commands/extension.js

@@ -0,0 +1,86 @@
+import chalk from 'chalk';
+import { loadConfig, saveConfig } from '../../config/store.js';
+/**
+ * List all Chrome extensions paired with this machine.
+ * Usage: tuna-agent extension list
+ */
+export async function extensionList() {
+    const config = loadConfig();
+    if (!config) {
+        console.error(chalk.red('Not connected. Run tuna-agent connect <CODE> first.'));
+        process.exit(1);
+    }
+    try {
+        const res = await fetch(`${config.apiUrl}/extension/list`, {
+            headers: { 'Authorization': `Bearer ${config.agentToken}` },
+        });
+        const body = await res.json();
+        if (!res.ok || !body.data) {
+            console.error(chalk.red(`Failed: ${body.message || 'Unknown error'}`));
+            process.exit(1);
+        }
+        const { extensions, total } = body.data;
+        console.log(chalk.cyan(`\nPaired Extensions (${total})\n`));
+        if (total === 0) {
+            console.log(chalk.gray('  No extensions paired yet.'));
+            console.log(`\n  Run ${chalk.bold('tuna-agent extension connect <CODE>')} to pair one.`);
+            return;
+        }
+        for (const ext of extensions) {
+            const status = ext.connected ? chalk.green('● connected') : chalk.gray('○ offline');
+            console.log(`  ${status}  ${chalk.bold(ext.code)}`);
+        }
+        console.log('');
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(chalk.red(`\nFailed: ${msg}`));
+        process.exit(1);
+    }
+}
+/**
+ * Pair this machine with a Chrome extension using its pairing code.
+ * Usage: tuna-agent extension connect TUNA-XXXX-XXXX
+ */
+export async function extensionConnect(code) {
+    const config = loadConfig();
+    if (!config) {
+        console.error(chalk.red('Not connected. Run tuna-agent connect <CODE> first.'));
+        process.exit(1);
+    }
+    const normalizedCode = code.trim().toUpperCase();
+    if (!normalizedCode.startsWith('TUNA-')) {
+        console.error(chalk.red('Invalid pair code. Expected format: TUNA-XXXX-XXXX'));
+        process.exit(1);
+    }
+    console.log(chalk.cyan('Pairing with Chrome extension...'));
+    console.log(`  Code: ${chalk.bold(normalizedCode)}`);
+    try {
+        const res = await fetch(`${config.apiUrl}/extension/pair`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${config.agentToken}`,
+            },
+            body: JSON.stringify({ code: normalizedCode }),
+        });
+        const body = await res.json();
+        if (!res.ok || !body.data) {
+            console.error(chalk.red(`\nFailed: ${body.message || 'Unknown error'}`));
+            process.exit(1);
+        }
+        console.log(chalk.green('\nExtension paired successfully!'));
+        console.log(`  Machine: ${body.data.machineName}`);
+        console.log('\nThe Content Creator extension should now show your agent as connected.');
+        // Save code locally so agent can restore the pairing after server restart
+        const codes = new Set(config.extensionCodes || []);
+        codes.add(normalizedCode);
+        saveConfig({ ...config, extensionCodes: [...codes] });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(chalk.red(`\nPairing failed: ${msg}`));
+        console.error(`Make sure tuna-agent daemon is configured (run tuna-agent connect first)`);
+        process.exit(1);
+    }
+}

package/dist/cli/index.js

@@ -4,6 +4,7 @@ import { connect } from './commands/connect.js';
 import { start } from './commands/start.js';
 import { stop } from './commands/stop.js';
 import { status } from './commands/status.js';
+import { extensionConnect, extensionList } from './commands/extension.js';
 const program = new Command()
     .name('tuna-agent')
     .description('Tuna Agent - Run AI coding tasks on your machine')
@@ -29,4 +30,15 @@ program
     .command('status')
     .description('Show agent connection status')
     .action(status);
+const extensionCmd = program
+    .command('extension')
+    .description('Manage Chrome extension pairing');
+extensionCmd
+    .command('connect <code>')
+    .description('Pair this agent with the Content Creator Chrome extension')
+    .action(extensionConnect);
+extensionCmd
+    .command('list')
+    .description('List all Chrome extensions paired with this machine')
+    .action(extensionList);
 program.parse();

package/dist/daemon/extension-handlers.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Extension Task Handlers
+ * Handles specialized tasks from the Chrome extension that don't need Claude:
+ * - get_history       — return local video history
+ * - retry_video       — re-queue a video for rendering
+ * - generate_scene(s) — call Veo3 to create clips
+ * - render_video      — compose final video via Remotion
+ * - list_characters   — return character profiles with thumbnails
+ * - create_character  — create new character profile directory
+ */
+import { AgentWebSocketClient } from './ws-client.js';
+export interface VideoRecord {
+    id: string;
+    title: string;
+    niche: string;
+    status: 'processing' | 'rendered' | 'failed';
+    progress: number;
+    error?: string;
+    createdAt: string;
+    outputPath?: string;
+    scenes?: Array<{
+        idx: number;
+        videoUrl?: string;
+        prompt: string;
+    }>;
+    aspectRatio?: string;
+}
+export declare function handleGetHistory(ws: AgentWebSocketClient, code: string, taskId: string): void;
+export declare function handleGenerateIdeas(ws: AgentWebSocketClient, code: string, taskId: string, topic: string): Promise<void>;
+export declare function handleGenerateScript(ws: AgentWebSocketClient, code: string, taskId: string, idea: string, topic: string, style?: string): Promise<void>;
+export declare function handleRetryVideo(ws: AgentWebSocketClient, code: string, taskId: string, videoId: string): void;
+export declare function handleGenerateScene(ws: AgentWebSocketClient, code: string, taskId: string, sceneIdx: number, prompt: string, aspectRatio: string): Promise<void>;
+export declare function handleGenerateScenes(ws: AgentWebSocketClient, code: string, taskId: string, scenes: Array<{
+    idx: number;
+    prompt: string;
+}>, aspectRatio: string): Promise<void>;
+export declare function handleRenderVideo(ws: AgentWebSocketClient, code: string, taskId: string, payload: {
+    scenes: Array<{
+        idx: number;
+        videoUrl?: string;
+        prompt: string;
+    }>;
+    script: string;
+    title: string;
+    aspectRatio: string;
+    voiceId: string;
+    subtitleStyle: string;
+}): Promise<void>;
+export interface CharProfile {
+    id: string;
+    name: string;
+    thumbnail: string;
+    gender: string;
+    age: string;
+    ethnicity: string;
+    vibe: string;
+    suitableFor: string;
+    poseCount: number;
+    images?: string[];
+}
+export declare function handleListCharacters(ws: AgentWebSocketClient, code: string, taskId: string): void;
+export declare function handleCreateCharacter(ws: AgentWebSocketClient, code: string, taskId: string, name: string, displayName: string, prompt: string, outputCount?: number, orientation?: string): Promise<void>;
+export declare function handleSaveCharacterSelection(ws: AgentWebSocketClient, code: string, taskId: string, characterId: string, selectedImages: string[]): void;