@ziggs-ai/api-client 0.40.4 → 0.40.5

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+## 0.40.5
+
+- An artifact reaches people only by being added to a bucket. The `artifact_share` tool, `shareArtifactCapability` and `ContextGrantsClient.shareArtifact` are removed, `context_delegate` no longer takes `scopeKind: 'artifact'`, and `link_list` no longer suggests sharing an artifact. The server refuses artifact grants issued or passed on directly.
+- Buckets. A bucket is pointers to items (messages, artifacts, tasks, agreements) and to who it is for; it holds no permission, and whether everyone in it can read each item is computed from the items' own grants when asked. Every message is sent through a bucket, and the bucket points at it; no message names its bucket. `BucketsClient` covers the operations: `listMine(item)` finds the buckets holding an item, the first being where a message was sent; `contents` reads what is in a bucket as you can read it now, under the selected run; `sendMessage` sends inside a bucket to its people, under the selected run; `addMembers` takes `onMisfit: 'share' | 'split'`, where split leaves the bucket as it is and starts a narrower one with the newcomers and only what everyone can read; `join` brings another bucket's people and items in. The bucket tools are `bucket_create`, `bucket_list`, `bucket_read`, `bucket_insert`, `bucket_remove`, `bucket_duplicate`, `bucket_move` (into another bucket, or a new one when given a name), `bucket_add_members`, `bucket_join`, `bucket_send`, `bucket_remove_member`, `bucket_rename` and `bucket_delete`.
+- A refusal's `impact` is carried through `describeOperationError`, next to `choices` and `recovery`. A bucket add or join that someone cannot read everything in now lists the misfits (`impact.misfits`, with any shares made in `impact.shared`) and the onMisfit values left (`choices`); a reply that leaves someone in its bucket out names the bucket and who is missing (`impact.bucketId`, `impact.missing`).
+
 ## 0.40.4
 
 - `InboxEnvelope.bellAt`: the latest delivery a read answered. `getInbox({ seen })` passes it back so a held read answers only mail delivered after it.

package/dist/capabilities/artifacts.d.ts

@@ -46,17 +46,6 @@ export interface UnsearchedContext {
  * scopes that were never opened. `coverage` sits between them naming what ran.
  */
 export declare const findArtifactsCapability: CapabilityDefinition;
-/**
- * hand one artifact you authored to one other agent.
- *
- * Deliberately not part of `context_delegate`: there is no parent grant to
- * attenuate here. An agent holds no grant over its own output — authorship is
- * the authority, and it belongs to the agent's owner, which is why a receiver
- * outside that owner's trust boundary needs their approval. What counts as
- * "inside" is the shared new-party policy, not a local rule: same owner, same
- * org, or an active agent link.
- */
-export declare const shareArtifactCapability: CapabilityDefinition;
 /**
  * attach an artifact you already have to a chat, a task, or an agreement.
  *
@@ -64,7 +53,7 @@ export declare const shareArtifactCapability: CapabilityDefinition;
  * by itself: it puts the artifact inside the container, and that container's
  * audience can read it from then on. Use this to publish to a room, bind a
  * deliverable to a task, or restore agreement scope after a free-standing
- * record; use artifact_share to hand it to ONE agent instead.
+ * record. To give it to someone, add it to a bucket with them.
  */
 export declare const attachArtifactCapability: CapabilityDefinition;
 /**

package/dist/capabilities/artifacts.js

@@ -1,6 +1,5 @@
 import { SOURCES_PARAM, sourcesArg } from './sources.js';
 import { ARTIFACT_FILE_FORMATS, ArtifactsClient, } from '../http/ArtifactsClient.js';
-import { ContextGrantsClient } from '../http/ContextGrantsClient.js';
 import { ContextDiscoveryClient, } from '../http/ContextDiscoveryClient.js';
 import { fullCreds } from './types.js';
 import { LIST_FIELDS_PARAM, listedFieldNote, parseListFields, pickListedRows } from './listedFields.js';
@@ -328,18 +327,6 @@ const OPEN_ID_FIELD = {
     artifact: 'artifactId',
     task: 'taskId',
 };
-function pendingAccessReceipt(result, extra) {
-    return {
-        ...extra,
-        ok: false,
-        outcome: 'pending',
-        status: 'pending_approval',
-        state: 'requested',
-        recoverable: true,
-        agreementId: result.agreementId,
-        ownerId: result.ownerId,
-    };
-}
 /**
  * The locked scopes near a search that found nothing.
  *
@@ -449,73 +436,6 @@ export const findArtifactsCapability = {
         return { ...shaped, notSearched: await unsearchedContext(env) };
     },
 };
-/**
- * hand one artifact you authored to one other agent.
- *
- * Deliberately not part of `context_delegate`: there is no parent grant to
- * attenuate here. An agent holds no grant over its own output — authorship is
- * the authority, and it belongs to the agent's owner, which is why a receiver
- * outside that owner's trust boundary needs their approval. What counts as
- * "inside" is the shared new-party policy, not a local rule: same owner, same
- * org, or an active agent link.
- */
-export const shareArtifactCapability = {
-    key: 'artifact_share',
-    names: { sdk: 'artifact_share', mcp: 'ziggs_artifact_share' },
-    title: 'Share an artifact',
-    descriptions: {
-        sdk: 'Share an artifact you authored with another agent — just that artifact, no chat or agreement. An agent already connected to you (same owner, same org, or an active link) gets it immediately; anyone else is offered to your owner to approve.',
-    },
-    annotation: 'destructive',
-    params: {
-        artifactId: {
-            type: 'string',
-            required: true,
-            description: 'The artifact to share — you must be its author',
-        },
-        holderId: { type: 'string', required: true, description: 'Agent id that receives it' },
-        expiresAt: {
-            type: 'string',
-            description: 'ISO-8601 expiry; omit for the default grant lifetime',
-        },
-        idempotencyKey: {
-            type: 'string',
-            description: 'Replay the same share. Same key and payload recover the original request; the same key with a different payload is a conflict, not a second share.',
-        },
-    },
-    needsAgentId: true,
-    handler: async (args, env) => {
-        if ('addressId' in args)
-            throw new Error('addressId is retired; use explicit work or an exact message artifact reference');
-        const creds = fullCreds(env);
-        const artifactId = args['artifactId'];
-        if (!artifactId)
-            throw new Error('artifactId is required');
-        const holderId = args['holderId'];
-        if (!holderId)
-            throw new Error('holderId is required');
-        const result = await new ContextGrantsClient(creds.operatorKey, creds.agentId, env.baseUrl).shareArtifact(artifactId, {
-            holderId,
-            expiresAt: args['expiresAt'],
-        }, {
-            idempotencyKey: typeof args['idempotencyKey'] === 'string'
-                ? args['idempotencyKey']
-                : undefined,
-        });
-        if (result.status === 'pending_approval') {
-            return pendingAccessReceipt(result, {
-                ...result,
-                note: `Requested, not granted — ${result.ownerId ?? 'the owner'} must approve agreement ${result.agreementId}. Recover that id; do not open a second card.`,
-            });
-        }
-        return {
-            ok: true,
-            outcome: 'ok',
-            ...result,
-            note: `${holderId} can now read artifact ${artifactId} with via=artifact:${artifactId}.`,
-        };
-    },
-};
 /**
  * attach an artifact you already have to a chat, a task, or an agreement.
  *
@@ -523,14 +443,14 @@ export const shareArtifactCapability = {
  * by itself: it puts the artifact inside the container, and that container's
  * audience can read it from then on. Use this to publish to a room, bind a
  * deliverable to a task, or restore agreement scope after a free-standing
- * record; use artifact_share to hand it to ONE agent instead.
+ * record. To give it to someone, add it to a bucket with them.
  */
 export const attachArtifactCapability = {
     key: 'artifact_attach',
     names: { sdk: 'artifact_attach', mcp: 'ziggs_artifact_attach' },
     title: 'Attach to a task or agreement',
     descriptions: {
-        sdk: 'Attach an artifact you can read to a task or agreement. To reference it in a message use message_send with an exact artifact reference; that reference grants no access. Task/agreement links remain subject to their work and source-disclosure policies. Use artifact_share to give it to one specific agent instead.',
+        sdk: 'Attach an artifact you can read to a task or agreement. To reference it in a message use message_send with an exact artifact reference; that reference grants no access. Task/agreement links remain subject to their work and source-disclosure policies. To give it to someone, add it to a bucket with them.',
     },
     annotation: 'destructive',
     params: {
@@ -818,7 +738,6 @@ export const ARTIFACT_CAPABILITIES = [
     recordArtifactCapability,
     listArtifactsCapability,
     findArtifactsCapability,
-    shareArtifactCapability,
     attachArtifactCapability,
     reviewArtifactContributionCapability,
     contributeArtifactCapability,

package/dist/capabilities/buckets.d.ts

@@ -0,0 +1,15 @@
+import { type CapabilityDefinition } from './types.js';
+export declare const bucketCreateCapability: CapabilityDefinition;
+export declare const bucketListCapability: CapabilityDefinition;
+export declare const bucketReadCapability: CapabilityDefinition;
+export declare const bucketInsertCapability: CapabilityDefinition;
+export declare const bucketMoveCapability: CapabilityDefinition;
+export declare const bucketRemoveCapability: CapabilityDefinition;
+export declare const bucketDuplicateCapability: CapabilityDefinition;
+export declare const bucketAddMembersCapability: CapabilityDefinition;
+export declare const bucketJoinCapability: CapabilityDefinition;
+export declare const bucketSendCapability: CapabilityDefinition;
+export declare const bucketRemoveMemberCapability: CapabilityDefinition;
+export declare const bucketRenameCapability: CapabilityDefinition;
+export declare const bucketDeleteCapability: CapabilityDefinition;
+export declare const BUCKET_CAPABILITIES: CapabilityDefinition[];

package/dist/capabilities/buckets.js

@@ -0,0 +1,353 @@
+import { BucketsClient, BUCKET_ITEM_KINDS, } from '../http/BucketsClient.js';
+import { fullCreds, rethrowWithContext } from './types.js';
+/**
+ * The bucket operations as tools, one per route.
+ *
+ * A bucket is a high-level way to work with context: pointers to items and to
+ * who it is for, with no permission of its own. Whether everyone it is for can
+ * read each item is computed from the items' own grants whenever it is asked;
+ * what does not fit comes back as `misfits`, and the caller chooses to share
+ * or to split. Every message is sent through a bucket.
+ */
+const BUCKET_ID = {
+    type: 'string',
+    required: true,
+};
+const ITEMS = {
+    type: 'array',
+    required: true,
+    description: '{kind, id}, up to 100.',
+    items: {
+        type: 'object',
+        properties: {
+            kind: { type: 'string', enum: [...BUCKET_ITEM_KINDS] },
+            id: { type: 'string' },
+        },
+        required: ['kind', 'id'],
+    },
+};
+const SHARE = {
+    type: 'boolean',
+    description: 'Share misfits first.',
+};
+const AUDIENCE = {
+    type: 'array',
+    description: 'Other person, agent or workspace ids.',
+    items: { type: 'string' },
+};
+function client(env) {
+    const creds = fullCreds(env);
+    return new BucketsClient(creds.operatorKey, creds.agentId || undefined);
+}
+function bucketId(args) {
+    const id = args['bucketId'];
+    if (typeof id !== 'string' || !id.trim())
+        throw new Error('bucketId is required');
+    return id.trim();
+}
+function items(args) {
+    const raw = args['items'];
+    if (!Array.isArray(raw) || raw.length === 0)
+        throw new Error('items must be a non-empty list of {kind, id}');
+    return raw.map((entry) => {
+        const item = entry;
+        if (!BUCKET_ITEM_KINDS.includes(item?.kind) || typeof item.id !== 'string' || !item.id.trim()) {
+            throw new Error(`Each item is {kind, id} with kind one of ${BUCKET_ITEM_KINDS.join(', ')}`);
+        }
+        return { kind: item.kind, id: item.id.trim() };
+    });
+}
+function principals(raw, field) {
+    if (raw === undefined)
+        return undefined;
+    if (!Array.isArray(raw) || raw.some((id) => typeof id !== 'string' || !id.trim())) {
+        throw new Error(`${field} must be a list of ids`);
+    }
+    return raw.map((id) => id.trim());
+}
+async function run(label, work) {
+    try {
+        return await work();
+    }
+    catch (e) {
+        rethrowWithContext(e, label);
+    }
+}
+export const bucketCreateCapability = {
+    key: 'bucket_create',
+    names: { sdk: 'bucket_create', mcp: 'ziggs_bucket_create' },
+    title: 'Create a bucket',
+    descriptions: {
+        sdk: 'Create a bucket: a working set whose whole audience can read every item in it. You are always in it. Items given here go in exactly as bucket_insert puts them.',
+    },
+    annotation: 'write',
+    needsAgentId: true,
+    params: {
+        name: { type: 'string', required: true },
+        audience: AUDIENCE,
+        items: { ...ITEMS, required: false },
+        share: SHARE,
+    },
+    handler: (args, env) => run('bucket_create', () => client(env).create({
+        name: String(args['name'] ?? ''),
+        ...(args['audience'] !== undefined ? { audience: principals(args['audience'], 'audience') } : {}),
+        ...(args['items'] !== undefined ? { items: items(args) } : {}),
+        ...(args['share'] === true ? { share: true } : {}),
+    })),
+};
+export const bucketListCapability = {
+    key: 'bucket_list',
+    names: { sdk: 'bucket_list', mcp: 'ziggs_bucket_list' },
+    title: 'List buckets',
+    descriptions: { sdk: 'List the buckets you are in: name, audience, revision and item count.' },
+    annotation: 'read-only',
+    needsAgentId: true,
+    params: {},
+    handler: (_args, env) => run('bucket_list', () => client(env).listMine()),
+};
+export const bucketReadCapability = {
+    key: 'bucket_read',
+    names: { sdk: 'bucket_read', mcp: 'ziggs_bucket_read' },
+    title: 'Read a bucket',
+    descriptions: {
+        sdk: 'Read one bucket and a page of its items, newest first. Items are references; read each one with its own tool (message_read, open). Pass nextCursor as before for the next page.',
+    },
+    annotation: 'read-only',
+    needsAgentId: true,
+    params: {
+        bucketId: BUCKET_ID,
+        before: { type: 'string', description: 'Cursor from the previous page.' },
+        limit: { type: 'number' },
+    },
+    handler: (args, env) => run('bucket_read', async () => {
+        const id = bucketId(args);
+        const c = client(env);
+        const [bucket, page] = await Promise.all([
+            c.get(id),
+            c.items(id, {
+                ...(typeof args['before'] === 'string' ? { before: args['before'] } : {}),
+                ...(typeof args['limit'] === 'number' ? { limit: args['limit'] } : {}),
+            }),
+        ]);
+        return { bucket, ...page };
+    }),
+};
+export const bucketInsertCapability = {
+    key: 'bucket_insert',
+    names: { sdk: 'bucket_insert', mcp: 'ziggs_bucket_insert' },
+    title: 'Put items in a bucket',
+    descriptions: {
+        sdk: 'Put items in a bucket. Each goes in only if everyone in its audience can read it; the rest come back as misfits, naming who cannot read them when you can read them yourself. With share, an item some members cannot read is first shared with them as you, under the ordinary share rules.',
+    },
+    annotation: 'write',
+    needsAgentId: true,
+    params: { bucketId: BUCKET_ID, items: ITEMS, share: SHARE },
+    handler: (args, env) => run('bucket_insert', () => client(env).insert(bucketId(args), items(args), args['share'] === true ? { share: true } : {})),
+};
+export const bucketMoveCapability = {
+    key: 'bucket_move',
+    names: { sdk: 'bucket_move', mcp: 'ziggs_bucket_move' },
+    title: 'Move bucket items',
+    descriptions: {
+        sdk: "Move items out of a bucket into another one (to), or into a new one (name, and audience when not this bucket's): a split. Each moves only if that bucket's audience can all read it; misfits stay where they are.",
+    },
+    annotation: 'write',
+    needsAgentId: true,
+    params: {
+        bucketId: BUCKET_ID,
+        items: ITEMS,
+        to: { type: 'string', description: 'An existing bucket.' },
+        name: { type: 'string', description: 'A new bucket.' },
+        audience: { ...AUDIENCE, description: "With name. Left out: this bucket's." },
+    },
+    handler: (args, env) => run('bucket_move', () => {
+        const to = args['to'];
+        const name = args['name'];
+        const hasTo = typeof to === 'string' && !!to.trim();
+        const hasName = typeof name === 'string' && !!name.trim();
+        if (hasTo === hasName)
+            throw new Error('Give to (an existing bucket) or name (a new one), not both');
+        if (hasTo)
+            return client(env).move(bucketId(args), { to: to.trim(), items: items(args) });
+        return client(env).split(bucketId(args), {
+            items: items(args),
+            name: name.trim(),
+            ...(args['audience'] !== undefined ? { audience: principals(args['audience'], 'audience') } : {}),
+        });
+    }),
+};
+export const bucketRemoveCapability = {
+    key: 'bucket_remove',
+    names: { sdk: 'bucket_remove', mcp: 'ziggs_bucket_remove' },
+    title: 'Remove bucket items',
+    descriptions: { sdk: 'Take items out of a bucket. The items themselves are untouched; only the reference leaves.' },
+    annotation: 'write',
+    needsAgentId: true,
+    params: { bucketId: BUCKET_ID, items: ITEMS },
+    handler: (args, env) => run('bucket_remove', () => client(env).remove(bucketId(args), items(args))),
+};
+export const bucketDuplicateCapability = {
+    key: 'bucket_duplicate',
+    names: { sdk: 'bucket_duplicate', mcp: 'ziggs_bucket_duplicate' },
+    title: 'Duplicate a bucket',
+    descriptions: {
+        sdk: "Copy items into a new bucket for another audience, for example the part you expose as someone's provider. The original stays whole. Items left out means all of them. Each goes in as bucket_insert puts it.",
+    },
+    annotation: 'write',
+    needsAgentId: true,
+    params: {
+        bucketId: BUCKET_ID,
+        name: { type: 'string', required: true },
+        audience: { ...AUDIENCE, description: "Left out: this bucket's." },
+        items: { ...ITEMS, required: false, description: 'Left out: all.' },
+        share: SHARE,
+    },
+    handler: (args, env) => run('bucket_duplicate', () => client(env).duplicate(bucketId(args), {
+        name: String(args['name'] ?? ''),
+        ...(args['audience'] !== undefined ? { audience: principals(args['audience'], 'audience') } : {}),
+        ...(args['items'] !== undefined ? { items: items(args) } : {}),
+        ...(args['share'] === true ? { share: true } : {}),
+    })),
+};
+export const bucketAddMembersCapability = {
+    key: 'bucket_add_members',
+    names: { sdk: 'bucket_add_members', mcp: 'ziggs_bucket_add_members' },
+    title: 'Add to a bucket',
+    descriptions: {
+        sdk: "Add people, agents or workspaces to a bucket's audience. If one cannot read an item, nothing changes until you choose: onMisfit share gives them access first, under the ordinary share rules; split leaves this bucket as it is and starts a narrower one with them and only what everyone can read.",
+    },
+    annotation: 'write',
+    needsAgentId: true,
+    params: {
+        bucketId: BUCKET_ID,
+        principalIds: { type: 'array', required: true, description: 'Person, agent or workspace ids.', items: { type: 'string' } },
+        onMisfit: { type: 'string', enum: ['share', 'split'], description: 'Left out: stop and list misfits.' },
+    },
+    handler: (args, env) => run('bucket_add_members', () => {
+        const choice = args['onMisfit'];
+        if (choice !== undefined && choice !== 'share' && choice !== 'split')
+            throw new Error('onMisfit is share or split');
+        return client(env).addMembers(bucketId(args), principals(args['principalIds'], 'principalIds') ?? [], choice ? { onMisfit: choice } : {});
+    }),
+};
+export const bucketJoinCapability = {
+    key: 'bucket_join',
+    names: { sdk: 'bucket_join', mcp: 'ziggs_bucket_join' },
+    title: 'Join buckets',
+    descriptions: {
+        sdk: "Bring another bucket's people and items into this one. If someone then cannot read an item, nothing changes until you pass onMisfit share. The other bucket stays.",
+    },
+    annotation: 'write',
+    needsAgentId: true,
+    params: {
+        bucketId: BUCKET_ID,
+        from: { type: 'string', required: true },
+        onMisfit: { type: 'string', enum: ['share'] },
+    },
+    handler: (args, env) => run('bucket_join', () => {
+        const from = args['from'];
+        if (typeof from !== 'string' || !from.trim())
+            throw new Error('from is required');
+        const choice = args['onMisfit'];
+        if (choice !== undefined && choice !== 'share')
+            throw new Error('onMisfit is share');
+        return client(env).join(bucketId(args), { from: from.trim(), ...(choice ? { onMisfit: 'share' } : {}) });
+    }),
+};
+export const bucketSendCapability = {
+    key: 'bucket_send',
+    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.",
+    },
+    annotation: 'destructive',
+    needsAgentId: true,
+    params: {
+        bucketId: BUCKET_ID,
+        text: { type: 'string', required: true },
+        recipients: { type: 'array', items: { type: 'string' } },
+        intent: { type: 'string', enum: ['fyi', 'request'] },
+        replyTo: { type: 'string' },
+        operationId: { type: 'string', description: 'Reuse on retry.' },
+    },
+    handler: (args, env) => run('bucket_send', () => {
+        const text = args['text'];
+        if (typeof text !== 'string' || !text.trim())
+            throw new Error('text is required');
+        const intent = args['intent'] ?? 'fyi';
+        if (intent !== 'fyi' && intent !== 'request')
+            throw new Error('intent is fyi or request');
+        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()}`,
+            content: { text },
+            deliveries: { kind: 'explicit', principalIds: principals(args['recipients'], 'recipients') ?? [] },
+            intent,
+            ...(typeof replyTo === 'string' ? { relationships: { replyToMessageId: replyTo.trim() } } : {}),
+        });
+    }),
+};
+export const bucketRemoveMemberCapability = {
+    key: 'bucket_remove_member',
+    names: { sdk: 'bucket_remove_member', mcp: 'ziggs_bucket_remove_member' },
+    title: 'Remove from a bucket',
+    descriptions: {
+        sdk: "Take one person, agent or workspace out of a bucket's audience. The bucket's creator does this, and stays.",
+    },
+    annotation: 'destructive',
+    needsAgentId: true,
+    params: {
+        bucketId: BUCKET_ID,
+        principalId: { type: 'string', required: true },
+    },
+    handler: (args, env) => run('bucket_remove_member', () => {
+        const principalId = args['principalId'];
+        if (typeof principalId !== 'string' || !principalId.trim())
+            throw new Error('principalId is required');
+        return client(env).removeMember(bucketId(args), principalId.trim());
+    }),
+};
+export const bucketRenameCapability = {
+    key: 'bucket_rename',
+    names: { sdk: 'bucket_rename', mcp: 'ziggs_bucket_rename' },
+    title: 'Rename a bucket',
+    descriptions: { sdk: "Rename a bucket. The bucket's creator does this." },
+    annotation: 'write',
+    needsAgentId: true,
+    params: {
+        bucketId: BUCKET_ID,
+        name: { type: 'string', required: true },
+    },
+    handler: (args, env) => run('bucket_rename', () => client(env).rename(bucketId(args), String(args['name'] ?? ''))),
+};
+export const bucketDeleteCapability = {
+    key: 'bucket_delete',
+    names: { sdk: 'bucket_delete', mcp: 'ziggs_bucket_delete' },
+    title: 'Delete a bucket',
+    descriptions: {
+        sdk: "Delete a bucket. The items themselves are untouched; only the bucket and its pointers go. The bucket's creator does this.",
+    },
+    annotation: 'destructive',
+    needsAgentId: true,
+    params: { bucketId: BUCKET_ID },
+    handler: (args, env) => run('bucket_delete', () => client(env).delete(bucketId(args))),
+};
+export const BUCKET_CAPABILITIES = [
+    bucketCreateCapability,
+    bucketListCapability,
+    bucketReadCapability,
+    bucketInsertCapability,
+    bucketRemoveCapability,
+    bucketDuplicateCapability,
+    bucketMoveCapability,
+    bucketAddMembersCapability,
+    bucketJoinCapability,
+    bucketSendCapability,
+    bucketRemoveMemberCapability,
+    bucketRenameCapability,
+    bucketDeleteCapability,
+];

package/dist/capabilities/context.js

@@ -173,18 +173,21 @@ export const contextDiscoverGrantableCapability = {
             })) };
     },
 };
+/** What a grant may be narrowed to when passed on. An artifact is not among
+ * them: it reaches people only by being added to a bucket. */
+const DELEGABLE_SCOPE_KINDS = GRANT_SCOPE_KINDS.filter((kind) => kind !== 'artifact');
 export const contextDelegateCapability = {
     key: 'context_delegate',
     names: { sdk: 'context_delegate', mcp: 'ziggs_context_delegate' },
     title: 'Pass on a narrower grant',
     descriptions: {
-        sdk: 'Delegate a narrower child context grant (tighter scope, shorter expiry, or from-now). Holder-only. Delegating a grant whose original owner is another party opens an approval request rather than minting immediately (status: pending_approval).',
+        sdk: 'Delegate a narrower child context grant (tighter scope, shorter expiry, or from-now). Holder-only. Delegating a grant whose original owner is another party opens an approval request rather than minting immediately (status: pending_approval). An artifact is not passed on this way: add it to a bucket.',
     },
     annotation: 'write',
     params: {
         parentGrantId: { type: 'string', required: true },
         holderId: { type: 'string', required: true, description: 'Agent receiving the delegated grant' },
-        scopeKind: { type: 'string', required: true, enum: GRANT_SCOPE_KINDS },
+        scopeKind: { type: 'string', required: true, enum: DELEGABLE_SCOPE_KINDS },
         scopeId: { type: 'string', required: true },
         temporal: {
             type: 'string',
@@ -210,8 +213,8 @@ export const contextDelegateCapability = {
             throw new Error('temporal must be from-now or from-start');
         }
         const scopeKind = args['scopeKind'];
-        if (!GRANT_SCOPE_KINDS.includes(scopeKind)) {
-            throw new Error(`scopeKind must be one of ${GRANT_SCOPE_KINDS.join(', ')}`);
+        if (!DELEGABLE_SCOPE_KINDS.includes(scopeKind)) {
+            throw new Error(`scopeKind must be one of ${DELEGABLE_SCOPE_KINDS.join(', ')}; an artifact is shared by adding it to a bucket`);
         }
         // #6 — an org scope may be named rather than pasted as org_… id.
         let scopeId = args['scopeId'];

package/dist/capabilities/grants.js

@@ -42,7 +42,7 @@ export const listGrantsCapability = {
     names: { sdk: 'grant_list', mcp: 'ziggs_grant_list' },
     title: 'List grants you hold',
     descriptions: {
-        sdk: 'List grants this agent holds — or, with role=issuer, grants this agent caused (author-shares and delegate children). Context (chat/agreement/org/artifact/task), connection, wallet, consent, and inbox — canonical grants (grantId, scope, caveats, expiresAt, health; no content or credentials). A `task` scope is a BRANCH of a work graph: the named task and everything under it, which is what holding a pass on a job looks like. Default role=holder answers "what grants do I HOLD?", which is narrower than "what can I reach?": your own authorship, and grants held by an org you belong to rather than by you, leave nothing under your own id — an empty holder list means "no grants of your own", never "no access". role=issuer answers "who did I share with / what did I mint?" after artifact_share. Filter by scopeKind, scopeId, and health (defaults to active). Rails you lack the operator-key read scope for are named in unreadableRails. Cursor-paginated.',
+        sdk: 'List grants this agent holds — or, with role=issuer, grants this agent caused (author-shares and delegate children). Context (chat/agreement/org/artifact/task), connection, wallet, consent, and inbox — canonical grants (grantId, scope, caveats, expiresAt, health; no content or credentials). A `task` scope is a BRANCH of a work graph: the named task and everything under it, which is what holding a pass on a job looks like. Default role=holder answers "what grants do I HOLD?", which is narrower than "what can I reach?": your own authorship, and grants held by an org you belong to rather than by you, leave nothing under your own id — an empty holder list means "no grants of your own", never "no access". role=issuer answers "who did I share with / what did I mint?" after a bucket share. Filter by scopeKind, scopeId, and health (defaults to active). Rails you lack the operator-key read scope for are named in unreadableRails. Cursor-paginated.',
     },
     annotation: 'read-only',
     params: {

package/dist/capabilities/index.d.ts

@@ -13,10 +13,11 @@ export { TASK_CAPABILITIES, listTasksCapability, cancelTaskCapability, delegateT
 export { AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION } from './proposeProviderId.js';
 export { MARKETPLACE_CAPABILITIES, marketplaceViewCapability } from './marketplace.js';
 export { GRANTS_CAPABILITIES, listGrantsCapability } from './grants.js';
+export { BUCKET_CAPABILITIES, bucketCreateCapability, bucketListCapability, bucketReadCapability, bucketInsertCapability, bucketRemoveCapability, bucketMoveCapability, bucketAddMembersCapability, bucketJoinCapability, bucketSendCapability, bucketRemoveMemberCapability, bucketDuplicateCapability, bucketRenameCapability, bucketDeleteCapability, } from './buckets.js';
 export { CONTEXT_CAPABILITIES, contextReadCapability, openCapability, accessExplainCapability, contextDelegateCapability, accessRequestCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, contextBounds, resolveOrgScopeId, explainRefusedRead, RESOURCE_HIDDEN_MESSAGE, RESOURCE_UNREADABLE_MESSAGE, type RefusedRead, } from './context.js';
 export { CONNECTION_CAPABILITIES, connectionProxyCapability, requestConnectionCapability, } from './connections.js';
 export { DISCOVERY_CAPABILITIES, agentSearchCapability, agentGetCapability, } from './discovery.js';
-export { ARTIFACT_CAPABILITIES, recordArtifactCapability, listArtifactsCapability, findArtifactsCapability, type UnsearchedContext, shareArtifactCapability, attachArtifactCapability, reviewArtifactContributionCapability, contributeArtifactCapability, uploadArtifactUrlCapability, completeArtifactFileCapability, downloadArtifactCapability, reextractArtifactCapability, } from './artifacts.js';
+export { ARTIFACT_CAPABILITIES, recordArtifactCapability, listArtifactsCapability, findArtifactsCapability, type UnsearchedContext, attachArtifactCapability, reviewArtifactContributionCapability, contributeArtifactCapability, uploadArtifactUrlCapability, completeArtifactFileCapability, downloadArtifactCapability, reextractArtifactCapability, } from './artifacts.js';
 export { EVERYDAY_MCP_TOOLS, EVERYDAY_NO_SDK_TWIN, EVERYDAY_SDK_TOOLS, } from './everyday.js';
 export { annotationForSdkTool } from './toolLane.js';
 export { presentResourceActions } from './resourceActions.js';

package/dist/capabilities/index.js

@@ -13,10 +13,11 @@ export { TASK_CAPABILITIES, listTasksCapability, cancelTaskCapability, delegateT
 export { AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION } from './proposeProviderId.js';
 export { MARKETPLACE_CAPABILITIES, marketplaceViewCapability } from './marketplace.js';
 export { GRANTS_CAPABILITIES, listGrantsCapability } from './grants.js';
+export { BUCKET_CAPABILITIES, bucketCreateCapability, bucketListCapability, bucketReadCapability, bucketInsertCapability, bucketRemoveCapability, bucketMoveCapability, bucketAddMembersCapability, bucketJoinCapability, bucketSendCapability, bucketRemoveMemberCapability, bucketDuplicateCapability, bucketRenameCapability, bucketDeleteCapability, } from './buckets.js';
 export { CONTEXT_CAPABILITIES, contextReadCapability, openCapability, accessExplainCapability, contextDelegateCapability, accessRequestCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, contextBounds, resolveOrgScopeId, explainRefusedRead, RESOURCE_HIDDEN_MESSAGE, RESOURCE_UNREADABLE_MESSAGE, } from './context.js';
 export { CONNECTION_CAPABILITIES, connectionProxyCapability, requestConnectionCapability, } from './connections.js';
 export { DISCOVERY_CAPABILITIES, agentSearchCapability, agentGetCapability, } from './discovery.js';
-export { ARTIFACT_CAPABILITIES, recordArtifactCapability, listArtifactsCapability, findArtifactsCapability, shareArtifactCapability, attachArtifactCapability, reviewArtifactContributionCapability, contributeArtifactCapability, uploadArtifactUrlCapability, completeArtifactFileCapability, downloadArtifactCapability, reextractArtifactCapability, } from './artifacts.js';
+export { ARTIFACT_CAPABILITIES, recordArtifactCapability, listArtifactsCapability, findArtifactsCapability, attachArtifactCapability, reviewArtifactContributionCapability, contributeArtifactCapability, uploadArtifactUrlCapability, completeArtifactFileCapability, downloadArtifactCapability, reextractArtifactCapability, } from './artifacts.js';
 export { EVERYDAY_MCP_TOOLS, EVERYDAY_NO_SDK_TWIN, EVERYDAY_SDK_TOOLS, } from './everyday.js';
 export { annotationForSdkTool } from './toolLane.js';
 export { presentResourceActions } from './resourceActions.js';

package/dist/capabilities/links.js

@@ -66,7 +66,6 @@ export const listLinksCapability = {
         // is now, as `peer`, resolved relative to whoever asked.
         const readPlan = active.length ? [
             nextCall(env, 'message_send', undefined, 'Send an explicit message command to a returned peer.id; choose readers, delivery recipients and the intent (fyi or request) separately. A link grants no history access.'),
-            nextCall(env, 'artifact_share', undefined, 'Share only the selected artifact under its grant and consent policy.'),
         ] : [];
         return {
             count: links.length,

package/dist/capabilities/mcpBriefs.js

@@ -165,10 +165,6 @@ const BRIEFS = {
     ziggs_artifact_find: {
         does: 'Searches artifacts you can read by name, filename or body. coverage and notSearched say what was and was not searched.',
     },
-    ziggs_artifact_share: {
-        does: 'Shares one artifact you authored with another agent.',
-        changes: 'grants it at once to a connected agent; otherwise asks your owner to approve (pending_approval)',
-    },
     ziggs_message_send: { does: 'Sends a canonical command with independent readers, recipients, an intent (fyi or request) and optional mandate.', changes: 'delivers a message and grants its readers access; a request wakes the agents it reaches' },
     ziggs_message_replies: { does: 'Reads authorized causal replies by messageId; a reference grants no access and receipt expiry does not erase history.' },
     ziggs_message_read: { does: 'Reads an exact message by messageId under current access and execution policy. Does not acknowledge its receipt.' },
@@ -291,6 +287,57 @@ const BRIEFS = {
         does: 'Calls one tool on a connected MCP server through the Ziggs gateway, within your grant. ziggs_connection_proxy refuses MCP servers (Unknown provider: mcp).',
         changes: 'whatever that tool changes',
     },
+    // Buckets: pointers to items and people; access is computed from the items' grants.
+    ziggs_bucket_create: {
+        does: 'Creates a bucket, with items if given.',
+        changes: 'creates it with what fits',
+    },
+    ziggs_bucket_list: {
+        does: 'Lists the buckets you are in.',
+    },
+    ziggs_bucket_read: {
+        does: 'Reads a bucket and a page of its items; those someone cannot read are set apart.',
+    },
+    ziggs_bucket_insert: {
+        does: 'Puts items in a bucket if everyone in it can read them.',
+        changes: 'adds what fits; share may share',
+    },
+    ziggs_bucket_remove: {
+        does: 'Takes items out of a bucket. The items are untouched.',
+        changes: 'removes them',
+    },
+    ziggs_bucket_duplicate: {
+        does: 'Copies items into a new bucket for another audience. The original stays.',
+        changes: 'creates it with what fits',
+    },
+    ziggs_bucket_move: {
+        does: 'Moves items to another or a new bucket, if its audience can read them.',
+        changes: 'moves what fits',
+    },
+    ziggs_bucket_add_members: {
+        does: 'Adds to a bucket audience. Who cannot read an item needs onMisfit share or split.',
+        changes: 'adds them',
+    },
+    ziggs_bucket_join: {
+        does: "Brings another bucket's people and items in. Who cannot read an item needs onMisfit share.",
+        changes: 'adds them',
+    },
+    ziggs_bucket_send: {
+        does: "Sends a message inside a bucket, to its people.",
+        changes: 'sends it',
+    },
+    ziggs_bucket_rename: {
+        does: 'Renames a bucket. Its creator does this.',
+        changes: 'the name',
+    },
+    ziggs_bucket_delete: {
+        does: 'Deletes a bucket. The items are untouched. Its creator does this.',
+        changes: 'deletes it',
+    },
+    ziggs_bucket_remove_member: {
+        does: 'Takes someone out of a bucket. Its creator does this.',
+        changes: 'removes them',
+    },
     ziggs_payment_balance: {
         does: 'Shows your points balance and what is available after holds. Points settle through work; here they cannot be bought, cashed out or transferred.',
     },

package/dist/capabilities/nextCall.js

@@ -30,7 +30,6 @@ const REQUIRED_ARGS = {
     agreement_subcontract: ['parentAgreementId', 'executorId', 'description'],
     agreement_respond: ['agreementId'],
     introduction_redeem: ['token'],
-    artifact_share: ['artifactId', 'holderId'],
     context_delegate: ['parentGrantId', 'holderId', 'scopeKind', 'scopeId', 'temporal'],
     task_create: ['agreementId', 'description'],
     task_cancel: ['taskId'],
@@ -61,7 +60,6 @@ const HTTP_BINDINGS = {
         path: '/agreements/:agreementId/approvals/:partyId',
     },
     marketplace_view: { method: 'GET', path: '/marketplace/offers' },
-    artifact_share: { method: 'POST', path: '/context/artifacts/:artifactId/share' },
     context_delegate: { method: 'POST', path: '/context/grants/:parentGrantId/delegate' },
     open: { method: 'POST', path: '/context/open' },
     access_explain: { method: 'POST', path: '/context/access/explain' },

package/dist/http/BucketsClient.d.ts

@@ -0,0 +1,219 @@
+import type { MessageCommand, MessageCommandResult } from '@ziggs-ai/contracts';
+/** What a bucket can hold. Each item is a pointer, never a copy. */
+export declare const BUCKET_ITEM_KINDS: readonly ["message", "artifact", "task", "agreement"];
+export type BucketItemKind = (typeof BUCKET_ITEM_KINDS)[number];
+export interface BucketItemRef {
+    kind: BucketItemKind;
+    id: string;
+}
+/**
+ * An item that does not fit where it was asked to go, or no longer fits where
+ * it is. Other members are named only when the caller can read the item.
+ */
+export type BucketMisfit = {
+    item: BucketItemRef;
+    reason: 'you-cannot-read';
+} | {
+    item: BucketItemRef;
+    reason: 'members-cannot-read';
+    memberIds: string[];
+};
+/**
+ * What to do when someone being added cannot read an item: share it with
+ * them, or split: start a narrower bucket with them and only what everyone
+ * can read, leaving this one as it is.
+ */
+export type BucketMisfitChoice = 'share' | 'split';
+export interface BucketView {
+    bucketId: string;
+    name: string;
+    createdBy: string;
+    /** Who it is for, as given: people, agents, workspaces. */
+    audience: string[];
+    /** Goes up when an item leaves or the audience changes. */
+    revision: number;
+    /** Items held; whether each still fits is computed when the items are read. */
+    itemCount: number;
+    createdAt: string | null;
+}
+/** One share made because the caller chose to share. */
+export interface BucketShare {
+    item: BucketItemRef;
+    holderId: string;
+    /** `pending` waits for the item owner's yes; the item stays out until then. */
+    outcome: 'shared' | 'pending' | 'refused';
+}
+export interface BucketInsertResult {
+    bucket: BucketView;
+    inserted: BucketItemRef[];
+    alreadyIn: BucketItemRef[];
+    misfits: BucketMisfit[];
+    shared: BucketShare[];
+}
+export interface BucketMoveResult {
+    source: BucketView;
+    bucket: BucketView;
+    moved: BucketItemRef[];
+    notIn: BucketItemRef[];
+    misfits: BucketMisfit[];
+}
+export interface BucketAddMembersResult {
+    bucket: BucketView;
+    added: string[];
+    shared: BucketShare[];
+    /** The narrower bucket a split started, and what it holds. This bucket is left as it was. */
+    split: {
+        bucket: BucketView;
+        items: BucketItemRef[];
+    } | null;
+}
+export interface BucketJoinResult {
+    bucket: BucketView;
+    added: string[];
+    joined: BucketItemRef[];
+    shared: BucketShare[];
+}
+/** One thread in a bucket, as the reader sees it. */
+export interface BucketThread {
+    rootMessageId: string;
+    title: string;
+    messageCount: number;
+    lastAt: string | null;
+    /** The reader wrote in it or it was delivered to them. */
+    yours: boolean;
+    /** The thread holding the message asked about as `current`. */
+    current: boolean;
+    /** The reader's own threads, other than the current one, come with their latest messages. */
+    recent?: Array<{
+        messageId: string;
+        from: string;
+        text: string;
+        at: string;
+    }>;
+}
+/** What is in a bucket as the reader can read it now: what a run starts from. */
+export interface BucketContents {
+    bucket: {
+        bucketId: string;
+        name: string;
+        audience: string[];
+        revision: number;
+    };
+    threads: BucketThread[];
+    artifacts: Array<{
+        artifactId: string;
+        name: string | null;
+    }>;
+    tasks: Array<{
+        taskId: string;
+        title: string;
+        state: string;
+    }>;
+    agreements: Array<{
+        agreementId: string;
+        title: string;
+        status: string;
+    }>;
+    /** 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'>;
+export interface BucketItemPage {
+    /** Items everyone it is for can read right now. */
+    items: Array<BucketItemRef & {
+        addedBy: string;
+        addedAt: string | null;
+    }>;
+    /** Items held that someone it is for can no longer read. */
+    outOfReach: BucketMisfit[];
+    nextCursor: string | null;
+}
+/**
+ * The bucket operations (`/buckets`). A bucket is pointers to items and to who
+ * it is for; it stores no permission. Whether everyone can read each item is
+ * computed from the items' own grants whenever it is asked.
+ *
+ * Every message is sent through a bucket and the bucket points at it; no
+ * message names its bucket. `listMine` with an item finds the buckets holding
+ * it, the first being where a message was sent.
+ *
+ * Changing a bucket is not part of a run, so those calls never carry the
+ * selected execution. Sending inside a bucket is: it carries the run, and the
+ * run's own guards apply to it.
+ */
+export declare class BucketsClient {
+    private readonly operatorKey;
+    private readonly agentId?;
+    private readonly baseUrl?;
+    constructor(operatorKey: string, agentId?: string | undefined, baseUrl?: string | undefined);
+    create(input: {
+        name: string;
+        audience?: string[];
+        items?: BucketItemRef[];
+        share?: boolean;
+    }): Promise<BucketInsertResult>;
+    /** The buckets you are in; given an item, those holding it, in the order it went in. */
+    listMine(item?: BucketItemRef): Promise<{
+        buckets: BucketView[];
+    }>;
+    /** Send a message inside a bucket, under the selected run when there is one. */
+    sendMessage(bucketId: string, message: BucketMessage): Promise<MessageCommandResult>;
+    /**
+     * What is in a bucket as you can read it now, under the selected run when
+     * there is one: your threads with their latest messages, the rest by title.
+     * `current` names the message being answered; its thread is marked.
+     */
+    contents(bucketId: string, opts?: {
+        current?: string;
+    }): Promise<BucketContents>;
+    /** Bring another bucket's people and items in. The other bucket stays. */
+    join(bucketId: string, input: {
+        from: string;
+        onMisfit?: 'share';
+    }): Promise<BucketJoinResult>;
+    get(bucketId: string): Promise<BucketView>;
+    items(bucketId: string, opts?: {
+        before?: string;
+        limit?: number;
+    }): Promise<BucketItemPage>;
+    insert(bucketId: string, items: BucketItemRef[], opts?: {
+        share?: boolean;
+    }): Promise<BucketInsertResult>;
+    remove(bucketId: string, items: BucketItemRef[]): Promise<{
+        bucket: BucketView;
+        removed: BucketItemRef[];
+        notIn: BucketItemRef[];
+    }>;
+    duplicate(bucketId: string, input: {
+        name: string;
+        audience?: string[];
+        items?: BucketItemRef[];
+        share?: boolean;
+    }): Promise<BucketInsertResult & {
+        notIn: BucketItemRef[];
+    }>;
+    move(bucketId: string, input: {
+        to: string;
+        items: BucketItemRef[];
+    }): Promise<BucketMoveResult>;
+    split(bucketId: string, input: {
+        items: BucketItemRef[];
+        name: string;
+        audience?: string[];
+    }): Promise<BucketMoveResult>;
+    addMembers(bucketId: string, principalIds: string[], opts?: {
+        onMisfit?: BucketMisfitChoice;
+    }): Promise<BucketAddMembersResult>;
+    removeMember(bucketId: string, principalId: string): Promise<{
+        bucket: BucketView;
+        removed: boolean;
+    }>;
+    rename(bucketId: string, name: string): Promise<BucketView>;
+    delete(bucketId: string): Promise<{
+        bucketId: string;
+        deleted: boolean;
+    }>;
+    private path;
+    private request;
+}

package/dist/http/BucketsClient.js

@@ -0,0 +1,109 @@
+import { getBackendUrl } from '../utils/urlUtils.js';
+import { throwApiError } from '../shared/apiError.js';
+import { buildOperatorHeaders, withoutExecution } from './operatorHeaders.js';
+/** What a bucket can hold. Each item is a pointer, never a copy. */
+export const BUCKET_ITEM_KINDS = ['message', 'artifact', 'task', 'agreement'];
+/**
+ * The bucket operations (`/buckets`). A bucket is pointers to items and to who
+ * it is for; it stores no permission. Whether everyone can read each item is
+ * computed from the items' own grants whenever it is asked.
+ *
+ * Every message is sent through a bucket and the bucket points at it; no
+ * message names its bucket. `listMine` with an item finds the buckets holding
+ * it, the first being where a message was sent.
+ *
+ * Changing a bucket is not part of a run, so those calls never carry the
+ * selected execution. Sending inside a bucket is: it carries the run, and the
+ * run's own guards apply to it.
+ */
+export class BucketsClient {
+    operatorKey;
+    agentId;
+    baseUrl;
+    constructor(operatorKey, agentId, baseUrl) {
+        this.operatorKey = operatorKey;
+        this.agentId = agentId;
+        this.baseUrl = baseUrl;
+        if (!operatorKey)
+            throw new Error('BucketsClient: operatorKey is required');
+    }
+    create(input) {
+        return this.request('POST', '/buckets', input, 'bucket create');
+    }
+    /** The buckets you are in; given an item, those holding it, in the order it went in. */
+    listMine(item) {
+        const query = item ? `?${new URLSearchParams({ kind: item.kind, id: item.id })}` : '';
+        return this.request('GET', `/buckets${query}`, undefined, 'bucket list');
+    }
+    /** Send a message inside a bucket, under the selected run when there is one. */
+    sendMessage(bucketId, message) {
+        return this.request('POST', `${this.path(bucketId)}/send`, message, 'bucket send', { inRun: true });
+    }
+    /**
+     * What is in a bucket as you can read it now, under the selected run when
+     * there is one: your threads with their latest messages, the rest by title.
+     * `current` names the message being answered; its thread is marked.
+     */
+    contents(bucketId, opts = {}) {
+        const query = opts.current ? `?${new URLSearchParams({ current: opts.current })}` : '';
+        return this.request('GET', `${this.path(bucketId)}/contents${query}`, undefined, 'bucket contents', { inRun: true });
+    }
+    /** Bring another bucket's people and items in. The other bucket stays. */
+    join(bucketId, input) {
+        return this.request('POST', `${this.path(bucketId)}/join`, input, 'bucket join');
+    }
+    get(bucketId) {
+        return this.request('GET', this.path(bucketId), undefined, 'bucket read');
+    }
+    items(bucketId, opts = {}) {
+        const query = new URLSearchParams();
+        if (opts.before)
+            query.set('before', opts.before);
+        if (opts.limit !== undefined)
+            query.set('limit', String(opts.limit));
+        const suffix = query.size ? `?${query}` : '';
+        return this.request('GET', `${this.path(bucketId)}/items${suffix}`, undefined, 'bucket items');
+    }
+    insert(bucketId, items, opts = {}) {
+        return this.request('POST', `${this.path(bucketId)}/insert`, { items, ...(opts.share ? { share: true } : {}) }, 'bucket insert');
+    }
+    remove(bucketId, items) {
+        return this.request('POST', `${this.path(bucketId)}/remove`, { items }, 'bucket remove');
+    }
+    duplicate(bucketId, input) {
+        return this.request('POST', `${this.path(bucketId)}/duplicate`, input, 'bucket duplicate');
+    }
+    move(bucketId, input) {
+        return this.request('POST', `${this.path(bucketId)}/move`, input, 'bucket move');
+    }
+    split(bucketId, input) {
+        return this.request('POST', `${this.path(bucketId)}/split`, input, 'bucket split');
+    }
+    addMembers(bucketId, principalIds, opts = {}) {
+        return this.request('POST', `${this.path(bucketId)}/members`, { principalIds, ...(opts.onMisfit ? { onMisfit: opts.onMisfit } : {}) }, 'bucket add members');
+    }
+    removeMember(bucketId, principalId) {
+        return this.request('DELETE', `${this.path(bucketId)}/members/${encodeURIComponent(principalId)}`, undefined, 'bucket remove member');
+    }
+    rename(bucketId, name) {
+        return this.request('PATCH', this.path(bucketId), { name }, 'bucket rename');
+    }
+    delete(bucketId) {
+        return this.request('DELETE', this.path(bucketId), undefined, 'bucket delete');
+    }
+    path(bucketId) {
+        return `/buckets/${encodeURIComponent(bucketId)}`;
+    }
+    async request(method, path, body, label, opts = {}) {
+        const headers = buildOperatorHeaders(this.operatorKey, this.agentId, body === undefined ? undefined : { 'content-type': 'application/json' });
+        const res = await fetch(`${this.baseUrl ?? getBackendUrl()}${path}`, {
+            method,
+            headers: opts.inRun ? headers : withoutExecution(headers),
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        });
+        const text = await res.text().catch(() => '');
+        if (!res.ok)
+            throwApiError(res, text, `${label} failed: ${res.status} ${res.statusText}`);
+        return (text ? JSON.parse(text) : {});
+    }
+}

package/dist/http/ContextGrantsClient.d.ts

@@ -124,22 +124,6 @@ export declare class ContextGrantsClient {
      * labels-only, grant-fenced server-side.
      */
     getReach(grantId: string): Promise<GrantReachResult>;
-    /**
-     * share an artifact THIS agent authored with another agent.
-     *
-     * Not a delegation: an agent holds no grant over its own output, so there is
-     * no parent to attenuate. Authorship is the authority, held by the agent's
-     * owner — which is why the receiver decides the outcome. A receiver already
-     * inside the sharer's trust boundary (same owner, same org, or an active link)
-     * is granted immediately; anyone else opens a request the owner approves,
-     * exactly like `delegateGrant`'s new-party path.
-     */
-    shareArtifact(artifactId: string, input: {
-        holderId: string;
-        expiresAt?: string | null;
-    }, opts?: {
-        idempotencyKey?: string;
-    }): Promise<DelegateContextGrantResult>;
     revokeGrant(grantId: string): Promise<{
         status: string;
         revokedCount?: number;

package/dist/http/ContextGrantsClient.js

@@ -136,33 +136,6 @@ export class ContextGrantsClient {
             truncatedAgreements: parsed.truncatedAgreements ?? 0,
         };
     }
-    /**
-     * share an artifact THIS agent authored with another agent.
-     *
-     * Not a delegation: an agent holds no grant over its own output, so there is
-     * no parent to attenuate. Authorship is the authority, held by the agent's
-     * owner — which is why the receiver decides the outcome. A receiver already
-     * inside the sharer's trust boundary (same owner, same org, or an active link)
-     * is granted immediately; anyone else opens a request the owner approves,
-     * exactly like `delegateGrant`'s new-party path.
-     */
-    async shareArtifact(artifactId, input, opts) {
-        const res = await fetch(`${this.baseUrl}/context/artifacts/${encodeURIComponent(artifactId)}/share`, {
-            method: 'POST',
-            headers: buildOperatorHeaders(this.operatorKey, this.agentId, {
-                'content-type': 'application/json',
-                ...(opts?.idempotencyKey
-                    ? { 'Idempotency-Key': opts.idempotencyKey }
-                    : {}),
-            }),
-            body: JSON.stringify(input),
-        });
-        const body = await res.text().catch(() => '');
-        if (!res.ok) {
-            throwApiError(res, body, `shareArtifact failed: ${res.status} ${res.statusText}`);
-        }
-        return parseGrantOrPending(body, 'POST /context/artifacts/:id/share');
-    }
     async revokeGrant(grantId) {
         const res = await fetch(`${this.baseUrl}/context/grants/${encodeURIComponent(grantId)}`, {
             method: 'DELETE',

package/dist/http/index.d.ts

@@ -28,6 +28,8 @@ export type { MyOrg, OrgResolution } from './OrgsClient.js';
 export { AgentSearchClient } from './AgentSearchClient.js';
 export { TelemetryClient } from './TelemetryClient.js';
 export { InboxClient } from './InboxClient.js';
+export { BucketsClient, BUCKET_ITEM_KINDS } from './BucketsClient.js';
+export type { BucketItemKind, BucketItemRef, BucketItemPage, BucketAddMembersResult, BucketContents, BucketThread, BucketJoinResult, BucketMessage, BucketInsertResult, BucketMisfit, BucketMisfitChoice, BucketMoveResult, BucketShare, BucketView, } from './BucketsClient.js';
 export { SessionsClient } from './SessionsClient.js';
 export type { AssistantSessionRow } from './SessionsClient.js';
 export { planInboxAck, planPartialInboxAck, inboxAckAllowed, inboxAckHandledIds, } from '../inboxAck.js';

package/dist/http/index.js

@@ -19,6 +19,7 @@ export { fetchMyOrgs, resolveOrgSelector, fetchDelegateAccess, fetchHostedAgentA
 export { AgentSearchClient } from './AgentSearchClient.js';
 export { TelemetryClient } from './TelemetryClient.js';
 export { InboxClient } from './InboxClient.js';
+export { BucketsClient, BUCKET_ITEM_KINDS } from './BucketsClient.js';
 export { SessionsClient } from './SessionsClient.js';
 export { planInboxAck, planPartialInboxAck, inboxAckAllowed, inboxAckHandledIds, } from '../inboxAck.js';
 // The lane header, built in one place — see operatorHeaders.ts. Exported

package/dist/shared/operationError.d.ts

@@ -12,7 +12,8 @@ export interface OperationError {
     /**
      * What the caller may pick from, when the refusal is a choice: the
      * agreements of WORK_SELECTION_REQUIRED, the workspaces of
-     * WORKSPACE_SELECTION_REQUIRED. Carried through verbatim so an assistant can
+     * WORKSPACE_SELECTION_REQUIRED, the onMisfit values (share, split) of
+     * BUCKET_MEMBERS_CANNOT_READ. Carried through verbatim so an assistant can
      * ask its human instead of re-reading the message.
      */
     choices?: unknown[];
@@ -22,6 +23,15 @@ export interface OperationError {
      * the same shape an open's action recovery has.
      */
     recovery?: Record<string, unknown>;
+    /**
+     * What the refusal is about, when the server said: the misfits of
+     * BUCKET_MEMBERS_CANNOT_READ (with any shares made before it stopped), the
+     * bucket and missing readers of BUCKET_READERS_MISSING, the live outside
+     * engagements that stop a workspace blocking outside agents. Carried
+     * through verbatim so an assistant can list
+     * them instead of re-reading the message.
+     */
+    impact?: Record<string, unknown>;
     /** Scoped restart position returned when too many observation streams exist. */
     recoveryCursor?: string;
     /** hidden | unreadable, the same outcome open and access_explain give. */

package/dist/shared/operationError.js

@@ -64,34 +64,31 @@ function thrownFields(err) {
     const message = typeof o.message === 'string' && o.message ? o.message : String(err);
     return { message, status, code, choices: choicesIn(o.body) };
 }
-/** The `recovery` call of a refusal body, when the server sent one. */
-function recoveryIn(body) {
+/** A refusal body's fields, when the server sent a JSON object. */
+function refusalBody(body) {
     if (typeof body !== 'string' || !body)
         return null;
     try {
         const parsed = JSON.parse(body);
-        const recovery = parsed?.recovery;
-        if (!recovery || typeof recovery !== 'object' || Array.isArray(recovery))
-            return null;
-        return recovery;
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : null;
     }
     catch {
         return null;
     }
 }
+/** One object field of a refusal body (`recovery`, `impact`), when the server sent it. */
+function objectIn(body, field) {
+    const value = refusalBody(body)?.[field];
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
 /** The `choices` list of a refusal body, when the server sent one. */
 function choicesIn(body) {
-    if (typeof body !== 'string' || !body)
-        return null;
-    try {
-        const parsed = JSON.parse(body);
-        return Array.isArray(parsed?.choices)
-            ? parsed.choices
-            : null;
-    }
-    catch {
-        return null;
-    }
+    const choices = refusalBody(body)?.choices;
+    return Array.isArray(choices) ? choices : null;
 }
 /**
  * Classify a thrown client error (or a plain string this layer raised) into a
@@ -101,9 +98,9 @@ export function describeOperationError(input, surface = 'sdk') {
     input = unwrapApiError(input);
     const shape = classify(input);
     const { choices } = thrownFields(input);
-    const recovery = typeof input === 'object' && input !== null
-        ? recoveryIn(input.body)
-        : null;
+    const body = typeof input === 'object' && input !== null ? input.body : undefined;
+    const recovery = objectIn(body, 'recovery');
+    const impact = objectIn(body, 'impact');
     let recoveryCursor;
     if (shape.code === 'INBOX_OBSERVATION_LIMIT' && input && typeof input === 'object') {
         try {
@@ -117,6 +114,7 @@ export function describeOperationError(input, surface = 'sdk') {
         ...shape,
         ...(recoveryCursor ? { recoveryCursor } : {}),
         ...(choices ? { choices } : {}),
+        ...(impact ? { impact } : {}),
         ...(recovery ? { recovery: typeof recovery.tool === 'string'
                 ? { ...presentResourceCall(recovery, surface) }
                 : recovery } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/api-client",
-  "version": "0.40.4",
+  "version": "0.40.5",
   "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.46.0",
+    "@ziggs-ai/contracts": "0.48.0",
     "socket.io-client": "^4.7.0"
   },
   "keywords": [