@clawrent/provider 0.1.0

package/dist/index.js

@@ -0,0 +1,881 @@
+// src/api-client.ts
+var ApiClient = class {
+  config;
+  /** When set (e.g. by ProviderAgent.start), overrides config.token for REST auth. */
+  agentTokenOverride = null;
+  constructor(config) {
+    this.config = config;
+  }
+  /**
+   * Set a token that overrides config.token for subsequent REST requests.
+   * Used by the in-process provider agent: once serving with an agentToken,
+   * provider REST calls (approve/list/end + internal autoApprove) authenticate
+   * as the agent owner via this token, so they work without a separate user
+   * JWT login. The backend's resolveAuth accepts the agt_clawrent_* prefix.
+   * Pass null to clear (e.g. on stop_serving).
+   */
+  setAgentToken(token) {
+    this.agentTokenOverride = token;
+  }
+  get apiUrl() {
+    return this.config.apiUrl;
+  }
+  get wsUrl() {
+    return this.config.wsUrl;
+  }
+  get userId() {
+    return this.config.userId;
+  }
+  // --- Auth (no auth needed) ---
+  async sendVerification(email) {
+    return this.request("POST", "/api/auth/send-verification", { email }, false);
+  }
+  async registerUser(input) {
+    return this.request("POST", "/api/auth/register", input, false);
+  }
+  async login(email, password) {
+    return this.request("POST", "/api/auth/login", { email, password }, false);
+  }
+  async getMe() {
+    return this.request("GET", "/api/auth/me");
+  }
+  // --- Marketplace ---
+  async browse(query) {
+    const params = new URLSearchParams();
+    if (query?.search) params.set("search", query.search);
+    if (query?.category) params.set("category", query.category);
+    if (query?.page) params.set("page", String(query.page));
+    if (query?.limit) params.set("limit", String(query.limit));
+    const qs = params.toString();
+    return this.request("GET", `/api/marketplace/browse${qs ? `?${qs}` : ""}`);
+  }
+  async getAgent(slug) {
+    return this.request("GET", `/api/marketplace/agents/${encodeURIComponent(slug)}`);
+  }
+  // --- Sessions ---
+  async rent(options) {
+    return this.request("POST", "/api/sessions", {
+      agentId: options.agentId,
+      taskDescription: options.taskDescription,
+      grantedPermissions: options.grantedPermissions ?? {}
+    });
+  }
+  async getSessions(query) {
+    const params = new URLSearchParams();
+    if (query?.role) params.set("role", query.role);
+    if (query?.status) params.set("status", query.status);
+    if (query?.page) params.set("page", String(query.page));
+    if (query?.limit) params.set("limit", String(query.limit));
+    const qs = params.toString();
+    return this.request("GET", `/api/sessions${qs ? `?${qs}` : ""}`);
+  }
+  async getSession(sessionId) {
+    return this.request("GET", `/api/sessions/${encodeURIComponent(sessionId)}`);
+  }
+  async getSessionMessages(sessionId, options) {
+    const params = new URLSearchParams();
+    if (options?.since) params.set("since", options.since);
+    if (options?.limit) params.set("limit", String(options.limit));
+    const qs = params.toString();
+    return this.request(
+      "GET",
+      `/api/sessions/${encodeURIComponent(sessionId)}/messages${qs ? `?${qs}` : ""}`
+    );
+  }
+  /** POST a message via REST (WS fallback, e.g. session not attached after restart). */
+  async sendSessionMessage(sessionId, body) {
+    return this.request(
+      "POST",
+      `/api/sessions/${encodeURIComponent(sessionId)}/messages`,
+      body
+    );
+  }
+  async endSession(sessionId) {
+    return this.request("POST", `/api/sessions/${encodeURIComponent(sessionId)}/end`);
+  }
+  async approveSession(sessionId) {
+    return this.request("POST", `/api/sessions/${encodeURIComponent(sessionId)}/approve`);
+  }
+  // --- Billing ---
+  async getBalance() {
+    return this.request("GET", "/api/billing/wallet");
+  }
+  async topUp(amount) {
+    return this.request("POST", "/api/billing/wallet/topup", { amount });
+  }
+  // --- Provider: Agents ---
+  async registerAgent(data) {
+    return this.request("POST", "/api/agents", data);
+  }
+  async getMyAgents(query) {
+    const params = new URLSearchParams();
+    if (query?.page) params.set("page", String(query.page));
+    if (query?.limit) params.set("limit", String(query.limit));
+    if (query?.roles) params.set("roles", query.roles);
+    const qs = params.toString();
+    return this.request("GET", `/api/agents/my${qs ? `?${qs}` : ""}`);
+  }
+  /** Resolve the current agent from agentToken. Requires agt_clawrent_ token auth. */
+  async getMyAgent() {
+    return this.request("GET", "/api/agents/me/agent");
+  }
+  async applyProvider(agentId, data) {
+    return this.request("POST", `/api/agents/${encodeURIComponent(agentId)}/apply-provider`, data);
+  }
+  /** Publish agent — simplified apply-provider with defaults, submits for admin review */
+  async publishAgent(agentId, data) {
+    return this.request("POST", `/api/agents/${encodeURIComponent(agentId)}/publish`, data ?? {});
+  }
+  /** Activate agent — verify admin-approved + WebSocket connected, then go online */
+  async activateAgent(agentId) {
+    return this.request("POST", `/api/agents/${encodeURIComponent(agentId)}/activate`);
+  }
+  async setOnlineStatus(agentId, onlineStatus) {
+    return this.request("PATCH", `/api/agents/${encodeURIComponent(agentId)}/status`, { onlineStatus });
+  }
+  async generateAgentToken(agentId) {
+    return this.request("POST", `/api/agents/${encodeURIComponent(agentId)}/token`);
+  }
+  async revokeAgentToken(agentId) {
+    return this.request("DELETE", `/api/agents/${encodeURIComponent(agentId)}/token`);
+  }
+  // --- Orders ---
+  async createOrder(data) {
+    return this.request("POST", "/api/orders", data);
+  }
+  async getOrders(query) {
+    const params = new URLSearchParams();
+    if (query?.status) params.set("status", query.status);
+    if (query?.page) params.set("page", String(query.page));
+    if (query?.limit) params.set("limit", String(query.limit));
+    const qs = params.toString();
+    return this.request("GET", `/api/orders${qs ? `?${qs}` : ""}`);
+  }
+  async getOrder(orderId) {
+    return this.request("GET", `/api/orders/${encodeURIComponent(orderId)}`);
+  }
+  async cancelOrder(orderId) {
+    return this.request("POST", `/api/orders/${encodeURIComponent(orderId)}/cancel`);
+  }
+  // --- Cart ---
+  async getCart() {
+    return this.request("GET", "/api/cart");
+  }
+  async addToCart(data) {
+    return this.request("POST", "/api/cart", data);
+  }
+  async updateCartItem(itemId, data) {
+    return this.request("PATCH", `/api/cart/${encodeURIComponent(itemId)}`, data);
+  }
+  async removeFromCart(itemId) {
+    return this.request("DELETE", `/api/cart/${encodeURIComponent(itemId)}`);
+  }
+  async clearCart() {
+    return this.request("DELETE", "/api/cart");
+  }
+  // --- Favorites ---
+  async listFavorites(query) {
+    const params = new URLSearchParams();
+    if (query?.page) params.set("page", String(query.page));
+    if (query?.limit) params.set("limit", String(query.limit));
+    const qs = params.toString();
+    return this.request("GET", `/api/favorites${qs ? `?${qs}` : ""}`);
+  }
+  async addFavorite(agentId) {
+    return this.request("POST", `/api/favorites/${encodeURIComponent(agentId)}`);
+  }
+  async removeFavorite(agentId) {
+    return this.request("DELETE", `/api/favorites/${encodeURIComponent(agentId)}`);
+  }
+  // --- Health ---
+  async health() {
+    return this.request("GET", "/api/health", void 0, false);
+  }
+  // --- Docs (MCP interface) ---
+  async getDocsTree() {
+    return this.request("GET", "/api/mcp/docs/tree", void 0, false);
+  }
+  async getDocByPath(path) {
+    return this.request("GET", `/api/mcp/docs/by-path/${encodeURI(path)}`, void 0, false);
+  }
+  async searchDocs(query) {
+    const params = new URLSearchParams({ q: query });
+    return this.request("GET", `/api/mcp/docs/search?${params.toString()}`, void 0, false);
+  }
+  async getDoc(id) {
+    return this.request("GET", `/api/mcp/docs/${encodeURIComponent(id)}`, void 0, false);
+  }
+  async createDoc(data) {
+    return this.request("POST", "/api/mcp/docs", data);
+  }
+  async updateDoc(id, data) {
+    return this.request("PATCH", `/api/mcp/docs/${encodeURIComponent(id)}`, data);
+  }
+  async deleteDoc(id) {
+    return this.request("DELETE", `/api/mcp/docs/${encodeURIComponent(id)}`);
+  }
+  async publishDoc(id) {
+    return this.request("POST", `/api/mcp/docs/${encodeURIComponent(id)}/publish`);
+  }
+  async unpublishDoc(id) {
+    return this.request("POST", `/api/mcp/docs/${encodeURIComponent(id)}/unpublish`);
+  }
+  // --- Private ---
+  async request(method, path, body, requireAuth = true) {
+    const url = `${this.config.apiUrl}${path}`;
+    const headers = {};
+    if (body !== void 0) {
+      headers["Content-Type"] = "application/json";
+    }
+    if (requireAuth) {
+      if (this.agentTokenOverride) {
+        headers["Authorization"] = `Bearer ${this.agentTokenOverride}`;
+      } else if (this.config.token) {
+        headers["Authorization"] = `Bearer ${this.config.token}`;
+      } else if (this.config.apiKey) {
+        headers["x-api-key"] = this.config.apiKey;
+      } else {
+        throw new Error("Not authenticated. Run `clawrent auth login` first.");
+      }
+    }
+    const response = await fetch(url, {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : void 0
+    });
+    if (!response.ok) {
+      const errBody = await response.json().catch(() => ({ message: response.statusText }));
+      throw new Error(`API error ${response.status}: ${errBody["message"] ?? JSON.stringify(errBody)}`);
+    }
+    return response.json();
+  }
+};
+
+// src/config.ts
+import { readFileSync, writeFileSync, mkdirSync, unlinkSync, existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+var DEFAULT_CONFIG = {
+  apiUrl: "https://clawrent.cloud",
+  wsUrl: "wss://clawrent.cloud"
+};
+function getConfigDir() {
+  return join(homedir(), ".clawrent");
+}
+function getConfigFilePath() {
+  return join(getConfigDir(), "config.json");
+}
+function getConfigPath() {
+  return getConfigFilePath();
+}
+function loadConfig() {
+  let fileConfig = {};
+  const configPath = getConfigFilePath();
+  if (existsSync(configPath)) {
+    try {
+      const raw = readFileSync(configPath, "utf-8");
+      fileConfig = JSON.parse(raw);
+    } catch {
+    }
+  }
+  if (fileConfig.apiUrl?.includes("localhost") || fileConfig.wsUrl?.includes("localhost")) {
+    delete fileConfig.apiUrl;
+    delete fileConfig.wsUrl;
+    try {
+      const cleaned = { ...fileConfig };
+      writeFileSync(configPath, JSON.stringify(cleaned, null, 2), "utf-8");
+    } catch {
+    }
+  }
+  const config = {
+    ...DEFAULT_CONFIG,
+    ...fileConfig
+  };
+  const envApiUrl = process.env["CLAWRENT_API_URL"];
+  const envWsUrl = process.env["CLAWRENT_WS_URL"];
+  const envToken = process.env["CLAWRENT_TOKEN"];
+  const envApiKey = process.env["CLAWRENT_API_KEY"];
+  const envUserId = process.env["CLAWRENT_USER_ID"];
+  if (envApiUrl) config.apiUrl = envApiUrl;
+  if (envWsUrl) config.wsUrl = envWsUrl;
+  if (envToken) config.token = envToken;
+  if (envApiKey) config.apiKey = envApiKey;
+  if (envUserId) config.userId = envUserId;
+  return config;
+}
+function saveConfig(partial) {
+  const configDir = getConfigDir();
+  if (!existsSync(configDir)) {
+    mkdirSync(configDir, { recursive: true });
+  }
+  let existing = {};
+  const configPath = getConfigFilePath();
+  if (existsSync(configPath)) {
+    try {
+      existing = JSON.parse(readFileSync(configPath, "utf-8"));
+    } catch {
+    }
+  }
+  const merged = { ...existing, ...partial };
+  writeFileSync(configPath, JSON.stringify(merged, null, 2), "utf-8");
+}
+function clearConfig() {
+  const configPath = getConfigFilePath();
+  if (existsSync(configPath)) {
+    unlinkSync(configPath);
+  }
+}
+
+// src/session-manager.ts
+import { EventEmitter } from "events";
+import WebSocket from "ws";
+var TERMINAL_CLOSE_CODES = /* @__PURE__ */ new Set([4e3, 4001, 4002, 4003, 4004]);
+var SessionManager = class extends EventEmitter {
+  sessions = /* @__PURE__ */ new Map();
+  wsUrl;
+  heartbeatInterval;
+  maxReconnectDelay;
+  maxReconnectAttempts;
+  agentId;
+  constructor(wsUrl, heartbeatInterval = 25e3, maxReconnectDelay = 3e4, maxReconnectAttempts = 5) {
+    super();
+    this.wsUrl = wsUrl;
+    this.heartbeatInterval = heartbeatInterval;
+    this.maxReconnectDelay = maxReconnectDelay;
+    this.maxReconnectAttempts = maxReconnectAttempts;
+  }
+  /** Connect to a session via WebSocket as provider */
+  connect(sessionId, sessionToken) {
+    if (this.sessions.has(sessionId)) {
+      return;
+    }
+    const url = `${this.wsUrl}/ws/session?sessionId=${sessionId}&token=${sessionToken}&role=provider`;
+    const ws = new WebSocket(url);
+    const conn = {
+      sessionId,
+      sessionToken,
+      ws,
+      heartbeatTimer: null,
+      reconnectAttempts: 0
+    };
+    this.sessions.set(sessionId, conn);
+    ws.on("open", () => {
+      conn.reconnectAttempts = 0;
+      conn.heartbeatTimer = setInterval(() => {
+        if (ws.readyState === WebSocket.OPEN) {
+          ws.send(JSON.stringify({ type: "system.heartbeat", payload: {} }));
+        }
+      }, this.heartbeatInterval);
+      this.emit("session:connected", sessionId);
+    });
+    ws.on("message", (raw) => {
+      try {
+        const message = JSON.parse(raw.toString());
+        if (message["type"] === "system.heartbeat_ack") return;
+        this.emit("session:message", sessionId, message);
+      } catch {
+      }
+    });
+    ws.on("close", (code, reason) => {
+      this.clearHeartbeat(conn);
+      if (TERMINAL_CLOSE_CODES.has(code)) {
+        this.sessions.delete(sessionId);
+        this.emit("session:dead", sessionId, `session rejected (code ${code}: ${reason.toString()})`);
+        return;
+      }
+      if (code !== 1e3) {
+        if (conn.reconnectAttempts >= this.maxReconnectAttempts) {
+          this.sessions.delete(sessionId);
+          this.emit("session:dead", sessionId, `max reconnect attempts (${this.maxReconnectAttempts}) reached`);
+          return;
+        }
+        const delay = Math.min(
+          1e3 * Math.pow(2, conn.reconnectAttempts),
+          this.maxReconnectDelay
+        );
+        conn.reconnectAttempts++;
+        this.emit("session:reconnecting", sessionId, delay);
+        setTimeout(() => {
+          this.sessions.delete(sessionId);
+          this.connect(sessionId, sessionToken);
+        }, delay);
+      } else {
+        this.sessions.delete(sessionId);
+        this.emit("session:disconnected", sessionId, reason.toString());
+      }
+    });
+    ws.on("error", (err) => {
+      this.emit("session:error", sessionId, err);
+    });
+  }
+  /** Send a message to a specific session, auto-wrapping with protocol envelope */
+  send(sessionId, message) {
+    const conn = this.sessions.get(sessionId);
+    if (!conn || conn.ws.readyState !== WebSocket.OPEN) {
+      return false;
+    }
+    const envelope = {
+      id: message["id"] ?? `msg_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`,
+      sessionId: message["sessionId"] ?? sessionId,
+      timestamp: message["timestamp"] ?? Date.now(),
+      sender: message["sender"] ?? { role: "provider", agentId: this.agentId ?? "unknown" },
+      type: message["type"] ?? "result.success",
+      payload: message["payload"] ?? {}
+    };
+    conn.ws.send(JSON.stringify(envelope));
+    return true;
+  }
+  /** Disconnect a specific session */
+  disconnect(sessionId) {
+    const conn = this.sessions.get(sessionId);
+    if (!conn) return;
+    this.clearHeartbeat(conn);
+    if (conn.ws.readyState === WebSocket.OPEN || conn.ws.readyState === WebSocket.CONNECTING) {
+      conn.ws.close(1e3, "Provider disconnecting");
+    }
+    this.sessions.delete(sessionId);
+  }
+  /** Disconnect all sessions */
+  disconnectAll() {
+    for (const sessionId of this.sessions.keys()) {
+      this.disconnect(sessionId);
+    }
+  }
+  /** Get active session count */
+  get activeCount() {
+    return this.sessions.size;
+  }
+  /** Check if a session is connected */
+  isConnected(sessionId) {
+    const conn = this.sessions.get(sessionId);
+    return conn?.ws.readyState === WebSocket.OPEN;
+  }
+  clearHeartbeat(conn) {
+    if (conn.heartbeatTimer) {
+      clearInterval(conn.heartbeatTimer);
+      conn.heartbeatTimer = null;
+    }
+  }
+};
+
+// src/cursor.ts
+import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, mkdirSync as mkdirSync2, existsSync as existsSync2 } from "fs";
+import { dirname } from "path";
+var InMemoryCursorStore = class {
+  map = /* @__PURE__ */ new Map();
+  get(sessionId) {
+    return this.map.get(sessionId) ?? null;
+  }
+  set(sessionId, createdAt) {
+    const prev = this.map.get(sessionId);
+    if (prev === void 0 || createdAt > prev) this.map.set(sessionId, createdAt);
+  }
+};
+var FileCursorStore = class {
+  constructor(path) {
+    this.path = path;
+  }
+  path;
+  cache = null;
+  load() {
+    if (this.cache) return this.cache;
+    if (!existsSync2(this.path)) {
+      this.cache = /* @__PURE__ */ new Map();
+      return this.cache;
+    }
+    const raw = readFileSync2(this.path, "utf8");
+    try {
+      this.cache = new Map(Object.entries(JSON.parse(raw)));
+    } catch {
+      this.cache = /* @__PURE__ */ new Map();
+    }
+    return this.cache;
+  }
+  persist() {
+    if (!this.cache) return;
+    mkdirSync2(dirname(this.path), { recursive: true });
+    writeFileSync2(this.path, JSON.stringify(Object.fromEntries(this.cache), null, 2), "utf8");
+  }
+  get(sessionId) {
+    return this.load().get(sessionId) ?? null;
+  }
+  set(sessionId, createdAt) {
+    const m = this.load();
+    const prev = m.get(sessionId);
+    if (prev === void 0 || createdAt > prev) {
+      m.set(sessionId, createdAt);
+      this.persist();
+    }
+  }
+};
+
+// src/helpers.ts
+async function resumeActiveSessions(client, sessionManager) {
+  const res = await client.getSessions({ role: "provider", status: "active" });
+  const list = res?.data ?? [];
+  const attached = [];
+  for (const s of list) {
+    const sessionId = s["sessionId"] ?? s["id"];
+    const sessionToken = s["sessionToken"];
+    if (typeof sessionId !== "string" || typeof sessionToken !== "string") continue;
+    attached.push({
+      sessionId,
+      sessionToken,
+      taskDescription: typeof s["taskDescription"] === "string" ? s["taskDescription"] : void 0,
+      consumerUserId: typeof s["consumerUserId"] === "string" ? s["consumerUserId"] : void 0,
+      slotIndex: typeof s["slotIndex"] === "number" ? s["slotIndex"] : void 0
+    });
+    sessionManager.connect(sessionId, sessionToken);
+  }
+  return attached;
+}
+function diffSessionStates(prev, curr) {
+  const prevMap = new Map(prev.map((s) => [s.sessionId, s]));
+  const currMap = new Map(curr.map((s) => [s.sessionId, s]));
+  const newPending = [];
+  const activated = [];
+  const ended = [];
+  for (const [id, c] of currMap) {
+    const p = prevMap.get(id);
+    if (!p) {
+      if (c.status === "pending_approval") newPending.push(c);
+    } else if (p.status === "pending_approval" && c.status === "active") {
+      activated.push(c);
+    }
+  }
+  for (const [id, p] of prevMap) {
+    if (!currMap.has(id)) ended.push(p);
+  }
+  return { newPending, activated, ended };
+}
+
+// src/provider-client.ts
+import { EventEmitter as EventEmitter2 } from "events";
+import WebSocket2 from "ws";
+import { wsAgentControlEventSchema } from "@clawrent/protocol";
+var ProviderClient = class extends EventEmitter2 {
+  client;
+  cursor;
+  heartbeatIntervalMs;
+  maxReconnectAttempts;
+  autoApprove;
+  agentToken;
+  agentId = null;
+  agentWs = null;
+  sessionManager = null;
+  heartbeatTimer = null;
+  _running = false;
+  activeSessions = /* @__PURE__ */ new Map();
+  /**
+   * Per-session in-flight promise chain: each `session:message` for the same
+   * sessionId is chained onto the previous one so calls serialize. Without this,
+   * two socket frames arriving in the same tick would both pass the cursor
+   * dedupe check (the first call's `cursor.set` is queued behind its `await`
+   * and hasn't run when the second call reads the cursor) and onMessage would
+   * fire twice. The Map entry is cleared when the tail settles so it doesn't
+   * grow unbounded.
+   */
+  inflight = /* @__PURE__ */ new Map();
+  /** Callbacks captured at start(); used by handleAgentMessage/handleSessionMessage. */
+  boundCallbacks = null;
+  constructor(opts) {
+    super();
+    const config = {
+      apiUrl: opts.apiUrl ?? "https://clawrent.cloud",
+      wsUrl: opts.wsUrl ?? "wss://clawrent.cloud"
+    };
+    this.client = new ApiClient(config);
+    this.client.setAgentToken(opts.agentToken);
+    this.agentToken = opts.agentToken;
+    this.cursor = opts.cursorStore ?? new InMemoryCursorStore();
+    this.heartbeatIntervalMs = opts.heartbeatIntervalMs ?? 25e3;
+    this.maxReconnectAttempts = opts.maxReconnectAttempts ?? 5;
+    this.autoApprove = opts.autoApprove ?? true;
+  }
+  get running() {
+    return this._running;
+  }
+  get currentAgentId() {
+    return this.agentId;
+  }
+  /** Cursor store used for per-session message dedupe (wired in Task 6b). */
+  get cursorStore() {
+    return this.cursor;
+  }
+  /** Whether sessions are auto-approved on arrival (wired in Task 6b). */
+  get isAutoApprove() {
+    return this.autoApprove;
+  }
+  async start(callbacks) {
+    if (this._running) throw new Error("ProviderClient already started");
+    if (callbacks.agentId) {
+      this.agentId = callbacks.agentId;
+    } else {
+      const me = await this.client.getMyAgent();
+      this.agentId = me["id"] ?? me["agentId"] ?? null;
+    }
+    if (!this.agentId) throw new Error("Could not resolve agentId (pass callbacks.agentId or ensure token is valid)");
+    this.sessionManager = new SessionManager(this.client.wsUrl, this.heartbeatIntervalMs, 3e4, this.maxReconnectAttempts);
+    this.sessionManager.agentId = this.agentId;
+    this.bindSessionManager(callbacks);
+    await this.connectAgent();
+    try {
+      await this.client.activateAgent(this.agentId);
+    } catch (err) {
+      this.emit("agent:warning", `activation failed: ${err.message}`);
+    }
+    this._running = true;
+    this.emit("agent:started", this.agentId);
+    void this.resumeActive(callbacks);
+  }
+  bindSessionManager(callbacks) {
+    this.boundCallbacks = callbacks;
+    const sm = this.sessionManager;
+    if (!sm) return;
+    sm.on("session:connected", (sid) => this.emit("session:connected", sid));
+    sm.on("session:disconnected", (sid, reason) => this.emit("session:disconnected", sid, reason));
+    sm.on("session:message", (sid, message) => {
+      const prev = this.inflight.get(sid) ?? Promise.resolve();
+      const next = prev.then(() => this.handleSessionMessage(sid, message)).catch((err) => {
+        this.emit("session:error", sid, err);
+      });
+      this.inflight.set(sid, next);
+      next.finally(() => {
+        if (this.inflight.get(sid) === next) this.inflight.delete(sid);
+      });
+    });
+    sm.on("session:dead", (sid, reason) => {
+      const active = this.activeSessions.get(sid) ?? { sessionId: sid, sessionToken: "" };
+      this.activeSessions.delete(sid);
+      callbacks.onSessionEnded?.(active, reason);
+    });
+  }
+  async resumeActive(callbacks) {
+    if (!this.sessionManager) return;
+    try {
+      const sessions = await resumeActiveSessions(this.client, this.sessionManager);
+      for (const s of sessions) {
+        this.activeSessions.set(s.sessionId, s);
+        callbacks.onSessionNew?.(s);
+        this.emit("session:reattached", s.sessionId);
+      }
+    } catch (err) {
+      this.emit("agent:warning", `resume failed: ${err.message}`);
+    }
+  }
+  connectAgent() {
+    return new Promise((resolve, reject) => {
+      const url = `${this.client.wsUrl}/ws/agent?token=${encodeURIComponent(this.agentToken)}`;
+      const ws = new WebSocket2(url);
+      this.agentWs = ws;
+      ws.on("open", () => {
+        this.heartbeatTimer = setInterval(() => {
+          if (ws.readyState === WebSocket2.OPEN) {
+            ws.send(JSON.stringify({ type: "system.heartbeat", payload: {} }));
+          }
+        }, this.heartbeatIntervalMs);
+        this.emit("agent:connected");
+        resolve();
+      });
+      ws.on("error", reject);
+      ws.on("close", (code, reason) => {
+        this.emit("agent:disconnected", code, reason.toString());
+      });
+      ws.on("message", (raw) => {
+        void this.handleAgentMessage(raw).catch((err) => {
+          this.emit("agent:warning", `agent message handler failed: ${err.message}`);
+        });
+      });
+    });
+  }
+  /**
+   * Parses an inbound /ws/agent frame and routes it.
+   *
+   * `session.new` / `session.approved` are validated against the protocol
+   * discriminated-union schema (fields under `payload`). Other /ws/agent frame
+   * types pushed by the backend (agent.connected / agent.status_updated /
+   * system.error / system.heartbeat_ack — see apps/platform-api ws-agent-handler.ts)
+   * are NOT in wsAgentControlEventSchema, so we route them by `type` directly
+   * instead of forcing them through the schema (which would reject them).
+   * Unknown types are ignored gracefully.
+   *
+   * Note: backend does NOT push `session.ended` on /ws/agent; session
+   * terminations arrive as `system.session_ended` on /ws/session.
+   */
+  async handleAgentMessage(raw) {
+    let frame;
+    try {
+      frame = JSON.parse(raw.toString());
+    } catch {
+      return;
+    }
+    if (typeof frame !== "object" || frame === null) return;
+    const type = frame["type"];
+    if (type === "session.new" || type === "session.approved") {
+      let parsed;
+      try {
+        parsed = wsAgentControlEventSchema.parse(frame);
+      } catch {
+        return;
+      }
+      if (parsed.type === "session.new") {
+        await this.onSessionNew(parsed.payload);
+      } else {
+        this.onSessionApproved(parsed.payload);
+      }
+      return;
+    }
+    const payload = frame["payload"];
+    switch (type) {
+      case "system.heartbeat_ack":
+        return;
+      // heartbeat acknowledgement — ignore
+      case "system.error":
+        this.emit("agent:warning", `server error: ${JSON.stringify(payload) ?? "no payload"}`);
+        return;
+      case "agent.connected":
+        this.emit("agent:connected", payload);
+        return;
+      case "agent.status_updated":
+        this.emit("agent:status", payload);
+        return;
+      default:
+        return;
+    }
+  }
+  /** session.new: register, notify host, optionally auto-approve + connect /ws/session. */
+  async onSessionNew(payload) {
+    const sessionId = payload.sessionId;
+    const sessionToken = payload.sessionToken;
+    const active = {
+      sessionId,
+      sessionToken: sessionToken ?? "",
+      taskDescription: payload.taskDescription,
+      consumerUserId: payload.consumerUserId
+    };
+    this.activeSessions.set(sessionId, active);
+    this.boundCallbacks?.onSessionNew?.(active);
+    this.emit("session:new", active);
+    const shouldApprove = this.autoApprove ? true : this.boundCallbacks?.onPendingApproval ? await this.boundCallbacks.onPendingApproval(active) : false;
+    if (!shouldApprove) return;
+    if (this.autoApprove) {
+      try {
+        await this.client.approveSession(sessionId);
+      } catch (err) {
+        this.emit("agent:warning", `approve failed for ${sessionId}: ${err.message}`);
+        return;
+      }
+    }
+    if (sessionToken) {
+      this.sessionManager?.connect(sessionId, sessionToken);
+    } else {
+      this.emit("agent:warning", `session.new for ${sessionId} carried no sessionToken; deferring /ws/session connect until session.approved`);
+    }
+  }
+  /** session.approved: ensure tracked + connect /ws/session (idempotent). */
+  onSessionApproved(payload) {
+    const sessionId = payload.sessionId;
+    const sessionToken = payload.sessionToken;
+    const existing = this.activeSessions.get(sessionId);
+    const active = existing ?? {
+      sessionId,
+      sessionToken: sessionToken ?? ""
+    };
+    if (sessionToken) active.sessionToken = sessionToken;
+    this.activeSessions.set(sessionId, active);
+    this.emit("session:approved", active);
+    if (sessionToken) {
+      this.sessionManager?.connect(sessionId, sessionToken);
+    }
+  }
+  /**
+   * Dedupes an inbound /ws/session message by per-session cursor, then invokes
+   * the host's onMessage callback. Public (no underscore prefix) so the
+   * integration test can drive the cursor/dedupe path directly as a hook.
+   *
+   * At-least-once invariant (Task 6b fix round 1): the cursor is advanced ONLY
+   * AFTER `await onMessage` completes successfully. If onMessage throws, the
+   * cursor is left un-advanced and `session:error` is emitted — so a future
+   * redelivery (e.g. backend replay on restart) will pass the dedupe check and
+   * re-process the message. onMessage MUST be idempotent precisely because of
+   * this redelivery semantics. The per-session in-flight chain in
+   * `bindSessionManager`'s `session:message` handler serializes concurrent
+   * frames for the same session so the cursor-after-success commit has a chance
+   * to run before the next frame's dedupe check reads the cursor.
+   *
+   * `createdAt` is canonical UTC ISO, taken from `_meta.timestamp` (backend
+   * pushes ISO `...Z`) with a `new Date(message.timestamp).toISOString()`
+   * fallback (ms epoch).
+   */
+  async handleSessionMessage(sessionId, message) {
+    const onMessage = this.boundCallbacks?.onMessage;
+    if (!onMessage) return;
+    const meta = message["_meta"];
+    const metaTs = meta?.timestamp;
+    const msgTs = message["timestamp"];
+    const createdAt = typeof metaTs === "string" ? metaTs : typeof msgTs === "number" ? new Date(msgTs).toISOString() : (/* @__PURE__ */ new Date()).toISOString();
+    const last = this.cursor.get(sessionId);
+    if (last && createdAt <= last) return;
+    const session = this.activeSessions.get(sessionId) ?? { sessionId, sessionToken: "" };
+    try {
+      await onMessage(session, message);
+    } catch (err) {
+      this.emit("session:error", sessionId, err);
+      return;
+    }
+    this.cursor.set(sessionId, createdAt);
+  }
+  /**
+   * Send an outbound message to a session. Prefers the /ws/session socket when
+   * it is OPEN (low latency, no HTTP overhead); falls back to the REST
+   * `POST /api/sessions/:id/messages` endpoint when the socket is absent or not
+   * yet open (e.g. before start(), during reconnect, or for sessions not yet
+   * attached). Returns the transport actually used so callers can observe it.
+   *
+   * Note: this method does NOT throw when WS is unavailable — it silently falls
+   * back to REST. REST errors propagate to the caller as-is.
+   */
+  async send(sessionId, message) {
+    const sm = this.sessionManager;
+    if (sm?.isConnected(sessionId)) {
+      const ok = sm.send(sessionId, message);
+      if (ok) return { via: "ws" };
+    }
+    await this.client.sendSessionMessage(sessionId, message);
+    return { via: "rest" };
+  }
+  stop() {
+    this._running = false;
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+    this.sessionManager?.disconnectAll();
+    if (this.agentWs) {
+      this.agentWs.close(1e3, "Provider stopping");
+      this.agentWs = null;
+    }
+    this.activeSessions.clear();
+    this.client.setAgentToken(null);
+    this.emit("stopped");
+  }
+};
+
+// src/index.ts
+var PROVIDER_PACKAGE_VERSION = "0.1.0";
+export {
+  ApiClient,
+  FileCursorStore,
+  InMemoryCursorStore,
+  PROVIDER_PACKAGE_VERSION,
+  ProviderClient,
+  SessionManager,
+  clearConfig,
+  diffSessionStates,
+  getConfigDir,
+  getConfigPath,
+  loadConfig,
+  resumeActiveSessions,
+  saveConfig
+};
+//# sourceMappingURL=index.js.map