@threahq/remote-session 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Threa contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,219 @@
+# @threahq/remote-session
+
+SDK for connecting an agent runtime to a Threa scratchpad. A connector
+implements one hook, `deliverTurn`, and optionally a session-control actuator.
+The SDK links the scratchpad, claims work, keeps presence and claim leases
+alive, routes `/steer` and `/stop`, moves attachments in both directions, and
+posts interim and final replies. Claude Code and Pi connect to Threa through
+this package.
+
+The protocol underneath is public and documented at
+[threa.io/developers](https://threa.io/developers) (API reference sections
+`Bot runtimes` and `Bot invocations`, and the "Connect your local agent"
+recipe). This package is a client for it; nothing here needs a special server.
+
+## Install
+
+```sh
+npm install @threahq/remote-session
+```
+
+Node 20+ or Bun. Pulls in `@threahq/bot-runtime-client` (the socket transport)
+and `socket.io-client`.
+
+## Which flow you need
+
+Threa dispatches work to a bot in two ways, and the runtime kind you register
+with picks the one you get.
+
+Mention-driven. Someone `@mentions` the bot in any stream. Any live instance of
+the bot may claim the invocation, do the work, and complete it with a reply.
+Available to every runtime kind, including `custom`. This is `ThreaClient`
+plus the transport; see [`examples/mention-bot.ts`](examples/mention-bot.ts).
+
+Scratchpad-linked. The runtime owns a scratchpad: every message in it is a
+turn for the runtime, the composer offers `/steer`, `/stop`, and whatever
+commands the runtime advertises, and the runtime replies in place. This is
+`RemoteSession`, registering as runtime kind `custom`. See
+[`examples/echo-connector.ts`](examples/echo-connector.ts).
+
+## Credentials
+
+Create a bot in Threa (personal or workspace), give it the `mentionable` trait
+and, for a scratchpad-linked runtime, `active-scratchpad`. Mint a
+`threa_bk_` key on it with `bot-runtime:write`, `bot-invocations:write`,
+`messages:write`, `streams:read`, `messages:read`, and `attachments:read`
+(add `attachments:write` to send files back, `delegations:read` and
+`delegations:write` to run delegations). `loadConfig` reads
+`THREA_WORKSPACE_ID`, `THREA_API_KEY`, and optional `THREA_BASE_URL` (default
+`https://app.threa.io`) from the environment, or from a JSON file you pass in.
+
+## A connector
+
+```ts
+import { hostname } from "node:os"
+import {
+  RemoteSession,
+  ThreaClient,
+  loadConfig,
+  wireLifecycle,
+  type SessionControlActuator,
+} from "@threahq/remote-session"
+
+const identity = { idPrefix: "oc", sessionIdPrefix: "ocs", displayNamePrefix: "OpenClaw" }
+const result = loadConfig({ env: process.env, cwd: process.cwd(), hostname: hostname() }, identity)
+if ("error" in result) throw new Error(result.error)
+
+// Only when the connector can drive its runtime; omit it and Threa never
+// offers the commands.
+const sessionControl: SessionControlActuator = {
+  commands: ["stop", "steer", "model"],
+  interrupt: () => myRuntime.interrupt(),
+  runCommand: async (name, args) => ({ ok: true, message: await myRuntime.run(name, args) }),
+}
+
+const session = new RemoteSession({
+  config: result.config,
+  client: new ThreaClient(result.config),
+  runtime: {
+    kind: "custom",
+    busyStatusText: "Working in OpenClaw…",
+    forwardedNote: "Forwarded to OpenClaw.",
+    shutdownErrorMessage: "OpenClaw channel shut down",
+  },
+  delegate: {
+    // Push a turn into the runtime; resolve when handed off, not when answered.
+    deliverTurn: async (turn) => myRuntime.prompt(turn.content, turn.invocationId),
+    sessionControl,
+  },
+})
+
+wireLifecycle(session, process, { logPrefix: "[openclaw-channel]" })
+await session.start()
+
+// From inside the runtime, stream progress and close the turn:
+await session.sendInterim(invocationId, "halfway there")
+await session.reply(invocationId, "done, here is the result")
+```
+
+`start()` creates or resumes the scratchpad link for this identity (the
+identity is derived from hostname and working directory, so a restart in the
+same directory lands in the same scratchpad), opens the socket, and begins
+claiming. `deliverTurn` receives each turn with the prompt, any hydrated
+history, and downloaded attachments listed in the content.
+
+## Asking the user a question
+
+When the runtime hits a call it cannot make for itself — a tool approval, a
+fork in the plan — `requestDecision` posts it to the scratchpad as a decision
+card and resolves when the user answers it there:
+
+```ts
+const outcome = await session.requestDecision({
+  title: "Run `Bash`?",
+  body: "Delete the build directory",
+  options: [
+    { id: "allow", label: "Allow", tone: "primary" },
+    { id: "deny", label: "Deny", tone: "destructive" },
+  ],
+  allowNote: true,
+  externalRef: requestId,
+  expiresInMs: 15 * 60 * 1000,
+})
+if (outcome.status === "resolved" && outcome.optionId === "allow") run()
+```
+
+The card lands on the active turn's stream (override with `streamId`) and is
+attributed to the in-flight invocation when there is one (`invocationId`). The
+answer arrives over the bot socket, with a poll as the missed-push backstop.
+`status` is `"resolved"` (with `optionId` and the optional `note`),
+`"cancelled"` or `"expired"`. Pass a `signal` to withdraw the card and reject
+with an `AbortError`; `session.cancelDecision(id)` withdraws it directly. A
+shutdown rejects every awaiting call with `DecisionAbandonedError`, and the
+turn blocked on a decision stays alive while the card is open. Decisions on an
+end-to-end encrypted scratchpad are not supported yet — the request is refused
+with `E2E_STREAM_PLAINTEXT_UNSUPPORTED`.
+
+## What the SDK decides for you
+
+- One normal turn at a time. While a turn is in flight the session claims
+  session-control invocations only, so `/stop` and `/steer` reach the runtime
+  while the next message waits.
+- `/stop` calls `actuator.interrupt()`, closes the in-flight turn (with a
+  "Stopped by /stop." note unless the turn had already posted an interim), and
+  does not pull the next queued message.
+- `/steer` folds the text into the running turn through `actuator.steer` when
+  the actuator has it, otherwise interrupts and redelivers the steer text plus
+  any queued messages as one combined turn.
+- Every other advertised command goes to `actuator.runCommand`, and its
+  returned `message` is posted as the acknowledgement.
+- Claims are renewed every 40s on a 120s lease; a claim the server no longer
+  knows is dropped and presence is resynced.
+- A turn that stays silent for `idleTimeoutMs` (default one hour, reset by
+  every `sendInterim`) is closed with a notice. Set it above the longest tool
+  call your runtime makes.
+- `reply` and `sendInterim` return `{ ok, message, retryable }` instead of
+  throwing. `ok: false` with `retryable: true` means the request is still
+  open and the same call can be repeated.
+- If the scratchpad is archived the session goes offline, fails its in-flight
+  turns, and waits for an unarchive. If none arrives within the grace window it
+  calls `delegate.onArchived`.
+- `wireLifecycle` routes SIGINT, SIGTERM, SIGHUP, stdin close, and uncaught
+  errors through `shutdown()`, which marks presence offline and fails
+  in-flight claims so the scratchpad is never left "busy" with nobody behind it.
+
+`delegate.onLinked(link)` runs on every link create or resume, if you need to
+record which scratchpad this process owns.
+
+## Delegations
+
+`DelegationClient` speaks the delegation endpoints (`list`, `get`, `claim`,
+`heartbeat`, `status`, `complete`, `fail`, `release`). `DelegationRunner` is an
+optional loop over it: it polls or reacts to the `delegation:available` nudge,
+claims, heartbeats the lease while your executor runs, and completes or fails
+with the executor's result. A 404 from a claim-authenticated call means the
+claim is lost; the runner aborts the executor and sends nothing further with
+that token.
+
+## Errors
+
+HTTP failures throw `ThreaApiError` with `status` and the server's structured
+`code` (for example `SCRATCHPAD_ARCHIVED`, `E2E_STREAM_PLAINTEXT_UNSUPPORTED`).
+Socket failures never throw; the transport logs them through the `log` you
+pass and falls back to HTTP.
+
+## End-to-end encrypted scratchpads
+
+Set `e2e: true` in the config (or `THREA_E2E=1`) to create the linked
+scratchpad encrypted. The SDK mints the stream key, wraps it to the bot
+owner's key and its own identity key, and from then on decrypts claims and
+seals replies and trace steps locally. The owner must have set up encryption
+in Threa first; until then `start()` logs the reason and retries on each poll.
+
+`keyScope` (`THREA_E2E_KEY_SCOPE`) decides which installs share that identity
+key: `host` (the default: every Threa runtime on this machine), `identity`
+(this bot, wherever it runs), `instance` (this install alone), or `stream`
+(one key per sealed scratchpad, minted when the bot is invited into it, so a
+key that leaks opens that one scratchpad). `keyStore`
+(`THREA_E2E_KEY_STORE`) picks where it is kept — `keychain` drives the OS
+keychain through its command-line tool, which survives the runtime being
+rebuilt, and `file` writes `0600` files under `keyDir`
+(`THREA_E2E_KEY_DIR`, default `~/.threa/e2e-keys`). Leaving `keyStore` unset
+takes the keychain when one works and asks you to choose when none does;
+there is no silent downgrade to disk. A single-key file from before the
+keyring (`bikPath`) is adopted under the configured scope, so scratchpads
+already sealed to it keep opening.
+
+When the owner takes the bot back off a sealed scratchpad, the server deletes
+the wraps only that bot could open and the owner rolls the stream key forward,
+so it reads nothing sent from then on. The runtime is told on the socket: it
+drops the key it minted for that scratchpad, re-advertises what it still holds,
+and the server stops registering the dropped one. Under any scope but `stream`
+there is no such key to drop — the one key still opens the other scratchpads,
+and the roll is what closed this one.
+
+## Inside the Threa repo
+
+This directory is consumed by `extensions/claude-code-remote` through a
+`file:` dependency and runs from `src/`. `bun run build` writes the
+publishable package to `dist/`; `bun run pack` produces the tarball.

package/attachments.d.ts

@@ -0,0 +1,107 @@
+import { type AttachmentRef } from "@threahq/bot-runtime-client";
+import type { AttachmentSummary, StreamMessageSummary, ThreaClient } from "./client.js";
+/** A reply line `THREA_ATTACH: ./out.png` tells the channel to upload that file and attach it to the reply. */
+export declare const ATTACH_DIRECTIVE_RE: RegExp;
+/** Inbound attachments land under `<cwd>/.threa-attachments/<invocationId>/<attachmentId>/`, fresh per turn. */
+export declare const ATTACHMENT_DIR = ".threa-attachments";
+export interface SelectedAttachment {
+    attachment: AttachmentSummary;
+    messageId: string;
+    /** True when the attachment is on the message that triggered this turn. */
+    isSource: boolean;
+}
+export interface DownloadedAttachment extends SelectedAttachment {
+    localPath: string;
+}
+/** Strip `THREA_ATTACH:` directive lines out of a reply, returning the remaining text and the paths. */
+export declare function extractAttachmentDirectives(markdown: string): {
+    markdown: string;
+    paths: string[];
+};
+export declare function guessMimeType(path: string): string;
+/**
+ * Pick the attachments worth downloading: those on the source message (the
+ * request) plus any on the history messages Claude is being shown. De-duplicated
+ * by attachment id, source first so the manifest leads with the current request.
+ */
+export declare function selectInboundAttachments(messages: StreamMessageSummary[], sourceMessageId: string, contextMessageIds: readonly string[]): SelectedAttachment[];
+/** The block appended to the channel event so Claude knows where the files landed. */
+export declare function formatInboundAttachmentManifest(downloaded: DownloadedAttachment[]): string;
+/** The attachment links / failure notes appended to an outbound reply. */
+export declare function buildReplyAttachmentSection(uploaded: AttachmentSummary[], failed: string[]): string;
+export declare function fetchAttachmentBytes(url: string, timeoutMs?: number, signal?: AbortSignal): Promise<Uint8Array>;
+/**
+ * Discover the attachments on the messages Claude is being shown, download them
+ * into `<cwd>/.threa-attachments/<invocationId>/<attachmentId>/`, and return
+ * what landed. A per-attachment failure is logged and skipped rather than
+ * aborting the turn.
+ */
+export declare function downloadInboundAttachments(client: Pick<ThreaClient, "listStreamMessages" | "getAttachmentDownloadUrl">, params: {
+    streamId: string;
+    sourceMessageId: string;
+    contextMessageIds: readonly string[];
+    invocationId: string;
+    cwd: string;
+    scanLimit: number;
+    log: (message: string) => void;
+    /** Live canonical rebuilds fail instead of acknowledging a partial file set. */
+    strict?: boolean;
+    signal?: AbortSignal;
+}): Promise<DownloadedAttachment[]>;
+/**
+ * Resolve `THREA_ATTACH:` directives in a reply: upload each referenced file and
+ * rewrite the reply to carry `attachment:<id>` links the backend associates with
+ * the posted message. Upload failures surface as a note rather than throwing.
+ */
+export declare function uploadReplyAttachments(client: Pick<ThreaClient, "uploadAttachment">, markdown: string, cwd: string): Promise<{
+    markdown: string;
+    uploaded: AttachmentSummary[];
+    failed: string[];
+}>;
+/**
+ * Server cap on `attachmentIds` per sealed message (`sealedAttachmentIdsSchema`
+ * caps at 16). Clamp before uploading: sending more ids would 400 the whole
+ * completion, and the retry loop would re-send the same over-limit body forever.
+ */
+export declare const MAX_SEALED_ATTACHMENTS_PER_MESSAGE = 16;
+/**
+ * Resolve `THREA_ATTACH:` directives in SEALED output: encrypt each file under a
+ * fresh single-use key, upload only the ciphertext (`e2e=true`, placeholder
+ * name/mime), and return the refs to seal into the message payload plus the ids
+ * the wire body binds to the message row. No `attachment:<id>` links are added —
+ * an E2E viewer renders attachments from the sealed refs, not the markdown.
+ * Upload failures surface as a note (itself sealed) rather than throwing.
+ */
+export declare function uploadSealedReplyAttachments(client: Pick<ThreaClient, "uploadAttachment">, markdown: string, cwd: string): Promise<{
+    markdown: string;
+    refs: AttachmentRef[];
+    attachmentIds: string[];
+}>;
+/** One inbound sealed attachment to fetch: the ref plus whether it rode the trigger message. */
+export interface SealedInboundRef {
+    ref: AttachmentRef;
+    isSource: boolean;
+}
+/**
+ * Dedupe the refs opened from a sealed claim (trigger payload + history
+ * payloads) by attachment id, trigger first — the sealed sibling of
+ * `selectInboundAttachments`, working from decrypted refs instead of the
+ * plaintext message list (which only holds placeholders on an E2E stream).
+ */
+export declare function selectSealedInboundRefs(promptRefs: readonly AttachmentRef[], historyRefs: readonly AttachmentRef[]): SealedInboundRef[];
+/**
+ * Download + decrypt a sealed turn's inbound attachments into
+ * `<cwd>/.threa-attachments/<invocationId>/<attachmentId>/`. The S3 object is opaque
+ * ciphertext; the ref's key/iv (opened from the sealed message payload) decrypt
+ * it locally, and the file lands under its REAL name — decrypted bytes never
+ * transit the server. A per-attachment failure is logged and skipped.
+ */
+export declare function downloadSealedInboundAttachments(client: Pick<ThreaClient, "getAttachmentDownloadUrl">, params: {
+    refs: SealedInboundRef[];
+    invocationId: string;
+    cwd: string;
+    log: (message: string) => void;
+    /** Live canonical rebuilds fail instead of acknowledging a partial file set. */
+    strict?: boolean;
+    signal?: AbortSignal;
+}): Promise<DownloadedAttachment[]>;

package/client.d.ts

@@ -0,0 +1,146 @@
+import { type CreateDecisionRequestBody, type DecisionRequest, type AttachmentRef, type ProvisionedWrap, type SealedReplyBody, type SealingState } from "@threahq/bot-runtime-client";
+/**
+ * A sealed message body on the wire: the sealed ciphertext plus the E2E
+ * attachment row ids the server binds to the message (the per-file keys ride
+ * only inside the sealed payload's `attachmentRefs`).
+ */
+export type SealedWireReply = SealedReplyBody & {
+    attachmentIds?: string[];
+};
+export interface RuntimeSessionLink {
+    linkId: string;
+    rootStreamId: string;
+    activeStreamId: string;
+    runtimeSessionId: string;
+    streamUrlPath: string;
+    /** The linked scratchpad's encryption state (create echoes the request; resume reports the actual state). */
+    e2eEnabled?: boolean;
+}
+export interface ExternalHistoryMessage {
+    messageId: string;
+    role: "user" | "assistant";
+    authorId: string;
+    authorType: string;
+    authorDisplayName?: string;
+    contentMarkdown: string;
+    createdAt: string;
+}
+export interface AttachmentSummary {
+    id: string;
+    filename: string;
+    mimeType: string;
+    sizeBytes: number;
+}
+/** The slice of `GET /streams/:id/messages` we consume — id plus any attachments. */
+export interface StreamMessageSummary {
+    id: string;
+    attachments?: AttachmentSummary[];
+}
+export interface ClaimedInvocation {
+    id: string;
+    workspaceId: string;
+    rootStreamId: string;
+    activeStreamId: string;
+    sourceMessageId: string;
+    sourceRevision: number;
+    responseStreamId: string;
+    actor: {
+        type: "bot";
+        id: string;
+        slug: string;
+    };
+    trigger: string;
+    requiredCapability: string;
+    promptMarkdown: string;
+    authorUserId: string;
+    mentionedActorSlugs: string[];
+    claimToken: string;
+    claimExpiresAt: string;
+    runtimeSessionId: string | null;
+    metadata: Record<string, unknown>;
+    context?: {
+        kind: "inline";
+        messages: ExternalHistoryMessage[];
+    };
+    /** Present on a sealed (E2E) claim as delivered by the server; consumed and cleared by hydration. */
+    sealedContext?: unknown;
+    /** Present on a session-control claim on an E2E stream: SSK wraps to seal the command ack. */
+    sealedAck?: unknown;
+    /** Derived from `sealedContext` at claim time; carries the stream key + binding for sealing replies/steps. */
+    sealing?: SealingState;
+    /** Attachment refs opened from the sealed trigger/history payloads at claim time — download + decrypt is the turn's job. */
+    sealedAttachments?: {
+        prompt: AttachmentRef[];
+        history: AttachmentRef[];
+    };
+}
+export declare class ThreaApiError extends Error {
+    readonly status: number;
+    /** The server's structured error `code` (e.g. `E2E_STREAM_PLAINTEXT_UNSUPPORTED`), when the body was JSON. */
+    readonly code?: string | undefined;
+    readonly retryAfterMs?: number | undefined;
+    constructor(message: string, status: number, 
+    /** The server's structured error `code` (e.g. `E2E_STREAM_PLAINTEXT_UNSUPPORTED`), when the body was JSON. */
+    code?: string | undefined, retryAfterMs?: number | undefined);
+}
+export interface ThreaClientOptions {
+    baseUrl: string;
+    workspaceId: string;
+    apiKey: string;
+    fetchTimeoutMs?: number;
+}
+export declare class ThreaClient {
+    private readonly opts;
+    constructor(opts: ThreaClientOptions);
+    private get base();
+    private request;
+    private requestWithin;
+    private workspacePath;
+    /** Returns the authenticated principal; only `.kind` (`"bot"` vs `"user"`) is consumed today. */
+    getMe(): Promise<{
+        kind: string;
+    }>;
+    createSession(body: Record<string, unknown>): Promise<RuntimeSessionLink>;
+    claim(body: Record<string, unknown>): Promise<ClaimedInvocation | null>;
+    complete(invocationId: string, body: Record<string, unknown>, signal?: AbortSignal): Promise<void>;
+    fail(invocationId: string, body: Record<string, unknown>): Promise<void>;
+    sendMessage(streamId: string, body: Record<string, unknown>): Promise<{
+        id: string;
+    }>;
+    sendInvocationMessage(invocationId: string, body: Record<string, unknown>): Promise<void>;
+    sendSealedMessage(invocationId: string, callbackToken: string, body: SealedWireReply): Promise<void>;
+    /** The bot owner's active encryption key (public half). 404 = the owner has not set up encryption. */
+    getOwnerE2eKey(): Promise<{
+        keyId: string;
+        publicKey: string;
+    }>;
+    /** Phase two of harness-created E2E scratchpads: store the generation-0 stream-key wraps. */
+    provisionStreamKeyWraps(streamId: string, body: {
+        keyGeneration: number;
+        wraps: ProvisionedWrap[];
+    }): Promise<void>;
+    /** Complete a sealed turn with its final sealed reply — or silently (`noResponse`). Callback-token auth. */
+    completeSealed(invocationId: string, callbackToken: string, body: ({
+        reply: SealedWireReply;
+    } | {
+        noResponse: true;
+    }) & {
+        sourceRevision: number;
+    }, signal?: AbortSignal): Promise<void>;
+    /** Open a decision card on a stream and return the created request. Bot key only. */
+    requestDecision(streamId: string, body: CreateDecisionRequestBody): Promise<DecisionRequest>;
+    /** Read one decision this bot opened. 404 once it is out of the caller's scope. */
+    getDecision(decisionId: string): Promise<DecisionRequest>;
+    /** Withdraw a decision this bot opened. */
+    cancelDecision(decisionId: string): Promise<DecisionRequest>;
+    /** Recent messages for a stream, newest-window first. Used to discover inbound attachments (the claim context omits them). Requires `messages:read` + `streams:read`. */
+    listStreamMessages(streamId: string, query?: {
+        limit?: number;
+    }): Promise<StreamMessageSummary[]>;
+    /** `archivedAt` for a stream, or null while it is live. Requires `streams:read`. */
+    getStreamArchivedAt(streamId: string): Promise<string | null>;
+    /** Short-lived signed download URL for an attachment. Requires `attachments:read`. */
+    getAttachmentDownloadUrl(attachmentId: string): Promise<string>;
+    /** Upload a file (multipart `file` field) and return its summary. Requires `attachments:write`. */
+    uploadAttachment(form: FormData): Promise<AttachmentSummary>;
+}

package/config-file.d.ts

@@ -0,0 +1,12 @@
+import { type RawConfig } from "./identity.js";
+/**
+ * A connector's optional JSON config file. Absent is undefined; a damaged file
+ * is logged and ignored so env vars can still carry the config.
+ */
+export declare function readConfigFile(path: string, log: (message: string) => void): RawConfig | undefined;
+/**
+ * Owner-only from the first byte, then swapped in whole: an existing file's
+ * looser mode never applies to the new content, and a reader or a crash never
+ * sees a half-written file.
+ */
+export declare function writeFileAtomic(path: string, content: string, mode?: number): void;

package/delegation-client.d.ts

@@ -0,0 +1,98 @@
+/** Wire shape of a delegation on the public API (list + lifecycle responses). */
+export interface DelegationSummary {
+    id: string;
+    streamId: string;
+    title: string;
+    status: string;
+    claimedByLabel?: string;
+    statusNote?: string;
+    resultMessageId?: string;
+    sourceConversationId?: string;
+    createdAt: string;
+    statusChangedAt: string;
+}
+/** Inspect response: the full working set without claim credentials. */
+export interface InspectedDelegation extends DelegationSummary {
+    brief: string;
+    contextRefs: string[];
+    claimExpiresAt?: string;
+}
+/** The claim response: the executor's full working set plus the one-time token. */
+export interface ClaimedDelegation extends InspectedDelegation {
+    /** Cleartext, returned exactly once — send it back as X-Threa-Callback-Token. */
+    claimToken: string;
+    claimExpiresAt: string;
+}
+export interface DelegationClientOptions {
+    baseUrl: string;
+    workspaceId: string;
+    apiKey: string;
+    fetchTimeoutMs?: number;
+}
+/**
+ * HTTP client for the delegation lifecycle (roadmap 5.3/5.4) — a deliberate
+ * sibling of `ThreaClient`, not an extension of it: the bot-runtime surface is
+ * bot-key-only with body-carried claim tokens, while delegations accept either
+ * key kind and authenticate transitions with the `X-Threa-Callback-Token`
+ * header. Keeping the clients separate keeps the two credential/transport
+ * models from cross-contaminating (the recorded 5.3 ruling).
+ */
+export declare class DelegationClient {
+    private readonly opts;
+    constructor(opts: DelegationClientOptions);
+    private get base();
+    private path;
+    private request;
+    private requestWithin;
+    /** Inspect a delegation without claiming it. The response never contains claim credentials. */
+    get(id: string): Promise<InspectedDelegation>;
+    /** Open delegations the key can access, oldest first. `since` narrows to a delta. */
+    listOpen(opts?: {
+        since?: string;
+    }): Promise<DelegationSummary[]>;
+    /**
+     * CAS-claim one delegation. Persist `idempotencyKey` BEFORE calling: a retry
+     * bearing the live claim's key re-keys it (fresh token + lease) instead of
+     * 409ing — the crash-between-response-and-persist recovery path.
+     * Throws `ThreaApiError` 409 (`DELEGATION_NOT_OPEN`) on a lost race.
+     */
+    claim(id: string, body: {
+        claimedByLabel: string;
+        idempotencyKey?: string;
+    }): Promise<ClaimedDelegation>;
+    /** Release a live claim back to the open queue. */
+    release(id: string, claimToken: string): Promise<DelegationSummary>;
+    /** Renew the 15-minute lease. Liveness only — nothing changes on the card. */
+    heartbeat(id: string, claimToken: string): Promise<{
+        claimExpiresAt: string;
+    }>;
+    /** Progress note on the card (`claimed|running → running`); also renews the lease. */
+    reportStatus(id: string, claimToken: string, statusNote: string): Promise<DelegationSummary>;
+    /**
+     * Terminal success. `resultMarkdown` posts into the delegation card's thread
+     * as the key's identity in the same transaction as the flip; retries with the
+     * same token are idempotent (the committed outcome comes back, nothing double-posts).
+     */
+    complete(id: string, claimToken: string, body: {
+        resultMarkdown?: string;
+        metadata?: Record<string, string>;
+    }): Promise<DelegationSummary & {
+        resultMessageId?: string;
+        resultThreadId?: string;
+    }>;
+    /** Terminal failure: the reason lands on the card. Idempotent like complete. */
+    fail(id: string, claimToken: string, errorMessage: string): Promise<DelegationSummary>;
+    /**
+     * Ask a stream member to grant this bot access to the delegation's stream
+     * (F3). Called when a claim 404s for lack of a channel grant — files a card a
+     * member approves or denies. No claim token: the bot has no claim yet. Returns
+     * `{ status: "already_granted" }` (no `requestId`) when the bot already had
+     * access, else `{ requestId, status: "open" }`; idempotent per (bot, stream).
+     */
+    requestAccess(delegationId: string, opts?: {
+        requestedByLabel?: string;
+    }): Promise<{
+        requestId?: string;
+        status: string;
+    }>;
+}

package/delegation-runner.d.ts

@@ -0,0 +1,57 @@
+import type { ClaimedDelegation, DelegationClient } from "./delegation-client.js";
+export declare const DELEGATION_STOP_REASON = "runner_shutdown";
+export interface DelegationExecutorContext {
+    signal: AbortSignal;
+    reportStatus(note: string): Promise<void>;
+}
+export type DelegationExecutor = (task: ClaimedDelegation, ctx: DelegationExecutorContext) => Promise<{
+    resultMarkdown?: string;
+    metadata?: Record<string, string>;
+} | void>;
+export interface DelegationRunnerOptions {
+    client: DelegationClient;
+    executor: DelegationExecutor;
+    claimedByLabel: string;
+    persistIdempotencyKey?: (delegationId: string, key: string) => void | Promise<void>;
+    pollMs?: number;
+    heartbeatMs?: number;
+    /** Maximum controlled-stop wait. Primarily useful to bound host reconnects. */
+    shutdownWaitMs?: number;
+    log?: (message: string) => void;
+}
+export declare class DelegationRunner {
+    private readonly client;
+    private readonly executor;
+    private readonly claimedByLabel;
+    private readonly persistIdempotencyKey?;
+    private readonly pollMs;
+    private readonly heartbeatMs;
+    private readonly shutdownWaitMs;
+    private readonly log;
+    private stopped;
+    private generation;
+    private current;
+    private stopOperation;
+    private pollTimer;
+    private active;
+    private readonly pendingNudged;
+    private readonly accessRequested;
+    constructor(opts: DelegationRunnerOptions);
+    start(): void;
+    stop(_reason?: string, options?: {
+        strict?: boolean;
+    }): Promise<void>;
+    notifyAvailable(nudge?: {
+        delegationId?: string;
+    }): void;
+    private isCurrent;
+    private drain;
+    private runDrain;
+    private tryClaim;
+    private tryClaimNudged;
+    private requestAccessOnce;
+    private releaseStoppedClaim;
+    private createActiveClaim;
+    private releaseActive;
+    private execute;
+}