@love-moon/app-sdk 0.3.2

package/dist/server/index.js

@@ -0,0 +1,1387 @@
+// src/types/errors.ts
+var ConductorAppError = class extends Error {
+  name = "ConductorAppError";
+  code;
+  status;
+  details;
+  requestId;
+  constructor(args) {
+    super(args.message, args.cause ? { cause: args.cause } : void 0);
+    this.code = args.code;
+    this.status = args.status;
+    this.details = args.details;
+    this.requestId = args.requestId;
+  }
+};
+function isConductorAppError(error) {
+  return typeof error === "object" && error !== null && error.name === "ConductorAppError";
+}
+
+// src/types/error-codes.ts
+function extractErrorMarker(details, message) {
+  if (details && typeof details === "object" && "error" in details) {
+    const raw = details.error;
+    if (typeof raw === "string") return raw.toLowerCase();
+  }
+  if (message) return message.toLowerCase();
+  return "";
+}
+function mapHttpStatusToErrorCode(status, details, message) {
+  const marker = extractErrorMarker(details, message);
+  if (status === 401) return "unauthorized";
+  if (status === 403) return "forbidden";
+  if (status === 404) {
+    if (marker.includes("project")) return "project_not_found";
+    if (marker.includes("task")) return "task_not_found";
+    if (marker.includes("message")) return "message_not_found";
+    return "task_not_found";
+  }
+  if (status === 408) return "timeout";
+  if (status === 409) {
+    if (marker.includes("fire owner")) return "task_fire_owner_offline";
+    if (marker.includes("task_type")) return "task_type_not_messageable";
+    if (marker.includes("not_running") || marker.includes("not running"))
+      return "task_not_running";
+    if (marker.includes("daemon") || marker.includes("offline")) return "daemon_offline";
+    if (marker.includes("binding")) return "binding_validation_failed";
+    return "binding_validation_failed";
+  }
+  if (status === 422) return "invalid_input";
+  if (status === 429) return "rate_limited";
+  if (status >= 500) return "server_error";
+  if (status >= 400) return "invalid_input";
+  return "server_error";
+}
+
+// src/index.ts
+var SDK_VERSION = "0.3.2";
+var SDK_NAME = "@love-moon/app-sdk";
+var SDK_USER_AGENT = `conductor-app-sdk/${SDK_VERSION}`;
+
+// src/server/fetcher.ts
+var Fetcher = class {
+  constructor(options) {
+    this.options = options;
+    this.fetchImpl = options.fetch ?? globalThis.fetch;
+    if (typeof this.fetchImpl !== "function") {
+      throw new ConductorAppError({
+        code: "invalid_input",
+        message: "No fetch implementation found. Provide options.fetch (Node \u226518 has globalThis.fetch built in)."
+      });
+    }
+    this.defaultTimeoutMs = options.timeoutMs ?? 3e4;
+  }
+  options;
+  fetchImpl;
+  defaultTimeoutMs;
+  async request(req) {
+    const url = this.buildUrl(req.path, req.query);
+    const token = await this.resolveToken();
+    const headers = {
+      Authorization: `Bearer ${token}`,
+      Accept: "application/json",
+      "User-Agent": SDK_USER_AGENT,
+      ...req.headers ?? {}
+    };
+    const bodyType = req.bodyType ?? "json";
+    let body;
+    if (req.body !== void 0 && req.body !== null) {
+      if (bodyType === "json") {
+        headers["Content-Type"] ??= "application/json";
+        body = JSON.stringify(req.body);
+      } else {
+        body = req.body;
+      }
+    }
+    const timeoutMs = req.timeoutMs ?? this.defaultTimeoutMs;
+    const composedSignal = composeAbortSignals(req.signal, timeoutMs);
+    let response;
+    try {
+      response = await this.fetchImpl(url, {
+        method: req.method ?? "GET",
+        headers,
+        body,
+        signal: composedSignal.signal
+      });
+    } catch (cause) {
+      composedSignal.dispose();
+      if (isAbortError(cause)) {
+        throw new ConductorAppError({
+          code: composedSignal.timedOut ? "timeout" : "stream_aborted",
+          message: composedSignal.timedOut ? `Request timed out after ${timeoutMs}ms: ${req.method ?? "GET"} ${req.path}` : `Request aborted: ${req.method ?? "GET"} ${req.path}`,
+          cause
+        });
+      }
+      throw new ConductorAppError({
+        code: "network_error",
+        message: `Network error on ${req.method ?? "GET"} ${req.path}: ${cause?.message ?? String(cause)}`,
+        cause
+      });
+    }
+    composedSignal.dispose();
+    if (response.status === 401) {
+      try {
+        this.options.onUnauthorized?.();
+      } catch {
+      }
+    }
+    if (response.status === 404 && req.resolveOn404) {
+      return void 0;
+    }
+    if (!response.ok) {
+      const { details, message } = await readErrorBody(response);
+      const code = mapHttpStatusToErrorCode(response.status, details, message);
+      throw new ConductorAppError({
+        code,
+        status: response.status,
+        message: message || `Conductor returned ${response.status} on ${req.method ?? "GET"} ${req.path}`,
+        details,
+        requestId: response.headers.get("x-request-id") ?? void 0
+      });
+    }
+    if (response.status === 204) {
+      return void 0;
+    }
+    const text = await response.text();
+    if (!text) {
+      return void 0;
+    }
+    try {
+      return JSON.parse(text);
+    } catch (cause) {
+      throw new ConductorAppError({
+        code: "server_error",
+        message: `Conductor returned non-JSON body on ${req.method ?? "GET"} ${req.path}`,
+        details: { rawBody: text.slice(0, 1024) },
+        cause
+      });
+    }
+  }
+  buildUrl(path, query) {
+    const base = this.options.baseUrl.replace(/\/+$/, "");
+    const cleanPath = path.startsWith("/") ? path : `/${path}`;
+    const url = `${base}${cleanPath}`;
+    if (!query) return url;
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+      if (value === void 0 || value === null) continue;
+      params.append(key, String(value));
+    }
+    const queryString = params.toString();
+    return queryString ? `${url}?${queryString}` : url;
+  }
+  async resolveToken() {
+    const { bearerToken } = this.options;
+    if (typeof bearerToken === "string") return bearerToken;
+    const resolved = await bearerToken();
+    if (!resolved) {
+      throw new ConductorAppError({
+        code: "unauthorized",
+        message: "bearerToken provider returned empty string"
+      });
+    }
+    return resolved;
+  }
+};
+function composeAbortSignals(external, timeoutMs) {
+  const controller = new AbortController();
+  let timedOut = false;
+  let timer = null;
+  if (timeoutMs > 0) {
+    timer = setTimeout(() => {
+      timedOut = true;
+      controller.abort();
+    }, timeoutMs);
+  }
+  const onExternalAbort = () => controller.abort();
+  if (external) {
+    if (external.aborted) {
+      controller.abort();
+    } else {
+      external.addEventListener("abort", onExternalAbort);
+    }
+  }
+  const dispose = () => {
+    if (timer) clearTimeout(timer);
+    if (external) external.removeEventListener("abort", onExternalAbort);
+  };
+  return {
+    signal: controller.signal,
+    dispose,
+    get timedOut() {
+      return timedOut;
+    }
+  };
+}
+function isAbortError(error) {
+  if (typeof error !== "object" || error === null) return false;
+  const name = error.name;
+  return name === "AbortError";
+}
+async function readErrorBody(response) {
+  const text = await response.text().catch(() => "");
+  if (!text) return { details: null, message: null };
+  try {
+    const parsed = JSON.parse(text);
+    const message = typeof parsed.error === "string" ? parsed.error : typeof parsed.message === "string" ? parsed.message : null;
+    return { details: parsed, message };
+  } catch {
+    return { details: { rawBody: text.slice(0, 1024) }, message: null };
+  }
+}
+
+// src/server/normalize.ts
+var str = (value) => {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed || null;
+};
+var num = (value) => {
+  if (typeof value !== "number" || !Number.isFinite(value)) return null;
+  return value;
+};
+var bool = (value) => Boolean(value);
+var pick = (raw, ...keys) => {
+  for (const key of keys) {
+    if (Object.prototype.hasOwnProperty.call(raw, key)) return raw[key];
+  }
+  return void 0;
+};
+var isoDate = (value) => {
+  if (typeof value === "string") return value;
+  if (value instanceof Date) return value.toISOString();
+  return (/* @__PURE__ */ new Date(0)).toISOString();
+};
+function normalizeProject(raw) {
+  const r = raw ?? {};
+  const metadata = pick(r, "metadata") ?? null;
+  const ownership = metadata && typeof metadata === "object" ? metadata.ownership : void 0;
+  const audit = metadata && typeof metadata === "object" ? metadata.audit : void 0;
+  const createdByApp = Boolean(ownership && ownership.kind === "app") || Boolean(audit && audit.createdByApp);
+  return {
+    id: str(pick(r, "id")) ?? "",
+    name: str(pick(r, "name")) ?? "",
+    daemonHost: str(pick(r, "daemonHost", "daemon_host")),
+    workspacePath: str(pick(r, "workspacePath", "workspace_path")),
+    repoRoot: str(pick(r, "repoRoot", "repo_root")),
+    worktreeBranch: str(pick(r, "worktreeBranch", "worktree_branch")),
+    lastCommit: str(pick(r, "lastCommit", "last_commit")),
+    lastCommitAt: str(pick(r, "lastCommitAt", "last_commit_at")),
+    fileCount: num(pick(r, "fileCount", "file_count")),
+    isDefault: bool(pick(r, "isDefault", "is_default")),
+    createdByApp,
+    createdAt: isoDate(pick(r, "createdAt", "created_at")),
+    updatedAt: isoDate(pick(r, "updatedAt", "updated_at"))
+  };
+}
+function normalizeTask(raw) {
+  const r = raw ?? {};
+  return {
+    id: str(pick(r, "id")) ?? "",
+    projectId: str(pick(r, "projectId", "project_id")) ?? "",
+    title: str(pick(r, "title")) ?? "",
+    status: str(pick(r, "status")) ?? "pending",
+    backendType: str(pick(r, "backendType", "backend_type")),
+    sessionId: str(pick(r, "sessionId", "session_id")),
+    sessionFilePath: str(pick(r, "sessionFilePath", "session_file_path")),
+    createdAt: isoDate(pick(r, "createdAt", "created_at")),
+    updatedAt: isoDate(pick(r, "updatedAt", "updated_at"))
+  };
+}
+function normalizeMessage(raw) {
+  const r = raw ?? {};
+  const metadata = pick(r, "metadata");
+  const rawAttachments = pick(r, "attachments");
+  const attachments = Array.isArray(rawAttachments) ? rawAttachments.map((a) => normalizeAttachment(a)) : [];
+  return {
+    id: str(pick(r, "id")) ?? "",
+    taskId: str(pick(r, "taskId", "task_id")) ?? "",
+    role: str(pick(r, "role")) ?? "sdk",
+    content: typeof r.content === "string" ? r.content : "",
+    metadata: metadata && typeof metadata === "object" && !Array.isArray(metadata) ? metadata : null,
+    attachments,
+    createdAt: isoDate(pick(r, "createdAt", "created_at"))
+  };
+}
+function normalizeAttachment(raw) {
+  const r = raw ?? {};
+  return {
+    id: str(pick(r, "id")) ?? "",
+    filename: str(pick(r, "filename", "name")) ?? "",
+    mimeType: str(pick(r, "mimeType", "mime_type", "contentType", "content_type")) ?? "application/octet-stream",
+    sizeBytes: num(pick(r, "sizeBytes", "size_bytes", "size")) ?? 0,
+    url: str(pick(r, "url")) ?? ""
+  };
+}
+
+// src/server/http/projects.ts
+var ProjectsApi = class {
+  /** @internal — constructed by `AppClient`; not part of the public surface. */
+  constructor(fetcher) {
+    this.fetcher = fetcher;
+  }
+  fetcher;
+  /**
+   * Idempotent find-or-create on (daemonHost, workspacePath).
+   *
+   * Flow:
+   *   1. POST `/api/projects/match-path` with `{ daemonHost, path: workspacePath }`.
+   *      If a project matches (or is a parent of) the path, return it.
+   *   2. Otherwise POST `/api/projects` with binding fields. The server
+   *      validates the binding with the user's daemon. Success returns the
+   *      new project; daemon-offline returns 409 → mapped to `daemon_offline`.
+   *
+   * The created project carries `metadata.audit.createdByApp` so it can be
+   * distinguished in the main Conductor UI later. No new schema is required.
+   */
+  async bind(input, opts) {
+    const name = input.name?.trim();
+    const daemonHost = input.daemonHost?.trim();
+    const workspacePath = input.workspacePath?.trim();
+    if (!name || !daemonHost || !workspacePath) {
+      throw new ConductorAppError({
+        code: "invalid_input",
+        message: "projects.bind requires non-empty name, daemonHost, and workspacePath"
+      });
+    }
+    const match = await this.fetcher.request({
+      method: "POST",
+      path: "/api/projects/match-path",
+      body: { daemonHost, path: workspacePath },
+      signal: opts?.signal
+    });
+    if (match?.project) {
+      return normalizeProject(match.project);
+    }
+    const created = await this.fetcher.request({
+      method: "POST",
+      path: "/api/projects",
+      body: {
+        name,
+        daemonHost,
+        workspacePath,
+        metadata: {
+          audit: {
+            createdByApp: {
+              name: input.appLabel ?? name,
+              sdkName: SDK_NAME,
+              sdkVersion: SDK_VERSION
+            }
+          }
+        }
+      },
+      signal: opts?.signal
+    });
+    return normalizeProject(created);
+  }
+  async list(opts) {
+    const raw = await this.fetcher.request({
+      method: "GET",
+      path: "/api/projects",
+      signal: opts?.signal
+    });
+    const list = Array.isArray(raw) ? raw : Array.isArray(raw.projects) ? raw.projects : [];
+    return list.map((entry) => normalizeProject(entry));
+  }
+  async get(projectId, opts) {
+    if (!projectId) {
+      throw new ConductorAppError({
+        code: "invalid_input",
+        message: "projects.get requires a projectId"
+      });
+    }
+    const raw = await this.fetcher.request({
+      method: "GET",
+      path: "/api/projects",
+      query: { projectId },
+      signal: opts?.signal
+    });
+    if (raw && typeof raw === "object" && "projects" in raw) {
+      const list = raw.projects ?? [];
+      if (list.length === 0) {
+        throw new ConductorAppError({
+          code: "project_not_found",
+          message: `Project ${projectId} not found`
+        });
+      }
+      return normalizeProject(list[0]);
+    }
+    return normalizeProject(raw);
+  }
+};
+
+// src/server/id.ts
+function generateRequestId() {
+  const c = globalThis.crypto;
+  if (c?.randomUUID) return c.randomUUID();
+  if (c?.getRandomValues) {
+    const bytes = new Uint8Array(16);
+    c.getRandomValues(bytes);
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+  }
+  return Math.random().toString(36).slice(2) + Date.now().toString(36);
+}
+
+// src/server/http/tasks.ts
+var TasksRestApi = class {
+  constructor(fetcher) {
+    this.fetcher = fetcher;
+  }
+  fetcher;
+  async create(input, opts) {
+    if (!input.projectId) {
+      throw new ConductorAppError({
+        code: "invalid_input",
+        message: "tasks.create requires projectId"
+      });
+    }
+    const trimmedTitle = input.title?.trim() ?? "";
+    if (!trimmedTitle) {
+      throw new ConductorAppError({
+        code: "invalid_input",
+        message: "tasks.create requires title"
+      });
+    }
+    const raw = await this.fetcher.request({
+      method: "POST",
+      path: "/api/tasks",
+      body: {
+        project_id: input.projectId,
+        title: trimmedTitle,
+        ...input.initialMessage ? { initial_content: input.initialMessage } : {},
+        ...input.backendType ? { backend_type: input.backendType } : {},
+        ...input.metadata ? { metadata: input.metadata } : {},
+        task_type: "ai_task"
+      },
+      signal: opts?.signal
+    });
+    return normalizeTask(raw);
+  }
+  async get(taskId, opts) {
+    if (!taskId) {
+      throw new ConductorAppError({
+        code: "invalid_input",
+        message: "tasks.get requires a taskId"
+      });
+    }
+    const raw = await this.fetcher.request({
+      method: "GET",
+      path: `/api/tasks/${encodeURIComponent(taskId)}`,
+      signal: opts?.signal
+    });
+    return normalizeTask(raw);
+  }
+  async list(filter = {}, opts) {
+    const raw = await this.fetcher.request({
+      method: "GET",
+      path: "/api/tasks",
+      query: {
+        ...filter.projectId ? { project_id: filter.projectId } : {},
+        ...filter.status ? { status: filter.status } : {}
+      },
+      signal: opts?.signal
+    });
+    const list = Array.isArray(raw) ? raw : Array.isArray(raw.tasks) ? raw.tasks : [];
+    return list.map((entry) => normalizeTask(entry));
+  }
+  async sendMessage(taskId, input, opts) {
+    if (!taskId) {
+      throw new ConductorAppError({
+        code: "invalid_input",
+        message: "tasks.sendMessage requires a taskId"
+      });
+    }
+    const normalized = typeof input === "string" ? { content: input } : input;
+    if (!normalized.content || !normalized.content.trim()) {
+      throw new ConductorAppError({
+        code: "invalid_input",
+        message: "tasks.sendMessage requires non-empty content"
+      });
+    }
+    const clientRequestId = normalized.clientRequestId ?? generateRequestId();
+    const raw = await this.fetcher.request({
+      method: "POST",
+      path: `/api/tasks/${encodeURIComponent(taskId)}/messages`,
+      body: {
+        content: normalized.content,
+        role: normalized.role ?? "sdk",
+        clientRequestId,
+        metadata: buildOutboundMetadata(normalized.metadata)
+      },
+      signal: opts?.signal
+    });
+    return normalizeMessage(raw);
+  }
+  /**
+   * Paginated history of messages for a task. Returns newest page first
+   * (most recent messages have largest createdAt).
+   */
+  async history(taskId, paging = {}, opts) {
+    if (!taskId) {
+      throw new ConductorAppError({
+        code: "invalid_input",
+        message: "tasks.history requires a taskId"
+      });
+    }
+    const raw = await this.fetcher.request({
+      method: "GET",
+      path: `/api/tasks/${encodeURIComponent(taskId)}/messages`,
+      query: {
+        pagination: "1",
+        ...paging.beforeId ? { before_id: paging.beforeId } : {},
+        ...paging.limit ? { limit: String(paging.limit) } : {}
+      },
+      signal: opts?.signal
+    });
+    if (!raw || typeof raw !== "object") {
+      return { messages: [], hasMoreBefore: false, oldestMessageId: null };
+    }
+    const messages = Array.isArray(raw.messages) ? raw.messages.map((entry) => normalizeMessage(entry)) : [];
+    const pagination = raw.pagination ?? {};
+    return {
+      messages,
+      hasMoreBefore: Boolean(pagination.has_more_before),
+      oldestMessageId: typeof pagination.oldest_message_id === "string" ? pagination.oldest_message_id : null
+    };
+  }
+  async interrupt(taskId, opts) {
+    if (!taskId) {
+      throw new ConductorAppError({
+        code: "invalid_input",
+        message: "tasks.interrupt requires a taskId"
+      });
+    }
+    if (!opts.targetReplyTo) {
+      throw new ConductorAppError({
+        code: "invalid_input",
+        message: "tasks.interrupt requires targetReplyTo"
+      });
+    }
+    await this.fetcher.request({
+      method: "POST",
+      path: `/api/tasks/${encodeURIComponent(taskId)}/interrupt`,
+      body: { target_reply_to: opts.targetReplyTo },
+      signal: opts.signal
+    });
+  }
+};
+function buildOutboundMetadata(callerMetadata) {
+  const base = callerMetadata && typeof callerMetadata === "object" ? { ...callerMetadata } : {};
+  const callerAudit = base.audit && typeof base.audit === "object" && !Array.isArray(base.audit) ? { ...base.audit } : {};
+  delete callerAudit.actor;
+  delete callerAudit.sdkName;
+  delete callerAudit.sdkVersion;
+  return {
+    ...base,
+    audit: {
+      // Caller-supplied audit fields first…
+      ...callerAudit,
+      // …then SDK fields LAST so they always win.
+      actor: "app",
+      sdkName: SDK_NAME,
+      sdkVersion: SDK_VERSION
+    }
+  };
+}
+
+// src/server/ws/socket.ts
+import WebSocket from "ws";
+var AppWebSocket = class {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  socket = null;
+  reconnectAttempts = 0;
+  closed = false;
+  reconnectTimer = null;
+  rawListeners = /* @__PURE__ */ new Set();
+  stateListeners = /* @__PURE__ */ new Set();
+  closeListeners = /* @__PURE__ */ new Set();
+  currentState = "offline";
+  /** Resolved when at least one connection has opened successfully. */
+  readyPromise = null;
+  readyResolver = null;
+  readyRejector = null;
+  /** Tracks whether we've ever opened a connection — gates state replay. */
+  hasEverConnected = false;
+  onEnvelope(listener) {
+    this.rawListeners.add(listener);
+    return {
+      unsubscribe: () => {
+        this.rawListeners.delete(listener);
+      }
+    };
+  }
+  /**
+   * Subscribe to the terminal "client closed" event. Fires exactly once when
+   * `close()` is invoked (or zero times if the socket is GC'd without close).
+   *
+   * Iterators that have already passed `connect()` need this signal — the
+   * regular `rawListeners` are cleared at close time, so the inner
+   * `subscribeToTask` loop would otherwise wedge waiting on `next()`. Late
+   * subscribers (after `close()` has run) get fired synchronously so they
+   * can't miss the signal.
+   *
+   * Returns an unsubscribe callback. Idempotent.
+   */
+  onClose(listener) {
+    if (this.closed) {
+      try {
+        listener();
+      } catch {
+      }
+      return () => void 0;
+    }
+    this.closeListeners.add(listener);
+    return () => {
+      this.closeListeners.delete(listener);
+    };
+  }
+  onConnectionState(listener) {
+    if (this.hasEverConnected || this.currentState !== "offline") {
+      try {
+        listener(this.currentState);
+      } catch {
+      }
+    }
+    this.stateListeners.add(listener);
+    return {
+      unsubscribe: () => {
+        this.stateListeners.delete(listener);
+      }
+    };
+  }
+  /**
+   * Open the connection (idempotent). Returns when the first OPEN event fires.
+   *
+   * The returned promise rejects only if the *initial* connection attempt
+   * fails (e.g. the token provider throws). Once we've ever connected, the
+   * promise resolves and subsequent disconnects are handled by the
+   * auto-reconnect loop (visible via `onConnectionState`).
+   */
+  async connect() {
+    if (this.closed) {
+      throw new ConductorAppError({
+        code: "subscribe_failed",
+        message: "AppWebSocket was closed; create a new one."
+      });
+    }
+    if (this.socket && this.socket.readyState === WebSocket.OPEN) return;
+    if (this.readyPromise) return this.readyPromise;
+    const readyPromise = new Promise((resolve, reject) => {
+      this.readyResolver = resolve;
+      this.readyRejector = reject;
+    });
+    readyPromise.catch(() => void 0);
+    this.readyPromise = readyPromise;
+    try {
+      await this.openOnce();
+    } catch (cause) {
+      const rejector = this.readyRejector;
+      this.readyPromise = null;
+      this.readyResolver = null;
+      this.readyRejector = null;
+      const error = cause instanceof ConductorAppError ? cause : new ConductorAppError({
+        code: "subscribe_failed",
+        message: `Failed to open WebSocket: ${cause?.message ?? String(cause)}`,
+        cause
+      });
+      if (rejector) rejector(error);
+      throw error;
+    }
+    return readyPromise;
+  }
+  close() {
+    if (this.closed) return;
+    const pendingRejector = this.readyRejector;
+    const closeListenersSnapshot = Array.from(this.closeListeners);
+    this.closed = true;
+    this.rawListeners.clear();
+    this.stateListeners.clear();
+    this.closeListeners.clear();
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.socket) {
+      try {
+        this.socket.close();
+      } catch {
+      }
+    }
+    this.socket = null;
+    this.readyPromise = null;
+    this.readyResolver = null;
+    this.readyRejector = null;
+    this.setState("offline");
+    if (pendingRejector) {
+      pendingRejector(
+        new ConductorAppError({
+          code: "subscribe_failed",
+          message: "client closed before connect resolved"
+        })
+      );
+    }
+    for (const listener of closeListenersSnapshot) {
+      try {
+        listener();
+      } catch {
+      }
+    }
+  }
+  async openOnce() {
+    const url = await this.buildUrl();
+    const Ctor = this.options.webSocketImpl ?? WebSocket;
+    const socket = new Ctor(url);
+    this.socket = socket;
+    socket.addEventListener("open", this.handleOpen);
+    socket.addEventListener("message", this.handleMessage);
+    socket.addEventListener("close", this.handleClose);
+    socket.addEventListener("error", this.handleError);
+  }
+  handleOpen = () => {
+    this.reconnectAttempts = 0;
+    this.hasEverConnected = true;
+    this.setState("connected");
+    if (this.readyResolver) {
+      this.readyResolver();
+      this.readyResolver = null;
+      this.readyRejector = null;
+    }
+  };
+  handleMessage = (event) => {
+    const data = event.data;
+    let text;
+    if (typeof data === "string") {
+      text = data;
+    } else if (data instanceof Buffer) {
+      text = data.toString("utf8");
+    } else if (data instanceof ArrayBuffer) {
+      text = new TextDecoder().decode(data);
+    } else {
+      return;
+    }
+    let envelope;
+    try {
+      envelope = JSON.parse(text);
+    } catch {
+      return;
+    }
+    for (const listener of this.rawListeners) {
+      try {
+        listener(envelope);
+      } catch {
+      }
+    }
+  };
+  handleClose = () => {
+    this.socket = null;
+    if (this.closed) return;
+    const pendingRejector = this.readyRejector;
+    this.readyPromise = null;
+    this.readyResolver = null;
+    this.readyRejector = null;
+    if (pendingRejector) {
+      pendingRejector(
+        new ConductorAppError({
+          code: "subscribe_failed",
+          message: "socket closed before open"
+        })
+      );
+    }
+    this.scheduleReconnect();
+  };
+  handleError = () => {
+  };
+  scheduleReconnect() {
+    const max = this.options.maxReconnects ?? Number.POSITIVE_INFINITY;
+    if (this.reconnectAttempts >= max) {
+      this.setState("offline");
+      this.closed = true;
+      return;
+    }
+    this.setState("reconnecting");
+    const backoff = computeBackoff(
+      this.reconnectAttempts,
+      this.options.initialBackoffMs ?? 250,
+      this.options.maxBackoffMs ?? 3e4
+    );
+    this.reconnectAttempts += 1;
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      if (this.closed) return;
+      void this.openOnce().catch(() => this.scheduleReconnect());
+    }, backoff);
+  }
+  setState(state) {
+    if (this.currentState === state) return;
+    this.currentState = state;
+    for (const listener of this.stateListeners) {
+      try {
+        listener(state);
+      } catch {
+      }
+    }
+  }
+  async buildUrl() {
+    const token = typeof this.options.bearerToken === "string" ? this.options.bearerToken : await this.options.bearerToken();
+    const parsed = new URL(this.options.baseUrl);
+    parsed.protocol = parsed.protocol === "https:" ? "wss:" : "ws:";
+    const pathname = parsed.pathname.replace(/\/+$/, "");
+    parsed.pathname = `${pathname}/ws/app`;
+    parsed.search = `?token=${encodeURIComponent(token)}`;
+    return parsed.toString();
+  }
+};
+function computeBackoff(attempt, initial, max) {
+  const exp = Math.min(initial * 2 ** attempt, max);
+  const jittered = Math.floor(Math.random() * exp);
+  const floor = Math.floor(initial / 2);
+  return Math.max(jittered, floor);
+}
+
+// src/server/ws/envelope.ts
+function envelopeToChatEvent(raw, filterTaskId) {
+  if (!raw || typeof raw !== "object") return null;
+  const envelope = raw;
+  const type = envelope.type;
+  const payload = envelope.payload ?? {};
+  const taskId = readString(payload.task_id ?? payload.taskId);
+  if (filterTaskId && taskId !== filterTaskId) {
+    return null;
+  }
+  switch (type) {
+    case "task_user_message":
+    case "task_sdk_message": {
+      const message = normalizeMessage({ ...payload, taskId });
+      if (!message.id) return null;
+      return { type: "message_appended", message };
+    }
+    case "task_status_update": {
+      if (!taskId) return null;
+      const status = readString(payload.status);
+      if (status === "finished" || status === "completed" || status === "done") {
+        return { type: "task_finished", taskId };
+      }
+      if (status === "failed" || status === "errored") {
+        return {
+          type: "task_failed",
+          taskId,
+          error: {
+            code: "task_failed",
+            message: readString(payload.summary) ?? "Task failed"
+          }
+        };
+      }
+      return null;
+    }
+    case "task_runtime_status": {
+      if (!taskId) return null;
+      const status = {
+        taskId,
+        state: readString(payload.state) ?? "idle",
+        phase: readString(payload.phase),
+        source: readString(payload.source),
+        statusLine: readString(payload.status_line ?? payload.statusLine),
+        statusDoneLine: readString(payload.status_done_line ?? payload.statusDoneLine),
+        replyPreview: readString(payload.reply_preview ?? payload.replyPreview),
+        replyTo: readString(payload.reply_to ?? payload.replyTo),
+        replyInProgress: readBool(payload.reply_in_progress ?? payload.replyInProgress),
+        backend: readString(payload.backend),
+        threadId: readString(payload.thread_id ?? payload.threadId),
+        daemon: readString(payload.daemon),
+        pid: readNumber(payload.pid),
+        sessionId: readString(payload.session_id ?? payload.sessionId),
+        sessionFilePath: readString(payload.session_file_path ?? payload.sessionFilePath),
+        tokenUsagePercent: readNumber(payload.token_usage_percent ?? payload.tokenUsagePercent),
+        contextUsagePercent: readNumber(payload.context_usage_percent ?? payload.contextUsagePercent),
+        createdAt: readString(payload.created_at ?? payload.createdAt)
+      };
+      return { type: "runtime_status", status };
+    }
+    default:
+      if (typeof process !== "undefined" && process.env && process.env.NODE_ENV === "development") {
+        console.warn(
+          `[app-sdk] envelopeToChatEvent: unknown envelope type "${type ?? ""}" (dropped)`
+        );
+      }
+      return null;
+  }
+}
+function readString(value) {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed || null;
+}
+function readNumber(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return null;
+  return value;
+}
+function readBool(value) {
+  if (typeof value === "boolean") return value;
+  return void 0;
+}
+
+// src/server/tasks/subscribe.ts
+function subscribeToTask(socket, taskId, opts) {
+  const bufferCap = opts?.bufferCap ?? 1024;
+  return {
+    [Symbol.asyncIterator]() {
+      const queue = [];
+      let pendingResolver = null;
+      let done = false;
+      const drain = () => {
+        if (!pendingResolver) return;
+        if (queue.length > 0) {
+          const value = queue.shift();
+          const resolver = pendingResolver;
+          pendingResolver = null;
+          resolver.resolve({ value, done: false });
+          return;
+        }
+        if (done) {
+          const resolver = pendingResolver;
+          pendingResolver = null;
+          resolver.resolve({ value: void 0, done: true });
+        }
+      };
+      const evictForCap = () => {
+        while (queue.length > bufferCap) {
+          const idx = queue.findIndex((e) => e.type === "runtime_status");
+          if (idx >= 0) {
+            queue.splice(idx, 1);
+          } else {
+            queue.shift();
+          }
+        }
+      };
+      const envelopeSub = socket.onEnvelope((envelope) => {
+        if (done) return;
+        const event = envelopeToChatEvent(envelope, taskId);
+        if (!event) return;
+        queue.push(event);
+        evictForCap();
+        drain();
+      });
+      const stateSub = socket.onConnectionState((state) => {
+        if (done) return;
+        queue.push({ type: "connection_state", state });
+        evictForCap();
+        drain();
+      });
+      const closeUnsub = socket.onClose(() => {
+        if (done) return;
+        queue.push({
+          type: "task_failed",
+          taskId,
+          error: {
+            code: "subscribe_failed",
+            message: "client closed"
+          }
+        });
+        evictForCap();
+        drain();
+        finish();
+      });
+      const onAbort = () => finish();
+      const finish = () => {
+        if (done) return;
+        done = true;
+        envelopeSub.unsubscribe();
+        stateSub.unsubscribe();
+        closeUnsub();
+        if (opts?.signal) {
+          opts.signal.removeEventListener("abort", onAbort);
+        }
+        drain();
+      };
+      if (opts?.signal) {
+        if (opts.signal.aborted) {
+          finish();
+        } else {
+          opts.signal.addEventListener("abort", onAbort, { once: true });
+        }
+      }
+      return {
+        next() {
+          if (queue.length > 0) {
+            const value = queue.shift();
+            return Promise.resolve({ value, done: false });
+          }
+          if (done) {
+            return Promise.resolve({ value: void 0, done: true });
+          }
+          return new Promise((resolve) => {
+            pendingResolver = { resolve };
+          });
+        },
+        return() {
+          finish();
+          return Promise.resolve({ value: void 0, done: true });
+        }
+      };
+    }
+  };
+}
+
+// src/server/tasks/stream-reply.ts
+function isAppOriginEcho(metadata) {
+  if (!metadata || typeof metadata !== "object") return false;
+  const audit = metadata.audit;
+  if (!audit || typeof audit !== "object") return false;
+  return audit.actor === "app";
+}
+function isSyntheticSystemMessage(metadata) {
+  if (!metadata || typeof metadata !== "object") return false;
+  return metadata.synthetic === true;
+}
+function streamReplyForTask(socket, taskId, opts) {
+  const emitInitial = opts?.emitInitialPreview ?? true;
+  const idleTimeoutMs = opts?.idleTimeoutMs ?? 12e4;
+  return {
+    async *[Symbol.asyncIterator]() {
+      let lastPreview = "";
+      let lastStatusState = null;
+      let bootstrapped = !emitInitial;
+      let currentReplyTo = null;
+      const idleController = new AbortController();
+      let idleTimer = null;
+      let idleFired = false;
+      const armIdle = () => {
+        if (idleTimeoutMs <= 0) return;
+        if (idleTimer) clearTimeout(idleTimer);
+        idleTimer = setTimeout(() => {
+          idleFired = true;
+          idleController.abort();
+        }, idleTimeoutMs);
+      };
+      const disarmIdle = () => {
+        if (idleTimer) {
+          clearTimeout(idleTimer);
+          idleTimer = null;
+        }
+      };
+      let composedSignal;
+      const externalSignal = opts?.signal;
+      const onExternalAbort = () => idleController.abort();
+      if (externalSignal && externalSignal.aborted) {
+        composedSignal = externalSignal;
+      } else if (externalSignal) {
+        externalSignal.addEventListener("abort", onExternalAbort, { once: true });
+        composedSignal = idleController.signal;
+      } else {
+        composedSignal = idleController.signal;
+      }
+      armIdle();
+      try {
+        for await (const event of subscribeToTask(socket, taskId, {
+          signal: composedSignal
+        })) {
+          if (event.type === "runtime_status") {
+            const status = event.status;
+            const replyTo = status.replyTo ?? currentReplyTo ?? "";
+            if (status.replyTo) currentReplyTo = status.replyTo;
+            const preview = status.replyPreview ?? "";
+            const previewAdvanced = preview !== "" && preview !== lastPreview;
+            if (previewAdvanced) {
+              const isContinuation = preview.startsWith(lastPreview);
+              yield {
+                type: "text",
+                text: bootstrapped && isContinuation ? preview.slice(lastPreview.length) : preview,
+                replyTo
+              };
+              lastPreview = preview;
+              bootstrapped = true;
+            }
+            yield { type: "status", status };
+            const stateChanged = status.state !== lastStatusState;
+            if (previewAdvanced || stateChanged) {
+              armIdle();
+              lastStatusState = status.state;
+            }
+            continue;
+          }
+          if (event.type === "message_appended") {
+            const message = event.message;
+            if (message.role === "user") {
+              continue;
+            }
+            if (isAppOriginEcho(message.metadata)) {
+              continue;
+            }
+            if (isSyntheticSystemMessage(message.metadata)) {
+              continue;
+            }
+            yield { type: "done", message };
+            return;
+          }
+          if (event.type === "task_failed") {
+            yield { type: "error", error: event.error };
+            return;
+          }
+          if (event.type === "task_finished") {
+            yield {
+              type: "error",
+              error: {
+                code: "task_not_running",
+                message: "task finished without reply"
+              }
+            };
+            return;
+          }
+        }
+        if (idleFired) {
+          yield {
+            type: "error",
+            error: {
+              code: "stream_aborted",
+              message: "idle timeout"
+            }
+          };
+        }
+      } finally {
+        disarmIdle();
+        if (externalSignal && !externalSignal.aborted) {
+          externalSignal.removeEventListener("abort", onExternalAbort);
+        }
+      }
+    }
+  };
+}
+
+// src/server/client.ts
+var AppClient = class {
+  projects;
+  tasks;
+  _fetcher;
+  _socket = null;
+  _closed = false;
+  options;
+  constructor(options) {
+    validateOptions(options);
+    this.options = options;
+    this._fetcher = new Fetcher({
+      baseUrl: options.baseUrl,
+      bearerToken: options.bearerToken,
+      fetch: options.fetch,
+      timeoutMs: options.timeoutMs,
+      onUnauthorized: options.onUnauthorized
+    });
+    this.projects = new ProjectsApi(this._fetcher);
+    const rest = new TasksRestApi(this._fetcher);
+    this.tasks = new TasksApi(
+      rest,
+      () => this.getOrCreateSocket(),
+      () => this._closed
+    );
+  }
+  /**
+   * Release the WS connection and mark the client closed. Idempotent —
+   * calling twice is a no-op rather than a NPE. After close, any new
+   * `tasks.subscribe()` / `tasks.streamReply()` / `tasks.*` REST call
+   * throws synchronously instead of returning a hanging iterator.
+   */
+  async close() {
+    if (this._closed) return;
+    this._closed = true;
+    if (this._socket) {
+      this._socket.close();
+      this._socket = null;
+    }
+  }
+  getOrCreateSocket() {
+    if (this._socket) return this._socket;
+    this._socket = new AppWebSocket({
+      baseUrl: this.options.baseUrl,
+      bearerToken: this.options.bearerToken,
+      webSocketImpl: this.options.webSocketImpl
+    });
+    return this._socket;
+  }
+};
+async function connect(options) {
+  return new AppClient(options);
+}
+var TasksApi = class {
+  /** @internal — constructed by `AppClient`; not part of the public surface. */
+  constructor(rest, getSocket, isClosed = () => false) {
+    this.rest = rest;
+    this.getSocket = getSocket;
+    this.isClosed = isClosed;
+  }
+  rest;
+  getSocket;
+  isClosed;
+  assertOpen() {
+    if (this.isClosed()) {
+      throw new ConductorAppError({
+        code: "subscribe_failed",
+        message: "client is closed"
+      });
+    }
+  }
+  create(input, opts) {
+    this.assertOpen();
+    return this.rest.create(input, opts);
+  }
+  get(taskId, opts) {
+    this.assertOpen();
+    return this.rest.get(taskId, opts);
+  }
+  list(filter, opts) {
+    this.assertOpen();
+    return this.rest.list(filter, opts);
+  }
+  sendMessage(taskId, input, opts) {
+    this.assertOpen();
+    return this.rest.sendMessage(taskId, input, opts);
+  }
+  history(taskId, paging, opts) {
+    this.assertOpen();
+    return this.rest.history(taskId, paging, opts);
+  }
+  interrupt(taskId, opts) {
+    this.assertOpen();
+    return this.rest.interrupt(taskId, opts);
+  }
+  /**
+   * Subscribe to a task's event stream. Yields ChatEvents until the caller
+   * breaks out of the `for await` loop, calls `signal.abort()`, or the
+   * client is closed.
+   *
+   * The first call lazily opens a /ws/app connection; subsequent calls share
+   * the same connection.
+   */
+  subscribe(taskId, opts) {
+    if (!taskId) {
+      throw new ConductorAppError({
+        code: "invalid_input",
+        message: "tasks.subscribe requires a taskId"
+      });
+    }
+    this.assertOpen();
+    const socket = this.getSocket();
+    const inner = subscribeToTask(socket, taskId, opts);
+    return {
+      [Symbol.asyncIterator]() {
+        const innerIter = inner[Symbol.asyncIterator]();
+        const connectPromise = socket.connect().then(
+          () => null,
+          (err) => err
+        );
+        let connectChecked = false;
+        return {
+          async next() {
+            if (!connectChecked) {
+              connectChecked = true;
+              const err = await connectPromise;
+              if (err) {
+                try {
+                  await innerIter.return?.();
+                } catch {
+                }
+                const event = {
+                  type: "task_failed",
+                  taskId,
+                  error: errorToChatError(err, "subscribe_failed")
+                };
+                return { value: event, done: false };
+              }
+            }
+            return innerIter.next();
+          },
+          async return() {
+            return await innerIter.return?.() ?? { value: void 0, done: true };
+          }
+        };
+      }
+    };
+  }
+  /**
+   * Higher-level convenience: yield only AI reply deltas. Internally consumes
+   * `subscribe()` and selects runtime_status preview chunks + the final
+   * assistant message.
+   */
+  streamReply(taskId, opts) {
+    if (!taskId) {
+      throw new ConductorAppError({
+        code: "invalid_input",
+        message: "tasks.streamReply requires a taskId"
+      });
+    }
+    this.assertOpen();
+    const socket = this.getSocket();
+    const inner = streamReplyForTask(socket, taskId, opts);
+    return {
+      [Symbol.asyncIterator]() {
+        const innerIter = inner[Symbol.asyncIterator]();
+        const connectPromise = socket.connect().then(
+          () => null,
+          (err) => err
+        );
+        let connectChecked = false;
+        return {
+          async next() {
+            if (!connectChecked) {
+              connectChecked = true;
+              const err = await connectPromise;
+              if (err) {
+                try {
+                  await innerIter.return?.();
+                } catch {
+                }
+                const delta = {
+                  type: "error",
+                  error: errorToChatError(err, "stream_aborted")
+                };
+                return { value: delta, done: false };
+              }
+            }
+            return innerIter.next();
+          },
+          async return() {
+            return await innerIter.return?.() ?? { value: void 0, done: true };
+          }
+        };
+      }
+    };
+  }
+};
+function errorToChatError(err, defaultCode = "subscribe_failed") {
+  if (err && typeof err === "object") {
+    const code = String(err.code ?? defaultCode);
+    const message = String(
+      err.message ?? "WebSocket connection failed"
+    );
+    const detailsRaw = err.details;
+    const result = {
+      code,
+      message
+    };
+    if (detailsRaw !== void 0) result.details = detailsRaw;
+    if (err instanceof Error) result.cause = err;
+    return result;
+  }
+  return { code: defaultCode, message: String(err) };
+}
+function validateOptions(options) {
+  if (!options.baseUrl) {
+    throw new ConductorAppError({
+      code: "invalid_input",
+      message: "connect(): baseUrl is required"
+    });
+  }
+  if (!options.bearerToken) {
+    throw new ConductorAppError({
+      code: "invalid_input",
+      message: "connect(): bearerToken is required"
+    });
+  }
+}
+export {
+  AppClient,
+  ConductorAppError,
+  connect,
+  isConductorAppError
+};