@threahq/bot-runtime-client 0.1.0

package/index.js

@@ -0,0 +1,2344 @@
+// src/transport.ts
+import * as socketIoClient from "socket.io-client";
+
+// src/sealed.ts
+import { ulid } from "ulid";
+
+// src/crypto.ts
+import { Aes256Gcm, CipherSuite, HkdfSha256 } from "@hpke/core";
+import { DhkemX25519HkdfSha256 } from "@hpke/dhkem-x25519";
+function bytesToBase64(bytes) {
+  const view = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+  let binary = "";
+  for (let i = 0;i < view.length; i++)
+    binary += String.fromCharCode(view[i]);
+  return btoa(binary);
+}
+function base64ToBytes(b64) {
+  const binary = atob(b64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0;i < binary.length; i++)
+    bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+function utf8Encode(text) {
+  return new TextEncoder().encode(text);
+}
+function utf8Decode(bytes) {
+  return new TextDecoder().decode(bytes);
+}
+function concatBytes(...parts) {
+  let total = 0;
+  for (const p of parts)
+    total += p.length;
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const p of parts) {
+    out.set(p, offset);
+    offset += p.length;
+  }
+  return out;
+}
+var suite = null;
+function getSuite() {
+  if (!suite) {
+    suite = new CipherSuite({
+      kem: new DhkemX25519HkdfSha256,
+      kdf: new HkdfSha256,
+      aead: new Aes256Gcm
+    });
+  }
+  return suite;
+}
+async function generateKeyPair() {
+  return getSuite().kem.generateKeyPair();
+}
+async function importRecipientPrivateKey(raw) {
+  const buf = raw instanceof Uint8Array ? raw.buffer.slice(raw.byteOffset, raw.byteOffset + raw.byteLength) : raw;
+  return getSuite().kem.deserializePrivateKey(buf);
+}
+async function exportPublicKey(key) {
+  return new Uint8Array(await getSuite().kem.serializePublicKey(key));
+}
+async function exportPrivateKey(key) {
+  return new Uint8Array(await getSuite().kem.serializePrivateKey(key));
+}
+async function importRecipientPublicKey(raw) {
+  const buf = raw instanceof Uint8Array ? raw.buffer.slice(raw.byteOffset, raw.byteOffset + raw.byteLength) : raw;
+  return getSuite().kem.deserializePublicKey(buf);
+}
+async function hpkeOpen(params) {
+  const buf = await getSuite().open({ recipientKey: params.recipientPrivateKey, enc: params.enc }, params.ct, params.aad);
+  return new Uint8Array(buf);
+}
+async function hpkeSeal(params) {
+  const sealed = await getSuite().seal({ recipientPublicKey: params.recipientPublicKey }, params.payload, params.aad);
+  return { enc: new Uint8Array(sealed.enc), ct: new Uint8Array(sealed.ct) };
+}
+var STREAM_ENVELOPE_VERSION = 2;
+var SSK_LENGTH = 32;
+var IV_LENGTH = 12;
+function assertBoundAad(fn, aad) {
+  if (aad.length === 0) {
+    throw new Error(`${fn}: aad must be non-empty (see buildMessageAad/buildWrapAad)`);
+  }
+}
+async function sealMessage(input) {
+  if (input.key.length !== SSK_LENGTH) {
+    throw new Error(`sealMessage: SSK must be ${SSK_LENGTH} bytes, got ${input.key.length}`);
+  }
+  assertBoundAad("sealMessage", input.aad);
+  const iv = new Uint8Array(IV_LENGTH);
+  crypto.getRandomValues(iv);
+  const plaintext = typeof input.payload === "string" ? utf8Encode(input.payload) : new Uint8Array(input.payload);
+  const aad = new Uint8Array(input.aad);
+  const sskKey = await crypto.subtle.importKey("raw", new Uint8Array(input.key), { name: "AES-GCM" }, false, [
+    "encrypt"
+  ]);
+  const ciphertext = new Uint8Array(await crypto.subtle.encrypt({ name: "AES-GCM", iv, additionalData: aad }, sskKey, plaintext));
+  return {
+    envelope: {
+      v: STREAM_ENVELOPE_VERSION,
+      keyGeneration: input.keyGeneration,
+      iv: bytesToBase64(iv),
+      aad: bytesToBase64(aad)
+    },
+    ciphertext
+  };
+}
+async function openMessage(input) {
+  if (input.envelope.v !== STREAM_ENVELOPE_VERSION) {
+    throw new Error(`Unsupported stream envelope version: ${input.envelope.v}`);
+  }
+  if (input.key.length !== SSK_LENGTH) {
+    throw new Error(`openMessage: SSK must be ${SSK_LENGTH} bytes, got ${input.key.length}`);
+  }
+  const aad = base64ToBytes(input.envelope.aad);
+  const sskKey = await crypto.subtle.importKey("raw", new Uint8Array(input.key), { name: "AES-GCM" }, false, [
+    "decrypt"
+  ]);
+  const plaintext = new Uint8Array(await crypto.subtle.decrypt({ name: "AES-GCM", iv: base64ToBytes(input.envelope.iv), additionalData: aad }, sskKey, new Uint8Array(input.ciphertext)));
+  return plaintext;
+}
+async function openMessageAsString(input) {
+  return utf8Decode(await openMessage(input));
+}
+async function wrapStreamKey(input) {
+  assertBoundAad("wrapStreamKey", input.aad);
+  if (input.key.length !== SSK_LENGTH) {
+    throw new Error(`wrapStreamKey: SSK must be ${SSK_LENGTH} bytes, got ${input.key.length}`);
+  }
+  return hpkeSeal({ recipientPublicKey: input.recipientPublicKey, payload: new Uint8Array(input.key), aad: input.aad });
+}
+function generateStreamKey() {
+  const key = new Uint8Array(SSK_LENGTH);
+  crypto.getRandomValues(key);
+  return key;
+}
+async function unwrapStreamKey(input) {
+  assertBoundAad("unwrapStreamKey", input.aad);
+  const key = await hpkeOpen({
+    recipientPrivateKey: input.recipientPrivateKey,
+    enc: input.enc,
+    ct: input.ct,
+    aad: input.aad
+  });
+  if (key.length !== SSK_LENGTH) {
+    throw new Error(`unwrapStreamKey: recovered key is ${key.length} bytes, expected ${SSK_LENGTH}`);
+  }
+  return key;
+}
+function buildWrapAad(parts) {
+  if (parts.streamId.length === 0 || parts.recipientKeyId.length === 0) {
+    throw new Error("buildWrapAad: streamId and recipientKeyId must be non-empty");
+  }
+  if (parts.streamId.includes("|") || parts.recipientKeyId.includes("|")) {
+    throw new Error("buildWrapAad: streamId and recipientKeyId must not contain '|'");
+  }
+  if (!Number.isInteger(parts.keyGeneration) || parts.keyGeneration < 0) {
+    throw new Error("buildWrapAad: keyGeneration must be a non-negative integer");
+  }
+  return concatBytes(utf8Encode(parts.streamId), utf8Encode("|"), utf8Encode(String(parts.keyGeneration)), utf8Encode("|"), utf8Encode(parts.recipientKeyId));
+}
+function buildMessageAad(parts) {
+  return concatBytes(utf8Encode(parts.streamId), utf8Encode("|"), utf8Encode(parts.messageId), utf8Encode("|"), utf8Encode(parts.senderId));
+}
+function buildDecisionAad(parts) {
+  return decisionAad("decision", parts.streamId, parts.decisionId, parts.requesterBotId);
+}
+function buildDecisionNoteAad(parts) {
+  return decisionAad("decision-note", parts.streamId, parts.decisionId, parts.decidedBy);
+}
+function decisionAad(label, streamId, decisionId, actorId) {
+  return concatBytes(utf8Encode(streamId), utf8Encode("|"), utf8Encode(label), utf8Encode("|"), utf8Encode(decisionId), utf8Encode("|"), utf8Encode(actorId));
+}
+var ATTACHMENT_AAD = utf8Encode("threa-attachment-v1");
+var ATTACHMENT_KEY_GENERATION = 0;
+async function encryptAttachmentBytes(plaintext) {
+  const key = generateStreamKey();
+  const { envelope, ciphertext } = await sealMessage({
+    key,
+    keyGeneration: ATTACHMENT_KEY_GENERATION,
+    payload: plaintext,
+    aad: ATTACHMENT_AAD
+  });
+  return { ciphertext, key: bytesToBase64(key), iv: envelope.iv };
+}
+async function decryptAttachmentBytes(input) {
+  return openMessage({
+    key: base64ToBytes(input.key),
+    envelope: {
+      v: STREAM_ENVELOPE_VERSION,
+      keyGeneration: ATTACHMENT_KEY_GENERATION,
+      iv: input.iv,
+      aad: bytesToBase64(ATTACHMENT_AAD)
+    },
+    ciphertext: input.ciphertext
+  });
+}
+var E2E_PAYLOAD_VERSION = 1;
+function serializeSealedPayload(contentMarkdown, extras) {
+  const attachmentRefs = extras?.attachmentRefs;
+  const sources = extras?.sources;
+  const draftContentJson = extras?.draftContentJson;
+  const hasRefs = attachmentRefs !== undefined && attachmentRefs.length > 0;
+  const hasSources = sources !== undefined && sources.length > 0;
+  const hasDraftBody = draftContentJson !== undefined && draftContentJson !== null;
+  if (!hasRefs && !hasSources && !hasDraftBody)
+    return contentMarkdown;
+  return JSON.stringify({
+    __e2ePayload: E2E_PAYLOAD_VERSION,
+    contentMarkdown,
+    attachmentRefs: attachmentRefs ?? [],
+    ...hasSources ? { sources } : {},
+    ...hasDraftBody ? { draftContentJson } : {}
+  });
+}
+function isAttachmentRef(value) {
+  if (typeof value !== "object" || value === null)
+    return false;
+  const r = value;
+  return typeof r.attachmentId === "string" && typeof r.key === "string" && typeof r.iv === "string" && typeof r.filename === "string" && typeof r.mimeType === "string" && typeof r.sizeBytes === "number";
+}
+function isSealedSourceItem(value) {
+  if (typeof value !== "object" || value === null)
+    return false;
+  const s = value;
+  return typeof s.title === "string" && typeof s.url === "string" && (s.type === undefined || typeof s.type === "string") && (s.snippet === undefined || typeof s.snippet === "string");
+}
+function isDocLike(value) {
+  if (typeof value !== "object" || value === null)
+    return false;
+  const v = value;
+  return v.type === "doc" && Array.isArray(v.content);
+}
+function parseSealedPayload(raw) {
+  if (raw.startsWith("{")) {
+    try {
+      const parsed = JSON.parse(raw);
+      if (parsed.__e2ePayload === E2E_PAYLOAD_VERSION && typeof parsed.contentMarkdown === "string") {
+        const attachmentRefs = Array.isArray(parsed.attachmentRefs) ? parsed.attachmentRefs.filter(isAttachmentRef) : [];
+        const sources = Array.isArray(parsed.sources) ? parsed.sources.filter(isSealedSourceItem) : [];
+        const draftContentJson = isDocLike(parsed.draftContentJson) ? parsed.draftContentJson : null;
+        return { contentMarkdown: parsed.contentMarkdown, attachmentRefs, sources, draftContentJson };
+      }
+    } catch {}
+  }
+  return { contentMarkdown: raw, attachmentRefs: [], sources: [], draftContentJson: null };
+}
+
+// src/sealed.ts
+var THREA_CALLBACK_TOKEN_HEADER = "X-Threa-Callback-Token";
+async function mintE2eKeyRecord() {
+  const keyPair = await generateKeyPair();
+  return {
+    keyId: `bik_${ulid()}`,
+    publicKey: bytesToBase64(await exportPublicKey(keyPair.publicKey)),
+    privateKey: bytesToBase64(await exportPrivateKey(keyPair.privateKey))
+  };
+}
+
+class BotKeyring {
+  buildRecords;
+  log;
+  records;
+  cached = [];
+  queue = Promise.resolve([]);
+  loaded = false;
+  constructor(opts) {
+    this.buildRecords = opts.keyring;
+    this.log = opts.log ?? ((message) => console.error(message));
+  }
+  get identities() {
+    return this.cached;
+  }
+  async ensure() {
+    if (this.loaded)
+      return this.cached;
+    return this.enqueue((keyring) => keyring.ensure());
+  }
+  async ensureForStream(streamId) {
+    return this.enqueue((keyring) => keyring.ensureForStream(streamId));
+  }
+  async identityForStream(streamId) {
+    const identities = await this.ensureForStream(streamId);
+    const record = this.records?.forStream(streamId);
+    return record ? identities.find((identity) => identity.publicKeyId === record.keyId) : undefined;
+  }
+  async dropStream(streamId) {
+    return this.enqueue(async (keyring) => keyring.dropStream(streamId));
+  }
+  presenceFields() {
+    return this.records?.presenceFields() ?? {};
+  }
+  enqueue(work) {
+    const next = this.queue.then(async () => {
+      try {
+        this.records ??= this.buildRecords();
+        this.cached = await importAll(await work(this.records));
+        this.loaded = this.cached.length > 0;
+      } catch (error) {
+        this.log(`Threa sealed: key load/create failed; sealed scratchpads are unavailable: ${String(error)}`);
+      }
+      return this.cached;
+    });
+    this.queue = next;
+    return next;
+  }
+}
+async function importAll(records) {
+  const identities = [];
+  for (const record of records) {
+    identities.push({
+      publicKeyId: record.keyId,
+      publicKeyBase64: record.publicKey,
+      privateKey: await importRecipientPrivateKey(base64ToBytes(record.privateKey))
+    });
+  }
+  return identities;
+}
+function isEnvelope(value) {
+  if (typeof value !== "object" || value === null)
+    return false;
+  const v = value;
+  return typeof v.v === "number" && typeof v.keyGeneration === "number" && typeof v.iv === "string" && typeof v.aad === "string";
+}
+function isSealedMessage(value) {
+  if (typeof value !== "object" || value === null)
+    return false;
+  const m = value;
+  return typeof m.ciphertext === "string" && isEnvelope(m.envelope);
+}
+function parseSealedTurnContext(raw) {
+  if (typeof raw !== "object" || raw === null)
+    return;
+  const c = raw;
+  if (typeof c.callbackToken !== "string" || c.callbackToken.length === 0)
+    return;
+  if (!Array.isArray(c.wraps))
+    return;
+  const wraps = [];
+  for (const wrap of c.wraps) {
+    if (typeof wrap !== "object" || wrap === null)
+      return;
+    const w = wrap;
+    if (typeof w.keyGeneration !== "number" || typeof w.wrapEnc !== "string" || typeof w.wrapCt !== "string") {
+      return;
+    }
+    wraps.push({ keyGeneration: w.keyGeneration, wrapEnc: w.wrapEnc, wrapCt: w.wrapCt });
+  }
+  if (!isSealedMessage(c.prompt))
+    return;
+  const reply = c.reply;
+  if (!reply || typeof reply.keyGeneration !== "number" || typeof reply.senderId !== "string")
+    return;
+  const history = [];
+  if (c.history !== undefined) {
+    if (!Array.isArray(c.history))
+      return;
+    for (const item of c.history) {
+      if (!isSealedMessage(item))
+        return;
+      const h = item;
+      const role = h.role === "assistant" ? "assistant" : "user";
+      history.push({
+        ciphertext: item.ciphertext,
+        envelope: item.envelope,
+        role,
+        sequence: typeof h.sequence === "string" ? h.sequence : "0"
+      });
+    }
+  }
+  const trigger = c.trigger;
+  return {
+    callbackToken: c.callbackToken,
+    wraps,
+    history,
+    prompt: c.prompt,
+    reply: { keyGeneration: reply.keyGeneration, senderId: reply.senderId },
+    ...trigger && typeof trigger.messageId === "string" && typeof trigger.authorName === "string" && typeof trigger.authorType === "string" && typeof trigger.createdAt === "string" ? {
+      trigger: {
+        messageId: trigger.messageId,
+        authorName: trigger.authorName,
+        authorType: trigger.authorType,
+        createdAt: trigger.createdAt
+      }
+    } : {}
+  };
+}
+async function unwrapWithAny(params) {
+  const { wrap, identities, streamId } = params;
+  for (const identity of identities) {
+    try {
+      return await unwrapStreamKey({
+        enc: base64ToBytes(wrap.wrapEnc),
+        ct: base64ToBytes(wrap.wrapCt),
+        recipientPrivateKey: identity.privateKey,
+        aad: buildWrapAad({ streamId, keyGeneration: wrap.keyGeneration, recipientKeyId: identity.publicKeyId })
+      });
+    } catch {
+      continue;
+    }
+  }
+  return;
+}
+async function openSealedTurnContext(params) {
+  const { sealed, identities, streamId } = params;
+  const sskByGeneration = new Map;
+  for (const wrap of sealed.wraps) {
+    const ssk = await unwrapWithAny({ wrap, identities, streamId });
+    if (ssk)
+      sskByGeneration.set(wrap.keyGeneration, ssk);
+  }
+  const promptSsk = sskByGeneration.get(sealed.prompt.envelope.keyGeneration);
+  if (!promptSsk)
+    throw new Error("Sealed claim: no SSK wrap for the prompt's key generation");
+  const promptRaw = await openMessageAsString({
+    key: promptSsk,
+    envelope: sealed.prompt.envelope,
+    ciphertext: base64ToBytes(sealed.prompt.ciphertext)
+  });
+  const promptPayload = parseSealedPayload(promptRaw);
+  const replySsk = sskByGeneration.get(sealed.reply.keyGeneration);
+  if (!replySsk)
+    throw new Error("Sealed claim: no SSK wrap for the reply's key generation");
+  const history = [];
+  for (const item of sealed.history) {
+    const ssk = sskByGeneration.get(item.envelope.keyGeneration);
+    if (!ssk)
+      continue;
+    try {
+      const raw = await openMessageAsString({
+        key: ssk,
+        envelope: item.envelope,
+        ciphertext: base64ToBytes(item.ciphertext)
+      });
+      const payload = parseSealedPayload(raw);
+      history.push({
+        role: item.role,
+        sequence: item.sequence,
+        contentMarkdown: payload.contentMarkdown,
+        attachmentRefs: payload.attachmentRefs
+      });
+    } catch {
+      continue;
+    }
+  }
+  return {
+    promptMarkdown: promptPayload.contentMarkdown,
+    promptAttachmentRefs: promptPayload.attachmentRefs,
+    history,
+    sealing: {
+      streamId,
+      replyKeyGeneration: sealed.reply.keyGeneration,
+      replySenderId: sealed.reply.senderId,
+      replySsk,
+      callbackToken: sealed.callbackToken
+    }
+  };
+}
+async function sealReply(sealing, markdown, extras) {
+  const messageId = `msg_${ulid()}`;
+  const sealed = await sealMessage({
+    key: sealing.replySsk,
+    keyGeneration: sealing.replyKeyGeneration,
+    payload: serializeSealedPayload(markdown, extras),
+    aad: buildMessageAad({ streamId: sealing.streamId, messageId, senderId: sealing.replySenderId })
+  });
+  return { messageId, ciphertext: bytesToBase64(sealed.ciphertext), envelope: sealed.envelope };
+}
+async function sealStep(sealing, stepType, content, opts) {
+  const stepId = `step_${ulid()}`;
+  const sealed = await sealMessage({
+    key: sealing.replySsk,
+    keyGeneration: sealing.replyKeyGeneration,
+    payload: serializeSealedPayload(content),
+    aad: buildMessageAad({ streamId: sealing.streamId, messageId: stepId, senderId: sealing.replySenderId })
+  });
+  return {
+    stepId,
+    stepType,
+    ciphertext: bytesToBase64(sealed.ciphertext),
+    envelope: sealed.envelope,
+    ...opts?.durationMs !== undefined ? { durationMs: opts.durationMs } : {}
+  };
+}
+async function sealDecision(sealing, card, content) {
+  const decisionId = `dreq_${ulid()}`;
+  const sealed = await sealMessage({
+    key: sealing.replySsk,
+    keyGeneration: sealing.replyKeyGeneration,
+    payload: JSON.stringify(content),
+    aad: buildDecisionAad({ streamId: card.streamId, decisionId, requesterBotId: card.requesterBotId })
+  });
+  return { decisionId, ciphertext: bytesToBase64(sealed.ciphertext), envelope: sealed.envelope };
+}
+async function openSealedDecisionNote(sealing, note) {
+  const expected = bytesToBase64(buildDecisionNoteAad({
+    streamId: note.streamId,
+    decisionId: note.decisionId,
+    decidedBy: note.decidedBy
+  }));
+  if (note.envelope.aad !== expected)
+    return null;
+  if (note.envelope.keyGeneration !== sealing.replyKeyGeneration)
+    return null;
+  try {
+    return await openMessageAsString({
+      key: sealing.replySsk,
+      envelope: note.envelope,
+      ciphertext: base64ToBytes(note.ciphertext)
+    });
+  } catch {
+    return null;
+  }
+}
+function scrubSealedError(error) {
+  return error instanceof Error ? error.name || "Error" : "Error";
+}
+function parseSealedAckContext(raw) {
+  if (typeof raw !== "object" || raw === null)
+    return;
+  const c = raw;
+  if (!Array.isArray(c.wraps))
+    return;
+  const wraps = [];
+  for (const wrap of c.wraps) {
+    if (typeof wrap !== "object" || wrap === null)
+      return;
+    const w = wrap;
+    if (typeof w.keyGeneration !== "number" || typeof w.wrapEnc !== "string" || typeof w.wrapCt !== "string") {
+      return;
+    }
+    wraps.push({ keyGeneration: w.keyGeneration, wrapEnc: w.wrapEnc, wrapCt: w.wrapCt });
+  }
+  const reply = c.reply;
+  if (!reply || typeof reply.keyGeneration !== "number" || typeof reply.senderId !== "string")
+    return;
+  return { wraps, reply: { keyGeneration: reply.keyGeneration, senderId: reply.senderId } };
+}
+async function openSealedAck(params) {
+  const { ack, identities, streamId } = params;
+  let replySsk;
+  for (const wrap of ack.wraps) {
+    if (wrap.keyGeneration !== ack.reply.keyGeneration)
+      continue;
+    replySsk = await unwrapWithAny({ wrap, identities, streamId });
+    if (replySsk)
+      break;
+  }
+  if (!replySsk)
+    throw new Error("Sealed ack: no SSK wrap for the reply's key generation");
+  return {
+    streamId,
+    replyKeyGeneration: ack.reply.keyGeneration,
+    replySenderId: ack.reply.senderId,
+    replySsk,
+    callbackToken: ""
+  };
+}
+async function mintStreamKeyWraps(params) {
+  const ssk = generateStreamKey();
+  const wraps = [];
+  for (const recipient of params.recipients) {
+    const publicKey = await importRecipientPublicKey(base64ToBytes(recipient.publicKeyBase64));
+    const wrapped = await wrapStreamKey({
+      key: ssk,
+      recipientPublicKey: publicKey,
+      aad: buildWrapAad({
+        streamId: params.streamId,
+        keyGeneration: params.keyGeneration,
+        recipientKeyId: recipient.recipientKeyId
+      })
+    });
+    wraps.push({
+      recipientKind: recipient.recipientKind,
+      recipientKeyId: recipient.recipientKeyId,
+      wrapEnc: bytesToBase64(wrapped.enc),
+      wrapCt: bytesToBase64(wrapped.ct)
+    });
+  }
+  return { wraps };
+}
+
+// src/ws-hint.ts
+function isObject(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function parseWsHint(value) {
+  if (!isObject(value))
+    return;
+  const url = typeof value.url === "string" ? value.url.trim() : "";
+  if (!url)
+    return;
+  const path = typeof value.path === "string" && value.path.trim() ? value.path.trim() : "/socket.io/";
+  const namespace = typeof value.namespace === "string" && value.namespace.trim() ? value.namespace.trim() : "/bot";
+  return { url, path, namespace };
+}
+function buildBotSocketUrl(hint) {
+  const parsed = new URL(hint.url);
+  const trimmedPath = parsed.pathname.replace(/\/$/, "");
+  parsed.pathname = `${trimmedPath}${hint.namespace}`;
+  return parsed.toString();
+}
+
+// src/invocation-control.ts
+var BOT_INVOCATION_CANCELLATION_REASONS = [
+  "source_deleted",
+  "routing_changed",
+  "input_restart",
+  "input_stale",
+  "key_grant_lost"
+];
+
+class InvocationControlManager {
+  hooks;
+  observations = new Map;
+  pendingTerminalGenerations = new Map;
+  queue = Promise.resolve();
+  stopped = false;
+  generation = 0;
+  retryDelayMs;
+  minRenewDelayMs;
+  now;
+  scheduler;
+  constructor(hooks, options = {}) {
+    this.hooks = hooks;
+    this.retryDelayMs = options.retryDelayMs ?? 5000;
+    this.minRenewDelayMs = options.minRenewDelayMs ?? 1000;
+    this.now = options.now ?? Date.now;
+    this.scheduler = options.scheduler ?? {
+      setTimeout: (callback, delayMs) => setTimeout(callback, delayMs),
+      clearTimeout: (handle) => clearTimeout(handle)
+    };
+  }
+  observe(params) {
+    this.pendingTerminalGenerations.delete(params.invocationId);
+    const prior = this.observations.get(params.invocationId);
+    if (prior)
+      this.unregister(prior);
+    const observation = {
+      generation: ++this.generation,
+      invocationId: params.invocationId,
+      claimTtlSeconds: params.claimTtlSeconds,
+      instanceId: params.instanceId,
+      claimToken: params.claimToken,
+      callbacks: params.callbacks,
+      sealedBinding: params.sealed ? {
+        identities: params.sealed.identities,
+        streamId: params.sealed.streamId,
+        callbackToken: params.sealed.callbackToken
+      } : undefined,
+      appliedRevision: params.sourceRevision,
+      highWaterRevision: params.sourceRevision,
+      terminal: false,
+      dirty: false,
+      abortController: new AbortController,
+      enqueuedRevisions: new Set
+    };
+    this.observations.set(params.invocationId, observation);
+    this.requestSync(observation);
+    return {
+      sync: () => this.syncAndDrain(observation),
+      unregister: () => this.unregister(observation),
+      dispose: () => this.unregister(observation)
+    };
+  }
+  hint(payload, cancelled) {
+    const hint = cancelled ? parseInvocationCancellation(payload) : parseUpdateHint(payload);
+    if (!hint)
+      return;
+    const observation = this.observations.get(hint.invocationId);
+    if (!observation)
+      return;
+    if (cancelled) {
+      this.terminalizeCancellation(observation, hint);
+      return;
+    }
+    if (hint.sourceRevision <= observation.highWaterRevision)
+      return;
+    observation.highWaterRevision = hint.sourceRevision;
+    this.requestSync(observation);
+  }
+  async bootstrap(recentCancellations, callback) {
+    for (const value of recentCancellations) {
+      const cancellation = parseInvocationCancellation(value);
+      if (!cancellation)
+        continue;
+      const observation = this.observations.get(cancellation.invocationId);
+      if (observation)
+        this.terminalizeCancellation(observation, cancellation);
+    }
+    for (const observation of this.observations.values())
+      this.requestSync(observation);
+    await this.enqueueAdapter(callback);
+  }
+  wake() {
+    for (const observation of this.observations.values())
+      this.requestSync(observation);
+  }
+  async enqueueAdapter(callback) {
+    await this.awaitStableControls();
+    if (!this.stopped) {
+      await this.enqueue(async () => {
+        if (this.stopped)
+          return;
+        try {
+          callback();
+        } catch {
+          this.hooks.log("invocation availability callback failed");
+        }
+      });
+    }
+  }
+  stop() {
+    this.stopped = true;
+    this.pendingTerminalGenerations.clear();
+    for (const observation of [...this.observations.values()])
+      this.unregister(observation);
+  }
+  async syncAndDrain(observation) {
+    if (this.isCurrent(observation))
+      this.requestSync(observation);
+    await this.awaitStableControls();
+  }
+  requestSync(observation) {
+    if (!this.isCurrent(observation))
+      return Promise.resolve();
+    observation.dirty = true;
+    if (observation.drain)
+      return observation.drain;
+    const drain = Promise.resolve().then(() => this.runDrain(observation));
+    observation.drain = drain;
+    return drain;
+  }
+  async runDrain(observation) {
+    while (this.isCurrent(observation) && observation.dirty) {
+      observation.dirty = false;
+      const restartRevision = observation.restartPendingRevision;
+      const knownSourceRevision = restartRevision ?? observation.appliedRevision;
+      const request = {
+        invocationId: observation.invocationId,
+        instanceId: observation.instanceId,
+        claimToken: observation.claimToken,
+        claimTtlSeconds: observation.claimTtlSeconds,
+        knownSourceRevision,
+        minimumSourceRevision: observation.appliedRevision,
+        ...restartRevision === undefined ? {} : { restartRequiredRevision: restartRevision },
+        ackTimeoutMs: Math.min(5000, observation.claimTtlSeconds * 1000 / 6),
+        signal: observation.abortController.signal
+      };
+      const authorityBehind = await this.runSync(observation, request);
+      if (!this.isCurrent(observation))
+        break;
+      if (authorityBehind) {
+        if (observation.immediateFollowupRevision !== observation.highWaterRevision) {
+          observation.immediateFollowupRevision = observation.highWaterRevision;
+          observation.dirty = true;
+        } else {
+          this.schedule(observation, this.retryDelayMs);
+        }
+      } else {
+        observation.immediateFollowupRevision = undefined;
+      }
+    }
+    observation.drain = undefined;
+  }
+  async runSync(observation, request) {
+    let result;
+    try {
+      result = await this.hooks.sync(request);
+    } catch {
+      result = { kind: "retry" };
+      this.hooks.log(`invocation control sync failed (${observation.invocationId})`);
+    }
+    if (!this.isCurrent(observation) || result.kind === "aborted")
+      return false;
+    if (result.kind === "not_found") {
+      if (request.restartRequiredRevision !== undefined) {
+        observation.restartPendingRevision = undefined;
+        observation.dirty = true;
+      } else {
+        const callback = observation.callbacks?.onClaimLost;
+        this.makeTerminal(observation, callback);
+      }
+      return false;
+    }
+    if (result.kind === "retry") {
+      this.schedule(observation, this.retryDelayMs);
+      return false;
+    }
+    const state = result.state;
+    if (state.status === "cancelled") {
+      const cancellation = {
+        invocationId: state.invocationId,
+        sourceRevision: state.sourceRevision,
+        reason: state.reason
+      };
+      if (!this.terminalizeCancellation(observation, cancellation))
+        this.schedule(observation, this.retryDelayMs);
+      return false;
+    }
+    const expiresAt = Date.parse(state.claimExpiresAt);
+    if (!Number.isFinite(expiresAt)) {
+      this.schedule(observation, this.retryDelayMs);
+      return false;
+    }
+    observation.claimExpiresAtMs = expiresAt;
+    observation.highWaterRevision = Math.max(observation.highWaterRevision, state.sourceRevision);
+    this.schedule(observation);
+    if (request.restartRequiredRevision !== undefined) {
+      if (observation.restartPendingRevision === request.restartRequiredRevision) {
+        this.schedule(observation, this.retryDelayMs);
+      }
+      return state.sourceRevision < observation.highWaterRevision;
+    }
+    if (state.sourceRevision > observation.appliedRevision) {
+      if (state.update)
+        await this.prepareUpdate(observation, state.update);
+      else
+        this.schedule(observation, this.retryDelayMs);
+    }
+    return state.sourceRevision < observation.highWaterRevision;
+  }
+  async prepareUpdate(observation, raw) {
+    const revision = parseRevision(isObject(raw) ? raw.sourceRevision : undefined);
+    if (revision === undefined || revision <= observation.appliedRevision)
+      return;
+    const highestEnqueued = Math.max(observation.appliedRevision, ...observation.enqueuedRevisions);
+    if (revision <= highestEnqueued || observation.restartPendingRevision !== undefined)
+      return;
+    let update;
+    try {
+      update = await openUpdate(observation, raw);
+    } catch (error) {
+      this.hooks.log(`sealed invocation update failed (${observation.invocationId}): ${scrubSealedError(error)}`);
+      this.markRestartPending(observation, revision);
+      return;
+    }
+    if (!this.isCurrent(observation))
+      return;
+    observation.enqueuedRevisions.add(revision);
+    const invocationId = observation.invocationId;
+    const generation = observation.generation;
+    this.enqueue(async () => {
+      const current = this.observations.get(invocationId);
+      if (!current || current.generation !== generation || current.terminal || this.stopped)
+        return;
+      if (revision <= current.appliedRevision || current.restartPendingRevision !== undefined) {
+        current.enqueuedRevisions.delete(revision);
+        return;
+      }
+      let disposition = "restart-required";
+      try {
+        disposition = await current.callbacks?.onInputUpdated(update, current.abortController.signal) ?? "restart-required";
+      } catch {
+        disposition = "restart-required";
+      }
+      const stillCurrent = this.observations.get(invocationId);
+      if (!stillCurrent || stillCurrent.generation !== generation || stillCurrent.terminal)
+        return;
+      stillCurrent.enqueuedRevisions.delete(revision);
+      if (disposition === "applied") {
+        stillCurrent.appliedRevision = revision;
+        if (stillCurrent.highWaterRevision > revision)
+          this.requestSync(stillCurrent);
+      } else {
+        this.markRestartPending(stillCurrent, revision);
+      }
+    });
+  }
+  markRestartPending(observation, revision) {
+    if (!this.isCurrent(observation))
+      return;
+    if (observation.restartPendingRevision !== undefined && observation.restartPendingRevision >= revision)
+      return;
+    observation.restartPendingRevision = revision;
+    observation.enqueuedRevisions.clear();
+    this.requestSync(observation);
+  }
+  highestLocallyKnownRevision(observation) {
+    return Math.max(observation.appliedRevision, observation.highWaterRevision, ...observation.enqueuedRevisions, observation.restartPendingRevision ?? -1);
+  }
+  terminalizeCancellation(observation, cancellation) {
+    if (!this.isCurrent(observation) || cancellation.sourceRevision < this.highestLocallyKnownRevision(observation)) {
+      return false;
+    }
+    this.makeTerminal(observation, observation.callbacks?.onCancelled);
+    return true;
+  }
+  makeTerminal(observation, callback) {
+    if (!this.isCurrent(observation))
+      return;
+    this.teardown(observation);
+    if (!callback)
+      return;
+    const { generation, invocationId } = observation;
+    this.pendingTerminalGenerations.set(invocationId, generation);
+    this.enqueue(async () => {
+      if (this.stopped || this.pendingTerminalGenerations.get(invocationId) !== generation)
+        return;
+      try {
+        await callback();
+      } catch {
+        this.hooks.log(`invocation cancellation callback failed (${invocationId})`);
+      } finally {
+        if (this.pendingTerminalGenerations.get(invocationId) === generation) {
+          this.pendingTerminalGenerations.delete(invocationId);
+        }
+      }
+    });
+  }
+  unregister(observation) {
+    if (this.pendingTerminalGenerations.get(observation.invocationId) === observation.generation) {
+      this.pendingTerminalGenerations.delete(observation.invocationId);
+    }
+    if (observation.terminal)
+      return;
+    this.teardown(observation);
+  }
+  teardown(observation) {
+    observation.terminal = true;
+    observation.abortController.abort();
+    if (observation.timer !== undefined)
+      this.scheduler.clearTimeout(observation.timer);
+    observation.timer = undefined;
+    if (this.observations.get(observation.invocationId) === observation) {
+      this.observations.delete(observation.invocationId);
+    }
+    this.scrub(observation);
+  }
+  scrub(observation) {
+    observation.claimToken = "";
+    observation.callbacks = undefined;
+    observation.sealedBinding = undefined;
+    observation.enqueuedRevisions.clear();
+    observation.restartPendingRevision = undefined;
+    observation.immediateFollowupRevision = undefined;
+  }
+  schedule(observation, requestedDelay) {
+    if (!this.isCurrent(observation))
+      return;
+    if (observation.timer !== undefined)
+      this.scheduler.clearTimeout(observation.timer);
+    const nominalLeaseMs = observation.claimTtlSeconds * 1000;
+    const safetyMs = Math.min(30000, Math.max(this.minRenewDelayMs, nominalLeaseMs / 3));
+    const authoritativeDelay = observation.claimExpiresAtMs === undefined ? this.retryDelayMs : Math.max(this.minRenewDelayMs, observation.claimExpiresAtMs - this.now() - safetyMs);
+    let delay = requestedDelay === undefined ? authoritativeDelay : Math.min(authoritativeDelay, requestedDelay);
+    if (!this.hooks.socketReady())
+      delay = Math.min(delay, this.retryDelayMs);
+    observation.timer = this.scheduler.setTimeout(() => {
+      observation.timer = undefined;
+      this.requestSync(observation);
+    }, Math.max(this.minRenewDelayMs, delay));
+  }
+  isCurrent(observation) {
+    return !this.stopped && !observation.terminal && this.observations.get(observation.invocationId) === observation;
+  }
+  enqueue(work) {
+    const result = this.queue.then(work, work);
+    this.queue = result.catch(() => {});
+    return result;
+  }
+  async awaitStableControls() {
+    while (true) {
+      const drains = [...this.observations.values()].flatMap((observation) => observation.drain ? [observation.drain] : []);
+      await Promise.allSettled(drains);
+      const adapterQueue = this.queue;
+      await adapterQueue;
+      if (this.queue === adapterQueue && [...this.observations.values()].every((observation) => observation.drain === undefined)) {
+        return;
+      }
+    }
+  }
+}
+async function openUpdate(observation, raw) {
+  if (!isObject(raw))
+    throw new Error("Invalid update");
+  const sourceRevision = parseRevision(raw.sourceRevision);
+  if (sourceRevision === undefined)
+    throw new Error("Invalid update");
+  const expectsSealed = observation.sealedBinding !== undefined;
+  if (!expectsSealed && raw.delivery === "plaintext" && typeof raw.promptMarkdown === "string") {
+    return {
+      sourceRevision,
+      delivery: "plaintext",
+      promptMarkdown: raw.promptMarkdown,
+      attachmentRefs: []
+    };
+  }
+  if (!expectsSealed || raw.delivery !== "sealed" || !observation.sealedBinding) {
+    throw new Error("Invalid update delivery");
+  }
+  const sealed = parseSealedTurnContext({
+    callbackToken: observation.sealedBinding.callbackToken,
+    wraps: raw.wraps,
+    history: [],
+    prompt: raw.prompt,
+    reply: raw.reply
+  });
+  if (!sealed)
+    throw new Error("Invalid sealed update");
+  const opened = await openSealedTurnContext({
+    sealed,
+    identities: observation.sealedBinding.identities,
+    streamId: observation.sealedBinding.streamId
+  });
+  return {
+    sourceRevision,
+    delivery: "sealed",
+    promptMarkdown: opened.promptMarkdown,
+    attachmentRefs: opened.promptAttachmentRefs,
+    sealing: opened.sealing
+  };
+}
+var cancellationReasonSet = new Set(BOT_INVOCATION_CANCELLATION_REASONS);
+function parseCancellationReason(value) {
+  if (value === "adapter_restart_required")
+    return "input_restart";
+  return typeof value === "string" && cancellationReasonSet.has(value) ? value : undefined;
+}
+function parseInvocationCancellation(value) {
+  if (!isObject(value) || typeof value.invocationId !== "string")
+    return;
+  const sourceRevision = parseRevision(value.sourceRevision);
+  const reason = parseCancellationReason(value.reason);
+  if (sourceRevision === undefined || !reason)
+    return;
+  return { invocationId: value.invocationId, sourceRevision, reason };
+}
+function parseUpdateHint(value) {
+  if (!isObject(value) || typeof value.invocationId !== "string")
+    return;
+  const sourceRevision = parseRevision(value.sourceRevision);
+  return sourceRevision === undefined ? undefined : { invocationId: value.invocationId, sourceRevision };
+}
+function parseRevision(value) {
+  return Number.isInteger(value) && value >= 0 ? value : undefined;
+}
+
+// src/transport.ts
+var DEFAULT_WS_ACK_TIMEOUT_MS = 5000;
+var DEFAULT_RECONNECTION_DELAY_MAX_MS = 30000;
+var DEFAULT_FETCH_TIMEOUT_MS = 30000;
+var DEFAULT_STALE_SOCKET_REDIAL_MS = 3 * 60 * 1000;
+
+class BotRuntimeTransport {
+  base;
+  workspaceId;
+  apiKey;
+  hello;
+  beforeHello;
+  callbacks;
+  wsAckTimeoutMs;
+  reconnectionDelayMaxMs;
+  fetchTimeoutMs;
+  staleSocketRedialMs;
+  logFn;
+  socket;
+  connected = false;
+  helloReady = false;
+  helloInFlight = false;
+  connecting = false;
+  stopped = false;
+  redialTimer;
+  disconnectedAt;
+  cursor;
+  controls;
+  constructor(opts) {
+    this.base = opts.baseUrl.replace(/\/$/, "");
+    this.workspaceId = opts.workspaceId;
+    this.apiKey = opts.apiKey;
+    this.hello = opts.hello;
+    this.beforeHello = opts.beforeHello;
+    this.callbacks = opts.callbacks ?? {};
+    this.wsAckTimeoutMs = opts.wsAckTimeoutMs ?? DEFAULT_WS_ACK_TIMEOUT_MS;
+    this.reconnectionDelayMaxMs = opts.reconnectionDelayMaxMs ?? DEFAULT_RECONNECTION_DELAY_MAX_MS;
+    this.fetchTimeoutMs = opts.fetchTimeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS;
+    this.staleSocketRedialMs = opts.staleSocketRedialMs ?? DEFAULT_STALE_SOCKET_REDIAL_MS;
+    this.logFn = opts.log ?? (() => {});
+    this.controls = new InvocationControlManager({
+      sync: (request) => this.syncObservedClaim(request),
+      socketReady: () => this.socketConnected,
+      log: this.logFn
+    }, {
+      retryDelayMs: opts.controlRetryDelayMs,
+      minRenewDelayMs: opts.controlMinRenewDelayMs,
+      scheduler: opts.controlScheduler
+    });
+  }
+  get socketConnected() {
+    return this.connected && this.helloReady;
+  }
+  async connect() {
+    if (this.connecting || this.stopped)
+      return;
+    if (this.socket) {
+      if (this.connected) {
+        if (!this.helloReady)
+          this.sendHello();
+        return;
+      }
+      const outageMs = Date.now() - (this.disconnectedAt ?? Date.now());
+      if (outageMs < this.staleSocketRedialMs)
+        return;
+      this.logFn(`socket disconnected for ${Math.round(outageMs / 1000)}s; redialing from a fresh hint`);
+      this.teardownSocket();
+    }
+    this.connecting = true;
+    try {
+      let hint;
+      try {
+        hint = await this.resolveWsHint();
+      } catch (error) {
+        this.logFn(`ws hint resolve failed (staying on HTTP): ${summarize(error)}`);
+      }
+      if (hint)
+        this.attachSocket(hint);
+    } finally {
+      this.connecting = false;
+    }
+  }
+  attachSocket(hint) {
+    if (this.socket || this.stopped)
+      return;
+    let socket;
+    try {
+      socket = socketIoClient.io(buildBotSocketUrl(hint), {
+        path: hint.path,
+        auth: { token: this.apiKey },
+        transports: ["websocket"],
+        reconnection: true,
+        reconnectionDelayMax: this.reconnectionDelayMaxMs
+      });
+    } catch (error) {
+      this.logFn(`socket attach failed (HTTP only): ${summarize(error)}`);
+      return;
+    }
+    this.socket = socket;
+    this.disconnectedAt = Date.now();
+    socket.on("connect", () => {
+      this.connected = true;
+      this.helloReady = false;
+      this.disconnectedAt = undefined;
+      this.sendHello();
+    });
+    socket.on("disconnect", (reason) => {
+      const wasReady = this.socketConnected;
+      this.connected = false;
+      this.helloReady = false;
+      this.helloInFlight = false;
+      this.disconnectedAt ??= Date.now();
+      if (wasReady)
+        this.callbacks.onDisconnected?.();
+      this.controls.wake();
+      if (reason === "io server disconnect")
+        socket.connect();
+    });
+    socket.on("connect_error", (error) => {
+      const wasReady = this.socketConnected;
+      this.connected = false;
+      this.helloReady = false;
+      this.helloInFlight = false;
+      this.disconnectedAt ??= Date.now();
+      if (wasReady)
+        this.callbacks.onDisconnected?.();
+      this.controls.wake();
+      this.logFn(`socket connect_error: ${summarize(error)}`);
+    });
+    socket.on("bot_invocation:available", () => this.controls.enqueueAdapter(() => this.callbacks.onInvocationAvailable?.()));
+    socket.on("bot_invocation:input_updated", (payload) => this.controls.hint(payload, false));
+    socket.on("bot_invocation:cancelled", (payload) => this.controls.hint(payload, true));
+    socket.on("delegation:available", (payload) => this.callbacks.onDelegationAvailable?.(payload));
+    socket.on("bot_invocation:claimed", (payload) => this.callbacks.onInvocationClaimed?.(payload));
+    socket.on("bot:active_actor_changed", (payload) => this.callbacks.onActiveActorChanged?.(payload));
+    socket.on("bot:session_archived", (payload) => this.callbacks.onSessionArchived?.(payload));
+    socket.on("bot:session_restored", (payload) => this.callbacks.onSessionRestored?.(payload));
+    socket.on("decision:resolved", (payload) => this.callbacks.onDecisionResolved?.(payload));
+    socket.on("decision:cancelled", (payload) => this.callbacks.onDecisionCancelled?.(payload));
+    socket.on("bot:e2e_grant", (payload) => this.callbacks.onE2eGrant?.(payload));
+    socket.on("bot:e2e_revoke", (payload) => this.callbacks.onE2eRevoke?.(payload));
+    socket.on("bot:resync", () => {
+      this.callbacks.onResync?.();
+      this.teardownSocket();
+      this.connect();
+    });
+  }
+  sendHello() {
+    const socket = this.socket;
+    if (!socket || this.helloInFlight)
+      return;
+    this.helloInFlight = true;
+    this.beforeHello?.(this.hello);
+    socket.timeout(this.wsAckTimeoutMs).emit("bot:hello", { ...this.hello, ...this.cursor ? { sinceCursor: this.cursor } : {} }, (error, ack) => {
+      if (socket !== this.socket)
+        return;
+      this.helloInFlight = false;
+      if (error || !isObject(ack) || ack.ok !== true) {
+        this.logFn(`bot:hello rejected: ${error ? summarize(error) : isObject(ack) ? String(ack.error) : "no ack"}`);
+        this.teardownSocket();
+        this.scheduleRedial();
+        return;
+      }
+      this.helloReady = true;
+      if (typeof ack.serverGeneratedAt === "string")
+        this.cursor = ack.serverGeneratedAt;
+      const bootstrap = {
+        serverGeneratedAt: typeof ack.serverGeneratedAt === "string" ? ack.serverGeneratedAt : undefined,
+        ...typeof ack.botId === "string" ? { botId: ack.botId } : {},
+        availableInvocations: Array.isArray(ack.availableInvocations) ? ack.availableInvocations : [],
+        ownedClaims: Array.isArray(ack.ownedClaims) ? ack.ownedClaims : [],
+        e2eGrantedStreamIds: Array.isArray(ack.e2eGrantedStreamIds) ? ack.e2eGrantedStreamIds.filter((id) => typeof id === "string") : []
+      };
+      this.controls.bootstrap(Array.isArray(ack.recentCancellations) ? ack.recentCancellations : [], () => this.callbacks.onBootstrap?.(bootstrap));
+    });
+  }
+  disconnect() {
+    this.stopped = true;
+    if (this.redialTimer)
+      clearTimeout(this.redialTimer);
+    this.redialTimer = undefined;
+    this.controls.stop();
+    this.teardownSocket();
+  }
+  scheduleRedial() {
+    if (this.stopped || this.redialTimer)
+      return;
+    this.redialTimer = setTimeout(() => {
+      this.redialTimer = undefined;
+      this.connect();
+    }, this.reconnectionDelayMaxMs);
+  }
+  teardownSocket() {
+    const wasReady = this.socketConnected;
+    this.connected = false;
+    this.helloReady = false;
+    this.helloInFlight = false;
+    this.disconnectedAt = undefined;
+    if (wasReady)
+      this.callbacks.onDisconnected?.();
+    const socket = this.socket;
+    this.socket = undefined;
+    if (socket) {
+      try {
+        socket.removeAllListeners();
+        socket.disconnect();
+      } catch {}
+    }
+  }
+  observeClaim(params) {
+    return this.controls.observe(params);
+  }
+  async recordSteps(invocationId, claimToken, steps, statusText, instanceId = this.hello.instanceId) {
+    if (steps.length === 0)
+      return;
+    const keyed = steps.map((step) => ({ ...step, clientStepId: step.clientStepId ?? crypto.randomUUID() }));
+    const { sent, ack } = await this.emitWrite("bot:invocation:steps", {
+      invocationId,
+      instanceId,
+      claimToken,
+      steps: keyed,
+      ...statusText ? { statusText } : {}
+    });
+    if (ack) {
+      if (!ack.ok)
+        this.logFn(`steps rejected (${ack.code ?? "?"}): ${ack.message ?? ""}`);
+      return;
+    }
+    if (sent) {
+      this.logFn("steps ack timed out; relying on the in-flight frame (no HTTP retry)");
+      return;
+    }
+    await this.httpRecordStepsFallback(invocationId, claimToken, keyed, statusText, instanceId);
+  }
+  async recordSealedSteps(invocationId, callbackToken, steps) {
+    if (steps.length === 0)
+      return;
+    const { sent, ack } = await this.emitWrite("bot:invocation:sealed-steps", {
+      invocationId,
+      callbackToken,
+      steps
+    });
+    if (ack) {
+      if (!ack.ok)
+        this.logFn(`sealed steps rejected (${ack.code ?? "?"}): ${ack.message ?? ""}`);
+      return;
+    }
+    if (sent) {
+      this.logFn("sealed steps ack timed out; relying on the in-flight frame (no HTTP retry)");
+      return;
+    }
+    await this.httpRecordSealedStepsFallback(invocationId, callbackToken, steps);
+  }
+  async renewClaim(invocationId, claimToken, claimTtlSeconds, instanceId = this.hello.instanceId) {
+    const { ack } = await this.emitWrite("bot:invocation:renew", {
+      invocationId,
+      instanceId,
+      claimToken,
+      claimTtlSeconds
+    });
+    if (ack) {
+      if (ack.ok)
+        return { notFound: false, renewed: true };
+      if (ack.code === "NOT_FOUND")
+        return { notFound: true, renewed: false };
+      this.logFn(`renew rejected (${ack.code ?? "?"}); retrying over HTTP`);
+    }
+    return this.httpRenewFallback(invocationId, claimToken, claimTtlSeconds, instanceId);
+  }
+  async updatePresence(body) {
+    const { ack } = await this.emitWrite("bot:presence:update", body);
+    if (ack) {
+      if (!ack.ok)
+        this.logFn(`presence rejected (${ack.code ?? "?"}): ${ack.message ?? ""}`);
+      return;
+    }
+    await this.httpPresenceFallback(body);
+  }
+  emitWrite(event, payload, signal, timeoutMs = this.wsAckTimeoutMs) {
+    const socket = this.socket;
+    if (signal?.aborted)
+      return Promise.resolve({ sent: false, ack: null, aborted: true });
+    if (!socket || !this.connected || !this.helloReady)
+      return Promise.resolve({ sent: false, ack: null });
+    return new Promise((resolve) => {
+      let settled = false;
+      const onAbort = () => done({ sent: true, ack: null, aborted: true });
+      const done = (result) => {
+        if (settled)
+          return;
+        settled = true;
+        signal?.removeEventListener("abort", onAbort);
+        resolve(result);
+      };
+      signal?.addEventListener("abort", onAbort, { once: true });
+      try {
+        socket.timeout(timeoutMs).emit(event, payload, (err, ack) => {
+          done({ sent: true, ack: err ? null : normalizeAck(ack) });
+        });
+      } catch (error) {
+        this.logFn(`socket emit ${event} threw: ${summarize(error)}`);
+        done({ sent: false, ack: null });
+      }
+    });
+  }
+  async resolveWsHint() {
+    const controller = new AbortController;
+    const timeout = setTimeout(() => controller.abort(), this.fetchTimeoutMs);
+    try {
+      const res = await fetch(`${this.base}/api/workspaces/${this.workspaceId}/config`, {
+        method: "GET",
+        signal: controller.signal,
+        headers: { Authorization: `Bearer ${this.apiKey}`, "Content-Type": "application/json" }
+      });
+      if (!res.ok)
+        return;
+      const body = await res.json();
+      return parseWsHint({ url: body.wsUrl });
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+  async httpRecordStepsFallback(invocationId, claimToken, steps, statusText, instanceId) {
+    for (const step of steps) {
+      try {
+        await this.httpRequest(this.v1Path(`/bot-invocations/${invocationId}/steps`), {
+          method: "POST",
+          body: JSON.stringify({
+            instanceId,
+            claimToken,
+            stepType: step.stepType,
+            content: step.content,
+            ...step.clientStepId ? { clientStepId: step.clientStepId } : {},
+            ...step.phase ? { phase: step.phase } : {},
+            ...step.durationMs !== undefined ? { durationMs: step.durationMs } : {},
+            ...statusText ? { statusText } : {}
+          })
+        });
+      } catch (error) {
+        this.logFn(`step HTTP fallback failed: ${summarize(error)}`);
+      }
+    }
+  }
+  async httpRecordSealedStepsFallback(invocationId, callbackToken, steps) {
+    for (const step of steps) {
+      try {
+        await this.httpRequest(this.v1Path(`/bot-invocations/${invocationId}/sealed-steps`), {
+          method: "POST",
+          headers: { [THREA_CALLBACK_TOKEN_HEADER]: callbackToken },
+          body: JSON.stringify(step)
+        });
+      } catch (error) {
+        this.logFn(`sealed step HTTP fallback failed: ${summarize(error)}`);
+      }
+    }
+  }
+  async httpRenewFallback(invocationId, claimToken, claimTtlSeconds, instanceId) {
+    try {
+      const res = await this.httpRequest(this.v1Path(`/bot-invocations/${invocationId}/renew`), {
+        method: "POST",
+        body: JSON.stringify({ instanceId, claimToken, claimTtlSeconds })
+      });
+      if (res.status === 404)
+        return { notFound: true, renewed: false };
+      if (!res.ok)
+        this.logFn(`renew HTTP fallback ${res.status}`);
+      return { notFound: false, renewed: res.ok };
+    } catch (error) {
+      this.logFn(`renew HTTP fallback failed: ${summarize(error)}`);
+      return { notFound: false, renewed: false };
+    }
+  }
+  async syncObservedClaim(request) {
+    const payload = {
+      invocationId: request.invocationId,
+      instanceId: request.instanceId ?? this.hello.instanceId,
+      claimToken: request.claimToken,
+      claimTtlSeconds: request.claimTtlSeconds,
+      knownSourceRevision: request.knownSourceRevision,
+      ...request.restartRequiredRevision === undefined ? {} : { restartRequiredRevision: request.restartRequiredRevision }
+    };
+    const ws = await this.emitWrite("bot:invocation:renew", payload, request.signal, Math.min(this.wsAckTimeoutMs, request.ackTimeoutMs));
+    if (request.signal.aborted || ws.aborted)
+      return { kind: "aborted" };
+    if (ws.ack?.ok) {
+      const parsed = parseControlState(ws.ack.data, request.invocationId, request.minimumSourceRevision);
+      if (parsed)
+        return { kind: "control", state: parsed };
+      this.logFn(`control state rejected over WS (${request.invocationId}); retrying over HTTP`);
+    } else if (ws.ack?.code === "NOT_FOUND") {
+      return { kind: "not_found" };
+    } else if (ws.ack) {
+      this.logFn(`control renew rejected over WS (${ws.ack.code ?? "?"}); retrying over HTTP`);
+    }
+    if (request.signal.aborted)
+      return { kind: "aborted" };
+    try {
+      const res = await this.httpRequest(this.v1Path(`/bot-invocations/${request.invocationId}/renew`), {
+        method: "POST",
+        body: JSON.stringify({
+          instanceId: payload.instanceId,
+          claimToken: payload.claimToken,
+          claimTtlSeconds: payload.claimTtlSeconds,
+          knownSourceRevision: request.knownSourceRevision,
+          ...request.restartRequiredRevision === undefined ? {} : { restartRequiredRevision: request.restartRequiredRevision }
+        })
+      }, request.signal);
+      if (request.signal.aborted)
+        return { kind: "aborted" };
+      if (res.status === 404)
+        return { kind: "not_found" };
+      if (!res.ok)
+        return { kind: "retry" };
+      const body = await res.json();
+      const parsed = isObject(body) ? parseControlState(body.data, request.invocationId, request.minimumSourceRevision) : undefined;
+      return parsed ? { kind: "control", state: parsed } : { kind: "retry" };
+    } catch {
+      return request.signal.aborted ? { kind: "aborted" } : { kind: "retry" };
+    }
+  }
+  async httpPresenceFallback(body) {
+    try {
+      await this.httpRequest(this.v1Path("/bot-runtime/presence"), { method: "POST", body: JSON.stringify(body) });
+    } catch (error) {
+      this.logFn(`presence HTTP fallback failed: ${summarize(error)}`);
+    }
+  }
+  v1Path(suffix) {
+    return `/api/v1/workspaces/${this.workspaceId}${suffix}`;
+  }
+  async httpRequest(path, init, callerSignal) {
+    const controller = new AbortController;
+    const onCallerAbort = () => controller.abort();
+    callerSignal?.addEventListener("abort", onCallerAbort, { once: true });
+    if (callerSignal?.aborted)
+      controller.abort();
+    const timeout = setTimeout(() => controller.abort(), this.fetchTimeoutMs);
+    try {
+      return await fetch(`${this.base}${path}`, {
+        ...init,
+        signal: controller.signal,
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          "Content-Type": "application/json",
+          ...init.headers
+        }
+      });
+    } finally {
+      clearTimeout(timeout);
+      callerSignal?.removeEventListener("abort", onCallerAbort);
+    }
+  }
+}
+function parseControlState(value, expectedInvocationId, minimumSourceRevision) {
+  if (!isObject(value) || value.invocationId !== expectedInvocationId)
+    return;
+  const sourceRevision = parseRevision(value.sourceRevision);
+  if (sourceRevision === undefined)
+    return;
+  if (value.status === "active" && typeof value.claimExpiresAt === "string") {
+    if (!Number.isFinite(Date.parse(value.claimExpiresAt)))
+      return;
+    if (value.update !== undefined) {
+      if (!isObject(value.update) || parseRevision(value.update.sourceRevision) !== sourceRevision)
+        return;
+    }
+    return {
+      invocationId: expectedInvocationId,
+      status: "active",
+      claimExpiresAt: value.claimExpiresAt,
+      sourceRevision,
+      ...value.update === undefined ? {} : { update: value.update }
+    };
+  }
+  const reason = parseCancellationReason(value.reason);
+  if (value.status === "cancelled" && value.claimExpiresAt === null && sourceRevision >= minimumSourceRevision && reason) {
+    return { invocationId: expectedInvocationId, status: "cancelled", claimExpiresAt: null, sourceRevision, reason };
+  }
+  return;
+}
+function normalizeAck(ack) {
+  if (!isObject(ack) || typeof ack.ok !== "boolean")
+    return null;
+  return {
+    ok: ack.ok,
+    data: isObject(ack.data) ? ack.data : undefined,
+    code: typeof ack.code === "string" ? ack.code : undefined,
+    message: typeof ack.message === "string" ? ack.message : undefined
+  };
+}
+function summarize(error) {
+  return (error instanceof Error ? error.message : String(error)).slice(0, 200);
+}
+// src/archive-grace.ts
+var ARCHIVE_RESTORE_GRACE_MS = 5 * 60 * 1000;
+var ARCHIVE_RESTORE_PROBE_MS = 45000;
+var WS_BACKSTOP_POLL_MS = 15 * 60 * 1000;
+
+class ArchiveGraceController {
+  hooks;
+  pending;
+  probing = false;
+  stopped = false;
+  transitions = 0;
+  graceMs;
+  constructor(hooks, options = {}) {
+    this.hooks = hooks;
+    this.graceMs = options.graceMs ?? ARCHIVE_RESTORE_GRACE_MS;
+  }
+  get detached() {
+    return this.pending !== undefined;
+  }
+  get pendingRootStreamId() {
+    return this.pending?.rootStreamId;
+  }
+  get generation() {
+    return this.transitions;
+  }
+  get probeDelayMs() {
+    return Math.min(ARCHIVE_RESTORE_PROBE_MS, Math.max(Math.floor(this.graceMs / 4), 10));
+  }
+  async archived(rootStreamId) {
+    if (this.stopped || this.pending)
+      return;
+    const pending = {
+      rootStreamId,
+      deadline: setTimeout(() => void this.windDown(pending), this.graceMs)
+    };
+    this.pending = pending;
+    this.transitions += 1;
+    this.hooks.log(`scratchpad ${rootStreamId} archived — detaching (reattaches if unarchived within ${Math.round(this.graceMs / 1000)}s)`);
+    await this.hooks.onDetached(rootStreamId, this.graceMs);
+  }
+  async restored() {
+    const pending = this.pending;
+    if (this.stopped || !pending)
+      return;
+    clearTimeout(pending.deadline);
+    pending.deadline = setTimeout(() => void this.windDown(pending), this.graceMs);
+    await this.attemptReattach(pending);
+  }
+  async probe(currentRootStreamId) {
+    if (this.stopped || this.probing)
+      return;
+    this.probing = true;
+    try {
+      const pending = this.pending;
+      if (pending) {
+        await this.attemptReattach(pending);
+        return;
+      }
+      if (!currentRootStreamId)
+        return;
+      const archived = await this.hooks.isArchived(currentRootStreamId);
+      if (archived !== true)
+        return;
+      if (this.stopped || this.pending)
+        return;
+      this.hooks.log(`archive backstop: ${currentRootStreamId} is archived with no push received`);
+      await this.archived(currentRootStreamId);
+    } catch (error) {
+      this.hooks.log(`archive probe failed: ${describe(error)}`);
+    } finally {
+      this.probing = false;
+    }
+  }
+  stop() {
+    this.stopped = true;
+    if (this.pending)
+      clearTimeout(this.pending.deadline);
+    this.pending = undefined;
+  }
+  async attemptReattach(pending) {
+    let reattached = false;
+    try {
+      reattached = await this.hooks.reattach(pending.rootStreamId);
+    } catch (error) {
+      this.hooks.log(`reattach failed, staying detached: ${describe(error)}`);
+      return;
+    }
+    if (!reattached || this.stopped || this.pending !== pending)
+      return;
+    clearTimeout(pending.deadline);
+    this.pending = undefined;
+    this.transitions += 1;
+    this.hooks.log(`scratchpad ${pending.rootStreamId} restored — reattached`);
+    await this.hooks.onReattached(pending.rootStreamId);
+  }
+  async windDown(pending) {
+    if (this.stopped || this.pending !== pending)
+      return;
+    clearTimeout(pending.deadline);
+    this.pending = undefined;
+    this.transitions += 1;
+    this.hooks.log(`scratchpad ${pending.rootStreamId} stayed archived — winding down`);
+    try {
+      await this.hooks.onWindDown(pending.rootStreamId);
+    } catch (error) {
+      this.hooks.log(`wind-down failed: ${describe(error)}`);
+    }
+  }
+}
+function describe(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+// src/attachment-files.ts
+import { join } from "node:path";
+var UNSAFE_SEGMENT_CHARS = /[\\/:*?"<>|]/g;
+var MAX_SEGMENT_BYTES = 180;
+var MAX_EXTENSION_BYTES = 16;
+var encoder = new TextEncoder;
+function byteLength(value) {
+  return encoder.encode(value).length;
+}
+function truncateToBytes(value, maxBytes) {
+  if (byteLength(value) <= maxBytes)
+    return value;
+  let out = "";
+  let bytes = 0;
+  for (const char of value) {
+    const size = byteLength(char);
+    if (bytes + size > maxBytes)
+      break;
+    out += char;
+    bytes += size;
+  }
+  return out;
+}
+function clean(value) {
+  return value.replace(UNSAFE_SEGMENT_CHARS, "_").replace(/^\.+$/, "_");
+}
+function safeSegment(value, fallback) {
+  return truncateToBytes(clean(value), MAX_SEGMENT_BYTES) || fallback;
+}
+function safeAttachmentFilename(filename) {
+  const cleaned = clean(filename);
+  const dot = cleaned.lastIndexOf(".");
+  const extension = dot > 0 ? cleaned.slice(dot) : "";
+  if (!extension || byteLength(extension) > MAX_EXTENSION_BYTES) {
+    return truncateToBytes(cleaned, MAX_SEGMENT_BYTES) || "attachment";
+  }
+  const stem = truncateToBytes(cleaned.slice(0, dot), MAX_SEGMENT_BYTES - byteLength(extension));
+  return `${stem}${extension}`;
+}
+function attachmentLocalPath(dir, attachmentId, filename) {
+  return join(dir, safeSegment(attachmentId, "attachment"), safeAttachmentFilename(filename));
+}
+// src/sealed-stream-client.ts
+import { ulid as ulid2 } from "ulid";
+function keyringKeySource(keyring) {
+  const imported = new Map;
+  return {
+    async keysForStream(streamId) {
+      await keyring.ensureForStream(streamId);
+      const held = keyring.forStream(streamId);
+      if (!held)
+        return [];
+      let privateKey = imported.get(held.keyId);
+      if (!privateKey) {
+        privateKey = importRecipientPrivateKey(base64ToBytes(held.privateKey));
+        imported.set(held.keyId, privateKey);
+      }
+      return [{ keyId: held.keyId, privateKey: await privateKey }];
+    }
+  };
+}
+
+class SealedStreamApiError extends Error {
+  status;
+  code;
+  constructor(message, status, code) {
+    super(message);
+    this.name = "SealedStreamApiError";
+    this.status = status;
+    this.code = code;
+  }
+}
+function reasonOf(error) {
+  return String(error instanceof Error ? error.message : error);
+}
+
+class SealedStreamClient {
+  opts;
+  doFetch;
+  roots = new Map;
+  ssks = new Map;
+  generations = new Map;
+  sender;
+  constructor(opts) {
+    this.opts = opts;
+    this.doFetch = opts.fetch ?? globalThis.fetch;
+  }
+  async readMessages(streamId, opts = {}) {
+    const root = await this.resolveRoot(streamId);
+    const query = new URLSearchParams;
+    if (opts.limit !== undefined)
+      query.set("limit", String(opts.limit));
+    if (opts.before)
+      query.set("before", opts.before);
+    if (opts.after)
+      query.set("after", opts.after);
+    const suffix = query.size > 0 ? `?${query.toString()}` : "";
+    const page = await this.request("GET", `/streams/${streamId}/messages${suffix}`);
+    const messages = [];
+    for (const wire of page.data) {
+      messages.push(await this.openMessage(root, wire));
+    }
+    return { messages, hasMore: page.hasMore };
+  }
+  async sendMessage(streamId, contentMarkdown, opts = {}) {
+    const root = await this.resolveRoot(streamId);
+    const keyGeneration = await this.currentGeneration(root);
+    const key = await this.streamKey(root, keyGeneration);
+    const senderId = await this.resolveSenderId();
+    const clientMessageId = opts.clientMessageId ?? `msg_${ulid2()}`;
+    const sealed = await sealMessage({
+      key,
+      keyGeneration,
+      payload: serializeSealedPayload(contentMarkdown, { attachmentRefs: opts.attachmentRefs }),
+      aad: buildMessageAad({ streamId: root, messageId: clientMessageId, senderId })
+    });
+    const created = await this.request("POST", `/streams/${streamId}/messages`, {
+      sealed: { ciphertext: bytesToBase64(sealed.ciphertext), envelope: sealed.envelope },
+      clientMessageId
+    });
+    return { messageId: created.data.id, clientMessageId };
+  }
+  async openSealedBody(streamId, sealed) {
+    const root = await this.resolveRoot(streamId);
+    return this.openBody(root, sealed);
+  }
+  async openBody(root, sealed) {
+    let key;
+    try {
+      key = await this.streamKey(root, sealed.envelope.keyGeneration);
+    } catch (error) {
+      return { contentMarkdown: null, attachmentRefs: [], unreadableReason: reasonOf(error) };
+    }
+    try {
+      const raw = await openMessageAsString({
+        key,
+        ciphertext: base64ToBytes(sealed.ciphertext),
+        envelope: sealed.envelope
+      });
+      const payload = parseSealedPayload(raw);
+      return { contentMarkdown: payload.contentMarkdown, attachmentRefs: payload.attachmentRefs ?? [] };
+    } catch (error) {
+      return { contentMarkdown: null, attachmentRefs: [], unreadableReason: reasonOf(error) };
+    }
+  }
+  async openMessage(root, wire) {
+    const base = {
+      id: wire.id,
+      sequence: wire.sequence,
+      authorId: wire.authorId,
+      authorType: wire.authorType,
+      ...wire.authorDisplayName ? { authorDisplayName: wire.authorDisplayName } : {},
+      createdAt: wire.createdAt,
+      attachmentRefs: []
+    };
+    if (!wire.sealed) {
+      return { ...base, contentMarkdown: null, unreadableReason: "Message carries no stream-key envelope" };
+    }
+    return { ...base, ...await this.openBody(root, wire.sealed) };
+  }
+  async streamKey(root, keyGeneration) {
+    const cached = this.ssks.get(`${root}:${keyGeneration}`);
+    if (cached)
+      return cached;
+    await this.loadWraps(root);
+    const key = this.ssks.get(`${root}:${keyGeneration}`);
+    if (!key) {
+      throw new Error(`No key wrap for generation ${keyGeneration} of ${root} is addressed to a key this client holds`);
+    }
+    return key;
+  }
+  async currentGeneration(root) {
+    await this.loadWraps(root);
+    return this.generations.get(root) ?? 0;
+  }
+  async loadWraps(root) {
+    const identities = await this.opts.keys.keysForStream(root);
+    if (identities.length === 0) {
+      throw new Error(`No end-to-end key available for ${root}`);
+    }
+    const wraps = await this.request("GET", `/streams/${root}/e2e/key-wraps`);
+    this.generations.set(root, wraps.data.currentKeyGeneration);
+    for (const wrap of wraps.data.wraps) {
+      const identity = identities.find((candidate) => candidate.keyId === wrap.recipientKeyId);
+      if (!identity)
+        continue;
+      if (this.ssks.has(`${root}:${wrap.keyGeneration}`))
+        continue;
+      const key = await unwrapStreamKey({
+        enc: base64ToBytes(wrap.wrapEnc),
+        ct: base64ToBytes(wrap.wrapCt),
+        recipientPrivateKey: identity.privateKey,
+        aad: buildWrapAad({
+          streamId: root,
+          keyGeneration: wrap.keyGeneration,
+          recipientKeyId: wrap.recipientKeyId
+        })
+      });
+      this.ssks.set(`${root}:${wrap.keyGeneration}`, key);
+    }
+  }
+  async resolveRoot(streamId) {
+    let pending = this.roots.get(streamId);
+    if (!pending) {
+      pending = this.request("GET", `/streams/${streamId}`).then((stream) => stream.data.rootStreamId ?? stream.data.id).catch((error) => {
+        this.roots.delete(streamId);
+        throw error;
+      });
+      this.roots.set(streamId, pending);
+    }
+    return pending;
+  }
+  async resolveSenderId() {
+    if (this.opts.senderId)
+      return this.opts.senderId;
+    if (!this.sender) {
+      this.sender = this.request("GET", "/me").then((me) => {
+        const id = me.data.kind === "bot" ? me.data.botId : me.data.userId;
+        if (!id)
+          throw new Error("GET /me named no principal id");
+        return id;
+      }).catch((error) => {
+        this.sender = undefined;
+        throw error;
+      });
+    }
+    return this.sender;
+  }
+  async request(method, path, body) {
+    const url = `${this.opts.baseUrl.replace(/\/$/, "")}/api/v1/workspaces/${this.opts.workspaceId}${path}`;
+    const response = await this.doFetch(url, {
+      method,
+      headers: {
+        Authorization: `Bearer ${this.opts.apiKey}`,
+        ...body === undefined ? {} : { "Content-Type": "application/json" }
+      },
+      ...body === undefined ? {} : { body: JSON.stringify(body) }
+    });
+    const text = await response.text();
+    if (!response.ok) {
+      let parsed = {};
+      try {
+        if (text.length > 0)
+          parsed = JSON.parse(text);
+      } catch {
+        parsed = {};
+      }
+      throw new SealedStreamApiError(typeof parsed.message === "string" ? parsed.message : `${method} ${path} failed`, response.status, typeof parsed.code === "string" ? parsed.code : "UNKNOWN");
+    }
+    return text.length > 0 ? JSON.parse(text) : {};
+  }
+}
+// src/keyring.ts
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join as join2 } from "node:path";
+var E2E_KEY_SCOPES = ["host", "identity", "instance", "stream"];
+var E2E_KEY_STORE_KINDS = ["keychain", "file"];
+function hash16(value) {
+  return createHash("sha256").update(value).digest("hex").slice(0, 16);
+}
+function e2eKeyAccount(params) {
+  switch (params.scope) {
+    case "identity":
+      return `identity-${hash16(params.identitySeed)}`;
+    case "instance":
+      return `instance-${params.instanceId.replace(/[^A-Za-z0-9_-]+/g, "-")}`.slice(0, 96);
+    case "host":
+      return `host-${hash16(params.hostname)}`;
+    case "stream":
+      return null;
+  }
+}
+function e2eStreamKeyAccount(streamId) {
+  return `stream-${hash16(streamId)}`;
+}
+function e2eUserKeyAccount(workspaceId, userId) {
+  return `user-${hash16(`${workspaceId}:${userId}`)}`;
+}
+function decodeRecord(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.keyId === "string" && typeof parsed.publicKey === "string" && typeof parsed.privateKey === "string") {
+      return { keyId: parsed.keyId, publicKey: parsed.publicKey, privateKey: parsed.privateKey };
+    }
+  } catch {}
+  return;
+}
+
+class FileKeyStore {
+  kind = "file";
+  describe;
+  dir;
+  constructor(opts) {
+    this.dir = opts.dir;
+    this.describe = opts.dir;
+  }
+  path(account) {
+    return join2(this.dir, `${account}.json`);
+  }
+  read(account) {
+    const path = this.path(account);
+    if (!existsSync(path))
+      return;
+    return decodeRecord(readFileSync(path, "utf8"));
+  }
+  hasAny() {
+    if (!existsSync(this.dir))
+      return false;
+    return readdirSync(this.dir).some((entry) => entry.endsWith(".json"));
+  }
+  createExclusive(account, record) {
+    const path = this.path(account);
+    mkdirSync(dirname(path), { recursive: true });
+    try {
+      writeFileSync(path, `${JSON.stringify(record, null, 2)}
+`, { mode: 384, flag: "wx" });
+      return record;
+    } catch (error) {
+      if (error.code !== "EEXIST")
+        throw error;
+      const winner = this.read(account);
+      if (!winner)
+        throw new Error(`${path} exists but could not be read`);
+      return winner;
+    }
+  }
+  write(account, record) {
+    const path = this.path(account);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(record, null, 2)}
+`, { mode: 384 });
+  }
+  remove(account) {
+    rmSync(this.path(account), { force: true });
+  }
+}
+var KEYCHAIN_COMMAND_TIMEOUT_MS = 5000;
+function runKeychainCommand(command, args, input, timeoutMs = KEYCHAIN_COMMAND_TIMEOUT_MS) {
+  const result = spawnSync(command, args, { encoding: "utf8", input, timeout: timeoutMs });
+  if (result.error?.code === "ETIMEDOUT") {
+    return {
+      status: -1,
+      stdout: "",
+      stderr: `${command} gave no answer within ${timeoutMs}ms; the keyring is probably locked and waiting on a password prompt`,
+      unavailable: true
+    };
+  }
+  if (result.error) {
+    return { status: -1, stdout: "", stderr: String(result.error), unavailable: true };
+  }
+  return { status: result.status ?? -1, stdout: result.stdout ?? "", stderr: result.stderr ?? "", unavailable: false };
+}
+function encodeSecret(record) {
+  return Buffer.from(JSON.stringify(record), "utf8").toString("base64");
+}
+function decodeSecret(raw) {
+  const trimmed = raw.trim();
+  if (!trimmed)
+    return;
+  return decodeRecord(Buffer.from(trimmed, "base64").toString("utf8"));
+}
+var KEYCHAIN_SERVICE = "threa-e2e";
+var sameRecord = (a, b) => a.keyId === b.keyId && a.publicKey === b.publicKey && a.privateKey === b.privateKey;
+
+class MacKeychainStore {
+  kind = "keychain";
+  describe = `macOS keychain (service ${KEYCHAIN_SERVICE})`;
+  exec;
+  constructor(opts = {}) {
+    this.exec = opts.exec ?? runKeychainCommand;
+  }
+  read(account) {
+    const result = this.exec("/usr/bin/security", [
+      "find-generic-password",
+      "-s",
+      KEYCHAIN_SERVICE,
+      "-a",
+      account,
+      "-w"
+    ]);
+    if (result.unavailable)
+      throw new Error(`macOS keychain unavailable: ${result.stderr}`);
+    if (result.status !== 0)
+      return;
+    return decodeSecret(result.stdout);
+  }
+  createExclusive(account, record) {
+    const result = this.exec("/usr/bin/security", ["-i"], `add-generic-password -s ${KEYCHAIN_SERVICE} -a ${account} -w ${encodeSecret(record)}
+`);
+    if (result.unavailable)
+      throw new Error(`macOS keychain unavailable: ${result.stderr}`);
+    const stored = this.read(account);
+    if (!stored)
+      throw new Error(`macOS keychain accepted no key for ${account}: ${result.stderr || result.stdout}`);
+    return stored;
+  }
+  write(account, record) {
+    const result = this.exec("/usr/bin/security", ["-i"], `add-generic-password -U -s ${KEYCHAIN_SERVICE} -a ${account} -w ${encodeSecret(record)}
+`);
+    if (result.unavailable)
+      throw new Error(`macOS keychain unavailable: ${result.stderr}`);
+    if (result.status !== 0) {
+      throw new Error(`macOS keychain rejected the key for ${account}: ${result.stderr || result.stdout}`);
+    }
+    const stored = this.read(account);
+    if (!stored || !sameRecord(stored, record)) {
+      throw new Error(`macOS keychain did not store the key for ${account}: ${result.stderr || result.stdout}`);
+    }
+  }
+  remove(account) {
+    const result = this.exec("/usr/bin/security", ["delete-generic-password", "-s", KEYCHAIN_SERVICE, "-a", account]);
+    if (result.unavailable)
+      throw new Error(`macOS keychain unavailable: ${result.stderr}`);
+    if (this.read(account))
+      throw new Error(`macOS keychain kept the key for ${account}: ${result.stderr}`);
+  }
+}
+
+class SecretServiceStore {
+  kind = "keychain";
+  describe = `Secret Service keyring (service ${KEYCHAIN_SERVICE})`;
+  exec;
+  constructor(opts = {}) {
+    this.exec = opts.exec ?? runKeychainCommand;
+  }
+  read(account) {
+    const result = this.exec("secret-tool", ["lookup", "service", KEYCHAIN_SERVICE, "account", account]);
+    if (result.unavailable)
+      throw new Error(`Secret Service unavailable: ${result.stderr}`);
+    if (result.status !== 0)
+      return;
+    return decodeSecret(result.stdout);
+  }
+  createExclusive(account, record) {
+    const existing = this.read(account);
+    if (existing)
+      return existing;
+    const result = this.exec("secret-tool", ["store", "--label", `Threa E2E key ${account}`, "service", KEYCHAIN_SERVICE, "account", account], encodeSecret(record));
+    if (result.unavailable)
+      throw new Error(`Secret Service unavailable: ${result.stderr}`);
+    const stored = this.read(account);
+    if (!stored)
+      throw new Error(`Secret Service stored no key for ${account}: ${result.stderr || result.stdout}`);
+    return stored;
+  }
+  write(account, record) {
+    const result = this.exec("secret-tool", ["store", "--label", `Threa E2E key ${account}`, "service", KEYCHAIN_SERVICE, "account", account], encodeSecret(record));
+    if (result.unavailable)
+      throw new Error(`Secret Service unavailable: ${result.stderr}`);
+    if (result.status !== 0) {
+      throw new Error(`Secret Service rejected the key for ${account}: ${result.stderr || result.stdout}`);
+    }
+    const stored = this.read(account);
+    if (!stored || !sameRecord(stored, record)) {
+      throw new Error(`Secret Service did not store the key for ${account}: ${result.stderr || result.stdout}`);
+    }
+  }
+  remove(account) {
+    const result = this.exec("secret-tool", ["clear", "service", KEYCHAIN_SERVICE, "account", account]);
+    if (result.unavailable)
+      throw new Error(`Secret Service unavailable: ${result.stderr}`);
+    if (this.read(account))
+      throw new Error(`Secret Service kept the key for ${account}: ${result.stderr}`);
+  }
+}
+function resolveKeyStore(input) {
+  const keychain = () => input.platform === "darwin" ? new MacKeychainStore({ exec: input.exec }) : new SecretServiceStore({ exec: input.exec });
+  if (input.requested === "file")
+    return new FileKeyStore({ dir: input.dir });
+  if (input.requested === "keychain") {
+    const store2 = keychain();
+    store2.read("threa-probe");
+    return store2;
+  }
+  if (input.hasExistingFileKey)
+    return new FileKeyStore({ dir: input.dir });
+  const store = keychain();
+  try {
+    store.read("threa-probe");
+    return store;
+  } catch (error) {
+    throw new Error(`No OS keychain available for Threa's end-to-end keys (${String(error)}). ` + `Set keyStore to "keychain" once one is installed and unlocked, or "file" to keep them in ${input.dir} at mode 0600.`);
+  }
+}
+
+class E2eKeyring {
+  opts;
+  log;
+  held = [];
+  inFlight = new Map;
+  loaded = false;
+  constructor(opts) {
+    this.opts = opts;
+    this.log = opts.log ?? ((message) => console.error(message));
+  }
+  get current() {
+    return this.held;
+  }
+  async ensure() {
+    if (this.loaded)
+      return this.held;
+    const account = this.opts.account;
+    if (account === null) {
+      this.loaded = true;
+      return this.held;
+    }
+    await this.loadAccount(account, undefined);
+    this.loaded = this.held.length > 0;
+    return this.held;
+  }
+  async ensureForStream(streamId) {
+    if (this.opts.account !== null)
+      return this.ensure();
+    return this.loadAccount(e2eStreamKeyAccount(streamId), streamId);
+  }
+  dropStream(streamId) {
+    const held = this.held.find((key) => key.streamId === streamId);
+    if (!held)
+      return this.held;
+    this.held = this.held.filter((key) => key !== held);
+    this.opts.store.remove(held.account);
+    this.log(`Threa sealed: dropped ${held.keyId}, the key for revoked stream ${streamId}`);
+    return this.held;
+  }
+  forStream(streamId) {
+    if (this.opts.account !== null)
+      return this.held.find((key) => !key.streamId);
+    return this.held.find((key) => key.streamId === streamId);
+  }
+  presenceFields() {
+    if (this.held.length === 0)
+      return {};
+    const e2eKeys = this.held.map((key) => ({
+      keyId: key.keyId,
+      publicKey: key.publicKey,
+      ...key.streamId ? { streamId: key.streamId } : {}
+    }));
+    const unscoped = this.held.find((key) => !key.streamId);
+    return unscoped ? { e2eKeys, publicKey: unscoped.publicKey, publicKeyId: unscoped.keyId } : { e2eKeys };
+  }
+  async loadAccount(account, streamId) {
+    const existing = this.held.find((key) => key.account === account);
+    if (existing)
+      return this.held;
+    let attempt = this.inFlight.get(account);
+    if (!attempt) {
+      attempt = this.mintAccount(account, streamId).finally(() => this.inFlight.delete(account));
+      this.inFlight.set(account, attempt);
+    }
+    return attempt;
+  }
+  async mintAccount(account, streamId) {
+    const record = this.opts.store.read(account) ?? await this.createRecord(account);
+    if (!this.held.some((key) => key.account === account)) {
+      this.held = [...this.held, { ...record, account, ...streamId ? { streamId } : {} }];
+    }
+    return this.held;
+  }
+  async createRecord(account) {
+    const legacy = account === this.opts.account ? this.opts.legacy?.() : undefined;
+    if (legacy) {
+      const adopted = this.opts.store.createExclusive(account, legacy);
+      this.log(`Threa sealed: adopted this install's existing key ${adopted.keyId} into ${this.opts.store.describe} as ${account}`);
+      return adopted;
+    }
+    const minted = this.opts.store.createExclusive(account, await this.opts.mint());
+    this.log(`Threa sealed: end-to-end key ${minted.keyId} is in ${this.opts.store.describe} as ${account}`);
+    return minted;
+  }
+}
+function readLegacyBikFile(path) {
+  if (!existsSync(path))
+    return;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (typeof parsed.publicKeyId === "string" && typeof parsed.publicKey === "string" && typeof parsed.privateKey === "string") {
+      return { keyId: parsed.publicKeyId, publicKey: parsed.publicKey, privateKey: parsed.privateKey };
+    }
+  } catch {}
+  return;
+}
+// src/user-key.ts
+import { argon2id } from "hash-wasm";
+var DEFAULT_KDF_PARAMS = {
+  algorithm: "argon2id",
+  m: 64 * 1024,
+  t: 3,
+  p: 1,
+  version: 19
+};
+var KEK_LENGTH_BYTES = 32;
+var PRIVATE_BUNDLE_VERSION = 1;
+var IV_LENGTH2 = 12;
+var ARGON2_VERSION = 19;
+async function deriveKEK(passphrase, salt, params = DEFAULT_KDF_PARAMS) {
+  if (params.algorithm !== "argon2id") {
+    throw new Error(`Unsupported KDF algorithm: ${params.algorithm}`);
+  }
+  if (params.version !== ARGON2_VERSION) {
+    throw new Error(`Unsupported Argon2 version: ${params.version}`);
+  }
+  const raw = await argon2id({
+    password: passphrase,
+    salt,
+    iterations: params.t,
+    parallelism: params.p,
+    memorySize: params.m,
+    hashLength: KEK_LENGTH_BYTES,
+    outputType: "binary"
+  });
+  return crypto.subtle.importKey("raw", new Uint8Array(raw), { name: "AES-GCM" }, false, ["decrypt"]);
+}
+
+class WrongPassphraseError extends Error {
+  constructor() {
+    super("Wrapped private bundle did not open with this passphrase");
+    this.name = "WrongPassphraseError";
+  }
+}
+async function unwrapPrivate(bundle, kek) {
+  if (bundle.length < 1 + IV_LENGTH2 + 1) {
+    throw new Error("Wrapped private bundle is too short");
+  }
+  const version = bundle[0];
+  if (version !== PRIVATE_BUNDLE_VERSION) {
+    throw new Error(`Unsupported private bundle version: ${version}`);
+  }
+  const iv = bundle.slice(1, 1 + IV_LENGTH2);
+  const ciphertext = bundle.slice(1 + IV_LENGTH2);
+  const plaintext = await crypto.subtle.decrypt({ name: "AES-GCM", iv }, kek, ciphertext).catch(() => {
+    throw new WrongPassphraseError;
+  });
+  const privBytes = new Uint8Array(plaintext);
+  return importRecipientPrivateKey(privBytes);
+}
+async function unlockUserKey(input) {
+  const kek = await deriveKEK(input.passphrase, input.kdfSalt, input.kdfParams);
+  return unwrapPrivate(input.encryptedPrivateBundle, kek);
+}
+export {
+  unwrapPrivate,
+  unlockUserKey,
+  serializeSealedPayload,
+  sealStep,
+  sealReply,
+  sealMessage,
+  sealDecision,
+  scrubSealedError,
+  safeAttachmentFilename,
+  resolveKeyStore,
+  readLegacyBikFile,
+  parseWsHint,
+  parseSealedTurnContext,
+  parseSealedPayload,
+  parseSealedAckContext,
+  openSealedTurnContext,
+  openSealedDecisionNote,
+  openSealedAck,
+  openMessageAsString,
+  mintStreamKeyWraps,
+  mintE2eKeyRecord,
+  keyringKeySource,
+  isObject,
+  encryptAttachmentBytes,
+  e2eUserKeyAccount,
+  e2eStreamKeyAccount,
+  e2eKeyAccount,
+  deriveKEK,
+  decryptAttachmentBytes,
+  bytesToBase64,
+  buildWrapAad,
+  buildMessageAad,
+  buildDecisionNoteAad,
+  buildDecisionAad,
+  buildBotSocketUrl,
+  base64ToBytes,
+  attachmentLocalPath,
+  WrongPassphraseError,
+  WS_BACKSTOP_POLL_MS,
+  THREA_CALLBACK_TOKEN_HEADER,
+  SecretServiceStore,
+  SealedStreamClient,
+  SealedStreamApiError,
+  MacKeychainStore,
+  FileKeyStore,
+  E2eKeyring,
+  E2E_KEY_STORE_KINDS,
+  E2E_KEY_SCOPES,
+  DEFAULT_KDF_PARAMS,
+  BotRuntimeTransport,
+  BotKeyring,
+  ArchiveGraceController,
+  ARCHIVE_RESTORE_PROBE_MS,
+  ARCHIVE_RESTORE_GRACE_MS
+};
+
+//# debugId=A1F550552BD6E62464756E2164756E21
+//# sourceMappingURL=index.js.map