@ziggs-ai/api-client 0.42.1 → 0.42.3

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+## 0.42.3
+
+## 0.42.2
+
+- `bucket_send` sends a page: `page` (a full HTML document) and `pageName` save the HTML as a file, and carry that exact version as the message's `page` (with its sha256); whoever reads the message opens the page, so nothing is shared. Without `replyTo` the message starts a thread of its own, which shows as that page; another page sent in the thread (`replyTo`) is its new version, and the tool says a new page names no `replyTo`, even in answer to someone. The result carries `page: {artifactId, address}`, the address being `/pages/<thread>`.
+
 ## 0.42.1
 
 ## 0.42.0

package/dist/capabilities/buckets.js

@@ -1,4 +1,5 @@
 import { BucketsClient, BUCKET_ITEM_KINDS, } from '../http/BucketsClient.js';
+import { ArtifactsClient } from '../http/ArtifactsClient.js';
 import { fullCreds, rethrowWithContext } from './types.js';
 /**
  * The bucket operations as tools, one per route.
@@ -236,20 +237,25 @@ export const bucketSendCapability = {
     names: { sdk: 'bucket_send', mcp: 'ziggs_bucket_send' },
     title: 'Send in a bucket',
     descriptions: {
-        sdk: "Send a message inside a bucket. Its readers are the bucket's people; name recipients among them. To reach anyone else, add them with bucket_add_members first. A request wakes the agents it is delivered to.",
+        sdk: "Send a message inside a bucket. Its readers are the bucket's people; name recipients among them. To reach anyone else, add them with bucket_add_members first. A request wakes the agents it is delivered to. With page, the message carries an HTML page: its thread shows as that page.",
     },
     annotation: 'destructive',
     needsAgentId: true,
     params: {
         bucketId: BUCKET_ID,
         text: { type: 'string', required: true },
+        page: {
+            type: 'string',
+            description: "A full HTML document (<!DOCTYPE html>), saved as a file that goes with the message. Without replyTo it starts a thread of its own, shown as the page; with replyTo that page's first message, it replaces that page.",
+        },
+        pageName: { type: 'string', description: 'Short, stable name of the page.' },
         recipients: {
             type: 'array',
             items: { type: 'string' },
             description: 'Who is told, among the bucket\'s people. Under work, name at least one person the work is with.',
         },
         intent: { type: 'string', enum: ['fyi', 'request'] },
-        replyTo: { type: 'string' },
+        replyTo: { type: 'string', description: 'The message this answers. Not for a new page.' },
         operationId: { type: 'string', description: 'Reuse on retry.' },
         agreementId: {
             type: 'string',
@@ -257,7 +263,7 @@ export const bucketSendCapability = {
         },
         taskId: { type: 'string', description: 'The task under agreementId this is about.' },
     },
-    handler: (args, env) => run('bucket_send', () => {
+    handler: (args, env) => run('bucket_send', async () => {
         const text = args['text'];
         if (typeof text !== 'string' || !text.trim())
             throw new Error('text is required');
@@ -267,17 +273,54 @@ export const bucketSendCapability = {
         const replyTo = args['replyTo'];
         if (replyTo !== undefined && (typeof replyTo !== 'string' || !replyTo.trim()))
             throw new Error('replyTo is a message id');
-        const operationId = args['operationId'];
-        return client(env).sendMessage(bucketId(args), {
-            operationId: typeof operationId === 'string' && operationId.trim() ? operationId.trim() : `bucket-send-${globalThis.crypto.randomUUID()}`,
+        const named = args['operationId'];
+        const operationId = typeof named === 'string' && named.trim() ? named.trim() : `bucket-send-${globalThis.crypto.randomUUID()}`;
+        const page = await pageOf(args, env, operationId);
+        const sent = await client(env).sendMessage(bucketId(args), {
+            operationId,
             content: { text },
             deliveries: { kind: 'explicit', principalIds: principals(args['recipients'], 'recipients') ?? [] },
             intent,
             ...(typeof replyTo === 'string' ? { relationships: { replyToMessageId: replyTo.trim() } } : {}),
             ...mandateOf(args, env),
+            // The message carries the page. Without replyTo it starts a thread of
+            // its own. Whoever reads the message opens the page: no share needed.
+            ...(page ? { page } : {}),
         });
+        return page ? { ...sent, page: { artifactId: page.id, address: `/pages/${sent.message.rootMessageId}` } } : sent;
     }),
 };
+/**
+ * The page a message carries: the HTML saved as a file, then linked by its
+ * exact version. The file is saved under the same retry identity as the
+ * message, so a retry links the same file.
+ */
+async function pageOf(args, env, operationId) {
+    const html = args['page'];
+    if (html === undefined)
+        return null;
+    if (typeof html !== 'string' || !/^\s*(?:<!doctype\s+html|<html)(?:\s|>)/i.test(html)) {
+        throw new Error('page is a full HTML document starting with <!DOCTYPE html>');
+    }
+    const name = typeof args['pageName'] === 'string' ? args['pageName'].trim() : '';
+    if (!name)
+        throw new Error('pageName is required with page');
+    const creds = fullCreds(env);
+    // The stored text is trimmed; the link names exactly what is stored.
+    const text = html.trim();
+    const { artifactId } = await new ArtifactsClient(creds.operatorKey, creds.agentId).writeStrict({
+        text,
+        name,
+        contentType: 'document',
+        visibility: 'address',
+        serviceAgreementId: env.serviceAgreementId,
+        idempotencyKey: `page-${operationId}`,
+    });
+    if (!artifactId)
+        throw new Error('The page file was not saved');
+    const { createHash } = await import('node:crypto');
+    return { kind: 'artifact', id: artifactId, sha256: createHash('sha256').update(text, 'utf8').digest('hex') };
+}
 /**
  * The work a send is under. Work under a hire keeps its mandate: the server
  * refuses a run's send that drops it. Named in the call, else the agreement

package/dist/http/BucketsClient.d.ts

@@ -122,8 +122,17 @@ export interface BucketContents {
     /** Items held that the reader cannot read here, as they ask now. */
     outOfReach: number;
 }
-/** A message sent inside a bucket: its readers are the bucket's people. */
-export type BucketMessage = Omit<MessageCommand, 'audience'>;
+/**
+ * A message sent inside a bucket: its readers are the bucket's people. `page`
+ * is the HTML file it carries, by its exact version (contracts 0.49).
+ */
+export type BucketMessage = Omit<MessageCommand, 'audience'> & {
+    page?: {
+        kind: 'artifact';
+        id: string;
+        sha256: string;
+    };
+};
 export interface BucketItemPage {
     /** Items everyone it is for can read right now. */
     items: Array<BucketItemRef & {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/api-client",
-  "version": "0.42.1",
+  "version": "0.42.3",
   "description": "HTTP and WebSocket client for the Ziggs backend API",
   "homepage": "https://ziggsai.com/docs",
   "bugs": {
@@ -31,7 +31,7 @@
     "test:watch": "node --import tsx/esm --test --watch test/*.test.ts"
   },
   "dependencies": {
-    "@ziggs-ai/contracts": "0.49.0",
+    "@ziggs-ai/contracts": "0.49.1",
     "socket.io-client": "^4.7.0"
   },
   "keywords": [