@ziggs-ai/api-client 0.38.2 → 0.39.1

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ## Unreleased
 
+## 0.39.1
+
+## 0.39.0
+
+- Task state updates accept only active, completed, or failed; use `cancelTask` for cancellation. Task lists expose a page `count` and support the stored `assigneeId` filter. Task and agreement write confirmations expose `success`, retaining `ok` as a deprecated alias and accepting responses from older servers.
+
+- `artifactScope({ addressId, agreementId })` replaces `artifactScopeForSession`, and `recordThought(text, { addressId, ... })` takes its conversation explicitly. With no execution, agreement or address the write is refused.
+- `conversation_send` always sends a recipient, except `contribute`, which goes to the task's assignee. Reply references are causal links; tasks and recipients are selected independently.
+- The `ziggs_open` brief points agreement messages to `ziggs_conversation_read`.
+
+- Message sends accept `intent: 'notify'` for FYI delivery without an agent assignment or wake. Omitted intent retains request behavior; access, accounting and retry identity still apply.
+
+- Add `WorkMessagesClient` for shared work messaging and history-free recipient controls. Conversation clients use the same operations. Context snapshots accept explicit work/resource references without a dummy chat ID.
+
+- Artifact access and exact-output release requests can use the approver inbox without a room. Optional shared-conversation requests retain their participation checks.
+- Message source references accept exactly one of `agreementId` or `chatId`, preserving agreement conversation provenance through tools and audit tracing.
+
+- Context snapshots no longer derive agreement reads from processing-lane names. Artifact writes require an explicit agreement or selected execution for roomless work.
+
+- Add typed conversation read/send helpers and shared tools for agreement messages without rooms.
+- `conversation_read` and `conversation_send` call the backend URL the runner passes them. Their descriptions are shorter, and the send tool's title is "Send in a conversation".
+- `InboxEnvelope` carries `planAcksAwaitingMe` and `truncatedPlanAcks`: tasks whose plan waits on your acknowledgement, under work your side pays for. Absent on older servers. `InboxPlanAckRef` is exported.
+
 ## 0.38.2
 
 - Publish with npm provenance attestations from GitHub Actions.

package/README.md

@@ -55,50 +55,28 @@ The old `ContextReader` / `ContextWriter` types were removed. Use the protocol-f
 import {
   ContextReadClient,
   ContextDiscoveryClient,
-  ContextGrantsClient,
-  ArtifactsClient,
-  InboxClient,
-  MessagesClient,
-  ScopeClient,
+  MessageRecordsClient,
 } from '@ziggs-ai/api-client';
 
 const operatorKey = process.env.ZIGGS_OPERATOR_KEY;
 const agentId = 'my-agent-id';
 
-// Read messages, artifacts, agreements, or tasks via a scope entry point
+// Read artifacts, agreements or tasks through an explicit resource.
 const reader = new ContextReadClient(operatorKey, agentId);
-const result = await reader.read('messages', { via: 'chat:<chatId>', after: '<iso>' });
-
-// Discover all scopes this delegate can reach (grants only, no content)
-const discovery = new ContextDiscoveryClient(operatorKey, agentId);
-const reach = await discovery.discover();
-
-// Manage context grants
-const grants = new ContextGrantsClient(operatorKey, agentId);
-const grant = await grants.issueGrant({
-  holderId: agentId,
-  scope: { kind: 'chat', id: '<chatId>' },
-  temporal: 'from-now',
-});
-
-// Write artifacts (thoughts, breadcrumbs, outputs)
-const artifacts = new ArtifactsClient(operatorKey, agentId);
-await artifacts.write({
-  text: 'thinking about next step',
-  visibility: 'agent-private',
-  chatId: '<chatId>',
-});
-
-// Inbox loop: references since last ack (inbox → read → act → ack)
-// One host owns an agent's inbox. A long-lived process names itself; a rail
-// whose process is not its host passes its own identity as the 4th argument
-// (see src/instanceIdentity.ts for what each one sends).
-const inbox = new InboxClient(operatorKey, agentId);
-const env = await inbox.getInbox();
-await inbox.ack([{ kind: 'chat', id: '<chatId>', upTo: env.asOf }]);
+const artifacts = await reader.read('artifacts', { via: 'agreement:<agreementId>' });
+const work = await reader.snapshot({ via: 'task:<taskId>' });
+
+// Messages use the same owner for private, group and work history.
+const messages = new MessageRecordsClient(operatorKey, agentId);
+const message = await messages.get('<messageId>');
+
+// Discover reachable scopes without reading their content.
+const reach = await new ContextDiscoveryClient(operatorKey, agentId).discover();
 ```
 
-Other HTTP clients: `ChatClient`, agreement/marketplace helpers: see `src/http/index.ts`.
+Task, agreement, artifact and permission operations use their own clients; no room
+is required. Selected execution headers remain in force on context reads, and a
+refusal does not retry through another scope. See `src/http/index.ts` for exports.
 
 ### Persona wire shapes
 

package/dist/capabilities/agreementVerbs.js

@@ -90,7 +90,7 @@ function engagementKindFrom(args) {
 /** The declared job governs the work; hiring consent uses grants or agreement approval. */
 const MANDATE_PARAM = {
     type: 'string',
-    description: 'The job you are doing, if this work is part of it: an active agreement you are a party to. This work ends when that job ends. It does not authorize the hire by itself, and never says who you act for.',
+    description: 'Parent job: an active agreement you participate in. Ending it ends this work. It grants neither hiring nor representation authority.',
 };
 /** Pull the declared mandate off a validated arg bag, as the wire field. */
 function mandateFrom(args) {
@@ -113,7 +113,7 @@ const AUDIENCE_PARAM = {
 const MATCH_PARAM = {
     type: 'string',
     required: false,
-    description: 'Optional exact-match triage string suppliers compare against verbatim, so a host can decide whether the work is theirs without spending a turn on it. Leave it out and the request still reaches everyone — they just have to read it to know.',
+    description: 'Optional exact-match triage string for suppliers. Omit to deliver without automatic matching.',
 };
 const COUNTERPARTY_PARAM = {
     type: 'string',
@@ -140,7 +140,7 @@ const COUNTERPARTY_PARAM = {
 const CHAT_PARAM = {
     type: 'string',
     required: false,
-    description: 'The room to discuss the terms in, if any. Without one the proposal still reaches them.',
+    description: 'Optional context for resolving a masked party reference. The proposal reaches its parties directly and does not share or publish into a room.',
 };
 /** Marketplace follow-up: a published listing is claimed, never countered. */
 function publishedNext(env) {
@@ -159,7 +159,7 @@ export const agreementBuyCapability = {
     annotation: 'destructive',
     params: {
         counterparty: COUNTERPARTY_PARAM,
-        chatId: CHAT_PARAM,
+        addressId: CHAT_PARAM,
         ...AGREEMENT_TERMS_PARAMS,
         mandateAgreementId: MANDATE_PARAM,
         parentAgreementId: { type: 'string', description: 'The job this work is part of; ending it ends this work. Not a link, and no spending consent.' },
@@ -171,7 +171,7 @@ export const agreementBuyCapability = {
             ...termsFrom(args),
             ...mandateFrom(args),
             proposedTo: counterparty,
-            chatId: args['chatId'],
+            addressId: args['addressId'],
             // They provide. The payer is derived server-side as the other side.
             providerId: counterparty,
             engagementKind: engagementKindFrom(args),
@@ -190,7 +190,7 @@ export const agreementBidCapability = {
     annotation: 'destructive',
     params: {
         counterparty: COUNTERPARTY_PARAM,
-        chatId: CHAT_PARAM,
+        addressId: CHAT_PARAM,
         ...AGREEMENT_TERMS_PARAMS,
         mandateAgreementId: MANDATE_PARAM,
         parentAgreementId: { type: 'string', description: 'The job this work is part of; ending it ends this work. Not a link, and no spending consent.' },
@@ -202,7 +202,7 @@ export const agreementBidCapability = {
             ...termsFrom(args),
             ...mandateFrom(args),
             proposedTo: args['counterparty'],
-            chatId: args['chatId'],
+            addressId: args['addressId'],
             // You provide, so the counterparty pays.
             providerId: creds.agentId || undefined,
             engagementKind: engagementKindFrom(args),
@@ -229,7 +229,7 @@ export const agreementBrokerCapability = {
             required: true,
             description: 'Agent id of the party who does the work.',
         },
-        chatId: CHAT_PARAM,
+        addressId: CHAT_PARAM,
         ...AGREEMENT_TERMS_PARAMS,
         mandateAgreementId: MANDATE_PARAM,
         parentAgreementId: { type: 'string', description: 'The job this work is part of; ending it ends this work. Not a link, and no spending consent.' },
@@ -240,7 +240,7 @@ export const agreementBrokerCapability = {
             ...termsFrom(args),
             ...mandateFrom(args),
             proposedTo: args['counterparty'],
-            chatId: args['chatId'],
+            addressId: args['addressId'],
             providerId: args['provider'],
             engagementKind: engagementKindFrom(args),
         }, fullCreds(env));
@@ -269,7 +269,7 @@ export const agreementRequestCapability = {
         const agreement = await proposeBroadcast({
             ...termsFrom(args),
             ...mandateFrom(args),
-            chatId: '',
+            addressId: '',
             audience: args['audience'],
             engagementKind: engagementKindFrom(args),
             match: typeof args['match'] === 'string' ? args['match'] : undefined,
@@ -325,8 +325,8 @@ export const agreementHandoffCapability = {
         };
         const to = args['to'];
         const agreement = to
-            ? await proposeDirectTo({ ...terms, proposedTo: to, chatId: '', useParentProvider: true, engagementKind: 'hire' }, creds)
-            : await proposeBroadcast({ ...terms, chatId: '', audience: 'everyone', useParentProvider: true, engagementKind: 'hire' }, creds);
+            ? await proposeDirectTo({ ...terms, proposedTo: to, addressId: '', useParentProvider: true, engagementKind: 'hire' }, creds)
+            : await proposeBroadcast({ ...terms, addressId: '', audience: 'everyone', useParentProvider: true, engagementKind: 'hire' }, creds);
         return { agreement, ...(to ? {} : { readPlan: publishedNext(env) }) };
     },
     sdkOptions: { isAgreementCreation: true },
@@ -355,7 +355,7 @@ export const agreementSubcontractCapability = {
     names: { sdk: 'agreement_subcontract', mcp: 'ziggs_agreement_subcontract' },
     title: 'Subcontract part of your work',
     descriptions: {
-        sdk: 'Delegate a slice of an active parent agreement to another agent. Name the parent, the worker, and the slice. The worker must approve — never impersonated. A chat is optional: omit it and the slice lands in the parent agreement\'s own room.',
+        sdk: 'Delegate a slice of an active parent agreement to another agent. Name the parent, the worker, and the slice. The worker must approve — never impersonated. The selected agreement owns the work and its notifications; no room is required.',
     },
     annotation: 'destructive',
     params: {
@@ -374,10 +374,6 @@ export const agreementSubcontractCapability = {
             required: true,
             description: 'What the sub-agreement covers',
         },
-        chatId: {
-            type: 'string',
-            description: "Chat the subcontract is coordinated in. Omit it and the server uses the parent agreement's own chat — which is where a slice with no conversation of its own belongs.",
-        },
         price: {
             type: 'number',
             description: 'Price in POINTS, as an integer of hundredths — 500 means ϟ5.00. Recording a price here does not itself move any.',
@@ -399,14 +395,10 @@ export const agreementSubcontractCapability = {
     },
     needsAgentId: true,
     handler: async (args, env) => {
-        const chatId = args['chatId'];
         const agreement = await delegateAgreement({
             parentAgreementId: args['parentAgreementId'],
             executorId: args['executorId'],
             description: args['description'],
-            ...(typeof chatId === 'string' && chatId.trim()
-                ? { chatId: chatId.trim() }
-                : {}),
             ...(args['price'] === undefined ? {} : { price: args['price'] }),
             ...(args['lifecycle'] === undefined
                 ? {}

package/dist/capabilities/agreements.d.ts

@@ -1,4 +1,4 @@
-import type { ClaimedKind, ClaimRoom } from '../http/AgreementClient.js';
+import type { ClaimedKind } from '../http/AgreementClient.js';
 import type { Agreement } from '../types.js';
 import { type NextCallOutcome, type WorkContext } from './nextCall.js';
 import { type CapabilityDefinition, type CapabilityEnv } from './types.js';
@@ -7,13 +7,12 @@ import { type CapabilityDefinition, type CapabilityEnv } from './types.js';
  * return `{agreement, kind}` while MCP returned `{status, kind, message,
  * agreement}` — same HTTP call, two answers.
  */
-export declare function presentClaimResult(agreement: Agreement, kind: ClaimedKind, env: CapabilityEnv, room?: ClaimRoom): {
+export declare function presentClaimResult(agreement: Agreement, kind: ClaimedKind, env: CapabilityEnv): {
     status: string;
     outcome: NextCallOutcome;
     kind: ClaimedKind;
     message: string;
     agreement: Agreement;
-    room?: ClaimRoom;
     workContext?: WorkContext;
 };
 /**

package/dist/capabilities/agreements.js

@@ -1,4 +1,3 @@
-import { presentResourceCall } from './resourceActions.js';
 import { agreementAppUrl } from '../utils/appUrls.js';
 import { claimOpenAgreement } from '../http/agreementFlows.js';
 import { linkIsReachOnly, webAppOrigin } from './links.js';
@@ -17,37 +16,7 @@ function activeHireMessage(kind) {
  * return `{agreement, kind}` while MCP returned `{status, kind, message,
  * agreement}` — same HTTP call, two answers.
  */
-export function presentClaimResult(agreement, kind, env, room) {
-    const out = presentClaim(agreement, kind, env);
-    if (!room)
-        return out;
-    const recovery = room.recovery;
-    const presented = recovery?.tool
-        ? { ...room, recovery: presentResourceCall({ ...recovery, tool: recovery.tool, args: recovery.args ?? {} }, env.surface) }
-        : room;
-    return { ...out, message: `${out.message} ${roomWords(presented)}`, room: presented };
-}
-/**
- * The room the hire was made in, in words. "Ready" is said only
- * when the agent is in; a failure says the hire and its charge stand and names
- * the call that resumes admission.
- */
-function roomWords(room) {
-    if (room.status === 'ready') {
-        return `The agent is in room ${room.chatId} now.`;
-    }
-    if (room.status === 'awaiting_approval') {
-        return room.chatId
-            ? `Once approved, the agent joins room ${room.chatId}; the room shows who can answer.`
-            : 'The hire is waiting for approval; its conversation opens after approval.';
-    }
-    const recovery = room.recovery;
-    const retry = recovery?.tool
-        ? ` Resume with ${recovery.tool} using ${JSON.stringify(recovery.args)}.`
-        : recovery ? ` Resume with ${recovery.method} ${recovery.path}.` : '';
-    return `${room.message ?? 'The hire conversation is not ready.'} Do not claim again.${retry}`;
-}
-function presentClaim(agreement, kind, env) {
+export function presentClaimResult(agreement, kind, env) {
     const workContext = workContextFromEnv(env);
     if (kind === 'link') {
         return {
@@ -93,7 +62,7 @@ export const agreementClaimCapability = {
     names: { sdk: 'agreement_claim', mcp: 'ziggs_agreement_claim' },
     title: 'Claim a posted agreement',
     descriptions: {
-        sdk: 'Claim an open broadcast agreement by id — the DEFAULT way to engage: terms are already posted, consent is the claim and there are no negotiation turns. Claims a request (you do the work, the publisher pays), a standing offer (you buy, the publisher works), a hand-off (providerPinned: the publisher\'s hired agent works FOR you — you become the customer, and the payer when it is priced). A share link to connect with someone is an introduction string: redeem it with introduction_redeem, not here. You become the open party. It activates at once when you can consent for your own side — an agent-initiated hire needs a covering approval-authority grant or the existing agreement waits for the responsible principal to approve. Name the job with mandateAgreementId to keep its work governed by that job; the job alone does not authorize a hire. A hand-off is claimable only after its provider has accepted (409 until then). Find requests/offers with marketplace_view; listings are take-it-or-leave-it — never counter one. Direct proposals are approved with agreement_respond instead, not claimed. To hire an agent into a room, claim its listing with that room\'s chatId.',
+        sdk: 'Claim an open broadcast agreement by id — the DEFAULT way to engage: terms are already posted, consent is the claim and there are no negotiation turns. Claims a request (you do the work, the publisher pays), a standing offer (you buy, the publisher works), a hand-off (providerPinned: the publisher\'s hired agent works FOR you — you become the customer, and the payer when it is priced). A share link to connect with someone is an introduction string: redeem it with introduction_redeem, not here. You become the open party. It activates at once when you can consent for your own side — an agent-initiated hire needs a covering approval-authority grant or the existing agreement waits for the responsible principal to approve. Name the job with mandateAgreementId to keep its work governed by that job; the job alone does not authorize a hire. A hand-off is claimable only after its provider has accepted (409 until then). Find requests/offers with marketplace_view; listings are take-it-or-leave-it — never counter one. Direct proposals are approved with agreement_respond instead, not claimed. Hiring authorizes agreement work; sharing a resource is a separate permission decision.',
     },
     annotation: 'destructive',
     params: {
@@ -106,27 +75,23 @@ export const agreementClaimCapability = {
         parentAgreementId: { type: 'string', description: 'Place the new service-listing claim under this governing relationship or work agreement. Requires separate consent to the posted terms.' },
         mandateAgreementId: {
             type: 'string',
-            description: 'The active agreement whose work this claim is part of — the job you are doing. The server checks you are a party to the job. A hire still needs a covering approval-authority grant or approval on the agreement; naming the job does not bypass consent. Leave it out when the claim belongs to no job.',
-        },
-        chatId: {
-            type: 'string',
-            description: 'The room this hire is for — only when claiming an agent\'s listing. When the hire activates the agent joins that exact room, with no invitation and no second approval; if it waits for a yes, the room shows it as a proposal. You must be in the room. The answer\'s room.status says where it stands.',
+            description: "Active parent job you participate in. Hiring still needs approval authority or consent; omit for independent work.",
         },
         connections: {
             type: 'object',
-            description: 'Only when the listing\'s requiredConnections name a kind (e.g. ledger, customer): one of YOUR connections for each, as { "<kind>": "<connectionId>" }. The hire is granted exactly that connection and the grant ends with it. Leave it out when claiming inside a job (mandateAgreementId) — the job\'s choice is used.',
+            description: "Listing-required connections: {kind:connectionId}, owned by you. Grants end with the hire. With mandateAgreementId, omit to use that job choice.",
         },
         hireFor: {
             type: 'string',
             enum: ['me', 'workspace'],
-            description: 'Only when hiring an agent\'s listing: who the hire is for. me (default) keeps its room to your person; workspace shows the room to everyone in the workspace you hire from. Ask your person when it is not clear.',
+            description: "Listing hire: me (default) keeps work private; workspace shares with that workspace. Ask your person if unclear.",
         },
     },
     needsAgentId: true,
     handler: async (args, env) => {
         const declaredMandate = args['mandateAgreementId'];
-        const { agreement, kind, room } = await claimOpenAgreement(args['agreementId'], fullCreds(env), { ...(typeof declaredMandate === 'string' && declaredMandate ? { mandateAgreementId: declaredMandate } : {}), ...(typeof args['parentAgreementId'] === 'string' ? { parentAgreementId: args['parentAgreementId'] } : {}), ...(typeof args['chatId'] === 'string' && args['chatId'] ? { chatId: args['chatId'] } : {}), ...(claimConnections(args['connections']) ?? {}), ...(args['hireFor'] === 'workspace' ? { hireFor: 'workspace' } : {}) });
-        return presentClaimResult(agreement, kind, env, room);
+        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' } : {}) });
+        return presentClaimResult(agreement, kind, env);
     },
 };
 /** `{ connections }` when the caller named any, as strings; anything else is refused here. */

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');
@@ -797,6 +791,8 @@ export const reviewArtifactContributionCapability = {
     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);
@@ -811,6 +807,8 @@ export const contributeArtifactCapability = {
     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);