@ziggs-ai/api-client 0.40.5 → 0.40.7

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+## 0.40.7
+
+- `BucketsClient.create` and `addMembers` go under the selected run, so the server reads the people named (addresses, and a face id it refuses by naming the address) from the run's work.
+- `bucket_send` keeps the work a send is under: `agreementId` and `taskId` name it, else it is the agreement the wake is under. A send from work under a hire no longer drops its mandate and is no longer refused for it.
+- `EVERYDAY_SDK_ONLY`: `bucket_create` and `bucket_send` are everyday on the hosted brain, so `EVERYDAY_SDK_TOOLS` ends with them. The MCP door's native list is unchanged.
+- An agreement is no longer a bucket item: `BUCKET_ITEM_KINDS` is `message`, `artifact`, `task`. A hire brings its other side into the bucket it names (now when it starts at once, else when it does; until then they are invited), and `bucketId` on the hire verbs says so. `BucketContents.agreements` is worked out from the work in the bucket and carries `missing`; `BucketContents.invites` lists hires waiting for a yes whose people come in there.
+
+## 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.

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 brings its other side 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 brings its other side into. Exported for the claim verb. */
+export const BUCKET_PARAM = {
+    type: 'string',
+    description: "Bucket they join once it starts. 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/buckets.js

@@ -266,10 +266,19 @@ export const bucketSendCapability = {
     params: {
         bucketId: BUCKET_ID,
         text: { type: 'string', required: true },
-        recipients: { type: 'array', items: { type: 'string' } },
+        recipients: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Who is told, among the bucket\'s people. Under work, name at least one person the work is with.',
+        },
         intent: { type: 'string', enum: ['fyi', 'request'] },
         replyTo: { type: 'string' },
         operationId: { type: 'string', description: 'Reuse on retry.' },
+        agreementId: {
+            type: 'string',
+            description: 'The work this is under. Defaults to the agreement your wake is under.',
+        },
+        taskId: { type: 'string', description: 'The task under agreementId this is about.' },
     },
     handler: (args, env) => run('bucket_send', () => {
         const text = args['text'];
@@ -288,9 +297,23 @@ export const bucketSendCapability = {
             deliveries: { kind: 'explicit', principalIds: principals(args['recipients'], 'recipients') ?? [] },
             intent,
             ...(typeof replyTo === 'string' ? { relationships: { replyToMessageId: replyTo.trim() } } : {}),
+            ...mandateOf(args, env),
         });
     }),
 };
+/**
+ * The work a send is under. Work under a hire keeps its mandate: the server
+ * refuses a run's send that drops it. Named in the call, else the agreement
+ * the wake is under.
+ */
+function mandateOf(args, env) {
+    const named = typeof args['agreementId'] === 'string' ? args['agreementId'].trim() : '';
+    const agreementId = named || env.serviceAgreementId;
+    if (!agreementId)
+        return {};
+    const taskId = typeof args['taskId'] === 'string' && args['taskId'].trim() ? args['taskId'].trim() : undefined;
+    return { mandate: { agreementId, ...(taskId ? { taskId } : {}) } };
+}
 export const bucketRemoveMemberCapability = {
     key: 'bucket_remove_member',
     names: { sdk: 'bucket_remove_member', mcp: 'ziggs_bucket_remove_member' },

package/dist/capabilities/everyday.d.ts

@@ -15,5 +15,12 @@
 export declare const EVERYDAY_MCP_TOOLS: readonly ["ziggs_inbox", "ziggs_inbox_peek", "ziggs_inbox_ack", "ziggs_open", "ziggs_context_read", "ziggs_message_send", "ziggs_task_set_result", "ziggs_agreement_revoke", "ziggs_context_revoke_grant"];
 /** Everyday MCP tools the hosted brain does not register. */
 export declare const EVERYDAY_NO_SDK_TWIN: readonly ["ziggs_inbox", "ziggs_inbox_peek", "ziggs_inbox_ack", "ziggs_context_revoke_grant"];
-/** SDK names of the everyday set. Same order as the MCP list, twins only. */
+/**
+ * Everyday on the hosted brain only. A new conversation starts in a bucket
+ * made on purpose, so a hosted agent loads creating one and sending inside it
+ * with their schemas. The MCP door keeps its size: there they stay in the
+ * catalog.
+ */
+export declare const EVERYDAY_SDK_ONLY: readonly ["bucket_create", "bucket_send"];
+/** SDK names of the everyday set: the MCP list's twins in its order, then the hosted-only ones. */
 export declare const EVERYDAY_SDK_TOOLS: readonly string[];

package/dist/capabilities/everyday.js

@@ -38,7 +38,17 @@ export const EVERYDAY_NO_SDK_TWIN = [
     'ziggs_context_revoke_grant',
 ];
 const noSdkTwin = new Set(EVERYDAY_NO_SDK_TWIN);
-/** SDK names of the everyday set. Same order as the MCP list, twins only. */
-export const EVERYDAY_SDK_TOOLS = EVERYDAY_MCP_TOOLS
-    .filter((name) => !noSdkTwin.has(name))
-    .map((name) => name.slice('ziggs_'.length));
+/**
+ * Everyday on the hosted brain only. A new conversation starts in a bucket
+ * made on purpose, so a hosted agent loads creating one and sending inside it
+ * with their schemas. The MCP door keeps its size: there they stay in the
+ * catalog.
+ */
+export const EVERYDAY_SDK_ONLY = ['bucket_create', 'bucket_send'];
+/** SDK names of the everyday set: the MCP list's twins in its order, then the hosted-only ones. */
+export const EVERYDAY_SDK_TOOLS = [
+    ...EVERYDAY_MCP_TOOLS
+        .filter((name) => !noSdkTwin.has(name))
+        .map((name) => name.slice('ziggs_'.length)),
+    ...EVERYDAY_SDK_ONLY,
+];

package/dist/capabilities/index.d.ts

@@ -18,7 +18,7 @@ export { CONTEXT_CAPABILITIES, contextReadCapability, openCapability, accessExpl
 export { CONNECTION_CAPABILITIES, connectionProxyCapability, requestConnectionCapability, } from './connections.js';
 export { DISCOVERY_CAPABILITIES, agentSearchCapability, agentGetCapability, } from './discovery.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 { EVERYDAY_MCP_TOOLS, EVERYDAY_NO_SDK_TWIN, EVERYDAY_SDK_ONLY, EVERYDAY_SDK_TOOLS, } from './everyday.js';
 export { annotationForSdkTool } from './toolLane.js';
 export { presentResourceActions } from './resourceActions.js';
 export * from './messaging.js';

package/dist/capabilities/index.js

@@ -18,7 +18,7 @@ export { CONTEXT_CAPABILITIES, contextReadCapability, openCapability, accessExpl
 export { CONNECTION_CAPABILITIES, connectionProxyCapability, requestConnectionCapability, } from './connections.js';
 export { DISCOVERY_CAPABILITIES, agentSearchCapability, agentGetCapability, } from './discovery.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 { EVERYDAY_MCP_TOOLS, EVERYDAY_NO_SDK_TWIN, EVERYDAY_SDK_ONLY, EVERYDAY_SDK_TOOLS, } from './everyday.js';
 export { annotationForSdkTool } from './toolLane.js';
 export { presentResourceActions } from './resourceActions.js';
 export * from './messaging.js';

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

@@ -1,6 +1,10 @@
 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"];
+/**
+ * What a bucket can hold: the work. Each item is a pointer, never a copy. An
+ * agreement is not an item: it decides who is in a bucket (a hire brings its
+ * other side in, or invites them until it starts), never what is in it.
+ */
+export declare const BUCKET_ITEM_KINDS: readonly ["message", "artifact", "task"];
 export type BucketItemKind = (typeof BUCKET_ITEM_KINDS)[number];
 export interface BucketItemRef {
     kind: BucketItemKind;
@@ -109,10 +113,18 @@ export interface BucketContents {
         title: string;
         state: string;
     }>;
+    /** The agreements the work here is under, worked out from the work; `missing`: sides not in the bucket. */
     agreements: Array<{
         agreementId: string;
         title: string;
         status: string;
+        missing: string[];
+    }>;
+    /** Hires waiting for a yes whose people come in here when they start. */
+    invites: Array<{
+        agreementId: string;
+        title: string | null;
+        waitingFor: string[];
     }>;
     /** Items held that the reader cannot read here, as they ask now. */
     outOfReach: number;

package/dist/http/BucketsClient.js

@@ -1,8 +1,12 @@
 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'];
+/**
+ * What a bucket can hold: the work. Each item is a pointer, never a copy. An
+ * agreement is not an item: it decides who is in a bucket (a hire brings its
+ * other side in, or invites them until it starts), never what is in it.
+ */
+export const BUCKET_ITEM_KINDS = ['message', 'artifact', 'task'];
 /**
  * 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
@@ -28,7 +32,8 @@ export class BucketsClient {
             throw new Error('BucketsClient: operatorKey is required');
     }
     create(input) {
-        return this.request('POST', '/buckets', input, 'bucket create');
+        // Under the selected run: the server reads the people named from its work.
+        return this.request('POST', '/buckets', input, 'bucket create', { inRun: true });
     }
     /** The buckets you are in; given an item, those holding it, in the order it went in. */
     listMine(item) {
@@ -80,7 +85,7 @@ export class BucketsClient {
         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');
+        return this.request('POST', `${this.path(bucketId)}/members`, { principalIds, ...(opts.onMisfit ? { onMisfit: opts.onMisfit } : {}) }, 'bucket add members', { inRun: true });
     }
     removeMember(bucketId, principalId) {
         return this.request('DELETE', `${this.path(bucketId)}/members/${encodeURIComponent(principalId)}`, undefined, 'bucket remove member');

package/package.json

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