@astralform/js 0.2.3 → 1.1.0

package/dist/index.js

@@ -13,9 +13,10 @@ var AuthenticationError = class extends AstralformError {
   }
 };
 var RateLimitError = class extends AstralformError {
-  constructor(message = "Rate limit exceeded") {
+  constructor(message = "Rate limit exceeded", details = {}) {
     super(message, "rate_limit_error");
     this.name = "RateLimitError";
+    Object.assign(this, details);
   }
 };
 var LLMNotConfiguredError = class extends AstralformError {
@@ -43,6 +44,143 @@ var StreamAbortedError = class extends AstralformError {
   }
 };
 
+// src/utils.ts
+function sanitizeErrorText(text) {
+  return text.slice(0, 500).replace(/Bearer\s+\S+/gi, "Bearer [REDACTED]");
+}
+function generateId() {
+  if (typeof crypto !== "undefined" && crypto.randomUUID) {
+    return crypto.randomUUID();
+  }
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+    const r = Math.random() * 16 | 0;
+    const v = c === "x" ? r : r & 3 | 8;
+    return v.toString(16);
+  });
+}
+
+// src/rate-limit.ts
+var DEFAULT_MESSAGE = "Rate limit exceeded";
+function parseNumber(value) {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (!trimmed) {
+      return void 0;
+    }
+    const parsed = Number(trimmed);
+    if (Number.isFinite(parsed)) {
+      return parsed;
+    }
+  }
+  return void 0;
+}
+function parseString(value) {
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const trimmed = value.trim();
+  return trimmed ? trimmed : void 0;
+}
+function parseJsonObject(rawText) {
+  if (!rawText) {
+    return void 0;
+  }
+  try {
+    const parsed = JSON.parse(rawText);
+    if (parsed && typeof parsed === "object") {
+      return parsed;
+    }
+  } catch {
+  }
+  return void 0;
+}
+function parseRetryAfterHeader(value) {
+  if (!value) {
+    return void 0;
+  }
+  const numeric = parseNumber(value);
+  if (numeric !== void 0) {
+    return Math.max(0, Math.ceil(numeric));
+  }
+  const asDate = Date.parse(value);
+  if (Number.isFinite(asDate)) {
+    const diffMs = asDate - Date.now();
+    return Math.max(0, Math.ceil(diffMs / 1e3));
+  }
+  return void 0;
+}
+function parseResetTimestamp(value) {
+  const numeric = parseNumber(value);
+  if (numeric !== void 0) {
+    if (numeric > 1e12) {
+      return Math.floor(numeric);
+    }
+    return Math.floor(numeric * 1e3);
+  }
+  const asString = parseString(value);
+  if (!asString) {
+    return void 0;
+  }
+  const asDate = Date.parse(asString);
+  if (Number.isFinite(asDate)) {
+    return asDate;
+  }
+  return void 0;
+}
+function pickFirst(payload, keys, parser) {
+  for (const key of keys) {
+    const parsed = parser(payload[key]);
+    if (parsed !== void 0) {
+      return parsed;
+    }
+  }
+  return void 0;
+}
+function buildRateLimitDetails(payload, headers) {
+  const headerRetryAfter = headers ? parseRetryAfterHeader(headers.get("retry-after")) : void 0;
+  const bodyRetryAfter = pickFirst(
+    payload,
+    ["retry_after", "retryAfter", "retry_after_sec", "retryAfterSec"],
+    parseNumber
+  );
+  const retryAfterSec = bodyRetryAfter ?? headerRetryAfter;
+  const headerReset = headers ? parseResetTimestamp(
+    headers.get("x-ratelimit-reset") ?? headers.get("x-ratelimit-reset-at")
+  ) : void 0;
+  const bodyReset = parseResetTimestamp(
+    payload.reset_at ?? payload.resetAt ?? payload.reset
+  );
+  const resetAt = bodyReset ?? headerReset ?? (retryAfterSec !== void 0 ? Date.now() + retryAfterSec * 1e3 : void 0);
+  const limit = pickFirst(payload, ["limit", "rate_limit", "max"], parseNumber) ?? (headers ? parseNumber(headers.get("x-ratelimit-limit")) : void 0);
+  const remaining = pickFirst(payload, ["remaining", "rate_limit_remaining"], parseNumber) ?? (headers ? parseNumber(headers.get("x-ratelimit-remaining")) : void 0);
+  const scope = pickFirst(payload, ["scope", "limit_scope"], parseString) ?? (headers ? parseString(headers.get("x-ratelimit-scope")) : void 0);
+  const policyId = pickFirst(payload, ["policy_id", "policyId", "policy"], parseString) ?? (headers ? parseString(
+    headers.get("x-ratelimit-policy") ?? headers.get("x-ratelimit-policy-id")
+  ) : void 0);
+  const requestId = pickFirst(payload, ["request_id", "requestId"], parseString) ?? (headers ? parseString(
+    headers.get("x-request-id") ?? headers.get("x-correlation-id")
+  ) : void 0);
+  return {
+    retryAfterSec,
+    resetAt,
+    scope,
+    policyId,
+    limit,
+    remaining,
+    requestId
+  };
+}
+function createRateLimitErrorFromHttp(response, rawText) {
+  const payload = parseJsonObject(rawText) ?? {};
+  const details = buildRateLimitDetails(payload, response.headers);
+  const sanitizedText = sanitizeErrorText(rawText);
+  const message = pickFirst(payload, ["message", "error_description"], parseString) ?? (sanitizedText || DEFAULT_MESSAGE);
+  return new RateLimitError(message, details);
+}
+
 // src/streaming.ts
 async function* streamJobSSE(options) {
   const { url, headers, signal, fetchFn } = options;
@@ -63,12 +201,12 @@ async function* streamJobSSE(options) {
   }
   if (!response.ok) {
     const rawText = await response.text().catch(() => "");
-    const text = rawText ? rawText.slice(0, 500).replace(/Bearer\s+\S+/gi, "Bearer [REDACTED]") : "";
+    const text = rawText ? sanitizeErrorText(rawText) : "";
     switch (response.status) {
       case 401:
         throw new AuthenticationError();
       case 429:
-        throw new RateLimitError();
+        throw createRateLimitErrorFromHttp(response, rawText);
       default:
         throw new ServerError(text || `HTTP ${response.status}`);
     }
@@ -131,20 +269,126 @@ function validateBaseURL(url) {
     throw new Error(`Invalid baseURL: "${cleaned}" is not a valid URL`);
   }
 }
+function isApiKeyConfig(config) {
+  return "apiKey" in config;
+}
 var AstralformClient = class {
   constructor(config) {
-    if (!config.apiKey || typeof config.apiKey !== "string") {
-      throw new Error("apiKey is required and must be a non-empty string");
+    if (isApiKeyConfig(config)) {
+      if (!config.apiKey || typeof config.apiKey !== "string") {
+        throw new Error("apiKey is required and must be a non-empty string");
+      }
+      if (!config.userId || typeof config.userId !== "string") {
+        throw new Error("userId is required in API-key mode");
+      }
+      this.auth = {
+        kind: "api_key",
+        apiKey: config.apiKey,
+        userId: config.userId
+      };
+    } else {
+      if (!config.accessToken || typeof config.accessToken !== "string") {
+        throw new Error(
+          "accessToken is required and must be a non-empty string in user-token mode"
+        );
+      }
+      const projectId = typeof config.projectId === "string" && config.projectId.length > 0 ? config.projectId : null;
+      this.auth = {
+        kind: "user_token",
+        accessToken: config.accessToken,
+        projectId,
+        endUserId: typeof config.endUserId === "string" && config.endUserId.length > 0 ? config.endUserId : null
+      };
     }
-    this.apiKey = config.apiKey;
     this.baseURL = validateBaseURL(config.baseURL ?? DEFAULT_BASE_URL);
-    this.userId = config.userId;
     this.fetchFn = config.fetch ?? globalThis.fetch.bind(globalThis);
   }
+  /**
+   * Replace the current OIDC access token without reconstructing the client.
+   * Use after refreshing via the host's token manager (e.g., Supabase JS SDK).
+   * Throws if the client was created in API-key mode.
+   */
+  updateAccessToken(accessToken) {
+    if (this.auth.kind !== "user_token") {
+      throw new Error("updateAccessToken is only valid in user-token mode");
+    }
+    if (!accessToken || typeof accessToken !== "string") {
+      throw new Error("accessToken must be a non-empty string");
+    }
+    this.auth = { ...this.auth, accessToken };
+  }
+  /**
+   * Swap the active project for a user-token client. The backend verifies the
+   * current developer has access to the new project; a 403 comes back if not.
+   */
+  updateProjectId(projectId) {
+    if (this.auth.kind !== "user_token") {
+      throw new Error("updateProjectId is only valid in user-token mode");
+    }
+    if (!projectId || typeof projectId !== "string") {
+      throw new Error("projectId must be a non-empty string");
+    }
+    this.auth = { ...this.auth, projectId };
+  }
+  /**
+   * Set (or clear) the end-user override for user-token mode.
+   *
+   * Pass `null` or an empty string to clear — subsequent requests go
+   * back to scoping against the developer's own identity. Throws if
+   * called in API-key mode, where end-user context already travels via
+   * the constructor's `userId` field.
+   */
+  updateEndUserId(endUserId) {
+    if (this.auth.kind !== "user_token") {
+      throw new Error("updateEndUserId is only valid in user-token mode");
+    }
+    const normalized = typeof endUserId === "string" && endUserId.length > 0 ? endUserId : null;
+    this.auth = { ...this.auth, endUserId: normalized };
+  }
+  /** Current end-user override in user-token mode, or `null` if unset. */
+  get endUserId() {
+    return this.auth.kind === "user_token" ? this.auth.endUserId : null;
+  }
+  /**
+   * Active project for user-token mode, or `null` if pre-pick (client
+   * was constructed without one). For API-key mode the project is baked
+   * into the key, so this getter returns `null` there too — use
+   * `authMode` to disambiguate.
+   */
+  get projectId() {
+    return this.auth.kind === "user_token" ? this.auth.projectId : null;
+  }
+  /** Which auth mode this client was constructed with. */
+  get authMode() {
+    return this.auth.kind;
+  }
+  /**
+   * Authorization + identity headers for the current auth mode, without
+   * `Content-Type`. Suitable for JSON requests (paired with the JSON header
+   * in the `headers` getter) and for multipart uploads where the browser
+   * must set its own `Content-Type` boundary.
+   */
+  get authHeaders() {
+    if (this.auth.kind === "api_key") {
+      return {
+        Authorization: `Bearer ${this.auth.apiKey}`,
+        "X-End-User-ID": this.auth.userId
+      };
+    }
+    const headers = {
+      Authorization: `Bearer ${this.auth.accessToken}`
+    };
+    if (this.auth.projectId) {
+      headers["X-Project-ID"] = this.auth.projectId;
+    }
+    if (this.auth.endUserId) {
+      headers["X-End-User-ID"] = this.auth.endUserId;
+    }
+    return headers;
+  }
   get headers() {
     return {
-      Authorization: `Bearer ${this.apiKey}`,
-      "X-End-User-ID": this.userId,
+      ...this.authHeaders,
       "Content-Type": "application/json"
     };
   }
@@ -179,9 +423,9 @@ var AstralformClient = class {
       case 401:
         throw new AuthenticationError();
       case 429:
-        throw new RateLimitError();
+        throw createRateLimitErrorFromHttp(response, text);
       default: {
-        const safeText = text ? text.slice(0, 500).replace(/Bearer\s+\S+/gi, "Bearer [REDACTED]") : "";
+        const safeText = text ? sanitizeErrorText(text) : "";
         throw new ServerError(safeText || `HTTP ${response.status}`);
       }
     }
@@ -192,12 +436,18 @@ var AstralformClient = class {
   }
   async getProjectStatus() {
     const raw = await this.get("/v1/project/status");
+    const ui = raw.ui_components ?? {};
     return {
       isReady: raw.is_ready,
       llmConfigured: raw.llm_configured,
       llmProvider: raw.llm_provider,
       llmModel: raw.llm_model,
-      message: raw.message
+      message: raw.message,
+      uiComponents: {
+        enabled: Boolean(ui.enabled),
+        protocol: ui.protocol ?? null,
+        mimeType: ui.mime_type ?? null
+      }
     };
   }
   async getConversations(limit = 50, offset = 0) {
@@ -255,6 +505,52 @@ var AstralformClient = class {
   async submitToolResult(request) {
     await this.post("/v1/tool-result", request);
   }
+  async submitToolApproval(request) {
+    await this.post("/v1/tool-approval", request);
+  }
+  // --- End-user tool-permission self-service ---
+  /**
+   * List the current end user's own remembered tool-permission grants.
+   * Only `conversation`/`always` grants exist (`once` is never persisted).
+   * Paginated via `limit` (default 100, max 200) / `offset`; `total` lets you
+   * page through all of them.
+   */
+  async getMyToolPermissions(options) {
+    const params = new URLSearchParams();
+    if (options?.limit != null) {
+      const safeLimit = Math.max(
+        1,
+        Math.min(200, Math.floor(Number(options.limit)))
+      );
+      params.set("limit", String(safeLimit));
+    }
+    if (options?.offset != null) {
+      const safeOffset = Math.max(0, Math.floor(Number(options.offset)));
+      params.set("offset", String(safeOffset));
+    }
+    const qs = params.toString();
+    const raw = await this.get(`/v1/me/tool-permissions${qs ? `?${qs}` : ""}`);
+    return {
+      grants: raw.grants.map((g) => ({
+        id: g.id,
+        toolName: g.tool_name,
+        decision: g.decision,
+        scope: g.scope,
+        conversationId: g.conversation_id,
+        createdAt: g.created_at
+      })),
+      total: raw.total,
+      limit: raw.limit,
+      offset: raw.offset
+    };
+  }
+  /**
+   * Revoke one of the current end user's remembered grants by id. The agent
+   * will ask again the next time that tool is used.
+   */
+  async revokeToolPermission(id) {
+    await this.del(`/v1/me/tool-permissions/${encodeURIComponent(id)}`);
+  }
   // --- Conversation Assets ---
   mapAsset(raw) {
     return {
@@ -276,10 +572,7 @@ var AstralformClient = class {
       `${this.baseURL}/v1/conversations/${encodeURIComponent(conversationId)}/uploads`,
       {
         method: "POST",
-        headers: {
-          Authorization: `Bearer ${this.apiKey}`,
-          "X-End-User-ID": this.userId
-        },
+        headers: this.authHeaders,
         body: formData
       }
     ).catch((err) => {
@@ -303,6 +596,31 @@ var AstralformClient = class {
     );
     return raw.map((r) => this.mapAsset(r));
   }
+  // --- Account-scoped discovery (user-token mode) ---
+  //
+  // Lets a signed-in user pick which team/project they want to act on.
+  // Backend gates these on OIDC user context (no X-Project-ID required) —
+  // sending them in API-key mode yields 401.
+  async listTeams() {
+    const raw = await this.get("/v1/teams");
+    return raw.map((t) => ({
+      id: t.id,
+      name: t.name,
+      slug: t.slug,
+      isDefault: t.is_default,
+      role: t.role
+    }));
+  }
+  async listProjects(teamId) {
+    const raw = await this.get(`/v1/teams/${encodeURIComponent(teamId)}/projects`);
+    return raw.map((p) => ({
+      id: p.id,
+      name: p.name,
+      teamId: p.team_id,
+      createdAt: p.created_at,
+      updatedAt: p.updated_at
+    }));
+  }
   // --- Jobs API ---
   async createJob(request) {
     return this.post("/v1/jobs", request);
@@ -319,90 +637,50 @@ var AstralformClient = class {
   async cancelJob(jobId) {
     await this.post(`/v1/jobs/${encodeURIComponent(jobId)}/cancel`, {});
   }
-};
-
-// src/block-builder.ts
-var _idCounter = 0;
-var BlockBuilder = class {
-  constructor() {
-    this._blocks = [];
-    this._handlers = /* @__PURE__ */ new Map();
-    this._onChange = null;
-    // Active block refs — public so handlers can read/write them
-    this.activeTextId = null;
-    this.activeThinkingId = null;
-    this.thinkingStartMs = null;
-    this.activeEditorId = null;
-    this.activeTodoId = null;
-  }
-  // ── Registration ──────────────────────────────────────────────
-  on(eventType, handler) {
-    this._handlers.set(eventType, handler);
-  }
-  registerHandlers(handlers) {
-    for (const [type, handler] of Object.entries(handlers)) {
-      this._handlers.set(type, handler);
-    }
-  }
-  // ── Event processing ──────────────────────────────────────────
-  processEvent(event) {
-    const handler = this._handlers.get(event.type);
-    if (handler === null) return;
-    if (!handler) return;
-    handler(event, this);
-  }
-  // ── State ─────────────────────────────────────────────────────
-  getBlocks() {
-    return [...this._blocks];
-  }
-  reset() {
-    this._blocks = [];
-    this.activeTextId = null;
-    this.activeThinkingId = null;
-    this.thinkingStartMs = null;
-    this.activeEditorId = null;
-    this.activeTodoId = null;
-  }
-  setOnChange(fn) {
-    this._onChange = fn;
-  }
-  // ── Block manipulation (used by handlers) ─────────────────────
-  addBlock(block) {
-    this._blocks = [...this._blocks, block];
-    this._notify();
-  }
-  updateBlock(id, updater) {
-    let changed = false;
-    this._blocks = this._blocks.map((b) => {
-      if (b.id !== id) return b;
-      changed = true;
-      return updater(b);
-    });
-    if (changed) this._notify();
-  }
-  /** Update any block by id with a partial update (type-loose for handlers). */
-  patchBlock(id, patch) {
-    let changed = false;
-    this._blocks = this._blocks.map((b) => {
-      if (b.id !== id) return b;
-      changed = true;
-      return { ...b, ...patch };
-    });
-    if (changed) this._notify();
+  async getJob(jobId) {
+    const raw = await this.get(`/v1/jobs/${encodeURIComponent(jobId)}`);
+    return {
+      jobId: raw.job_id,
+      status: raw.status,
+      createdAt: raw.created_at ?? null,
+      startedAt: raw.started_at ?? null,
+      completedAt: raw.completed_at ?? null,
+      errorMessage: raw.error_message ?? null,
+      inputTokens: raw.input_tokens ?? 0,
+      outputTokens: raw.output_tokens ?? 0
+    };
   }
-  findBlock(predicate) {
-    for (let i = this._blocks.length - 1; i >= 0; i--) {
-      const block = this._blocks[i];
-      if (block && predicate(block)) return block;
-    }
-    return void 0;
+  async submitFeedback(jobId, request) {
+    const body = {
+      rating: request.rating
+    };
+    if (request.comment != null) body.comment = request.comment;
+    const raw = await this.post(`/v1/jobs/${encodeURIComponent(jobId)}/feedback`, body);
+    return {
+      id: raw.id,
+      jobId: raw.job_id,
+      rating: raw.rating,
+      comment: raw.comment,
+      createdAt: raw.created_at
+    };
   }
-  nextId() {
-    return `blk_${++_idCounter}`;
+  async getActiveJob(conversationId) {
+    const raw = await this.get(`/v1/conversations/${encodeURIComponent(conversationId)}/active-job`);
+    return {
+      jobId: raw.job_id ?? null,
+      status: raw.status
+    };
   }
-  // ── Internal ──────────────────────────────────────────────────
-  _notify() {
-    this._onChange?.();
+  async listJobs(conversationId) {
+    const raw = await this.get(`/v1/conversations/${encodeURIComponent(conversationId)}/jobs`);
+    return raw.map((j) => ({
+      jobId: j.job_id,
+      status: j.status,
+      replacesJobId: j.replaces_job_id ?? null,
+      responseContent: j.response_content ?? null,
+      metrics: j.metrics ?? null,
+      createdAt: j.created_at ?? null
+    }));
   }
 };
 
@@ -556,40 +834,348 @@ var ToolRegistry = class {
   }
 };
 
-// src/utils.ts
-function generateId() {
-  if (typeof crypto !== "undefined" && crypto.randomUUID) {
-    return crypto.randomUUID();
+// src/protocol-registry.ts
+var ProtocolRegistry = class {
+  constructor() {
+    this.adapters = /* @__PURE__ */ new Map();
+  }
+  /** Register or replace the adapter for a MIME type. */
+  register(adapter) {
+    this.adapters.set(adapter.mimeType, adapter);
+  }
+  /** Remove the adapter for a MIME type. No-op if not registered. */
+  unregister(mimeType) {
+    this.adapters.delete(mimeType);
+  }
+  /** Returns the adapter for a MIME type, or ``null`` if none is registered. */
+  get(mimeType) {
+    return this.adapters.get(mimeType) ?? null;
+  }
+  has(mimeType) {
+    return this.adapters.has(mimeType);
+  }
+  /** Drop every adapter. Called when a session disconnects. */
+  clear() {
+    this.adapters.clear();
+  }
+  listMimeTypes() {
+    return Array.from(this.adapters.keys());
+  }
+};
+
+// src/translate.ts
+function translateDelta(wire) {
+  switch (wire.channel) {
+    case "text":
+      return { channel: "text", text: wire.text };
+    case "thinking":
+      return { channel: "thinking", text: wire.text };
+    case "signature":
+      return { channel: "signature", signature: wire.signature };
+    case "input":
+      return { channel: "input", partialJson: wire.partial_json };
+    case "input_arg":
+      return {
+        channel: "inputArg",
+        argName: wire.arg_name,
+        text: wire.text
+      };
+    case "output":
+      return { channel: "output", stream: wire.stream, chunk: wire.chunk };
+    case "status":
+      return {
+        channel: "status",
+        status: wire.status,
+        note: wire.note
+      };
+    default:
+      return null;
+  }
+}
+function translateAgentIdentity(raw) {
+  return {
+    name: raw.name ?? "",
+    displayName: raw.display_name ?? null,
+    avatarUrl: raw.avatar_url ?? null,
+    description: raw.description ?? null
+  };
+}
+function translateCustomEvent(name, data) {
+  switch (name) {
+    case "user_message":
+      return {
+        type: "user_message",
+        content: data.content ?? "",
+        createdAt: data.created_at
+      };
+    case "title_generated":
+      return {
+        type: "title_generated",
+        title: data.title ?? ""
+      };
+    case "todo_update":
+      return {
+        type: "todo_update",
+        todos: data.todos ?? []
+      };
+    case "context_update":
+      return {
+        type: "context_update",
+        context: data.context ?? {},
+        phase: data.phase ?? null,
+        updatedAt: data.updated_at ?? null
+      };
+    case "subagent_start":
+      return {
+        type: "subagent_start",
+        agent: translateAgentIdentity(
+          data.agent ?? {}
+        ),
+        taskCallId: data.task_call_id ?? null
+      };
+    case "subagent_stop":
+      return {
+        type: "subagent_stop",
+        agent: translateAgentIdentity(
+          data.agent ?? {}
+        ),
+        taskCallId: data.task_call_id ?? null
+      };
+    case "context_warning":
+      return {
+        type: "context_warning",
+        severity: data.severity ?? "warning",
+        utilizationPct: data.utilization_pct ?? 0,
+        remainingTokens: data.remaining_tokens ?? 0,
+        windowTokens: data.window_tokens ?? 0,
+        inputTokens: data.input_tokens ?? 0,
+        message: data.message ?? ""
+      };
+    case "memory_recall":
+      return {
+        type: "memory_recall",
+        memories: data.memories ?? []
+      };
+    case "memory_update":
+      return {
+        type: "memory_update",
+        action: data.action ?? "",
+        memoryId: data.memory_id ?? null,
+        key: data.key ?? null,
+        namespace: data.namespace ?? null
+      };
+    case "desktop_stream":
+      return {
+        type: "desktop_stream",
+        url: data.url ?? "",
+        sandboxId: data.sandbox_id ?? null
+      };
+    case "attachment_staged":
+      return {
+        type: "attachment_staged",
+        attachmentId: data.attachment_id ?? "",
+        filename: data.filename ?? "",
+        contentType: data.content_type ?? null,
+        sizeBytes: data.size_bytes ?? null
+      };
+    case "workspace_ready":
+      return {
+        type: "workspace_ready",
+        sandboxId: data.sandbox_id ?? "",
+        workspacePath: data.workspace_path ?? null
+      };
+    case "asset_created":
+      return {
+        type: "asset_created",
+        assetId: data.asset_id ?? "",
+        filename: data.filename ?? "",
+        url: data.url ?? null,
+        contentType: data.content_type ?? null
+      };
+    case "tool_approval_requested":
+      return {
+        type: "tool_approval_requested",
+        toolName: data.tool_name ?? "",
+        callId: data.call_id ?? "",
+        arguments: data.arguments ?? {},
+        riskLevel: data.risk_level ?? null,
+        reason: data.reason ?? null
+      };
+    case "tool_approval_granted":
+      return {
+        type: "tool_approval_granted",
+        toolName: data.tool_name ?? "",
+        callId: data.call_id ?? ""
+      };
+    case "tool_permission_denied":
+      return {
+        type: "tool_permission_denied",
+        toolName: data.tool_name ?? "",
+        callId: data.call_id ?? "",
+        reason: data.reason ?? null,
+        deniedBy: data.denied_by ?? null
+      };
+    case "tool_harness_warning":
+      return {
+        type: "tool_harness_warning",
+        toolName: data.tool_name ?? "",
+        callId: data.call_id ?? "",
+        message: data.message ?? null,
+        details: data.details ?? null
+      };
+    case "user_unavailable":
+      return {
+        type: "user_unavailable",
+        consecutiveTimeouts: data.consecutive_timeouts ?? 0,
+        toolName: data.tool_name ?? null
+      };
+    case "prompt_suggestion":
+      return {
+        type: "prompt_suggestion",
+        suggestions: data.suggestions ?? []
+      };
+    case "state_changed":
+      return {
+        type: "state_changed",
+        state: data.state ?? ""
+      };
+    default:
+      return { type: "custom", name, data };
+  }
+}
+function legacyCustomEventData(wire) {
+  return wire;
+}
+function translateWireEvent(wire) {
+  if (wire.type === "prompt_suggestion") {
+    return translateCustomEvent(
+      "prompt_suggestion",
+      legacyCustomEventData(wire)
+    );
+  }
+  switch (wire.type) {
+    case "message_start":
+      return {
+        type: "message_start",
+        turnId: wire.turn_id,
+        model: wire.model,
+        agentName: wire.agent_name,
+        agentDisplayName: wire.agent_display_name,
+        agentAvatarUrl: wire.agent_avatar_url
+      };
+    case "block_start":
+      return {
+        type: "block_start",
+        turnId: wire.turn_id,
+        path: wire.path,
+        parentPath: wire.parent_path ?? null,
+        kind: wire.kind,
+        metadata: wire.metadata
+      };
+    case "block_delta": {
+      const delta = translateDelta(wire.delta);
+      if (!delta) return null;
+      return {
+        type: "block_delta",
+        turnId: wire.turn_id,
+        path: wire.path,
+        delta
+      };
+    }
+    case "block_stop":
+      return {
+        type: "block_stop",
+        turnId: wire.turn_id,
+        path: wire.path,
+        status: wire.status,
+        final: wire.final
+      };
+    case "message_stop":
+      return {
+        type: "message_stop",
+        turnId: wire.turn_id,
+        jobId: wire.job_id,
+        stopReason: wire.stop_reason,
+        usage: {
+          inputTokens: wire.usage.input_tokens ?? 0,
+          outputTokens: wire.usage.output_tokens ?? 0,
+          cachedTokens: wire.usage.cached_tokens ?? 0
+        },
+        ttfbMs: wire.ttfb_ms,
+        totalMs: wire.total_ms,
+        stallCount: wire.stall_count
+      };
+    case "stall":
+      return {
+        type: "stall",
+        sinceLastEventMs: wire.since_last_event_ms,
+        stallCount: wire.stall_count
+      };
+    case "retry":
+      return {
+        type: "retry",
+        attempt: wire.attempt,
+        reason: wire.reason,
+        backoffMs: wire.backoff_ms,
+        strategy: wire.strategy ?? null,
+        maxAttempts: wire.max_attempts ?? null,
+        contextRecovery: wire.context_recovery ?? null
+      };
+    case "error":
+      return {
+        type: "error",
+        code: wire.code,
+        message: wire.message,
+        blockPath: wire.block_path ?? null
+      };
+    case "keepalive":
+      return {
+        type: "keepalive",
+        sinceLastEventMs: wire.since_last_event_ms
+      };
+    case "custom":
+      return translateCustomEvent(wire.name, wire.data);
+    default: {
+      const _exhaustive = wire;
+      void _exhaustive;
+      return null;
+    }
   }
-  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
-    const r = Math.random() * 16 | 0;
-    const v = c === "x" ? r : r & 3 | 8;
-    return v.toString(16);
-  });
 }
 
 // src/session.ts
+function pathEquals(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}
 var ChatSession = class {
-  constructor(config, storage, blockBuilder) {
+  constructor(config, storage) {
+    /**
+     * Pluggable UI protocol adapters. Consumers register a framework-
+     * specific adapter (e.g. React) for each MIME type they can render,
+     * typically gated on ``session.projectStatus.uiComponents.protocol``.
+     * ``ToolBlock``-style consumers look up the adapter for an incoming
+     * embedded resource and hand off rendering.
+     */
+    this.protocols = new ProtocolRegistry();
     // State
     this.conversationId = null;
     this.conversations = [];
     this.messages = [];
-    this.streamingContent = "";
     this.isStreaming = false;
-    this.executingTool = null;
     this.projectStatus = null;
     this.agents = [];
     this.skills = [];
     this.enabledClientTools = /* @__PURE__ */ new Set();
     this.modelDisplayName = null;
-    // New state fields
-    this.thinkingContent = "";
-    this.isThinking = false;
-    this.activeSubagents = /* @__PURE__ */ new Map();
-    this.capsuleOutputs = [];
-    this.todos = [];
-    this.activeTools = /* @__PURE__ */ new Map();
+    // Minimal in-session accumulation for the assistant message record.
+    // Only top-level ``text`` blocks contribute; subagent / tool output
+    // is tracked by the consumer's own block store.
+    this.accumulatedText = "";
+    this.currentTextPath = null;
     this.handlers = /* @__PURE__ */ new Set();
     this.abortController = null;
     /** Last received sequence number for resumable reconnection */
@@ -599,13 +1185,6 @@ var ChatSession = class {
     this.client = new AstralformClient(config);
     this.toolRegistry = new ToolRegistry();
     this.storage = storage ?? new InMemoryStorage();
-    this.blockBuilder = blockBuilder ?? new BlockBuilder();
-    this.blockBuilder.setOnChange(() => {
-      this.emit({
-        type: "blocks_changed",
-        blocks: this.blockBuilder.getBlocks()
-      });
-    });
   }
   on(handler) {
     this.handlers.add(handler);
@@ -614,9 +1193,6 @@ var ChatSession = class {
     };
   }
   emit(event) {
-    if (event.type !== "blocks_changed" && event.type !== "connected") {
-      this.blockBuilder.processEvent(event);
-    }
     for (const handler of this.handlers) {
       try {
         handler(event);
@@ -669,7 +1245,8 @@ var ChatSession = class {
       ),
       upload_ids: options?.uploadIds,
       agent_name: options?.agentName,
-      enable_search: options?.enableSearch
+      enable_search: options?.enableSearch,
+      plan_mode: options?.planMode
     };
     await this.processStream(request);
   }
@@ -686,13 +1263,8 @@ var ChatSession = class {
     await this.processStream(request);
   }
   resetStreamingState() {
-    this.streamingContent = "";
-    this.thinkingContent = "";
-    this.isThinking = false;
-    this.activeSubagents.clear();
-    this.capsuleOutputs = [];
-    this.todos = [];
-    this.activeTools.clear();
+    this.accumulatedText = "";
+    this.currentTextPath = null;
   }
   async processStream(request) {
     this.isStreaming = true;
@@ -704,22 +1276,42 @@ var ChatSession = class {
       if (!(err instanceof DOMException && err.name === "AbortError")) {
         this.emit({
           type: "error",
-          error: err instanceof Error ? err : new ConnectionError(String(err))
+          code: "connection_error",
+          message: err instanceof Error ? err.message : String(err),
+          blockPath: null
         });
       }
     } finally {
       this.isStreaming = false;
-      this.executingTool = null;
       this.abortController = null;
     }
   }
   async consumeJobStream(request) {
     const job = await this.client.createJob(request);
     this.currentJobId = job.job_id;
-    let conversationId = job.conversation_id;
+    const conversationId = job.conversation_id;
     if (!this.conversationId) {
       this.conversationId = conversationId;
     }
+    if (!this.conversations.some((c) => c.id === conversationId)) {
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      const conv = {
+        id: conversationId,
+        title: "",
+        messageCount: 0,
+        createdAt: now,
+        updatedAt: now
+      };
+      this.conversations.unshift(conv);
+      await this.storage.createConversation(conversationId, "").catch(() => {
+      });
+    }
+    const lastMsg = this.messages[this.messages.length - 1];
+    if (lastMsg?.role === "user" && !lastMsg.conversationId) {
+      lastMsg.conversationId = conversationId;
+      await this.storage.addMessage(lastMsg, conversationId).catch(() => {
+      });
+    }
     const messageId = job.message_id;
     this.lastSeq = -1;
     const stream = this.client.streamJobEvents(
@@ -736,7 +1328,8 @@ var ChatSession = class {
     );
   }
   /**
-   * Shared event consumption loop used by both consumeJobStream and reconnectToJob.
+   * Shared event consumption loop. Parses each wire event, updates
+   * minimal session state, and emits typed ChatEvents to consumers.
    */
   async consumeEventStream(stream, conversationId, messageId, executeClientTools) {
     for await (const raw of stream) {
@@ -756,419 +1349,112 @@ var ChatSession = class {
       } catch {
         continue;
       }
-      switch (parsed.type) {
-        case "message_start":
-          conversationId = parsed.conversation_id;
-          if (!this.conversationId) {
-            this.conversationId = conversationId;
-          }
-          if (parsed.message_id) {
-            messageId = parsed.message_id;
-          }
-          if (parsed.model_display_name) {
-            this.modelDisplayName = parsed.model_display_name;
-            this.emit({
-              type: "model_info",
-              name: parsed.model_display_name
-            });
-          }
-          break;
-        case "content_block_delta":
-          this.streamingContent += parsed.delta.text;
-          this.emit({ type: "chunk", text: parsed.delta.text });
-          break;
-        case "tool_use_start": {
-          this.applyEvent(parsed);
-          if (executeClientTools && parsed.is_client_tool) {
-            const results = await this.executeClientTools([
-              {
-                callId: parsed.call_id,
-                toolName: parsed.tool,
-                displayName: parsed.display_name,
-                description: parsed.description,
-                arguments: parsed.arguments,
-                isClientTool: parsed.is_client_tool,
-                toolCategory: parsed.tool_category,
-                iconUrl: parsed.icon_url
-              }
-            ]);
-            await this.client.submitToolResult({
-              conversation_id: conversationId,
-              message_id: messageId,
-              tool_results: results
-            });
-          }
-          break;
-        }
-        case "subagent_content_delta": {
-          const subagent = this.activeSubagents.get(parsed.tool_call_id);
-          if (subagent) {
-            subagent.content += parsed.delta.text;
-          }
-          this.emit({
-            type: "subagent_chunk",
-            agentName: parsed.agent_name,
-            toolCallId: parsed.tool_call_id,
-            text: parsed.delta.text
-          });
-          break;
-        }
-        case "thinking_delta":
-          this.thinkingContent += parsed.delta.text;
-          this.isThinking = true;
-          this.emit({ type: "thinking_delta", text: parsed.delta.text });
-          break;
-        case "thinking_complete":
-          this.isThinking = false;
-          this.emit({ type: "thinking_complete" });
-          break;
-        case "retry":
-          this.emit({
-            type: "retry",
-            attempt: parsed.attempt,
-            maxAttempts: parsed.max_attempts,
-            delaySeconds: parsed.delay_seconds
-          });
-          break;
-        case "message_stop":
-          await this.completeStream(
-            conversationId,
-            messageId,
-            parsed.title,
-            parsed.metrics,
-            parsed.job_id
-          );
-          this.isStreaming = false;
-          this.currentJobId = null;
-          break;
-        case "error":
-          this.emit({
-            type: "error",
-            error: new AstralformError(parsed.message, parsed.code)
-          });
-          break;
-        default:
-          this.applyEvent(parsed);
-      }
+      await this.dispatchWireEvent(
+        parsed,
+        conversationId,
+        messageId,
+        executeClientTools
+      );
+    }
+  }
+  async dispatchWireEvent(wire, conversationId, messageId, executeClientTools) {
+    this.applyWireSideEffects(wire, conversationId, messageId);
+    const event = translateWireEvent(wire);
+    if (event) {
+      this.emit(event);
+    }
+    if (executeClientTools && wire.type === "block_stop" && wire.status === "awaiting_client_result" && wire.final?.call_id) {
+      const f = wire.final;
+      const request = {
+        callId: f.call_id ?? "",
+        toolName: f.tool_name ?? "",
+        arguments: f.input ?? {},
+        isClientTool: true
+      };
+      const results = await this.executeClientTools([request]);
+      await this.client.submitToolResult({
+        conversation_id: conversationId,
+        message_id: messageId,
+        tool_results: results
+      });
     }
   }
   /**
-   * Apply a single SSE event to session state and notify consumers.
-   * Shared between live streaming and historical event replay.
+   * State mutations driven by wire events. Kept separate from translation so
+   * the pure wire → ChatEvent mapping can live in translate.ts and be reused
+   * by the replay path.
+   *
+   * ``messageId`` is the server-assigned assistant message id for the current
+   * turn; empty in the reconnect and conversation-switch replay paths where
+   * messages have already been loaded from REST and shouldn't be re-pushed.
    */
-  applyEvent(event) {
-    switch (event.type) {
-      case "user_message":
-        this.emit({
-          type: "user_message",
-          content: event.content,
-          createdAt: event.created_at
-        });
-        break;
-      case "title_generated": {
-        if (this.conversationId && event.title) {
-          const conv = this.conversations.find(
-            (c) => c.id === this.conversationId
-          );
-          if (conv) {
-            conv.title = event.title;
-          }
-        }
-        this.emit({ type: "title_generated", title: event.title });
-        break;
-      }
+  applyWireSideEffects(wire, conversationId, messageId) {
+    switch (wire.type) {
       case "message_start":
-        if (event.conversation_id && !this.conversationId) {
-          this.conversationId = event.conversation_id;
+        this.resetStreamingState();
+        if (wire.model) {
+          this.modelDisplayName = wire.model;
         }
-        if (event.model_display_name) {
-          this.modelDisplayName = event.model_display_name;
-          this.emit({ type: "model_info", name: event.model_display_name });
+        return;
+      case "block_start":
+        if (wire.kind === "text" && (!wire.parent_path || wire.parent_path.length === 0)) {
+          this.currentTextPath = wire.path;
         }
-        break;
-      case "content_block_delta":
-        this.streamingContent += event.delta.text;
-        this.emit({ type: "chunk", text: event.delta.text });
-        break;
-      case "thinking_delta":
-        this.thinkingContent += event.delta.text;
-        this.isThinking = true;
-        this.emit({ type: "thinking_delta", text: event.delta.text });
-        break;
-      case "thinking_complete":
-        this.isThinking = false;
-        this.emit({ type: "thinking_complete" });
-        break;
-      case "tool_executing":
-        this.emit({
-          type: "tool_executing",
-          name: event.tool,
-          call_id: event.call_id
-        });
-        break;
-      case "tool_progress":
-        this.emit({
-          type: "tool_progress",
-          callId: event.call_id,
-          tool: event.tool,
-          index: event.index,
-          total: event.total,
-          item: event.item
-        });
-        break;
-      case "message_stop":
-        this.emit({
-          type: "complete",
-          content: this.streamingContent,
-          conversationId: this.conversationId ?? "",
-          messageId: event.job_id ?? "",
-          title: event.title,
-          metrics: event.metrics,
-          job_id: event.job_id
-        });
-        break;
-      case "tool_use_start": {
-        const request = {
-          callId: event.call_id,
-          toolName: event.tool,
-          displayName: event.display_name,
-          description: event.description,
-          arguments: event.arguments,
-          isClientTool: event.is_client_tool,
-          toolCategory: event.tool_category,
-          iconUrl: event.icon_url
-        };
-        this.activeTools.set(event.call_id, {
-          ...request,
-          status: event.is_client_tool ? "calling" : "executing"
-        });
-        this.emit({ type: "tool_call", request });
-        break;
-      }
-      case "tool_use_end": {
-        const toolState = this.activeTools.get(event.call_id);
-        if (toolState) {
-          toolState.status = "completed";
+        return;
+      case "block_delta":
+        if (wire.delta.channel === "text" && this.currentTextPath !== null && pathEquals(this.currentTextPath, wire.path)) {
+          this.accumulatedText += wire.delta.text;
         }
-        this.emit({
-          type: "tool_end",
-          callId: event.call_id,
-          toolName: event.tool,
-          result: event.result,
-          sources: event.sources,
-          durationMs: event.duration_ms
-        });
-        break;
-      }
-      case "agent_start":
-        this.emit({
-          type: "agent_start",
-          agentName: event.agent_name,
-          agentDisplayName: event.agent_display_name,
-          avatarUrl: event.avatar_url
-        });
-        break;
-      case "agent_end":
-        this.emit({ type: "agent_end", agentName: event.agent_name });
-        break;
-      case "subagent_start":
-        this.activeSubagents.set(event.tool_call_id, {
-          agentName: event.agent_name,
-          displayName: event.display_name,
-          avatarUrl: event.avatar_url,
-          description: event.description,
-          content: "",
-          isActive: true
-        });
-        this.emit({
-          type: "subagent_start",
-          agentName: event.agent_name,
-          displayName: event.display_name,
-          toolCallId: event.tool_call_id,
-          avatarUrl: event.avatar_url,
-          description: event.description
-        });
-        break;
-      case "subagent_update": {
-        const sub = this.activeSubagents.get(event.tool_call_id);
-        if (sub) {
-          sub.agentName = event.agent_name;
-          sub.displayName = event.display_name;
+        return;
+      case "block_stop":
+        if (this.currentTextPath !== null && pathEquals(this.currentTextPath, wire.path)) {
+          this.currentTextPath = null;
         }
-        this.emit({
-          type: "subagent_update",
-          agentName: event.agent_name,
-          displayName: event.display_name,
-          toolCallId: event.tool_call_id
-        });
-        break;
-      }
-      case "subagent_end": {
-        const sub = this.activeSubagents.get(event.tool_call_id);
-        if (sub) {
-          sub.isActive = false;
+        return;
+      case "message_stop":
+        if (messageId) {
+          const assistantMessage = {
+            id: messageId,
+            conversationId,
+            role: "assistant",
+            content: this.accumulatedText,
+            status: "complete",
+            createdAt: (/* @__PURE__ */ new Date()).toISOString()
+          };
+          this.messages.push(assistantMessage);
+          this.storage.addMessage(assistantMessage, conversationId).catch(() => {
+          });
         }
-        this.emit({
-          type: "subagent_end",
-          agentName: event.agent_name,
-          displayName: event.display_name,
-          toolCallId: event.tool_call_id
-        });
-        break;
-      }
-      case "subagent_tool_use":
-        this.emit({
-          type: "subagent_tool_use",
-          agentName: event.agent_name,
-          toolName: event.tool,
-          toolCallId: event.tool_call_id,
-          result: event.result
-        });
-        break;
-      case "capsule_output": {
-        const capsule = {
-          toolName: event.tool_name,
-          agentName: event.agent_name,
-          command: event.command,
-          output: event.output,
-          durationMs: event.duration_ms,
-          callId: event.call_id
-        };
-        this.capsuleOutputs.push(capsule);
-        this.emit({ type: "capsule_output", ...capsule });
-        break;
-      }
-      case "capsule_output_chunk":
-        this.emit({
-          type: "capsule_output_chunk",
-          callId: event.call_id,
-          stream: event.stream,
-          chunk: event.chunk
-        });
-        break;
-      case "todo_update":
-        this.todos = event.todos;
-        this.emit({ type: "todo_update", todos: event.todos });
-        break;
-      case "context_update":
-        this.emit({
-          type: "context_update",
-          context: event.context,
-          phase: event.phase,
-          updatedAt: event.updated_at
-        });
-        break;
-      case "desktop_stream":
-        this.emit({
-          type: "desktop_stream",
-          url: event.url,
-          authKey: event.auth_key,
-          sandboxId: event.sandbox_id
-        });
-        break;
-      case "attachment_staged":
-        this.emit({
-          type: "attachment_staged",
-          files: (event.files || []).map((f) => ({
-            name: f.name,
-            path: f.path,
-            mediaType: f.media_type,
-            sizeBytes: f.size_bytes
-          }))
-        });
-        break;
-      case "workspace_ready":
-        this.emit({
-          type: "workspace_ready",
-          conversationId: event.conversation_id,
-          sandboxId: event.sandbox_id
-        });
-        break;
-      case "asset_created":
-        this.emit({
-          type: "asset_created",
-          assetId: event.asset_id,
-          name: event.name,
-          url: event.url,
-          mediaType: event.media_type,
-          sizeBytes: event.size_bytes
-        });
-        break;
-      case "editor_content_start":
-        this.emit({
-          type: "editor_content_start",
-          callId: event.call_id,
-          path: event.path,
-          language: event.language
-        });
-        break;
-      case "editor_content_delta":
-        this.emit({
-          type: "editor_content_delta",
-          callId: event.call_id,
-          path: event.path,
-          delta: event.delta
-        });
-        break;
-      case "editor_content_end":
-        this.emit({
-          type: "editor_content_end",
-          callId: event.call_id
-        });
-        break;
+        this.isStreaming = false;
+        this.currentJobId = null;
+        return;
+      case "custom":
+        if (wire.name === "title_generated") {
+          const title = wire.data.title ?? "";
+          if (this.conversationId && title) {
+            const conv = this.conversations.find(
+              (c) => c.id === this.conversationId
+            );
+            if (conv) {
+              conv.title = title;
+            }
+            this.storage.updateConversationTitle(this.conversationId, title).catch(() => {
+            });
+          }
+        }
+        return;
+      default:
+        return;
     }
   }
   async executeClientTools(toolCalls) {
     const results = [];
     for (const call of toolCalls) {
-      this.executingTool = call.toolName;
-      const toolState = this.activeTools.get(call.callId);
-      if (toolState) {
-        toolState.status = "executing";
-      }
-      this.emit({ type: "tool_executing", name: call.toolName });
       const result = await this.toolRegistry.executeTool(call);
       results.push(result);
-      if (toolState) {
-        toolState.status = "completed";
-      }
-      this.emit({
-        type: "tool_completed",
-        name: call.toolName,
-        result: result.result
-      });
     }
-    this.executingTool = null;
     return results;
   }
-  async completeStream(conversationId, messageId, title, metrics, jobId) {
-    const assistantMessage = {
-      id: messageId || generateId(),
-      conversationId,
-      role: "assistant",
-      content: this.streamingContent,
-      status: "complete",
-      createdAt: (/* @__PURE__ */ new Date()).toISOString()
-    };
-    this.messages.push(assistantMessage);
-    await this.storage.addMessage(assistantMessage, conversationId);
-    if (title && conversationId) {
-      await this.storage.updateConversationTitle(conversationId, title);
-      const conv = this.conversations.find((c) => c.id === conversationId);
-      if (conv) {
-        conv.title = title;
-      }
-    }
-    this.emit({
-      type: "complete",
-      content: this.streamingContent,
-      conversationId,
-      messageId: assistantMessage.id,
-      title,
-      metrics,
-      job_id: jobId
-    });
-  }
   /**
    * Load conversation context (messages) without replaying events.
    * Used before reconnectToJob — SSE replay handles event replay.
@@ -1176,13 +1462,11 @@ var ChatSession = class {
   async loadConversation(id) {
     this.conversationId = id;
     this.resetStreamingState();
-    this.blockBuilder.reset();
     this.messages = await this.client.getMessages(id).catch(() => this.storage.fetchMessages(id));
   }
   /**
    * Reconnect to a running job's SSE stream (e.g. after page reload).
    * Replays all events from the beginning and continues live.
-   * Does NOT reset BlockBuilder — caller controls reset.
    */
   async reconnectToJob(jobId) {
     if (this.isStreaming) return;
@@ -1207,23 +1491,21 @@ var ChatSession = class {
     } catch (err) {
       this.emit({
         type: "error",
-        error: err instanceof Error ? err : new ConnectionError(String(err))
+        code: "connection_error",
+        message: err instanceof Error ? err.message : String(err),
+        blockPath: null
       });
     } finally {
       this.isStreaming = false;
-      this.executingTool = null;
       this.abortController = null;
     }
   }
-  /** Detach from the SSE stream without cancelling the job.
-   *  The backend job keeps running — caller can reconnect later. */
+  /** Detach from the SSE stream without cancelling the job. */
   detach() {
     this.abortController?.abort();
     this.abortController = null;
     this.isStreaming = false;
-    this.streamingContent = "";
-    this.executingTool = null;
-    this.blockBuilder.reset();
+    this.resetStreamingState();
     this.emit({ type: "disconnected" });
   }
   /** Stop the job and disconnect (explicit user action). */
@@ -1234,6 +1516,7 @@ var ChatSession = class {
     }
     this.detach();
     this.currentJobId = null;
+    this.protocols.clear();
   }
   async createNewConversation() {
     const id = generateId();
@@ -1244,21 +1527,39 @@ var ChatSession = class {
     this.conversations.unshift(conversation);
     this.conversationId = id;
     this.messages = [];
-    this.streamingContent = "";
     return id;
   }
-  async switchConversation(id, jobId) {
+  async switchConversation(id, jobId, userMessageContent) {
     this.conversationId = id;
     this.resetStreamingState();
-    this.blockBuilder.reset();
     const [messagesResult, eventsResult] = await Promise.allSettled([
       this.client.getMessages(id).catch(() => this.storage.fetchMessages(id)),
       this.client.getConversationEvents(id, jobId)
     ]);
     this.messages = messagesResult.status === "fulfilled" ? messagesResult.value : [];
     if (eventsResult.status === "fulfilled") {
+      let userMessageEmitted = !userMessageContent;
       for (const ev of eventsResult.value) {
-        this.applyEvent({ type: ev.event, ...ev.data });
+        const type = ev.data.type || ev.event;
+        if (!type || type === "done") continue;
+        if (!userMessageEmitted && type === "message_start") {
+          this.emit({
+            type: "user_message",
+            content: userMessageContent
+          });
+          userMessageEmitted = true;
+        }
+        const wire = { ...ev.data, type };
+        try {
+          await this.dispatchWireEvent(
+            wire,
+            id,
+            "",
+            false
+            // don't execute client tools on replay
+          );
+        } catch {
+        }
       }
     }
   }
@@ -1284,456 +1585,46 @@ var ChatSession = class {
   }
 };
 
-// src/standard-handlers.ts
-function finalizeText(builder) {
-  if (builder.activeTextId) {
-    builder.patchBlock(builder.activeTextId, {
-      isStreaming: false
-    });
-    builder.activeTextId = null;
-  }
-}
-function finalizeThinking(builder) {
-  if (builder.activeThinkingId) {
-    builder.patchBlock(builder.activeThinkingId, {
-      isActive: false
-    });
-    builder.activeThinkingId = null;
-    builder.thinkingStartMs = null;
-  }
-}
-function finalizeEditor(builder) {
-  if (builder.activeEditorId) {
-    builder.patchBlock(builder.activeEditorId, {
-      isStreaming: false
-    });
-    builder.activeEditorId = null;
-  }
-}
-var handleUserMessage = (event, builder) => {
-  const e = event;
-  const existing = builder.findBlock((b) => b.type === "user");
-  if (existing) {
-    if (e.createdAt) {
-      builder.patchBlock(existing.id, {
-        createdAt: e.createdAt
-      });
-    }
-    return;
-  }
-  builder.addBlock({
-    type: "user",
-    id: builder.nextId(),
-    content: e.content,
-    createdAt: e.createdAt
-  });
-};
-var handleChunk = (event, builder) => {
-  const e = event;
-  if (!builder.activeTextId) {
-    const id = builder.nextId();
-    builder.activeTextId = id;
-    builder.addBlock({
-      type: "text",
-      id,
-      content: e.text,
-      isStreaming: true
-    });
-  } else {
-    const id = builder.activeTextId;
-    const existing = builder.findBlock((b) => b.id === id);
-    if (existing && existing.type === "text") {
-      builder.patchBlock(id, {
-        content: existing.content + e.text
-      });
-    }
-  }
-};
-var handleToolCall = (event, builder) => {
-  const e = event;
-  finalizeText(builder);
-  builder.addBlock({
-    type: "tool",
-    id: builder.nextId(),
-    callId: e.request.callId,
-    toolName: e.request.toolName,
-    displayName: e.request.displayName,
-    description: e.request.description,
-    arguments: e.request.arguments,
-    toolCategory: e.request.toolCategory,
-    iconUrl: e.request.iconUrl,
-    status: "calling"
-  });
-};
-var handleToolExecuting = (event, builder) => {
-  const e = event;
-  const block = builder.findBlock(
-    (b) => b.type === "tool" && (e.call_id ? b.callId === e.call_id : b.toolName === e.name) && b.status === "calling"
-  );
-  if (block) {
-    builder.patchBlock(block.id, { status: "executing" });
-  }
-};
-var handleToolProgress = (event, builder) => {
-  const e = event;
-  const block = builder.findBlock(
-    (b) => b.type === "tool" && b.callId === e.callId
-  );
-  if (block && block.type === "tool") {
-    const sources = block.sources ? [...block.sources] : [];
-    sources.push(e.item);
-    builder.patchBlock(block.id, {
-      sources,
-      status: "executing"
-    });
-  }
-};
-var handleToolEnd = (event, builder) => {
-  const e = event;
-  const callId = e.type === "tool_end" ? e.callId : void 0;
-  const name = e.type === "tool_end" ? e.toolName : e.name;
-  const block = builder.findBlock(
-    (b) => b.type === "tool" && (callId ? b.callId === callId : b.toolName === name) && b.status !== "completed"
-  );
-  if (block) {
-    const toolEnd = e.type === "tool_end" ? e : null;
-    builder.patchBlock(block.id, {
-      status: "completed",
-      ...toolEnd?.sources ? { sources: toolEnd.sources } : {},
-      ...toolEnd?.durationMs != null ? { durationMs: toolEnd.durationMs } : {},
-      ...toolEnd?.result ? { result: toolEnd.result } : {}
-    });
-  }
-};
-var handleAgentStart = (event, builder) => {
-  const e = event;
-  finalizeText(builder);
-  builder.addBlock({
-    type: "agent",
-    id: builder.nextId(),
-    agentName: e.agentName,
-    displayName: e.agentDisplayName,
-    avatarUrl: e.avatarUrl
-  });
-};
-var handleThinkingDelta = (event, builder) => {
-  const e = event;
-  if (!builder.activeThinkingId) {
-    const id = builder.nextId();
-    builder.activeThinkingId = id;
-    builder.thinkingStartMs = Date.now();
-    builder.addBlock({
-      type: "thinking",
-      id,
-      content: e.text,
-      isActive: true
-    });
-  } else {
-    const id = builder.activeThinkingId;
-    const existing = builder.findBlock((b) => b.id === id);
-    if (existing && existing.type === "thinking") {
-      builder.patchBlock(id, {
-        content: existing.content + e.text
-      });
-    }
-  }
-};
-var handleThinkingComplete = (_event, builder) => {
-  if (builder.activeThinkingId) {
-    const durationMs = builder.thinkingStartMs ? Math.max(0, Date.now() - builder.thinkingStartMs) : void 0;
-    builder.patchBlock(builder.activeThinkingId, {
-      isActive: false,
-      durationMs
-    });
-    builder.activeThinkingId = null;
-    builder.thinkingStartMs = null;
-  }
-};
-var handleSubagentStart = (event, builder) => {
-  const e = event;
-  finalizeText(builder);
-  builder.addBlock({
-    type: "subagent",
-    id: builder.nextId(),
-    agentName: e.agentName,
-    displayName: e.displayName,
-    toolCallId: e.toolCallId,
-    avatarUrl: e.avatarUrl,
-    description: e.description,
-    content: "",
-    isActive: true
-  });
-};
-var handleSubagentChunk = (event, builder) => {
-  const e = event;
-  const block = builder.findBlock(
-    (b) => b.type === "subagent" && b.toolCallId === e.toolCallId
-  );
-  if (block && block.type === "subagent") {
-    builder.patchBlock(block.id, {
-      content: block.content + e.text
-    });
-  }
-};
-var handleSubagentUpdate = (event, builder) => {
-  const e = event;
-  const block = builder.findBlock(
-    (b) => b.type === "subagent" && b.toolCallId === e.toolCallId
-  );
-  if (block) {
-    builder.patchBlock(block.id, {
-      displayName: e.displayName
-    });
-  }
-};
-var handleSubagentEnd = (event, builder) => {
-  const e = event;
-  const block = builder.findBlock(
-    (b) => b.type === "subagent" && b.toolCallId === e.toolCallId
-  );
-  if (block) {
-    builder.patchBlock(block.id, {
-      isActive: false
-    });
-  }
-};
-var handleComplete = (_event, builder) => {
-  finalizeText(builder);
-  finalizeThinking(builder);
-  finalizeEditor(builder);
-  for (const b of builder.getBlocks()) {
-    if (b.type === "tool" && b.status !== "completed") {
-      builder.patchBlock(b.id, { status: "completed" });
-    }
-  }
-};
-var handleError = (event, builder) => {
-  const e = event;
-  finalizeText(builder);
-  finalizeThinking(builder);
-  builder.addBlock({
-    type: "error",
-    id: builder.nextId(),
-    message: e.error.message
-  });
-};
-var handleDisconnected = (_event, builder) => {
-  finalizeText(builder);
-  finalizeThinking(builder);
-  finalizeEditor(builder);
-};
-var handleCapsuleOutputChunk = (event, builder) => {
-  const e = event;
-  const block = builder.findBlock(
-    (b) => b.type === "capsule" && b.callId === e.callId
-  );
-  if (block && block.type === "capsule") {
-    builder.patchBlock(block.id, {
-      output: block.output + e.chunk
-    });
-  } else {
-    builder.addBlock({
-      type: "capsule",
-      id: builder.nextId(),
-      callId: e.callId,
-      toolName: "",
-      output: e.chunk,
-      isActive: true
-    });
-  }
-};
-var handleCapsuleOutput = (event, builder) => {
-  const e = event;
-  const block = builder.findBlock(
-    (b) => b.type === "capsule" && b.callId === (e.callId ?? "")
-  );
-  if (block) {
-    builder.patchBlock(block.id, {
-      output: e.output,
-      command: e.command,
-      toolName: e.toolName,
-      durationMs: e.durationMs,
-      isActive: false
-    });
-  } else {
-    builder.addBlock({
-      type: "capsule",
-      id: builder.nextId(),
-      callId: e.callId ?? "",
-      toolName: e.toolName,
-      command: e.command,
-      output: e.output,
-      durationMs: e.durationMs,
-      isActive: false
-    });
-  }
-};
-var handleAssetCreated = (event, builder) => {
-  const e = event;
-  builder.addBlock({
-    type: "asset",
-    id: builder.nextId(),
-    assetId: e.assetId,
-    name: e.name,
-    url: e.url,
-    mediaType: e.mediaType,
-    sizeBytes: e.sizeBytes
-  });
-};
-var handleTodoUpdate = (event, builder) => {
-  const e = event;
-  if (builder.activeTodoId) {
-    builder.patchBlock(builder.activeTodoId, {
-      todos: e.todos
-    });
-  } else {
-    const id = builder.nextId();
-    builder.activeTodoId = id;
-    builder.addBlock({
-      type: "todo",
-      id,
-      todos: e.todos
-    });
-  }
-};
-var handleEditorContentStart = (event, builder) => {
-  const e = event;
-  const id = builder.nextId();
-  builder.activeEditorId = id;
-  builder.addBlock({
-    type: "editor",
-    id,
-    callId: e.callId,
-    path: e.path,
-    language: e.language,
-    content: "",
-    isStreaming: true
-  });
-};
-var handleEditorContentDelta = (event, builder) => {
-  const e = event;
-  const block = builder.findBlock(
-    (b) => b.type === "editor" && b.callId === e.callId
-  );
-  if (block && block.type === "editor") {
-    builder.patchBlock(block.id, {
-      content: block.content + e.delta
-    });
-  }
-};
-var handleEditorContentEnd = (event, builder) => {
-  const e = event;
-  const block = builder.findBlock(
-    (b) => b.type === "editor" && b.callId === e.callId
-  );
-  if (block) {
-    builder.patchBlock(block.id, {
-      isStreaming: false
-    });
-  }
-  builder.activeEditorId = null;
-};
-var handleDesktopStream = (event, builder) => {
-  const e = event;
-  if (!e.url) return;
-  const existing = builder.findBlock((b) => b.type === "desktop_stream");
-  if (existing) {
-    builder.patchBlock(existing.id, {
-      url: e.url,
-      authKey: e.authKey,
-      sandboxId: e.sandboxId
-    });
-  } else {
-    builder.addBlock({
-      type: "desktop_stream",
-      id: builder.nextId(),
-      url: e.url,
-      authKey: e.authKey,
-      sandboxId: e.sandboxId
-    });
-  }
-};
-var handleAttachmentStaged = (event, builder) => {
-  const e = event;
-  if (!e.files || e.files.length === 0) return;
-  builder.addBlock({
-    type: "attachment",
-    id: builder.nextId(),
-    files: e.files
-  });
-};
-var noop = () => {
-};
-var standardHandlers = {
-  user_message: handleUserMessage,
-  chunk: handleChunk,
-  tool_call: handleToolCall,
-  tool_executing: handleToolExecuting,
-  tool_progress: handleToolProgress,
-  tool_completed: handleToolEnd,
-  tool_end: handleToolEnd,
-  agent_start: handleAgentStart,
-  agent_end: noop,
-  thinking_delta: handleThinkingDelta,
-  thinking_complete: handleThinkingComplete,
-  subagent_start: handleSubagentStart,
-  subagent_chunk: handleSubagentChunk,
-  subagent_update: handleSubagentUpdate,
-  subagent_end: handleSubagentEnd,
-  subagent_tool_use: noop,
-  capsule_output: handleCapsuleOutput,
-  capsule_output_chunk: handleCapsuleOutputChunk,
-  asset_created: handleAssetCreated,
-  todo_update: handleTodoUpdate,
-  editor_content_start: handleEditorContentStart,
-  editor_content_delta: handleEditorContentDelta,
-  editor_content_end: handleEditorContentEnd,
-  desktop_stream: handleDesktopStream,
-  attachment_staged: handleAttachmentStaged,
-  workspace_ready: noop,
-  retry: noop,
-  complete: handleComplete,
-  error: handleError,
-  disconnected: handleDisconnected
-};
-
 // src/types.ts
 var ChatEventType = {
+  // Connection lifecycle (SDK-local, not wire)
   Connected: "connected",
-  BlocksChanged: "blocks_changed",
+  Disconnected: "disconnected",
+  // Turn lifecycle
+  MessageStart: "message_start",
+  MessageStop: "message_stop",
+  // Block lifecycle
+  BlockStart: "block_start",
+  BlockDelta: "block_delta",
+  BlockStop: "block_stop",
+  // Reliability
+  Stall: "stall",
+  Retry: "retry",
+  Error: "error",
+  Keepalive: "keepalive",
+  // Conversation-level (typed custom events)
   UserMessage: "user_message",
   TitleGenerated: "title_generated",
-  ModelInfo: "model_info",
-  Chunk: "chunk",
-  ToolCall: "tool_call",
-  ToolExecuting: "tool_executing",
-  ToolProgress: "tool_progress",
-  ToolCompleted: "tool_completed",
-  ToolEnd: "tool_end",
-  AgentStart: "agent_start",
-  AgentEnd: "agent_end",
-  ThinkingDelta: "thinking_delta",
-  ThinkingComplete: "thinking_complete",
-  SubagentStart: "subagent_start",
-  SubagentChunk: "subagent_chunk",
-  SubagentUpdate: "subagent_update",
-  SubagentEnd: "subagent_end",
-  SubagentToolUse: "subagent_tool_use",
-  CapsuleOutput: "capsule_output",
-  CapsuleOutputChunk: "capsule_output_chunk",
-  AssetCreated: "asset_created",
   TodoUpdate: "todo_update",
-  EditorContentStart: "editor_content_start",
-  EditorContentDelta: "editor_content_delta",
-  EditorContentEnd: "editor_content_end",
-  Complete: "complete",
-  Error: "error",
-  Disconnected: "disconnected",
-  Retry: "retry",
   ContextUpdate: "context_update",
+  SubagentStart: "subagent_start",
+  SubagentStop: "subagent_stop",
+  ContextWarning: "context_warning",
+  MemoryRecall: "memory_recall",
+  MemoryUpdate: "memory_update",
   DesktopStream: "desktop_stream",
   AttachmentStaged: "attachment_staged",
-  WorkspaceReady: "workspace_ready"
+  WorkspaceReady: "workspace_ready",
+  AssetCreated: "asset_created",
+  ToolApprovalRequested: "tool_approval_requested",
+  ToolApprovalGranted: "tool_approval_granted",
+  ToolPermissionDenied: "tool_permission_denied",
+  ToolHarnessWarning: "tool_harness_warning",
+  UserUnavailable: "user_unavailable",
+  PromptSuggestion: "prompt_suggestion",
+  StateChanged: "state_changed",
+  // Generic fallthrough for unknown custom events
+  Custom: "custom"
 };
 
 // src/stream-manager.ts
@@ -1788,22 +1679,12 @@ var StreamManager = class {
   }
   onSessionEvent(event) {
     const convId = this.session.conversationId;
-    if (event.type === ChatEventType.BlocksChanged) {
-      if (this._state === "streaming" && convId) {
-        this.emit({
-          type: "blocksChanged",
-          conversationId: convId,
-          blocks: event.blocks
-        });
-      }
-      return;
-    }
     this.emit({
       type: "event",
       conversationId: convId,
       event
     });
-    if (event.type === ChatEventType.Complete) {
+    if (event.type === ChatEventType.MessageStop) {
       if (this._state === "streaming") {
         this.setState("idle");
       }
@@ -1816,13 +1697,13 @@ var StreamManager = class {
       const id = await this.session.createNewConversation();
       this.setActiveConversation(id);
     }
-    this.prepareUserBlock(content);
     this.setState("streaming");
     try {
       await this.session.send(content, {
         enableSearch: options?.enableSearch,
         agentName: options?.agentName,
-        uploadIds: options?.uploadIds
+        uploadIds: options?.uploadIds,
+        planMode: options?.planMode
       });
     } catch {
     }
@@ -1836,7 +1717,6 @@ var StreamManager = class {
     );
     const lastUserMsg = userMsgs[userMsgs.length - 1];
     if (!lastUserMsg) return;
-    this.prepareUserBlock(lastUserMsg.content);
     this.setState("streaming");
     try {
       await this.session.resendFromCheckpoint(
@@ -1900,14 +1780,6 @@ var StreamManager = class {
     this.handlers = [];
   }
   // ── Internal: helpers ──────────────────────────────────────────
-  prepareUserBlock(content) {
-    this.session.blockBuilder.reset();
-    this.session.blockBuilder.addBlock({
-      type: "user",
-      id: this.session.blockBuilder.nextId(),
-      content
-    });
-  }
   finalizeStream() {
     if (this._state === "streaming") {
       this.setState("idle");
@@ -1918,8 +1790,8 @@ var StreamManager = class {
     this.setState("restoring");
     let activeJobId = null;
     try {
-      const res = await this.session.client.get(`/v1/conversations/${encodeURIComponent(conversationId)}/active-job`);
-      activeJobId = res.job_id ?? null;
+      const res = await this.session.client.getActiveJob(conversationId);
+      activeJobId = res.jobId;
     } catch {
     }
     if (activeJobId) {
@@ -1939,15 +1811,19 @@ var StreamManager = class {
         const completedJobs = jobs.filter(
           (j) => j.status === "completed"
         );
-        for (const job of completedJobs) {
-          await this.session.switchConversation(conversationId, job.job_id);
+        const userMessages = this.session.messages.filter(
+          (m) => m.role === "user"
+        );
+        for (let i = 0; i < completedJobs.length; i++) {
+          const job = completedJobs[i];
+          const userContent = userMessages[i]?.content;
+          await this.session.switchConversation(
+            conversationId,
+            job.job_id,
+            userContent
+          );
         }
         if (completedJobs.length > 0) {
-          this.emit({
-            type: "blocksChanged",
-            conversationId,
-            blocks: this.session.blockBuilder.getBlocks()
-          });
           this.emit({
             type: "versionsReady",
             conversationId,
@@ -1965,23 +1841,93 @@ var StreamManager = class {
     this.emit({ type: "conversationChanged", conversationId: id });
   }
 };
+
+// src/replay.ts
+function toWireEvent(raw) {
+  const type = raw.data.type || raw.event;
+  if (!type || type === "done") return null;
+  return { ...raw.data, type };
+}
+function mapSseToChat(raw) {
+  const wire = toWireEvent(raw);
+  if (!wire) return [];
+  const event = translateWireEvent(wire);
+  return event ? [event] : [];
+}
+function replayEvents(sseEvents, userMessages, handleEvent, addBlock) {
+  const userMsgs = userMessages.filter((m) => m.role === "user");
+  let userIdx = 0;
+  let expectingUserMessage = true;
+  for (const raw of sseEvents) {
+    const type = raw.data.type || raw.event;
+    if (type === "message_stop") {
+      expectingUserMessage = true;
+    }
+    if (type === "message_start" && expectingUserMessage && userIdx < userMsgs.length) {
+      const userMsg = userMsgs[userIdx];
+      addBlock({
+        type: "user",
+        id: `replay_user_${userIdx}`,
+        content: userMsg.content
+      });
+      userIdx++;
+      expectingUserMessage = false;
+    }
+    for (const ce of mapSseToChat(raw)) {
+      handleEvent(ce);
+    }
+  }
+}
+
+// src/embedded-resource.ts
+function isEmbeddedResource(value) {
+  return typeof value === "object" && value !== null && value._embedded_resource === true;
+}
+function parseEmbeddedResource(value) {
+  let candidate = value;
+  if (typeof candidate === "string") {
+    const trimmed = candidate.trim();
+    if (!trimmed.startsWith("{")) return null;
+    try {
+      candidate = JSON.parse(trimmed);
+    } catch {
+      return null;
+    }
+  }
+  if (!isEmbeddedResource(candidate)) return null;
+  const mimeType = candidate.mime_type;
+  const uri = candidate.uri;
+  const payload = candidate.payload;
+  if (typeof mimeType !== "string" || !mimeType) return null;
+  if (typeof uri !== "string" || !uri) return null;
+  if (!payload || typeof payload !== "object") return null;
+  return {
+    mimeType,
+    uri,
+    payload
+  };
+}
 export {
   AstralformClient,
   AstralformError,
   AuthenticationError,
-  BlockBuilder,
   ChatEventType,
   ChatSession,
   ConnectionError,
   InMemoryStorage,
   LLMNotConfiguredError,
+  ProtocolRegistry,
   RateLimitError,
   ServerError,
   StreamAbortedError,
   StreamManager,
   ToolRegistry,
   generateId,
-  standardHandlers,
-  streamJobSSE
+  isEmbeddedResource,
+  mapSseToChat,
+  parseEmbeddedResource,
+  replayEvents,
+  streamJobSSE,
+  translateDelta
 };
 //# sourceMappingURL=index.js.map