@ziggs-ai/api-client 0.40.4 → 0.40.6

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/AgreementClient.d.ts

@@ -45,6 +45,11 @@ export interface ProposeDirectInput extends ProposeTerms {
     proposedTo: string;
     /** Optional display-reference context for resolving a masked party; does not publish or share. */
     addressId?: string;
+    /**
+     * The bucket the agreement goes into, one you are in. Left out: the bucket
+     * your run works in, else a new one. The other side comes in when it starts.
+     */
+    bucketId?: string;
 }
 /**
  * Open buyer-broadcast. `audience` selects who may see/claim it:
@@ -134,6 +139,11 @@ export interface DelegateAgreementData {
     interactionMode?: 'messages' | 'tasks' | 'both';
     agreementDescription?: string;
     payerId?: string;
+    /**
+     * The bucket the sub-agreement goes into, one you are in. Left out: the
+     * bucket your run works in, else the parent's buckets, else a new one.
+     */
+    bucketId?: string;
     idempotencyKey?: string;
 }
 export declare function delegateAgreement(proposalData: DelegateAgreementData, creds: Creds): Promise<Agreement>;
@@ -328,6 +338,11 @@ export type ClaimedKind = 'link' | 'offer' | 'request' | 'hand-off';
  */
 export interface ClaimOptions {
     parentAgreementId?: string;
+    /**
+     * The bucket the hire goes into, one you are in. Left out: the bucket your
+     * run works in, else a new one. The other side comes in when it starts.
+     */
+    bucketId?: string;
     /**
      * The active agreement whose work this claim is part of. An agent acting
      * inside a job its human approved does not need a second consent for the

package/dist/http/AgreementClient.js

@@ -559,7 +559,7 @@ export async function claimAgreement(agreementId, creds, opts = {}) {
     const res = await fetch(`${getAgreementBaseUrl()}/${encodeURIComponent(agreementId)}/claim`, {
         method: 'POST',
         headers: buildHeaders(creds),
-        body: JSON.stringify({ ...(opts.mandateAgreementId ? { mandateAgreementId: opts.mandateAgreementId } : {}), ...(opts.parentAgreementId ? { parentAgreementId: opts.parentAgreementId } : {}), ...(opts.connections && Object.keys(opts.connections).length ? { connections: opts.connections } : {}), ...(opts.hireFor === 'workspace' ? { hireFor: 'workspace' } : {}) }),
+        body: JSON.stringify({ ...(opts.mandateAgreementId ? { mandateAgreementId: opts.mandateAgreementId } : {}), ...(opts.parentAgreementId ? { parentAgreementId: opts.parentAgreementId } : {}), ...(opts.connections && Object.keys(opts.connections).length ? { connections: opts.connections } : {}), ...(opts.hireFor === 'workspace' ? { hireFor: 'workspace' } : {}), ...(opts.bucketId ? { bucketId: opts.bucketId } : {}) }),
     });
     if (!res.ok) {
         const body = await res.text().catch(() => '');

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. */