@threahq/remote-session 0.1.0

package/examples/echo-connector.ts

@@ -0,0 +1,73 @@
+// A scratchpad-linked connector: the runtime owns a scratchpad, every message
+// in it is a turn, and /steer and /stop work from the composer.
+//
+//   THREA_WORKSPACE_ID=ws_… THREA_API_KEY=threa_bk_… bun examples/echo-connector.ts
+//
+// The "runtime" here is a timer that echoes the turn after ECHO_DELAY_MS, so the
+// session-control paths have something to interrupt. Replace `runtime` with a
+// bridge to a real agent; everything else stays.
+
+import { hostname } from "node:os"
+import { RemoteSession, ThreaClient, loadConfig, wireLifecycle } from "@threahq/remote-session"
+
+const runtimeKind = process.env.THREA_RUNTIME_KIND ?? "custom"
+const echoDelayMs = Number(process.env.ECHO_DELAY_MS ?? 0)
+
+const loaded = loadConfig(
+  { env: process.env, cwd: process.cwd(), hostname: hostname() },
+  { idPrefix: "echo", sessionIdPrefix: "echos", displayNamePrefix: "Echo" }
+)
+if ("error" in loaded) {
+  console.error(loaded.error)
+  process.exit(1)
+}
+
+let pending: { invocationId: string; content: string; timer: ReturnType<typeof setTimeout> } | undefined
+
+const runtime = {
+  prompt(invocationId: string, content: string): void {
+    void session.sendInterim(invocationId, "Working on it.")
+    const timer = setTimeout(async () => {
+      const turn = pending
+      pending = undefined
+      if (!turn) return
+      await session.reply(turn.invocationId, `Echo: ${turn.content}`)
+    }, echoDelayMs)
+    pending = { invocationId, content, timer }
+  },
+  interrupt(): boolean {
+    if (pending) clearTimeout(pending.timer)
+    pending = undefined
+    return true
+  },
+  steer(text: string): boolean {
+    if (!pending) return false
+    pending.content = `${pending.content}\n${text}`
+    return true
+  },
+}
+
+const session = new RemoteSession({
+  config: loaded.config,
+  client: new ThreaClient(loaded.config),
+  runtime: {
+    kind: runtimeKind,
+    busyStatusText: "Echoing…",
+    forwardedNote: "Forwarded to the echo runtime.",
+    shutdownErrorMessage: "Echo connector shut down",
+  },
+  delegate: {
+    deliverTurn: async (turn) => runtime.prompt(turn.invocationId, turn.content),
+    sessionControl: {
+      commands: ["stop", "steer"],
+      interrupt: () => runtime.interrupt(),
+      steer: (text) => runtime.steer(text),
+      runCommand: async (name) => ({ ok: false, message: `Unsupported command: /${name}` }),
+    },
+    onLinked: (link) => console.error(`linked to ${loaded.config.baseUrl}${link.streamUrlPath}`),
+  },
+  log: (line) => console.error(`[echo] ${line}`),
+})
+
+wireLifecycle(session, process, { logPrefix: "[echo]" })
+await session.start()

package/examples/mention-bot.ts

@@ -0,0 +1,120 @@
+// A mention-driven bot: any runtime kind (here `custom`) can claim the work
+// Threa creates when someone @mentions the bot, do it, and reply.
+//
+//   THREA_WORKSPACE_ID=ws_… THREA_API_KEY=threa_bk_… bun examples/mention-bot.ts
+//
+// The socket delivers "work is claimable" nudges and carries presence and claim
+// renewals; the claim, the reply, and the poll backstop are plain HTTP.
+
+import { BotRuntimeTransport } from "@threahq/bot-runtime-client"
+import { ThreaClient } from "@threahq/remote-session"
+
+const baseUrl = process.env.THREA_BASE_URL ?? "https://app.threa.io"
+const workspaceId = process.env.THREA_WORKSPACE_ID!
+const apiKey = process.env.THREA_API_KEY!
+const instanceId = process.env.THREA_INSTANCE_ID ?? "mention-bot-1"
+const runtimeKind = "custom"
+
+const client = new ThreaClient({ baseUrl, workspaceId, apiKey })
+const transport = new BotRuntimeTransport({
+  baseUrl,
+  workspaceId,
+  apiKey,
+  hello: { instanceId, runtimeKind, supportedCapabilities: ["mentionable"] },
+  callbacks: { onInvocationAvailable: () => void drain(), onBootstrap: () => void drain() },
+  log: (line) => console.error(`[transport] ${line}`),
+})
+
+const presence = (status: "available" | "busy" | "offline") =>
+  transport.updatePresence({
+    runtimeKind,
+    instanceId,
+    status,
+    acceptingInvocations: status === "available",
+    capabilities: {},
+  })
+
+let draining = false
+async function drain(): Promise<void> {
+  if (draining) return
+  draining = true
+  try {
+    for (;;) {
+      const invocation = await client.claim({
+        runtimeKind,
+        instanceId,
+        supportedCapabilities: ["mentionable"],
+        claimTtlSeconds: 120,
+      })
+      if (!invocation) return
+      await presence("busy")
+      // Renew while working so a slow answer never loses the claim. If the
+      // server says the claim is gone, or has not confirmed the lease for long
+      // enough that it may have expired, the reply has nowhere to land.
+      let claimLost = false
+      let leaseConfirmedAt = Date.now()
+      const renew = setInterval(async () => {
+        const { notFound, renewed } = await transport.renewClaim(invocation.id, invocation.claimToken, 120)
+        if (renewed) leaseConfirmedAt = Date.now()
+        if (notFound || (!renewed && Date.now() - leaseConfirmedAt > 80_000)) {
+          claimLost = true
+          clearInterval(renew)
+          console.error(`[bot] claim ${invocation.id} lost or unconfirmed; dropping the reply`)
+        }
+      }, 40_000)
+      try {
+        await transport.recordSteps(invocation.id, invocation.claimToken, [
+          { stepType: "thinking", content: "Composing a reply" },
+        ])
+        const reply = await answer(invocation.promptMarkdown)
+        if (claimLost) continue
+        await client.complete(invocation.id, {
+          instanceId,
+          claimToken: invocation.claimToken,
+          finalMessageMarkdown: reply,
+        })
+      } catch (error) {
+        await client
+          .fail(invocation.id, {
+            instanceId,
+            claimToken: invocation.claimToken,
+            errorMessage: error instanceof Error ? error.message : String(error),
+          })
+          .catch((failure) => console.error(`[bot] could not fail ${invocation.id}: ${failure}`))
+      } finally {
+        clearInterval(renew)
+        await presence("available")
+      }
+    }
+  } catch (error) {
+    // A transient claim failure is logged; the socket nudge or the backstop
+    // poll runs the loop again. Nothing here should end the process.
+    console.error(`[bot] claim loop: ${error instanceof Error ? error.message : String(error)}`)
+  } finally {
+    draining = false
+  }
+}
+
+// Replace with your agent.
+async function answer(prompt: string): Promise<string> {
+  return `You said: ${prompt}`
+}
+
+const backstop = setInterval(() => void drain(), 30_000)
+const heartbeat = setInterval(() => void presence(draining ? "busy" : "available"), 20_000)
+let stopping = false
+for (const signal of ["SIGINT", "SIGTERM"] as const) {
+  process.on(signal, async () => {
+    if (stopping) return
+    stopping = true
+    clearInterval(backstop)
+    clearInterval(heartbeat)
+    transport.disconnect()
+    await presence("offline")
+    process.exit(0)
+  })
+}
+
+await presence("available")
+await transport.connect()
+await drain()

package/identity.d.ts

@@ -0,0 +1,157 @@
+import { type E2eKeyScope, type E2eKeyStoreKind } from "@threahq/bot-runtime-client";
+export declare const TRACE_MODES: readonly ["headline", "commands"];
+export type TraceMode = (typeof TRACE_MODES)[number];
+export interface RemoteSessionConfig {
+    baseUrl: string;
+    workspaceId: string;
+    apiKey: string;
+    /** Scratchpad display name: the configured prefix with the project directory appended. */
+    displayName: string;
+    /** Sent as `labelName` on session create; the backend applies it only to a newly created scratchpad. Unset = no label. */
+    defaultLabel?: string;
+    /**
+     * Recorded on the session link as the runtime's working directory, for a
+     * supervisor (harnessd) that reaps worktrees. Unset = not sent; a public
+     * connector has no reason to upload a local path.
+     */
+    localCwd?: string;
+    /** Cold-start behavior when this identity still points at an archived scratchpad. Default: replace. */
+    coldStartIfArchived?: "wait" | "replace";
+    /** Cold-start behavior when this identity has no session link. Default: create. */
+    coldStartIfMissing?: "create" | "error";
+    /** When set by a supervisor, refuse a session link to any other scratchpad root. */
+    expectedRootStreamId?: string;
+    /** `^[A-Za-z0-9_-]+$`, ≤64 — must satisfy the `/bot` hello schema. */
+    instanceId: string;
+    runtimeSessionId: string;
+    /** Relay the runtime's tool-approval prompts into the scratchpad for remote approval. */
+    permissionRelay: boolean;
+    /** Backstop claim-poll cadence; the `/bot` socket pushes work faster than this. */
+    pollMs: number;
+    /**
+     * Safety net for a wedged turn: an in-flight invocation is force-closed after
+     * this much *inactivity*. Every interim send (and tool-approval activity)
+     * resets it, so an actively-working turn never trips it — only one that went
+     * silent without a reply. Must exceed the longest single tool call the agent
+     * makes, since it can't heartbeat while blocked on a tool.
+     */
+    idleTimeoutMs: number;
+    /**
+     * The single-key BIK file this install used before keyrings. Still read: when
+     * the configured key scope holds nothing yet, the old key is adopted under it
+     * so the owner's existing wraps keep addressing a key this runtime holds.
+     * Unset = a per-runtime-kind default under `~/.threa/`.
+     */
+    bikPath?: string;
+    /**
+     * How widely this install's E2E identity key is shared. `host` (default) is
+     * one key for every runtime on this machine, so a person running several
+     * agents invites one recipient rather than one per agent. `identity` is one
+     * key per bot (per API key) across machines, `instance` one per install.
+     * Changing it points the runtime at a different key, so the owner must
+     * re-invite it to streams wrapped under the old one.
+     */
+    keyScope: E2eKeyScope;
+    /**
+     * Where E2E keys are kept. Unset lets a working OS keychain win and otherwise
+     * asks rather than choosing disk on the operator's behalf; `file` keeps them
+     * at mode 0600 under `keyDir`; `keychain` requires one and fails loudly
+     * without it.
+     */
+    keyStore?: E2eKeyStoreKind;
+    /** Directory for the file key store. Default `~/.threa/e2e-keys`. */
+    keyDir?: string;
+    /**
+     * Emit FULL trace detail (real commands, file contents, outputs) on sealed
+     * (E2EE) turns — safe because sealed step content is ciphertext the server
+     * can't read. Default on; set false to use `traceMode` on sealed turns too.
+     * Has no effect on plaintext turns, which never emit full detail.
+     */
+    sealedFullTrace: boolean;
+    /**
+     * Base trace detail. `headline` keeps shell commands hidden; `commands`
+     * includes only the Bash command while file bodies, patches, and every tool
+     * result stay hidden. Used for plaintext turns and sealed turns when
+     * `sealedFullTrace` is false. Defaults to `headline`.
+     */
+    traceMode: TraceMode;
+    /**
+     * Create this connector's linked scratchpad end-to-end encrypted: the harness
+     * mints the stream key and wraps it to the bot owner's UIK + its own BIK, so
+     * the server only ever stores ciphertext. Requires the owner to have set up
+     * encryption in Threa (their UIK is fetched at session create). Off by
+     * default — an encrypted scratchpad opts out of GAM memory extraction.
+     */
+    e2e?: boolean;
+    /**
+     * Run the workspace delegation queue on this connector (claim → execute →
+     * complete, see delegation-runner.ts). Off by default: delegations are
+     * workspace-wide and claimed first-come-first-served, so with several
+     * connectors running only the one(s) the user explicitly opted in should
+     * race for them.
+     */
+    delegations?: boolean;
+}
+/**
+ * Who this connector is: the stable-id prefixes that key its sessions and the
+ * default display-name prefix. Every connector picks its own (Claude Code uses
+ * cc/ccs), so two runtimes in the same directory never collide.
+ */
+export interface ConnectorIdentity {
+    /** Prefix for the derived instance id (e.g. "cc"). */
+    idPrefix: string;
+    /** Prefix for the derived runtime-session id (e.g. "ccs"). */
+    sessionIdPrefix: string;
+    /** Human prefix for the scratchpad display name (e.g. "Claude Code"). */
+    displayNamePrefix: string;
+    /** Where the connector reads file config from — used only in the missing-config error message. */
+    configPathHint?: string;
+}
+export declare function sanitizeId(raw: string): string;
+/**
+ * Deterministic id from a seed (host + cwd), so the same project directory
+ * always maps back to the same Threa scratchpad across runtime restarts —
+ * no on-disk session state to keep in sync.
+ */
+export declare function deriveStableId(prefix: string, seed: string): string;
+export declare function defaultDisplayName(cwd: string, prefix: string, override?: string): string;
+export interface RawConfig {
+    baseUrl?: unknown;
+    workspaceId?: unknown;
+    apiKey?: unknown;
+    displayName?: unknown;
+    defaultLabel?: unknown;
+    coldStartIfArchived?: unknown;
+    coldStartIfMissing?: unknown;
+    expectedRootStreamId?: unknown;
+    permissionRelay?: unknown;
+    pollMs?: unknown;
+    idleTimeoutMs?: unknown;
+    instanceId?: unknown;
+    runtimeSessionId?: unknown;
+    bikPath?: unknown;
+    keyScope?: unknown;
+    keyStore?: unknown;
+    keyDir?: unknown;
+    e2e?: unknown;
+    sealedFullTrace?: unknown;
+    traceMode?: unknown;
+    delegations?: unknown;
+}
+export declare function parseConfigFile(text: string): RawConfig;
+export interface LoadConfigInput {
+    env: Record<string, string | undefined>;
+    cwd: string;
+    hostname: string;
+    file?: RawConfig;
+}
+export type LoadConfigResult = {
+    config: RemoteSessionConfig;
+} | {
+    error: string;
+};
+/**
+ * Pure config resolver: file values are the base, environment variables win.
+ * Kept side-effect-free so it can be unit-tested without touching disk/env.
+ */
+export declare function loadConfig(input: LoadConfigInput, identity: ConnectorIdentity): LoadConfigResult;

package/index.d.ts

@@ -0,0 +1,10 @@
+export { RemoteSession, DecisionAbandonedError, parseSessionControlCommand, isSessionControlInvocation, formatInvocationContent, buildSteerContent, effectiveRuntimeManifest, supportedCapabilitiesFor, claimCapabilitiesFor, runtimeCapabilitiesFor, SESSION_CONTROL_CAPABILITY, STEER_SETTLE_MS, COMPLETED_TURN_MEMORY, type DecisionOutcome, type DecisionRequestInput, type DeliveredTurn, type HandedOffCommandClaim, type ModelSuggestionInfo, type RemoteSessionDelegate, type RemoteSessionOptions, type RemoteSessionStatusSnapshot, type RuntimeDescriptor, type RuntimePresenceReport, type SendResult, type SessionControlActuator, type SessionControlInvocationContext, type ShutdownOptions, type SpawnRuntimeInfo, } from "./session.js";
+export { ThreaClient, ThreaApiError, type AttachmentSummary, type ClaimedInvocation, type ExternalHistoryMessage, type RuntimeSessionLink, type StreamMessageSummary, type ThreaClientOptions, } from "./client.js";
+export { TRACE_MODES, loadConfig, parseConfigFile, sanitizeId, deriveStableId, defaultDisplayName, type ConnectorIdentity, type LoadConfigInput, type LoadConfigResult, type RawConfig, type RemoteSessionConfig, type TraceMode, } from "./identity.js";
+export { readConfigFile, writeFileAtomic } from "./config-file.js";
+export { downloadInboundAttachments, formatInboundAttachmentManifest, uploadReplyAttachments, extractAttachmentDirectives, guessMimeType, ATTACH_DIRECTIVE_RE, ATTACHMENT_DIR, type DownloadedAttachment, type SelectedAttachment, } from "./attachments.js";
+export { wireLifecycle, type LifecycleOptions, type LifecycleProcess } from "./lifecycle.js";
+export { DelegationClient, type DelegationClientOptions, type DelegationSummary, type InspectedDelegation, type ClaimedDelegation, } from "./delegation-client.js";
+export { DelegationRunner, type DelegationRunnerOptions, type DelegationExecutor, type DelegationExecutorContext, } from "./delegation-runner.js";
+export { toolTraceContent, type ToolTraceSection, type ToolTraceSectionLabel } from "./tool-trace.js";
+export type { DecisionRequest, StepFrame } from "@threahq/bot-runtime-client";