@ziggs-ai/api-client 0.38.0 → 0.39.0

package/dist/capabilities/artifacts.js

@@ -104,7 +104,6 @@ async function recordFileArtifact(args, env, visibility) {
         byteSize,
         format: args['format'],
         visibility,
-        chatId: args['chatId'],
         agreementId: args['agreementId'],
         serviceAgreementId: args['serviceAgreementId'] ?? (!taskId && !args['agreementId'] ? env.serviceAgreementId : undefined),
         taskId,
@@ -123,7 +122,6 @@ async function recordFileArtifact(args, env, visibility) {
         artifactId: uploaded.artifactId,
         artifact,
         visibility,
-        chatId: args['chatId'],
         agreementId: args['agreementId'],
         taskId,
         byteSize,
@@ -154,7 +152,7 @@ export const recordArtifactCapability = {
     title: 'Record an artifact',
     descriptions: {
         sdk: 'Write an artifact — text (text) or a file (filename + mime + contentBase64; the upload ' +
-            'happens inside this call). Scope is optional: pass agreementId or chatId to record it there, ' +
+            'happens inside this call). Scope is optional: pass agreementId to record it there, ' +
             'or pass no scope at all to record it as yours alone and attach it somewhere later. ' +
             'Set visibility explicitly. For a finished deliverable, set contentType=result and pass ' +
             'taskId to bind it to the task. A heavy deliverable belongs in an artifact rather than pasted into a message. ' +
@@ -168,7 +166,7 @@ export const recordArtifactCapability = {
         },
         contentBase64: {
             type: 'string',
-            description: 'Base64 file bytes for a file artifact — requires filename and mime. This call presigns, uploads and completes; you never compute a checksum. Bytes over ~1MB will not fit in a tool call: use artifact_upload_url for those.',
+            description: 'File bytes; requires filename and mime. Handles upload/checksum. Over ~1MB: use artifact_upload_url.',
         },
         name: {
             type: 'string',
@@ -190,15 +188,14 @@ export const recordArtifactCapability = {
         visibility: {
             type: 'string',
             required: true,
-            enum: ['chat', 'agent-private'],
-            description: 'chat = the scope’s parties can read it; agent-private = not shared with them. ' +
+            enum: ['address', 'agent-private'],
+            description: 'address = eligible for authorized work readers; agent-private = not shared with other agents. Discussion references grant no access. ' +
                 'Neither is permanent: you can share any artifact later with a specific agent.',
         },
         serviceAgreementId: { type: 'string', description: 'Agreement authorizing this work, separate from the destination chat. Defaults to the SDK wake agreement when no task/agreement scope is supplied.' },
-        chatId: { type: 'string', description: 'Optional chat scope' },
         agreementId: {
             type: 'string',
-            description: 'Optional agreement scope — for a hire deliverable, prefer this. Mutually exclusive with chatId: pass one, not both.',
+            description: 'Optional agreement scope — for a hire deliverable, prefer this. This names work, not a discussion.',
         },
         taskId: {
             type: 'string',
@@ -222,21 +219,22 @@ export const recordArtifactCapability = {
     },
     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 agreementId = args['agreementId'];
-        // Both containers is refused, not resolved. This used to drop chatId and
+        // Both containers is refused, not resolved. This used to drop addressId and
         // call agreement the winner — two answers to one call, and the silent one
         // was worse: the artifact landed somewhere the caller had just been told it
         // would also appear. The refusal itself lives in ArtifactsClient, the one
         // gate every writer goes through, so this surface cannot drift from the
         // others by wording its own verdict.
-        const chatId = args['chatId'];
         // no scope is legal. The throw that used to live here ("Pass
-        // chatId or agreementId") is the exact failure this ticket removed — it cost
+        // addressId or agreementId") is the exact failure this ticket removed — it cost
         // a live agent a turn mid-delivery for naming no container, when the record
         // itself never needed one.
         const visibility = args['visibility'];
-        if (visibility !== 'chat' && visibility !== 'agent-private') {
-            throw new Error('visibility must be chat or agent-private');
+        if (visibility !== 'address' && visibility !== 'agent-private') {
+            throw new Error('visibility must be address or agent-private');
         }
         // One tool, two body forms. Both at once is refused rather
         // than resolved: which one won would be invisible in the response.
@@ -259,7 +257,6 @@ export const recordArtifactCapability = {
             text,
             name: args['name']?.trim() || undefined,
             visibility,
-            chatId,
             agreementId,
             taskId,
             serviceAgreementId: args['serviceAgreementId'] ?? (!taskId && !agreementId ? env.serviceAgreementId : undefined),
@@ -272,7 +269,6 @@ export const recordArtifactCapability = {
             ok: true,
             artifactId,
             visibility,
-            chatId,
             agreementId,
             taskId,
             reportingHint: reportingHint(env, contentType, taskId),
@@ -304,6 +300,8 @@ export const listArtifactsCapability = {
     },
     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 listed = await new ArtifactsClient(creds.operatorKey, creds.agentId).list({ authoredBy: 'me' }, {
             after: args['after'],
@@ -325,7 +323,7 @@ const UNSEARCHED_NOTE = 'These were NOT searched. You hold no grant on them, so
     'root grant. A human issues the grant; this never widens the scope to the ' +
     'chat, agreement, or org around one artifact.';
 const OPEN_ID_FIELD = {
-    chat: 'chatId',
+    address: 'addressId',
     agreement: 'agreementId',
     artifact: 'artifactId',
     task: 'taskId',
@@ -422,12 +420,14 @@ export const findArtifactsCapability = {
         },
         includeUnreadable: {
             type: 'boolean',
-            description: 'Also list context you hold no grant on (labels only, never contents). When omitted, that list is attached only if nothing matched. Pass true to ask for it alongside matches. Pass false to leave it off.',
+            description: 'Include unreadable labels, never bodies. Default: only when no matches. true: alongside matches; false: omit.',
         },
         fields: LIST_FIELDS_PARAM,
     },
     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 found = await new ArtifactsClient(creds.operatorKey, creds.agentId).find(args['q'], {
             limit: typeof args['limit'] === 'number' ? args['limit'] : undefined,
@@ -478,10 +478,6 @@ export const shareArtifactCapability = {
             type: 'string',
             description: 'ISO-8601 expiry; omit for the default grant lifetime',
         },
-        chatId: {
-            type: 'string',
-            description: 'Chat to surface the approval request in, when the receiver’s owner has to approve',
-        },
         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.',
@@ -489,6 +485,8 @@ export const shareArtifactCapability = {
     },
     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)
@@ -499,7 +497,6 @@ export const shareArtifactCapability = {
         const result = await new ContextGrantsClient(creds.operatorKey, creds.agentId, env.baseUrl).shareArtifact(artifactId, {
             holderId,
             expiresAt: args['expiresAt'],
-            chatId: args['chatId'],
         }, {
             idempotencyKey: typeof args['idempotencyKey'] === 'string'
                 ? args['idempotencyKey']
@@ -531,14 +528,13 @@ export const shareArtifactCapability = {
 export const attachArtifactCapability = {
     key: 'artifact_attach',
     names: { sdk: 'artifact_attach', mcp: 'ziggs_artifact_attach' },
-    title: 'Attach to a chat, task, or agreement',
+    title: 'Attach to a task or agreement',
     descriptions: {
-        sdk: 'Attach an artifact you can read to a chat, a task, or an agreement. Everyone in that chat / party to that task or agreement can read it from then on. 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. Use artifact_share to give it to one specific agent instead.',
     },
     annotation: 'destructive',
     params: {
         artifactId: { type: 'string', required: true, description: 'Artifact to attach' },
-        chatId: { type: 'string', description: 'Chat to attach it to' },
         taskId: { type: 'string', description: 'Task to attach it to' },
         agreementId: {
             type: 'string',
@@ -553,15 +549,16 @@ export const attachArtifactCapability = {
     },
     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 artifactId = args['artifactId'];
         if (!artifactId)
             throw new Error('artifactId is required');
-        const chatId = args['chatId'];
         const taskId = args['taskId'];
         const agreementId = args['agreementId'];
-        const named = [chatId, taskId, agreementId].filter(Boolean).length;
+        const named = [taskId, agreementId].filter(Boolean).length;
         if (named !== 1) {
-            throw new Error('Pass exactly one of chatId, taskId, or agreementId');
+            throw new Error('Pass exactly one of taskId or agreementId');
         }
         const role = args['role'] ?? 'output';
         if (role !== 'input' && role !== 'output') {
@@ -569,15 +566,6 @@ export const attachArtifactCapability = {
         }
         const creds = fullCreds(env);
         const client = new ArtifactsClient(creds.operatorKey, creds.agentId);
-        if (chatId) {
-            await client.attachToChat(artifactId, chatId);
-            return {
-                ok: true,
-                artifactId,
-                chatId,
-                note: `Everyone in chat ${chatId} can now read artifact ${artifactId}.`,
-            };
-        }
         if (agreementId) {
             await client.attachToAgreement(artifactId, agreementId);
             return {
@@ -634,13 +622,12 @@ export const uploadArtifactUrlCapability = {
         },
         visibility: {
             type: 'string',
-            enum: ['chat', 'agent-private'],
+            enum: ['address', 'agent-private'],
             description: 'Defaults server-side when omitted',
         },
-        chatId: { type: 'string', description: 'Optional chat scope' },
         agreementId: {
             type: 'string',
-            description: 'Optional agreement scope; mutually exclusive with chatId',
+            description: 'Optional agreement scope',
         },
         serviceAgreementId: { type: 'string', description: 'Agreement authorizing this work, separate from the destination chat.' },
         taskId: { type: 'string', description: 'Optional task binding' },
@@ -655,6 +642,8 @@ export const uploadArtifactUrlCapability = {
     },
     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 filename = args['filename'];
         const mime = args['mime'];
         const byteSize = args['byteSize'];
@@ -667,9 +656,9 @@ export const uploadArtifactUrlCapability = {
         }
         const visibility = args['visibility'];
         if (visibility != null &&
-            visibility !== 'chat' &&
+            visibility !== 'address' &&
             visibility !== 'agent-private') {
-            throw new Error('visibility must be chat or agent-private');
+            throw new Error('visibility must be address or agent-private');
         }
         const creds = fullCreds(env);
         const result = await new ArtifactsClient(creds.operatorKey, creds.agentId).uploadUrl({
@@ -678,7 +667,6 @@ export const uploadArtifactUrlCapability = {
             byteSize: Math.trunc(byteSize),
             format: args['format'],
             visibility,
-            chatId: args['chatId'],
             agreementId: args['agreementId'],
             taskId: args['taskId'],
             serviceAgreementId: args['serviceAgreementId'] ?? (!args['taskId'] && !args['agreementId'] ? env.serviceAgreementId : undefined),
@@ -715,6 +703,8 @@ export const completeArtifactFileCapability = {
     },
     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 artifactId = args['artifactId'];
         const checksum = args['checksum'];
         if (!artifactId)
@@ -745,6 +735,8 @@ export const downloadArtifactCapability = {
     },
     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 artifactId = args['artifactId'];
         if (!artifactId)
             throw new Error('artifactId is required');
@@ -767,6 +759,8 @@ export const reextractArtifactCapability = {
     },
     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 artifactId = args['artifactId'];
         if (!artifactId)
             throw new Error('artifactId is required');
@@ -775,12 +769,59 @@ export const reextractArtifactCapability = {
         return { ok: true, artifact };
     },
 };
+const CONTRIBUTION_PARAMS = {
+    artifactId: { type: 'string', required: true, description: 'The output' },
+    agreementId: { type: 'string', required: true, description: 'Where it goes' },
+};
+function contributionTarget(args) {
+    if (typeof args.artifactId !== 'string' || !args.artifactId.trim() || typeof args.agreementId !== 'string' || !args.agreementId.trim())
+        throw new Error('artifactId and agreementId are required');
+    return { artifactId: args.artifactId, agreementId: args.agreementId };
+}
+/**
+ * The read half of a contribution, its own tool: a directory listing may not
+ * put a safe read and an unsafe write under one annotation.
+ */
+export const reviewArtifactContributionCapability = {
+    key: 'artifact_contribution_review',
+    names: { sdk: 'artifact_contribution_review', mcp: 'ziggs_artifact_contribution_review' },
+    title: 'Review a contribution',
+    descriptions: { sdk: 'Review the approvals one immutable artifact needs before artifact_contribute delivers it to another agreement. Keep the producing execution selected. Returns source releases you can identify and a privateSourceCount for hidden upstream inputs; if that count is nonzero, the original source authority must arrange any further release. Request them with access_request using scopeId=output artifact, contributionTo=destination and releaseSource from the review. Also obtain ordinary output-owner contribution consent.' },
+    annotation: 'read-only',
+    needsAgentId: true,
+    params: CONTRIBUTION_PARAMS,
+    handler: async (args, env) => {
+        if ('addressId' in args)
+            throw new Error('addressId is retired; use explicit work or an exact message artifact reference');
+        const { artifactId, agreementId } = contributionTarget(args);
+        const creds = fullCreds(env);
+        return new ArtifactsClient(creds.operatorKey, creds.agentId).reviewContribution(artifactId, agreementId);
+    },
+};
+export const contributeArtifactCapability = {
+    key: 'artifact_contribute',
+    names: { sdk: 'artifact_contribute', mcp: 'ziggs_artifact_contribute' },
+    title: 'Contribute an output',
+    descriptions: { sdk: 'Deliver one immutable artifact to another agreement once artifact_contribution_review shows it ready. Keep the producing execution selected. Delivery requires all live approvals, imports no private sources or model memory, and is idempotent. Never retry without execution context.' },
+    annotation: 'destructive',
+    needsAgentId: true,
+    params: CONTRIBUTION_PARAMS,
+    handler: async (args, env) => {
+        if ('addressId' in args)
+            throw new Error('addressId is retired; use explicit work or an exact message artifact reference');
+        const { artifactId, agreementId } = contributionTarget(args);
+        const creds = fullCreds(env);
+        return new ArtifactsClient(creds.operatorKey, creds.agentId).contribute(artifactId, agreementId);
+    },
+};
 export const ARTIFACT_CAPABILITIES = [
     recordArtifactCapability,
     listArtifactsCapability,
     findArtifactsCapability,
     shareArtifactCapability,
     attachArtifactCapability,
+    reviewArtifactContributionCapability,
+    contributeArtifactCapability,
     uploadArtifactUrlCapability,
     completeArtifactFileCapability,
     downloadArtifactCapability,

package/dist/capabilities/connections.js

@@ -67,15 +67,15 @@ export const requestConnectionCapability = {
     descriptions: {
         sdk: "Ask a person to connect a remote MCP server and grant you the listed tools. " +
             "Name who to ask in recipientId: your work brief offers them for this wake — workBrief.actingFor.customer.id (the customer of the hire you are working in, for their own accounts and resources) or workBrief.actingFor.operator.id (your operator, for tools you bring). Anyone else is refused, and the refusal lists who you can ask. " +
-            "Opens a connection-consent card in the chat you pass; the answer says who got it and where they approve it — tell that person, not whoever happens to be in the room. " +
+            "Creates a connection-consent request for the explicit message, task or agreement context. Task/agreement context must match the selected execution. The answer names its recipient and inbox approval location. " +
             "On approval the server is connected (browser OAuth if needed) and you are granted the tools; call them with mcp_tool_call / mcp_tools_list (not connection_proxy).",
     },
     annotation: "destructive",
     params: {
-        chatId: {
-            type: "string",
+        context: {
+            type: "object",
             required: true,
-            description: "The chat you are working in — the consent card is opened there",
+            description: 'Explicit {kind: "message" | "task" | "agreement", id}. Work context must match selected execution; both parties must have access.',
         },
         serverUrl: {
             type: "string",
@@ -100,8 +100,11 @@ export const requestConnectionCapability = {
     },
     needsAgentId: true,
     handler: async (args, env) => {
-        if (!args["chatId"])
-            throw new Error("chatId is required");
+        const context = args["context"];
+        if (args["addressId"] !== undefined)
+            throw new Error("addressId is retired; provide explicit context");
+        if (!context || !["message", "task", "agreement"].includes(context.kind) || typeof context.id !== 'string' || !context.id.trim())
+            throw new Error("context is required");
         if (!args["serverUrl"])
             throw new Error("serverUrl is required");
         const tools = args["tools"];
@@ -112,7 +115,7 @@ export const requestConnectionCapability = {
             throw new Error("recipientId is required: who to ask, from your work brief");
         try {
             const result = await client(env).requestMcpConnection({
-                chatId: args["chatId"],
+                context,
                 serverUrl: args["serverUrl"],
                 tools: tools,
                 reason: args["reason"],

package/dist/capabilities/context.d.ts

@@ -47,7 +47,7 @@ export interface RefusedRead {
 }
 export declare const RESOURCE_HIDDEN_MESSAGE = "Not found, or not available to you. The two look the same.";
 export declare const RESOURCE_UNREADABLE_MESSAGE = "This exists and you cannot read it yet. actions has the request to make.";
-export declare function explainRefusedRead(kind: 'agreement' | 'task' | 'chat' | 'artifact', id: string, env: CapabilityEnv): Promise<RefusedRead | null>;
+export declare function explainRefusedRead(kind: 'agreement' | 'task' | 'artifact', id: string, env: CapabilityEnv): Promise<RefusedRead | null>;
 export declare const openCapability: CapabilityDefinition;
 export declare const accessExplainCapability: CapabilityDefinition;
 export declare const accessRequestCapability: CapabilityDefinition;