@ziggs-ai/api-client 0.10.4 → 0.12.0

package/dist/capabilities/agreementVerbs.d.ts

@@ -1,8 +1,15 @@
 import type { CapabilityDefinition } from './types.js';
-export declare const agreementCommissionCapability: CapabilityDefinition;
+export declare const agreementBuyCapability: CapabilityDefinition;
 export declare const agreementBidCapability: CapabilityDefinition;
 export declare const agreementBrokerCapability: CapabilityDefinition;
-export declare const agreementQuestCapability: CapabilityDefinition;
+export declare const agreementRequestCapability: CapabilityDefinition;
+/**
+ * No mandate param here, deliberately: a listing is formed inside no job. It is
+ * a standing invitation to the world that outlives whatever the agent happens
+ * to be doing today, and the publish path says so at its own end
+ * (`POST /marketplace/offers/publish`). Hanging one under a job would kill the
+ * listing when the job ended.
+ */
 export declare const agreementOfferCapability: CapabilityDefinition;
 export declare const agreementHandoffCapability: CapabilityDefinition;
 export declare const AGREEMENT_VERB_CAPABILITIES: CapabilityDefinition[];

package/dist/capabilities/agreementVerbs.js

@@ -30,7 +30,7 @@ const TERMS_PARAMS = {
     },
     price: {
         type: 'number',
-        description: 'Amount in CENTS — 500 means $5.00, and ϟ5.00 in the UI. Optional; recording a price does not itself move money. Convert BOTH ways or you are off by 100x: a human who says "ϟ2" means 200, and quoting 500 back as "ϟ500" is the same mistake inverted.',
+        description: 'Price in POINTS, as an integer of hundredths — 500 means ϟ5.00. Recording a price here does not itself move any. Convert BOTH ways or you are off by 100x: a human who says "ϟ2" means 200, and quoting 500 back as "ϟ500" is the same mistake inverted.',
     },
     billing: {
         type: 'string',
@@ -77,6 +77,28 @@ function termsFrom(args) {
 function engagementKindFrom(args) {
     return args['engagementKind'] ?? 'service';
 }
+/**
+ * The job an agent declares it is acting inside.
+ *
+ * The consent gate excuses a formation that sits inside a job a human already
+ * approved, and it verifies the claim against the acting agent. What did not
+ * exist was a way to MAKE the claim: `parentAgreementId` rode only on internal
+ * service calls, so every agreement an agent formed arrived at the gate as an
+ * outsider and waited on a human — including the ordinary case of buying the
+ * help the job it was hired for needs.
+ *
+ * Declared by the caller, never guessed by the server. The SDK fills it in from
+ * the task it is executing, so an agent doing assigned work pays nothing for it.
+ */
+const MANDATE_PARAM = {
+    type: 'string',
+    description: 'The active agreement whose work this is part of — the job you are doing. It becomes this engagement\'s parent, so it ends when the job ends, and it is what lets you commit without waiting on your human: work inside a job they already approved needs no second approval. Name only an agreement you are actually a party to; the server checks, and a wrong name simply earns nothing. Leave it out for work that belongs to no job.',
+};
+/** Pull the declared mandate off a validated arg bag, as the wire field. */
+function mandateFrom(args) {
+    const declared = args['mandateAgreementId'];
+    return typeof declared === 'string' && declared ? { parentAgreementId: declared } : {};
+}
 /** The audience a broadcast reaches. */
 const AUDIENCE_PARAM = {
     type: 'string',
@@ -101,25 +123,27 @@ function publishedNext(env) {
     ];
 }
 /* ─────────────────────────── direct, to one counterparty ─────────────────── */
-export const agreementCommissionCapability = {
-    key: 'agreement_commission',
-    names: { sdk: 'agreement_commission', mcp: 'ziggs_agreement_commission' },
-    title: 'Commission a counterparty',
+export const agreementBuyCapability = {
+    key: 'agreement_buy',
+    names: { sdk: 'agreement_buy', mcp: 'ziggs_agreement_buy' },
+    title: 'They work, you pay (named counterparty)',
     descriptions: {
-        sdk: 'Ask a named counterparty to do work your side pays for. They provide, you pay. For work you would do for them instead, use agreement_bid; to reach whoever is available rather than someone named, use agreement_quest.',
-        mcp: 'Ask a named counterparty to do work your side pays for: they provide, you pay. Prefer claiming their listing first if they have one (ziggs_marketplace_view then ziggs_agreement_claim) — listings are take-it-or-leave-it and most published agents refuse direct proposals. Use this for bespoke terms, renegotiation, or a counterparty with no listing. For work you would do for them, use ziggs_agreement_bid; to reach whoever is available, use ziggs_agreement_quest.',
+        sdk: 'Ask a named counterparty to do work your side pays for. They provide, you pay. For work you would do for them instead, use agreement_bid; to reach whoever is available rather than someone named, use agreement_request.',
+        mcp: 'Ask a named counterparty to do work your side pays for: they provide, you pay. Prefer claiming their listing first if they have one (ziggs_marketplace_view then ziggs_agreement_claim) — listings are take-it-or-leave-it and most published agents refuse direct proposals. Use this for bespoke terms, renegotiation, or a counterparty with no listing. For work you would do for them, use ziggs_agreement_bid; to reach whoever is available, use ziggs_agreement_request.',
     },
     annotation: 'write',
     params: {
         counterparty: COUNTERPARTY_PARAM,
         chatId: CHAT_PARAM,
         ...TERMS_PARAMS,
+        mandateAgreementId: MANDATE_PARAM,
     },
     needsAgentId: true,
     handler: async (args, env) => {
         const counterparty = args['counterparty'];
         const agreement = await proposeDirectTo({
             ...termsFrom(args),
+            ...mandateFrom(args),
             proposedTo: counterparty,
             chatId: args['chatId'],
             // They provide. The payer is derived server-side as the other side.
@@ -133,22 +157,24 @@ export const agreementCommissionCapability = {
 export const agreementBidCapability = {
     key: 'agreement_bid',
     names: { sdk: 'agreement_bid', mcp: 'ziggs_agreement_bid' },
-    title: 'Offer to work for a counterparty',
+    title: 'You work, they pay (named counterparty)',
     descriptions: {
         sdk: 'Offer to do work for a named counterparty, who pays. You provide. To publish the same offer to whoever wants it rather than one named party, use agreement_offer.',
-        mcp: 'Offer to do work for a named counterparty, who pays: you provide. This is the direct form of a listing — to publish the same offer to whoever wants it, use ziggs_agreement_offer instead. To ask someone else to do work you pay for, use ziggs_agreement_commission.',
+        mcp: 'Offer to do work for a named counterparty, who pays: you provide. This is the direct form of a listing — to publish the same offer to whoever wants it, use ziggs_agreement_offer instead. To ask someone else to do work you pay for, use ziggs_agreement_buy.',
     },
     annotation: 'write',
     params: {
         counterparty: COUNTERPARTY_PARAM,
         chatId: CHAT_PARAM,
         ...TERMS_PARAMS,
+        mandateAgreementId: MANDATE_PARAM,
     },
     needsAgentId: true,
     handler: async (args, env) => {
         const creds = fullCreds(env);
         const agreement = await proposeDirectTo({
             ...termsFrom(args),
+            ...mandateFrom(args),
             proposedTo: args['counterparty'],
             chatId: args['chatId'],
             // You provide, so the counterparty pays.
@@ -162,7 +188,7 @@ export const agreementBidCapability = {
 export const agreementBrokerCapability = {
     key: 'agreement_broker',
     names: { sdk: 'agreement_broker', mcp: 'ziggs_agreement_broker' },
-    title: 'Broker work between two other parties',
+    title: 'A third party does the work, you arrange it',
     descriptions: {
         sdk: 'Introduce a provider to a customer: the provider does the work, the counterparty pays, and neither side is you. The provider must already have a matching active offer.',
         mcp: 'Introduce a provider to a customer: the named provider does the work, the counterparty pays, and you are neither. The provider needs a matching active offer for this to stand. This is the one verb where naming a provider is the point — every other agreement verb infers it from the direction of work.',
@@ -180,11 +206,13 @@ export const agreementBrokerCapability = {
         },
         chatId: CHAT_PARAM,
         ...TERMS_PARAMS,
+        mandateAgreementId: MANDATE_PARAM,
     },
     needsAgentId: true,
     handler: async (args, env) => {
         const agreement = await proposeDirectTo({
             ...termsFrom(args),
+            ...mandateFrom(args),
             proposedTo: args['counterparty'],
             chatId: args['chatId'],
             providerId: args['provider'],
@@ -195,20 +223,25 @@ export const agreementBrokerCapability = {
     sdkOptions: { isAgreementCreation: true },
 };
 /* ──────────────────────────────── broadcast ──────────────────────────────── */
-export const agreementQuestCapability = {
-    key: 'agreement_quest',
-    names: { sdk: 'agreement_quest', mcp: 'ziggs_agreement_quest' },
-    title: 'Post a quest',
+export const agreementRequestCapability = {
+    key: 'agreement_request',
+    names: { sdk: 'agreement_request', mcp: 'ziggs_agreement_request' },
+    title: 'They work, you pay (open to anyone)',
     descriptions: {
         sdk: 'Post work you want done and will pay for, for whoever claims it. Whoever claims does the work. To offer work you would do instead, use agreement_offer.',
         mcp: 'Post work you want done and will pay for: whoever claims it does the work. Use this when nothing already listed fits, rather than proposing to named counterparties one at a time. To offer work you would do, use ziggs_agreement_offer. Claimable via ziggs_agreement_claim; visible in ziggs_marketplace_view.',
     },
     annotation: 'write',
-    params: { audience: AUDIENCE_PARAM, ...TERMS_PARAMS },
+    params: {
+        audience: AUDIENCE_PARAM,
+        ...TERMS_PARAMS,
+        mandateAgreementId: MANDATE_PARAM,
+    },
     needsAgentId: true,
     handler: async (args, env) => {
         const agreement = await proposeBroadcast({
             ...termsFrom(args),
+            ...mandateFrom(args),
             chatId: '',
             audience: args['audience'],
             engagementKind: engagementKindFrom(args),
@@ -217,13 +250,20 @@ export const agreementQuestCapability = {
     },
     sdkOptions: { isAgreementCreation: true },
 };
+/**
+ * No mandate param here, deliberately: a listing is formed inside no job. It is
+ * a standing invitation to the world that outlives whatever the agent happens
+ * to be doing today, and the publish path says so at its own end
+ * (`POST /marketplace/offers/publish`). Hanging one under a job would kill the
+ * listing when the job ended.
+ */
 export const agreementOfferCapability = {
     key: 'agreement_offer',
     names: { sdk: 'agreement_offer', mcp: 'ziggs_agreement_offer' },
-    title: 'Publish a standing offer',
+    title: 'You work, they pay (open to anyone)',
     descriptions: {
         sdk: 'Publish work you will do, for whoever claims it and pays. You provide. This is your listing: it stands until revoked or exhausted. To offer one named counterparty instead, use agreement_bid.',
-        mcp: 'Publish work you will do, for whoever claims it and pays: you provide. This is your listing — it stands until revoked or exhausted, and claimers take it as posted rather than countering it. To offer one named counterparty instead, use ziggs_agreement_bid. To ask for work rather than supply it, use ziggs_agreement_quest.',
+        mcp: 'Publish work you will do, for whoever claims it and pays: you provide. This is your listing — it stands until revoked or exhausted, and claimers take it as posted rather than countering it. To offer one named counterparty instead, use ziggs_agreement_bid. To ask for work rather than supply it, use ziggs_agreement_request.',
     },
     annotation: 'write',
     params: { audience: AUDIENCE_PARAM, ...TERMS_PARAMS },
@@ -248,7 +288,7 @@ export const agreementOfferCapability = {
 export const agreementHandoffCapability = {
     key: 'agreement_handoff',
     names: { sdk: 'agreement_handoff', mcp: 'ziggs_agreement_handoff' },
-    title: 'Hand off an agent you hired',
+    title: 'Pass a hire you hold to whoever claims it',
     descriptions: {
         sdk: 'Share an agent you have hired: the provider stays pinned, and whoever claims or approves becomes the customer the work is done for. Omit `to` to make it claimable by anyone. Handing off someone else\'s agent leaves that provider\'s approval pending — it must accept once before the hand-off can be claimed.',
         mcp: 'Share an agent you have hired: the provider stays pinned, and whoever claims or approves is the CUSTOMER the work is done for, never the worker. Omit `to` to publish it claimable; name `to` and that party approves directly. On a priced hand-off the claimer is also the payer; omit price (or 0) and nobody is billed for their tasks. Handing off someone else\'s agent leaves that provider\'s approval pending — it must accept once before the hand-off can be claimed. The provider is read from the parent hire, so you do not pass it.',
@@ -278,7 +318,7 @@ export const agreementHandoffCapability = {
         // would have had to look it up to pass it, and a lookup whose answer is
         // unique is not a decision worth handing to the caller.
         const parent = await getAgreement(parentAgreementId, creds);
-        const providerId = parent?.parties?.providerAgent;
+        const providerId = parent?.parties?.provider?.actor;
         if (!providerId) {
             throw new Error(`Cannot hand off ${parentAgreementId}: it names no provider, so there is no hire to share. Check the id with agreement_get.`);
         }
@@ -296,10 +336,10 @@ export const agreementHandoffCapability = {
     sdkOptions: { isAgreementCreation: true },
 };
 export const AGREEMENT_VERB_CAPABILITIES = [
-    agreementCommissionCapability,
+    agreementBuyCapability,
     agreementBidCapability,
     agreementBrokerCapability,
-    agreementQuestCapability,
+    agreementRequestCapability,
     agreementOfferCapability,
     agreementHandoffCapability,
 ];

package/dist/capabilities/agreements.d.ts

@@ -1,6 +1,6 @@
 import { type CapabilityDefinition } from './types.js';
 /**
- * the one claim verb. Quests, standing offers, and link invites
+ * the one claim verb. Requests, standing offers, and link invites
  * are all open broadcasts; claiming any of them is this call. The respond
  * tool no longer claims — it approves/rejects direct proposals only.
  */

package/dist/capabilities/agreements.js

@@ -2,7 +2,7 @@ import { claimOpenAgreement } from '../http/agreementFlows.js';
 import { linkIsReachOnly } from './links.js';
 import { fullCreds } from './types.js';
 /**
- * the one claim verb. Quests, standing offers, and link invites
+ * the one claim verb. Requests, standing offers, and link invites
  * are all open broadcasts; claiming any of them is this call. The respond
  * tool no longer claims — it approves/rejects direct proposals only.
  */
@@ -11,20 +11,32 @@ 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, activation is instant, no negotiation turns. Claims a quest (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 and the agreement activates. A hand-off is claimable only after its provider has accepted (409 until then). Find quests/offers with marketplace_view; listings are take-it-or-leave-it — never counter one. Direct proposals are approved with agreement_respond instead, not claimed.',
-        mcp: 'Claim an open broadcast agreement by id — the DEFAULT way to engage: terms are already posted, consent is the claim, activation is instant, no negotiation turns. Claims a quest (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 and the agreement activates. A hand-off is claimable only after its provider has accepted (409 until then). Find quests/offers with ziggs_marketplace_view; listings are take-it-or-leave-it — never counter one. Direct proposals are approved with ziggs_agreement_respond instead, not claimed. You cannot claim your own broadcast.',
+        sdk: 'Claim an open broadcast agreement by id — the DEFAULT way to engage: terms are already posted, consent is the claim, activation is instant, 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 and the agreement activates. 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.',
+        mcp: 'Claim an open broadcast agreement by id — the DEFAULT way to engage: terms are already posted, consent is the claim, activation is instant, 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 and the agreement activates. A hand-off is claimable only after its provider has accepted (409 until then). Find requests/offers with ziggs_marketplace_view; listings are take-it-or-leave-it — never counter one. Direct proposals are approved with ziggs_agreement_respond instead, not claimed. You cannot claim your own broadcast.',
     },
     annotation: 'write',
     params: {
         agreementId: {
             type: 'string',
             required: true,
-            description: 'The open agreement to claim (quest / offer / link invite id)',
+            description: 'The open agreement to claim (request / offer / link invite id)',
+        },
+        // The job this claim is part of. A claim is the DEFAULT way to engage, so
+        // without this the ordinary case — an agent claiming the help the job it is
+        // doing needs — waited on a human every time. It authorizes; it does not
+        // re-parent: the row belongs to whoever posted it, and a claimer cannot move
+        // somebody else's agreement into its own tree.
+        mandateAgreementId: {
+            type: 'string',
+            description: 'The active agreement whose work this claim is part of — the job you are doing. Claiming for a job your human already approved needs no second approval from them, but you have to name the job: the server checks you are a party to it, and a wrong name simply earns nothing. Leave it out when the claim belongs to no job.',
         },
     },
     needsAgentId: true,
     handler: async (args, env) => {
-        const { agreement, kind } = await claimOpenAgreement(args['agreementId'], fullCreds(env));
+        const declaredMandate = args['mandateAgreementId'];
+        const { agreement, kind } = await claimOpenAgreement(args['agreementId'], fullCreds(env), typeof declaredMandate === 'string' && declaredMandate
+            ? { mandateAgreementId: declaredMandate }
+            : {});
         if (kind === 'link') {
             return {
                 status: 'linked',
@@ -40,7 +52,7 @@ export const agreementClaimCapability = {
                 ? 'Standing offer claimed — the publisher provides, your side pays. Spawn work under it with the task-create tool.'
                 : kind === 'hand-off'
                     ? 'Hand-off claimed — the pinned agent works FOR you: you are the customer (and the payer when priced), never the worker. Spawn work under it with the task-create tool.'
-                    : 'Quest claimed — you provide the work. Read the terms, then post progress and set the task result under this agreement.',
+                    : 'Request claimed — you provide the work. Read the terms, then post progress and set the task result under this agreement.',
             agreement,
         };
     },

package/dist/capabilities/artifacts.d.ts

@@ -29,8 +29,10 @@ export declare const shareArtifactCapability: CapabilityDefinition;
  */
 export declare const attachArtifactCapability: CapabilityDefinition;
 /**
- * File deliverables (presign → PUT → complete). Text `artifact_record` stays
- * for text bodies; use this rail when the payload is a file on object storage.
+ * The escape hatch for bytes too big to travel inside a tool call
+ * (the remote MCP transport caps a request body at 1MB). The ordinary way to
+ * record a file is `artifact_record` with contentBase64, which runs this presign
+ * → PUT → complete sequence internally.
  */
 export declare const uploadArtifactUrlCapability: CapabilityDefinition;
 export declare const completeArtifactFileCapability: CapabilityDefinition;

package/dist/capabilities/artifacts.js

@@ -18,33 +18,153 @@ function reportingHint(env, contentType, taskId) {
     return `Reporting finished work? Record it with contentType=result bound to the task (taskId), then close the task with ${close} — chat messages are conversation only.`;
 }
 /** Inline body cap + escape hatch, shared by SDK/MCP descriptions. */
-const ARTIFACT_RECORD_INLINE_CAP = 'Inline text max 50000 characters. Over that: use ziggs_artifact_upload_url ' +
-    '(file rail), or record an index artifact plus part artifacts and list the ' +
-    'part ids in the index. The server does not auto-split.';
+const ARTIFACT_RECORD_INLINE_CAP = 'Inline text max 50000 characters. Over that: pass the body as a file ' +
+    '(filename + mime + contentBase64, handled in this one call), or record an ' +
+    'index artifact plus part artifacts and list the part ids in the index. ' +
+    'The server does not auto-split.';
+/**
+ * The file rail, as one call.
+ *
+ * Recording a file used to be three steps a caller had to perform in order:
+ * ask for a presigned URL, PUT the bytes to object storage, then report the
+ * sha256 back. That is our storage design surfaced as a caller obligation —
+ * one of those two tools spent 1,421 characters explaining it — and every
+ * agent paid for both schemas in every session whether or not it ever wrote a
+ * file. Hand `contentBase64` here and the presign, the PUT and the completion
+ * all happen inside this handler.
+ *
+ * `artifact_upload_url` / `artifact_complete_file` still exist for the one case
+ * that genuinely needs them: bytes too large to travel inside a tool call (the
+ * remote MCP transport caps a request body at 1MB). They are no longer the
+ * documented path.
+ */
+/**
+ * The file's bytes, or a refusal that says the payload arrived damaged.
+ *
+ * `Buffer.from(s, 'base64')` does not validate: it silently drops every
+ * character it does not recognise and stops at the first bad padding, so a
+ * truncated payload — the ordinary failure when a model inlines a long file —
+ * decodes to FEWER bytes and everything downstream agrees with itself. The
+ * sha256 is taken over what survived, the upload completes, and the caller is
+ * told the file stored. Nothing surfaces until someone reads a garbled extract
+ * with no way back to the call that wrote it.
+ *
+ * Re-encoding is the cheap question Node will not ask: if every character
+ * carried data, the bytes round-trip to the same string. Whitespace is stripped
+ * first (wrapping is normal in transports) and base64url is folded into
+ * standard base64, so only genuine corruption is refused.
+ */
+function decodeFileBytes(contentBase64) {
+    const normalized = contentBase64
+        .replace(/\s+/g, '')
+        .replace(/-/g, '+')
+        .replace(/_/g, '/')
+        .replace(/=+$/, '');
+    const bytes = Buffer.from(normalized, 'base64');
+    if (bytes.byteLength < 1) {
+        throw new Error('contentBase64 decoded to zero bytes — pass the base64 of the file, or use text for a text artifact.');
+    }
+    if (bytes.toString('base64').replace(/=+$/, '') !== normalized) {
+        throw new Error(`contentBase64 is not intact base64: ${normalized.length} characters decoded to ${bytes.byteLength} bytes and do not re-encode to what was sent, so part of the payload was dropped. ` +
+            'Send the whole encoding — storing it would give you a smaller, corrupt file whose checksum matches the corruption. ' +
+            'Bytes over ~1MB do not fit in a tool call at all: use artifact_upload_url for those.');
+    }
+    return bytes;
+}
+async function recordFileArtifact(args, env, visibility) {
+    const filename = args['filename']?.trim();
+    const mime = args['mime']?.trim();
+    if (!filename)
+        throw new Error('filename is required when passing contentBase64');
+    if (!mime)
+        throw new Error('mime is required when passing contentBase64');
+    const contentBase64 = args['contentBase64'];
+    // Decoded once, here, and handed on as bytes: `uploadUrl` takes `content`
+    // directly, so passing the string instead made every file call decode the
+    // same payload twice — and a stdio caller has no 1MB cap, so "the payload"
+    // can be tens of megabytes.
+    const bytes = decodeFileBytes(contentBase64);
+    const creds = fullCreds(env);
+    const client = new ArtifactsClient(creds.operatorKey, creds.agentId, creds.laneId);
+    const taskId = args['taskId'];
+    const byteSize = bytes.byteLength;
+    const uploaded = await client.uploadUrl({
+        filename,
+        mime,
+        // The byte length of what will be PUT, not of the base64 envelope — the
+        // presign signs this number and S3 rejects a mismatch.
+        byteSize,
+        format: args['format'],
+        visibility,
+        chatId: args['chatId'],
+        agreementId: args['agreementId'],
+        taskId,
+        idempotencyKey: args['idempotencyKey'],
+        // ArtifactsClient does the PUT and hands back the sha256 of what it sent,
+        // so the checksum is never something the caller has to compute.
+        content: bytes,
+    });
+    if (!uploaded.checksum) {
+        throw new Error(`Uploaded ${filename} but the storage layer returned no checksum, so the artifact is incomplete. ` +
+            `Finish it with artifact_complete_file (artifactId ${uploaded.artifactId}) once you have the sha256 of the bytes.`);
+    }
+    const artifact = await client.completeFile(uploaded.artifactId, uploaded.checksum);
+    return {
+        ok: true,
+        artifactId: uploaded.artifactId,
+        artifact,
+        visibility,
+        chatId: args['chatId'],
+        agreementId: args['agreementId'],
+        taskId,
+        byteSize,
+        note: 'File stored and completed. Text extraction runs asynchronously — when extractionStatus is ok, read the extracted text rather than downloading the bytes again.',
+        reportingHint: reportingHint(env, args['contentType'], taskId),
+    };
+}
 export const recordArtifactCapability = {
     key: 'artifact_record',
     names: { sdk: 'artifact_record', mcp: 'ziggs_artifact_record' },
     title: 'Record an artifact',
     descriptions: {
-        sdk: 'Write an artifact. Scope is optional: pass agreementId or chatId to record it there, ' +
+        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, ' +
             '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 — heavy results belong in artifacts, not chat messages. ' +
+            'taskId to bind it to the task. A heavy deliverable belongs in an artifact rather than pasted into a message. ' +
             ARTIFACT_RECORD_INLINE_CAP,
-        mcp: 'Write an artifact. Scope is optional — pass agreementId or chatId to record it into that ' +
+        mcp: 'Write an artifact — text (text) or a file (filename + mime + contentBase64; presign, upload ' +
+            'and completion all happen inside this one call, so there is no separate upload dance). ' +
+            'Scope is optional — pass agreementId or chatId to record it into that ' +
             'scope, pass taskId alone to bind a deliverable to its task, or pass no scope at all for a ' +
             'free-standing artifact that is yours until you attach or share it. Never guess a scope: ' +
             'recording with none always succeeds. Set visibility explicitly. ' +
             'For a finished deliverable, set contentType=result and pass taskId to bind it to the task. ' +
-            'Finished work is the task result — set it with ziggs_task_set_result; never report finished work as a chat message (chat is conversation only). ' +
+            'When the work rides a task, close it with ziggs_task_set_result too: that is what the next agent reads from its own inbox. ' +
             ARTIFACT_RECORD_INLINE_CAP,
     },
     annotation: 'write',
     params: {
         text: {
             type: 'string',
-            required: true,
-            description: 'Artifact body (max 50000 chars). Over limit: ziggs_artifact_upload_url or index+parts.',
+            description: 'Artifact body for a text artifact (max 50000 chars). Pass this or contentBase64, not both.',
+        },
+        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.',
+        },
+        filename: {
+            type: 'string',
+            description: 'Original filename — required with contentBase64',
+        },
+        mime: {
+            type: 'string',
+            description: 'Content-Type of the file bytes (e.g. application/pdf) — required with contentBase64',
+        },
+        format: {
+            type: 'string',
+            enum: ['pdf', 'docx', 'hwpx', 'md', 'txt', 'html'],
+            description: 'Optional file format; inferred from filename when omitted',
         },
         visibility: {
             type: 'string',
@@ -89,11 +209,24 @@ export const recordArtifactCapability = {
         if (visibility !== 'chat' && visibility !== 'agent-private') {
             throw new Error('visibility must be chat 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.
+        const text = args['text'];
+        const contentBase64 = args['contentBase64'];
+        if (text != null && contentBase64 != null) {
+            throw new Error('Pass text or contentBase64, not both');
+        }
+        if (contentBase64 != null) {
+            return recordFileArtifact(args, env, visibility);
+        }
+        if (text == null) {
+            throw new Error('Pass text for a text artifact, or contentBase64 (with filename and mime) for a file');
+        }
         const contentType = args['contentType'];
         const taskId = args['taskId'];
         const creds = fullCreds(env);
         const { artifactId } = await new ArtifactsClient(creds.operatorKey, creds.agentId, creds.laneId).writeStrict({
-            text: args['text'],
+            text,
             visibility,
             chatId,
             agreementId,
@@ -284,26 +417,27 @@ export const attachArtifactCapability = {
     },
 };
 /**
- * File deliverables (presign → PUT → complete). Text `artifact_record` stays
- * for text bodies; use this rail when the payload is a file on object storage.
+ * The escape hatch for bytes too big to travel inside a tool call
+ * (the remote MCP transport caps a request body at 1MB). The ordinary way to
+ * record a file is `artifact_record` with contentBase64, which runs this presign
+ * → PUT → complete sequence internally.
  */
 export const uploadArtifactUrlCapability = {
     key: 'artifact_upload_url',
     names: { sdk: 'artifact_upload_url', mcp: 'ziggs_artifact_upload_url' },
-    title: 'Start a file upload',
+    title: 'Start a large file upload',
     descriptions: {
-        sdk: 'Start a file artifact upload. Returns a short-lived uploadUrl. PUT the exact ' +
-            'byteSize bytes to that URL (Content-Type = mime), then call artifact_complete_file ' +
-            'with the sha256 hex of those bytes. Pass contentBase64 (or have the runtime supply ' +
-            'content) to have this tool PUT for you and return checksum. When extractionStatus ' +
-            'becomes ok, read extracted text via context_read / the extracted-text child — not ' +
-            'by stuffing file bytes into artifact_record.',
-        mcp: 'Start a file artifact upload (pdf/docx/hwpx/md/txt/html). Returns uploadUrl + artifactId. ' +
-            'PUT the file bytes to uploadUrl with the declared mime, then call ' +
-            'ziggs_artifact_complete_file with sha256 hex. Prefer contentBase64 so this tool PUTs ' +
-            'and returns checksum for you. Scope optional (chatId / agreementId / taskId) like ' +
-            'ziggs_artifact_record. Do not put large file bodies into ziggs_artifact_record. ' +
-            'After extract finishes (extractionStatus=ok), read text from context / the derived ' +
+        sdk: 'Large-file escape hatch. Ordinary files go through artifact_record (filename + mime + ' +
+            'contentBase64), which does all of this in one call — use this only when the bytes are too ' +
+            'large to travel inside a tool call. Returns a short-lived uploadUrl: PUT the exact byteSize ' +
+            'bytes to it (Content-Type = mime), then call artifact_complete_file with the sha256 hex of ' +
+            'those bytes.',
+        mcp: 'Large-file escape hatch (pdf/docx/hwpx/md/txt/html). Ordinary files go through ' +
+            'ziggs_artifact_record (filename + mime + contentBase64), which presigns, uploads and ' +
+            'completes in one call — use this only when the bytes are too large to travel inside a tool ' +
+            'call. Returns uploadUrl + artifactId: PUT the bytes with the declared mime, then call ' +
+            'ziggs_artifact_complete_file with sha256 hex. Scope optional (chatId / agreementId / ' +
+            'taskId). After extract finishes (extractionStatus=ok), read text from context / the derived ' +
             'extracted-text artifact.',
     },
     annotation: 'write',
@@ -387,15 +521,16 @@ export const uploadArtifactUrlCapability = {
 export const completeArtifactFileCapability = {
     key: 'artifact_complete_file',
     names: { sdk: 'artifact_complete_file', mcp: 'ziggs_artifact_complete_file' },
-    title: 'Finish a file upload',
+    title: 'Finish a large file upload',
     descriptions: {
-        sdk: 'Finish a file upload after the S3 PUT. Pass artifactId + sha256 hex of the bytes ' +
-            'you uploaded. Sets extractionStatus=pending and enqueues extract. Poll artifact_list ' +
-            'or context until extractionStatus is ok/failed; download still works while pending.',
-        mcp: 'Finish a file upload after the S3 PUT (or after ziggs_artifact_upload_url returned ' +
-            'checksum). Pass artifactId + sha256 hex. Enqueues text extract. When extractionStatus ' +
-            'is ok, read extracted text via ziggs_context_read / grants — file bytes stay on ' +
-            'ziggs_artifact_download.',
+        sdk: 'Second half of the large-file escape hatch — only needed after artifact_upload_url. ' +
+            'Pass artifactId + sha256 hex of the bytes you PUT. Sets extractionStatus=pending and ' +
+            'enqueues extract. Poll artifact_list or context until extractionStatus is ok/failed; ' +
+            'download still works while pending.',
+        mcp: 'Second half of the large-file escape hatch — only needed after ziggs_artifact_upload_url. ' +
+            'Pass artifactId + sha256 hex of the bytes you PUT. Enqueues text extract. When ' +
+            'extractionStatus is ok, read extracted text via ziggs_context_read / grants — file bytes ' +
+            'stay on ziggs_artifact_download.',
     },
     annotation: 'write',
     params: {

package/dist/capabilities/chat.d.ts

@@ -1,9 +1,8 @@
 import { type CapabilityDefinition } from './types.js';
 /**
  * the decided chat surface for agents: chat_open only.
- * There is deliberately NO chat-listing tool on the SDK: agents read context
- * only via held grants and chat membership auto-mints a chat grant,
- * so "what chats can I see" is already answered by grant_list
+ * There is deliberately NO chat-listing tool on the SDK: taking part in a room
+ * IS a grant on it, so "what chats can I see" is already answered by grant_list
  * scopeKind=chat. MCP keeps its rich session-UX lister
  * (ziggs_chat_list) for humans in Cursor/Claude.
  */

package/dist/capabilities/chat.js

@@ -2,9 +2,8 @@ import { openConversation } from '../http/ChatClient.js';
 import { fullCreds } from './types.js';
 /**
  * the decided chat surface for agents: chat_open only.
- * There is deliberately NO chat-listing tool on the SDK: agents read context
- * only via held grants and chat membership auto-mints a chat grant,
- * so "what chats can I see" is already answered by grant_list
+ * There is deliberately NO chat-listing tool on the SDK: taking part in a room
+ * IS a grant on it, so "what chats can I see" is already answered by grant_list
  * scopeKind=chat. MCP keeps its rich session-UX lister
  * (ziggs_chat_list) for humans in Cursor/Claude.
  */
@@ -13,8 +12,8 @@ export const openConversationCapability = {
     names: { sdk: 'chat_open', mcp: 'ziggs_chat_open' },
     title: 'Open a chat',
     descriptions: {
-        sdk: 'Open or reuse a chat with a user or agent participant. Calling it again for the same participant returns the SAME chat, so it is how you find the conversation you already have with someone — pass newChat only when this really is a separate subject. To reach an agent in ANOTHER org, establish a link first — link_propose (if you have its agent id) or link_create_invite (if you do not), approved/claimed — otherwise this fails with AGENT_NOT_PUBLISHED. To list chats you can already read, use grant_list scopeKind=chat.',
-        mcp: 'Open or reuse a chat with a user or agent participant. Calling it again for the same participant returns the SAME chat; pass newChat only when this really is a separate subject. To reach an agent in ANOTHER org, an unpublished agent must establish a link first — ziggs_link_propose (if you have its agent id) or ziggs_link_create_invite (if you do not), approved/claimed — otherwise this fails with AGENT_NOT_PUBLISHED.',
+        sdk: 'Open or reuse a chat with a user or agent participant. Calling it again for the same participant returns the SAME chat, so it is how you find the conversation you already have with someone — pass newChat only when this really is a separate subject. This is also how you reach the HUMAN who hired you when the work needs an answer only they have: pass their user id (context_snapshot lists it under users; on your agreement they are the payer/creator party), then chat_send in the chat it returns with no receiverId. Opening a room is issuing the other side access to it, so it needs something that authorizes that: they publish a listing, you share an org, you hold a live agreement with them (a link counts, so link_propose is how you get one with a peer in another org), or they claimed your invite. With none of those the call is refused and the refusal names the levers. To list chats you can already read, use grant_list scopeKind=chat.',
+        mcp: 'Open or reuse a chat with a user or agent participant. Calling it again for the same participant returns the SAME chat; pass newChat only when this really is a separate subject. Opening a room is issuing the other side access to it, so it needs something that authorizes that: they publish a listing, you share an org, you hold a live agreement with them (a link counts, so ziggs_link_propose is how you get one with a peer in another org), or they claimed your invite. With none of those the call is refused and names the levers.',
     },
     annotation: 'write',
     params: {
@@ -38,7 +37,7 @@ export const openConversationCapability = {
             throw new Error('participantId is required');
         const { chatId, reused } = await openConversation(args['participantId'], fullCreds(env), { newChat: args['newChat'] === true });
         const lister = env.surface === 'mcp' ? 'ziggs_grant_list' : 'grant_list';
-        const grantNote = `Your membership auto-mints a chat grant, so the chat also appears in ${lister} scopeKind=chat for context reads.`;
+        const grantNote = `Opening the room issued you a grant on it, so the chat also appears in ${lister} scopeKind=chat for context reads.`;
         // word the note from the outcome instead of covering both cases.
         // "Open (or reused)" told the agent the distinction existed and then
         // withheld it — worse than silence, because the agent cannot even tell