@prismer/sdk 2.0.3 → 2.0.5

package/dist/cli.js

@@ -1753,6 +1753,44 @@ function resolveBaseUrl(explicit) {
   }
   return void 0;
 }
+function generateIdempotencyKey() {
+  try {
+    if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+      return crypto.randomUUID();
+    }
+  } catch {
+  }
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+    const r = Math.random() * 16 | 0;
+    return (c === "x" ? r : r & 3 | 8).toString(16);
+  });
+}
+function buildSendPayload(content, options) {
+  const key = options?.idempotencyKey ?? generateIdempotencyKey();
+  const isBlocks = Array.isArray(content);
+  const body = {
+    // For ContentBlock[] inputs, populate `content` as a fallback summary
+    // (server's legacy `content` column stays compatible during the 6-sprint
+    // double-write window from §4.6); the SOT is `contentBlocks`.
+    content: isBlocks ? "" : content,
+    type: options?.type ?? "text",
+    metadata: options?.metadata,
+    attachments: options?.attachments,
+    parentId: options?.parentId,
+    quotedMessageId: options?.quotedMessageId,
+    idempotencyKey: key
+  };
+  if (isBlocks) {
+    body.contentBlocks = content;
+  } else if (options?.contentBlocks) {
+    body.contentBlocks = options.contentBlocks;
+  }
+  return {
+    body,
+    opts: { headers: { "X-Idempotency-Key": key } },
+    key
+  };
+}
 var AccountClient = class {
   constructor(_r) {
     this._r = _r;
@@ -1795,16 +1833,17 @@ var DirectClient = class {
   constructor(_r) {
     this._r = _r;
   }
-  /** Send a direct message to a user */
+  /**
+   * Send a direct message to a user.
+   *
+   * v2.0 §4.6 — `content` may now be a `ContentBlock[]` for multimodal sends.
+   * v2.0 §3.0.2 Gap A-④ — when `options.idempotencyKey` is omitted, the SDK
+   * generates a UUID per call and stamps it into the `X-Idempotency-Key`
+   * header. Pass the same key across retries to trigger server dedup.
+   */
   async send(userId, content, options) {
-    return this._r("POST", `/api/im/direct/${userId}/messages`, {
-      content,
-      type: options?.type ?? "text",
-      metadata: options?.metadata,
-      attachments: options?.attachments,
-      parentId: options?.parentId,
-      quotedMessageId: options?.quotedMessageId
-    });
+    const { body, opts } = buildSendPayload(content, options);
+    return this._r("POST", `/api/im/direct/${userId}/messages`, body, void 0, opts);
   }
   /** Get direct message history with a user */
   async getMessages(userId, options) {
@@ -1830,16 +1869,15 @@ var GroupsClient = class {
   async get(groupId) {
     return this._r("GET", `/api/im/groups/${groupId}`);
   }
-  /** Send a message to a group */
+  /**
+   * Send a message to a group.
+   *
+   * v2.0 §4.6 — `content` may now be a `ContentBlock[]` for multimodal sends.
+   * v2.0 §3.0.2 Gap A-④ — auto-generates `X-Idempotency-Key` per call.
+   */
   async send(groupId, content, options) {
-    return this._r("POST", `/api/im/groups/${groupId}/messages`, {
-      content,
-      type: options?.type ?? "text",
-      metadata: options?.metadata,
-      attachments: options?.attachments,
-      parentId: options?.parentId,
-      quotedMessageId: options?.quotedMessageId
-    });
+    const { body, opts } = buildSendPayload(content, options);
+    return this._r("POST", `/api/im/groups/${groupId}/messages`, body, void 0, opts);
   }
   /** Get group message history */
   async getMessages(groupId, options) {
@@ -1909,16 +1947,23 @@ var MessagesClient = class {
   constructor(_r) {
     this._r = _r;
   }
-  /** Send a message to a conversation */
+  /**
+   * Send a message to a conversation.
+   *
+   * v2.0 §4.6 — `content` may now be a `ContentBlock[]` for multimodal sends.
+   * The SDK serialises ContentBlock[] into `body.contentBlocks` (preferred
+   * path) while still writing a string `content` for legacy renderers during
+   * the §4.6 6-sprint double-read window.
+   *
+   * v2.0 §3.0.2 Gap A-④ — when `options.idempotencyKey` is omitted, the SDK
+   * auto-generates `crypto.randomUUID()` per call and includes it as the
+   * `X-Idempotency-Key` HTTP header. The server applies UNIQUE
+   * `(conversationId, idempotencyKey)` dedup; pass the same key across
+   * retries to safely re-send.
+   */
   async send(conversationId, content, options) {
-    return this._r("POST", `/api/im/messages/${conversationId}`, {
-      content,
-      type: options?.type ?? "text",
-      metadata: options?.metadata,
-      attachments: options?.attachments,
-      parentId: options?.parentId,
-      quotedMessageId: options?.quotedMessageId
-    });
+    const { body, opts } = buildSendPayload(content, options);
+    return this._r("POST", `/api/im/messages/${conversationId}`, body, void 0, opts);
   }
   /** Get message history for a conversation */
   async getHistory(conversationId, options) {
@@ -2456,6 +2501,46 @@ var EvolutionSkillsClient = class {
     return this._r("POST", `/api/im/skills/${encodeURIComponent(skillId)}/star`);
   }
 };
+var AgentsClient = class {
+  constructor(_r) {
+    this._r = _r;
+  }
+  async spec(agentId, workspaceId) {
+    const query = workspaceId ? { workspaceId } : void 0;
+    return this._r("GET", `/api/im/agents/${encodeURIComponent(agentId)}/spec`, void 0, query);
+  }
+  async snapshot(agentId, options) {
+    return this._r("POST", `/api/im/agents/${encodeURIComponent(agentId)}/snapshot`, options ?? {});
+  }
+  async snapshots(agentId, options) {
+    const query = {};
+    if (options?.cursor) query.cursor = options.cursor;
+    if (options?.limit != null) query.limit = String(options.limit);
+    return this._r("GET", `/api/im/agents/${encodeURIComponent(agentId)}/snapshots`, void 0, query);
+  }
+  async restore(agentId, options) {
+    return this._r("POST", `/api/im/agents/${encodeURIComponent(agentId)}/restore`, options);
+  }
+  async publish(agentId, options) {
+    return this._r("POST", `/api/im/agents/${encodeURIComponent(agentId)}/publish`, options ?? {});
+  }
+  async listPacks(options) {
+    const query = {};
+    if (options?.q) query.q = options.q;
+    if (options?.curatedQuality) query.curatedQuality = options.curatedQuality;
+    if (options?.license) query.license = options.license;
+    if (options?.publisherDid) query.publisherDid = options.publisherDid;
+    if (options?.cursor) query.cursor = options.cursor;
+    if (options?.limit != null) query.limit = String(options.limit);
+    return this._r("GET", "/api/im/agent-packs", void 0, query);
+  }
+  async forkPack(packIdOrSlug, options) {
+    return this._r("POST", `/api/im/agent-packs/${encodeURIComponent(packIdOrSlug)}/fork`, options);
+  }
+  async deletePack(packIdOrSlug) {
+    return this._r("DELETE", `/api/im/agent-packs/${encodeURIComponent(packIdOrSlug)}`);
+  }
+};
 var EvolutionClient = class {
   constructor(_r) {
     this._r = _r;
@@ -3696,6 +3781,7 @@ var IMClient = class {
     this.knowledge = new KnowledgeLinkClient(request2);
     this.identity = new IdentityClient(request2);
     this.security = new SecurityClient(request2);
+    this.agents = new AgentsClient(request2);
     this.evolution = new EvolutionClient(request2);
     this.community = new CommunityHub(request2, communityHubConfig ?? void 0);
     this.files = new FilesClient(request2, wsBase, fetchFn, getAuthHeaders);
@@ -3761,6 +3847,9 @@ var PrismerClient = class {
     if (config.offline) {
       this._offlineManager = new OfflineManager(
         config.offline.storage,
+        // OfflineManager has a 4-arg RequestFn signature (legacy); the 5th
+        // opts param is dropped on the offline path until OfflineManager is
+        // upgraded. Online path forwards opts (see below).
         (m, p, b, q) => this._request(m, p, b, q),
         config.offline
       );
@@ -3768,23 +3857,28 @@ var PrismerClient = class {
         (err) => console.warn("[PrismerSDK] Offline storage init failed:", err)
       );
     }
-    let imRequest = this._offlineManager ? (m, p, b, q) => this._offlineManager.dispatch(m, p, b, q) : (m, p, b, q) => this._request(m, p, b, q);
+    let imRequest = this._offlineManager ? (m, p, b, q, _opts) => (
+      // Offline path: opts dropped (manager doesn't forward headers yet).
+      // Idempotency key is also stamped into the body JSON, so server-side
+      // dedup still works via the JSON field even without the header.
+      this._offlineManager.dispatch(m, p, b, q)
+    ) : (m, p, b, q, opts) => this._request(m, p, b, q, opts);
     if (config.identity) {
       const baseRequest = imRequest;
-      imRequest = (method, path5, body, query) => {
+      imRequest = (method, path5, body, query, opts) => {
         if (method === "POST" && path5.includes("/messages") && body) {
           const b = body;
           if (!b.signature && !b.skipSigning) {
             const ready = this._identityReady || Promise.resolve();
             return ready.then(() => {
               if (this._identity) {
-                return this._signAndSend(baseRequest, method, path5, b, query);
+                return this._signAndSend(baseRequest, method, path5, b, query, opts);
               }
-              return baseRequest(method, path5, body, query);
+              return baseRequest(method, path5, body, query, opts);
             });
           }
         }
-        return baseRequest(method, path5, body, query);
+        return baseRequest(method, path5, body, query, opts);
       };
     }
     this.im = new IMClient(
@@ -3806,9 +3900,9 @@ var PrismerClient = class {
     return this._identity;
   }
   /** Auto-sign a message body and send (v1.8.0 S1) */
-  async _signAndSend(baseRequest, method, path5, body, query) {
+  async _signAndSend(baseRequest, method, path5, body, query, opts) {
     if (this._identityReady) await this._identityReady;
-    if (!this._identity) return baseRequest(method, path5, body, query);
+    if (!this._identity) return baseRequest(method, path5, body, query, opts);
     const content = body.content || "";
     const contentHashBytes = new Uint8Array(
       await crypto.subtle.digest("SHA-256", new TextEncoder().encode(content))
@@ -3825,7 +3919,7 @@ var PrismerClient = class {
       contentHash,
       signature,
       signedAt: timestamp
-    }, query);
+    }, query, opts);
   }
   /** Build auth headers for raw HTTP requests (used by file upload) */
   _getAuthHeaders() {
@@ -3883,7 +3977,7 @@ var PrismerClient = class {
   // --------------------------------------------------------------------------
   // Internal request helper
   // --------------------------------------------------------------------------
-  async _request(method, path5, body, query, _isRetry) {
+  async _request(method, path5, body, query, opts, _isRetry) {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
@@ -3898,6 +3992,9 @@ var PrismerClient = class {
       if (this.imAgent) {
         headers["X-IM-Agent"] = this.imAgent;
       }
+      if (opts?.headers) {
+        for (const [k, v] of Object.entries(opts.headers)) headers[k] = v;
+      }
       const init = { method, headers, signal: controller.signal };
       if (body !== void 0) {
         headers["Content-Type"] = "application/json";
@@ -3907,10 +4004,10 @@ var PrismerClient = class {
       const data = await response.json();
       if (response.status === 401 && this.apiKey.startsWith("eyJ") && !_isRetry && !path5.includes("/token/refresh")) {
         try {
-          const refreshRes = await this._request("POST", "/api/im/token/refresh", void 0, void 0, true);
+          const refreshRes = await this._request("POST", "/api/im/token/refresh", void 0, void 0, void 0, true);
           if (refreshRes?.ok && refreshRes?.data?.token) {
             this.apiKey = refreshRes.data.token;
-            return this._request(method, path5, body, query, true);
+            return this._request(method, path5, body, query, opts, true);
           }
         } catch {
         }
@@ -7777,6 +7874,111 @@ function parseIntOpt2(value) {
   return n;
 }
 
+// src/commands/agent.ts
+function register13(parent, getIMClient2, _getAPIClient) {
+  const agent = parent.command("agent").description("Manage agent specs, snapshots, publish, and fork");
+  agent.command("spec <agent-id>").description("Read an AgentSpec 4-tuple").option("--workspace-id <id>", "Workspace scope").option("--json", "Output raw JSON response").action(async (agentId, opts) => {
+    const res = await getIMClient2().im.agents.spec(agentId, opts.workspaceId);
+    printOrExit(res, opts.json, (data) => {
+      console.log(`AgentSpec ${agentId}`);
+      console.log(`  identity: ${data.identity.displayName} (${data.identity.imUserId})`);
+      console.log(`  role:     ${data.definition.roleTemplateSlug ?? "custom"}`);
+      console.log(`  skills:   ${data.skills.length}`);
+      console.log(`  memory:   ${data.memory.scope}`);
+    });
+  });
+  agent.command("snapshot <agent-id>").description("Create an agent-level snapshot").option("--include-memory", "Include memory dump reference").option("--label <label>", "Snapshot label").option("--json", "Output raw JSON response").action(async (agentId, opts) => {
+    const res = await getIMClient2().im.agents.snapshot(agentId, {
+      includeMemory: Boolean(opts.includeMemory),
+      label: opts.label
+    });
+    printOrExit(res, opts.json, (data) => {
+      console.log(`Snapshot created: ${data.id}`);
+      console.log(`  agent:  ${data.agentImUserId}`);
+      console.log(`  memory: ${data.includeMemory ? "included" : "stripped"}`);
+      console.log(`  size:   ${data.sizeBytes ?? 0} bytes`);
+    });
+  });
+  agent.command("snapshots <agent-id>").description("List agent snapshots").option("-n, --limit <n>", "Max snapshots", "20").option("--json", "Output raw JSON response").action(async (agentId, opts) => {
+    const res = await getIMClient2().im.agents.snapshots(agentId, { limit: parseInt(opts.limit, 10) || 20 });
+    printOrExit(res, opts.json, (data) => {
+      const rows = data.items ?? [];
+      if (rows.length === 0) {
+        console.log("No snapshots.");
+        return;
+      }
+      for (const item of rows) {
+        console.log(`${item.id}	${item.createdAt}	memory=${item.includeMemory ? "yes" : "no"}	size=${item.sizeBytes ?? 0}`);
+      }
+    });
+  });
+  agent.command("restore <agent-id> <snapshot-id>").description("Restore agent definition and skills from a snapshot").option("--override-memory", "Restore memory reference when available").option("--json", "Output raw JSON response").action(async (agentId, snapshotId, opts) => {
+    const res = await getIMClient2().im.agents.restore(agentId, {
+      snapshotId,
+      overrideMemory: Boolean(opts.overrideMemory)
+    });
+    printOrExit(res, opts.json, () => {
+      console.log(`Restored ${agentId} from ${snapshotId}`);
+    });
+  });
+  agent.command("publish <agent-id>").description("Publish an agent as an Agent Pack").requiredOption("--slug <slug>", "Agent Pack slug").option("--version <version>", "Package version", "1.0.0").option("--license <license>", "Package license", "proprietary").option("--title <title>", "Display title metadata").option("--description <description>", "Description metadata").option("--json", "Output raw JSON response").action(async (agentId, opts) => {
+    const res = await getIMClient2().im.agents.publish(agentId, {
+      slug: opts.slug,
+      version: opts.version,
+      license: opts.license,
+      metadata: {
+        ...opts.title ? { title: opts.title } : {},
+        ...opts.description ? { description: opts.description } : {}
+      },
+      stripMemory: true
+    });
+    printOrExit(res, opts.json, (data) => {
+      console.log(`Agent Pack published: ${data.slug}@${data.version}`);
+      console.log(`  id:        ${data.id}`);
+      console.log(`  publisher: ${data.publisherDid}`);
+    });
+  });
+  agent.command("packs").description("List published Agent Packs").option("-q, --query <query>", "Search query").option("-n, --limit <n>", "Max packs", "20").option("--json", "Output raw JSON response").action(async (opts) => {
+    const res = await getIMClient2().im.agents.listPacks({
+      q: opts.query,
+      limit: parseInt(opts.limit, 10) || 20
+    });
+    printOrExit(res, opts.json, (data) => {
+      const rows = data.items ?? [];
+      if (rows.length === 0) {
+        console.log("No Agent Packs.");
+        return;
+      }
+      for (const item of rows) {
+        console.log(`${item.slug}@${item.version}	${item.id}	${item.license}	${item.publisherDid}`);
+      }
+    });
+  });
+  agent.command("fork <pack-id-or-slug>").description("Fork an Agent Pack into a workspace").requiredOption("--workspace-id <id>", "Target workspace id").option("--display-name <name>", "New agent display name").option("--json", "Output raw JSON response").action(async (packId, opts) => {
+    const res = await getIMClient2().im.agents.forkPack(packId, {
+      targetWorkspaceId: opts.workspaceId,
+      displayName: opts.displayName
+    });
+    printOrExit(res, opts.json, (data) => {
+      console.log(`Forked Agent Pack ${packId}`);
+      console.log(`  new agent: ${data.newImUserId}`);
+      console.log(`  did:       ${data.newDid ?? "not issued"}`);
+    });
+  });
+}
+function printOrExit(res, json, print) {
+  if (!res.ok || !res.data) {
+    process.stderr.write(`Error: ${res.error?.message || "request failed"}
+`);
+    process.exit(1);
+  }
+  if (json) {
+    process.stdout.write(JSON.stringify(res.data, null, 2) + "\n");
+    return;
+  }
+  print(res.data);
+}
+
 // src/daemon.ts
 var fs3 = __toESM(require("fs"));
 var path3 = __toESM(require("path"));
@@ -8701,6 +8903,7 @@ register9(program, getIMClient, getAPIClient);
 register10(program, getIMClient, getAPIClient);
 register11(program, getIMClient, getAPIClient);
 register12(program, getIMClient, getAPIClient);
+register13(program, getIMClient, getAPIClient);
 program.command("send").description("Send a direct message (shortcut for: im send)").argument("<user-id-or-username>", "Target user/agent IM user ID (or username with --by-username)").argument("<message>", "Message content").option("-t, --type <type>", "Message type: text, markdown, code, etc.", "text").option("--reply-to <id>", "Reply to a message ID").option("--conversation-id <id>", "Pin message to a specific conversation/session").option("--asset-id <id>", "Attach a previously uploaded asset (treats type as file)").option("--by-username", "Treat the first argument as a username; resolve to imUserId first").option("--json", "JSON output").action(async (target, message, opts) => {
   const client = getIMClient();
   let userId = target;