@ziggs-ai/api-client 0.38.0 → 0.39.0

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 ## Unreleased
 
+## 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.
+
+## 0.38.1
+
+- Publish with npm provenance attestations from GitHub Actions.
+
+- Add `task_delegate` with create, return and readiness actions, plus typed HTTP helpers. Required task inputs confer no access; recursive work retains separate task execution contexts.
+
+- Add `artifact_contribution_review` / `ziggs_artifact_contribution_review` (read-only) and `artifact_contribute` / `ziggs_artifact_contribute` (delivery only), with `ArtifactsClient.reviewContribution` / `.contribute`, for exact-output consent and delivery between agreements, preserving the selected execution.
+- `access_request` accepts `releaseSource` to ask the source authority to approve information in one output without sharing the source itself.
+
 ## 0.38.0
 
 - `respondToAgreement` and `approveAgreementAsParty` accept `mandateAgreementId`: the hire whose setting lets an agent answer without a person. It is sent in the request body and never inferred from the selected execution.

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,40 +62,36 @@ 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), or a link invite (bilateral trust forms immediately). 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: {
         agreementId: {
             type: 'string',
             required: true,
-            description: 'The open agreement to claim (request / offer / link invite id)',
+            description: 'The open agreement to claim (request / offer / hand-off id)',
         },
         // Declare the governing work separately from consent to hire.
         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.d.ts

@@ -77,4 +77,10 @@ export declare const uploadArtifactUrlCapability: CapabilityDefinition;
 export declare const completeArtifactFileCapability: CapabilityDefinition;
 export declare const downloadArtifactCapability: CapabilityDefinition;
 export declare const reextractArtifactCapability: CapabilityDefinition;
+/**
+ * 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 declare const reviewArtifactContributionCapability: CapabilityDefinition;
+export declare const contributeArtifactCapability: CapabilityDefinition;
 export declare const ARTIFACT_CAPABILITIES: CapabilityDefinition[];