@ziggs-ai/api-client 0.9.5 → 0.9.8

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.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,7 +51,7 @@ 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',
         },
@@ -78,7 +78,7 @@ export const recordArtifactCapability = {
         if (visibility !== 'chat' && visibility !== 'agent-private') {
             throw new Error('visibility must be chat or agent-private');
         }
-        const contentType = args['content_type'];
+        const contentType = args['contentType'];
         const taskId = args['taskId'];
         const creds = fullCreds(env);
         const { artifactId } = await new ArtifactsClient(creds.operatorKey, creds.agentId, creds.laneId).writeStrict({
@@ -87,7 +87,7 @@ export const recordArtifactCapability = {
             chatId,
             agreementId,
             taskId,
-            content_type: contentType,
+            contentType,
             idempotencyKey: args['idempotencyKey'],
         });
         return {

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: {

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

@@ -2,6 +2,7 @@ export { type CapabilitySurface, type CapabilityAnnotation, type CapabilityParam
 export { PAYMENT_CAPABILITIES, paymentBalanceCapability, paymentTransferCapability, paymentWaitForApprovalCapability, paymentHoldCapability, paymentReleaseCapability, paymentResolveWalletCapability, paymentIssueGrantCapability, paymentAttenuateGrantCapability, paymentRevokeGrantCapability, } from './payments.js';
 export { LINK_CAPABILITIES, createLinkInviteCapability, listLinksCapability, linkIsReachOnly, } from './links.js';
 export { AGREEMENT_CAPABILITIES, agreementClaimCapability } from './agreements.js';
+export { AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION } from './proposeProviderId.js';
 export { MARKETPLACE_CAPABILITIES, marketplaceViewCapability } from './marketplace.js';
 export { GRANTS_CAPABILITIES, listGrantsCapability } from './grants.js';
 export { CONTEXT_CAPABILITIES, contextReadCapability, contextDelegateCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, contextBounds, resolveOrgScopeId, } from './context.js';

package/dist/capabilities/index.js

@@ -2,6 +2,7 @@ export { fullCreds, rethrowWithContext, } from './types.js';
 export { PAYMENT_CAPABILITIES, paymentBalanceCapability, paymentTransferCapability, paymentWaitForApprovalCapability, paymentHoldCapability, paymentReleaseCapability, paymentResolveWalletCapability, paymentIssueGrantCapability, paymentAttenuateGrantCapability, paymentRevokeGrantCapability, } from './payments.js';
 export { LINK_CAPABILITIES, createLinkInviteCapability, listLinksCapability, linkIsReachOnly, } from './links.js';
 export { AGREEMENT_CAPABILITIES, agreementClaimCapability } from './agreements.js';
+export { AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION } from './proposeProviderId.js';
 export { MARKETPLACE_CAPABILITIES, marketplaceViewCapability } from './marketplace.js';
 export { GRANTS_CAPABILITIES, listGrantsCapability } from './grants.js';
 export { CONTEXT_CAPABILITIES, contextReadCapability, contextDelegateCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, contextBounds, resolveOrgScopeId, } from './context.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/capabilities/proposeProviderId.d.ts

@@ -0,0 +1,6 @@
+/**
+ * ZIG-1274 — `providerId` parameter description shared by SDK + MCP propose
+ * tools. Stated on the schema so a fresh agent does not burn a turn learning
+ * the rule from the validation error.
+ */
+export declare const AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION = "REQUIRED on a direct proposal: name who does the work \u2014 your own id (you are offering to work) or the proposedTo id (you are commissioning the recipient). Do not omit it when proposedTo is a person/agent id. Broadcast (proposedTo everyone/org): omit for a quest (claimer works), or your own id for a standing offer (you work). A third-party id brokers and needs a matching published offer. Payer is always the non-providing side.";

package/dist/capabilities/proposeProviderId.js

@@ -0,0 +1,6 @@
+/**
+ * ZIG-1274 — `providerId` parameter description shared by SDK + MCP propose
+ * tools. Stated on the schema so a fresh agent does not burn a turn learning
+ * the rule from the validation error.
+ */
+export const AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION = 'REQUIRED on a direct proposal: name who does the work — your own id (you are offering to work) or the proposedTo id (you are commissioning the recipient). Do not omit it when proposedTo is a person/agent id. Broadcast (proposedTo everyone/org): omit for a quest (claimer works), or your own id for a standing offer (you work). A third-party id brokers and needs a matching published offer. Payer is always the non-providing side.';

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;
@@ -160,6 +160,9 @@ export declare class ArtifactsClient {
         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

@@ -92,7 +92,7 @@ export class ArtifactsClient {
         return this.write({
             ...artifactScopeForSession(sessionId),
             text,
-            content_type: 'thought',
+            contentType: 'thought',
             visibility: 'agent-private',
             idempotencyKey: opts.idempotencyKey,
         });
@@ -128,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,
@@ -194,30 +194,18 @@ export class ArtifactsClient {
         if (bytes && bytes.byteLength !== input.byteSize) {
             throw new Error(`ArtifactsClient.uploadUrl: byteSize ${input.byteSize} does not match content length ${bytes.byteLength}`);
         }
-        const url = `${getBackendUrl()}/artifacts/upload-url`;
-        const res = await fetch(url, {
-            method: 'POST',
-            headers: this._headers(),
-            body: JSON.stringify({
-                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 } : {}),
-            }),
-        });
-        const text = await res.text().catch(() => '');
-        if (!res.ok) {
-            throwApiError(res, text, `artifact upload-url failed: ${res.status} ${res.statusText}`);
-        }
-        const parsed = text
-            ? JSON.parse(text)
-            : {};
+        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');
         }
@@ -244,30 +232,12 @@ export class ArtifactsClient {
         if (!/^[a-f0-9]{64}$/i.test(checksum)) {
             throw new Error('ArtifactsClient.completeFile: checksum must be sha256 hex');
         }
-        const url = `${getBackendUrl()}/artifacts/${encodeURIComponent(artifactId)}/complete`;
-        const res = await fetch(url, {
-            method: 'POST',
-            headers: this._headers(),
-            body: JSON.stringify({ checksum: checksum.toLowerCase() }),
-        });
-        const text = await res.text().catch(() => '');
-        if (!res.ok) {
-            throwApiError(res, text, `artifact complete failed: ${res.status} ${res.statusText}`);
-        }
-        return text ? JSON.parse(text) : {};
+        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 url = `${getBackendUrl()}/artifacts/${encodeURIComponent(artifactId)}/download`;
-        const res = await fetch(url, { headers: this._headers() });
-        const text = await res.text().catch(() => '');
-        if (!res.ok) {
-            throwApiError(res, text, `artifact download failed: ${res.status} ${res.statusText}`);
-        }
-        const parsed = text
-            ? JSON.parse(text)
-            : {};
+        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');
         }
@@ -280,28 +250,33 @@ export class ArtifactsClient {
     async reExtract(artifactId) {
         if (!artifactId)
             throw new Error('ArtifactsClient.reExtract: artifactId is required');
-        const url = `${getBackendUrl()}/artifacts/${encodeURIComponent(artifactId)}/re-extract`;
-        const res = await fetch(url, {
+        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(),
-            body: JSON.stringify({}),
+            body: JSON.stringify(body),
         });
         const text = await res.text().catch(() => '');
         if (!res.ok) {
-            throwApiError(res, text, `artifact re-extract failed: ${res.status} ${res.statusText}`);
+            throwApiError(res, text, `${label} failed: ${res.status} ${res.statusText}`);
         }
-        return text ? JSON.parse(text) : {};
+        return (text ? JSON.parse(text) : {});
     }
-    async _attach(path, body) {
+    async _get(path, label) {
         const res = await fetch(`${getBackendUrl()}${path}`, {
-            method: 'POST',
             headers: this._headers(),
-            body: JSON.stringify(body),
         });
         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 _attach(path, body) {
+        await this._post(path, body, 'attachArtifact');
         return { success: true };
     }
     /**

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.5",
+  "version": "0.9.8",
   "description": "HTTP and WebSocket client for the Ziggs backend API",
   "type": "module",
   "main": "dist/index.js",