@ziggs-ai/api-client 0.38.0 → 0.39.0

package/dist/http/AgreementClient.d.ts

@@ -43,17 +43,8 @@ export interface ProposeTerms {
 /** 1:1 proposal to a specific user or agent (`proposedTo` = their id). */
 export interface ProposeDirectInput extends ProposeTerms {
     proposedTo: string;
-    /**
-     * The room the terms are discussed in, when there is one.
-     *
-     * Optional, matching the server, which has always accepted a proposal
-     * without one. Delivery does not depend on it: the create-time agreement
-     * event targets the party slots, so the counterparty is told either way; a
-     * room only gives them somewhere to talk about it. Required here was what
-     * forced a bookkeeping agreement between parties with no conversation to
-     * invent a chat id in order to exist.
-     */
-    chatId?: string;
+    /** Optional display-reference context for resolving a masked party; does not publish or share. */
+    addressId?: string;
 }
 /**
  * Open buyer-broadcast. `audience` selects who may see/claim it:
@@ -133,8 +124,6 @@ export interface DelegateAgreementData {
     /** What this text drew on. See {@link WriteSource}. */
     sources?: WriteSource[];
     executorId: string;
-    /** Omit it and the server uses the parent agreement's own chat. */
-    chatId?: string;
     parentAgreementId: string;
     price?: number;
     lifecycle?: string;
@@ -258,6 +247,20 @@ export interface CreateLinkBody {
     description?: string;
     /** Open invites only: how many people may claim this one link. Default 1. */
     maxClaims?: number;
+    /**
+     * A chat, task or agreement you hold. Approving the link lets the person
+     * and the agent named in `to` into it; already linked, they are in now.
+     * Needs `to`.
+     */
+    about?: {
+        kind: 'agreement' | 'task' | 'address';
+        id: string;
+    };
+}
+export interface WriteSuccess {
+    success: boolean;
+    /** @deprecated Use success. */
+    ok: boolean;
 }
 /**
  * The route's answer.
@@ -278,8 +281,7 @@ export interface CreateLinkBody {
  * Without it a caller could not reference what it had just created, check on it
  * later, or tell a repeat from a first attempt.
  */
-export interface CreateLinkResult {
-    ok: boolean;
+export interface CreateLinkResult extends WriteSuccess {
     status: 'sent';
     /** The link row, for a named agent id or an open invite. Null for an email. */
     agreementId: string | null;
@@ -295,14 +297,12 @@ export interface CreateLinkResult {
  * carries links and nothing else.
  */
 export declare function createLink(body: CreateLinkBody, creds: Creds): Promise<CreateLinkResult>;
-export declare function revokeAgreement(agreementId: string, creds: Creds): Promise<{
-    ok: boolean;
+export declare function revokeAgreement(agreementId: string, creds: Creds): Promise<WriteSuccess & {
     agreement: Agreement;
 }>;
 /** mark an agreement fulfilled (complete). A provider closing its own
  * delivered work — party-gated server-side. */
-export declare function fulfillAgreement(agreementId: string, creds: Creds): Promise<{
-    ok: boolean;
+export declare function fulfillAgreement(agreementId: string, creds: Creds): Promise<WriteSuccess & {
     agreement: Agreement;
 }>;
 /** What an open-broadcast claim resolved to. ⚠️ Mirrors the server; it is authoritative. */
@@ -335,11 +335,6 @@ export interface ClaimOptions {
      * verifies the claim against the acting agent and never guesses one.
      */
     mandateAgreementId?: string;
-    /**
-     * The room a hire of a listing is made in. On activation its
-     * agent joins that room; the claimer must take part in it.
-     */
-    chatId?: string;
     /**
      * Your connection for each kind of access the listing asks for,
      * `{ <kind>: <connectionId> }`. The hire is granted exactly that connection. A claim made inside a job (mandateAgreementId)
@@ -347,42 +342,15 @@ export interface ClaimOptions {
      */
     connections?: Record<string, string>;
     /**
-     * Who a hire of a listing is for. `me` (the default) keeps its room to the
-     * person; `workspace` makes the workspace the payer and shows the room to
-     * every member.
+     * Who a hire is for. `me` keeps the agreement private; `workspace` makes
+     * the workspace the payer and shares work with its members.
      */
     hireFor?: 'me' | 'workspace';
 }
-/**
- * Where a hire made in a room stands on getting its agent in.
- * `ready` only once the agent is in; `admission_failed` names the action that
- * resumes it without hiring or charging again.
- */
-export interface ClaimRoom {
-    chatId?: string;
-    status: 'awaiting_approval' | 'ready' | 'admission_failed' | 'preparation_failed' | 'unavailable';
-    message?: string;
-    recovery?: {
-        method: string;
-        path: string;
-        tool?: string;
-        args?: Record<string, unknown>;
-    };
-}
-export declare function claimAgreement(agreementId: string, creds: Creds, opts?: ClaimOptions): Promise<{
-    ok: boolean;
+export declare function claimAgreement(agreementId: string, creds: Creds, opts?: ClaimOptions): Promise<WriteSuccess & {
     agreement: Agreement;
     kind?: ClaimedKind;
-    room?: ClaimRoom;
 }>;
-/**
- * Link types a caller may ask for. `origin` and `delegation` are workflow-owned;
- * callers may only pin an agreement into a chat as a reference (`mention`).
- */
-export declare const CHAT_LINK_TYPES: readonly ["mention"];
-export type ChatLinkType = (typeof CHAT_LINK_TYPES)[number];
-export declare function linkAgreementToChat(agreementId: string, chatId: string, linkType: ChatLinkType | undefined, creds: Creds): Promise<unknown | null>;
-export declare function getChatsForAgreement(agreementId: string, creds: Creds): Promise<unknown[]>;
 export declare const ARTIFACT_LINK_TYPES: readonly ["produced", "referenced"];
 export type ArtifactLinkType = (typeof ARTIFACT_LINK_TYPES)[number];
 export declare function linkArtifactToAgreement(agreementId: string, artifactId: string, linkType: ArtifactLinkType | undefined, creds: Creds): Promise<unknown | null>;
@@ -408,22 +376,16 @@ export declare class AgreementClient {
     listMine(filters?: GetMyAgreementsFilters): Promise<Agreement[]>;
     get(id: string): Promise<Agreement | null>;
     createLink(data: CreateLinkBody): Promise<CreateLinkResult>;
-    revoke(id: string): Promise<{
-        ok: boolean;
+    revoke(id: string): Promise<WriteSuccess & {
         agreement: Agreement;
     }>;
-    fulfill(id: string): Promise<{
-        ok: boolean;
+    fulfill(id: string): Promise<WriteSuccess & {
         agreement: Agreement;
     }>;
-    claimAgreement(id: string): Promise<{
-        ok: boolean;
+    claimAgreement(id: string): Promise<WriteSuccess & {
         agreement: Agreement;
         kind?: ClaimedKind;
-        room?: ClaimRoom;
     }>;
-    linkToChat(id: string, chatId: string, linkType?: ChatLinkType): Promise<unknown>;
-    listChats(id: string): Promise<unknown[]>;
     linkArtifact(id: string, artifactId: string, linkType?: ArtifactLinkType): Promise<unknown>;
     listArtifacts(id: string): Promise<unknown[]>;
 }

package/dist/http/AgreementClient.js

@@ -472,6 +472,10 @@ export async function getAgreement(agreementId, creds) {
     const agreement = await getAgreementDocument(agreementId, creds);
     return agreement ? shapeAgreement(agreement) : null;
 }
+function writeSuccess(data) {
+    const success = data['success'] === true || (data['success'] === undefined && data['ok'] === true);
+    return { success, ok: success };
+}
 /**
  * Connect with someone — by email, by agent id, or with a shareable invite.
  *
@@ -496,12 +500,12 @@ export async function createLink(body, creds) {
     }
     const data = await res.json().catch(() => null);
     if (data?.['status'] !== 'sent') {
-        throw new Error('Invalid response: expected { ok, status: "sent", shareUrl } from POST /agreements/links');
+        throw new Error('Invalid response: expected { success, status: "sent", shareUrl } from POST /agreements/links');
     }
     const shareUrl = data['shareUrl'];
     const agreementId = data['agreementId'];
     return {
-        ok: data['ok'] === true,
+        ...writeSuccess(data),
         status: 'sent',
         agreementId: typeof agreementId === 'string' ? agreementId : null,
         shareUrl: typeof shareUrl === 'string' ? shareUrl : null,
@@ -511,8 +515,7 @@ export async function revokeAgreement(agreementId, creds) {
     if (!agreementId)
         throw new Error('agreementId is required for revocation');
     assertCreds(creds, 'agreement revocation');
-    // canonical REST verb. Legacy POST /agreements/:id/revoke stays
-    // serving the identical handler (with Deprecation headers) until PR-F.
+    // Revocation uses the resource DELETE operation.
     const res = await fetch(`${getAgreementBaseUrl()}/${encodeURIComponent(agreementId)}`, {
         method: 'DELETE',
         headers: buildHeaders(creds),
@@ -523,10 +526,10 @@ export async function revokeAgreement(agreementId, creds) {
     }
     const data = await res.json().catch(() => null);
     if (!data?.['agreement']) {
-        throw new Error('Invalid response: expected { ok, agreement } from DELETE /agreements/:id');
+        throw new Error('Invalid response: expected { success, agreement } from DELETE /agreements/:id');
     }
     const envelope = data;
-    return { ...envelope, agreement: shapeAgreement(envelope.agreement) };
+    return { ...envelope, ...writeSuccess(data), agreement: shapeAgreement(envelope.agreement) };
 }
 /** mark an agreement fulfilled (complete). A provider closing its own
  * delivered work — party-gated server-side. */
@@ -544,10 +547,10 @@ export async function fulfillAgreement(agreementId, creds) {
     }
     const data = await res.json().catch(() => null);
     if (!data?.['agreement']) {
-        throw new Error('Invalid response: expected { ok, agreement } from POST /agreements/:id/fulfill');
+        throw new Error('Invalid response: expected { success, agreement } from POST /agreements/:id/fulfill');
     }
     const envelope = data;
-    return { ...envelope, agreement: shapeAgreement(envelope.agreement) };
+    return { ...envelope, ...writeSuccess(data), agreement: shapeAgreement(envelope.agreement) };
 }
 export async function claimAgreement(agreementId, creds, opts = {}) {
     if (!agreementId)
@@ -556,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.chatId ? { chatId: opts.chatId } : {}), ...(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' } : {}) }),
     });
     if (!res.ok) {
         const body = await res.text().catch(() => '');
@@ -564,66 +567,14 @@ export async function claimAgreement(agreementId, creds, opts = {}) {
     }
     const data = await res.json().catch(() => null);
     if (!data?.['agreement']) {
-        throw new Error('Invalid response: expected { ok, agreement } from POST /agreements/:id/claim');
+        throw new Error('Invalid response: expected { success, agreement } from POST /agreements/:id/claim');
     }
     // the route reports which kind of broadcast this turned out to be.
     // A caller cannot work it out from the row — post-claim no sentinel is left,
     // and a request (you do the work) reads the same shape as a standing offer (you
     // pay for it) unless you know which slot you landed in.
     const envelope = data;
-    return { ...envelope, agreement: shapeAgreement(envelope.agreement) };
-}
-// ---------------------------------------------------------------------------
-// Chat links
-// ---------------------------------------------------------------------------
-/**
- * Link types a caller may ask for. `origin` and `delegation` are workflow-owned;
- * callers may only pin an agreement into a chat as a reference (`mention`).
- */
-export const CHAT_LINK_TYPES = ['mention'];
-export async function linkAgreementToChat(agreementId, chatId, linkType = 'mention', creds) {
-    if (!agreementId || !chatId)
-        return null;
-    assertCreds(creds, 'link agreement to chat');
-    try {
-        const res = await fetch(`${getAgreementBaseUrl()}/${agreementId}/link`, {
-            method: 'POST',
-            headers: buildHeaders(creds),
-            body: JSON.stringify({ chatId, linkType }),
-        });
-        if (!res.ok) {
-            const body = await res.text().catch(() => '');
-            runtimeLog.warn('AgreementClient', `⚠️ Link agreement to chat failed: ${res.status} ${res.statusText} ${body?.slice(0, 200)}`);
-            return null;
-        }
-        return await res.json().catch(() => null);
-    }
-    catch (e) {
-        runtimeLog.warn('AgreementClient', `⚠️ Link agreement to chat failed: ${e.message}`);
-        return null;
-    }
-}
-export async function getChatsForAgreement(agreementId, creds) {
-    if (!agreementId)
-        return [];
-    assertCreds(creds, 'get chats for agreement');
-    try {
-        const res = await fetch(`${getAgreementBaseUrl()}/${agreementId}/chats`, {
-            method: 'GET',
-            headers: buildHeaders(creds),
-        });
-        if (!res.ok) {
-            const body = await res.text().catch(() => '');
-            runtimeLog.warn('AgreementClient', `⚠️ Get chats for agreement failed: ${res.status} ${res.statusText} ${body?.slice(0, 200)}`);
-            return [];
-        }
-        const data = await res.json().catch(() => null);
-        return Array.isArray(data?.['links']) ? data['links'] : [];
-    }
-    catch (e) {
-        runtimeLog.warn('AgreementClient', `⚠️ Get chats for agreement failed: ${e.message}`);
-        return [];
-    }
+    return { ...envelope, ...writeSuccess(data), agreement: shapeAgreement(envelope.agreement) };
 }
 // ---------------------------------------------------------------------------
 // Artifact links
@@ -701,8 +652,6 @@ export class AgreementClient {
     revoke(id) { return revokeAgreement(id, this.creds); }
     fulfill(id) { return fulfillAgreement(id, this.creds); }
     claimAgreement(id) { return claimAgreement(id, this.creds); }
-    linkToChat(id, chatId, linkType) { return linkAgreementToChat(id, chatId, linkType ?? 'mention', this.creds); }
-    listChats(id) { return getChatsForAgreement(id, this.creds); }
     linkArtifact(id, artifactId, linkType) { return linkArtifactToAgreement(id, artifactId, linkType ?? 'produced', this.creds); }
     listArtifacts(id) { return getArtifactsForAgreement(id, this.creds); }
 }

package/dist/http/ArtifactsClient.d.ts

@@ -8,13 +8,12 @@ import type { ListReachableArtifactsResult } from '@ziggs-ai/contracts';
 export declare const ARTIFACT_INLINE_TEXT_MAX_CHARS = 50000;
 /** Named escape hatch for agents that hit the inline cap. */
 export declare const ARTIFACT_INLINE_TEXT_OVER_LIMIT_HINT: string;
-export type ArtifactVisibility = 'chat' | 'agent-private';
+export type ArtifactVisibility = 'address' | 'agent-private';
 export interface ListArtifactsOptions {
     after?: string;
     limit?: number;
 }
 export interface ListArtifactsQuery {
-    chatId?: string;
     agreementId?: string;
     taskId?: string;
     serviceAgreementId?: string;
@@ -73,7 +72,6 @@ export interface WriteArtifactInput {
     contentType?: string;
     visibility?: ArtifactVisibility;
     /** When the artifact is associated with a chat. */
-    chatId?: string;
     /** When the artifact is associated with an agreement. */
     agreementId?: string;
     /** Optional task binding — creates a TaskArtifactLink alongside the primary scope link. */
@@ -106,7 +104,6 @@ export interface ArtifactUploadUrlInput {
     byteSize: number;
     format?: ArtifactFileFormat;
     visibility?: ArtifactVisibility;
-    chatId?: string;
     agreementId?: string;
     taskId?: string;
     serviceAgreementId?: string;
@@ -136,12 +133,18 @@ export type ArtifactFileView = Record<string, unknown> & {
     extractionError?: string | null;
     filename?: string | null;
 };
+/**
+ * Replaces `ContextReader`'s artifact reads + `ContextWriter`'s breadcrumb
+ * writes. `visibility: 'agent-private'` is the new home for agent thoughts —
+ * they persist, are searchable, but are not visible to other chat parties.
+ */
+/** Artifact scope is explicit selected work. */
 import type { ArtifactExternalRef, ArtifactFileFormat } from '@ziggs-ai/contracts';
 export { AGREEMENT_LANE_PREFIX } from '@ziggs-ai/contracts';
-export declare function artifactScopeForSession(sessionId: string): {
-    chatId: string;
-} | {
-    agreementId: string;
+export declare function artifactScope(target?: {
+    agreementId?: string;
+}): {
+    agreementId?: string;
 };
 export declare class ArtifactsClient {
     private readonly operatorKey;
@@ -158,7 +161,7 @@ export declare class ArtifactsClient {
      * This is not `list()` with a query string. `list()` answers "what is in this
      * container"; a person's cross-container view lives behind `reach` arms that
      * an agent has no business asking for. The server refuses `reach`,
-     * `authoredBy` and `chatId` here rather than ignoring them, so a narrowing
+     * `authoredBy` and `addressId` here rather than ignoring them, so a narrowing
      * filter can never be silently dropped — hence no options for them.
      *
      * The result always carries `coverage`. An empty `artifacts` is a statement
@@ -174,7 +177,7 @@ export declare class ArtifactsClient {
      * endpoint is updated to accept `visibility`, this falls back to logging
      * locally (operators can still wire their own sink).
      */
-    recordThought(sessionId: string, text: string, opts?: {
+    recordThought(text: string, opts?: {
         idempotencyKey?: string;
         serviceAgreementId?: string;
     }): Promise<void>;
@@ -190,19 +193,29 @@ export declare class ArtifactsClient {
         artifactId?: string;
     }>;
     /**
-     * attach an existing artifact to a chat, a task, or an agreement.
+     * attach an existing artifact to a task or agreement.
      *
-     * Attaching confers nothing on its own: it places the artifact inside the
-     * container, and that container's audience (chat members / task or agreement
-     * parties) can read it from then on. This is how a free-standing artifact
-     * reaches anyone without granting it to one specific agent.
+     * A chat link is a presentation reference, never an access grant. Task and
+     * agreement associations use their work authority and source-disclosure policy.
+     * Explicit artifact sharing grants access to the selected holder.
      */
-    attachToChat(artifactId: string, chatId: string): Promise<{
-        success: boolean;
-    }>;
     attachToTask(artifactId: string, taskId: string, role?: 'input' | 'output'): Promise<{
         success: boolean;
     }>;
+    /** Inspect the exact-output approvals without dropping the source execution. */
+    reviewContribution(artifactId: string, agreementId: string): Promise<{
+        artifactId: string;
+        target: import('@ziggs-ai/contracts').ContributionTarget;
+        ready: boolean;
+        releaseSources: import('@ziggs-ai/contracts').ContributionSource[];
+        privateSourceCount: number;
+    }>;
+    /** Delivers only this immutable artifact after all required consent is live. */
+    contribute(artifactId: string, agreementId: string): Promise<{
+        artifactId: string;
+        agreementId: string;
+        outcome: 'created' | 'existing';
+    }>;
     attachToAgreement(artifactId: string, agreementId: string): Promise<{
         success: boolean;
     }>;
@@ -232,6 +245,5 @@ export declare class ArtifactsClient {
      * binds it to a task. Both containers at once is still a mistake worth naming,
      * since only one of them would take effect.
      */
-    private _assertScopeXor;
     private _headers;
 }

package/dist/http/ArtifactsClient.js

@@ -1,7 +1,7 @@
 import { runtimeLog } from '../shared/runtimeLog.js';
 import { throwApiError } from '../shared/apiError.js';
 import { getBackendUrl } from '../utils/urlUtils.js';
-import { buildOperatorHeaders } from './operatorHeaders.js';
+import { buildOperatorHeaders, currentWorkExecution } from './operatorHeaders.js';
 /**
  * Inline `POST /artifacts` body cap (matches backend
  * `ARTIFACT_PUBLIC_TEXT_MAX_CHARS`). Over this → file rail or multi-part; the
@@ -26,28 +26,22 @@ function resolveUploadBytes(input) {
     }
     return null;
 }
-/**
- * Replaces `ContextReader`'s artifact reads + `ContextWriter`'s breadcrumb
- * writes. `visibility: 'agent-private'` is the new home for agent thoughts —
- * they persist, are searchable, but are not visible to other chat parties.
- */
-/**
- * turn a runtime lane id into a scope the backend can accept.
- *
- * A task with no origin chat runs on the lane `agrn-<agreementId>` (see
- * Agent.laneSessionIdForTask). That is a routing key, not a chat: no such
- * chat row exists, so passing it as `chatId` made every breadcrumb and recorded
- * thought on an agreement lane come back 403 "not authorized for this scope" —
- * a fictional scope reading like an auth failure. The work is agreement-scoped,
- * so say so; same rule settled for deliverables.
- */
-import { agreementIdFromLane } from '@ziggs-ai/contracts';
 export { AGREEMENT_LANE_PREFIX } from '@ziggs-ai/contracts';
-export function artifactScopeForSession(sessionId) {
-    const agreementId = agreementIdFromLane(sessionId);
-    if (agreementId)
-        return { agreementId };
-    return { chatId: sessionId };
+function rejectRoomScope(input) {
+    if ('addressId' in input)
+        throw new Error('addressId is retired; use explicit task/agreement work or an exact message artifact reference');
+}
+export function artifactScope(target = {}) {
+    rejectRoomScope(target);
+    const execution = currentWorkExecution();
+    if (execution?.agreementId)
+        return { agreementId: execution.agreementId };
+    if (execution)
+        return {};
+    if (target.agreementId)
+        return { agreementId: target.agreementId };
+    // An unattached artifact is private to its owner; a container is optional.
+    return {};
 }
 export class ArtifactsClient {
     operatorKey;
@@ -60,13 +54,12 @@ export class ArtifactsClient {
         this.agentId = agentId;
     }
     async list(q, opts = {}) {
-        const selectors = [q.chatId, q.agreementId, q.taskId, q.authoredBy].filter(Boolean);
+        rejectRoomScope(q);
+        const selectors = [q.agreementId, q.taskId, q.authoredBy].filter(Boolean);
         if (selectors.length !== 1) {
-            throw new Error('ArtifactsClient.list: pass exactly one of chatId, agreementId, taskId, or authoredBy');
+            throw new Error('ArtifactsClient.list: pass exactly one of agreementId, taskId, or authoredBy');
         }
         const url = new URL(`${getBackendUrl()}/artifacts`);
-        if (q.chatId)
-            url.searchParams.set('chatId', q.chatId);
         if (q.agreementId)
             url.searchParams.set('agreementId', q.agreementId);
         if (q.taskId)
@@ -93,7 +86,7 @@ export class ArtifactsClient {
      * This is not `list()` with a query string. `list()` answers "what is in this
      * container"; a person's cross-container view lives behind `reach` arms that
      * an agent has no business asking for. The server refuses `reach`,
-     * `authoredBy` and `chatId` here rather than ignoring them, so a narrowing
+     * `authoredBy` and `addressId` here rather than ignoring them, so a narrowing
      * filter can never be silently dropped — hence no options for them.
      *
      * The result always carries `coverage`. An empty `artifacts` is a statement
@@ -126,10 +119,9 @@ export class ArtifactsClient {
      * endpoint is updated to accept `visibility`, this falls back to logging
      * locally (operators can still wire their own sink).
      */
-    async recordThought(sessionId, text, opts = {}) {
-        // `sessionId` may be an agreement lane, which is not a chat.
+    async recordThought(text, opts = {}) {
         return this.write({
-            ...artifactScopeForSession(sessionId),
+            ...artifactScope({ agreementId: opts.serviceAgreementId }),
             text,
             contentType: 'thought',
             visibility: 'agent-private',
@@ -138,9 +130,9 @@ export class ArtifactsClient {
         });
     }
     async write(input) {
+        rejectRoomScope(input);
         if (!input.text || !input.text.trim())
             return;
-        this._assertScopeXor(input);
         try {
             await this.writeStrict(input);
         }
@@ -161,7 +153,7 @@ export class ArtifactsClient {
         if (!input.text || !input.text.trim()) {
             throw new Error('ArtifactsClient.writeStrict: text is required');
         }
-        this._assertScopeXor(input);
+        rejectRoomScope(input);
         const text = input.text.trim();
         // Refuse before the wire so MCP/SDK get a named escape hatch
         // instead of a bare class-validator string.
@@ -176,8 +168,7 @@ export class ArtifactsClient {
                 text,
                 ...(input.name?.trim() ? { name: input.name.trim() } : {}),
                 contentType: input.contentType ?? 'text',
-                visibility: input.visibility ?? 'chat',
-                chatId: input.chatId,
+                visibility: input.visibility ?? 'address',
                 agreementId: input.agreementId,
                 taskId: input.taskId,
                 serviceAgreementId: input.serviceAgreementId,
@@ -202,24 +193,31 @@ export class ArtifactsClient {
         }
     }
     /**
-     * attach an existing artifact to a chat, a task, or an agreement.
+     * attach an existing artifact to a task or agreement.
      *
-     * Attaching confers nothing on its own: it places the artifact inside the
-     * container, and that container's audience (chat members / task or agreement
-     * parties) can read it from then on. This is how a free-standing artifact
-     * reaches anyone without granting it to one specific agent.
+     * A chat link is a presentation reference, never an access grant. Task and
+     * agreement associations use their work authority and source-disclosure policy.
+     * Explicit artifact sharing grants access to the selected holder.
      */
-    async attachToChat(artifactId, chatId) {
-        return this._attach(`/chats/${encodeURIComponent(chatId)}/artifacts`, {
-            artifactId,
-        });
-    }
     async attachToTask(artifactId, taskId, role = 'output') {
         return this._attach(`/tasks/${encodeURIComponent(taskId)}/artifacts`, {
             artifactId,
             role,
         });
     }
+    /** Inspect the exact-output approvals without dropping the source execution. */
+    async reviewContribution(artifactId, agreementId) {
+        const url = new URL(`${getBackendUrl()}/artifacts/${encodeURIComponent(artifactId)}/contribution-review`);
+        url.searchParams.set('agreementId', agreementId);
+        const response = await fetch(url, { headers: this._headers() });
+        if (!response.ok)
+            throwApiError(response, await response.text(), 'reviewContribution failed');
+        return response.json();
+    }
+    /** Delivers only this immutable artifact after all required consent is live. */
+    async contribute(artifactId, agreementId) {
+        return this._post(`/agreements/${encodeURIComponent(agreementId)}/contributions`, { artifactId }, 'contributeArtifact');
+    }
     async attachToAgreement(artifactId, agreementId) {
         return this._attach(`/agreements/${encodeURIComponent(agreementId)}/artifacts`, { artifactId });
     }
@@ -229,6 +227,7 @@ export class ArtifactsClient {
      * S3 PUT here and returns a sha256 so complete can follow immediately.
      */
     async uploadUrl(input) {
+        rejectRoomScope(input);
         if (!input.filename?.trim()) {
             throw new Error('ArtifactsClient.uploadUrl: filename is required');
         }
@@ -238,11 +237,6 @@ export class ArtifactsClient {
         if (!Number.isInteger(input.byteSize) || input.byteSize < 1) {
             throw new Error('ArtifactsClient.uploadUrl: byteSize must be a positive integer');
         }
-        this._assertScopeXor({
-            text: '.',
-            chatId: input.chatId,
-            agreementId: input.agreementId,
-        });
         const bytes = resolveUploadBytes(input);
         if (bytes && bytes.byteLength !== input.byteSize) {
             throw new Error(`ArtifactsClient.uploadUrl: byteSize ${input.byteSize} does not match content length ${bytes.byteLength}`);
@@ -254,7 +248,6 @@ export class ArtifactsClient {
             byteSize: input.byteSize,
             format: input.format,
             visibility: input.visibility,
-            chatId: input.chatId,
             agreementId: input.agreementId,
             taskId: input.taskId,
             serviceAgreementId: input.serviceAgreementId,
@@ -343,18 +336,6 @@ export class ArtifactsClient {
      * binds it to a task. Both containers at once is still a mistake worth naming,
      * since only one of them would take effect.
      */
-    _assertScopeXor(input) {
-        if (input.chatId && input.agreementId) {
-            // the refusal names the recovery, because this is the one gate
-            // for every caller — the exposed tool surfaces inherit it rather than each
-            // wording their own. Wording matters: this fires at the last step of a
-            // finished task, where a bare "pick one" leaves the deliverable unfiled.
-            throw new Error('pass at most one of chatId or agreementId — a deliverable under an ' +
-                'agreement wants agreementId alone (its parties see it); use chatId ' +
-                'only for a chat-scoped note. To put it in both places, record it ' +
-                'with agreementId, then attach it to the chat.');
-        }
-    }
     _headers() {
         return buildOperatorHeaders(this.operatorKey, this.agentId, { 'content-type': 'application/json' });
     }

package/dist/http/ConnectionsClient.d.ts

@@ -38,11 +38,10 @@ export interface McpConnectionRequestParams {
      * per-user relay may send it as `onBehalfOfUserId` instead.
      */
     recipientId?: string;
-    /**
-     * Working chat the consent card is opened into. Required by the backend for
-     * the agent-tool path; the per-user gateway trigger omits it.
-     */
-    chatId?: string;
+    context: {
+        kind: 'message' | 'task' | 'agreement';
+        id: string;
+    };
     /**
      * Target the consent request at this end-user (X-On-Behalf-Of-User) instead
      * of the operator — the per-user MCP gateway's connect prompt.
@@ -112,10 +111,10 @@ export declare class ConnectionsClient {
     /**
      * agent-initiated MCP connection request: ask the principal to
      * connect a remote MCP server and grant this agent the listed tools. Opens a
-     * connection-consent agreement in the working chat; on approval the
+     * connection-consent agreement for explicit work/message context; on approval the
      * server is connected (if needed) and the agent is granted the tools.
      */
-    requestMcpConnection({ serverUrl, tools, reason, chatId, recipientId, onBehalfOfUserId, }: McpConnectionRequestParams): Promise<Record<string, unknown>>;
+    requestMcpConnection({ serverUrl, tools, reason, context, recipientId, onBehalfOfUserId, }: McpConnectionRequestParams): Promise<Record<string, unknown>>;
     private _requestRaw;
     private _request;
 }