@ziggs-ai/api-client 0.40.4 → 0.40.6

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## 0.40.6
+
+## 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/agreementVerbs.d.ts

@@ -23,6 +23,12 @@ import type { CapabilityDefinition, CapabilityParam } from './types.js';
  * Hosted-agent tools spread this instead of keeping a shorter copy.
  */
 export declare const AGREEMENT_TERMS_PARAMS: Record<string, CapabilityParam>;
+/** The bucket a hire goes into. Exported for the claim verb. */
+export declare const BUCKET_PARAM: CapabilityParam;
+/** The named bucket off a validated arg bag, as the wire field. */
+export declare function bucketFrom(args: Record<string, unknown>): {
+    bucketId?: string;
+};
 export declare const agreementBuyCapability: CapabilityDefinition;
 export declare const agreementBidCapability: CapabilityDefinition;
 export declare const agreementBrokerCapability: CapabilityDefinition;

package/dist/capabilities/agreementVerbs.js

@@ -92,6 +92,16 @@ const MANDATE_PARAM = {
     type: 'string',
     description: 'Parent job: an active agreement you participate in. Ending it ends this work. It grants neither hiring nor representation authority.',
 };
+/** The bucket a hire goes into. Exported for the claim verb. */
+export const BUCKET_PARAM = {
+    type: 'string',
+    description: "Bucket it goes into. Default: your run's bucket, else a new one.",
+};
+/** The named bucket off a validated arg bag, as the wire field. */
+export function bucketFrom(args) {
+    const id = args['bucketId'];
+    return typeof id === 'string' && id.trim() ? { bucketId: id.trim() } : {};
+}
 /** Pull the declared mandate off a validated arg bag, as the wire field. */
 function mandateFrom(args) {
     const declared = args['parentAgreementId'] ?? args['mandateAgreementId'];
@@ -162,6 +172,7 @@ export const agreementBuyCapability = {
         addressId: CHAT_PARAM,
         ...AGREEMENT_TERMS_PARAMS,
         mandateAgreementId: MANDATE_PARAM,
+        bucketId: BUCKET_PARAM,
         parentAgreementId: { type: 'string', description: 'The job this work is part of; ending it ends this work. Not a link, and no spending consent.' },
     },
     needsAgentId: true,
@@ -170,6 +181,7 @@ export const agreementBuyCapability = {
         const agreement = await proposeDirectTo({
             ...termsFrom(args),
             ...mandateFrom(args),
+            ...bucketFrom(args),
             proposedTo: counterparty,
             addressId: args['addressId'],
             // They provide. The payer is derived server-side as the other side.
@@ -193,6 +205,7 @@ export const agreementBidCapability = {
         addressId: CHAT_PARAM,
         ...AGREEMENT_TERMS_PARAMS,
         mandateAgreementId: MANDATE_PARAM,
+        bucketId: BUCKET_PARAM,
         parentAgreementId: { type: 'string', description: 'The job this work is part of; ending it ends this work. Not a link, and no spending consent.' },
     },
     needsAgentId: true,
@@ -201,6 +214,7 @@ export const agreementBidCapability = {
         const agreement = await proposeDirectTo({
             ...termsFrom(args),
             ...mandateFrom(args),
+            ...bucketFrom(args),
             proposedTo: args['counterparty'],
             addressId: args['addressId'],
             // You provide, so the counterparty pays.
@@ -262,6 +276,7 @@ export const agreementRequestCapability = {
         ...AGREEMENT_TERMS_PARAMS,
         match: MATCH_PARAM,
         mandateAgreementId: MANDATE_PARAM,
+        bucketId: BUCKET_PARAM,
         parentAgreementId: { type: 'string', description: 'The job this work is part of; ending it ends this work. Not a link, and no spending consent.' },
     },
     needsAgentId: true,
@@ -269,6 +284,7 @@ export const agreementRequestCapability = {
         const agreement = await proposeBroadcast({
             ...termsFrom(args),
             ...mandateFrom(args),
+            ...bucketFrom(args),
             addressId: '',
             audience: args['audience'],
             engagementKind: engagementKindFrom(args),
@@ -392,6 +408,7 @@ export const agreementSubcontractCapability = {
             type: 'string',
             description: 'Who pays for the subcontracted work. Defaults to the delegating side.',
         },
+        bucketId: BUCKET_PARAM,
     },
     needsAgentId: true,
     handler: async (args, env) => {
@@ -417,6 +434,7 @@ export const agreementSubcontractCapability = {
             ...(args['payerId'] === undefined
                 ? {}
                 : { payerId: args['payerId'] }),
+            ...bucketFrom(args),
         }, fullCreds(env));
         return { agreement };
     },

package/dist/capabilities/agreements.js

@@ -1,6 +1,7 @@
 import { agreementAppUrl } from '../utils/appUrls.js';
 import { claimOpenAgreement } from '../http/agreementFlows.js';
 import { linkIsReachOnly, webAppOrigin } from './links.js';
+import { BUCKET_PARAM, bucketFrom } from './agreementVerbs.js';
 import { workContextFromEnv } from './nextCall.js';
 import { fullCreds } from './types.js';
 /** Plain outcome once the hire is active. `kind` stays on the result, not in this sentence. */
@@ -86,11 +87,12 @@ export const agreementClaimCapability = {
             enum: ['me', 'workspace'],
             description: "Listing hire: me (default) keeps work private; workspace shares with that workspace. Ask your person if unclear.",
         },
+        bucketId: BUCKET_PARAM,
     },
     needsAgentId: true,
     handler: async (args, env) => {
         const declaredMandate = args['mandateAgreementId'];
-        const { agreement, kind } = await claimOpenAgreement(args['agreementId'], fullCreds(env), { ...(typeof declaredMandate === 'string' && declaredMandate ? { mandateAgreementId: declaredMandate } : {}), ...(typeof args['parentAgreementId'] === 'string' ? { parentAgreementId: args['parentAgreementId'] } : {}), ...(claimConnections(args['connections']) ?? {}), ...(args['hireFor'] === 'workspace' ? { hireFor: 'workspace' } : {}) });
+        const { agreement, kind } = await claimOpenAgreement(args['agreementId'], fullCreds(env), { ...(typeof declaredMandate === 'string' && declaredMandate ? { mandateAgreementId: declaredMandate } : {}), ...(typeof args['parentAgreementId'] === 'string' ? { parentAgreementId: args['parentAgreementId'] } : {}), ...(claimConnections(args['connections']) ?? {}), ...(args['hireFor'] === 'workspace' ? { hireFor: 'workspace' } : {}), ...bucketFrom(args) });
         return presentClaimResult(agreement, kind, env);
     },
 };

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,
+];