TaskHandle

A TaskHandle represents a background agent run. Created via agent.run() or resumed via client.task(sessionId).

const task = await agent.run("Refactor the auth module");
// or
const task = client.task("task-session-id");

Properties

task.id

The underlying session ID for this task. Use it to resume the task from another process.

Type: string (readonly)

---

Methods

task.poll()

Check the task status without blocking.

const status = await task.poll();
// "accepted" | "busy" | "compacting" | "idle" | "error"

Returns: Promise<TaskStatus>

Status	Meaning
accepted	Task received, waiting to start
busy	Agent is working
compacting	Compacting context
idle	Finished successfully
error	Failed

---

task.result(opts?)

Block until the task completes or errors. Uses exponential backoff polling internally.

const result = await task.result({ timeoutMs: 300_000 });

console.log(result.status); // "completed" | "error"
console.log(result.text); // agent's final text output
console.log(result.messages); // full message history
console.log(result.tokens); // token usage
console.log(result.cost); // cost in USD

• timeoutMs number (default: 600000) — Maximum time to wait in milliseconds. Throws if exceeded.

Returns: Promise<TaskResult>

interface TaskResult {
    sessionId: string;
    status: "completed" | "error";
    text: string;
    messages: WithParts[];
    tokens?: Tokens;
    cost?: number;
}

---

task.cancel()

Cancel the running task. The underlying session is aborted.

await task.cancel();

Returns: Promise<void>

---

Patterns

Resume from another process

// Process A: launch and save the ID
const task = await agent.run("Update all dependencies");
saveToDatabase(task.id);

// Process B: resume and wait
const taskId = loadFromDatabase();
const resumed = client.task(taskId);
const result = await resumed.result();

With webhooks (no polling)

const task = await agent.run("Refactor auth module", {
    webhook: "https://my-app.com/hooks/agent-done",
});
// Your webhook receives the result when the task completes

Cleanup after completion

Tasks create sessions under the hood. Clean up when done:

const result = await task.result();
// ... process result ...
await client.session(task.id).end();