@tiny-fish/cli 0.50.2-next.407 → 0.51.0

package/README.md

@@ -454,3 +454,11 @@ TinyFish-owned origins (`*.tinyfish.ai`, `*.tinyfish.io`) or a local development
       --sync \
       --pretty
 ```
+
+### Research
+
+`tinyfish research run "question"` streams JSON events; `--async` returns a durable `research_run_id`. Use `--mode max` for deeper research with a larger budget; slower and costs more (default: deep), `--language ja`, or `--pretty` for readable output.
+
+Manage runs with `tinyfish research run get <id>`, `list`, `watch <id>`, and `cancel <id>`. `get` includes partial/final reports; `list` supports `--status`, `--query`, `--limit`, `--cursor`, and `--sort-direction`. `watch --timeout <ms>` replays saved events and waits up to 45 minutes by default.
+
+Ctrl+C during a streamed start requests cancellation with a five-second timeout; during watch it only detaches. JSON output stays on stdout; recovery hints go to stderr. Failed, cancelled, timed-out, and incomplete streams exit unsuccessfully. Starts are not retried automatically: if no ID arrives, check `list` before submitting again.

package/dist/commands/research.d.ts

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

package/dist/commands/research.js

@@ -0,0 +1,181 @@
+import { Option } from 'commander';
+import { withResolvedKey } from '../lib/auth.js';
+import * as api from '../lib/client.js';
+import { integerInRange } from '../lib/list-options.js';
+import { ApiError, errLine, handleApiError, out, outLine } from '../lib/output.js';
+import * as research from '../lib/research.js';
+import { installSignalGuard, onBrokenPipe } from '../lib/signals.js';
+const runLine = (run) => `${run.research_run_id}  ${run.status}  ${run.query}`;
+function printReport(report) {
+    outLine(report.result);
+    report.citations.forEach((url, index) => outLine(`[${index + 1}] ${url}`));
+}
+function printRun(run, pretty) {
+    if (!pretty)
+        return out(run);
+    outLine(runLine(run));
+    if (run.deep_result)
+        printReport(run.deep_result);
+}
+async function observe(input, apiKey, pretty, timeout = research.RESEARCH_TIMEOUT_MS) {
+    const started = typeof input !== 'string';
+    let runId = started ? undefined : input;
+    // Guard exits 130 once the handler settles.
+    const uninstall = installSignalGuard(() => interrupted(started, runId, apiKey));
+    const removePipeHandler = onBrokenPipe(() => interrupted(started, runId, apiKey));
+    try {
+        let done = false;
+        for await (const event of api.researchStream(input, apiKey, AbortSignal.timeout(timeout))) {
+            if (event.event === 'created') {
+                runId = event.research_run_id;
+                errLine(`Research ID: ${runId}`);
+            }
+            renderEvent(event, pretty);
+            if (event.event === 'done') {
+                done = true;
+                break;
+            }
+        }
+        if (!done || !runId)
+            throw new Error('Research stream ended before completion');
+        const result = await api.getResearch(runId, apiKey);
+        if (result.status !== 'COMPLETED') {
+            printRun(result, pretty);
+            throw new Error(`Research ${result.status}: ${result.error?.message ?? runId}`);
+        }
+    }
+    catch (error) {
+        recoveryHint(error, started, runId);
+        throw error;
+    }
+    finally {
+        uninstall();
+        removePipeHandler();
+    }
+}
+// Fields per event: internal-docs/sse-research-events.md.
+const PROGRESS = {
+    run_status: ['status'],
+    session: ['session_id'],
+    plan_updated: ['iteration', 'subquestions', 'search_queries'],
+    sources_searched: ['candidates'],
+    sources_fetching: ['urls'],
+    source_fetched: ['status', 'url'],
+    partial_summary: ['citations'],
+    evidence_snapshot: ['evidence'],
+    run_stats: ['stats'],
+};
+function field(key, value) {
+    if (Array.isArray(value))
+        return [`${value.length} ${key}`];
+    if (typeof value === 'number')
+        return [`${key} ${value}`];
+    if (typeof value === 'string')
+        return [value];
+    if (typeof value !== 'object' || !value)
+        return [];
+    return Object.entries(value).flatMap(([k, v]) => (typeof v === 'number' ? field(k, v) : []));
+}
+function renderEvent(event, pretty) {
+    if (!pretty)
+        return out(event);
+    if (event.event === 'final_result')
+        return printReport(research.reportSchema.parse(event));
+    if (event.event === 'heartbeat')
+        return;
+    const detail = (PROGRESS[event.event] ?? ['message']).flatMap((key) => field(key, event[key]));
+    errLine(detail.length ? `${event.event}: ${detail.join(', ')}` : event.event);
+}
+function recoveryHint(error, started, runId) {
+    // A 4xx before creation means no run exists.
+    if (error instanceof ApiError && error.status < 500 && !(started && runId))
+        return;
+    errLine(`Check tinyfish research run ${runId ? `get ${runId}` : 'list before starting again'}.`);
+}
+async function interrupted(started, id, apiKey) {
+    if (!id)
+        return errLine('No research ID received. Check tinyfish research run list.');
+    if (!started)
+        return;
+    try {
+        errLine(`Research ${(await api.cancelResearch(id, apiKey)).status}.`);
+    }
+    catch {
+        errLine(`Cancellation unconfirmed. Use tinyfish research run cancel ${id}.`);
+    }
+}
+const shellQuote = (value) => `'${value.replaceAll("'", `'\\''`)}'`;
+// The cursor is only valid with the filters that produced it.
+function nextPageFlags(opts, cursor) {
+    const flags = [
+        ['--status', opts.status],
+        ['--query', opts.query === undefined ? undefined : shellQuote(opts.query)],
+        ['--limit', opts.limit],
+        ['--sort-direction', opts.sortDirection],
+        ['--cursor', cursor],
+    ];
+    return flags
+        .flatMap(([flag, value]) => (value === undefined ? [] : [`${flag} ${value}`]))
+        .join(' ');
+}
+function start(query, opts) {
+    if (!query?.trim())
+        handleApiError(new Error('query required'));
+    return withResolvedKey(async (apiKey) => {
+        const request = api.parseWithSchema(research.requestSchema, { query, mode: opts.mode, output_language: opts.language }, 'Invalid research request');
+        if (!opts.async)
+            return observe(request, apiKey, opts.pretty);
+        const result = await api.startResearchAsync(request, apiKey);
+        if (opts.pretty)
+            outLine(result.research_run_id);
+        else
+            out(result);
+        if (result.error)
+            throw new Error(result.error.message);
+    });
+}
+export function registerResearch(program) {
+    const group = program
+        .command('research')
+        .description('Research reports')
+        .enablePositionalOptions();
+    const run = group
+        .command('run')
+        .description('Start research or manage runs')
+        .argument('[query]', 'Research question; a lone subcommand name runs that subcommand')
+        .option('--async', 'Submit without waiting for the report')
+        .addOption(new Option('--mode <mode>', 'deep (default) | max: deeper research with a larger budget; slower and costs more').choices(research.requestSchema.shape.mode.unwrap().options))
+        .option('--language <tag>', 'Report language (BCP 47)')
+        .option('--pretty', 'Human-readable output')
+        .addHelpText('after', '\nCtrl+C cancels a started run; watch only detaches.')
+        .action(start);
+    const command = (name, description) => run.command(name).description(description).option('--pretty', 'Human-readable output');
+    command('get <id>', 'Get status and partial or final results').action((id, opts) => withResolvedKey(async (apiKey) => printRun(await api.getResearch(id, apiKey), opts.pretty)));
+    command('cancel <id>', 'Cancel research; safe to repeat').action((id, opts) => withResolvedKey(async (apiKey) => {
+        const result = await api.cancelResearch(id, apiKey);
+        if (!opts.pretty)
+            return out(result);
+        outLine(`${result.research_run_id}  ${result.status}${result.cancelled ? '' : ' (unchanged)'}`);
+    }));
+    command('list', 'List research runs')
+        .addOption(new Option('--status <status>', 'Run status').choices(research.statusSchema.options))
+        .option('--query <text>', 'Filter by query text')
+        .option('--limit <n>', 'Maximum runs (1-100; default: 20)', integerInRange(1, 100))
+        .option('--cursor <cursor>', 'Pagination cursor from a previous response')
+        .addOption(new Option('--sort-direction <direction>', 'Creation order (default: desc)').choices(research.listQuerySchema.shape.sort_direction.unwrap().options))
+        .action((opts) => withResolvedKey(async (apiKey) => {
+        const { pretty, sortDirection, ...filters } = opts;
+        const query = api.parseWithSchema(research.listQuerySchema, { ...filters, sort_direction: sortDirection }, 'Invalid list filters');
+        const result = await api.listResearch(query, apiKey);
+        if (!pretty)
+            return out(result);
+        if (result.data.length === 0)
+            outLine('No research runs.');
+        result.data.forEach((item) => outLine(runLine(item)));
+        if (result.pagination.next_cursor)
+            outLine(`Next: ${nextPageFlags(opts, result.pagination.next_cursor)}`);
+    }));
+    command('watch <id>', 'Replay and stream an existing run; Ctrl+C detaches')
+        .option('--timeout <ms>', 'Maximum watch duration in milliseconds', integerInRange(1, 2147483647), research.RESEARCH_TIMEOUT_MS)
+        .action((id, opts) => withResolvedKey((apiKey) => observe(api.parseResearchId(id), apiKey, opts.pretty, opts.timeout)));
+}

package/dist/index.js

@@ -1,5 +1,12 @@
 #!/usr/bin/env node
 import { buildProgram } from './program.js';
+import { handleBrokenPipe } from './lib/signals.js';
+// A reader closing early (`| head`) is not an error.
+process.stdout.on('error', (error) => {
+    if (error.code !== 'EPIPE')
+        throw error;
+    handleBrokenPipe();
+});
 // Await parseAsync so async command handlers complete before the process exits
 buildProgram()
     .then(({ program }) => program.parseAsync(process.argv))

package/dist/lib/client.d.ts

@@ -2,12 +2,14 @@ import { type AgentRunAsyncResponse, type AgentRunResponse, type AgentRunWithStr
 import type { PageParams } from './list-options.js';
 import type { BatchCancelResponse, BatchGetResponse, BatchRunRequest, BatchRunResponse, CancelRunResponse, CliAgentRunParams, CliBrowserSessionCreateParams, CookieRecord, ProfileCreateResponse, ProfileSummary, ProfileUploadResponse, RunStepsResponse, VaultConnectRequest, VaultConnectResponse, VaultConnectionsListResponse, VaultDisconnectResponse, VaultItemsListResponse, VaultItemsSyncResponse } from './types.js';
 import { z } from 'zod';
+import * as research from './research.js';
 type ConnectMap = Record<string, {
     attempt_id: string;
 }> | undefined;
 export declare function buildConnectHeaders(connect: ConnectMap, caller: string | null): Record<string, string>;
 export declare function setupPageConnectHeaders(attemptId: string | undefined): Record<string, string>;
 export declare function resolveClientName(env?: Record<string, string | undefined>): string;
+export declare function parseWithSchema<T>(schema: z.ZodType<T>, value: unknown, message: string): T;
 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, onDropped?: (count: number) => void): AsyncGenerator<AgentRunWithStreamingResponse>;
@@ -137,4 +139,76 @@ export declare function vaultConnect(req: VaultConnectRequest, apiKey: string):
 export declare function vaultDisconnect(connectionId: string, apiKey: string): Promise<VaultDisconnectResponse>;
 export declare function vaultItems(apiKey: string): Promise<VaultItemsListResponse>;
 export declare function vaultSync(apiKey: string): Promise<VaultItemsSyncResponse>;
+export declare const parseResearchId: (id: string) => string;
+export declare function startResearchAsync(req: research.Request, apiKey: string): Promise<{
+    [x: string]: unknown;
+    research_run_id: string;
+    error: {
+        code: string;
+        message: string;
+    } | null;
+}>;
+export declare function getResearch(id: string, apiKey: string): Promise<{
+    [x: string]: unknown;
+    research_run_id: string;
+    status: "RUNNING" | "COMPLETED" | "FAILED" | "CANCELLED" | "QUEUED" | "TIMED_OUT";
+    query: string;
+    quick_result: {
+        [x: string]: unknown;
+        answer: string;
+        citations: string[];
+    } | null;
+    quick_result_summary: string | null;
+    deep_result: {
+        [x: string]: unknown;
+        result: string;
+        citations: string[];
+    } | null;
+    run_ids: string[];
+    created_at: string | null;
+    completed_at: string | null;
+    error: {
+        code: string;
+        message: string;
+    } | null;
+    research_plan: z.core.util.JSONType;
+    evidence: z.core.util.JSONType[] | null;
+    iterations: number | null;
+}>;
+export declare function listResearch(opts: research.ListQuery, apiKey: string): Promise<{
+    [x: string]: unknown;
+    data: {
+        [x: string]: unknown;
+        research_run_id: string;
+        status: "RUNNING" | "COMPLETED" | "FAILED" | "CANCELLED" | "QUEUED" | "TIMED_OUT";
+        query: string;
+        quick_result: {
+            [x: string]: unknown;
+            answer: string;
+            citations: string[];
+        } | null;
+        quick_result_summary: string | null;
+        deep_result: {
+            [x: string]: unknown;
+            result: string;
+            citations: string[];
+        } | null;
+        run_ids: string[];
+        created_at: string | null;
+        completed_at: string | null;
+    }[];
+    pagination: {
+        [x: string]: unknown;
+        total: number;
+        next_cursor: string | null;
+        has_more: boolean;
+    };
+}>;
+export declare function cancelResearch(id: string, apiKey: string): Promise<{
+    [x: string]: unknown;
+    research_run_id: string;
+    status: "RUNNING" | "COMPLETED" | "FAILED" | "CANCELLED" | "QUEUED" | "TIMED_OUT";
+    cancelled: boolean;
+}>;
+export declare function researchStream(input: research.Request | string, apiKey: string, signal: AbortSignal): AsyncGenerator<research.Event>;
 export {};

package/dist/lib/client.js

@@ -1,10 +1,11 @@
-import { APIStatusError, agentRunAsyncResponseSchema, agentRunResponseSchema, agentRunWithStreamingResponseSchema, browserSessionSchema, searchQueryResponseSchema, TinyFish, runSchema, runStatusSchema, } from '@tiny-fish/sdk';
+import { APIConnectionError, APIStatusError, agentRunAsyncResponseSchema, agentRunResponseSchema, agentRunWithStreamingResponseSchema, browserSessionSchema, searchQueryResponseSchema, TinyFish, runSchema, runStatusSchema, } from '@tiny-fish/sdk';
 import { CONNECT_SOURCE, RUNTIME_ATTEMPT_ENV, loadConfig } from './auth.js';
 import { API_URL_OVERRIDE, CLI_AGENT_IDENTITY, CLI_VERSION } from './constants.js';
 import { detectHarness, detectHumanInitiated } from './harness.js';
 import { captureNotice } from './notice.js';
 import { ApiError, parseJson } from './output.js';
 import { z } from 'zod';
+import * as research from './research.js';
 // Install-level connect context (PF-3169). A known caller is credited only to its own
 // install; under an unknown caller we credit a lone install, else send source only.
 // Never guess a client. Request-level harness truth is client_name (PF-3168).
@@ -84,6 +85,19 @@ class TinyFishCliClient extends TinyFish {
         }
         return headers;
     }
+    // The SDK lacks GET streaming; reuse its authentication headers.
+    async researchEvents(path, signal) {
+        const response = await fetch(`${this.baseURL}${path}`, {
+            headers: { ...this._buildHeaders(), Accept: 'text/event-stream' },
+            signal,
+        });
+        captureNotice(response.headers);
+        if (!response.ok)
+            throw await apiErrorFrom(response);
+        if (!response.body)
+            throw new Error('Research events response has no body');
+        return response.body.pipeThrough(new TextDecoderStream());
+    }
     // SDK has no PATCH and its delete() throws on 204.
     async send(method, path, json) {
         const response = await fetch(`${this.baseURL}${path}`, {
@@ -103,9 +117,10 @@ class TinyFishCliClient extends TinyFish {
 async function apiErrorFrom(response) {
     const text = await response.text().catch(() => '');
     const body = parseJson(text);
-    const message = [body?.error?.message, body?.message].find((m) => typeof m === 'string') ??
+    const error = typeof body?.error === 'string' ? undefined : body?.error;
+    const message = [error?.message, body?.message].find((m) => typeof m === 'string') ??
         (text || `HTTP ${response.status}`);
-    const code = typeof body?.error?.code === 'string' ? body.error.code : undefined;
+    const code = typeof error?.code === 'string' ? error.code : undefined;
     return new ApiError(response.status, message, code);
 }
 function createSdkClient(apiKey, timeout, baseUrl) {
@@ -120,18 +135,29 @@ function createSdkClient(apiKey, timeout, baseUrl) {
         ...(timeout !== undefined ? { timeout } : {}),
     });
 }
-function sdk(apiKey, call) {
-    return call(createSdkClient(apiKey)).catch(rethrowSdkError);
+function sdk(apiKey, call, timeout) {
+    const client = createSdkClient(apiKey, timeout);
+    return call(client).catch((error) => rethrowSdkError(error, client.baseURL));
 }
-function rethrowSdkError(error) {
+function rethrowSdkError(error, baseURL) {
     if (error instanceof APIStatusError) {
         throw new ApiError(error.statusCode, error.message, error.code);
     }
+    if (error instanceof APIConnectionError || (error instanceof TypeError && error.cause)) {
+        throw new Error(networkMessage(error, baseURL));
+    }
     if (error instanceof Error) {
         throw error;
     }
     throw new Error(String(error));
 }
+// Node's fetch keeps the reason (ECONNREFUSED, ENOTFOUND) in cause.
+function networkMessage(error, baseURL) {
+    const cause = z.looseObject({ code: z.string() }).safeParse(error.cause).data?.code;
+    const detail = cause ?? (error.cause instanceof Error ? error.cause.message : undefined);
+    const reason = detail ? `${error.message} (${detail})` : error.message;
+    return baseURL ? `Cannot reach ${new URL(baseURL).host}: ${reason}` : reason;
+}
 const cancelRunResponseSchema = z.object({
     run_id: z.string(),
     status: z.string(),
@@ -172,12 +198,14 @@ const runStepsResponseSchema = z.object({
     status: runStatusSchema,
     steps: z.array(runStepSchema),
 });
-function parseWithSchema(schema, value, message) {
+// Zod's own message is a JSON dump of every issue.
+export function parseWithSchema(schema, value, message) {
     const result = schema.safeParse(value);
-    if (!result.success) {
-        throw new Error(message);
-    }
-    return result.data;
+    if (result.success)
+        return result.data;
+    const issues = result.error.issues.map((i) => [...i.path.map(String), i.message].join(': '));
+    const more = issues.length > 3 ? `; +${issues.length - 3} more` : '';
+    throw new Error(`${message}: ${issues.slice(0, 3).join('; ')}${more}`);
 }
 function normalizeStreamEvent(event) {
     if (typeof event !== 'object' ||
@@ -587,3 +615,48 @@ export function vaultSync(apiKey) {
         return parseWithSchema(vaultItemsSyncResponseSchema, response, 'Invalid vault sync response');
     });
 }
+// A run may exist; never lose its ID.
+function parseResearch(schema, body) {
+    const id = z.looseObject({ research_run_id: research.idSchema }).safeParse(body).data;
+    const suffix = id ? ` for ${id.research_run_id}` : '';
+    return parseWithSchema(schema, body, `Invalid research response${suffix}`);
+}
+export const parseResearchId = (id) => parseWithSchema(research.idSchema, id, 'Invalid research ID');
+const runPath = (id) => `/v1/research-run/${parseResearchId(id)}`;
+export function startResearchAsync(req, apiKey) {
+    return sdk(apiKey, async (client) => parseResearch(research.acceptedSchema, await client.post('/v1/automation/run-research-async', {
+        json: research.requestSchema.parse(req),
+    })), research.START_TIMEOUT_MS);
+}
+export function getResearch(id, apiKey) {
+    return sdk(apiKey, async (client) => parseResearch(research.detailSchema, await client.get(runPath(id))), research.READ_TIMEOUT_MS);
+}
+export function listResearch(opts, apiKey) {
+    return sdk(apiKey, async (client) => parseResearch(research.listSchema, await client.get('/v1/research-run', { params: research.listQuerySchema.parse(opts) })), research.READ_TIMEOUT_MS);
+}
+export function cancelResearch(id, apiKey) {
+    return sdk(apiKey, async (client) => parseResearch(research.cancelSchema, await client.post(`${runPath(id)}/cancel`)), research.CANCEL_TIMEOUT_MS);
+}
+export async function* researchStream(input, apiKey, signal) {
+    let stream;
+    const client = createSdkClient(apiKey, research.RESEARCH_TIMEOUT_MS);
+    try {
+        stream =
+            typeof input === 'string'
+                ? await client.researchEvents(`${runPath(input)}/events`, signal)
+                : await client.postStream('/v1/automation/run-research', {
+                    json: research.requestSchema.parse(input),
+                    signal,
+                });
+        for await (const event of parseSseStream(stream, () => {
+            throw new Error('Invalid research event JSON');
+        }))
+            yield parseWithSchema(research.eventSchema, event, 'Invalid research event');
+    }
+    catch (error) {
+        rethrowSdkError(error, client.baseURL);
+    }
+    finally {
+        await stream?.cancel().catch(() => { });
+    }
+}

package/dist/lib/list-options.js

@@ -3,7 +3,8 @@ import { out, outLine } from './output.js';
 const MAX_PAGE_SIZE = 1000;
 export function integerInRange(min, max) {
     return (value) => {
-        const parsed = Number(value);
+        // Number() also accepts 0x10, 1e3 and blank strings.
+        const parsed = /^\d+$/.test(value) ? Number(value) : NaN;
         if (!Number.isSafeInteger(parsed) || parsed < min || (max !== undefined && parsed > max)) {
             throw new InvalidArgumentError(max === undefined
                 ? 'must be a positive integer'

package/dist/lib/research.d.ts

@@ -0,0 +1,158 @@
+import { z } from 'zod';
+export declare const RESEARCH_TIMEOUT_MS = 2700000;
+export declare const START_TIMEOUT_MS = 30000;
+export declare const READ_TIMEOUT_MS = 15000;
+export declare const CANCEL_TIMEOUT_MS = 5000;
+export declare const requestSchema: z.ZodObject<{
+    query: z.ZodString;
+    mode: z.ZodOptional<z.ZodEnum<{
+        deep: "deep";
+        max: "max";
+    }>>;
+    output_language: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type Request = z.infer<typeof requestSchema>;
+export declare const idSchema: z.ZodUUID;
+export declare const statusSchema: z.ZodEnum<{
+    RUNNING: "RUNNING";
+    COMPLETED: "COMPLETED";
+    FAILED: "FAILED";
+    CANCELLED: "CANCELLED";
+    QUEUED: "QUEUED";
+    TIMED_OUT: "TIMED_OUT";
+}>;
+export declare const acceptedSchema: z.ZodObject<{
+    research_run_id: z.ZodUUID;
+    error: z.ZodNullable<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$loose>;
+export declare const reportSchema: z.ZodObject<{
+    result: z.ZodString;
+    citations: z.ZodArray<z.ZodString>;
+}, z.core.$loose>;
+export type Report = z.infer<typeof reportSchema>;
+export declare const runSchema: z.ZodObject<{
+    research_run_id: z.ZodUUID;
+    status: z.ZodEnum<{
+        RUNNING: "RUNNING";
+        COMPLETED: "COMPLETED";
+        FAILED: "FAILED";
+        CANCELLED: "CANCELLED";
+        QUEUED: "QUEUED";
+        TIMED_OUT: "TIMED_OUT";
+    }>;
+    query: z.ZodString;
+    quick_result: z.ZodNullable<z.ZodObject<{
+        answer: z.ZodString;
+        citations: z.ZodArray<z.ZodString>;
+    }, z.core.$loose>>;
+    quick_result_summary: z.ZodNullable<z.ZodString>;
+    deep_result: z.ZodNullable<z.ZodObject<{
+        result: z.ZodString;
+        citations: z.ZodArray<z.ZodString>;
+    }, z.core.$loose>>;
+    run_ids: z.ZodArray<z.ZodString>;
+    created_at: z.ZodNullable<z.ZodString>;
+    completed_at: z.ZodNullable<z.ZodString>;
+}, z.core.$loose>;
+export type Run = z.infer<typeof runSchema>;
+export declare const detailSchema: z.ZodObject<{
+    research_run_id: z.ZodUUID;
+    status: z.ZodEnum<{
+        RUNNING: "RUNNING";
+        COMPLETED: "COMPLETED";
+        FAILED: "FAILED";
+        CANCELLED: "CANCELLED";
+        QUEUED: "QUEUED";
+        TIMED_OUT: "TIMED_OUT";
+    }>;
+    query: z.ZodString;
+    quick_result: z.ZodNullable<z.ZodObject<{
+        answer: z.ZodString;
+        citations: z.ZodArray<z.ZodString>;
+    }, z.core.$loose>>;
+    quick_result_summary: z.ZodNullable<z.ZodString>;
+    deep_result: z.ZodNullable<z.ZodObject<{
+        result: z.ZodString;
+        citations: z.ZodArray<z.ZodString>;
+    }, z.core.$loose>>;
+    run_ids: z.ZodArray<z.ZodString>;
+    created_at: z.ZodNullable<z.ZodString>;
+    completed_at: z.ZodNullable<z.ZodString>;
+    error: z.ZodNullable<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strip>>;
+    research_plan: z.ZodNullable<z.ZodJSONSchema>;
+    evidence: z.ZodNullable<z.ZodArray<z.ZodJSONSchema>>;
+    iterations: z.ZodNullable<z.ZodNumber>;
+}, z.core.$loose>;
+export declare const listQuerySchema: z.ZodObject<{
+    status: z.ZodOptional<z.ZodEnum<{
+        RUNNING: "RUNNING";
+        COMPLETED: "COMPLETED";
+        FAILED: "FAILED";
+        CANCELLED: "CANCELLED";
+        QUEUED: "QUEUED";
+        TIMED_OUT: "TIMED_OUT";
+    }>>;
+    query: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    cursor: z.ZodOptional<z.ZodString>;
+    sort_direction: z.ZodOptional<z.ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>>;
+}, z.core.$strip>;
+export type ListQuery = z.infer<typeof listQuerySchema>;
+export declare const listSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        research_run_id: z.ZodUUID;
+        status: z.ZodEnum<{
+            RUNNING: "RUNNING";
+            COMPLETED: "COMPLETED";
+            FAILED: "FAILED";
+            CANCELLED: "CANCELLED";
+            QUEUED: "QUEUED";
+            TIMED_OUT: "TIMED_OUT";
+        }>;
+        query: z.ZodString;
+        quick_result: z.ZodNullable<z.ZodObject<{
+            answer: z.ZodString;
+            citations: z.ZodArray<z.ZodString>;
+        }, z.core.$loose>>;
+        quick_result_summary: z.ZodNullable<z.ZodString>;
+        deep_result: z.ZodNullable<z.ZodObject<{
+            result: z.ZodString;
+            citations: z.ZodArray<z.ZodString>;
+        }, z.core.$loose>>;
+        run_ids: z.ZodArray<z.ZodString>;
+        created_at: z.ZodNullable<z.ZodString>;
+        completed_at: z.ZodNullable<z.ZodString>;
+    }, z.core.$loose>>;
+    pagination: z.ZodObject<{
+        total: z.ZodNumber;
+        next_cursor: z.ZodNullable<z.ZodString>;
+        has_more: z.ZodBoolean;
+    }, z.core.$loose>;
+}, z.core.$loose>;
+export declare const cancelSchema: z.ZodObject<{
+    research_run_id: z.ZodUUID;
+    status: z.ZodEnum<{
+        RUNNING: "RUNNING";
+        COMPLETED: "COMPLETED";
+        FAILED: "FAILED";
+        CANCELLED: "CANCELLED";
+        QUEUED: "QUEUED";
+        TIMED_OUT: "TIMED_OUT";
+    }>;
+    cancelled: z.ZodBoolean;
+}, z.core.$loose>;
+export declare const eventSchema: z.ZodObject<{
+    event: z.ZodString;
+    research_run_id: z.ZodOptional<z.ZodUUID>;
+    message: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export type Event = z.infer<typeof eventSchema>;

package/dist/lib/research.js

@@ -0,0 +1,78 @@
+import { z } from 'zod';
+// Research can exceed the SDK's ten-minute timeout.
+export const RESEARCH_TIMEOUT_MS = 2_700_000;
+export const START_TIMEOUT_MS = 30_000;
+export const READ_TIMEOUT_MS = 15_000;
+export const CANCEL_TIMEOUT_MS = 5_000;
+export const requestSchema = z.object({
+    query: z.string().trim().min(1).max(2000),
+    mode: z.enum(['deep', 'max']).optional(),
+    output_language: z.string().optional(),
+});
+export const idSchema = z.uuid();
+export const statusSchema = z.enum([
+    'QUEUED',
+    'RUNNING',
+    'COMPLETED',
+    'FAILED',
+    'CANCELLED',
+    'TIMED_OUT',
+]);
+const errorSchema = z.object({ code: z.string(), message: z.string() }).nullable();
+export const acceptedSchema = z.looseObject({
+    research_run_id: idSchema,
+    error: errorSchema,
+});
+export const reportSchema = z.looseObject({ result: z.string(), citations: z.array(z.string()) });
+export const runSchema = z.looseObject({
+    research_run_id: idSchema,
+    status: statusSchema,
+    query: z.string(),
+    quick_result: z.looseObject({ answer: z.string(), citations: z.array(z.string()) }).nullable(),
+    quick_result_summary: z.string().nullable(),
+    deep_result: reportSchema.nullable(),
+    run_ids: z.array(z.string()),
+    created_at: z.string().nullable(),
+    completed_at: z.string().nullable(),
+});
+export const detailSchema = runSchema.extend({
+    error: errorSchema,
+    research_plan: z.json().nullable(),
+    evidence: z.array(z.json()).nullable(),
+    iterations: z.number().int().nonnegative().nullable(),
+});
+export const listQuerySchema = z.object({
+    status: statusSchema.optional(),
+    query: z.string().max(500).optional(),
+    limit: z.number().int().min(1).max(100).optional(),
+    cursor: z.string().optional(),
+    sort_direction: z.enum(['asc', 'desc']).optional(),
+});
+export const listSchema = z.looseObject({
+    data: z.array(runSchema),
+    pagination: z.looseObject({
+        total: z.number(),
+        next_cursor: z.string().nullable(),
+        has_more: z.boolean(),
+    }),
+});
+export const cancelSchema = z.looseObject({
+    research_run_id: idSchema,
+    status: statusSchema,
+    cancelled: z.boolean(),
+});
+export const eventSchema = z
+    .looseObject({
+    event: z.string().min(1),
+    research_run_id: idSchema.optional(),
+    message: z.string().optional(),
+})
+    .superRefine((event, ctx) => {
+    if (event.event === 'final_result' && !reportSchema.safeParse(event).success)
+        ctx.addIssue({ code: 'custom', message: 'Invalid final research report' });
+    const required = { created: 'research_run_id', error: 'message' };
+    for (const [name, field] of Object.entries(required)) {
+        if (event.event === name && event[field] === undefined)
+            ctx.addIssue({ code: 'custom', message: `Missing ${field}`, path: [field] });
+    }
+});

package/dist/lib/signals.d.ts

@@ -10,3 +10,6 @@ export type TerminalSignal = keyof typeof SIGNAL_EXIT_CODES;
  * exits rather than waiting on it.
  */
 export declare function installSignalGuard(onSignal: (signal: TerminalSignal) => Promise<void> | void): () => void;
+/** Registers cleanup for a closed reader (`| head`); returns its remover. */
+export declare function onBrokenPipe(handler: () => Promise<void> | void): () => void;
+export declare function handleBrokenPipe(): void;

package/dist/lib/signals.js

@@ -25,3 +25,22 @@ export function installSignalGuard(onSignal) {
             process.off(signal, handler);
     };
 }
+let brokenPipeHandler;
+/** Registers cleanup for a closed reader (`| head`); returns its remover. */
+export function onBrokenPipe(handler) {
+    brokenPipeHandler = handler;
+    return () => {
+        if (brokenPipeHandler === handler)
+            brokenPipeHandler = undefined;
+    };
+}
+let pipeClosed = false;
+// Disconnecting never cancels a run server-side; the handler must.
+export function handleBrokenPipe() {
+    if (pipeClosed)
+        return;
+    pipeClosed = true;
+    void Promise.resolve(brokenPipeHandler?.())
+        .catch(() => { })
+        .finally(() => process.exit(0));
+}

package/dist/program.js

@@ -24,6 +24,7 @@ const GROUPS = {
         (await import('./commands/runs.js')).registerRuns(runCmd);
         (await import('./commands/batch.js')).registerBatch(agentCmd);
     },
+    research: async (p) => (await import('./commands/research.js')).registerResearch(p),
     search: async (p) => (await import('./commands/search.js')).registerSearch(p),
     fetch: async (p) => (await import('./commands/fetch.js')).registerFetch(p),
     monitor: async (p) => (await import('./commands/monitor.js')).registerMonitor(p),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiny-fish/cli",
-  "version": "0.50.2-next.407",
+  "version": "0.51.0",
   "description": "TinyFish CLI — run web automations from your terminal",
   "type": "module",
   "bin": {