@eightstate/escli 0.5.0 → 0.7.1

package/dist/lib/registry.js

@@ -24,34 +24,89 @@ import Research, { ResearchDataSchema } from '../commands/research.js';
 import Social, { SocialDataSchema } from '../commands/social.js';
 import Usage, { UsageDataSchema } from '../commands/usage.js';
 import Version, { VersionDataSchema } from '../commands/version.js';
+import NotionTopic from '../commands/notion/index.js';
+import NotionEnroll from '../commands/notion/enroll.js';
+import NotionWhoami from '../commands/notion/whoami.js';
+import NotionPageRead from '../commands/notion/page/read.js';
+import NotionPageEdit from '../commands/notion/page/edit.js';
+import NotionPageReplace from '../commands/notion/page/replace.js';
+import NotionPageTrash from '../commands/notion/page/trash.js';
+import NotionPageMove from '../commands/notion/page/move.js';
+import NotionPageReplaceText from '../commands/notion/page/replace-text.js';
+import NotionPageReplaceContent from '../commands/notion/page/replace-content.js';
+import NotionBlockTrash from '../commands/notion/block/trash.js';
+import NotionDbQuery from '../commands/notion/db/query.js';
+import NotionDbCreate from '../commands/notion/db/create.js';
+import NotionDbRowCreate from '../commands/notion/db/row/create.js';
+import NotionDbRowUpdate from '../commands/notion/db/row/update.js';
+import NotionDsCreate from '../commands/notion/ds/create.js';
+import NotionViewCreate from '../commands/notion/view/create.js';
+import NotionSearch from '../commands/notion/search.js';
+import NotionCommentsList from '../commands/notion/comments/list.js';
+import NotionCommentsGet from '../commands/notion/comments/get.js';
+import NotionCommentsThread from '../commands/notion/comments/thread.js';
+import NotionCommentsAdd from '../commands/notion/comments/add.js';
+import NotionCommentsReply from '../commands/notion/comments/reply.js';
+import NotionUpload from '../commands/notion/upload/index.js';
+import NotionUploadAttach from '../commands/notion/upload/attach.js';
+import NotionUploadStatus from '../commands/notion/upload/status.js';
+import NotionUploadList from '../commands/notion/upload/list.js';
 import { registerCommandMetadata } from './command-metadata.js';
 import { renderAuthLogin, renderAuthLogout, renderAuthProfiles, renderAuthStatus, renderAuthSwitch, renderDocsContent, renderDocsSearch, renderFetch, renderModelList, renderResearch, renderSearch, renderSocial, renderUsage, renderVersion, } from '../io/io.js';
+const asCommandClass = (c) => c;
 const commandClasses = [
-    { id: 'image', command: ImageTopic },
-    { id: 'image generate', command: ImageGenerate },
-    { id: 'image edit', command: ImageEdit },
-    { id: 'audio', command: AudioTopic },
-    { id: 'audio transcribe', command: AudioTranscribe },
-    { id: 'audio status', command: AudioStatus },
-    { id: 'audio get', command: AudioGet },
-    { id: 'audio list', command: AudioList },
-    { id: 'auth', command: AuthTopic },
-    { id: 'auth login', command: AuthLogin },
-    { id: 'auth logout', command: AuthLogout },
-    { id: 'auth status', command: AuthStatus },
-    { id: 'auth profiles', command: AuthProfiles },
-    { id: 'auth switch', command: AuthSwitch },
-    { id: 'docs', command: DocsTopic },
-    { id: 'docs search', command: DocsSearch },
-    { id: 'docs get', command: DocsGet },
-    { id: 'docs fetch', command: DocsFetch },
-    { id: 'fetch', command: Fetch },
-    { id: 'models', command: Models },
-    { id: 'search', command: Search },
-    { id: 'research', command: Research },
-    { id: 'social', command: Social },
-    { id: 'usage', command: Usage },
-    { id: 'version', command: Version },
+    { id: 'image', command: asCommandClass(ImageTopic) },
+    { id: 'image generate', command: asCommandClass(ImageGenerate) },
+    { id: 'image edit', command: asCommandClass(ImageEdit) },
+    { id: 'audio', command: asCommandClass(AudioTopic) },
+    { id: 'audio transcribe', command: asCommandClass(AudioTranscribe) },
+    { id: 'audio status', command: asCommandClass(AudioStatus) },
+    { id: 'audio get', command: asCommandClass(AudioGet) },
+    { id: 'audio list', command: asCommandClass(AudioList) },
+    { id: 'auth', command: asCommandClass(AuthTopic) },
+    { id: 'auth login', command: asCommandClass(AuthLogin) },
+    { id: 'auth logout', command: asCommandClass(AuthLogout) },
+    { id: 'auth status', command: asCommandClass(AuthStatus) },
+    { id: 'auth profiles', command: asCommandClass(AuthProfiles) },
+    { id: 'auth switch', command: asCommandClass(AuthSwitch) },
+    { id: 'docs', command: asCommandClass(DocsTopic) },
+    { id: 'docs search', command: asCommandClass(DocsSearch) },
+    { id: 'docs get', command: asCommandClass(DocsGet) },
+    { id: 'docs fetch', command: asCommandClass(DocsFetch) },
+    { id: 'fetch', command: asCommandClass(Fetch) },
+    { id: 'models', command: asCommandClass(Models) },
+    { id: 'search', command: asCommandClass(Search) },
+    { id: 'research', command: asCommandClass(Research) },
+    { id: 'social', command: asCommandClass(Social) },
+    { id: 'usage', command: asCommandClass(Usage) },
+    { id: 'version', command: asCommandClass(Version) },
+    { id: 'notion', command: asCommandClass(NotionTopic) },
+    { id: 'notion enroll', command: asCommandClass(NotionEnroll) },
+    { id: 'notion whoami', command: asCommandClass(NotionWhoami) },
+    { id: 'notion page read', command: asCommandClass(NotionPageRead) },
+    { id: 'notion page edit', command: asCommandClass(NotionPageEdit) },
+    { id: 'notion page replace', command: asCommandClass(NotionPageReplace) },
+    { id: 'notion page trash', command: asCommandClass(NotionPageTrash) },
+    { id: 'notion page move', command: asCommandClass(NotionPageMove) },
+    { id: 'notion page replace-text', command: asCommandClass(NotionPageReplaceText) },
+    { id: 'notion page replace-content', command: asCommandClass(NotionPageReplaceContent) },
+    { id: 'notion block trash', command: asCommandClass(NotionBlockTrash) },
+    { id: 'notion db query', command: asCommandClass(NotionDbQuery) },
+    { id: 'notion db create', command: asCommandClass(NotionDbCreate) },
+    { id: 'notion db row create', command: asCommandClass(NotionDbRowCreate) },
+    { id: 'notion db row update', command: asCommandClass(NotionDbRowUpdate) },
+    { id: 'notion ds create', command: asCommandClass(NotionDsCreate) },
+    { id: 'notion view create', command: asCommandClass(NotionViewCreate) },
+    { id: 'notion search', command: asCommandClass(NotionSearch) },
+    { id: 'notion comments list', command: asCommandClass(NotionCommentsList) },
+    { id: 'notion comments get', command: asCommandClass(NotionCommentsGet) },
+    { id: 'notion comments thread', command: asCommandClass(NotionCommentsThread) },
+    { id: 'notion comments add', command: asCommandClass(NotionCommentsAdd) },
+    { id: 'notion comments reply', command: asCommandClass(NotionCommentsReply) },
+    { id: 'notion upload', command: asCommandClass(NotionUpload) },
+    { id: 'notion upload attach', command: asCommandClass(NotionUploadAttach) },
+    { id: 'notion upload status', command: asCommandClass(NotionUploadStatus) },
+    { id: 'notion upload list', command: asCommandClass(NotionUploadList) },
 ];
 const aliasOverrides = new Map([
     ['image', ['img', 'i']],
@@ -79,6 +134,15 @@ const aliasOverrides = new Map([
     ['social', []],
     ['usage', ['u']],
     ['version', []],
+    ['notion', ['n']],
+    // file-upload alias surface: every help text, "next" hint, and example
+    // advertises `notion file-upload upload|attach|status|list` but the registry
+    // ids are `notion upload …` — wire the file-upload forms in so users typing
+    // the advertised commands actually resolve. `ls` kept as a list shorthand.
+    ['notion upload', ['notion file-upload', 'notion file-upload upload']],
+    ['notion upload attach', ['notion file-upload attach']],
+    ['notion upload status', ['notion file-upload status']],
+    ['notion upload list', ['notion file-upload list', 'notion file-upload ls', 'notion upload ls']],
 ]);
 const metadataEntries = [
     ['image', { inputSchema: z.object({}), dataSchema: z.object({}) }],
@@ -172,6 +236,8 @@ const metadataEntries = [
                 metadata: z.string().optional(),
                 'follow-up': z.string().optional(),
                 'no-basis': z.boolean().optional(),
+                'max-wait': z.number().int().optional(),
+                async: z.boolean().optional(),
             }), dataSchema: ResearchDataSchema, render: renderResearch }],
     ['social', { inputSchema: z.object({
                 query: z.array(z.string()).min(1),
@@ -191,6 +257,33 @@ const metadataEntries = [
                 pricing: z.boolean().optional(),
             }), dataSchema: UsageDataSchema, render: renderUsage }],
     ['version', { inputSchema: z.object({}), dataSchema: VersionDataSchema, render: renderVersion }],
+    ['notion', { inputSchema: z.object({}), dataSchema: z.object({}) }],
+    ['notion enroll', { inputSchema: z.object({}).passthrough(), dataSchema: z.unknown() }],
+    ['notion whoami', { inputSchema: z.object({}).passthrough(), dataSchema: z.unknown() }],
+    ['notion page read', { inputSchema: z.object({}).passthrough(), dataSchema: z.unknown() }],
+    ['notion page edit', { inputSchema: z.object({}).passthrough(), dataSchema: z.unknown() }],
+    ['notion page replace', { inputSchema: z.object({}).passthrough(), dataSchema: z.unknown() }],
+    ['notion page trash', { inputSchema: z.object({}).passthrough(), dataSchema: z.unknown() }],
+    ['notion page move', { inputSchema: z.object({}).passthrough(), dataSchema: z.unknown() }],
+    ['notion page replace-text', { inputSchema: z.object({}).passthrough(), dataSchema: z.unknown() }],
+    ['notion page replace-content', { inputSchema: z.object({}).passthrough(), dataSchema: z.unknown() }],
+    ['notion block trash', { inputSchema: z.object({}).passthrough(), dataSchema: z.unknown() }],
+    ['notion db query', { inputSchema: z.object({}).passthrough(), dataSchema: z.unknown() }],
+    ['notion db create', { inputSchema: z.object({}).passthrough(), dataSchema: z.unknown() }],
+    ['notion db row create', { inputSchema: z.object({}).passthrough(), dataSchema: z.unknown() }],
+    ['notion db row update', { inputSchema: z.object({}).passthrough(), dataSchema: z.unknown() }],
+    ['notion ds create', { inputSchema: z.object({}).passthrough(), dataSchema: z.unknown() }],
+    ['notion view create', { inputSchema: z.object({}).passthrough(), dataSchema: z.unknown() }],
+    ['notion search', { inputSchema: z.object({}).passthrough(), dataSchema: z.unknown() }],
+    ['notion comments list', { inputSchema: z.object({}).passthrough(), dataSchema: z.unknown() }],
+    ['notion comments get', { inputSchema: z.object({}).passthrough(), dataSchema: z.unknown() }],
+    ['notion comments thread', { inputSchema: z.object({}).passthrough(), dataSchema: z.unknown() }],
+    ['notion comments add', { inputSchema: z.object({}).passthrough(), dataSchema: z.unknown() }],
+    ['notion comments reply', { inputSchema: z.object({}).passthrough(), dataSchema: z.unknown() }],
+    ['notion upload', { inputSchema: z.object({}).passthrough(), dataSchema: z.unknown() }],
+    ['notion upload attach', { inputSchema: z.object({}).passthrough(), dataSchema: z.unknown() }],
+    ['notion upload status', { inputSchema: z.object({}).passthrough(), dataSchema: z.unknown() }],
+    ['notion upload list', { inputSchema: z.object({}).passthrough(), dataSchema: z.unknown() }],
 ];
 const metadata = new Map(metadataEntries);
 export const commandRegistry = commandClasses.map(({ id, command }) => buildRegistration(id, command));

package/dist/services/notion.js

@@ -0,0 +1,274 @@
+import { ErrorCode } from '@eightstate/contracts/errors';
+import { ExitCodes } from '@eightstate/contracts/exit-codes';
+import { exitCodeForErrorCode } from '@eightstate/contracts/failure-taxonomy';
+import { EscliError } from '../lib/escli-error.js';
+import { resolveCliToken } from './credentials.js';
+export const NOTION_VERSION = '2026-03-11';
+const DEFAULT_GATE_URL = 'https://internal.eightstate.co';
+const DEFAULT_TIMEOUT_MS = 30_000;
+export async function whoami() {
+    return gateRequest('GET', '/v1/notion/whoami');
+}
+export async function enroll(token, options = {}) {
+    return gateRequest('POST', '/v1/notion/enroll', withDefined({ token, force: options.force === true ? true : undefined }));
+}
+export async function rotate(token, options = {}) {
+    return gateRequest('POST', '/v1/notion/rotate', withDefined({ token, force: options.force === true ? true : undefined }));
+}
+export async function deleteEnrollment() {
+    return gateRequest('DELETE', '/v1/notion/enrollment');
+}
+export async function proxy(method, path, opts = {}) {
+    const idempotent = opts.idempotent ?? method === 'GET';
+    try {
+        return await gateRequest('POST', '/v1/notion/proxy', { method, path, query: opts.query, body: opts.body, idempotent });
+    }
+    catch (error) {
+        // A CLI-local timeout on a write is genuinely ambiguous: the gate may have
+        // already accepted the request and forwarded it to Notion. POST read
+        // endpoints such as search/query opt into idempotent=true and keep the
+        // normal retryable network.timeout classification.
+        if (error instanceof EscliError && error.code === ErrorCode.NetworkTimeout && !idempotent) {
+            throw new EscliError('uncertain — local timeout on a Notion write; verify the operation in Notion before retrying', {
+                code: ErrorCode.NotionTimeoutUncertain,
+                exitCode: ExitCodes.Error,
+                details: error.details,
+                causeCode: 'notion.timeout_uncertain',
+            });
+        }
+        throw error;
+    }
+}
+export function notionFetchPage(id) {
+    return proxy('GET', `/v1/pages/${encodeURIComponent(id)}/markdown`);
+}
+export function notionPagePatchMarkdown(id, ops) {
+    return proxy('PATCH', `/v1/pages/${encodeURIComponent(id)}/markdown`, { body: ops });
+}
+export function notionDataSourceQuery(dsId, filter, sorts, pageSize, nextCursor) {
+    return proxy('POST', `/v1/data_sources/${encodeURIComponent(dsId)}/query`, {
+        body: withDefined({ filter, sorts, page_size: pageSize, start_cursor: nextCursor }),
+        idempotent: true,
+    });
+}
+export function notionSearch(query, opts = {}) {
+    return proxy('POST', '/v1/search', { body: { query, ...opts }, idempotent: true });
+}
+export function notionCommentsList(pageId, nextCursor) {
+    return proxy('GET', '/v1/comments', { query: withDefined({ block_id: pageId, start_cursor: nextCursor }) });
+}
+export function notionCommentsCreate(input) {
+    const body = input.body ?? withDefined({ parent: input.pageId ? { page_id: input.pageId } : undefined, discussion_id: input.discussionId, rich_text: input.richText });
+    return proxy('POST', '/v1/comments', { body });
+}
+export function notionFileUploadCreate(body) {
+    return proxy('POST', '/v1/file_uploads', { body });
+}
+export function notionFileUploadSend(fileUploadId, options) {
+    return proxy('POST', `/v1/file_uploads/${encodeURIComponent(fileUploadId)}/send`, {
+        body: withDefined({ file: options.file, filename: options.filename, content_type: options.contentType }),
+    });
+}
+export function notionFileUploadComplete(fileUploadId) {
+    return proxy('POST', `/v1/file_uploads/${encodeURIComponent(fileUploadId)}/complete`);
+}
+export function notionPagesCreate(parent, props, markdown) {
+    return proxy('POST', '/v1/pages', { body: withDefined({ parent, properties: props, markdown }) });
+}
+export function notionPagesPatchProps(pageId, props) {
+    return proxy('PATCH', `/v1/pages/${encodeURIComponent(pageId)}`, { body: { properties: props } });
+}
+export function notionPagesMove(pageId, parent) {
+    return proxy('POST', `/v1/pages/${encodeURIComponent(pageId)}/move`, { body: { parent } });
+}
+export function notionPagesTrash(pageId, inTrash) {
+    return proxy('PATCH', `/v1/pages/${encodeURIComponent(pageId)}`, { body: { in_trash: inTrash } });
+}
+export function notionUsersMe() {
+    return proxy('GET', '/v1/users/me');
+}
+export function notionBlocksGet(blockId, nextCursor) {
+    return proxy('GET', `/v1/blocks/${encodeURIComponent(blockId)}/children`, { query: withDefined({ start_cursor: nextCursor }) });
+}
+export function notionBlocksUpdate(blockId, body) {
+    return proxy('PATCH', `/v1/blocks/${encodeURIComponent(blockId)}`, { body });
+}
+export function notionBlocksDelete(blockId) {
+    return proxy('DELETE', `/v1/blocks/${encodeURIComponent(blockId)}`);
+}
+export function notionBlocksAppendChildren(blockId, children, position) {
+    return proxy('PATCH', `/v1/blocks/${encodeURIComponent(blockId)}/children`, { body: withDefined({ children, position }) });
+}
+async function gateRequest(method, path, body) {
+    const token = resolveCliToken();
+    if (!token) {
+        throw new EscliError('not authenticated', {
+            code: ErrorCode.AuthRequired,
+            exitCode: ExitCodes.Auth,
+            remediation: { command: 'escli auth login' },
+        });
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
+    try {
+        const response = await fetch(new URL(path, gateUrl()), {
+            method,
+            headers: { 'authorization': `Bearer ${token}`, 'accept': 'application/json', ...(body === undefined ? {} : { 'content-type': 'application/json' }) },
+            body: body === undefined ? undefined : JSON.stringify(body),
+            signal: controller.signal,
+        });
+        const payload = await parseJson(response);
+        if (!response.ok)
+            throw mapGateFailure(response.status, payload);
+        return normalizeGatePayload(payload);
+    }
+    catch (error) {
+        if (error instanceof EscliError)
+            throw error;
+        throw mapNetworkError(error);
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+async function parseJson(response) {
+    const text = await response.text();
+    if (!text)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        throw new EscliError(`invalid JSON response: ${error instanceof Error ? error.message : String(error)}`, {
+            code: ErrorCode.GateInvalidResponse,
+            details: text,
+        });
+    }
+}
+function normalizeGatePayload(payload) {
+    const record = recordValue(payload);
+    if (record && typeof record.ok === 'boolean') {
+        const envelope = record;
+        if (envelope.ok === false)
+            throw mapGateErrorObject(envelope.error, payload);
+        const data = envelope.data;
+        return { data, raw: data, meta: notionMeta(envelope.meta, data) };
+    }
+    return { data: payload, raw: payload, meta: notionMeta(undefined, payload) };
+}
+function notionMeta(meta, data) {
+    return {
+        ...(meta ?? {}),
+        next: stringValue(meta?.next) ?? stringValue(recordValue(data)?.next_cursor) ?? null,
+        notion_version: NOTION_VERSION,
+    };
+}
+function mapGateFailure(status, body) {
+    const envelope = recordValue(body);
+    if (envelope?.ok === false)
+        return mapGateErrorObject(envelope.error, body);
+    const code = stringValue(recordValue(body)?.code) ?? stringValue(recordValue(recordValue(body)?.error)?.code);
+    const message = extractErrorMessage(body) ?? `Notion broker request failed with HTTP ${status}`;
+    return new EscliError(message, { code: mapErrorCode(code, status), exitCode: exitCodeForStatusAndCode(status, code), details: body, causeCode: code });
+}
+function mapGateErrorObject(error, body) {
+    const code = error?.code;
+    return new EscliError(error?.message ?? 'Notion broker request failed', {
+        code: mapErrorCode(code),
+        exitCode: exitCodeForCode(code),
+        details: error?.details ?? body,
+        causeCode: code,
+    });
+}
+function mapErrorCode(code, status) {
+    switch (code) {
+        case 'notion.unauthorized':
+        case 'unauthorized':
+            return ErrorCode.NotionUnauthorized;
+        case 'notion.restricted':
+        case 'restricted_resource':
+            return ErrorCode.NotionRestricted;
+        case 'notion.not_found':
+        case 'object_not_found':
+            return ErrorCode.NotionNotFound;
+        case 'notion.rate_limited':
+        case 'rate_limited':
+            return ErrorCode.NotionRateLimited;
+        case 'notion.validation':
+        case 'notion.payload_too_large':
+        case 'notion.method_not_allowed':
+        case 'notion.invalid_token_type':
+        case 'validation_error':
+        case 'invalid_request':
+            return ErrorCode.NotionValidation;
+        case 'notion.conflict':
+        case 'conflict_error':
+        case 'notion.already_enrolled':
+        case 'notion.identity_mismatch':
+            return ErrorCode.NotionConflict;
+        case 'notion.timeout_uncertain':
+            return ErrorCode.NotionTimeoutUncertain;
+        case 'notion.enrollment_required':
+            return ErrorCode.NotionEnrollmentRequired;
+        case 'notion.batch_partial':
+            return ErrorCode.NotionBatchPartial;
+        case 'notion.upstream_unreachable':
+            return ErrorCode.ServiceUnavailable;
+        case 'notion.invalid_json':
+            return ErrorCode.GateInvalidResponse;
+        case 'notion.invalid_request_url':
+            return ErrorCode.UsageInvalid;
+        default:
+            if (status === 401)
+                return ErrorCode.NotionUnauthorized;
+            if (status === 403)
+                return ErrorCode.NotionRestricted;
+            if (status === 404)
+                return ErrorCode.NotionNotFound;
+            if (status === 409)
+                return ErrorCode.NotionConflict;
+            if (status === 429)
+                return ErrorCode.NotionRateLimited;
+            if (status !== undefined && status >= 500)
+                return ErrorCode.ServiceUnavailable;
+            return ErrorCode.ApiError;
+    }
+}
+function exitCodeForStatusAndCode(status, code) {
+    if (code)
+        return exitCodeForCode(code);
+    if (status >= 500)
+        return ExitCodes.Transient;
+    return exitCodeForCode(code);
+}
+function exitCodeForCode(code) {
+    // Single source of truth: contracts/failure-taxonomy. Removing the local
+    // switch fixes the case where notion.conflict mapped to NotFound here but
+    // Error in contracts — same code, different exit per surface.
+    return exitCodeForErrorCode(mapErrorCode(code));
+}
+function mapNetworkError(error) {
+    const isAbort = error instanceof Error && error.name === 'AbortError';
+    return new EscliError(isAbort ? 'network error: request timed out' : `network error: ${error instanceof Error ? error.message : String(error)}`, {
+        code: isAbort ? ErrorCode.NetworkTimeout : ErrorCode.NetworkError,
+        exitCode: ExitCodes.Transient,
+        details: error instanceof Error ? error.message : error,
+    });
+}
+function extractErrorMessage(body) {
+    const root = recordValue(body);
+    return stringValue(root?.message) ?? stringValue(root?.error) ?? stringValue(recordValue(root?.error)?.message);
+}
+function withDefined(input) {
+    return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== undefined));
+}
+function gateUrl() {
+    return process.env.ESCLI_GATE_URL ?? DEFAULT_GATE_URL;
+}
+function recordValue(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+}
+function stringValue(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+//# sourceMappingURL=notion.js.map

package/dist/services/research.js

@@ -28,8 +28,11 @@ export async function runResearch(options) {
         throw new EscliError('task creation response missing run_id', { code: ErrorCode.GateInvalidResponse });
     if (captured.key)
         await rememberRunOwner(runId, captured.key.fingerprint);
+    if (options.async) {
+        return { run_id: runId, processor: options.processor, status: stringValue(task.status) ?? 'submitted' };
+    }
     const apiKey = captured.key?.apiKey ?? await getResearchApiKeyForRun(runId);
-    const output = await pollUntilComplete(apiKey, runId, options.timeoutSeconds);
+    const output = await pollUntilComplete(apiKey, runId, options.timeoutSeconds, options.maxWaitSeconds);
     const data = { run_id: runId, processor: options.processor, output };
     if (options.output) {
         data.path = resolve(options.output);
@@ -219,22 +222,40 @@ async function requestText(url, options) {
         clearTimeout(timeout);
     }
 }
-async function pollUntilComplete(apiKey, runId, timeoutSeconds) {
+async function pollUntilComplete(apiKey, runId, requestTimeoutSeconds, maxWaitSeconds) {
     const started = Date.now();
-    const maxMs = pollMaxMs(timeoutSeconds);
+    const maxMs = pollMaxMs(maxWaitSeconds);
+    let lastStatus = 'unknown';
     while (Date.now() - started < maxMs) {
-        const result = await apiRequest('GET', `/v1/tasks/runs/${runId}`, apiKey, undefined, undefined, timeoutSeconds);
-        const status = result.status;
+        const remainingMs = maxMs - (Date.now() - started);
+        const requestTimeout = boundedRequestTimeoutSeconds(requestTimeoutSeconds, remainingMs);
+        const result = await apiRequest('GET', `/v1/tasks/runs/${runId}`, apiKey, undefined, undefined, requestTimeout);
+        const status = stringValue(result.status) ?? 'unknown';
+        lastStatus = status;
         if (status === 'completed') {
-            const output = await apiRequest('GET', `/v1/tasks/runs/${runId}/result`, apiKey, undefined, undefined, timeoutSeconds);
+            const output = await apiRequest('GET', `/v1/tasks/runs/${runId}/result`, apiKey, undefined, undefined, requestTimeoutSeconds);
             return normalizeOutput(output.output);
         }
         if (status === 'failed' || status === 'cancelled') {
-            throw new EscliError(`task ${String(status)}: ${String(result.error ?? '')}`, { code: ErrorCode.ResearchTaskFailed, details: result.error });
+            throw new EscliError(`task ${status}: ${String(result.error ?? '')}`, { code: ErrorCode.ResearchTaskFailed, details: result.error });
         }
         await sleep(pollIntervalMs());
     }
-    throw new EscliError('research task timed out', { code: ErrorCode.ResearchTimeout });
+    const elapsedMs = Date.now() - started;
+    throw new EscliError(`research task timed out; last status: ${lastStatus}`, {
+        code: ErrorCode.ResearchTimeout,
+        details: { run_id: runId, status: lastStatus, elapsed_ms: elapsedMs, max_wait_ms: maxMs },
+        remediation: {
+            command: `escli research --status ${runId}`,
+            hint: `Task did not complete within ${Math.round(maxMs / 1000)}s. Poll with \`escli research --status ${runId}\` and fetch with \`escli research --result ${runId} -o <path>\` once it completes.`,
+        },
+    });
+}
+function boundedRequestTimeoutSeconds(requestTimeoutSeconds, remainingMs) {
+    const remainingSeconds = Math.max(1, Math.ceil(remainingMs / 1000));
+    if (requestTimeoutSeconds === undefined)
+        return remainingSeconds;
+    return Math.max(1, Math.min(requestTimeoutSeconds, remainingSeconds));
 }
 async function writeResearchOutput(path, query, processor, runId, output, createdAt, noBasis) {
     try {
@@ -431,13 +452,13 @@ async function rememberRunOwner(runId, fingerprint) {
 function pollIntervalMs() {
     return Math.max(1, Number(process.env.ESCLI_RESEARCH_POLL_INTERVAL_MS ?? DEFAULT_POLL_INTERVAL_MS));
 }
-function pollMaxMs(timeoutSeconds) {
+function pollMaxMs(maxWaitSeconds) {
     if (typeof __ESCLI_TEST__ === 'undefined' || __ESCLI_TEST__) {
         const value = Number(process.env.ESCLI_RESEARCH_MAX_POLL_MS);
         if (Number.isFinite(value) && value > 0)
             return Math.max(1, value);
     }
-    return timeoutSeconds ? Math.max(1, timeoutSeconds * 1000) : DEFAULT_MAX_POLL_MS;
+    return maxWaitSeconds ? Math.max(1, maxWaitSeconds * 1000) : DEFAULT_MAX_POLL_MS;
 }
 function timeoutMs(timeoutSeconds, defaultMs = DEFAULT_TIMEOUT_MS) {
     return Math.max(1, timeoutSeconds ? timeoutSeconds * 1000 : defaultMs);