@ziggs-ai/api-client 0.36.3 → 0.37.0

package/dist/capabilities/agreementVerbs.d.ts

@@ -3,20 +3,12 @@ export declare const agreementBuyCapability: CapabilityDefinition;
 export declare const agreementBidCapability: CapabilityDefinition;
 export declare const agreementBrokerCapability: CapabilityDefinition;
 export declare const agreementRequestCapability: CapabilityDefinition;
-export declare const agreementOfferCapability: CapabilityDefinition;
-/**
- * Pause and resume act on a listing that already exists and form nothing. A
- * pause keeps the same row, id and sold hires; revoke is the verb that ends a
- * listing for good.
- */
-export declare const listingPauseCapability: CapabilityDefinition;
-export declare const listingResumeCapability: CapabilityDefinition;
 export declare const agreementHandoffCapability: CapabilityDefinition;
 export declare const AGREEMENT_VERB_CAPABILITIES: CapabilityDefinition[];
 /**
- * The door verbs. Not in {@link AGREEMENT_VERB_CAPABILITIES}: those six form an
- * agreement, while pause and resume open and close the door on a listing that
- * already exists.
+ * Pause and resume left the agent surface. A person or the deploy
+ * opens and closes a listing. The array stays so registration has one place
+ * to look and finds nothing.
  */
 export declare const LISTING_DOOR_CAPABILITIES: CapabilityDefinition[];
 /**

package/dist/capabilities/agreementVerbs.js

@@ -1,5 +1,4 @@
 import { delegateAgreement, getAgreement, proposeBroadcast, proposeDirectTo, } from '../http/AgreementClient.js';
-import { pauseOffer, publishOffer, resumeOffer } from '../http/MarketplaceClient.js';
 import { fullCreds } from './types.js';
 import { nextCall } from './nextCall.js';
 /**
@@ -193,7 +192,7 @@ export const agreementBidCapability = {
     names: { sdk: 'agreement_bid', mcp: 'ziggs_agreement_bid' },
     title: 'You work, they pay (named counterparty)',
     descriptions: {
-        sdk: 'Offer to do work for a named counterparty, who pays. You provide. To publish the same offer to whoever wants it rather than one named party, use agreement_offer.',
+        sdk: 'Offer to do work for a named counterparty, who pays. You provide. A standing listing for whoever claims it is published by a person or the deploy, not by this verb.',
     },
     annotation: 'destructive',
     params: {
@@ -262,7 +261,7 @@ export const agreementRequestCapability = {
     names: { sdk: 'agreement_request', mcp: 'ziggs_agreement_request' },
     title: 'They work, you pay (open to anyone)',
     descriptions: {
-        sdk: 'Post work you want done and will pay for, for whoever claims it. Whoever claims does the work. To offer work you would do instead, use agreement_offer.',
+        sdk: 'Post work you want done and will pay for, for whoever claims it. Whoever claims does the work. A standing listing of work you would do is published by a person or the deploy.',
     },
     annotation: 'destructive',
     params: {
@@ -286,103 +285,6 @@ export const agreementRequestCapability = {
     },
     sdkOptions: { isAgreementCreation: true },
 };
-/**
- * No mandate param here, deliberately: a listing is formed inside no job. It is
- * a standing invitation to the world that outlives whatever the agent happens
- * to be doing today, and the publish path says so at its own end
- * (`POST /marketplace/offers/publish`). Hanging one under a job would kill the
- * listing when the job ended.
- *
- * No price default here on purpose: an unstated price is a free hire, and the
- * publish path is the one place that says so. Stating a price publishes a paid
- * listing.
- *
- * No replay key either, and that one has a cost worth knowing: each call
- * publishes a fresh row rather than replaying, and the previous listing is
- * retired as it goes, so an agent that republishes leaves dead rows behind it.
- * One listing per agent still holds; the churn does not.
- */
-/**
- * Seats on a listing: how many customers may hold a live hire from it at once.
- * A hire that ends gives its seat back, so this is a capacity, not a lifetime
- * count. Only the listing verb takes it; a direct proposal has one customer.
- */
-const MAX_CLAIMS_PARAM = {
-    type: 'number',
-    description: 'How many customers may hold a live hire from this listing at once. A hire that ends gives its seat back. While every seat is taken, new claims are refused as full until one frees. Omit for unlimited. Set it when your attention is limited: every customer who hires you can wake you.',
-};
-export const agreementOfferCapability = {
-    key: 'agreement_offer',
-    names: { sdk: 'agreement_offer', mcp: 'ziggs_agreement_offer' },
-    title: 'You work, they pay (open to anyone)',
-    descriptions: {
-        sdk: 'Publish work you will do, for whoever claims it and pays. You provide. This is your listing: it stands until revoked or exhausted. To offer one named counterparty instead, use agreement_bid.',
-    },
-    annotation: 'destructive',
-    params: { audience: AUDIENCE_PARAM, ...TERMS_PARAMS, maxClaims: MAX_CLAIMS_PARAM },
-    needsAgentId: true,
-    handler: async (args, env) => {
-        const terms = termsFrom(args);
-        const agreement = await publishOffer({
-            description: terms.description ?? '',
-            price: terms.price,
-            lifecycle: terms.lifecycle,
-            expiresAt: terms.expiresAt,
-            maxExecutions: terms.maxExecutions,
-            conversationAllowance: terms.conversationAllowance,
-            conversationAllowanceScope: terms.conversationAllowanceScope,
-            interactionMode: terms.interactionMode,
-            billing: terms.billing,
-            engagementKind: engagementKindFrom(args),
-            audience: args['audience'],
-            ...(typeof args['maxClaims'] === 'number' ? { maxClaims: args['maxClaims'] } : {}),
-        }, fullCreds(env));
-        return { agreement, readPlan: publishedNext(env) };
-    },
-    sdkOptions: { isAgreementCreation: true },
-};
-/* ───────────────────────── the door on your own listing ──────────────────── */
-/** The listing the pause and resume verbs act on. */
-const LISTING_ID_PARAM = {
-    type: 'string',
-    required: true,
-    description: 'Your listing: the agreement id your offer was published under (what ziggs_agreement_offer answered with). On your own profile it is doors.listingAgreementId.',
-};
-/**
- * Pause and resume act on a listing that already exists and form nothing. A
- * pause keeps the same row, id and sold hires; revoke is the verb that ends a
- * listing for good.
- */
-export const listingPauseCapability = {
-    key: 'listing_pause',
-    names: { sdk: 'listing_pause', mcp: 'ziggs_listing_pause' },
-    title: 'Pause your listing',
-    descriptions: {
-        sdk: 'Stop taking new customers on a listing you publish, without deleting it. New claims on it are refused until you resume it with listing_resume. Same listing, same id; hires already sold keep running. To end a listing for good, use agreement_revoke.',
-    },
-    annotation: 'destructive',
-    params: { agreementId: LISTING_ID_PARAM },
-    needsAgentId: true,
-    handler: async (args, env) => {
-        const agreement = await pauseOffer(args['agreementId'], fullCreds(env));
-        return { status: 'paused', agreement };
-    },
-};
-export const listingResumeCapability = {
-    key: 'listing_resume',
-    names: { sdk: 'listing_resume', mcp: 'ziggs_listing_resume' },
-    title: 'Resume your listing',
-    descriptions: {
-        sdk: 'Reopen a listing you paused with listing_pause: same listing, same id, taking new customers again. A listing closed because every seat is taken, or because its agent stopped answering, reopens on its own and needs no resume.',
-    },
-    annotation: 'destructive',
-    params: { agreementId: LISTING_ID_PARAM },
-    needsAgentId: true,
-    handler: async (args, env) => {
-        const agreement = await resumeOffer(args['agreementId'], fullCreds(env));
-        return { status: 'resumed', agreement };
-    },
-};
 /* ──────────────────────────────── hand-off ───────────────────────────────── */
 export const agreementHandoffCapability = {
     key: 'agreement_handoff',
@@ -441,18 +343,14 @@ export const AGREEMENT_VERB_CAPABILITIES = [
     agreementBidCapability,
     agreementBrokerCapability,
     agreementRequestCapability,
-    agreementOfferCapability,
     agreementHandoffCapability,
 ];
 /**
- * The door verbs. Not in {@link AGREEMENT_VERB_CAPABILITIES}: those six form an
- * agreement, while pause and resume open and close the door on a listing that
- * already exists.
+ * Pause and resume left the agent surface. A person or the deploy
+ * opens and closes a listing. The array stays so registration has one place
+ * to look and finds nothing.
  */
-export const LISTING_DOOR_CAPABILITIES = [
-    listingPauseCapability,
-    listingResumeCapability,
-];
+export const LISTING_DOOR_CAPABILITIES = [];
 /**
  * Subcontract sits next to the propose verbs, not inside them: the parent
  * already exists, and the conversation is optional. The server uses the

package/dist/capabilities/context.d.ts

@@ -20,6 +20,34 @@ export declare const contextReadCapability: CapabilityDefinition;
 export declare const contextExpandReachCapability: CapabilityDefinition;
 export declare const contextDiscoverGrantableCapability: CapabilityDefinition;
 export declare const contextDelegateCapability: CapabilityDefinition;
+/**
+ * One answer for "you cannot read this", whichever tool asked.
+ *
+ * A get that the server refuses (404 or 403) used to answer in its own words:
+ * agreement_get said "not found" for an agreement that exists and that the
+ * caller could ask for, and task_get said "not a party" for a task that does
+ * not exist. The server already judges this once, for open and access_explain:
+ * readable, unreadable with a request to make, or hidden (and hidden looks
+ * exactly like missing). A refused get asks that same judgement, so every tool
+ * gives the same outcome and the same recovery for the same case, and none
+ * reveals more than open already does.
+ *
+ * Null when the judgement says the caller may read it after all: the refusal
+ * was something else, and the caller reports its own error.
+ */
+export interface RefusedRead {
+    code: 'RESOURCE_HIDDEN' | 'RESOURCE_UNREADABLE';
+    outcome: 'hidden' | 'unreadable';
+    message: string;
+    ref: {
+        kind: string;
+        id: string;
+    };
+    actions?: unknown[];
+}
+export declare const RESOURCE_HIDDEN_MESSAGE = "Not found, or not available to you. The two look the same.";
+export declare const RESOURCE_UNREADABLE_MESSAGE = "This exists and you cannot read it yet. actions has the request to make.";
+export declare function explainRefusedRead(kind: 'agreement' | 'task' | 'chat' | 'artifact', id: string, env: CapabilityEnv): Promise<RefusedRead | null>;
 export declare const openCapability: CapabilityDefinition;
 export declare const accessExplainCapability: CapabilityDefinition;
 export declare const contextRequestCapability: CapabilityDefinition;

package/dist/capabilities/context.js

@@ -322,6 +322,32 @@ function presentOpenResult(result, env) {
         } : {}),
     };
 }
+export const RESOURCE_HIDDEN_MESSAGE = 'Not found, or not available to you. The two look the same.';
+export const RESOURCE_UNREADABLE_MESSAGE = 'This exists and you cannot read it yet. actions has the request to make.';
+export async function explainRefusedRead(kind, id, env) {
+    const creds = fullCreds(env);
+    let presented;
+    try {
+        const client = new ContextOpenClient(creds.operatorKey, creds.agentId, env.baseUrl, creds.laneId);
+        presented = presentOpenResult(await client.explain({ [`${kind}Id`]: id }), env);
+    }
+    catch {
+        return null;
+    }
+    const outcome = presented['outcome'];
+    if (outcome !== 'hidden' && outcome !== 'unreadable')
+        return null;
+    const actions = Array.isArray(presented['actions']) ? presented['actions'] : [];
+    return outcome === 'hidden'
+        ? { code: 'RESOURCE_HIDDEN', outcome, message: RESOURCE_HIDDEN_MESSAGE, ref: { kind, id } }
+        : {
+            code: 'RESOURCE_UNREADABLE',
+            outcome,
+            message: RESOURCE_UNREADABLE_MESSAGE,
+            ref: { kind, id },
+            ...(actions.length ? { actions } : {}),
+        };
+}
 export const openCapability = {
     key: 'open',
     names: { sdk: 'open', mcp: 'ziggs_open' },

package/dist/capabilities/discovery.js

@@ -1,4 +1,5 @@
 import { AgentSearchClient } from '../http/AgentSearchClient.js';
+import { RESOURCE_HIDDEN_MESSAGE } from './context.js';
 import { fullCreds } from './types.js';
 export const agentSearchCapability = {
     key: 'agent_search',
@@ -32,6 +33,8 @@ export const agentSearchCapability = {
         }
         const chatOpen = env.surface === 'mcp' ? 'ziggs_chat_open' : 'chat_open';
         const linkList = env.surface === 'mcp' ? 'ziggs_link_list' : 'link_list';
+        const marketplace = env.surface === 'mcp' ? 'ziggs_marketplace_view' : 'marketplace_view';
+        const request = env.surface === 'mcp' ? 'ziggs_agreement_request' : 'agreement_request';
         const people = result.people ?? [];
         const messageThem = people.length
             ? {
@@ -52,6 +55,10 @@ export const agentSearchCapability = {
                     'your org: people by name (returned under people, to message as people)',
                 ],
                 hint: 'Zero agents means no agent matched these terms; discovery itself is up. ' +
+                    // An agent given work to farm out stopped here with it undone. The
+                    // next rungs of the hiring ladder belong at the moment the search
+                    // comes back empty, not in a skill loaded every session.
+                    `To get work done, open listings and requests are in ${marketplace}; when nothing fits, post the work with ${request} so whoever can do it claims it. ` +
                     "People are not agents: a teammate is found by their name and comes back under people, never as their agents. " +
                     `To reach them, open a chat with that user id (${chatOpen} participantId). ` +
                     'Matching is lexical, so try shorter or different keywords. ' +
@@ -83,7 +90,13 @@ export const agentGetCapability = {
         const client = new AgentSearchClient(creds.operatorKey, creds.agentId);
         const result = await client.getAgentById(args['agentId']);
         if (!result.success) {
-            throw new Error(result.error ?? 'agent not found');
+            // A missing agent and one you may not see answer alike, in the words
+            // every read tool uses. There is nothing to request: an agent is reached
+            // through its listing or its person, not by access to its profile.
+            if (result.error === 'agent not found') {
+                throw Object.assign(new Error(RESOURCE_HIDDEN_MESSAGE), { code: 'RESOURCE_HIDDEN' });
+            }
+            throw new Error(result.error ?? 'Failed to get agent details');
         }
         const { success: _success, ...agent } = result;
         return { agent };

package/dist/capabilities/index.d.ts

@@ -1,7 +1,7 @@
 export { type CapabilitySurface, type CapabilityAnnotation, type CapabilityParam, type CapabilityEnv, type CapabilityDefinition, fullCreds, rethrowWithContext, } from './types.js';
 export { type McpBrief, type McpDoor, hasMcpBrief, mcpBriefNames, mcpDescription, } from './mcpBriefs.js';
 export { nextCall, nextCallsFromUntrustedContent, isStaleAdvertisedAction, peerPrincipalId, isPersonaFace, workContextFromEnv, type NextCall, type NextCallOutcome, type NextCallEffects, type NextCallHold, type NextCallOptions, type WorkContext, } from './nextCall.js';
-export { AGREEMENT_VERB_CAPABILITIES, LISTING_DOOR_CAPABILITIES, listingPauseCapability, listingResumeCapability, agreementBuyCapability, agreementBidCapability, agreementBrokerCapability, agreementRequestCapability, agreementOfferCapability, agreementHandoffCapability, agreementSubcontractCapability, } from './agreementVerbs.js';
+export { AGREEMENT_VERB_CAPABILITIES, LISTING_DOOR_CAPABILITIES, agreementBuyCapability, agreementBidCapability, agreementBrokerCapability, agreementRequestCapability, agreementHandoffCapability, agreementSubcontractCapability, } from './agreementVerbs.js';
 export { PAYMENT_CAPABILITIES, paymentBalanceCapability } from './payments.js';
 export { LINK_CAPABILITIES, listLinksCapability, proposeLinkCapability, linkIsReachOnly, } from './links.js';
 export { INTRODUCTION_CAPABILITIES, mintIntroductionCapability, redeemIntroductionCapability, listIntroductionsCapability, revokeIntroductionCapability, } from './introductions.js';
@@ -12,7 +12,7 @@ export { TASK_CAPABILITIES, listTasksCapability, cancelTaskCapability, presentTa
 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, openCapability, accessExplainCapability, contextDelegateCapability, contextRequestCapability, accessRequestCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, contextBounds, resolveOrgScopeId, } from './context.js';
+export { CONTEXT_CAPABILITIES, contextReadCapability, openCapability, accessExplainCapability, contextDelegateCapability, contextRequestCapability, accessRequestCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, contextBounds, resolveOrgScopeId, explainRefusedRead, RESOURCE_HIDDEN_MESSAGE, RESOURCE_UNREADABLE_MESSAGE, type RefusedRead, } from './context.js';
 export { CONNECTION_CAPABILITIES, connectionProxyCapability, requestConnectionCapability, } from './connections.js';
 export { DISCOVERY_CAPABILITIES, agentSearchCapability, agentGetCapability, } from './discovery.js';
 export { ARTIFACT_CAPABILITIES, recordArtifactCapability, listArtifactsCapability, findArtifactsCapability, type UnsearchedContext, shareArtifactCapability, attachArtifactCapability, uploadArtifactUrlCapability, completeArtifactFileCapability, downloadArtifactCapability, reextractArtifactCapability, } from './artifacts.js';

package/dist/capabilities/index.js

@@ -1,7 +1,7 @@
 export { fullCreds, rethrowWithContext, } from './types.js';
 export { hasMcpBrief, mcpBriefNames, mcpDescription, } from './mcpBriefs.js';
 export { nextCall, nextCallsFromUntrustedContent, isStaleAdvertisedAction, peerPrincipalId, isPersonaFace, workContextFromEnv, } from './nextCall.js';
-export { AGREEMENT_VERB_CAPABILITIES, LISTING_DOOR_CAPABILITIES, listingPauseCapability, listingResumeCapability, agreementBuyCapability, agreementBidCapability, agreementBrokerCapability, agreementRequestCapability, agreementOfferCapability, agreementHandoffCapability, agreementSubcontractCapability, } from './agreementVerbs.js';
+export { AGREEMENT_VERB_CAPABILITIES, LISTING_DOOR_CAPABILITIES, agreementBuyCapability, agreementBidCapability, agreementBrokerCapability, agreementRequestCapability, agreementHandoffCapability, agreementSubcontractCapability, } from './agreementVerbs.js';
 export { PAYMENT_CAPABILITIES, paymentBalanceCapability } from './payments.js';
 export { LINK_CAPABILITIES, listLinksCapability, proposeLinkCapability, linkIsReachOnly, } from './links.js';
 export { INTRODUCTION_CAPABILITIES, mintIntroductionCapability, redeemIntroductionCapability, listIntroductionsCapability, revokeIntroductionCapability, } from './introductions.js';
@@ -12,7 +12,7 @@ export { TASK_CAPABILITIES, listTasksCapability, cancelTaskCapability, presentTa
 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, openCapability, accessExplainCapability, contextDelegateCapability, contextRequestCapability, accessRequestCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, contextBounds, resolveOrgScopeId, } from './context.js';
+export { CONTEXT_CAPABILITIES, contextReadCapability, openCapability, accessExplainCapability, contextDelegateCapability, contextRequestCapability, accessRequestCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, contextBounds, resolveOrgScopeId, explainRefusedRead, RESOURCE_HIDDEN_MESSAGE, RESOURCE_UNREADABLE_MESSAGE, } from './context.js';
 export { CONNECTION_CAPABILITIES, connectionProxyCapability, requestConnectionCapability, } from './connections.js';
 export { DISCOVERY_CAPABILITIES, agentSearchCapability, agentGetCapability, } from './discovery.js';
 export { ARTIFACT_CAPABILITIES, recordArtifactCapability, listArtifactsCapability, findArtifactsCapability, shareArtifactCapability, attachArtifactCapability, uploadArtifactUrlCapability, completeArtifactFileCapability, downloadArtifactCapability, reextractArtifactCapability, } from './artifacts.js';

package/dist/capabilities/marketplace.js

@@ -7,8 +7,8 @@ const VIEW_KINDS = ['all', 'requests', 'offers'];
 function publishHint(env) {
     const claim = env.surface === 'mcp' ? 'ziggs_agreement_claim' : 'agreement_claim';
     const publish = env.surface === 'mcp'
-        ? 'Publish a request with ziggs_agreement_request (claimer works, you pay) or a standing offer with ziggs_agreement_offer (you work, claimer pays).'
-        : 'Publish your own via agreement_propose with proposedTo "everyone"/"org" (providerId = your id for an offer, omitted for a request).';
+        ? 'Post a request with ziggs_agreement_request (claimer works, you pay). A standing listing is published by a person or the deploy.'
+        : 'Post a request via agreement_propose with proposedTo "everyone"/"org" and no providerId. A standing listing is published by a person or the deploy.';
     return (`Reuse an active agreement that already covers the work. Otherwise claim any row with ${claim} ` +
         `(agreementId) — listings are take-it-or-leave-it, never counter one. ${publish}`);
 }

package/dist/capabilities/mcpBriefs.js

@@ -62,10 +62,6 @@ const BRIEFS = {
         does: 'Posts work you want done and will pay for: whoever claims it does the work.',
         changes: 'publishes a request others can claim',
     },
-    ziggs_agreement_offer: {
-        does: 'Publishes your listing: you provide, whoever claims it pays. Claimers take it as posted.',
-        changes: 'publishes it until revoked or sold out',
-    },
     ziggs_agreement_buy: {
         does: 'Proposes work to a named counterparty: they provide, you pay. Most published agents accept only claims of their listing.',
         changes: 'sends a proposal they approve, reject or counter',
@@ -102,14 +98,6 @@ const BRIEFS = {
         does: 'Ends an agreement you provide, for good, once its whole scope is delivered. A finished task closes with ziggs_task_set_result instead.',
         changes: 'revokes every grant it conferred; it cannot be reopened',
     },
-    ziggs_listing_pause: {
-        does: 'Stops new claims on a listing you publish; hires already sold keep running.',
-        changes: 'pauses it until ziggs_listing_resume',
-    },
-    ziggs_listing_resume: {
-        does: 'Reopens a listing you paused.',
-        changes: 'it takes new claims again',
-    },
     // Rooms
     ziggs_chat_list: {
         does: 'Lists rooms you hold a grant on, with last message and unread count. fields adds members or rosterSummary.',

package/dist/capabilities/proposeProviderId.d.ts

@@ -3,4 +3,4 @@
  * 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 request (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.";
+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 providerId to post a request (claimer works). A person or the deploy publishes a standing listing; this agent does not. Payer is always the non-providing side.";

package/dist/capabilities/proposeProviderId.js

@@ -3,4 +3,4 @@
  * 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 request (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.';
+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 providerId to post a request (claimer works). A person or the deploy publishes a standing listing; this agent does not. Payer is always the non-providing side.';

package/dist/http/ContextOpenClient.js

@@ -33,7 +33,9 @@ export class ContextOpenClient {
     async post(path, body) {
         const filled = ['artifactId', 'chatId', 'taskId', 'agreementId'].filter((key) => typeof body[key] === 'string' && body[key].trim());
         if (filled.length !== 1) {
-            throw new Error('ContextOpenClient: pass exactly one of artifactId, chatId, taskId, agreementId');
+            // A caller's input mistake, named in the caller's words: the shared
+            // INVALID_INPUT code, and no internal class name in the sentence.
+            throw Object.assign(new Error('Pass exactly one of artifactId, chatId, taskId, agreementId.'), { code: 'INVALID_INPUT' });
         }
         const url = `${this.baseUrl || getBackendUrl()}${path}`;
         const res = await fetch(url, {

package/dist/http/PaymentsClient.d.ts

@@ -90,11 +90,6 @@ export declare class PaymentsClient {
         holderId: string;
         caveats?: unknown;
     }): Promise<PaymentGrantEnvelope>;
-    attenuateGrant({ grantId, holderId, caveats, }: {
-        grantId: string;
-        holderId: string;
-        caveats?: unknown;
-    }): Promise<PaymentGrantEnvelope>;
     revokeGrant(grantId: string): Promise<RevokeGrantResult>;
     /**
      * Live wallet grants the acting agent holds, via the unified GET /grants

package/dist/http/PaymentsClient.js

@@ -79,12 +79,6 @@ export class PaymentsClient {
     async issueGrant({ holderId, caveats }) {
         return (await this._post('/payments/grants', { holderId, caveats }));
     }
-    async attenuateGrant({ grantId, holderId, caveats, }) {
-        return (await this._post(`/payments/grants/${grantId}/attenuate`, {
-            holderId,
-            caveats,
-        }));
-    }
     async revokeGrant(grantId) {
         return (await this._request('DELETE', `/payments/grants/${grantId}`, undefined));
     }

package/dist/http/operatorHeaders.d.ts

@@ -1,6 +1,11 @@
 type AssistantHints = {
     orgId?: string;
     resource?: string;
+    clientSessionId?: string;
+    instanceId?: string;
+    workspaceIds?: string;
+    app?: string;
+    sessionName?: string;
 };
 /** Node-only, opt-in request context. Ordinary HTTP clients remain browser-safe. */
 export declare function withAssistantRequest<T>(hints: AssistantHints, run: () => T): Promise<Awaited<T>>;

package/dist/http/operatorHeaders.js

@@ -6,11 +6,22 @@ export async function withAssistantRequest(hints, run) {
         assistantRequest = new AsyncLocalStorage();
         return assistantRequest;
     });
-    return await (await assistantContextLoading).run(hints, run);
+    const context = await assistantContextLoading;
+    // A workspace router adds its per-operation target inside the caller's
+    // session. Preserve that session without sharing it between concurrent calls.
+    return await context.run({ ...context.getStore(), ...hints, orgId: hints.orgId, resource: hints.resource }, run);
 }
 export function assistantRequestHeaders() {
     const hints = assistantRequest?.getStore();
-    return { ...(hints?.orgId ? { 'X-Workspace-Id': hints.orgId } : {}), ...(hints?.resource ? { 'X-Ziggs-Resource': hints.resource } : {}) };
+    return {
+        ...(hints?.orgId ? { 'X-Workspace-Id': hints.orgId } : {}),
+        ...(hints?.resource ? { 'X-Ziggs-Resource': hints.resource } : {}),
+        ...(hints?.clientSessionId ? { 'X-Ziggs-Session': hints.clientSessionId } : {}),
+        ...(hints?.instanceId ? { 'X-Ziggs-Instance': hints.instanceId } : {}),
+        ...(hints?.workspaceIds ? { 'X-Ziggs-Workspaces': hints.workspaceIds } : {}),
+        ...(hints?.app ? { 'X-Ziggs-App': hints.app } : {}),
+        ...(hints?.sessionName ? { 'X-Ziggs-Session-Name': hints.sessionName } : {}),
+    };
 }
 /**
  * Auth headers for operator-key HTTP clients.

package/dist/index.d.ts

@@ -7,6 +7,9 @@ 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';
+export type { RuntimeLogLevel } from './shared/runtimeLog.js';
+export { resolveDelegateCreds, resolveDelegateHttpUrl, } from './shared/delegateCreds.js';
+export type { DelegateEnv, ResolvedDelegateCreds, } from './shared/delegateCreds.js';
 export { RateLimitedError, isRateLimited, parseRetryAfterMs, pollSurfaceError, } from './shared/rateLimit.js';
 export { parseErrorMessage, parseErrorCode, throwApiError, } from './shared/apiError.js';
 export { ApiError } from './types.js';

package/dist/index.js

@@ -6,6 +6,7 @@ export { getBackendUrl } from './utils/urlUtils.js';
 // the host injects the environment; this package never reads it.
 export { configureApiClient, apiClientConfig } from './config.js';
 export { runtimeLog, resetRuntimeLogLevelCache } from './shared/runtimeLog.js';
+export { resolveDelegateCreds, resolveDelegateHttpUrl, } from './shared/delegateCreds.js';
 // one ApiError shape; 429s carry the server's wait.
 export { RateLimitedError, isRateLimited, parseRetryAfterMs, pollSurfaceError, } from './shared/rateLimit.js';
 // One reader for the one error shape the API answers in — exported so nothing has

package/dist/shared/delegateCreds.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The environment a delegate process was handed. Callers read the process;
+ * this module does not.
+ */
+export interface DelegateEnv {
+    ZIGGS_API_URL?: string;
+    HTTP_URL?: string;
+    ZIGGS_OPERATOR_KEY?: string;
+    ZIGGS_AGENT_ID?: string;
+}
+export interface ResolvedDelegateCreds {
+    /** `ZIGGS_API_URL` wins over `HTTP_URL`. Absent when neither is set. */
+    httpUrl?: string;
+    operatorKey: string;
+    /** Empty when the key is a directory connection (`connectionClientId`). */
+    agentId: string;
+}
+/** Which base URL this process was told to use. The specific name wins. */
+export declare function resolveDelegateHttpUrl(env: DelegateEnv): string | undefined;
+/**
+ * One reading of a delegate's key, agent, and base URL.
+ * An agent-scoped key supplies the agent id. A session JWT is refused.
+ */
+export declare function resolveDelegateCreds(env: DelegateEnv): ResolvedDelegateCreds;

package/dist/shared/delegateCreds.js

@@ -0,0 +1,44 @@
+import { decodeOperatorKeyClaims, isOperatorKeyExpired } from './operatorKey.js';
+const MINT = 'An MCP client that supports OAuth signs in at https://mcp.ziggsai.com/mcp. ' +
+    'To run with a key, issue one in the Ziggs app (Agent-only access, or Agents > Access keys). ' +
+    'Docs: https://ziggsai.com/docs#connect-assistant';
+/** Which base URL this process was told to use. The specific name wins. */
+export function resolveDelegateHttpUrl(env) {
+    const specific = env.ZIGGS_API_URL?.trim();
+    if (specific)
+        return specific;
+    const generic = env.HTTP_URL?.trim();
+    return generic || undefined;
+}
+/**
+ * One reading of a delegate's key, agent, and base URL.
+ * An agent-scoped key supplies the agent id. A session JWT is refused.
+ */
+export function resolveDelegateCreds(env) {
+    const operatorKey = env.ZIGGS_OPERATOR_KEY?.trim() ?? '';
+    if (!operatorKey) {
+        throw new Error(`ZIGGS_OPERATOR_KEY is required. ${MINT}`);
+    }
+    const claims = decodeOperatorKeyClaims(operatorKey);
+    if (claims?.type && claims.type !== 'operator') {
+        throw new Error(`ZIGGS_OPERATOR_KEY must be an operator token (not a session JWT). ${MINT}`);
+    }
+    if (isOperatorKeyExpired(claims)) {
+        throw new Error(`operator key expired (keyId=${claims?.keyId ?? 'unknown'}). ${MINT}`);
+    }
+    const httpUrl = resolveDelegateHttpUrl(env);
+    if (claims?.connectionClientId) {
+        return { httpUrl, operatorKey, agentId: '' };
+    }
+    const bound = claims?.boundAgentId?.trim() || '';
+    const fromEnv = env.ZIGGS_AGENT_ID?.trim() || '';
+    if (bound && fromEnv && bound !== fromEnv) {
+        throw new Error(`ZIGGS_AGENT_ID (${fromEnv}) conflicts with agent-scoped key bound to "${bound}". ` +
+            'Remove ZIGGS_AGENT_ID or use a fleet impersonation key instead.');
+    }
+    const agentId = bound || fromEnv;
+    if (!agentId) {
+        throw new Error(`set ZIGGS_AGENT_ID, or mint an agent-scoped operator key (boundAgentId in token). ${MINT}`);
+    }
+    return { httpUrl, operatorKey, agentId };
+}

package/dist/shared/runtimeLog.js

@@ -1,8 +1,7 @@
 /**
- * Same semantics as `@ziggs-ai/agent-sdk` `shared/runtimeLog.ts` (duplicated
- * here so this package stays dependency-free).
- *
- * @see agent-sdk/src/shared/runtimeLog.ts
+ * Process-wide log level for every package that imports this. The host sets it
+ * with `configureApiClient({ logLevel })`; this package does not read the
+ * environment. The SDK re-exports these names.
  */
 import { apiClientConfig, apiClientConfigVersion } from '../config.js';
 const SEVERITY = {

package/package.json

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