guidinghand 0.1.0

package/dist/cjs/index.js

@@ -0,0 +1,281 @@
+"use strict";
+// GuidingHand SDK for JavaScript and TypeScript: the /v1 API (https://guidinghand.ai/openapi.json).
+// No dependencies: it uses the platform's fetch and WebCrypto (Node 18+, Deno, Bun, Cloudflare Workers).
+//
+//   import GuidingHand from 'guidinghand';
+//   const gh = new GuidingHand(); // reads GUIDINGHAND_API_KEY
+//   const session = await gh.sessions.create({ agent_id: 'billing' });
+//   // send session.invite_url to the person at the computer, then:
+//   await gh.sessions.waitForConnection(session.session_id);
+//   const task = await gh.tasks.run(session.session_id, { prompt: 'Turn on Dark Mode', onQuestion: async (q) => 'Work', onApproval: async () => true });
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GuidingHand = exports.WebhookVerificationError = exports.NeedsInputError = exports.SessionExpiredError = exports.TimeoutError = exports.APIConnectionError = exports.APIError = exports.RateLimitError = exports.ConflictError = exports.NotFoundError = exports.PermissionDeniedError = exports.PaymentRequiredError = exports.AuthenticationError = exports.InvalidRequestError = exports.GuidingHandError = exports.VERSION = void 0;
+exports.verifyWebhook = verifyWebhook;
+exports.VERSION = '0.1.0';
+// ---------- errors ----------
+class GuidingHandError extends Error {
+    status;
+    type;
+    body;
+    extra;
+    constructor(message, status = 0, type = 'error', body = null) {
+        super(message);
+        this.name = new.target.name;
+        this.status = status;
+        this.type = type;
+        this.body = body;
+        const e = body?.error;
+        this.extra = e ? Object.fromEntries(Object.entries(e).filter(([k]) => k !== 'type' && k !== 'message')) : {};
+    }
+}
+exports.GuidingHandError = GuidingHandError;
+class InvalidRequestError extends GuidingHandError {
+}
+exports.InvalidRequestError = InvalidRequestError;
+class AuthenticationError extends GuidingHandError {
+}
+exports.AuthenticationError = AuthenticationError;
+class PaymentRequiredError extends GuidingHandError {
+}
+exports.PaymentRequiredError = PaymentRequiredError;
+class PermissionDeniedError extends GuidingHandError {
+}
+exports.PermissionDeniedError = PermissionDeniedError;
+class NotFoundError extends GuidingHandError {
+}
+exports.NotFoundError = NotFoundError;
+class ConflictError extends GuidingHandError {
+}
+exports.ConflictError = ConflictError;
+class RateLimitError extends GuidingHandError {
+}
+exports.RateLimitError = RateLimitError;
+class APIError extends GuidingHandError {
+}
+exports.APIError = APIError;
+class APIConnectionError extends GuidingHandError {
+}
+exports.APIConnectionError = APIConnectionError;
+class TimeoutError extends GuidingHandError {
+}
+exports.TimeoutError = TimeoutError;
+class SessionExpiredError extends GuidingHandError {
+}
+exports.SessionExpiredError = SessionExpiredError;
+/** A task waits on a question or approval and `run()` got no handler for it. */
+class NeedsInputError extends GuidingHandError {
+    task;
+    constructor(task) { super(`The task is waiting for ${task.pending?.type === 'approval' ? 'an approval' : 'an answer'}; pass ${task.pending?.type === 'approval' ? 'onApproval' : 'onQuestion'} to run().`, 0, 'needs_input'); this.task = task; }
+}
+exports.NeedsInputError = NeedsInputError;
+class WebhookVerificationError extends GuidingHandError {
+}
+exports.WebhookVerificationError = WebhookVerificationError;
+const BY_STATUS = { 400: InvalidRequestError, 401: AuthenticationError, 402: PaymentRequiredError, 403: PermissionDeniedError, 404: NotFoundError, 409: ConflictError, 413: InvalidRequestError, 429: RateLimitError };
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const env = (k) => (typeof process !== 'undefined' ? process.env?.[k] : undefined);
+class GuidingHand {
+    baseUrl;
+    agents;
+    sessions;
+    tasks;
+    webhook;
+    apiKey;
+    timeout;
+    maxRetries;
+    fetchImpl;
+    constructor(opts = {}) {
+        const key = opts.apiKey ?? env('GUIDINGHAND_API_KEY');
+        if (!key)
+            throw new AuthenticationError('No API key: pass { apiKey } or set GUIDINGHAND_API_KEY. Make one in the console under Settings → API keys.', 401, 'authentication');
+        this.apiKey = key;
+        this.baseUrl = (opts.baseUrl ?? env('GUIDINGHAND_BASE_URL') ?? 'https://guidinghand.ai').replace(/\/+$/, '');
+        this.timeout = opts.timeout ?? 60_000;
+        this.maxRetries = opts.maxRetries ?? 2;
+        this.fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);
+        this.agents = new Agents(this);
+        this.sessions = new Sessions(this);
+        this.tasks = new Tasks(this);
+        this.webhook = new WebhookEndpoint(this);
+    }
+    /** @internal */
+    async request(method, path, { query, body, retry, wait = 0, raw } = {}) {
+        const qs = query ? Object.entries(query).filter(([, v]) => v !== undefined && v !== null && v !== '').map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`).join('&') : '';
+        const url = `${this.baseUrl}/v1${path}${qs ? `?${qs}` : ''}`;
+        const canRetry = retry ?? (method === 'GET' || method === 'DELETE');
+        for (let attempt = 0;; attempt++) {
+            let res;
+            try {
+                res = await this.fetchImpl(url, {
+                    method,
+                    headers: { Authorization: `Bearer ${this.apiKey}`, 'User-Agent': `guidinghand-js/${exports.VERSION}`, ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}) },
+                    body: body !== undefined ? JSON.stringify(body) : undefined,
+                    signal: AbortSignal.timeout(this.timeout + wait),
+                });
+            }
+            catch (e) {
+                if (canRetry && attempt < this.maxRetries) {
+                    await sleep(500 * 2 ** attempt);
+                    continue;
+                }
+                const timedOut = e?.name === 'TimeoutError';
+                throw timedOut ? new TimeoutError(`No answer from ${this.baseUrl} in ${Math.round((this.timeout + wait) / 1000)} s.`, 0, 'timeout') : new APIConnectionError(`Couldn’t reach ${this.baseUrl}: ${e?.message ?? e}`, 0, 'connection');
+            }
+            if (res.ok)
+                return (raw ? new Uint8Array(await res.arrayBuffer()) : await res.json());
+            if (canRetry && attempt < this.maxRetries && (res.status === 429 || res.status >= 500)) {
+                const after = Number(res.headers.get('retry-after'));
+                await sleep(Number.isFinite(after) && after > 0 ? after * 1000 : 500 * 2 ** attempt);
+                continue;
+            }
+            const j = await res.json().catch(() => null);
+            const Err = BY_STATUS[res.status] ?? (res.status >= 500 ? APIError : GuidingHandError);
+            throw new Err(j?.error?.message ?? `The server answered ${res.status}.`, res.status, j?.error?.type ?? 'error', j);
+        }
+    }
+    /** @internal Every item of a paged list. */
+    async *pages(path, query) {
+        let cursor;
+        do {
+            const p = await this.request('GET', path, { query: { ...query, limit: 100, cursor } });
+            yield* p.data;
+            cursor = p.has_more ? p.next_cursor : null;
+        } while (cursor);
+    }
+}
+exports.GuidingHand = GuidingHand;
+exports.default = GuidingHand;
+class Resource {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+}
+const enc = encodeURIComponent;
+class Agents extends Resource {
+    list() { return this.client.request('GET', '/agents'); }
+    create(params) { return this.client.request('POST', '/agents', { body: params }); }
+    retrieve(agentId) { return this.client.request('GET', `/agents/${enc(agentId)}`); }
+    update(agentId, params) { return this.client.request('PATCH', `/agents/${enc(agentId)}`, { body: params }); }
+    delete(agentId) { return this.client.request('DELETE', `/agents/${enc(agentId)}`); }
+}
+class Sessions extends Resource {
+    /** Makes a code and its invite link. Send `invite_url` to the person at the computer. */
+    create(params = {}) { return this.client.request('POST', '/sessions', { body: params }); }
+    list(params = {}) { return this.client.request('GET', '/sessions', { query: params }); }
+    /** Every session, newest first, across pages. */
+    listAll(params = {}) { return this.client.pages('/sessions', params); }
+    retrieve(sessionId) { return this.client.request('GET', `/sessions/${enc(sessionId)}`); }
+    /** Disconnects the computer and deletes the session's tasks and recordings. */
+    delete(sessionId) { return this.client.request('DELETE', `/sessions/${enc(sessionId)}`); }
+    /** Resolves once the person's computer is connected. */
+    async waitForConnection(sessionId, { timeout = 600_000, pollInterval = 3_000 } = {}) {
+        const until = Date.now() + timeout;
+        for (;;) {
+            const s = await this.retrieve(sessionId);
+            if (s.status === 'connected')
+                return s;
+            if (s.status === 'expired')
+                throw new SessionExpiredError(`Session ${sessionId} expired before a computer connected. Make a new one.`, 0, 'session_expired');
+            if (Date.now() + pollInterval > until)
+                throw new TimeoutError(`No computer connected to ${sessionId} within ${Math.round(timeout / 1000)} s.`, 0, 'timeout');
+            await sleep(pollInterval);
+        }
+    }
+}
+class Tasks extends Resource {
+    /** Starts a task on the session's computer (it must be connected). */
+    create(sessionId, params) { return this.client.request('POST', `/sessions/${enc(sessionId)}/tasks`, { body: params, retry: !!params.request_id }); }
+    list(params = {}) { return this.client.request('GET', '/tasks', { query: params }); }
+    listAll(params = {}) { return this.client.pages('/tasks', params); }
+    retrieve(taskId, { include } = {}) { return this.client.request('GET', `/tasks/${enc(taskId)}`, { query: { include: include?.join(',') } }); }
+    /** Events after `after`; with `wait_ms`, waits (long poll) for the next one. */
+    events(taskId, { after = 0, wait_ms = 0 } = {}) {
+        return this.client.request('GET', `/tasks/${enc(taskId)}/events`, { query: { after, wait_ms }, wait: wait_ms });
+    }
+    respond(taskId, params) { return this.client.request('POST', `/tasks/${enc(taskId)}/respond`, { body: params }); }
+    stop(taskId) { return this.client.request('POST', `/tasks/${enc(taskId)}/stop`, { body: {} }); }
+    recording(taskId) { return this.client.request('GET', `/tasks/${enc(taskId)}/recording`); }
+    /** One recorded screen, as PNG bytes. */
+    recordingFrame(taskId, seq) { return this.client.request('GET', `/tasks/${enc(taskId)}/recording/${seq}`, { raw: true }); }
+    /** Every event of a task as it happens, until it's done. `for await (const e of gh.tasks.stream(id))` */
+    async *stream(taskId, { after = 0 } = {}) {
+        for (;;) {
+            const r = await this.events(taskId, { after, wait_ms: 25_000 });
+            for (const e of r.data)
+                yield e;
+            after = r.cursor;
+            if (r.task.done)
+                return r.task;
+        }
+    }
+    /** Starts a task and sees it through: events to onEvent, questions to onQuestion, approvals to onApproval. Resolves with the finished task. */
+    async run(sessionId, { onEvent, onQuestion, onApproval, timeout, ...params }) {
+        let task = await this.create(sessionId, params);
+        const until = timeout ? Date.now() + timeout : Infinity;
+        let after = 0, answered = '';
+        while (!task.done) {
+            if (Date.now() > until) {
+                await this.stop(task.task_id).catch(() => { });
+                throw new TimeoutError(`Task ${task.task_id} took longer than ${Math.round(timeout / 1000)} s; stopped it.`, 0, 'timeout');
+            }
+            const r = await this.events(task.task_id, { after, wait_ms: Math.min(25_000, Math.max(0, until - Date.now())) });
+            task = r.task;
+            after = r.cursor;
+            for (const e of r.data)
+                await onEvent?.(e, task);
+            const p = task.pending;
+            if (!p || task.done)
+                continue;
+            const id = p.type === 'question' ? p.question_id : p.approval_id;
+            if (id === answered)
+                continue; // answered already; the task is picking it up
+            if (p.type === 'question') {
+                if (!onQuestion)
+                    throw new NeedsInputError(task);
+                await this.respond(task.task_id, { question_id: p.question_id, answer: String(await onQuestion(p, task)) });
+            }
+            else {
+                if (!onApproval)
+                    throw new NeedsInputError(task);
+                const d = await onApproval(p, task);
+                const decision = typeof d === 'object' ? d : { decision: d === true || d === 'approve' ? 'approve' : 'deny' };
+                await this.respond(task.task_id, { approval_id: p.approval_id, ...decision });
+            }
+            answered = id;
+        }
+        return task;
+    }
+}
+// ---------- webhooks ----------
+class WebhookEndpoint extends Resource {
+    retrieve() { return this.client.request('GET', '/webhook'); }
+    /** Sets the endpoint. The signing secret is in the response when it's new (or with rotate_secret), never again. */
+    update(params) { return this.client.request('PUT', '/webhook', { body: params }); }
+    delete() { return this.client.request('PUT', '/webhook', { body: { url: null } }); }
+}
+/**
+ * Checks a webhook's GuidingHand-Signature header against the raw request body and your signing secret, and
+ * returns the parsed event. Throws WebhookVerificationError if it doesn't match or is older than `tolerance` s.
+ */
+async function verifyWebhook(payload, signatureHeader, secret, { tolerance = 300 } = {}) {
+    const fail = (m) => new WebhookVerificationError(m, 400, 'webhook_verification');
+    const parts = Object.fromEntries(String(signatureHeader ?? '').split(',').map((kv) => kv.trim().split('=')));
+    const t = Number(parts.t), v1 = parts.v1;
+    if (!t || !v1)
+        throw fail('Missing or malformed GuidingHand-Signature header.');
+    if (Math.abs(Date.now() / 1000 - t) > tolerance)
+        throw fail('The webhook’s timestamp is too old.');
+    const body = typeof payload === 'string' ? payload : new TextDecoder().decode(payload);
+    const key = await crypto.subtle.importKey('raw', new TextEncoder().encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const mac = new Uint8Array(await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(`${t}.${body}`)));
+    const want = [...mac].map((b) => b.toString(16).padStart(2, '0')).join('');
+    if (want.length !== v1.length)
+        throw fail('The webhook’s signature doesn’t match.');
+    let diff = 0;
+    for (let i = 0; i < want.length; i++)
+        diff |= want.charCodeAt(i) ^ v1.charCodeAt(i);
+    if (diff)
+        throw fail('The webhook’s signature doesn’t match.');
+    return JSON.parse(body);
+}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/esm/index.d.ts

@@ -0,0 +1,327 @@
+export declare const VERSION = "0.1.0";
+export type Metadata = Record<string, string>;
+export type Effort = 'low' | 'medium' | 'high' | null;
+export type Agent = {
+    object: 'agent';
+    agent_id: string;
+    name: string;
+    instructions: string;
+    effort: Effort;
+    greeting: string;
+    is_default: boolean;
+    invite_url_template: string;
+    created_at: string | null;
+    updated_at: string | null;
+};
+export type Device = {
+    os: 'mac' | 'windows' | 'linux' | 'unknown';
+    name: string | null;
+    width: number;
+    height: number;
+    app_version: string | null;
+};
+export type SessionStatus = 'waiting' | 'connected' | 'disconnected' | 'expired';
+export type Session = {
+    object: 'session';
+    session_id: string;
+    code: string;
+    agent_id: string;
+    invite_url: string;
+    status: SessionStatus;
+    device: Device | null;
+    metadata: Metadata;
+    created_at: string;
+    paired_at: string | null;
+    last_active_at: string;
+    expires_at: string | null;
+    task_count?: number;
+    latest_task_id?: string | null;
+};
+export type TaskStatus = 'queued' | 'running' | 'waiting_for_user' | 'waiting_for_approval' | 'completed' | 'failed' | 'stopped';
+export type Question = {
+    type: 'question';
+    question_id: string;
+    question: string;
+    options: string[];
+};
+export type Approval = {
+    type: 'approval';
+    approval_id: string;
+    action: string;
+    risk: 'low' | 'medium' | 'high';
+};
+export type EventType = 'started' | 'progress' | 'thinking' | 'action' | 'message' | 'question' | 'answer' | 'approval_required' | 'approved' | 'denied' | 'completed' | 'error' | 'stopped';
+export type TaskEvent = {
+    cursor: number;
+    type: EventType;
+    message: string;
+    ts: string;
+    data?: Record<string, unknown>;
+};
+export type Task = {
+    object: 'task';
+    task_id: string;
+    session_id: string;
+    agent_id: string;
+    status: TaskStatus;
+    done: boolean;
+    prompt: string;
+    result: string | null;
+    error: string | null;
+    pending: Question | Approval | null;
+    cursor?: number;
+    metadata: Metadata;
+    created_at: string;
+    updated_at: string;
+    active_seconds: number;
+    billed_minutes: number | null;
+    replay_url: string | null;
+    recording?: {
+        frames: number;
+    };
+    events?: TaskEvent[];
+    trace?: unknown[];
+    interrupted?: boolean;
+};
+export type Frame = {
+    seq: number;
+    t_ms: number;
+    after_event: number;
+    width: number;
+    height: number;
+    url: string;
+};
+export type Recording = {
+    object: 'recording';
+    task_id: string;
+    frames: Frame[];
+};
+export type WebhookEventType = 'session.connected' | 'session.disconnected' | 'task.started' | 'task.waiting_for_user' | 'task.waiting_for_approval' | 'task.completed' | 'task.failed' | 'task.stopped';
+export type Webhook = {
+    object: 'webhook';
+    url: string | null;
+    events: WebhookEventType[];
+    has_secret: boolean;
+    secret?: string;
+    event_types: WebhookEventType[];
+};
+export type WebhookEvent = {
+    id: string;
+    type: WebhookEventType;
+    created_at: string;
+    org_id: string;
+    data: {
+        task?: Task;
+        session?: Session;
+    };
+};
+export type Page<T> = {
+    data: T[];
+    has_more: boolean;
+    next_cursor: string | null;
+};
+export type Deleted = {
+    object: string;
+    deleted: true;
+};
+export declare class GuidingHandError extends Error {
+    status: number;
+    type: string;
+    body: unknown;
+    extra: Record<string, unknown>;
+    constructor(message: string, status?: number, type?: string, body?: unknown);
+}
+export declare class InvalidRequestError extends GuidingHandError {
+}
+export declare class AuthenticationError extends GuidingHandError {
+}
+export declare class PaymentRequiredError extends GuidingHandError {
+}
+export declare class PermissionDeniedError extends GuidingHandError {
+}
+export declare class NotFoundError extends GuidingHandError {
+}
+export declare class ConflictError extends GuidingHandError {
+}
+export declare class RateLimitError extends GuidingHandError {
+}
+export declare class APIError extends GuidingHandError {
+}
+export declare class APIConnectionError extends GuidingHandError {
+}
+export declare class TimeoutError extends GuidingHandError {
+}
+export declare class SessionExpiredError extends GuidingHandError {
+}
+/** A task waits on a question or approval and `run()` got no handler for it. */
+export declare class NeedsInputError extends GuidingHandError {
+    task: Task;
+    constructor(task: Task);
+}
+export declare class WebhookVerificationError extends GuidingHandError {
+}
+export type ClientOptions = {
+    /** An org API key (gh_live_…). Defaults to the GUIDINGHAND_API_KEY environment variable. */
+    apiKey?: string;
+    /** Defaults to https://guidinghand.ai (use https://dev.guidinghand.ai for Stripe test mode). */
+    baseUrl?: string;
+    /** Per request, in ms (long polls add their wait). Default 60 000. */
+    timeout?: number;
+    /** Retries on connection errors, 429 and 5xx, for reads and for starts with a request_id. Default 2. */
+    maxRetries?: number;
+    fetch?: typeof fetch;
+};
+type Req = {
+    query?: Record<string, string | number | undefined | null>;
+    body?: unknown;
+    retry?: boolean;
+    wait?: number;
+    raw?: boolean;
+};
+export declare class GuidingHand {
+    readonly baseUrl: string;
+    readonly agents: Agents;
+    readonly sessions: Sessions;
+    readonly tasks: Tasks;
+    readonly webhook: WebhookEndpoint;
+    private apiKey;
+    private timeout;
+    private maxRetries;
+    private fetchImpl;
+    constructor(opts?: ClientOptions);
+    /** @internal */
+    request<T>(method: string, path: string, { query, body, retry, wait, raw }?: Req): Promise<T>;
+    /** @internal Every item of a paged list. */
+    pages<T>(path: string, query: Record<string, string | number | undefined | null>): AsyncGenerator<T>;
+}
+export default GuidingHand;
+declare class Resource {
+    protected client: GuidingHand;
+    constructor(client: GuidingHand);
+}
+export type AgentCreate = {
+    name: string;
+    agent_id?: string;
+    instructions?: string;
+    effort?: Effort;
+    greeting?: string;
+};
+export type AgentUpdate = Partial<Omit<AgentCreate, 'agent_id'>>;
+declare class Agents extends Resource {
+    list(): Promise<Page<Agent>>;
+    create(params: AgentCreate): Promise<Agent>;
+    retrieve(agentId: string): Promise<Agent>;
+    update(agentId: string, params: AgentUpdate): Promise<Agent>;
+    delete(agentId: string): Promise<Deleted>;
+}
+export type SessionCreate = {
+    agent_id?: string;
+    metadata?: Metadata;
+};
+export type SessionList = {
+    agent_id?: string;
+    limit?: number;
+    cursor?: string;
+};
+declare class Sessions extends Resource {
+    /** Makes a code and its invite link. Send `invite_url` to the person at the computer. */
+    create(params?: SessionCreate): Promise<Session & {
+        session_token: string;
+    }>;
+    list(params?: SessionList): Promise<Page<Session>>;
+    /** Every session, newest first, across pages. */
+    listAll(params?: Omit<SessionList, 'limit' | 'cursor'>): AsyncGenerator<Session>;
+    retrieve(sessionId: string): Promise<Session>;
+    /** Disconnects the computer and deletes the session's tasks and recordings. */
+    delete(sessionId: string): Promise<Deleted>;
+    /** Resolves once the person's computer is connected. */
+    waitForConnection(sessionId: string, { timeout, pollInterval }?: {
+        timeout?: number;
+        pollInterval?: number;
+    }): Promise<Session>;
+}
+export type TaskCreate = {
+    prompt: string;
+    agent_id?: string;
+    request_id?: string;
+    metadata?: Metadata;
+};
+export type TaskList = {
+    session_id?: string;
+    agent_id?: string;
+    status?: TaskStatus;
+    limit?: number;
+    cursor?: string;
+};
+export type Respond = {
+    question_id: string;
+    answer: string;
+} | {
+    approval_id: string;
+    decision: 'approve' | 'deny';
+    note?: string;
+};
+export type RunOptions = TaskCreate & {
+    /** Every event, as it happens. */
+    onEvent?: (event: TaskEvent, task: Task) => void | Promise<void>;
+    /** The agent asks something: return the answer. */
+    onQuestion?: (question: Question, task: Task) => string | Promise<string>;
+    /** The agent wants to do something consequential: return true (or 'approve') to let it, false (or 'deny', or { decision, note }) not to. */
+    onApproval?: (approval: Approval, task: Task) => boolean | 'approve' | 'deny' | {
+        decision: 'approve' | 'deny';
+        note?: string;
+    } | Promise<boolean | 'approve' | 'deny' | {
+        decision: 'approve' | 'deny';
+        note?: string;
+    }>;
+    /** Give up (and stop the task) after this long, in ms. */
+    timeout?: number;
+};
+declare class Tasks extends Resource {
+    /** Starts a task on the session's computer (it must be connected). */
+    create(sessionId: string, params: TaskCreate): Promise<Task>;
+    list(params?: TaskList): Promise<Page<Task>>;
+    listAll(params?: Omit<TaskList, 'limit' | 'cursor'>): AsyncGenerator<Task>;
+    retrieve(taskId: string, { include }?: {
+        include?: ('events' | 'trace')[];
+    }): Promise<Task>;
+    /** Events after `after`; with `wait_ms`, waits (long poll) for the next one. */
+    events(taskId: string, { after, wait_ms }?: {
+        after?: number;
+        wait_ms?: number;
+    }): Promise<{
+        data: TaskEvent[];
+        cursor: number;
+        task: Task;
+    }>;
+    respond(taskId: string, params: Respond): Promise<Task>;
+    stop(taskId: string): Promise<Task & {
+        interrupted: boolean;
+    }>;
+    recording(taskId: string): Promise<Recording>;
+    /** One recorded screen, as PNG bytes. */
+    recordingFrame(taskId: string, seq: number): Promise<Uint8Array>;
+    /** Every event of a task as it happens, until it's done. `for await (const e of gh.tasks.stream(id))` */
+    stream(taskId: string, { after }?: {
+        after?: number;
+    }): AsyncGenerator<TaskEvent, Task>;
+    /** Starts a task and sees it through: events to onEvent, questions to onQuestion, approvals to onApproval. Resolves with the finished task. */
+    run(sessionId: string, { onEvent, onQuestion, onApproval, timeout, ...params }: RunOptions): Promise<Task>;
+}
+declare class WebhookEndpoint extends Resource {
+    retrieve(): Promise<Webhook>;
+    /** Sets the endpoint. The signing secret is in the response when it's new (or with rotate_secret), never again. */
+    update(params: {
+        url: string;
+        events?: WebhookEventType[];
+        rotate_secret?: boolean;
+    }): Promise<Webhook>;
+    delete(): Promise<Webhook>;
+}
+/**
+ * Checks a webhook's GuidingHand-Signature header against the raw request body and your signing secret, and
+ * returns the parsed event. Throws WebhookVerificationError if it doesn't match or is older than `tolerance` s.
+ */
+export declare function verifyWebhook(payload: string | Uint8Array, signatureHeader: string | null | undefined, secret: string, { tolerance }?: {
+    tolerance?: number;
+}): Promise<WebhookEvent>;