@prismer/sdk 2.0.7 → 2.2.55

package/dist/index.js

@@ -62,6 +62,7 @@ __export(index_exports, {
   MessagesClient: () => MessagesClient,
   MetricsClient: () => MetricsClient,
   OfflineManager: () => OfflineManager,
+  PkfClient: () => PkfClient,
   PrismerClient: () => PrismerClient,
   ProjectMembersClient: () => ProjectMembersClient,
   ProjectsClient: () => ProjectsClient,
@@ -588,6 +589,8 @@ var OfflineManager = class extends OfflineEmitter {
     this._isOnline = true;
     this._syncState = "idle";
     this.sseSource = null;
+    /** release203/12 — unified single-WS realtime transport (preferred over SSE). */
+    this.wsSource = null;
     this.sseReconnectTimer = null;
     this.sseReconnectAttempts = 0;
     /** Presence cache for realtime presence events */
@@ -606,6 +609,8 @@ var OfflineManager = class extends OfflineEmitter {
         warningThreshold: options.quota.warningThreshold ?? 0.9
       } : void 0
     };
+    this.WS = options.WebSocket ?? (typeof WebSocket !== "undefined" ? WebSocket : void 0);
+    this.unifiedWs = options.unifiedWs ?? true;
   }
   get isOnline() {
     return this._isOnline;
@@ -1082,14 +1087,17 @@ var OfflineManager = class extends OfflineEmitter {
    * Replaces polling with real-time push when syncMode is 'push'.
    */
   async startContinuousSync() {
-    if (this.sseSource) return;
-    if (typeof EventSource === "undefined") {
-      return this.sync();
-    }
+    if (this.sseSource || this.wsSource) return;
     const token = this.tokenProvider?.();
     if (!token) {
       return this.sync();
     }
+    if (this.unifiedWs && this.WS) {
+      return this.startContinuousSyncWs(token);
+    }
+    if (typeof EventSource === "undefined") {
+      return this.sync();
+    }
     const cursor = await this.storage.getCursor("global_sync") ?? "0";
     const baseUrl = this.getBaseUrl();
     const url = `${baseUrl}/api/im/sync/stream?token=${encodeURIComponent(token)}&since=${cursor}`;
@@ -1142,9 +1150,103 @@ var OfflineManager = class extends OfflineEmitter {
     }
   }
   /**
-   * Stop the SSE continuous sync connection.
+   * release203/12 — continuous sync over the unified single WebSocket.
+   * Consumes the `{ch:'sync',name:'sync',data}` frames (the same per-user
+   * fan-out the SSE endpoint served) and ignores the `tasks` channel + control
+   * frames. Behaviour-preserving vs the SSE path: same applySyncEvent, same
+   * cursor, same emitted events — only the transport differs (2 sockets → 1).
+   */
+  async startContinuousSyncWs(token) {
+    if (!this.WS) return this.sync();
+    const cursor = await this.storage.getCursor("global_sync") ?? "0";
+    const httpBase = this.getBaseUrl();
+    const wsBase = httpBase.replace(/^http/, "ws").replace(/\/$/, "");
+    const url = `${wsBase}/ws/realtime?token=${encodeURIComponent(token)}&since=${cursor}`;
+    this._syncState = "syncing";
+    this.emit("sync.start", void 0);
+    this.sseReconnectAttempts = 0;
+    let totalNew = 0;
+    let totalUpdated = 0;
+    try {
+      const ws = new this.WS(url);
+      this.wsSource = ws;
+      ws.onopen = () => {
+        this.sseReconnectAttempts = 0;
+      };
+      ws.onmessage = async (ev) => {
+        let frame;
+        try {
+          frame = JSON.parse(typeof ev.data === "string" ? ev.data : String(ev.data));
+        } catch {
+          return;
+        }
+        const name = frame.name;
+        if (name === "heartbeat") return;
+        if (name === "caught_up") {
+          this._syncState = "idle";
+          this.sseReconnectAttempts = 0;
+          this.emit("sync.complete", { newMessages: totalNew, updatedConversations: totalUpdated });
+          totalNew = 0;
+          totalUpdated = 0;
+          return;
+        }
+        if (name === "error") {
+          this._syncState = "error";
+          this.emit("sync.error", { error: "WS stream error", willRetry: true });
+          return;
+        }
+        if (frame.ch !== "sync" || name !== "sync") return;
+        const data = frame.data;
+        if (!data || typeof data !== "object") return;
+        if (data.type === "sync.backfill.truncated") {
+          if (typeof data.newestSeq === "number") await this.storage.setCursor("global_sync", String(data.newestSeq));
+          return;
+        }
+        if (data.type === "sync.backfill.done") {
+          if (typeof data.seq === "number") await this.storage.setCursor("global_sync", String(data.seq));
+          return;
+        }
+        try {
+          const event = data;
+          await this.applySyncEvent(event);
+          if (typeof event.seq === "number") await this.storage.setCursor("global_sync", String(event.seq));
+          if (event.type === "message.new") totalNew++;
+          if (event.type?.startsWith("conversation.")) totalUpdated++;
+          this.emit("sync.progress", { synced: 1, total: 1 });
+          if (this.options.quota) await this.checkQuota();
+        } catch {
+        }
+      };
+      ws.onerror = () => {
+        this._syncState = "error";
+        this.emit("sync.error", { error: "WS connection error", willRetry: true });
+      };
+      ws.onclose = () => {
+        this.wsSource = null;
+        if (this._syncState !== "idle") this._syncState = "error";
+        this.scheduleSseReconnect();
+      };
+    } catch (err) {
+      this.wsSource = null;
+      this._syncState = "error";
+      this.emit("sync.error", {
+        error: err instanceof Error ? err.message : "WS init failed",
+        willRetry: true
+      });
+      this.scheduleSseReconnect();
+    }
+  }
+  /**
+   * Stop the continuous sync connection (WS or SSE).
    */
   stopContinuousSync() {
+    if (this.wsSource) {
+      try {
+        this.wsSource.close();
+      } catch {
+      }
+      this.wsSource = null;
+    }
     if (this.sseSource) {
       this.sseSource.close();
       this.sseSource = null;
@@ -1577,7 +1679,7 @@ var import_aip_sdk5 = require("@prismer/aip-sdk");
 
 // src/types.ts
 var ENVIRONMENTS = {
-  production: "https://prismer.cloud"
+  production: "https://prod.docbrew.cn"
 };
 
 // src/im/workspace/tasks.ts
@@ -3850,9 +3952,10 @@ var WorkspaceClient = class {
   async initGroup(options) {
     return this._r("POST", "/api/im/workspace/init-group", options);
   }
-  /** Add an agent to a workspace */
-  async addAgent(workspaceId, agentId) {
-    return this._r("POST", `/api/im/workspace/${workspaceId}/agents`, { agentId });
+  /** Create a low-level agent identity in a workspace. Role workflows use the role-builder harness. */
+  async addAgent(workspaceId, options) {
+    const body = typeof options === "string" ? { agentName: options, agentDisplayName: options } : options;
+    return this._r("POST", `/api/im/workspace/${workspaceId}/agents`, body);
   }
   /** List agents in a workspace */
   async listAgents(workspaceId) {
@@ -3978,6 +4081,17 @@ var TasksClient = class {
   async approve(taskId) {
     return this._r("POST", `/api/im/tasks/${taskId}/approve`);
   }
+  /**
+   * apc P-6 — post an auditable task event (`POST /tasks/:id/event`).
+   *
+   * Lands one `im_task_logs` row: `action = code.toLowerCase()`, `payload`
+   * serialised into metadata. Server-side authorization: only the task
+   * assignee may post. Used by `cloud skill ack` for skill invocation
+   * receipts (code `SKILL_ACK` → action `skill_ack`).
+   */
+  async postEvent(taskId, options) {
+    return this._r("POST", `/api/im/tasks/${taskId}/event`, options);
+  }
   /** Reject a task with reason */
   async reject(taskId, reason) {
     return this._r("POST", `/api/im/tasks/${taskId}/reject`, { reason });
@@ -4142,6 +4256,40 @@ var MetricsClient = class {
     if (filterPairs.length) query.filter = filterPairs.join(",");
     return this._r("GET", "/api/im/metrics/aggregate", void 0, query);
   }
+  /**
+   * B-P1d — raw event rows behind an aggregate (runtime210/06 W12b
+   * provenance read). workspaceId is mandatory on the filter — same
+   * cross-workspace rule as aggregate(); the server rejects without it.
+   */
+  async events(opts) {
+    const query = {
+      namespace: opts.namespace,
+      name: opts.name
+    };
+    if (opts.range) query.range = opts.range;
+    if (opts.from) query.from = opts.from;
+    if (opts.to) query.to = opts.to;
+    if (opts.limit !== void 0) query.limit = String(opts.limit);
+    const filterPairs = Object.entries(opts.filter).map(([k, v]) => `${k}:${v}`);
+    if (filterPairs.length) query.filter = filterPairs.join(",");
+    return this._r("GET", "/api/im/metrics/events", void 0, query);
+  }
+  /**
+   * B-P1d — conversation / task / agent scoped turn summary over the turn.*
+   * family. The response `data` shape is the frozen TurnMetricsSummary
+   * contract above.
+   */
+  async turnSummary(opts) {
+    const query = {
+      scope: opts.scope,
+      id: opts.id,
+      workspaceId: opts.workspaceId
+    };
+    if (opts.range) query.range = opts.range;
+    if (opts.from) query.from = opts.from;
+    if (opts.to) query.to = opts.to;
+    return this._r("GET", "/api/im/metrics/turns", void 0, query);
+  }
 };
 var IdentityClient = class {
   constructor(_r) {
@@ -4353,6 +4501,14 @@ var AgentsClient = class {
     this._r = _r;
     this.skills = new AgentSkillsClient(_r);
   }
+  /** Discover AgentCard-backed agents in a workspace the caller belongs to. */
+  async discover(options) {
+    const query = { workspaceId: options.workspaceId };
+    if (options.agentType) query.agentType = options.agentType;
+    if (options.capability) query.capability = options.capability;
+    if (options.onlineOnly) query.onlineOnly = "true";
+    return this._r("GET", "/api/im/agents", void 0, query);
+  }
   async spec(agentId, workspaceId) {
     const query = workspaceId ? { workspaceId } : void 0;
     return this._r("GET", `/api/im/agents/${encodeURIComponent(agentId)}/spec`, void 0, query);
@@ -4993,17 +5149,18 @@ var WorkspacesClient = class {
     return this._r("GET", `/api/im/workspaces/${workspaceId}/orchestrator`);
   }
   /**
-   * Appoint an agent as the workspace's orchestrator. Owner-only. If an
-   * orchestrator is already active, this auto-revokes the previous one in the
-   * same UPDATE.
+   * Appoint an agent as the workspace's orchestrator. Owner-only.
+   *
+   * ⚠️ FIRST appointment only. The orchestrator is a node of the platform
+   * network — it holds a globally-unique AIP identity (DID) and system contact
+   * edges to the platform official agents — so the appointment is PERMANENT:
+   * appointing a different agent while one is already in place fails with
+   * 409 `ORCHESTRATOR_IMMUTABLE`. Re-appointing the same agent is a no-op.
+   * Revocation does not exist (`revokeOrchestrator` was removed in 2.1.0).
    */
   async appointOrchestrator(workspaceId, agentImUserId) {
     return this._r("POST", `/api/im/workspaces/${workspaceId}/orchestrator`, { agentImUserId });
   }
-  /** Revoke the workspace's current orchestrator. Owner-only. Idempotent. */
-  async revokeOrchestrator(workspaceId) {
-    return this._r("DELETE", `/api/im/workspaces/${workspaceId}/orchestrator`);
-  }
   // Sub-clients `members` / `invites` are declared at the top of the class and
   // wired up inside the constructor body — see `AgentsClient` for the same
   // pattern. Declaring them as field initializers that reference `this._r`
@@ -5579,6 +5736,19 @@ var FilesClient = class {
    */
   async sendFile(conversationId, input, opts) {
     const uploaded = await this.upload(input, opts);
+    const outboxDir = process.env.PRISMER_OUTBOX_DIR;
+    if (outboxDir) {
+      try {
+        const fsMod = await import("fs");
+        const pathMod = await import("path");
+        const srcPath = typeof input === "string" ? input : input.path;
+        if (srcPath && typeof srcPath === "string") {
+          await fsMod.promises.mkdir(outboxDir, { recursive: true });
+          fsMod.cpSync(srcPath, pathMod.join(outboxDir, pathMod.basename(srcPath)));
+        }
+      } catch {
+      }
+    }
     const msgRes = await this._r("POST", `/api/im/messages/${conversationId}`, {
       content: opts?.content || uploaded.fileName,
       type: "file",
@@ -5706,6 +5876,11 @@ var IMRealtimeClient = class {
    *   sub.disconnect();
    */
   async subscribeTaskEvents(token, onEvent, options) {
+    const wantWs = options?.unifiedWs ?? true;
+    const WS = options?.WebSocket ?? (typeof WebSocket !== "undefined" ? WebSocket : void 0);
+    if (wantWs && WS) {
+      return this.subscribeTaskEventsWs(token, onEvent, WS, options?.signal);
+    }
     const controller = new AbortController();
     const onAbort = () => controller.abort();
     options?.signal?.addEventListener("abort", onAbort);
@@ -5786,6 +5961,45 @@ var IMRealtimeClient = class {
       }
     };
   }
+  /**
+   * release203/12 — task events over the unified single WebSocket.
+   * Connects to `WS /ws/realtime`, filters the `ch:'tasks'` frames, and emits
+   * the SAME `{ type, payload }` envelopes `subscribeTaskEvents` did over SSE
+   * (the WS carries no per-event `id`; cursor resume is handled by the sync
+   * channel). The `ch:'sync'` frames + control frames are ignored here.
+   */
+  subscribeTaskEventsWs(token, onEvent, WS, signal) {
+    const wsBase = this._wsBase.replace(/^http/, "ws").replace(/\/$/, "");
+    const url = `${wsBase}/ws/realtime?token=${encodeURIComponent(token)}&since=0`;
+    const ws = new WS(url);
+    const disconnect = () => {
+      try {
+        ws.close();
+      } catch {
+      }
+    };
+    if (signal) {
+      if (signal.aborted) disconnect();
+      else signal.addEventListener("abort", disconnect, { once: true });
+    }
+    ws.onmessage = (ev) => {
+      let frame;
+      try {
+        frame = JSON.parse(typeof ev.data === "string" ? ev.data : String(ev.data));
+      } catch {
+        return;
+      }
+      if (frame.ch !== "tasks" || !frame.name) return;
+      try {
+        onEvent({
+          type: frame.name,
+          payload: frame.data ?? {}
+        });
+      } catch {
+      }
+    };
+    return { disconnect };
+  }
 };
 var SkillsDraftClient = class {
   constructor(_r) {
@@ -5817,6 +6031,81 @@ var SkillsClient = class {
     this.draft = new SkillsDraftClient(_r);
   }
 };
+var PkfClient = class {
+  constructor(_r, _fetchAuthed) {
+    this._r = _r;
+    this._fetchAuthed = _fetchAuthed;
+  }
+  async materialize(input) {
+    return this._r("POST", "/api/pkf/materializations", input);
+  }
+  async getMaterialization(query) {
+    return this._r("GET", "/api/pkf/materializations", void 0, {
+      workspaceId: query.workspaceId,
+      idempotencyKey: query.idempotencyKey,
+      targetKind: query.targetKind
+    });
+  }
+  async discoverMaterialization(query) {
+    return this._r("GET", "/api/pkf/materializations", void 0, {
+      workspaceId: query.workspaceId,
+      messageId: query.source.messageId,
+      blockId: query.source.blockId,
+      blockRevision: String(query.source.blockRevision),
+      sourceHash: query.source.sourceHash,
+      targetKind: query.targetKind
+    });
+  }
+  /** Atomically commit a PKF root plus its exact root-bound dependency graph. */
+  async commitBundle(input) {
+    return this._r("POST", "/api/pkf/bundles/commit", input);
+  }
+  /** Restore the caller-scoped durable bundle receipt after process restart. */
+  async getBundle(query) {
+    return this._r("GET", "/api/pkf/bundles/commit", void 0, {
+      workspaceId: query.workspaceId,
+      idempotencyKey: query.idempotencyKey
+    });
+  }
+  async getArtifactRelations(query) {
+    const rootKind = encodeURIComponent(query.rootKind);
+    const rootId = encodeURIComponent(query.rootId);
+    return this._r(
+      "GET",
+      `/api/pkf/artifacts/${rootKind}/${rootId}/relations`,
+      void 0,
+      { workspaceId: query.workspaceId, revision: String(query.revision) }
+    );
+  }
+  async getResourceDetail(query) {
+    return this._r("GET", "/api/pkf/resources/detail", void 0, pkfResourceReadParams(query));
+  }
+  /**
+   * Read root-authorized dependency bytes. This intentionally returns the raw
+   * Response so callers can stream the body and verify `X-Asset-Hash`.
+   */
+  async getResourceBytes(query) {
+    const params = new URLSearchParams(pkfResourceReadParams(query));
+    return this._fetchAuthed(`/api/pkf/resources/bytes?${params.toString()}`);
+  }
+  /** Low-level canonical request seam used by the Cloud CLI. */
+  async request(method, path, body, query) {
+    return this._r(method, path, body, query);
+  }
+};
+function pkfResourceReadParams(query) {
+  const params = {
+    workspaceId: query.workspaceId,
+    rootKind: query.rootKind,
+    rootId: query.rootId,
+    rootRevision: String(query.rootRevision),
+    rootHash: query.rootHash
+  };
+  if (typeof query.targetAssetId === "string") params.targetAssetId = query.targetAssetId;
+  else if (typeof query.targetHash === "string") params.targetHash = query.targetHash;
+  else throw new TypeError("PKF resource read requires exactly one target locator");
+  return params;
+}
 var IMClient = class {
   constructor(request, wsBase, fetchFn, getAuthHeaders, offlineManager, communityHubConfig) {
     this._request = request;
@@ -5895,6 +6184,7 @@ var PrismerClient = class {
     this.timeout = config.timeout || 3e4;
     this.fetchFn = config.fetch || fetch;
     this.imAgent = config.imAgent;
+    this.imWorkspace = config.imWorkspace;
     if (config.identity) {
       if (config.identity === "auto" && this.apiKey) {
         this._identityReady = import_aip_sdk.AIPIdentity.fromApiKey(this.apiKey).then((id) => {
@@ -5952,6 +6242,10 @@ var PrismerClient = class {
       this._offlineManager,
       config.community ?? null
     );
+    this.pkf = new PkfClient(
+      (method, path, body, query, opts) => this._request(method, path, body, query, opts),
+      (path, init) => this.fetchAuthed(path, init)
+    );
     this.workspaces = this.im.workspaces;
     this.invites = this.im.invites;
     this.projects = this.im.projects;
@@ -5987,10 +6281,13 @@ var PrismerClient = class {
     }, query, opts);
   }
   /** Build auth headers for raw HTTP requests (used by file upload) */
-  _getAuthHeaders() {
+  _getAuthHeaders(authority = "im") {
     const headers = {};
     if (this.apiKey) headers["Authorization"] = `Bearer ${this.apiKey}`;
-    if (this.imAgent) headers["X-IM-Agent"] = this.imAgent;
+    if (this.imAgent) {
+      headers[authority === "pkf" ? "X-Prismer-Agent" : "X-IM-Agent"] = this.imAgent;
+    }
+    if (this.imWorkspace) headers["X-IM-Workspace"] = this.imWorkspace;
     return headers;
   }
   /**
@@ -6013,16 +6310,17 @@ var PrismerClient = class {
    *
    * The path may be absolute (`/api/...`) or a full URL — full URLs are used
    * verbatim (useful for following 302 redirects), otherwise the path is
-   * appended to the client's configured `baseUrl`. Authorization + `X-IM-Agent`
-   * headers are added automatically; caller-supplied headers in `init.headers`
-   * override them on collision.
+   * appended to the client's configured `baseUrl`. Authorization plus the
+   * authority-specific agent header are added automatically: canonical PKF
+   * requests use `X-Prismer-Agent`, while legacy `/api/im/*` keeps
+   * `X-IM-Agent`. Caller-supplied headers override them on collision.
    *
    * Use this for binary downloads / partial fetches; for normal JSON-envelope
    * IM requests use `client.im.request()` (typed) or the typed sub-clients.
    */
   async fetchAuthed(url, init) {
     const fullUrl = /^https?:\/\//i.test(url) ? url : `${this.baseUrl}${url}`;
-    const authHeaders = this._getAuthHeaders();
+    const authHeaders = this._getAuthHeaders(/\/api\/pkf\//.test(url) ? "pkf" : "im");
     const callerHeaders = {};
     if (init?.headers) {
       const h = init.headers;
@@ -6055,7 +6353,10 @@ var PrismerClient = class {
         headers["Authorization"] = `Bearer ${this.apiKey}`;
       }
       if (this.imAgent) {
-        headers["X-IM-Agent"] = this.imAgent;
+        headers[path.startsWith("/api/pkf/") ? "X-Prismer-Agent" : "X-IM-Agent"] = this.imAgent;
+      }
+      if (this.imWorkspace) {
+        headers["X-IM-Workspace"] = this.imWorkspace;
       }
       if (opts?.headers) {
         for (const [k, v] of Object.entries(opts.headers)) headers[k] = v;
@@ -6196,6 +6497,7 @@ function createClient(config) {
   MessagesClient,
   MetricsClient,
   OfflineManager,
+  PkfClient,
   PrismerClient,
   ProjectMembersClient,
   ProjectsClient,