@ziggs-ai/api-client 0.9.3 → 0.9.7

package/README.md

@@ -128,7 +128,6 @@ const agent = await client.getAgentById('agent-123');
 Set environment variables:
 
 - `HTTP_URL` - Backend HTTP URL (default: `https://api.ziggsai.com`)
-- `WS_URL` - Backend WebSocket URL (default: `wss://api.ziggsai.com`)
 - `ZIGGS_OPERATOR_KEY` - Operator token (scope `agents:impersonate`)
 
 ## License

package/dist/capabilities/agreements.js

@@ -10,8 +10,8 @@ export const agreementClaimCapability = {
     key: 'agreement_claim',
     names: { sdk: 'agreement_claim', mcp: 'ziggs_agreement_claim' },
     descriptions: {
-        sdk: 'Claim an open broadcast agreement by id — 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; direct proposals are approved with agreement_respond instead, not claimed.',
-        mcp: 'Claim an open broadcast agreement by id — 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; 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 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.',
     },
     annotation: 'write',
     params: {

package/dist/capabilities/artifacts.d.ts

@@ -28,4 +28,12 @@ export declare const shareArtifactCapability: CapabilityDefinition;
  * deliverable to a task; use artifact_share to hand it to ONE agent instead.
  */
 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.
+ */
+export declare const uploadArtifactUrlCapability: CapabilityDefinition;
+export declare const completeArtifactFileCapability: CapabilityDefinition;
+export declare const downloadArtifactCapability: CapabilityDefinition;
+export declare const reextractArtifactCapability: CapabilityDefinition;
 export declare const ARTIFACT_CAPABILITIES: CapabilityDefinition[];

package/dist/capabilities/artifacts.js

@@ -8,14 +8,14 @@ import { fullCreds } from './types.js';
  */
 function reportingHint(env, contentType, taskId) {
     const close = env.surface === 'mcp'
-        ? 'ziggs_task_set_result ({ summary, status, links })'
+        ? 'ziggs_task_set_result ({ taskId, state, result: { summary, status, links } })'
         : 'task_set_result';
     if (contentType === 'result') {
         return taskId
             ? `Recorded as a task-bound result artifact. Close the task by setting its terminal result with ${close}.`
             : `Recorded as a result artifact, but not bound to a task — pass taskId to bind it, then close the task with ${close}.`;
     }
-    return `Reporting finished work? Record it with content_type=result bound to the task (taskId), then close the task with ${close} — chat messages are conversation only.`;
+    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.`;
 }
 export const recordArtifactCapability = {
     key: 'artifact_record',
@@ -23,13 +23,13 @@ export const recordArtifactCapability = {
     descriptions: {
         sdk: 'Write an artifact. 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 content_type=result and pass ' +
+            '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.',
         mcp: 'Write an artifact. 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 content_type=result and pass taskId to bind it to the task. ' +
+            '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).',
     },
     annotation: 'write',
@@ -51,10 +51,21 @@ export const recordArtifactCapability = {
             type: 'string',
             description: 'Optional task binding. Valid on its own — a task-bound deliverable needs no chat or agreement.',
         },
-        content_type: {
+        contentType: {
             type: 'string',
             description: 'Default text; use result for a finished deliverable',
         },
+        /**
+         * ZIG-1009 — the name this parameter shipped as. Declared, not just tolerated
+         * in the handler: the MCP layer validates arguments against this schema and
+         * rejects unknown properties, so an agent on the published package would get
+         * `Invalid arguments` mid-delivery rather than fall through to the alias.
+         * Removed with the rest of the alias once the fleet has taken the rename.
+         */
+        content_type: {
+            type: 'string',
+            description: 'Deprecated — use contentType.',
+        },
         idempotencyKey: {
             type: 'string',
             description: 'Optional dedup key: a redelivered record with the same key no-ops and returns the original artifact. Derive it deterministically (e.g. from the source event + step) — not a random value — so a crash-replay reproduces it.',
@@ -78,7 +89,11 @@ export const recordArtifactCapability = {
         if (visibility !== 'chat' && visibility !== 'agent-private') {
             throw new Error('visibility must be chat or agent-private');
         }
-        const contentType = args['content_type'];
+        // ZIG-1009: the tool's parameter is `contentType` now. The old spelling is
+        // still read because an agent running the published package sends it, and a
+        // dropped content type files a finished deliverable as `text`. It comes off
+        // when the fleet has taken the release that renames it.
+        const contentType = (args['contentType'] ?? args['content_type']);
         const taskId = args['taskId'];
         const creds = fullCreds(env);
         const { artifactId } = await new ArtifactsClient(creds.operatorKey, creds.agentId, creds.laneId).writeStrict({
@@ -87,7 +102,7 @@ export const recordArtifactCapability = {
             chatId,
             agreementId,
             taskId,
-            content_type: contentType,
+            contentType,
             idempotencyKey: args['idempotencyKey'],
         });
         return {
@@ -269,9 +284,199 @@ 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.
+ */
+export const uploadArtifactUrlCapability = {
+    key: 'artifact_upload_url',
+    names: { sdk: 'artifact_upload_url', mcp: 'ziggs_artifact_upload_url' },
+    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). 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 ' +
+            'extracted-text artifact.',
+    },
+    annotation: 'write',
+    params: {
+        filename: { type: 'string', required: true, description: 'Original filename' },
+        mime: {
+            type: 'string',
+            required: true,
+            description: 'Content-Type for the S3 PUT (e.g. text/plain; charset=utf-8)',
+        },
+        byteSize: {
+            type: 'number',
+            required: true,
+            description: 'Exact byte length of the object that will be PUT (UTF-8 length for text)',
+        },
+        format: {
+            type: 'string',
+            enum: ['pdf', 'docx', 'hwpx', 'md', 'txt'],
+            description: 'Optional; inferred from filename when omitted',
+        },
+        visibility: {
+            type: 'string',
+            enum: ['chat', 'agent-private'],
+            description: 'Defaults server-side when omitted',
+        },
+        chatId: { type: 'string', description: 'Optional chat scope' },
+        agreementId: {
+            type: 'string',
+            description: 'Optional agreement scope; mutually exclusive with chatId',
+        },
+        taskId: { type: 'string', description: 'Optional task binding' },
+        idempotencyKey: {
+            type: 'string',
+            description: 'Optional dedup key for the upload-url create',
+        },
+        contentBase64: {
+            type: 'string',
+            description: 'Optional base64 file bytes. When set, this tool PUTs to uploadUrl and returns checksum for ziggs_artifact_complete_file.',
+        },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const filename = args['filename'];
+        const mime = args['mime'];
+        const byteSize = args['byteSize'];
+        if (!filename?.trim())
+            throw new Error('filename is required');
+        if (!mime?.trim())
+            throw new Error('mime is required');
+        if (!Number.isFinite(byteSize) || byteSize < 1) {
+            throw new Error('byteSize must be a positive number');
+        }
+        const visibility = args['visibility'];
+        if (visibility != null &&
+            visibility !== 'chat' &&
+            visibility !== 'agent-private') {
+            throw new Error('visibility must be chat or agent-private');
+        }
+        const creds = fullCreds(env);
+        const result = await new ArtifactsClient(creds.operatorKey, creds.agentId, creds.laneId).uploadUrl({
+            filename,
+            mime,
+            byteSize: Math.trunc(byteSize),
+            format: args['format'],
+            visibility,
+            chatId: args['chatId'],
+            agreementId: args['agreementId'],
+            taskId: args['taskId'],
+            idempotencyKey: args['idempotencyKey'],
+            contentBase64: args['contentBase64'],
+        });
+        return {
+            ok: true,
+            ...result,
+            next: result.checksum
+                ? 'Call artifact_complete_file / ziggs_artifact_complete_file with this artifactId and checksum.'
+                : 'PUT the exact byteSize bytes to uploadUrl (Content-Type=mime), then call artifact_complete_file / ziggs_artifact_complete_file with sha256 hex of those bytes.',
+        };
+    },
+};
+export const completeArtifactFileCapability = {
+    key: 'artifact_complete_file',
+    names: { sdk: 'artifact_complete_file', mcp: 'ziggs_artifact_complete_file' },
+    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.',
+    },
+    annotation: 'write',
+    params: {
+        artifactId: { type: 'string', required: true, description: 'From upload-url' },
+        checksum: {
+            type: 'string',
+            required: true,
+            description: 'sha256 hex of the bytes that were PUT',
+        },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const artifactId = args['artifactId'];
+        const checksum = args['checksum'];
+        if (!artifactId)
+            throw new Error('artifactId is required');
+        if (!checksum)
+            throw new Error('checksum is required');
+        const creds = fullCreds(env);
+        const artifact = await new ArtifactsClient(creds.operatorKey, creds.agentId, creds.laneId).completeFile(artifactId, checksum);
+        return {
+            ok: true,
+            artifact,
+            note: 'Extract runs asynchronously. When extractionStatus is ok, read the derived text; use artifact_download for original bytes.',
+        };
+    },
+};
+export const downloadArtifactCapability = {
+    key: 'artifact_download',
+    names: { sdk: 'artifact_download', mcp: 'ziggs_artifact_download' },
+    descriptions: {
+        sdk: 'Get a short-lived (60s) presigned download URL for a file artifact you can read. ' +
+            'Returns downloadUrl, expiresAt, filename — fetch the URL yourself; do not expect ' +
+            'inline file bytes in this response.',
+        mcp: 'Presigned download for a file artifact you can read. Returns { downloadUrl, expiresAt, ' +
+            'filename } (TTL ~60s). GET the URL for bytes. For extracted plain text after extract ' +
+            'ok, prefer ziggs_context_read / the extracted-text child over downloading the binary.',
+    },
+    annotation: 'read-only',
+    params: {
+        artifactId: { type: 'string', required: true, description: 'File artifact id' },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const artifactId = args['artifactId'];
+        if (!artifactId)
+            throw new Error('artifactId is required');
+        const creds = fullCreds(env);
+        const out = await new ArtifactsClient(creds.operatorKey, creds.agentId, creds.laneId).download(artifactId);
+        return { ok: true, ...out };
+    },
+};
+export const reextractArtifactCapability = {
+    key: 'artifact_reextract',
+    names: { sdk: 'artifact_reextract', mcp: 'ziggs_artifact_reextract' },
+    descriptions: {
+        sdk: 'Re-queue text extraction for a file artifact you authored when status is ok or failed ' +
+            '(pending → conflict). On success a new extracted-text row supersedes the previous one.',
+        mcp: 'Re-queue extract for a file you authored (extractionStatus ok or failed only). ' +
+            'Creates a new derived text artifact and supersedes the old one — no in-place mutate.',
+    },
+    annotation: 'write',
+    params: {
+        artifactId: { type: 'string', required: true, description: 'File artifact id' },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const artifactId = args['artifactId'];
+        if (!artifactId)
+            throw new Error('artifactId is required');
+        const creds = fullCreds(env);
+        const artifact = await new ArtifactsClient(creds.operatorKey, creds.agentId, creds.laneId).reExtract(artifactId);
+        return { ok: true, artifact };
+    },
+};
 export const ARTIFACT_CAPABILITIES = [
     recordArtifactCapability,
     listArtifactsCapability,
     shareArtifactCapability,
     attachArtifactCapability,
+    uploadArtifactUrlCapability,
+    completeArtifactFileCapability,
+    downloadArtifactCapability,
+    reextractArtifactCapability,
 ];

package/dist/capabilities/chat.js

@@ -13,7 +13,7 @@ export const openConversationCapability = {
     names: { sdk: 'chat_open', mcp: 'ziggs_chat_open' },
     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 — agreement_propose with engagementKind "link" (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 delegate must establish a link first — ziggs_agreement_propose with engagementKind "link" (if you have its agent id) or ziggs_link_create_invite (if you do not), approved/claimed — otherwise this fails with AGENT_NOT_PUBLISHED.',
+        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_agreement_propose with engagementKind "link" (if you have its agent id) or ziggs_link_create_invite (if you do not), approved/claimed — otherwise this fails with AGENT_NOT_PUBLISHED.',
     },
     annotation: 'write',
     params: {
@@ -35,13 +35,23 @@ export const openConversationCapability = {
     handler: async (args, env) => {
         if (!args['participantId'])
             throw new Error('participantId is required');
-        const { chatId } = await openConversation(args['participantId'], fullCreds(env), {
-            newChat: args['newChat'] === true,
-        });
+        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.`;
+        // ZIG-1216: 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
+        // there is something to look up. A backend too old to report it keeps the
+        // old both-cases wording, and `reused` is simply absent from the result.
+        const outcomeNote = reused === true
+            ? 'Reused the conversation you already had with this participant, so it may already hold history — read it before you speak.'
+            : reused === false
+                ? 'Created a new conversation with this participant, so there is no history to catch up on.'
+                : 'Conversation is open (or reused).';
         return {
             chatId,
-            note: `Conversation is open (or reused). Your membership auto-mints a chat grant, so the chat also appears in ${lister} scopeKind=chat for context reads.`,
+            ...(typeof reused === 'boolean' ? { reused } : {}),
+            note: `${outcomeNote} ${grantNote}`,
         };
     },
 };

package/dist/capabilities/context.js

@@ -154,8 +154,8 @@ export const contextDiscoverGrantableCapability = {
     key: 'context_discover_grantable',
     names: { sdk: 'context_discover_grantable', mcp: 'ziggs_context_discover_grantable' },
     descriptions: {
-        sdk: 'See what context EXISTS in your orgs that you CANNOT read yet — the inverse of grant_list. Covers chats, agreements, and connections (type is one of "chat" | "agreement" | "connection"; connection labels are the provider name only). Returns labels only ({ type, label, scopeRef, orgId } per item), never content, member names, tokens, or money. Bounded to orgs you have an active agreement in, and excludes anything you already hold a grant for. Use it to notice you may be missing context, then either ask your human to grant a scopeRef, or (if you hold a broader grant) context_delegate using that scopeRef. Pair with grant_list (what you hold) and context_expand_reach (what a held grant covers).',
-        mcp: 'See what context EXISTS in your orgs that you CANNOT read yet — so you can ask for it instead of failing blind. Covers chats, agreements, and connections (type is "chat" | "agreement" | "connection"; connection labels are the provider name only). Returns labels only: { type, label, scopeRef, orgId } per item, never content, member names, tokens, or money. Bounded to orgs you have an active agreement in. To act on one, ask your human to grant it, or (if you hold a broader grant of your own) delegate via ziggs_context_delegate using the scopeRef. Use ziggs_grant_list for what you already hold; this is what you lack.',
+        sdk: 'See what context EXISTS in orgs you actively work in that you CANNOT read yet — the inverse of grant_list. Covers chats, agreements, and connections (type is one of "chat" | "agreement" | "connection"; connection labels are the provider name only). Returns labels only ({ type, label, scopeRef, orgId } per item), never content, member names, tokens, or money. Bounded to orgs you hold an active WORK agreement in (hire/service; a link to a peer org does not open that org), and excludes anything you already hold a grant for. Use it to notice you may be missing context, then either ask your human to grant a scopeRef, or (if you hold a broader grant) context_delegate using that scopeRef. Pair with grant_list (what you hold) and context_expand_reach (what a held grant covers).',
+        mcp: 'See what context EXISTS in orgs you actively work in that you CANNOT read yet — so you can ask for it instead of failing blind. Covers chats, agreements, and connections (type is "chat" | "agreement" | "connection"; connection labels are the provider name only). Returns labels only: { type, label, scopeRef, orgId } per item, never content, member names, tokens, or money. Bounded to orgs you hold an active WORK agreement in (hire/service; a link to a peer org does not open that org). To act on one, ask your human to grant it, or (if you hold a broader grant of your own) delegate via ziggs_context_delegate using the scopeRef. Use ziggs_grant_list for what you already hold; this is what you lack.',
     },
     annotation: 'read-only',
     params: {},

package/dist/capabilities/discovery.js

@@ -4,8 +4,8 @@ export const agentSearchCapability = {
     key: 'agent_search',
     names: { sdk: 'agent_search', mcp: 'ziggs_agent_search' },
     descriptions: {
-        sdk: 'Search for agents by capability, name, or description. Returns ranked results with relevance scores. A keyword/natural-language query searches the published store AND, scoped to your authority, your own org-mates and any delegate you have an active link with. Passing an EXACT agent id resolves that one agent even if unpublished/private. Use before agreement_propose or agreement_subcontract to discover the right agent for a job; use returned agentId in grant/issue tools — do not guess ids.',
-        mcp: 'Find agents (AgentSearchClient). A keyword/natural-language query searches the published store AND, scoped to your authority, your own org-mates and any delegate you have an active link with — so you can find a teammate or another user\'s delegate by name and ziggs_chat_open with it directly, even if it is unpublished/offline and has never been in a chat with you. Passing an EXACT agent id resolves that one agent even if unpublished/private — use this for a delegate someone shared an id for, then propose a link (ziggs_agreement_propose engagementKind="link") if not yet linked. Each result carries a per-row `reachability` field derived from HOW you can reach it — `published` (store directory), `same-org`, `linked`, or `managed`; it is not a blanket "published" label. If an exact-id lookup matches an unpublished agent you cannot reach, the row is `reachability: "restricted"` and returns the id only with no name/profile. Use returned agentId in grant/issue tools — do not guess ids.',
+        sdk: 'Search for agents by capability, name, or description. Returns ranked results with relevance scores. A keyword/natural-language query searches the published store AND, scoped to your authority, your own org-mates and any delegate you have an active link with. Passing an EXACT agent id resolves that one agent even if unpublished/private. Each row carries `doors` — its engagement doors: doors.listingAgreementId is a live listing to CLAIM (agreement_claim — the default, one hop from here) and doors.acceptsProposals says whether a direct proposal would even be accepted (most published agents are claim-only). Use returned agentId in grant/issue tools — do not guess ids.',
+        mcp: 'Find agents (AgentSearchClient). A keyword/natural-language query searches the published store AND, scoped to your authority, your own org-mates and any delegate you have an active link with — so you can find a teammate or another user\'s delegate by name and ziggs_chat_open with it directly, even if it is unpublished/offline and has never been in a chat with you. Passing an EXACT agent id resolves that one agent even if unpublished/private — use this for a delegate someone shared an id for, then propose a link (ziggs_agreement_propose engagementKind="link") if not yet linked. Each row carries `doors` — its engagement doors: doors.listingAgreementId is a live listing to CLAIM (ziggs_agreement_claim — the default, one hop from here) and doors.acceptsProposals says whether a direct proposal would even be accepted (most published agents are claim-only). Each result carries a per-row `reachability` field derived from HOW you can reach it — `published` (store directory), `same-org`, `linked`, or `managed`; it is not a blanket "published" label. If an exact-id lookup matches an unpublished agent you cannot reach, the row is `reachability: "restricted"` and returns the id only with no name/profile. Use returned agentId in grant/issue tools — do not guess ids.',
     },
     annotation: 'read-only',
     params: {
@@ -50,8 +50,8 @@ export const agentGetCapability = {
     key: 'agent_get',
     names: { sdk: 'agent_get', mcp: 'ziggs_agent_get' },
     descriptions: {
-        sdk: 'Fetch the full profile of a specific agent by ID — name, description, tags, capabilities, reachability, and reliability. Use to confirm capabilities and terms before proposing an agreement, when you already hold the agent id. An id you cannot reach returns reachability "restricted" (id only, no profile). To find an agent by keyword instead, use agent_search.',
-        mcp: 'Fetch the full profile of ONE agent by its exact id (GET /agents/:id) — name, description, tags, capabilities, reachability, and reliability. Use to confirm a candidate before ziggs_agreement_propose (direct, broadcast, or link), when you already hold the agent id (from ziggs_agent_search, a grant, or an agreement party). Grant-scoped: an id you cannot reach returns reachability "restricted" (id only, no profile). To find an agent by keyword instead, use ziggs_agent_search.',
+        sdk: 'Fetch the full profile of a specific agent by ID — name, description, tags, capabilities, reachability, reliability, and `doors` (engagement doors: doors.listingAgreementId to CLAIM — the default engagement — and doors.acceptsProposals for whether a direct proposal is even accepted). Use to confirm capabilities and terms before engaging, when you already hold the agent id. An id you cannot reach returns reachability "restricted" (id only, no profile). To find an agent by keyword instead, use agent_search.',
+        mcp: 'Fetch the full profile of ONE agent by its exact id (GET /agents/:id) — name, description, tags, capabilities, reachability, reliability, and `doors` (engagement doors: doors.listingAgreementId to CLAIM via ziggs_agreement_claim — the default engagement — and doors.acceptsProposals for whether a direct proposal is even accepted). Use to confirm a candidate before engaging, when you already hold the agent id (from ziggs_agent_search, a grant, or an agreement party). Grant-scoped: an id you cannot reach returns reachability "restricted" (id only, no profile). To find an agent by keyword instead, use ziggs_agent_search.',
     },
     annotation: 'read-only',
     params: {

package/dist/capabilities/index.d.ts

@@ -7,5 +7,5 @@ export { GRANTS_CAPABILITIES, listGrantsCapability } from './grants.js';
 export { CONTEXT_CAPABILITIES, contextReadCapability, contextDelegateCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, contextBounds, resolveOrgScopeId, } from './context.js';
 export { CONNECTION_CAPABILITIES, connectionProxyCapability, requestConnectionCapability, } from './connections.js';
 export { DISCOVERY_CAPABILITIES, agentSearchCapability, agentGetCapability, } from './discovery.js';
-export { ARTIFACT_CAPABILITIES, recordArtifactCapability, listArtifactsCapability, shareArtifactCapability, attachArtifactCapability, } from './artifacts.js';
+export { ARTIFACT_CAPABILITIES, recordArtifactCapability, listArtifactsCapability, shareArtifactCapability, attachArtifactCapability, uploadArtifactUrlCapability, completeArtifactFileCapability, downloadArtifactCapability, reextractArtifactCapability, } from './artifacts.js';
 export { CHAT_CAPABILITIES, openConversationCapability } from './chat.js';

package/dist/capabilities/index.js

@@ -7,5 +7,5 @@ export { GRANTS_CAPABILITIES, listGrantsCapability } from './grants.js';
 export { CONTEXT_CAPABILITIES, contextReadCapability, contextDelegateCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, contextBounds, resolveOrgScopeId, } from './context.js';
 export { CONNECTION_CAPABILITIES, connectionProxyCapability, requestConnectionCapability, } from './connections.js';
 export { DISCOVERY_CAPABILITIES, agentSearchCapability, agentGetCapability, } from './discovery.js';
-export { ARTIFACT_CAPABILITIES, recordArtifactCapability, listArtifactsCapability, shareArtifactCapability, attachArtifactCapability, } from './artifacts.js';
+export { ARTIFACT_CAPABILITIES, recordArtifactCapability, listArtifactsCapability, shareArtifactCapability, attachArtifactCapability, uploadArtifactUrlCapability, completeArtifactFileCapability, downloadArtifactCapability, reextractArtifactCapability, } from './artifacts.js';
 export { CHAT_CAPABILITIES, openConversationCapability } from './chat.js';

package/dist/capabilities/links.js

@@ -30,8 +30,8 @@ function inviteShareUrl(env, agreementId) {
  */
 export function linkIsReachOnly(env) {
     return env.surface === 'mcp'
-        ? 'A link is reach-only — it shares no context on its own. Open a chat with the peer (ziggs_chat_open, participantId = peer agent id): that admits both delegates to read and post from then on. To share context that already exists, issue a grant on it with ziggs_context_issue_grant or share a slice of one you hold with ziggs_context_delegate.'
-        : 'A link is reach-only — it shares no context on its own. Opening a chat with the peer admits both delegates to it from then on. To share context that already exists, share a slice of a grant you hold with context_delegate, or ask the peer owner to issue one.';
+        ? 'A link is reach-only — it shares no context on its own. Open a chat with the peer (ziggs_chat_open, participantId = peer agent id): that admits both linked agents to read and post from then on. To share context that already exists, issue a grant on it with ziggs_context_issue_grant or share a slice of one you hold with ziggs_context_delegate.'
+        : 'A link is reach-only — it shares no context on its own. Opening a chat with the peer admits both linked agents to it from then on. To share context that already exists, share a slice of a grant you hold with context_delegate, or ask the peer owner to issue one.';
 }
 const LINK_STATUSES = ['active', 'open', 'cancelled', 'all'];
 /**
@@ -83,8 +83,8 @@ export const createLinkInviteCapability = {
             maxClaims: seats,
             seatsRemaining: seats - (agreement.linkInvite?.claimsUsed ?? 0),
             message: env.surface === 'mcp'
-                ? `Open link invite created, ${seatNote}. Give the human shareUrl and nothing else — it is the whole invite. A recipient with no Ziggs account signs up straight from that page, no beta code needed, and accepting the link is part of the same step; a recipient who would rather their own assistant do the wiring can hand it the same URL, because the page carries the MCP server address and the claim instructions in its markup. Either way the recipient needs their own assistant connected before the link carries anything.`
-                : `Open link invite created, ${seatNote}. shareUrl is the whole invite: a recipient with no Ziggs account signs up straight from that page and accepts the link in the same step, and an assistant handed the same URL reads the connect instructions off it. They still need an assistant connected before the link carries anything. No agent id needed on either side. Revoke with agreement_revoke to disable.`,
+                ? `Open link invite created, ${seatNote}. Give the human shareUrl and nothing else — it is the whole invite. A recipient with no Ziggs account signs up straight from that page, no beta code needed, and accepting the link is part of the same step; a recipient who would rather their own assistant do the wiring can hand it the same URL, because the page carries the MCP server address and the claim instructions in its markup. Either way the recipient's side of the link is one of their agents — their assistant by default — and it must be running before the link carries anything.`
+                : `Open link invite created, ${seatNote}. shareUrl is the whole invite: a recipient with no Ziggs account signs up straight from that page and accepts the link in the same step, and an assistant handed the same URL reads the connect instructions off it. Their side of the link is one of their agents (their assistant by default), and it must be running before the link carries anything. No agent id needed on either side. Revoke with agreement_revoke to disable.`,
             agreement,
         };
     },
@@ -94,8 +94,8 @@ export const listLinksCapability = {
     key: 'link_list',
     names: { sdk: 'link_list', mcp: 'ziggs_link_list' },
     descriptions: {
-        sdk: 'List link agreements for this agent — bilateral agent-to-agent trust relationships (GET /agreements?engagementKind=link). Defaults to ACTIVE links only; pass status to see pending proposals ("open") or revoked ones ("cancelled"). Each item is a link summary: agreementId, status, proposalStatus, parties. Request a new link with agreement_propose (engagementKind "link"), or link_create_invite when you lack the agent id; end one with agreement_revoke.',
-        mcp: 'List link agreements for this delegate — bilateral agent-to-agent trust relationships, NOT third-party service connections (see ziggs_connection_list for those) (GET /agreements?engagementKind=link). Defaults to ACTIVE links only; pass status to see pending proposals ("open") or revoked ones ("cancelled"). Each item is a link summary: agreementId, status, proposalStatus, parties.creatorAgent (requester), parties.providerAgent (target), parties.proposedTo (target owner). Approve pending links via ziggs_agreement_respond; request a new one with ziggs_agreement_propose (engagementKind "link"), or ziggs_link_create_invite when you lack the agent id; end one with ziggs_agreement_revoke.',
+        sdk: 'List link agreements for this agent — bilateral agent-to-agent trust relationships (GET /agreements?engagementKind=link). Any agent can link with any other agent. Defaults to ACTIVE links only; pass status to see pending proposals ("open") or revoked ones ("cancelled"). Each item is a link summary: agreementId, status, proposalStatus, parties. Request a new link with agreement_propose (engagementKind "link"), or link_create_invite when you lack the agent id; end one with agreement_revoke.',
+        mcp: 'List link agreements for this agent — bilateral agent-to-agent trust relationships, NOT third-party service connections (see ziggs_connection_list for those) (GET /agreements?engagementKind=link). Any agent can link with any other agent. Defaults to ACTIVE links only; pass status to see pending proposals ("open") or revoked ones ("cancelled"). Each item is a link summary: agreementId, status, proposalStatus, parties.creatorAgent (requester), parties.providerAgent (target), parties.proposedTo (target owner). Approve pending links via ziggs_agreement_respond; request a new one with ziggs_agreement_propose (engagementKind "link"), or ziggs_link_create_invite when you lack the agent id; end one with ziggs_agreement_revoke.',
     },
     annotation: 'read-only',
     params: {

package/dist/capabilities/marketplace.js

@@ -17,8 +17,8 @@ export const marketplaceViewCapability = {
     key: 'marketplace_view',
     names: { sdk: 'marketplace_view', mcp: 'ziggs_marketplace_view' },
     descriptions: {
-        sdk: 'Browse the open marketplace: quests (work buyers broadcast — you would do the work) and standing offers (services sellers broadcast — you would buy). Returns public rows plus org-scoped rows from your org, filtered server-side. Claim a row with agreement_claim; publish your own via agreement_propose with proposedTo "everyone"/"org" (providerId = your id for an offer, omitted for a quest).',
-        mcp: 'Browse the open marketplace: quests (work buyers broadcast — you would do the work) and standing offers (services sellers broadcast — you would buy). Returns public rows plus org-scoped rows from your org, filtered server-side. Claim a row with ziggs_agreement_claim; publish your own via ziggs_agreement_propose with proposedTo "everyone"/"org" (providerId = your id for an offer, omitted for a quest).',
+        sdk: 'Browse the open marketplace — where every engagement STARTS (posted-first: reuse an active agreement, else claim a listing here, before ever proposing). Quests are work buyers broadcast (you would do the work); standing offers are services sellers broadcast (you would buy). Returns public rows plus org-scoped rows from your org, filtered server-side. Claim a row with agreement_claim — listings are take-it-or-leave-it, never counter one; publish your own via agreement_propose with proposedTo "everyone"/"org" (providerId = your id for an offer, omitted for a quest).',
+        mcp: 'Browse the open marketplace — where every engagement STARTS (posted-first: reuse an active agreement, else claim a listing here, before ever proposing). Quests are work buyers broadcast (you would do the work); standing offers are services sellers broadcast (you would buy). Returns public rows plus org-scoped rows from your org, filtered server-side. Claim a row with ziggs_agreement_claim — listings are take-it-or-leave-it, never counter one; publish your own via ziggs_agreement_propose with proposedTo "everyone"/"org" (providerId = your id for an offer, omitted for a quest).',
     },
     annotation: 'read-only',
     params: {

package/dist/config.d.ts

@@ -15,8 +15,6 @@ export type ApiClientLogLevel = 'debug' | 'trace' | 'info' | 'warn' | 'error' |
 export interface ApiClientConfig {
     /** Backend base URL. Falls back to production when nothing sets it. */
     httpUrl?: string;
-    /** WebSocket base URL. Falls back to production when nothing sets it. */
-    wsUrl?: string;
     /** `runtimeLog` threshold. Falls back to `info`. */
     logLevel?: ApiClientLogLevel;
 }

package/dist/config.js

@@ -26,8 +26,6 @@ let version = 0;
 export function configureApiClient(next) {
     if (next.httpUrl !== undefined)
         config.httpUrl = next.httpUrl;
-    if (next.wsUrl !== undefined)
-        config.wsUrl = next.wsUrl;
     if (next.logLevel !== undefined)
         config.logLevel = next.logLevel;
     version += 1;

package/dist/http/ArtifactsClient.d.ts

@@ -20,7 +20,7 @@ export interface ListArtifactsResult {
 }
 export interface WriteArtifactInput {
     text: string;
-    content_type?: string;
+    contentType?: string;
     visibility?: ArtifactVisibility;
     /** When the artifact is associated with a chat. */
     chatId?: string;
@@ -37,6 +37,43 @@ export interface WriteArtifactInput {
      */
     idempotencyKey?: string;
 }
+export type ArtifactFileFormat = 'pdf' | 'docx' | 'hwpx' | 'md' | 'txt';
+export interface ArtifactUploadUrlInput {
+    filename: string;
+    mime: string;
+    /** Exact UTF-8 / file byte length of the object that will be PUT. */
+    byteSize: number;
+    format?: ArtifactFileFormat;
+    visibility?: ArtifactVisibility;
+    chatId?: string;
+    agreementId?: string;
+    taskId?: string;
+    service?: Record<string, unknown>;
+    idempotencyKey?: string;
+    /**
+     * Optional raw bytes. When set, the client PUTs to the presigned URL and
+     * returns `checksum` for {@link ArtifactsClient.completeFile}.
+     */
+    content?: Uint8Array | Buffer;
+    /** Optional base64 of the same bytes as `content`. */
+    contentBase64?: string;
+}
+export interface ArtifactUploadUrlResult {
+    artifactId: string;
+    uploadUrl: string;
+    expiresAt: string;
+    storageKey: string;
+    /** Set when this client performed the S3 PUT. */
+    putOk?: boolean;
+    /** sha256 hex when content was supplied and PUT succeeded. */
+    checksum?: string;
+}
+export type ArtifactFileView = Record<string, unknown> & {
+    artifactId?: string;
+    extractionStatus?: string | null;
+    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 —
@@ -110,6 +147,22 @@ export declare class ArtifactsClient {
     attachToTask(artifactId: string, taskId: string, role?: 'input' | 'output'): Promise<{
         success: boolean;
     }>;
+    /**
+     * File artifact rail — presign PUT, then client uploads bytes to `uploadUrl`,
+     * then {@link completeFile}. Optional `content` / `contentBase64` performs the
+     * S3 PUT here and returns a sha256 so complete can follow immediately.
+     */
+    uploadUrl(input: ArtifactUploadUrlInput): Promise<ArtifactUploadUrlResult>;
+    completeFile(artifactId: string, checksum: string): Promise<ArtifactFileView>;
+    download(artifactId: string): Promise<{
+        downloadUrl: string;
+        expiresAt: string;
+        filename: string;
+    }>;
+    reExtract(artifactId: string): Promise<ArtifactFileView>;
+    /** ZIG-1262 — shared fetch → text → throwApiError → JSON parse for file rail. */
+    private _post;
+    private _get;
     private _attach;
     /**
      * ZIG-1037 — at most one container, and none is fine.

package/dist/http/ArtifactsClient.js

@@ -2,6 +2,17 @@ import { runtimeLog } from '../shared/runtimeLog.js';
 import { throwApiError } from '../shared/apiError.js';
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { buildOperatorHeaders } from './operatorHeaders.js';
+function resolveUploadBytes(input) {
+    if (input.content != null) {
+        return Buffer.isBuffer(input.content)
+            ? input.content
+            : Buffer.from(input.content);
+    }
+    if (input.contentBase64 != null && input.contentBase64 !== '') {
+        return Buffer.from(input.contentBase64, 'base64');
+    }
+    return null;
+}
 /**
  * Replaces `ContextReader`'s artifact reads + `ContextWriter`'s breadcrumb
  * writes. `visibility: 'agent-private'` is the new home for agent thoughts —
@@ -81,7 +92,7 @@ export class ArtifactsClient {
         return this.write({
             ...artifactScopeForSession(sessionId),
             text,
-            content_type: 'thought',
+            contentType: 'thought',
             visibility: 'agent-private',
             idempotencyKey: opts.idempotencyKey,
         });
@@ -117,7 +128,7 @@ export class ArtifactsClient {
             headers: this._headers(),
             body: JSON.stringify({
                 text: input.text.trim(),
-                content_type: input.content_type ?? 'text',
+                contentType: input.contentType ?? 'text',
                 visibility: input.visibility ?? 'chat',
                 chatId: input.chatId,
                 agreementId: input.agreementId,
@@ -159,7 +170,90 @@ export class ArtifactsClient {
             role,
         });
     }
-    async _attach(path, body) {
+    /**
+     * File artifact rail — presign PUT, then client uploads bytes to `uploadUrl`,
+     * then {@link completeFile}. Optional `content` / `contentBase64` performs the
+     * S3 PUT here and returns a sha256 so complete can follow immediately.
+     */
+    async uploadUrl(input) {
+        if (!input.filename?.trim()) {
+            throw new Error('ArtifactsClient.uploadUrl: filename is required');
+        }
+        if (!input.mime?.trim()) {
+            throw new Error('ArtifactsClient.uploadUrl: mime is required');
+        }
+        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}`);
+        }
+        const parsed = await this._post('/artifacts/upload-url', {
+            filename: input.filename.trim(),
+            mime: input.mime.trim(),
+            byteSize: input.byteSize,
+            format: input.format,
+            visibility: input.visibility,
+            chatId: input.chatId,
+            agreementId: input.agreementId,
+            taskId: input.taskId,
+            service: input.service,
+            ...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}),
+        }, 'artifact upload-url');
+        if (!parsed.artifactId || !parsed.uploadUrl) {
+            throw new Error('artifact upload-url response missing artifactId/uploadUrl');
+        }
+        if (bytes) {
+            const put = await fetch(parsed.uploadUrl, {
+                method: 'PUT',
+                headers: { 'Content-Type': input.mime.trim() },
+                // Blob/Uint8Array — Buffer is not always a DOM BodyInit under tsc DOM libs.
+                body: new Uint8Array(bytes),
+            });
+            if (!put.ok) {
+                const putBody = await put.text().catch(() => '');
+                throw new Error(`S3 PUT failed: ${put.status} ${put.statusText}${putBody ? ` — ${putBody.slice(0, 200)}` : ''}`);
+            }
+            const { createHash } = await import('node:crypto');
+            parsed.checksum = createHash('sha256').update(bytes).digest('hex');
+            parsed.putOk = true;
+        }
+        return parsed;
+    }
+    async completeFile(artifactId, checksum) {
+        if (!artifactId)
+            throw new Error('ArtifactsClient.completeFile: artifactId is required');
+        if (!/^[a-f0-9]{64}$/i.test(checksum)) {
+            throw new Error('ArtifactsClient.completeFile: checksum must be sha256 hex');
+        }
+        return this._post(`/artifacts/${encodeURIComponent(artifactId)}/complete`, { checksum: checksum.toLowerCase() }, 'artifact complete');
+    }
+    async download(artifactId) {
+        if (!artifactId)
+            throw new Error('ArtifactsClient.download: artifactId is required');
+        const parsed = await this._get(`/artifacts/${encodeURIComponent(artifactId)}/download`, 'artifact download');
+        if (!parsed.downloadUrl || !parsed.expiresAt || !parsed.filename) {
+            throw new Error('artifact download response incomplete');
+        }
+        return {
+            downloadUrl: parsed.downloadUrl,
+            expiresAt: parsed.expiresAt,
+            filename: parsed.filename,
+        };
+    }
+    async reExtract(artifactId) {
+        if (!artifactId)
+            throw new Error('ArtifactsClient.reExtract: artifactId is required');
+        return this._post(`/artifacts/${encodeURIComponent(artifactId)}/re-extract`, {}, 'artifact re-extract');
+    }
+    /** ZIG-1262 — shared fetch → text → throwApiError → JSON parse for file rail. */
+    async _post(path, body, label) {
         const res = await fetch(`${getBackendUrl()}${path}`, {
             method: 'POST',
             headers: this._headers(),
@@ -167,8 +261,22 @@ export class ArtifactsClient {
         });
         const text = await res.text().catch(() => '');
         if (!res.ok) {
-            throwApiError(res, text, `attachArtifact failed: ${res.status} ${res.statusText}`);
+            throwApiError(res, text, `${label} failed: ${res.status} ${res.statusText}`);
+        }
+        return (text ? JSON.parse(text) : {});
+    }
+    async _get(path, label) {
+        const res = await fetch(`${getBackendUrl()}${path}`, {
+            headers: this._headers(),
+        });
+        const text = await res.text().catch(() => '');
+        if (!res.ok) {
+            throwApiError(res, text, `${label} failed: ${res.status} ${res.statusText}`);
         }
+        return (text ? JSON.parse(text) : {});
+    }
+    async _attach(path, body) {
+        await this._post(path, body, 'attachArtifact');
         return { success: true };
     }
     /**

package/dist/http/ChatClient.d.ts

@@ -13,6 +13,7 @@ export declare function openConversation(participantId: string, creds: Creds, {
     newChat?: boolean;
 }): Promise<{
     chatId: string;
+    reused?: boolean;
 }>;
 export interface SendChatMessageInput {
     chatId: string;
@@ -80,6 +81,7 @@ export declare class ChatClient {
         newChat?: boolean;
     }): Promise<{
         chatId: string;
+        reused?: boolean;
     }>;
     addMember(input: AddChatMemberInput): Promise<AddChatMemberResult>;
     sendMessage(input: SendChatMessageInput): Promise<SendChatMessageResult>;

package/dist/http/ChatClient.js

@@ -36,7 +36,15 @@ export async function openConversation(participantId, creds, { newChat = false }
     if (!data?.['chatId'] || typeof data['chatId'] !== 'string') {
         throw new Error('Invalid response: expected { chatId } from POST /chats');
     }
-    return { chatId: data['chatId'] };
+    // ZIG-1216: left UNDEFINED rather than defaulted when the backend does not
+    // send it. A backend from before this field cannot be assumed to have created
+    // the room — defaulting to false would report a reused conversation as fresh,
+    // which is worse than saying nothing.
+    const reused = data['reused'];
+    return {
+        chatId: data['chatId'],
+        ...(typeof reused === 'boolean' ? { reused } : {}),
+    };
 }
 /**
  * POST /chats/:chatId/members — add user/agent; agent-invite may return pending admission (ZIG-426).

package/dist/http/OrgsClient.d.ts

@@ -27,9 +27,30 @@ export type OrgResolution = {
  * match. Ambiguous names return the candidates rather than guessing.
  */
 export declare function resolveOrgSelector(orgs: MyOrg[], selector: string): OrgResolution;
+/** MCP OAuth auto-provisioned delegate id prefix (ZIG-545 / ZIG-852). */
+export declare const MCP_OAUTH_DELEGATE_AGENT_ID_PREFIX = "claude-delegate--";
+/** True when `agentId` is an inbound MCP OAuth auto-provisioned delegate. */
+export declare function isMcpOAuthDelegateAgentId(agentId: string): boolean;
 /**
  * ZIG-640 / ZIG-956 — runtime acting org from the server (self-hire / agent
  * row): GET /agents/claude-delegate/access. Moved here from ziggs-mcp's inline
  * fetch (ZIG-894 "one client for every surface").
+ *
+ * Only valid for MCP OAuth Claude-delegate sessions. Hosted / fleet
+ * impersonation must use {@link fetchHostedAgentAccess} (ZIG-1272).
  */
 export declare function fetchDelegateAccess(creds: Creds, baseUrl?: string): Promise<Record<string, unknown>>;
+/**
+ * ZIG-1272 — session access for hosted / fleet impersonation (owner key +
+ * X-Agent-Id, or an agent-scoped key that is not a Claude OAuth delegate).
+ *
+ * `GET /agents/claude-delegate/access` refuses those credentials (or reports
+ * disconnected), even though every other tool works. The credential's tenant
+ * is already on the actor (`GET /orgs/me` → `activeOrgId`).
+ */
+export declare function fetchHostedAgentAccess(creds: Creds, baseUrl?: string): Promise<Record<string, unknown>>;
+/**
+ * ZIG-1272 — pick the access reader that matches the acting agent.
+ * Claude OAuth delegates → self-hire status; everything else → hosted path.
+ */
+export declare function fetchSessionAccess(creds: Creds, baseUrl?: string): Promise<Record<string, unknown>>;

package/dist/http/OrgsClient.js

@@ -42,10 +42,19 @@ export function resolveOrgSelector(orgs, selector) {
         return { status: 'ambiguous', matches: byName };
     return { status: 'not-found' };
 }
+/** MCP OAuth auto-provisioned delegate id prefix (ZIG-545 / ZIG-852). */
+export const MCP_OAUTH_DELEGATE_AGENT_ID_PREFIX = 'claude-delegate--';
+/** True when `agentId` is an inbound MCP OAuth auto-provisioned delegate. */
+export function isMcpOAuthDelegateAgentId(agentId) {
+    return !!agentId && agentId.startsWith(MCP_OAUTH_DELEGATE_AGENT_ID_PREFIX);
+}
 /**
  * ZIG-640 / ZIG-956 — runtime acting org from the server (self-hire / agent
  * row): GET /agents/claude-delegate/access. Moved here from ziggs-mcp's inline
  * fetch (ZIG-894 "one client for every surface").
+ *
+ * Only valid for MCP OAuth Claude-delegate sessions. Hosted / fleet
+ * impersonation must use {@link fetchHostedAgentAccess} (ZIG-1272).
  */
 export async function fetchDelegateAccess(creds, baseUrl) {
     const url = `${baseUrl || getBackendUrl()}/agents/claude-delegate/access`;
@@ -59,3 +68,55 @@ export async function fetchDelegateAccess(creds, baseUrl) {
     }
     return body ? JSON.parse(body) : {};
 }
+/**
+ * ZIG-1272 — session access for hosted / fleet impersonation (owner key +
+ * X-Agent-Id, or an agent-scoped key that is not a Claude OAuth delegate).
+ *
+ * `GET /agents/claude-delegate/access` refuses those credentials (or reports
+ * disconnected), even though every other tool works. The credential's tenant
+ * is already on the actor (`GET /orgs/me` → `activeOrgId`).
+ */
+export async function fetchHostedAgentAccess(creds, baseUrl) {
+    const url = `${baseUrl || getBackendUrl()}/orgs/me`;
+    const res = await fetch(url, {
+        method: 'GET',
+        headers: buildOperatorHeaders(creds.operatorKey, creds.agentId),
+    });
+    const body = await res.text().catch(() => '');
+    if (!res.ok) {
+        throwApiError(res, body, `GET /orgs/me failed: ${res.status}`);
+    }
+    const parsed = body
+        ? JSON.parse(body)
+        : {};
+    const activeOrgId = typeof parsed.activeOrgId === 'string' && parsed.activeOrgId
+        ? parsed.activeOrgId
+        : null;
+    const match = (parsed.orgs ?? []).find((o) => o.orgId === activeOrgId);
+    // Prefer `activeOrg` (ZIG-1272) — membership list often omits the agent home
+    // org under fleet impersonation.
+    const fromActive = parsed.activeOrg;
+    const orgName = (typeof fromActive?.name === 'string' && fromActive.name) ||
+        match?.name ||
+        null;
+    const orgKind = (typeof fromActive?.kind === 'string' && fromActive.kind) ||
+        match?.kind ||
+        null;
+    return {
+        connected: true,
+        orgId: activeOrgId,
+        orgName,
+        orgKind,
+        switchOrgHint: 'Hosted agent session — acting org is the agent home / key workspace, not MCP OAuth consent.',
+    };
+}
+/**
+ * ZIG-1272 — pick the access reader that matches the acting agent.
+ * Claude OAuth delegates → self-hire status; everything else → hosted path.
+ */
+export async function fetchSessionAccess(creds, baseUrl) {
+    if (isMcpOAuthDelegateAgentId(creds.agentId)) {
+        return fetchDelegateAccess(creds, baseUrl);
+    }
+    return fetchHostedAgentAccess(creds, baseUrl);
+}

package/dist/http/TaskClient.d.ts

@@ -38,9 +38,11 @@ export declare function getActiveTasksForChat(chatId: string, creds: Creds): Pro
 export declare function cancelTask(taskId: string, creds: Creds): Promise<Task>;
 export declare function getSubtasks(parentTaskId: string, creds: Creds): Promise<Task[]>;
 export interface PlanReplaceStep {
-    stepId: string;
+    /** Omit to let the server mint `step-<n>` (ZIG-1268). */
+    stepId?: string;
     description: string;
-    order: number;
+    /** Omit to use the array index (ZIG-1268). */
+    order?: number;
 }
 export declare function replaceTaskPlan(taskId: string, steps: PlanReplaceStep[], creds: Creds): Promise<Task>;
 export declare function updateTaskPlanStep(taskId: string, stepId: string, status: string, result: unknown, creds: Creds): Promise<Task>;

package/dist/http/index.d.ts

@@ -21,7 +21,7 @@ export { PaymentsClient } from './PaymentsClient.js';
 export type { PaymentsError, WalletBalance, WalletRef, PaymentTransactionView, TransferResult, HoldResult, ReleaseResult, PaymentGrantView, PaymentGrantEnvelope, RevokeGrantResult, PaymentApproval, WaitForApprovalResult, } from './PaymentsClient.js';
 export { ConnectionsClient, assertNoLeakedConnectionSecret, } from './ConnectionsClient.js';
 export type { ConnectionsError, ConnectionProxyParams, ConnectionGrant, ConnectionWithGrants, McpConnectionRequestParams, } from './ConnectionsClient.js';
-export { fetchMyOrgs, resolveOrgSelector, fetchDelegateAccess, } from './OrgsClient.js';
+export { fetchMyOrgs, resolveOrgSelector, fetchDelegateAccess, fetchHostedAgentAccess, fetchSessionAccess, isMcpOAuthDelegateAgentId, MCP_OAUTH_DELEGATE_AGENT_ID_PREFIX, } from './OrgsClient.js';
 export type { MyOrg, OrgResolution } from './OrgsClient.js';
 export { AgentSearchClient } from './AgentSearchClient.js';
 export { TelemetryClient } from './TelemetryClient.js';

package/dist/http/index.js

@@ -14,7 +14,7 @@ export { ContextGrantsClient } from './ContextGrantsClient.js';
 export { grantCaveat, CONTEXT_GRANT_SCOPE_KINDS, GRANT_SCOPE_KINDS, } from './grants.js';
 export { PaymentsClient } from './PaymentsClient.js';
 export { ConnectionsClient, assertNoLeakedConnectionSecret, } from './ConnectionsClient.js';
-export { fetchMyOrgs, resolveOrgSelector, fetchDelegateAccess, } from './OrgsClient.js';
+export { fetchMyOrgs, resolveOrgSelector, fetchDelegateAccess, fetchHostedAgentAccess, fetchSessionAccess, isMcpOAuthDelegateAgentId, MCP_OAUTH_DELEGATE_AGENT_ID_PREFIX, } from './OrgsClient.js';
 export { AgentSearchClient } from './AgentSearchClient.js';
 export { TelemetryClient } from './TelemetryClient.js';
 export { InboxClient } from './InboxClient.js';

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export * from './relay/provisionRelayWorkers.js';
 export { ConnectionManager } from './ConnectionManager.js';
 export { EntryTypes, ContentTypes, OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET, BROADCAST_TARGETS, isBroadcastTarget, isPersonaRef, isRoomPresentationRef, isOpaquePresentationRef, AGREEMENT_ENGAGEMENT_KIND, isValidContentType, } from './types.js';
 export type { PrincipalPresentation } from './types.js';
-export { getBackendUrl, getWebSocketUrl } from './utils/urlUtils.js';
+export { getBackendUrl } from './utils/urlUtils.js';
 export { configureApiClient, apiClientConfig } from './config.js';
 export type { ApiClientConfig, ApiClientLogLevel } from './config.js';
 export { runtimeLog, resetRuntimeLogLevelCache } from './shared/runtimeLog.js';

package/dist/index.js

@@ -3,7 +3,7 @@ export * from './capabilities/index.js';
 export * from './relay/provisionRelayWorkers.js';
 export { ConnectionManager } from './ConnectionManager.js';
 export { EntryTypes, ContentTypes, OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET, BROADCAST_TARGETS, isBroadcastTarget, isPersonaRef, isRoomPresentationRef, isOpaquePresentationRef, AGREEMENT_ENGAGEMENT_KIND, isValidContentType, } from './types.js';
-export { getBackendUrl, getWebSocketUrl } from './utils/urlUtils.js';
+export { getBackendUrl } from './utils/urlUtils.js';
 // ZIG-652: the host injects the environment; this package never reads it.
 export { configureApiClient, apiClientConfig } from './config.js';
 export { runtimeLog, resetRuntimeLogLevelCache } from './shared/runtimeLog.js';

package/dist/types.d.ts

@@ -244,7 +244,7 @@ export interface MessageMetadata {
      */
     presentation?: PrincipalPresentation | null;
     entryType?: string;
-    content_type?: string;
+    contentType?: string;
     taskId?: string | null;
     /**
      * Optional task / agreement snapshot pinned by the backend on

package/dist/utils/urlUtils.d.ts

@@ -1,2 +1 @@
 export declare function getBackendUrl(): string;
-export declare function getWebSocketUrl(): string;

package/dist/utils/urlUtils.js

@@ -3,7 +3,3 @@ export function getBackendUrl() {
     const url = apiClientConfig().httpUrl || 'https://api.ziggsai.com';
     return url.startsWith('http') ? url : `https://${url}`;
 }
-export function getWebSocketUrl() {
-    const wsUrl = apiClientConfig().wsUrl || 'wss://api.ziggsai.com';
-    return wsUrl.startsWith('ws') ? wsUrl : `wss://${wsUrl}`;
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/api-client",
-  "version": "0.9.3",
+  "version": "0.9.7",
   "description": "HTTP and WebSocket client for the Ziggs backend API",
   "type": "module",
   "main": "dist/index.js",