guidinghand 0.1.1 → 0.3.0

package/README.md

@@ -26,8 +26,8 @@ await gh.sessions.waitForConnection(session.session_id);
 const task = await gh.tasks.run(session.session_id, {
   prompt: 'Turn on Dark Mode',
   onEvent: (e) => console.log(e.type, e.message),
-  onQuestion: async (q) => 'Work',              // q.question, q.options
-  onApproval: async (a) => a.risk !== 'high',   // true/'approve' or false/'deny'
+  onQuestion: async (q) => 'Work',              // q.question, q.options (leave it out to let the customer answer on their screen)
+  onApproval: async (a) => a.risk !== 'high',   // true/'approve' or false/'deny' (leave it out to let the customer decide on their screen)
 });
 
 console.log(task.status, task.result);  // completed "Dark Mode is on."
@@ -36,11 +36,12 @@ console.log('Replay:', task.replay_url);
 
 ## Agents
 
-An agent is your configuration: instructions (added under GuidingHand's own rules, which always win), effort and a greeting for the invite page. Every org has a `default` agent.
+An agent is your configuration: instructions (added under GuidingHand's own rules, which always win), effort, a greeting for the invite page, and what the customer sees and may do on their screen. Every org has a `default` agent.
 
 ```ts
 await gh.agents.create({ agent_id: 'billing', name: 'Billing help', instructions: 'Open the Billing app from the Dock.', effort: 'medium', greeting: 'Hi, this is Acme billing.' });
 await gh.agents.update('billing', { effort: 'high' });
+await gh.agents.update('billing', { display_name: 'Acme Support', narration: true, customer_answers: false, customer_approvals: false }); // on their screen
 const { data } = await gh.agents.list();
 await gh.agents.delete('billing');
 ```
@@ -72,6 +73,30 @@ const page = await gh.tasks.list({ status: 'completed', limit: 50 });    // { da
 for await (const t of gh.tasks.listAll({ agent_id: 'billing' })) { /* every page */ }
 ```
 
+## Questions and approvals the customer answers
+
+Unless the agent turns it off (`customer_answers: false`), the agent's questions also appear on the customer's screen, and they can answer them there. `question.customer_can_answer` says whether they can answer the open one. The first answer is used, from them or from you.
+
+- Without `onQuestion`, `run()` leaves those questions to the customer and keeps following the task (pass `timeout` to give up eventually). It throws `NeedsInputError` only for a question they can't answer.
+- With `onQuestion`, return `null` to leave one to them (say, when `q.customer_can_answer` is true). If they answer while your handler works, your answer is refused with a 409 and `run()` carries on.
+- `respond()` after they answered throws `ConflictError` with `extra.code === 'already_answered'` and `extra.answered_by === 'customer'`.
+- The `answer` event has `data.answered_by` (`'customer'` or `'operator'`), and the `task.question_answered` webhook carries the answer and who gave it.
+
+Approvals work the same way. Unless the agent turns it off (`customer_approvals: false`), the customer can approve or deny the agent's approval requests on their screen, and `approval.customer_can_approve` says whether they can decide the open one.
+
+- Without `onApproval`, `run()` leaves those approvals to the customer and keeps following. With `onApproval`, return `null` to leave one to them.
+- `respond()` after they decided throws `ConflictError` with `extra.code === 'already_answered'` and `extra.answered_by === 'customer'`.
+- The `approved` and `denied` events have `data.answered_by`, and the `task.approval_decided` webhook carries the decision and who made it.
+
+```ts
+const task = await gh.tasks.run(sessionId, {
+  prompt: 'Set up the office printer',
+  onEvent: (e) => { if (e.type === 'answer') console.log(`${e.data?.answered_by} answered: ${e.message}`); },
+  onQuestion: async (q) => (q.customer_can_answer ? null : askMyTeam(q.question, q.options)),
+  onApproval: async (a) => (a.customer_can_approve && a.risk !== 'high' ? null : askMyTeamToApprove(a.action)),
+});
+```
+
 ## Recordings
 
 ```ts
@@ -84,7 +109,7 @@ The console replays them with the agent's cursor at `task.replay_url`.
 ## Webhooks
 
 ```ts
-const { secret } = await gh.webhook.update({ url: 'https://example.com/guidinghand', events: ['task.completed', 'task.waiting_for_user'] });
+const { secret } = await gh.webhook.update({ url: 'https://example.com/guidinghand', events: ['task.completed', 'task.waiting_for_user', 'task.question_answered', 'task.approval_decided'] });
 ```
 
 Verify each delivery with the raw request body:
@@ -95,6 +120,8 @@ import { verifyWebhook } from 'guidinghand';
 app.post('/guidinghand', express.raw({ type: 'application/json' }), async (req, res) => {
   const event = await verifyWebhook(req.body, req.header('GuidingHand-Signature'), process.env.GUIDINGHAND_WEBHOOK_SECRET);
   if (event.type === 'task.completed') console.log(event.data.task.result);
+  if (event.type === 'task.question_answered') console.log(event.data.answer.answered_by, event.data.answer.answer);
+  if (event.type === 'task.approval_decided') console.log(event.data.decision.answered_by, event.data.decision.decision);
   res.sendStatus(200);
 });
 ```
@@ -110,11 +137,11 @@ Every error is a `GuidingHandError` with `status`, `type`, `message` and `extra`
 | `PaymentRequiredError` | 402 | the org's plan doesn't allow it (free minutes used up) |
 | `PermissionDeniedError` | 403 | your role can't do this |
 | `NotFoundError` | 404 | not in this org |
-| `ConflictError` | 409 | no computer connected, a task already running (`extra.active_task_id`), nothing pending |
+| `ConflictError` | 409 | no computer connected, a task already running (`extra.active_task_id`), nothing pending, or already answered or decided (`extra.code: 'already_answered'`, `extra.answered_by`) |
 | `RateLimitError` | 429 | too many requests, or the plan's tasks at once |
 | `APIError` | 5xx | our side |
 | `APIConnectionError`, `TimeoutError` | | network |
-| `NeedsInputError` | | `run()` got a question or approval without a handler (`error.task`) |
+| `NeedsInputError` | | `run()` got a question or approval (that the customer can't answer or decide) without a handler (`error.task`) |
 | `SessionExpiredError` | | `waitForConnection()` on a code that expired |
 
 Reads, deletes and starts with a `request_id` are retried on connection errors, 429 and 5xx (`maxRetries`, default 2).

package/dist/cjs/index.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.1.1";
+export declare const VERSION = "0.3.0";
 export type Metadata = Record<string, string>;
 export type Effort = 'low' | 'medium' | 'high' | null;
 export type Agent = {
@@ -8,6 +8,14 @@ export type Agent = {
     instructions: string;
     effort: Effort;
     greeting: string;
+    /** What the app calls the agent on the person's screen; '' is "GuidingHand". */
+    display_name: string;
+    /** The app shows the agent's thoughts and steps on the person's screen as it works. */
+    narration: boolean;
+    /** The person at the computer can answer the agent's questions in the app (the team still can; the first answer is used). */
+    customer_answers: boolean;
+    /** The person at the computer can approve or deny the agent's approval requests in the app (the team still can; the first decision is used). */
+    customer_approvals: boolean;
     is_default: boolean;
     invite_url_template: string;
     created_at: string | null;
@@ -38,19 +46,29 @@ export type Session = {
     latest_task_id?: string | null;
 };
 export type TaskStatus = 'queued' | 'running' | 'waiting_for_user' | 'waiting_for_approval' | 'completed' | 'failed' | 'stopped';
+/** customer_can_answer: the person at the computer can answer it on their screen too (the first answer is used). */
 export type Question = {
     type: 'question';
     question_id: string;
     question: string;
     options: string[];
+    customer_can_answer: boolean;
 };
+/** customer_can_approve: the person at the computer can approve or deny it on their screen too (the first decision is used). */
 export type Approval = {
     type: 'approval';
     approval_id: string;
     action: string;
     risk: 'low' | 'medium' | 'high';
+    customer_can_approve: boolean;
 };
 export type EventType = 'started' | 'progress' | 'thinking' | 'action' | 'message' | 'question' | 'answer' | 'approval_required' | 'approved' | 'denied' | 'completed' | 'error' | 'stopped';
+/** Who answered a question or decided an approval: the person at the computer ('customer', in the app) or your team ('operator': the API or the console). */
+export type AnsweredBy = 'customer' | 'operator';
+/**
+ * data: e.g. { action } for 'action', { question_id, question, options } for 'question', { question_id, answered_by } for 'answer'
+ * (whose message is the answer), { approval_id, answered_by, note? } for 'approved' and 'denied'.
+ */
 export type TaskEvent = {
     cursor: number;
     type: EventType;
@@ -96,7 +114,7 @@ export type 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 WebhookEventType = 'session.connected' | 'session.disconnected' | 'task.started' | 'task.waiting_for_user' | 'task.question_answered' | 'task.waiting_for_approval' | 'task.approval_decided' | 'task.completed' | 'task.failed' | 'task.stopped';
 export type Webhook = {
     object: 'webhook';
     url: string | null;
@@ -105,6 +123,18 @@ export type Webhook = {
     secret?: string;
     event_types: WebhookEventType[];
 };
+export type QuestionAnswer = {
+    question_id: string;
+    answer: string;
+    answered_by: AnsweredBy;
+};
+export type ApprovalDecision = {
+    approval_id: string;
+    decision: 'approve' | 'deny';
+    note: string | null;
+    answered_by: AnsweredBy;
+};
+/** data.answer: for task.question_answered. data.decision: for task.approval_decided. */
 export type WebhookEvent = {
     id: string;
     type: WebhookEventType;
@@ -113,6 +143,8 @@ export type WebhookEvent = {
     data: {
         task?: Task;
         session?: Session;
+        answer?: QuestionAnswer;
+        decision?: ApprovalDecision;
     };
 };
 export type Page<T> = {
@@ -141,6 +173,7 @@ export declare class PermissionDeniedError extends GuidingHandError {
 }
 export declare class NotFoundError extends GuidingHandError {
 }
+/** 409. From respond(): extra.code is 'already_answered' when someone answered or decided first (extra.answered_by: 'customer' is the person at the computer), else 'not_pending'. */
 export declare class ConflictError extends GuidingHandError {
 }
 export declare class RateLimitError extends GuidingHandError {
@@ -153,7 +186,7 @@ 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. */
+/** A task waits on a question or approval and `run()` got no handler for it (one the person at the computer can answer or decide is left to them instead). */
 export declare class NeedsInputError extends GuidingHandError {
     task: Task;
     constructor(task: Task);
@@ -205,6 +238,10 @@ export type AgentCreate = {
     instructions?: string;
     effort?: Effort;
     greeting?: string;
+    display_name?: string;
+    narration?: boolean;
+    customer_answers?: boolean;
+    customer_approvals?: boolean;
 };
 export type AgentUpdate = Partial<Omit<AgentCreate, 'agent_id'>>;
 declare class Agents extends Resource {
@@ -261,19 +298,27 @@ export type Respond = {
     decision: 'approve' | 'deny';
     note?: string;
 };
+/** null leaves the approval to the person at the computer when they can decide it (customer_can_approve); otherwise it denies. */
+export type ApprovalReply = boolean | 'approve' | 'deny' | {
+    decision: 'approve' | 'deny';
+    note?: string;
+} | null | undefined;
 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;
-    }>;
+    /**
+     * The agent asks something: return the answer. When the person at the computer can answer it on their screen
+     * (question.customer_can_answer), return null to leave it to them; without onQuestion, run() does that for
+     * every such question and throws NeedsInputError only for the others. If they answer first, yours is dropped.
+     */
+    onQuestion?: (question: Question, task: Task) => string | null | undefined | Promise<string | null | undefined>;
+    /**
+     * The agent wants to do something consequential: return true (or 'approve') to let it, false (or 'deny', or
+     * { decision, note }) not to. When the person at the computer can decide it on their screen
+     * (approval.customer_can_approve), return null to leave it to them; without onApproval, run() does that for
+     * every such approval and throws NeedsInputError only for the others. If they decide first, yours is dropped.
+     */
+    onApproval?: (approval: Approval, task: Task) => ApprovalReply | Promise<ApprovalReply>;
     /** Give up (and stop the task) after this long, in ms. */
     timeout?: number;
 };
@@ -305,7 +350,7 @@ declare class Tasks extends Resource {
     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. */
+    /** Starts a task and sees it through: events to onEvent, questions to onQuestion and approvals to onApproval (or the person at the computer). Resolves with the finished task. */
     run(sessionId: string, { onEvent, onQuestion, onApproval, timeout, ...params }: RunOptions): Promise<Task>;
 }
 declare class WebhookEndpoint extends Resource {

package/dist/cjs/index.js

@@ -8,10 +8,11 @@
 //   // 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 });
+//   // (without onQuestion or onApproval, what the person at the computer can answer or decide on their screen is left to them)
 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.1';
+exports.VERSION = '0.3.0';
 // ---------- errors ----------
 class GuidingHandError extends Error {
     status;
@@ -44,6 +45,7 @@ exports.PermissionDeniedError = PermissionDeniedError;
 class NotFoundError extends GuidingHandError {
 }
 exports.NotFoundError = NotFoundError;
+/** 409. From respond(): extra.code is 'already_answered' when someone answered or decided first (extra.answered_by: 'customer' is the person at the computer), else 'not_pending'. */
 class ConflictError extends GuidingHandError {
 }
 exports.ConflictError = ConflictError;
@@ -62,7 +64,7 @@ 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. */
+/** A task waits on a question or approval and `run()` got no handler for it (one the person at the computer can answer or decide is left to them instead). */
 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; }
@@ -212,7 +214,7 @@ class Tasks extends Resource {
                 return r.task;
         }
     }
-    /** Starts a task and sees it through: events to onEvent, questions to onQuestion, approvals to onApproval. Resolves with the finished task. */
+    /** Starts a task and sees it through: events to onEvent, questions to onQuestion and approvals to onApproval (or the person at the computer). 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;
@@ -234,23 +236,35 @@ class Tasks extends Resource {
                 continue;
             const id = p.type === 'question' ? p.question_id : p.approval_id;
             if (id === answered)
-                continue; // answered already; the task is picking it up
+                continue; // answered or decided already (or left to the person at the computer); the task is picking it up
             try {
                 if (p.type === 'question') {
-                    if (!onQuestion)
+                    // Without onQuestion, or when it returns nothing, a question the person at the computer can answer on
+                    // their screen is left to them: keep following.
+                    if (!onQuestion && !p.customer_can_answer)
                         throw new NeedsInputError(task);
-                    await this.respond(task.task_id, { question_id: p.question_id, answer: String(await onQuestion(p, task)) });
+                    const reply = onQuestion ? await onQuestion(p, task) : null;
+                    if (reply !== null && reply !== undefined)
+                        await this.respond(task.task_id, { question_id: p.question_id, answer: String(reply) });
+                    else if (!p.customer_can_answer)
+                        throw new TypeError('onQuestion returned no answer, and the person at the computer can’t answer this question (customer_can_answer is false).');
                 }
                 else {
-                    if (!onApproval)
+                    // The same for an approval the person at the computer can decide on their screen.
+                    if (!onApproval && !p.customer_can_approve)
                         throw new NeedsInputError(task);
-                    const d = await onApproval(p, task);
-                    const decision = d && typeof d === 'object' ? d : { decision: d === true || d === 'approve' ? 'approve' : 'deny' };
-                    await this.respond(task.task_id, { approval_id: p.approval_id, ...decision });
+                    const d = onApproval ? await onApproval(p, task) : null;
+                    // null leaves it to the person at the computer when they can decide it; otherwise it denies, as before.
+                    if ((d === null || d === undefined) && p.customer_can_approve) { /* theirs */ }
+                    else {
+                        const decision = d && typeof d === 'object' ? d : { decision: d === true || d === 'approve' ? 'approve' : 'deny' };
+                        await this.respond(task.task_id, { approval_id: p.approval_id, ...decision });
+                    }
                 }
             }
             catch (e) {
-                // Answered from somewhere else (the console, another process) or the task ended meanwhile: keep following.
+                // Answered or decided somewhere else first (the person at the computer, the console, another process: extra.code
+                // 'already_answered') or the task ended meanwhile: keep following.
                 if (!(e instanceof ConflictError))
                     throw e;
             }

package/dist/esm/index.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.1.1";
+export declare const VERSION = "0.3.0";
 export type Metadata = Record<string, string>;
 export type Effort = 'low' | 'medium' | 'high' | null;
 export type Agent = {
@@ -8,6 +8,14 @@ export type Agent = {
     instructions: string;
     effort: Effort;
     greeting: string;
+    /** What the app calls the agent on the person's screen; '' is "GuidingHand". */
+    display_name: string;
+    /** The app shows the agent's thoughts and steps on the person's screen as it works. */
+    narration: boolean;
+    /** The person at the computer can answer the agent's questions in the app (the team still can; the first answer is used). */
+    customer_answers: boolean;
+    /** The person at the computer can approve or deny the agent's approval requests in the app (the team still can; the first decision is used). */
+    customer_approvals: boolean;
     is_default: boolean;
     invite_url_template: string;
     created_at: string | null;
@@ -38,19 +46,29 @@ export type Session = {
     latest_task_id?: string | null;
 };
 export type TaskStatus = 'queued' | 'running' | 'waiting_for_user' | 'waiting_for_approval' | 'completed' | 'failed' | 'stopped';
+/** customer_can_answer: the person at the computer can answer it on their screen too (the first answer is used). */
 export type Question = {
     type: 'question';
     question_id: string;
     question: string;
     options: string[];
+    customer_can_answer: boolean;
 };
+/** customer_can_approve: the person at the computer can approve or deny it on their screen too (the first decision is used). */
 export type Approval = {
     type: 'approval';
     approval_id: string;
     action: string;
     risk: 'low' | 'medium' | 'high';
+    customer_can_approve: boolean;
 };
 export type EventType = 'started' | 'progress' | 'thinking' | 'action' | 'message' | 'question' | 'answer' | 'approval_required' | 'approved' | 'denied' | 'completed' | 'error' | 'stopped';
+/** Who answered a question or decided an approval: the person at the computer ('customer', in the app) or your team ('operator': the API or the console). */
+export type AnsweredBy = 'customer' | 'operator';
+/**
+ * data: e.g. { action } for 'action', { question_id, question, options } for 'question', { question_id, answered_by } for 'answer'
+ * (whose message is the answer), { approval_id, answered_by, note? } for 'approved' and 'denied'.
+ */
 export type TaskEvent = {
     cursor: number;
     type: EventType;
@@ -96,7 +114,7 @@ export type 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 WebhookEventType = 'session.connected' | 'session.disconnected' | 'task.started' | 'task.waiting_for_user' | 'task.question_answered' | 'task.waiting_for_approval' | 'task.approval_decided' | 'task.completed' | 'task.failed' | 'task.stopped';
 export type Webhook = {
     object: 'webhook';
     url: string | null;
@@ -105,6 +123,18 @@ export type Webhook = {
     secret?: string;
     event_types: WebhookEventType[];
 };
+export type QuestionAnswer = {
+    question_id: string;
+    answer: string;
+    answered_by: AnsweredBy;
+};
+export type ApprovalDecision = {
+    approval_id: string;
+    decision: 'approve' | 'deny';
+    note: string | null;
+    answered_by: AnsweredBy;
+};
+/** data.answer: for task.question_answered. data.decision: for task.approval_decided. */
 export type WebhookEvent = {
     id: string;
     type: WebhookEventType;
@@ -113,6 +143,8 @@ export type WebhookEvent = {
     data: {
         task?: Task;
         session?: Session;
+        answer?: QuestionAnswer;
+        decision?: ApprovalDecision;
     };
 };
 export type Page<T> = {
@@ -141,6 +173,7 @@ export declare class PermissionDeniedError extends GuidingHandError {
 }
 export declare class NotFoundError extends GuidingHandError {
 }
+/** 409. From respond(): extra.code is 'already_answered' when someone answered or decided first (extra.answered_by: 'customer' is the person at the computer), else 'not_pending'. */
 export declare class ConflictError extends GuidingHandError {
 }
 export declare class RateLimitError extends GuidingHandError {
@@ -153,7 +186,7 @@ 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. */
+/** A task waits on a question or approval and `run()` got no handler for it (one the person at the computer can answer or decide is left to them instead). */
 export declare class NeedsInputError extends GuidingHandError {
     task: Task;
     constructor(task: Task);
@@ -205,6 +238,10 @@ export type AgentCreate = {
     instructions?: string;
     effort?: Effort;
     greeting?: string;
+    display_name?: string;
+    narration?: boolean;
+    customer_answers?: boolean;
+    customer_approvals?: boolean;
 };
 export type AgentUpdate = Partial<Omit<AgentCreate, 'agent_id'>>;
 declare class Agents extends Resource {
@@ -261,19 +298,27 @@ export type Respond = {
     decision: 'approve' | 'deny';
     note?: string;
 };
+/** null leaves the approval to the person at the computer when they can decide it (customer_can_approve); otherwise it denies. */
+export type ApprovalReply = boolean | 'approve' | 'deny' | {
+    decision: 'approve' | 'deny';
+    note?: string;
+} | null | undefined;
 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;
-    }>;
+    /**
+     * The agent asks something: return the answer. When the person at the computer can answer it on their screen
+     * (question.customer_can_answer), return null to leave it to them; without onQuestion, run() does that for
+     * every such question and throws NeedsInputError only for the others. If they answer first, yours is dropped.
+     */
+    onQuestion?: (question: Question, task: Task) => string | null | undefined | Promise<string | null | undefined>;
+    /**
+     * The agent wants to do something consequential: return true (or 'approve') to let it, false (or 'deny', or
+     * { decision, note }) not to. When the person at the computer can decide it on their screen
+     * (approval.customer_can_approve), return null to leave it to them; without onApproval, run() does that for
+     * every such approval and throws NeedsInputError only for the others. If they decide first, yours is dropped.
+     */
+    onApproval?: (approval: Approval, task: Task) => ApprovalReply | Promise<ApprovalReply>;
     /** Give up (and stop the task) after this long, in ms. */
     timeout?: number;
 };
@@ -305,7 +350,7 @@ declare class Tasks extends Resource {
     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. */
+    /** Starts a task and sees it through: events to onEvent, questions to onQuestion and approvals to onApproval (or the person at the computer). Resolves with the finished task. */
     run(sessionId: string, { onEvent, onQuestion, onApproval, timeout, ...params }: RunOptions): Promise<Task>;
 }
 declare class WebhookEndpoint extends Resource {

package/dist/esm/index.js

@@ -7,7 +7,8 @@
 //   // 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 });
-export const VERSION = '0.1.1';
+//   // (without onQuestion or onApproval, what the person at the computer can answer or decide on their screen is left to them)
+export const VERSION = '0.3.0';
 // ---------- errors ----------
 export class GuidingHandError extends Error {
     status;
@@ -34,6 +35,7 @@ export class PermissionDeniedError extends GuidingHandError {
 }
 export class NotFoundError extends GuidingHandError {
 }
+/** 409. From respond(): extra.code is 'already_answered' when someone answered or decided first (extra.answered_by: 'customer' is the person at the computer), else 'not_pending'. */
 export class ConflictError extends GuidingHandError {
 }
 export class RateLimitError extends GuidingHandError {
@@ -46,7 +48,7 @@ export class TimeoutError extends GuidingHandError {
 }
 export class SessionExpiredError extends GuidingHandError {
 }
-/** A task waits on a question or approval and `run()` got no handler for it. */
+/** A task waits on a question or approval and `run()` got no handler for it (one the person at the computer can answer or decide is left to them instead). */
 export 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; }
@@ -193,7 +195,7 @@ class Tasks extends Resource {
                 return r.task;
         }
     }
-    /** Starts a task and sees it through: events to onEvent, questions to onQuestion, approvals to onApproval. Resolves with the finished task. */
+    /** Starts a task and sees it through: events to onEvent, questions to onQuestion and approvals to onApproval (or the person at the computer). 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;
@@ -215,23 +217,35 @@ class Tasks extends Resource {
                 continue;
             const id = p.type === 'question' ? p.question_id : p.approval_id;
             if (id === answered)
-                continue; // answered already; the task is picking it up
+                continue; // answered or decided already (or left to the person at the computer); the task is picking it up
             try {
                 if (p.type === 'question') {
-                    if (!onQuestion)
+                    // Without onQuestion, or when it returns nothing, a question the person at the computer can answer on
+                    // their screen is left to them: keep following.
+                    if (!onQuestion && !p.customer_can_answer)
                         throw new NeedsInputError(task);
-                    await this.respond(task.task_id, { question_id: p.question_id, answer: String(await onQuestion(p, task)) });
+                    const reply = onQuestion ? await onQuestion(p, task) : null;
+                    if (reply !== null && reply !== undefined)
+                        await this.respond(task.task_id, { question_id: p.question_id, answer: String(reply) });
+                    else if (!p.customer_can_answer)
+                        throw new TypeError('onQuestion returned no answer, and the person at the computer can’t answer this question (customer_can_answer is false).');
                 }
                 else {
-                    if (!onApproval)
+                    // The same for an approval the person at the computer can decide on their screen.
+                    if (!onApproval && !p.customer_can_approve)
                         throw new NeedsInputError(task);
-                    const d = await onApproval(p, task);
-                    const decision = d && typeof d === 'object' ? d : { decision: d === true || d === 'approve' ? 'approve' : 'deny' };
-                    await this.respond(task.task_id, { approval_id: p.approval_id, ...decision });
+                    const d = onApproval ? await onApproval(p, task) : null;
+                    // null leaves it to the person at the computer when they can decide it; otherwise it denies, as before.
+                    if ((d === null || d === undefined) && p.customer_can_approve) { /* theirs */ }
+                    else {
+                        const decision = d && typeof d === 'object' ? d : { decision: d === true || d === 'approve' ? 'approve' : 'deny' };
+                        await this.respond(task.task_id, { approval_id: p.approval_id, ...decision });
+                    }
                 }
             }
             catch (e) {
-                // Answered from somewhere else (the console, another process) or the task ended meanwhile: keep following.
+                // Answered or decided somewhere else first (the person at the computer, the console, another process: extra.code
+                // 'already_answered') or the task ended meanwhile: keep following.
                 if (!(e instanceof ConflictError))
                     throw e;
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "guidinghand",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "GuidingHand SDK: put an AI agent on your customer's computer with one link. Sessions, tasks, agents, recordings and webhooks.",
   "license": "MIT",
   "homepage": "https://guidinghand.ai",