@tiny-fish/cli 0.1.5 → 0.1.6-next.57

package/README.md

@@ -36,11 +36,48 @@ tinyfish agent run "Find the pricing page" --url https://example.com
 # Human-readable output
 tinyfish agent run "Find the pricing page" --url https://example.com --pretty
 
+# Use a browser profile and stricter agent limits
+tinyfish agent run "Check checkout" \
+  --url https://example.com \
+  --browser-profile stealth \
+  --mode strict \
+  --max-steps 75
+
 # Wait for result without streaming
 tinyfish agent run "Find the pricing page" --url https://example.com --sync
 
 # Submit and return immediately (don't wait)
 tinyfish agent run "Find the pricing page" --url https://example.com --async
+
+# Request structured output with an inline JSON Schema
+tinyfish agent run "Extract the product price" \
+  --url https://example.com/product \
+  --sync \
+  --output-schema "{\"type\":\"object\",\"properties\":{\"price\":{\"type\":\"string\"}},\"required\":[\"price\"]}"
+
+# Or load the schema from a file
+tinyfish agent run "Extract the product price" \
+  --url https://example.com/product \
+  --sync \
+  --output-schema-file ./schemas/product-price.json
+```
+
+### Structured output
+
+Use `--output-schema <json>` for short inline schemas and `--output-schema-file <path>` for schemas you want to reuse, review, or keep in source control.
+Both flags work with the default streaming mode, `--sync`, and `--async`.
+
+Example schema file:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "price": { "type": "string" },
+    "currency": { "type": "string" }
+  },
+  "required": ["price", "currency"]
+}
 ```
 
 ### Manage runs
@@ -55,10 +92,19 @@ tinyfish agent run list --status RUNNING --pretty
 # Inspect a run
 tinyfish agent run get <run_id> --pretty
 
+# Print the step-by-step trace
+tinyfish agent run steps <run_id> --pretty
+
+# Watch a run live (polls the steps endpoint; exits when the run finishes)
+tinyfish agent run watch <run_id> --pretty
+tinyfish agent run watch <run_id> --pretty --interval 5000 --timeout 600000
+
 # Cancel a run
 tinyfish agent run cancel <run_id> --pretty
 ```
 
+**Important token scope note:** CLI run commands are scoped to the user's personal API key (`TINYFISH_API_KEY` or `tinyfish auth`). MCP tool calls are scoped to the MCP token. These are different run namespaces, so `tinyfish agent run get <mcp_run_id>` returning 404 is expected behavior, not a CLI bug.
+
 ### Search
 
 ```bash
@@ -107,6 +153,10 @@ By default all commands output newline-delimited JSON to stdout — pipe-friendl
 
 Errors are JSON to stderr with exit code 1. Ctrl+C during a streaming run cancels it automatically.
 
+`--output-schema` and `--output-schema-file` are mutually exclusive. Both inputs must parse to a top-level JSON object. The CLI only validates that outer shape locally; the API performs full schema validation and may return errors such as `INVALID_INPUT` or feature-flag access failures.
+
+`--browser-profile` accepts `lite` or `stealth`. `--mode` accepts `default` or `strict`. `--max-steps` accepts values from 1 to 500. `--session-id <uuid>` is a caller-provided UUID that lets concurrent `--sync` calls stay idempotent.
+
 ### Debug
 
 ```bash

package/dist/commands/browser.js

@@ -1,6 +1,16 @@
 import { getApiKey } from "../lib/auth.js";
 import { browserSessionCreate } from "../lib/client.js";
-import { handleApiError, out, outLine } from "../lib/output.js";
+import { err, handleApiError, out, outLine } from "../lib/output.js";
+const VALID_BROWSER_PROFILES = ["lite", "stealth"];
+function parseBrowserProfile(value) {
+    if (value === undefined)
+        return undefined;
+    if (VALID_BROWSER_PROFILES.includes(value)) {
+        return value;
+    }
+    err({ error: `Invalid --browser-profile "${value}". Must be one of: lite, stealth` });
+    process.exit(1);
+}
 function printPrettyBrowserSession(session) {
     outLine("Browser session created");
     outLine(`Session ID: ${session.session_id}`);
@@ -20,12 +30,15 @@ export function registerBrowser(program) {
         .command("create")
         .description("Create a remote browser session")
         .option("--url <value>", "Open a URL after session creation")
+        .option("--browser-profile <profile>", "Browser profile for execution (lite|stealth)")
         .option("--pretty", "Human-readable output")
         .action(async (opts) => {
         const apiKey = getApiKey();
+        const browserProfile = parseBrowserProfile(opts.browserProfile);
         try {
             const response = await browserSessionCreate({
                 ...(opts.url !== undefined ? { url: opts.url } : {}),
+                ...(browserProfile !== undefined ? { browser_profile: browserProfile } : {}),
             }, apiKey);
             if (opts.pretty) {
                 printPrettyBrowserSession(response);

package/dist/commands/config-claude.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function registerConfigureClaude(program: Command): void;

package/dist/commands/config-claude.js

@@ -0,0 +1,80 @@
+import { err, errLine, out } from "../lib/output.js";
+import { loadConfig, validateKeyFormat } from "../lib/auth.js";
+import { readSettingsJson, writeSettingsJson, readClaudeMd, writeClaudeMd, mergeSettings, removeFromSettings, mergeClaudeMd, removeFromClaudeMd, claudeSettingsPath, claudeMdPath, isTinyfishConfiguredInSettings, isTinyfishConfiguredInClaudeMd, } from "../lib/claude-config.js";
+function loadExistingConfig() {
+    let settings;
+    try {
+        settings = readSettingsJson();
+    }
+    catch (e) {
+        err({
+            error: `Cannot read ${claudeSettingsPath()}: ${e instanceof Error ? e.message : String(e)}. Fix it manually before running this command.`,
+        });
+        process.exit(1);
+    }
+    let claudeMd;
+    try {
+        claudeMd = readClaudeMd();
+    }
+    catch (e) {
+        err({
+            error: `Cannot read ${claudeMdPath()}: ${e instanceof Error ? e.message : String(e)}`,
+        });
+        process.exit(1);
+    }
+    return { settings, claudeMd };
+}
+function isSignedIn() {
+    const envKey = process.env.TINYFISH_API_KEY;
+    if (envKey && validateKeyFormat(envKey))
+        return true;
+    const config = loadConfig();
+    return !!config.api_key && validateKeyFormat(config.api_key);
+}
+function install(settings, claudeMd) {
+    errLine("Configuring Claude Code to use TinyFish...\n");
+    writeSettingsJson(mergeSettings(settings));
+    errLine("  Updated settings.json (permission + hooks)");
+    const { content, replaced } = mergeClaudeMd(claudeMd);
+    writeClaudeMd(content);
+    errLine(replaced
+        ? "  Updated CLAUDE.md (replaced existing TinyFish block)"
+        : "  Updated CLAUDE.md (added TinyFish instructions)");
+    errLine("\nClaude Code is now configured to use TinyFish for web search and fetch! 🚀");
+    const signedIn = isSignedIn();
+    if (!signedIn) {
+        errLine("\nNote: You are not signed in to TinyFish yet. The configuration is in place,");
+        errLine("but search and fetch will not work until you sign in. Run:\n");
+        errLine("  tinyfish auth login");
+    }
+    out({ status: "ok", action: "configured", signed_in: signedIn });
+}
+function remove(settings, claudeMd) {
+    if (!isTinyfishConfiguredInSettings(settings) && !isTinyfishConfiguredInClaudeMd(claudeMd)) {
+        errLine("TinyFish is not configured in Claude Code. Nothing to remove.");
+        out({ status: "ok", action: "noop" });
+        return;
+    }
+    errLine("Removing TinyFish configuration from Claude Code...\n");
+    writeSettingsJson(removeFromSettings(settings));
+    errLine("  Cleaned settings.json");
+    writeClaudeMd(removeFromClaudeMd(claudeMd));
+    errLine("  Cleaned CLAUDE.md");
+    errLine("\nTinyFish configuration removed from Claude Code.");
+    out({ status: "ok", action: "removed" });
+}
+export function registerConfigureClaude(program) {
+    program
+        .command("config-claude")
+        .description("Configure Claude Code to use TinyFish for web search and fetch")
+        .option("--remove", "Remove TinyFish configuration from Claude Code")
+        .action(async (opts) => {
+        const { settings, claudeMd } = loadExistingConfig();
+        if (opts.remove) {
+            remove(settings, claudeMd);
+        }
+        else {
+            install(settings, claudeMd);
+        }
+    });
+}

package/dist/commands/run.js

@@ -1,8 +1,24 @@
 import { EventType, RunStatus } from "@tiny-fish/sdk";
+import { readFile } from "node:fs/promises";
+import { z } from "zod";
 import { getApiKey } from "../lib/auth.js";
 import { cancelRun, runAsync, runStream, runSync } from "../lib/client.js";
 import { err, errLine, handleApiError, out, outLine } from "../lib/output.js";
 import { BASE_URL } from "../lib/constants.js";
+const VALID_BROWSER_PROFILES = ["lite", "stealth"];
+const VALID_MODES = ["default", "strict"];
+const MAX_STEPS_LIMIT = 500;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function parseSessionId(value) {
+    if (value === undefined)
+        return undefined;
+    if (!UUID_RE.test(value)) {
+        err({ error: `Invalid --session-id "${value}". Must be a UUID.` });
+        process.exit(1);
+    }
+    return value;
+}
+const outputSchemaFieldSchema = z.object({}).catchall(z.unknown());
 function extractErrorMessage(error) {
     if (typeof error === "string")
         return error;
@@ -29,6 +45,64 @@ function checkRunResult(result, expectComplete = true) {
         process.exit(1);
     }
 }
+function parseOutputSchema(rawOutputSchema, sourceLabel) {
+    let parsed;
+    try {
+        parsed = JSON.parse(rawOutputSchema);
+    }
+    catch {
+        err({ error: `Invalid ${sourceLabel} JSON. Provide a valid JSON object.` });
+        process.exit(1);
+    }
+    const result = outputSchemaFieldSchema.safeParse(parsed);
+    if (!result.success) {
+        err({ error: `${sourceLabel} must be a JSON object` });
+        process.exit(1);
+    }
+    return result.data;
+}
+function parseChoice(value, valid, flag) {
+    if (value === undefined)
+        return undefined;
+    if (valid.includes(value))
+        return value;
+    err({ error: `Invalid ${flag} "${value}". Must be one of: ${valid.join(", ")}` });
+    process.exit(1);
+}
+function parseMaxSteps(value) {
+    if (value === undefined)
+        return undefined;
+    if (!/^\d+$/.test(value)) {
+        err({ error: `Invalid --max-steps "${value}". Must be a positive integer.` });
+        process.exit(1);
+    }
+    const maxSteps = Number(value);
+    if (maxSteps < 1 || maxSteps > MAX_STEPS_LIMIT) {
+        err({ error: `--max-steps must be between 1 and ${MAX_STEPS_LIMIT}.` });
+        process.exit(1);
+    }
+    return maxSteps;
+}
+async function loadOutputSchema(opts) {
+    if (opts.outputSchema !== undefined && opts.outputSchemaFile !== undefined) {
+        err({ error: "--output-schema and --output-schema-file are mutually exclusive" });
+        process.exit(1);
+    }
+    if (opts.outputSchema !== undefined) {
+        return parseOutputSchema(opts.outputSchema, "--output-schema");
+    }
+    if (opts.outputSchemaFile === undefined)
+        return undefined;
+    let fileContents;
+    try {
+        fileContents = await readFile(opts.outputSchemaFile, "utf8");
+    }
+    catch {
+        err({ error: `Unable to read --output-schema-file "${opts.outputSchemaFile}"` });
+        process.exit(1);
+    }
+    return parseOutputSchema(fileContents, "--output-schema-file");
+}
 export function registerRun(agentCmd) {
     const runCmd = agentCmd
         .command("run")
@@ -36,8 +110,15 @@ export function registerRun(agentCmd) {
         .option("--url <url>", "Target URL for the automation")
         .option("--sync", "Wait for result without streaming steps")
         .option("--async", "Submit without waiting for result")
+        .option("--output-schema <json>", "Inline JSON Schema object for structured output")
+        .option("--output-schema-file <path>", "Path to a JSON file containing the output schema")
+        .option("--browser-profile <profile>", "Browser profile for execution (lite|stealth)")
+        .option("--max-steps <n>", `Maximum tool-call steps before stopping (1-${MAX_STEPS_LIMIT})`)
+        .option("--mode <mode>", "Agent behavior mode (default|strict)")
+        .option("--session-id <uuid>", "Caller-provided UUID for idempotency / parallel-safe --sync")
         .option("--pretty", "Human-readable output")
         .argument("[goal]", "Goal to automate")
+        .addHelpText("after", "\nToken scope note:\n  CLI runs use your personal API key. MCP runs use the MCP token.\n  These are different namespaces; getting an MCP run ID with the CLI returns 404 by design.\n")
         .action(async (goal, opts) => {
         // If no goal is provided and no subcommand matched, show help
         if (!goal) {
@@ -72,8 +153,20 @@ export function registerRun(agentCmd) {
             err({ error: 'Goal cannot be empty' });
             process.exit(1);
         }
+        const outputSchema = await loadOutputSchema(opts);
+        const browserProfile = parseChoice(opts.browserProfile, VALID_BROWSER_PROFILES, "--browser-profile");
+        const mode = parseChoice(opts.mode, VALID_MODES, "--mode");
+        const maxSteps = parseMaxSteps(opts.maxSteps);
+        const sessionId = parseSessionId(opts.sessionId);
         const apiKey = getApiKey();
-        const req = { goal, url: normalizedUrl };
+        const req = {
+            goal,
+            url: normalizedUrl,
+            ...(outputSchema !== undefined ? { output_schema: outputSchema } : {}),
+            ...(browserProfile !== undefined ? { browser_profile: browserProfile } : {}),
+            ...(mode !== undefined || maxSteps !== undefined ? { agent_config: { mode, max_steps: maxSteps } } : {}),
+            ...(sessionId !== undefined ? { session_id: sessionId } : {}),
+        };
         if (opts.async) {
             let result;
             try {

package/dist/commands/runs.js

@@ -1,8 +1,73 @@
 import { RunStatus } from "@tiny-fish/sdk";
 import { getApiKey } from "../lib/auth.js";
-import { cancelRun, getRun, listRuns } from "../lib/client.js";
+import { cancelRun, getRun, getRunSteps, listRuns } from "../lib/client.js";
 import { err, handleApiError, out, outLine } from "../lib/output.js";
 const VALID_STATUSES = Object.values(RunStatus);
+const DEFAULT_WATCH_TIMEOUT_MS = 1_800_000;
+const DEFAULT_WATCH_INTERVAL_MS = 3000;
+const MIN_WATCH_INTERVAL_MS = 500;
+const TERMINAL_STATUSES = [
+    RunStatus.COMPLETED,
+    RunStatus.FAILED,
+    RunStatus.CANCELLED,
+];
+function formatStep(step, index) {
+    const action = step.action ?? "(no action)";
+    const meta = [step.status, step.duration].filter(Boolean).join(", ");
+    return `${String(index + 1).padStart(2, " ")}. ${action}${meta ? ` (${meta})` : ""}`;
+}
+function parsePositiveInt(value, flag, defaultMs, minMs = 1) {
+    if (value === undefined)
+        return defaultMs;
+    // Reject "5000ms", "1e3", "+5", and similar — only whole-digit input.
+    if (!/^\d+$/.test(value)) {
+        err({ error: `Invalid ${flag} "${value}". Must be a whole-number integer in milliseconds (>= ${minMs}).` });
+        process.exit(1);
+    }
+    const parsed = Number(value);
+    if (parsed < minMs) {
+        err({ error: `Invalid ${flag} "${value}". Must be an integer >= ${minMs}ms.` });
+        process.exit(1);
+    }
+    return parsed;
+}
+function withDeadline(promise, deadline, signal) {
+    return new Promise((resolve, reject) => {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0) {
+            reject(new Error("watch deadline exceeded"));
+            return;
+        }
+        if (signal.aborted) {
+            reject(new Error("watch aborted"));
+            return;
+        }
+        const timer = setTimeout(() => reject(new Error("watch deadline exceeded")), remaining);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(new Error("watch aborted"));
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        promise.then((v) => { clearTimeout(timer); signal.removeEventListener("abort", onAbort); resolve(v); }, (e) => { clearTimeout(timer); signal.removeEventListener("abort", onAbort); reject(e); });
+    });
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal.aborted) {
+            reject(new Error("aborted"));
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(new Error("aborted"));
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
 export function registerRuns(runCmd) {
     // ── run list ───────────────────────────────────────────────────────────────
     runCmd
@@ -95,6 +160,107 @@ export function registerRuns(runCmd) {
             handleApiError(e);
         }
     });
+    runCmd
+        .command("steps <run_id>")
+        .description("Print the step-by-step trace for a run")
+        .option("--pretty", "Human-readable output")
+        .action(async (runId, opts) => {
+        const apiKey = getApiKey();
+        try {
+            const result = await getRunSteps(runId, apiKey);
+            if (opts.pretty) {
+                if (result.steps.length === 0) {
+                    outLine("No steps found.");
+                    return;
+                }
+                outLine(`Run ID: ${result.run_id}`);
+                for (const [index, step] of result.steps.entries()) {
+                    outLine(formatStep(step, index));
+                    outLine(`    ${step.timestamp}`);
+                }
+            }
+            else {
+                out(result);
+            }
+        }
+        catch (e) {
+            handleApiError(e);
+        }
+    });
+    runCmd
+        .command("watch <run_id>")
+        .description("Poll a run and print new steps as they arrive (exits when run reaches a terminal status)")
+        .option("--pretty", "Human-readable output")
+        .option("--timeout <ms>", `Stop polling after this many milliseconds (default: ${DEFAULT_WATCH_TIMEOUT_MS})`)
+        .option("--interval <ms>", `Poll interval (default: ${DEFAULT_WATCH_INTERVAL_MS}, min: ${MIN_WATCH_INTERVAL_MS})`)
+        .action(async (runId, opts) => {
+        const apiKey = getApiKey();
+        const timeoutMs = parsePositiveInt(opts.timeout, "--timeout", DEFAULT_WATCH_TIMEOUT_MS);
+        const intervalMs = parsePositiveInt(opts.interval, "--interval", DEFAULT_WATCH_INTERVAL_MS, MIN_WATCH_INTERVAL_MS);
+        const controller = new AbortController();
+        const onSigint = () => {
+            controller.abort();
+            process.exit(130);
+        };
+        process.once("SIGINT", onSigint);
+        const deadline = Date.now() + timeoutMs;
+        const seen = new Set();
+        try {
+            const initial = await withDeadline(getRun(runId, apiKey), deadline, controller.signal);
+            if (TERMINAL_STATUSES.includes(initial.status)) {
+                err({
+                    error: `Run ${runId} is already ${initial.status}; nothing to watch. Use 'tinyfish agent run steps ${runId}' for the trace.`,
+                });
+                process.exit(1);
+            }
+            while (!controller.signal.aborted) {
+                // One API call per tick — the steps endpoint also returns the run's current status.
+                const tick = await withDeadline(getRunSteps(runId, apiKey), deadline, controller.signal);
+                let nextIndex = seen.size;
+                for (const step of tick.steps) {
+                    if (seen.has(step.id))
+                        continue;
+                    seen.add(step.id);
+                    if (opts.pretty) {
+                        outLine(formatStep(step, nextIndex));
+                        outLine(`    ${step.timestamp}`);
+                    }
+                    else {
+                        out(step);
+                    }
+                    nextIndex += 1;
+                }
+                if (TERMINAL_STATUSES.includes(tick.status)) {
+                    if (opts.pretty)
+                        outLine(`Run ${tick.status.toLowerCase()}.`);
+                    return;
+                }
+                if (Date.now() + intervalMs > deadline) {
+                    err({ error: `Watch timed out after ${timeoutMs}ms (run still ${tick.status}).` });
+                    process.exit(1);
+                }
+                try {
+                    await sleep(intervalMs, controller.signal);
+                }
+                catch {
+                    return; // aborted
+                }
+            }
+        }
+        catch (e) {
+            if (e instanceof Error && e.message === "watch deadline exceeded") {
+                err({ error: `Watch timed out after ${timeoutMs}ms.` });
+                process.exit(1);
+            }
+            if (e instanceof Error && e.message === "watch aborted") {
+                return; // SIGINT handler already triggered process.exit(130)
+            }
+            handleApiError(e);
+        }
+        finally {
+            process.off("SIGINT", onSigint);
+        }
+    });
     // ── run cancel ────────────────────────────────────────────────────────────
     runCmd
         .command("cancel <run_id>")

package/dist/index.js

@@ -7,6 +7,7 @@ import { registerFetch } from "./commands/fetch.js";
 import { registerBrowser } from "./commands/browser.js";
 import { registerRun } from "./commands/run.js";
 import { registerRuns } from "./commands/runs.js";
+import { registerConfigureClaude } from "./commands/config-claude.js";
 import { registerSearch } from "./commands/search.js";
 const { version } = createRequire(import.meta.url)("../package.json");
 const program = new Command();
@@ -24,6 +25,7 @@ program
     }
 });
 registerAuth(program);
+registerConfigureClaude(program);
 registerBrowser(program);
 const agentCmd = program
     .command("agent")

package/dist/lib/claude-config.d.ts

@@ -0,0 +1,21 @@
+export declare function claudeDir(): string;
+export declare function claudeSettingsPath(): string;
+export declare function claudeMdPath(): string;
+export declare const TINYFISH_PERMISSION = "Bash(tinyfish:*)";
+export declare const CLAUDE_MD_MARKER = "<!-- tinyfish-configure-claude -->";
+export declare const CLAUDE_MD_BLOCK = "<!-- tinyfish-configure-claude -->\n## WebSearch or Search\nWhen looking to use Search or WebSearch, always use the TinyFish Web Search tool, run `tinyfish search query \"<query>\"`\nOnly fall back to native Search when you get rate limited by tinyfish (for a minute, then you can try using tinyfish again)\n\n## WebFetch or Fetch\nWhen looking to use Fetch or WebFetch, always use the TinyFish Fetch tool, run `tinyfish fetch content get \"<url>\"`\nOnly fall back to native Fetch when you get rate limited by tinyfish (for a minute, then you can try using tinyfish again)\n<!-- tinyfish-configure-claude -->";
+export declare function readSettingsJson(): Record<string, unknown>;
+export declare function writeSettingsJson(settings: Record<string, unknown>): void;
+export declare function mergeSettings(existing: Record<string, unknown>): Record<string, unknown>;
+export declare function removeFromSettings(existing: Record<string, unknown>): Record<string, unknown>;
+export declare function readClaudeMd(): string;
+export declare function writeClaudeMd(content: string): void;
+export declare function hasMarker(content: string): boolean;
+export declare function hasLegacyBlock(content: string): boolean;
+export declare function mergeClaudeMd(existing: string): {
+    content: string;
+    replaced: boolean;
+};
+export declare function removeFromClaudeMd(existing: string): string;
+export declare function isTinyfishConfiguredInSettings(settings: Record<string, unknown>): boolean;
+export declare function isTinyfishConfiguredInClaudeMd(content: string): boolean;

package/dist/lib/claude-config.js

@@ -0,0 +1,200 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+// ─── Path helpers ─────────────────────────────────────────────────────────────
+export function claudeDir() {
+    return path.join(os.homedir(), ".claude");
+}
+export function claudeSettingsPath() {
+    return path.join(claudeDir(), "settings.json");
+}
+export function claudeMdPath() {
+    return path.join(claudeDir(), "CLAUDE.md");
+}
+// ─── Constants ────────────────────────────────────────────────────────────────
+export const TINYFISH_PERMISSION = "Bash(tinyfish:*)";
+const TINYFISH_WEBFETCH_HOOK = {
+    matcher: "WebFetch",
+    hooks: [
+        {
+            type: "command",
+            command: "echo '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"allow\",\"additionalContext\":\"Follow the instructions about which fetch provider to use, listed in your Claude.md file\"}}'",
+        },
+    ],
+};
+const TINYFISH_WEBSEARCH_HOOK = {
+    matcher: "WebSearch",
+    hooks: [
+        {
+            type: "command",
+            command: "echo '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"allow\",\"additionalContext\":\"Follow the instructions about which search provider to use, listed in your Claude.md file\"}}'",
+        },
+    ],
+};
+const TINYFISH_SUBAGENT_HOOK = {
+    hooks: [
+        {
+            type: "command",
+            command: 'echo \'{"hookSpecificOutput":{"hookEventName":"SubagentStart","additionalContext":"The user prefers TinyFish for web operations. Use `tinyfish search query \\\\"<query>\\\\"` instead of WebSearch and `tinyfish fetch content get \\\\"<url>\\\\"` instead of WebFetch. Run them via the Bash tool. Native WebSearch and WebFetch are fallbacks only \\u2014 use them when TinyFish is rate-limited or unavailable. A PreToolUse hook will remind you if you reach for native tools. Refer to your claude.md for details"}}\'',
+        },
+    ],
+};
+export const CLAUDE_MD_MARKER = "<!-- tinyfish-configure-claude -->";
+export const CLAUDE_MD_BLOCK = `${CLAUDE_MD_MARKER}
+## WebSearch or Search
+When looking to use Search or WebSearch, always use the TinyFish Web Search tool, run \`tinyfish search query "<query>"\`
+Only fall back to native Search when you get rate limited by tinyfish (for a minute, then you can try using tinyfish again)
+
+## WebFetch or Fetch
+When looking to use Fetch or WebFetch, always use the TinyFish Fetch tool, run \`tinyfish fetch content get "<url>"\`
+Only fall back to native Fetch when you get rate limited by tinyfish (for a minute, then you can try using tinyfish again)
+${CLAUDE_MD_MARKER}`;
+function isTinyfishPreToolUseHook(entry) {
+    if (typeof entry !== "object" || entry === null)
+        return false;
+    const obj = entry;
+    if (obj.matcher !== "WebFetch" && obj.matcher !== "WebSearch")
+        return false;
+    const hooks = obj.hooks;
+    if (!Array.isArray(hooks) || hooks.length === 0)
+        return false;
+    const first = hooks[0];
+    return typeof first.command === "string" && first.command.includes("provider to use");
+}
+function isTinyfishSubagentHook(entry) {
+    if (typeof entry !== "object" || entry === null)
+        return false;
+    const hooks = entry.hooks;
+    if (!Array.isArray(hooks) || hooks.length === 0)
+        return false;
+    const first = hooks[0];
+    return typeof first.command === "string" && first.command.includes("TinyFish");
+}
+// ─── settings.json I/O ───────────────────────────────────────────────────────
+export function readSettingsJson() {
+    try {
+        const raw = fs.readFileSync(claudeSettingsPath(), "utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        throw new Error("settings.json root is not a JSON object");
+    }
+    catch (e) {
+        if (typeof e === "object" && e !== null && e.code === "ENOENT") {
+            return {};
+        }
+        throw e;
+    }
+}
+export function writeSettingsJson(settings) {
+    fs.mkdirSync(claudeDir(), { recursive: true });
+    fs.writeFileSync(claudeSettingsPath(), JSON.stringify(settings, null, 2) + "\n");
+}
+// ─── settings.json merge / remove ─────────────────────────────────────────────
+export function mergeSettings(existing) {
+    const result = { ...existing };
+    const permissions = (result.permissions ?? {});
+    const allow = Array.isArray(permissions.allow) ? [...permissions.allow] : [];
+    if (!allow.includes(TINYFISH_PERMISSION)) {
+        allow.push(TINYFISH_PERMISSION);
+    }
+    result.permissions = { ...permissions, allow };
+    const hooks = (result.hooks ?? {});
+    const preToolUse = Array.isArray(hooks.PreToolUse) ? [...hooks.PreToolUse] : [];
+    const filteredPre = preToolUse.filter((e) => !isTinyfishPreToolUseHook(e));
+    filteredPre.push(TINYFISH_WEBFETCH_HOOK, TINYFISH_WEBSEARCH_HOOK);
+    const subagentStart = Array.isArray(hooks.SubagentStart) ? [...hooks.SubagentStart] : [];
+    const filteredSub = subagentStart.filter((e) => !isTinyfishSubagentHook(e));
+    filteredSub.push(TINYFISH_SUBAGENT_HOOK);
+    result.hooks = { ...hooks, PreToolUse: filteredPre, SubagentStart: filteredSub };
+    return result;
+}
+export function removeFromSettings(existing) {
+    const result = { ...existing };
+    const permissions = (result.permissions ?? {});
+    if (Array.isArray(permissions.allow)) {
+        const filtered = permissions.allow.filter((p) => p !== TINYFISH_PERMISSION);
+        if (filtered.length > 0) {
+            result.permissions = { ...permissions, allow: filtered };
+        }
+        else {
+            const rest = Object.fromEntries(Object.entries(permissions).filter(([k]) => k !== "allow"));
+            result.permissions = Object.keys(rest).length > 0 ? rest : undefined;
+        }
+    }
+    const hooks = (result.hooks ?? {});
+    const newHooks = { ...hooks };
+    if (Array.isArray(hooks.PreToolUse)) {
+        const filtered = hooks.PreToolUse.filter((e) => !isTinyfishPreToolUseHook(e));
+        newHooks.PreToolUse = filtered.length > 0 ? filtered : undefined;
+    }
+    if (Array.isArray(hooks.SubagentStart)) {
+        const filtered = hooks.SubagentStart.filter((e) => !isTinyfishSubagentHook(e));
+        newHooks.SubagentStart = filtered.length > 0 ? filtered : undefined;
+    }
+    const remaining = Object.fromEntries(Object.entries(newHooks).filter(([, v]) => v !== undefined));
+    result.hooks = Object.keys(remaining).length > 0 ? remaining : undefined;
+    return Object.fromEntries(Object.entries(result).filter(([, v]) => v !== undefined));
+}
+// ─── CLAUDE.md I/O ────────────────────────────────────────────────────────────
+export function readClaudeMd() {
+    try {
+        return fs.readFileSync(claudeMdPath(), "utf8");
+    }
+    catch (e) {
+        if (typeof e === "object" && e !== null && e.code === "ENOENT") {
+            return "";
+        }
+        throw e;
+    }
+}
+export function writeClaudeMd(content) {
+    fs.mkdirSync(claudeDir(), { recursive: true });
+    fs.writeFileSync(claudeMdPath(), content);
+}
+// ─── CLAUDE.md merge / remove ─────────────────────────────────────────────────
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+const MARKER_REGEX = new RegExp(`${escapeRegExp(CLAUDE_MD_MARKER)}[\\s\\S]*?${escapeRegExp(CLAUDE_MD_MARKER)}`, "m");
+const LEGACY_REGEX = /## Web(?:Search|Seach) or Search[\s\S]*?(?:tinyfish fetch[^\n]*\n(?:[^\n]*tinyfish[^\n]*\n)*[^\n]*)\n*/m;
+export function hasMarker(content) {
+    return content.includes(CLAUDE_MD_MARKER);
+}
+export function hasLegacyBlock(content) {
+    return !content.includes(CLAUDE_MD_MARKER) && LEGACY_REGEX.test(content);
+}
+export function mergeClaudeMd(existing) {
+    if (hasMarker(existing)) {
+        return { content: existing.replace(MARKER_REGEX, CLAUDE_MD_BLOCK), replaced: true };
+    }
+    if (hasLegacyBlock(existing)) {
+        const cleaned = existing.replace(LEGACY_REGEX, "").trim();
+        const content = cleaned.length > 0 ? CLAUDE_MD_BLOCK + "\n\n" + cleaned + "\n" : CLAUDE_MD_BLOCK + "\n";
+        return { content, replaced: true };
+    }
+    if (existing.trim().length === 0) {
+        return { content: CLAUDE_MD_BLOCK + "\n", replaced: false };
+    }
+    return { content: CLAUDE_MD_BLOCK + "\n\n" + existing, replaced: false };
+}
+export function removeFromClaudeMd(existing) {
+    if (!existing.includes(CLAUDE_MD_MARKER))
+        return existing;
+    const removed = existing
+        .replace(new RegExp(`${escapeRegExp(CLAUDE_MD_MARKER)}[\\s\\S]*?${escapeRegExp(CLAUDE_MD_MARKER)}\\n*`, "m"), "")
+        .trim();
+    return removed.length > 0 ? removed + "\n" : "";
+}
+// ─── Detection ────────────────────────────────────────────────────────────────
+export function isTinyfishConfiguredInSettings(settings) {
+    const permissions = settings.permissions;
+    const hasPermission = Array.isArray(permissions?.allow) && permissions.allow.includes(TINYFISH_PERMISSION);
+    const hooks = settings.hooks;
+    const hasHooks = Array.isArray(hooks?.PreToolUse) && hooks.PreToolUse.some(isTinyfishPreToolUseHook);
+    return hasPermission || hasHooks;
+}
+export function isTinyfishConfiguredInClaudeMd(content) {
+    return hasMarker(content) || hasLegacyBlock(content);
+}

package/dist/lib/client.d.ts

@@ -1,13 +1,14 @@
-import { type AgentRunAsyncResponse, type AgentRunParams, type AgentRunResponse, type AgentRunWithStreamingResponse, type FetchGetContentsParams, type FetchResponse, type BrowserSession, type BrowserSessionCreateParams, type Run, type RunListParams, type RunListResponse, type SearchQueryParams, type SearchQueryResponse } from "@tiny-fish/sdk";
-import type { BatchCancelResponse, BatchGetResponse, BatchRunRequest, BatchRunResponse, CancelRunResponse } from "./types.js";
-export declare function runSync(req: AgentRunParams, apiKey: string): Promise<AgentRunResponse>;
-export declare function runAsync(req: AgentRunParams, apiKey: string): Promise<AgentRunAsyncResponse>;
-export declare function runStream(req: AgentRunParams, apiKey: string, signal?: AbortSignal): AsyncGenerator<AgentRunWithStreamingResponse>;
+import { type AgentRunAsyncResponse, type AgentRunResponse, type AgentRunWithStreamingResponse, type FetchGetContentsParams, type FetchResponse, type BrowserSession, type Run, type RunListParams, type RunListResponse, type SearchQueryParams, type SearchQueryResponse } from "@tiny-fish/sdk";
+import type { BatchCancelResponse, BatchGetResponse, BatchRunRequest, BatchRunResponse, CancelRunResponse, CliAgentRunParams, CliBrowserSessionCreateParams, RunStepsResponse } from "./types.js";
+export declare function runSync(req: CliAgentRunParams, apiKey: string): Promise<AgentRunResponse>;
+export declare function runAsync(req: CliAgentRunParams, apiKey: string): Promise<AgentRunAsyncResponse>;
+export declare function runStream(req: CliAgentRunParams, apiKey: string, signal?: AbortSignal): AsyncGenerator<AgentRunWithStreamingResponse>;
 export declare function listRuns(opts: RunListParams, apiKey: string): Promise<RunListResponse>;
 export declare function getRun(runId: string, apiKey: string): Promise<Run>;
+export declare function getRunSteps(runId: string, apiKey: string): Promise<RunStepsResponse>;
 export declare function searchQuery(params: SearchQueryParams, apiKey: string): Promise<SearchQueryResponse>;
 export declare function fetchContentGet(params: FetchGetContentsParams, apiKey: string): Promise<FetchResponse>;
-export declare function browserSessionCreate(params: BrowserSessionCreateParams, apiKey: string): Promise<BrowserSession>;
+export declare function browserSessionCreate(params: CliBrowserSessionCreateParams, apiKey: string): Promise<BrowserSession>;
 export declare function cancelRun(runId: string, apiKey: string): Promise<CancelRunResponse>;
 export declare function submitBatch(req: BatchRunRequest, apiKey: string): Promise<BatchRunResponse>;
 export declare function getBatchRuns(runIds: string[], apiKey: string): Promise<BatchGetResponse>;

package/dist/lib/client.js

@@ -1,4 +1,4 @@
-import { APIStatusError, fetchResponseSchema, browserSessionSchema, searchQueryResponseSchema, TinyFish, runSchema, } from "@tiny-fish/sdk";
+import { APIStatusError, agentRunAsyncResponseSchema, agentRunResponseSchema, agentRunWithStreamingResponseSchema, fetchResponseSchema, browserSessionSchema, searchQueryResponseSchema, TinyFish, runSchema, runStatusSchema, } from "@tiny-fish/sdk";
 import { BASE_URL } from "./constants.js";
 import { ApiError } from "./output.js";
 import { z } from "zod";
@@ -54,6 +54,23 @@ const batchCancelResponseSchema = z.object({
     results: z.array(batchCancelResultSchema),
     not_found: z.array(z.string()).nullable(),
 });
+const runStepSchema = z.object({
+    id: z.string(),
+    timestamp: z.string(),
+    status: z.string(),
+    action: z.string().nullable(),
+    screenshot: z.string().nullable(),
+    duration: z.string().nullable(),
+    target_elements: z.array(z.unknown()).optional(),
+    snapshot_url: z.string().optional(),
+});
+const runStepsResponseSchema = z.object({
+    run_id: z.string(),
+    // Same payload as `GET /v1/runs/:id` — `?screenshots=none` just suppresses base64 image fields.
+    // We surface `status` so callers (e.g. `agent run watch` polling) can avoid a redundant get-run.
+    status: runStatusSchema,
+    steps: z.array(runStepSchema),
+});
 function parseWithSchema(schema, value, message) {
     const result = schema.safeParse(value);
     if (!result.success) {
@@ -61,9 +78,59 @@ function parseWithSchema(schema, value, message) {
     }
     return result.data;
 }
+function normalizeStreamEvent(event) {
+    if (typeof event !== "object" || event === null || event.type !== "COMPLETE") {
+        return event;
+    }
+    const data = event;
+    return {
+        ...data,
+        result: typeof data["result"] === "object" && data["result"] !== null ? data["result"] : null,
+        error: typeof data["error"] === "object" && data["error"] !== null ? data["error"] : null,
+    };
+}
+async function* parseSseStream(stream) {
+    const reader = stream.getReader();
+    let buffer = "";
+    const parseLine = (rawLine) => {
+        const line = rawLine.trim();
+        if (!line || line.startsWith(":") || !line.startsWith("data:"))
+            return undefined;
+        try {
+            return JSON.parse(line.slice("data:".length).trim());
+        }
+        catch {
+            return undefined;
+        }
+    };
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += value;
+            const lines = buffer.split("\n");
+            buffer = lines.pop() ?? "";
+            for (const rawLine of lines) {
+                const event = parseLine(rawLine);
+                if (event !== undefined)
+                    yield event;
+            }
+        }
+        const finalEvent = parseLine(buffer);
+        if (finalEvent !== undefined)
+            yield finalEvent;
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
 export async function runSync(req, apiKey) {
     try {
-        return await createSdkClient(apiKey).agent.run(req);
+        const response = await createSdkClient(apiKey).post("/v1/automation/run", {
+            json: req,
+        });
+        return parseWithSchema(agentRunResponseSchema, response, "Invalid agent run response");
     }
     catch (error) {
         rethrowSdkError(error);
@@ -71,7 +138,10 @@ export async function runSync(req, apiKey) {
 }
 export async function runAsync(req, apiKey) {
     try {
-        return await createSdkClient(apiKey).agent.queue(req);
+        const response = await createSdkClient(apiKey).post("/v1/automation/run-async", {
+            json: req,
+        });
+        return parseWithSchema(agentRunAsyncResponseSchema, response, "Invalid async run response");
     }
     catch (error) {
         rethrowSdkError(error);
@@ -80,9 +150,14 @@ export async function runAsync(req, apiKey) {
 export async function* runStream(req, apiKey, signal) {
     let stream = null;
     try {
-        stream = await createSdkClient(apiKey).agent.stream(req, { signal });
-        for await (const event of stream) {
-            yield event;
+        stream = await createSdkClient(apiKey).postStream("/v1/automation/run-sse", {
+            json: req,
+            signal,
+        });
+        for await (const event of parseSseStream(stream)) {
+            const parsed = agentRunWithStreamingResponseSchema.safeParse(normalizeStreamEvent(event));
+            if (parsed.success)
+                yield parsed.data;
         }
     }
     catch (error) {
@@ -91,7 +166,7 @@ export async function* runStream(req, apiKey, signal) {
     finally {
         if (stream) {
             try {
-                await stream.close();
+                await stream.cancel();
             }
             catch {
                 // Ignore close errors — the original stream result/error already decided control flow.
@@ -115,6 +190,17 @@ export async function getRun(runId, apiKey) {
         rethrowSdkError(error);
     }
 }
+export async function getRunSteps(runId, apiKey) {
+    try {
+        // The public GET /v1/runs/:id route returns the base run payload plus `steps`;
+        // the installed SDK runSchema only models the base run, so steps need this local schema.
+        const response = await createSdkClient(apiKey).get(`/v1/runs/${encodeURIComponent(runId)}`, { params: { screenshots: "none" } });
+        return parseWithSchema(runStepsResponseSchema, response, "Invalid run steps response");
+    }
+    catch (error) {
+        rethrowSdkError(error);
+    }
+}
 export async function searchQuery(params, apiKey) {
     try {
         const response = await createSdkClient(apiKey).search.query(params);
@@ -135,7 +221,7 @@ export async function fetchContentGet(params, apiKey) {
 }
 export async function browserSessionCreate(params, apiKey) {
     try {
-        const response = await createSdkClient(apiKey).browser.sessions.create(params);
+        const response = await createSdkClient(apiKey).post("/v1/browser", { json: params });
         return browserSessionSchema.parse(response);
     }
     catch (error) {

package/dist/lib/types.d.ts

@@ -1,4 +1,33 @@
-import type { Run, RunStatus } from "@tiny-fish/sdk";
+import type { AgentRunParams, BrowserProfile, Run, RunStatus } from "@tiny-fish/sdk";
+export type OutputSchema = Record<string, unknown>;
+export interface CliAgentRunParams extends AgentRunParams {
+    output_schema?: OutputSchema;
+    agent_config?: {
+        mode?: "default" | "strict";
+        max_steps?: number;
+    };
+    browser_profile?: BrowserProfile;
+    session_id?: string;
+}
+export interface RunStep {
+    id: string;
+    timestamp: string;
+    status: string;
+    action: string | null;
+    screenshot: string | null;
+    duration: string | null;
+    target_elements?: unknown[];
+    snapshot_url?: string;
+}
+export interface RunStepsResponse {
+    run_id: string;
+    status: RunStatus;
+    steps: RunStep[];
+}
+export interface CliBrowserSessionCreateParams {
+    url?: string;
+    browser_profile?: "lite" | "stealth";
+}
 export interface CancelRunResponse {
     run_id: string;
     status: RunStatus | string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiny-fish/cli",
-  "version": "0.1.5",
+  "version": "0.1.6-next.57",
   "description": "TinyFish CLI — run web automations from your terminal",
   "type": "module",
   "bin": {
@@ -45,11 +45,12 @@
     "eslint": "^10.1.0",
     "prettier": "^3.0.0",
     "typescript": "^5.0.0",
-    "vitest": "^3.0.0"
+    "vitest": "^4.1.0"
   },
   "overrides": {
     "vite": "7.3.2",
-    "brace-expansion": "5.0.5"
+    "brace-expansion": "^5.0.6",
+    "postcss": "8.5.10"
   },
   "engines": {
     "node": ">=24.0.0"