@ziggs-ai/agent-sdk 0.11.1 → 0.12.0

package/dist/server/ZiggsEffectHandler.js

@@ -15,7 +15,7 @@ const emptySnapshot = (agentId, chatMissing = false) => ({
     history: [],
     agreements: [],
     users: [],
-    agents: [{ agentId, role: 'self', isYou: true }],
+    agents: [{ agentId, role: 'self', isYou: true, kind: 'agent' }],
     latestSequence: null,
     ...(chatMissing ? { chatMissing: true } : {}),
 });
@@ -26,7 +26,11 @@ async function buildSnapshot(deps, chatId, agentId, opts = {}) {
         const snap = await deps.contextReadClient.snapshot(chatId, {
             maxMessages: opts.limit,
         });
-        return snap;
+        // Built rather than cast: the roster rows are typed on both sides now (they
+        // carry the declared participant kind), and only `history` is loose on the
+        // wire, so a whole-object cast would be asserting past the one field that
+        // actually needs it.
+        return { ...snap, history: snap.history };
     }
     catch (err) {
         // Defensive: server normally signals a dead chat as 200 + chatMissing, but

package/dist/server/agreements/AgreementService.d.ts

@@ -1,4 +1,4 @@
-import { type Agreement, type ClaimedKind, type ProposeAgreementData, type ProposeDirectInput, type ProposeBroadcastInput, type PublishOfferPayload, type DelegateAgreementData, type CounterAgreementData, type CreateAgreementBody, type ListAgreementsFilters, type GetMyAgreementsFilters, type ChatLinkType, type ArtifactLinkType, type UserRole } from '@ziggs-ai/api-client';
+import { type Agreement, type ClaimedKind, type ProposeAgreementData, type ProposeDirectInput, type ProposeBroadcastInput, type PublishOfferPayload, type DelegateAgreementData, type CounterAgreementData, type CreateLinkBody, type ListAgreementsFilters, type GetMyAgreementsFilters, type ChatLinkType, type ArtifactLinkType, type UserRole } from '@ziggs-ai/api-client';
 export declare class AgreementService {
     private creds;
     constructor(operatorKey: string, agentId: string);
@@ -20,7 +20,7 @@ export declare class AgreementService {
     delegate(payload: DelegateAgreementData): Promise<Agreement>;
     respond(agreementId: string, action: 'approve' | 'reject'): Promise<Agreement>;
     /**
-     * claim any open broadcast (quest, standing offer, hand-off,
+     * claim any open broadcast (request, standing offer, hand-off,
      * link invite). Routing (offer vs agreement claim endpoint) is decided in
      * the shared flow; `kind` is the api-client ClaimedKind so this signature
      * can't drift from the flow again (a 'hand-off' addition broke the build).
@@ -45,7 +45,12 @@ export declare class AgreementService {
      */
     mine(filters?: GetMyAgreementsFilters): Promise<Agreement[]>;
     get(agreementId: string): Promise<Agreement | null>;
-    create(body: CreateAgreementBody): Promise<{
+    /**
+     * Create a trust link — direct to one agent, or an open invite. Work
+     * agreements are created by `propose` / the marketplace claim routes, which
+     * run the term normalisation and consent gates this rail never had.
+     */
+    createLink(body: CreateLinkBody): Promise<{
         ok: boolean;
         agreement: Agreement;
     }>;

package/dist/server/agreements/AgreementService.js

@@ -1,4 +1,4 @@
-import { proposeAgreement, proposeBroadcast as proposeBroadcastApi, delegateAgreement, respondToAgreement, counterAgreement, claimOpenAgreement, getAgreementStatus, listAgreements, getMyAgreements, getAgreement, publishOffer as publishOfferApi, createAgreement, revokeAgreement, fulfillAgreement, linkAgreementToChat, getChatsForAgreement, linkArtifactToAgreement, getArtifactsForAgreement, linkUserToAgreement, getUsersForAgreement, } from '@ziggs-ai/api-client';
+import { proposeAgreement, proposeBroadcast as proposeBroadcastApi, delegateAgreement, respondToAgreement, counterAgreement, claimOpenAgreement, getAgreementStatus, listAgreements, getMyAgreements, getAgreement, publishOffer as publishOfferApi, createLink, revokeAgreement, fulfillAgreement, linkAgreementToChat, getChatsForAgreement, linkArtifactToAgreement, getArtifactsForAgreement, linkUserToAgreement, getUsersForAgreement, } from '@ziggs-ai/api-client';
 export class AgreementService {
     creds;
     constructor(operatorKey, agentId) {
@@ -38,7 +38,7 @@ export class AgreementService {
         return respondToAgreement(agreementId, action, this.creds);
     }
     /**
-     * claim any open broadcast (quest, standing offer, hand-off,
+     * claim any open broadcast (request, standing offer, hand-off,
      * link invite). Routing (offer vs agreement claim endpoint) is decided in
      * the shared flow; `kind` is the api-client ClaimedKind so this signature
      * can't drift from the flow again (a 'hand-off' addition broke the build).
@@ -51,7 +51,7 @@ export class AgreementService {
      * agent; the target owner approves. Folds the old request_link tool.
      */
     async requestLink(providerId, description) {
-        const { agreement } = await createAgreement({ engagementKind: 'link', providerId, ...(description ? { description } : {}) }, this.creds);
+        const { agreement } = await createLink({ targetAgentId: providerId, ...(description ? { description } : {}) }, this.creds);
         return agreement;
     }
     counter(agreementId, counter) {
@@ -75,8 +75,13 @@ export class AgreementService {
     get(agreementId) {
         return getAgreement(agreementId, this.creds);
     }
-    create(body) {
-        return createAgreement(body, this.creds);
+    /**
+     * Create a trust link — direct to one agent, or an open invite. Work
+     * agreements are created by `propose` / the marketplace claim routes, which
+     * run the term normalisation and consent gates this rail never had.
+     */
+    createLink(body) {
+        return createLink(body, this.creds);
     }
     revoke(agreementId) {
         return revokeAgreement(agreementId, this.creds);

package/dist/server/inboxLoop.d.ts

@@ -1,4 +1,4 @@
-import { type InboxQuestRef, type InboxTaskRef, type Creds } from '@ziggs-ai/api-client';
+import { type InboxRequestRef, type InboxTaskRef, type Creds } from '@ziggs-ai/api-client';
 import { SeenMessages } from './SeenMessages.js';
 /**
  * Per-agent inbox long-poll loop (delivery law, phase 4). This is the ONLY way
@@ -27,11 +27,11 @@ export interface InboxLoopDeps {
      */
     onTask?: (task: InboxTaskRef) => Promise<void>;
     /**
-     * A marketplace quest doorbell. The host MUST triage with a plain
+     * A marketplace request doorbell. The host MUST triage with a plain
      * string compare and return without an LLM wake on miss — otherwise every
-     * public quest burns a full Claude turn per published supplier.
+     * public request burns a full Claude turn per published supplier.
      */
-    onQuest?: (quest: InboxQuestRef) => Promise<void>;
+    onRequest?: (request: InboxRequestRef) => Promise<void>;
     label?: string;
 }
 export interface InboxPassResult {
@@ -41,8 +41,8 @@ export interface InboxPassResult {
     resourceEvents: number;
     /** Assigned open tasks delivered this pass. */
     tasksDelivered: number;
-    /** Quest refs triaged this pass — includes misses that only ack. */
-    questsTriaged: number;
+    /** Request refs triaged this pass — includes misses that only ack. */
+    requestsTriaged: number;
     /** True when the watermark advanced this pass. */
     acked: boolean;
     /** True when there was more mail than one envelope carries. */

package/dist/server/inboxLoop.js

@@ -83,7 +83,7 @@ export async function pollInboxOnce(deps, waitSeconds = 0, opts = {}) {
     let messagesDelivered = 0;
     let resourceEvents = 0;
     let tasksDelivered = 0;
-    let questsTriaged = 0;
+    let requestsTriaged = 0;
     let failures = 0;
     // a handover that failed must not be acked, and must not be
     // remembered as seen — otherwise the redelivery the held watermark buys is
@@ -107,10 +107,16 @@ export async function pollInboxOnce(deps, waitSeconds = 0, opts = {}) {
         // make a badly backed-up agent replay its whole backlog forever.
         warn(label, 'inbox deliveriesCapped (more mail than one envelope carries — the tail follows on the next pass)');
     }
-    // Oldest delivery per chat: where to start reading that chat's messages.
+    // The single-assign law: a row is MINE to act on iff it carries my stamp.
+    // Everything else in the merged view (a sibling carrier's mail, the owner's
+    // needs-human rows, granted ambient lanes) is context the host may read on
+    // demand — never a wake, never mine to ack as handled.
+    const mine = (d) => d.assigneeId === deps.ownAgentId;
+    // Oldest ASSIGNED delivery per chat: where to start reading that chat's
+    // messages. Ambient chat rows must not drag the read window earlier.
     const earliestByChat = new Map();
     for (const d of envelope.deliveries) {
-        if (!d.chatId)
+        if (!d.chatId || !mine(d))
             continue;
         const seen = earliestByChat.get(d.chatId);
         if (!seen || d.ts < seen)
@@ -126,10 +132,14 @@ export async function pollInboxOnce(deps, waitSeconds = 0, opts = {}) {
     // Everything that is not chat text is handed over as a resource event, from
     // the delivery itself — the reference already carries the ids the host needs,
     // so nothing has to be re-derived to name what changed.
-    // Quests must never take this path — even if a pre-cut server
+    // Requests must never take this path — even if a pre-cut server
     // left them in `deliveries`, skip so they cannot wake the LLM before triage.
+    // Unassigned rows never take it either: waking the brain on a sibling's
+    // mail is the N-wakes-per-event cost the party-owned inbox exists to kill.
     for (const d of envelope.deliveries) {
-        if (d.kind === 'message' || d.kind === 'quest')
+        if (d.kind === 'message' || d.kind === 'request')
+            continue;
+        if (!mine(d))
             continue;
         const key = `delivery:${d.kind}:${d.resourceId}:${d.ts}`;
         if (deps.seen.has(key))
@@ -169,26 +179,26 @@ export async function pollInboxOnce(deps, waitSeconds = 0, opts = {}) {
     if (envelope.truncatedTasks) {
         warn(label, `inbox truncatedTasks=${envelope.truncatedTasks} (more assigned tasks than one pass surfaces — they appear as earlier ones close)`);
     }
-    // quest channel. Triage is the host's job (exact string compare);
+    // request channel. Triage is the host's job (exact string compare);
     // a miss must still count as handled so the watermark can advance with 0 tokens.
-    for (const quest of envelope.questsAwaitingMe ?? []) {
-        const key = `quest:${quest.agreementId}:${quest.ts}`;
+    for (const request of envelope.requestsAwaitingMe ?? []) {
+        const key = `request:${request.agreementId}:${request.ts}`;
         if (deps.seen.has(key))
             continue;
         deps.seen.mark(key);
-        if (deps.onQuest) {
-            const handled = await attempt(`quest ${quest.agreementId}`, () => deps.onQuest(quest), () => deps.seen.unmark(key));
+        if (deps.onRequest) {
+            const handled = await attempt(`request ${request.agreementId}`, () => deps.onRequest(request), () => deps.seen.unmark(key));
             if (handled)
-                questsTriaged++;
+                requestsTriaged++;
         }
         else {
             // No handler → still count as handled (ack) so an old host cannot wedge
-            // forever on quest mail it does not understand.
-            questsTriaged++;
+            // forever on request mail it does not understand.
+            requestsTriaged++;
         }
     }
-    if (envelope.truncatedQuests) {
-        warn(label, `inbox truncatedQuests=${envelope.truncatedQuests} (more quests than one pass surfaces — the tail follows on the next pass)`);
+    if (envelope.truncatedRequests) {
+        warn(label, `inbox truncatedRequests=${envelope.truncatedRequests} (more requests than one pass surfaces — the tail follows on the next pass)`);
     }
     // Pending decisions are standing state, not deliveries: they keep appearing
     // until answered, so dedup them the same way tasks are deduped.
@@ -226,10 +236,13 @@ export async function pollInboxOnce(deps, waitSeconds = 0, opts = {}) {
             runtimeLog.error(label, `acking a window that failed ${failures} handover(s) — giving up on redelivery to keep the ` +
                 `agent alive; this mail is lost (ackTo=${envelope.ackTo})`);
         }
+        // Assigned rows only: the server's bury-guard checks what was MINE to
+        // handle. Ambient rows slide past the cursor unlisted — they were never
+        // this agent's to act on, and the owner's seen mark tracks them.
         const handledResourceIds = [
             ...new Set([
-                ...envelope.deliveries.map((d) => d.resourceId),
-                ...(envelope.questsAwaitingMe ?? []).map((q) => q.agreementId),
+                ...envelope.deliveries.filter(mine).map((d) => d.resourceId),
+                ...(envelope.requestsAwaitingMe ?? []).map((q) => q.agreementId),
             ]),
         ].filter((id) => typeof id === 'string' && id.length > 0);
         await inbox.ack(envelope.ackTo, { handledResourceIds });
@@ -245,7 +258,7 @@ export async function pollInboxOnce(deps, waitSeconds = 0, opts = {}) {
         messagesDelivered,
         resourceEvents,
         tasksDelivered,
-        questsTriaged,
+        requestsTriaged,
         acked,
         truncated: envelope.deliveriesCapped,
         failures,

package/dist/server/requestMatch.d.ts

@@ -0,0 +1,5 @@
+/**
+ * exact-match triage for marketplace requests.
+ * Empty match never hits (token-safe default). Comparison is exact after trim.
+ */
+export declare function requestExactMatch(match: string, tags: ReadonlyArray<string | null | undefined>): boolean;

package/dist/server/{questMatch.js → requestMatch.js}

@@ -1,8 +1,8 @@
 /**
- * exact-match triage for marketplace quests.
+ * exact-match triage for marketplace requests.
  * Empty match never hits (token-safe default). Comparison is exact after trim.
  */
-export function questExactMatch(match, tags) {
+export function requestExactMatch(match, tags) {
     const needle = typeof match === 'string' ? match.trim() : '';
     if (!needle)
         return false;

package/dist/server/runLauncher.js

@@ -5,6 +5,14 @@ import { boundKeyFleetWarning } from '../shared/operatorKeyClaims.js';
 import { runtimeLog } from '../shared/runtimeLog.js';
 import { PollRegistry } from './polls/PollKind.js';
 import { PollRunner } from './polls/PollRunner.js';
+/**
+ * How long a shutdown waits for in-flight turns after it has stopped taking new
+ * work. An agent turn is an LLM call, so the old 30s was under the length of the
+ * work it was meant to protect; the container's stop timeout is what has to be
+ * larger still, or the drain is cut short by SIGKILL regardless (ECS
+ * `stopTimeout`, 120s on the fleet task definitions).
+ */
+const DRAIN_TIMEOUT_MS = Number(process.env.FLEET_DRAIN_TIMEOUT_MS) || 90_000;
 /**
  * Collect the poll kinds the agents themselves ship and start a runner for
  * whatever they declared. This lives in the launcher, not in a caller's
@@ -57,7 +65,7 @@ async function runSingle(config, { operatorKey, label = 'agent', port = process.
         runtimeLog.info(label, 'SIGTERM — shutting down');
         pollRunner?.stop();
         agent.disconnect();
-        await agent.drain(30_000);
+        await agent.drain(DRAIN_TIMEOUT_MS);
         try {
             await onShutdown?.();
         }
@@ -122,10 +130,23 @@ async function runFleet(configs, { operatorKey, port = process.env.PORT || 8080,
     });
     process.on('SIGTERM', async () => {
         runtimeLog.info(label, 'SIGTERM — shutting down');
+        // Stop taking new work everywhere first, then wait for what is running.
+        //
+        // This used to disconnect and drain only `primary` — which `run.ts` never
+        // sets, so in the deployed fleet the drain was a no-op on null and the
+        // process exited straight through `disconnectAll`, killing every in-flight
+        // turn. A buyer whose request landed mid-rollout got a host that stopped
+        // mid-sentence and never reported.
+        //
+        // Draining before stopping intake is the other half of the same bug: the
+        // wait is exactly the window in which a host on its way out keeps accepting
+        // deliveries the incoming host is also being handed.
         pollRunner?.stop();
         primary?.disconnect?.();
-        await primary?.drain?.(30_000);
-        await pool.disconnectAll();
+        await Promise.all([
+            pool.shutdown(DRAIN_TIMEOUT_MS),
+            primary?.drain?.(DRAIN_TIMEOUT_MS) ?? Promise.resolve(),
+        ]);
         try {
             await onShutdown?.();
         }

package/dist/server/tools/index.d.ts

@@ -19,7 +19,7 @@ export { PROTOCOL_TOOLS, agreementProposeTool, agreementSubcontractTool, agreeme
 export { dispatchProtocolOp } from './tier1/protocolRunner.js';
 export { DISCOVERY_TOOLS, agentSearchTool, agentGetTool } from './tier2/discoveryTools.js';
 export { MARKETPLACE_TOOLS, marketplaceViewTool } from './tier2/marketplaceTools.js';
-export { PAYMENT_TOOLS, paymentBalanceTool, paymentTransferTool, paymentWaitForApprovalTool, paymentHoldTool, paymentReleaseTool, paymentResolveWalletTool, paymentIssueGrantTool, paymentAttenuateGrantTool, paymentRevokeGrantTool, } from './tier2/paymentTools.js';
+export { PAYMENT_TOOLS, paymentBalanceTool } from './tier2/paymentTools.js';
 export { CONNECTION_TOOLS, connectionProxyTool, connectionListGrantsTool, requestConnectionTool, } from './tier2/connectionTools.js';
 export { CONTEXT_TOOLS, contextReadTool, contextDelegateTool, contextExpandReachTool, contextDiscoverGrantableTool, } from './tier2/contextTools.js';
 export { GRANTS_TOOLS, listGrantsTool } from './tier2/grantsTools.js';

package/dist/server/tools/index.js

@@ -21,7 +21,7 @@ export { dispatchProtocolOp } from './tier1/protocolRunner.js';
 // ── Tier 2: capability bundles ──────────────────────────────────────────────
 export { DISCOVERY_TOOLS, agentSearchTool, agentGetTool } from './tier2/discoveryTools.js';
 export { MARKETPLACE_TOOLS, marketplaceViewTool } from './tier2/marketplaceTools.js';
-export { PAYMENT_TOOLS, paymentBalanceTool, paymentTransferTool, paymentWaitForApprovalTool, paymentHoldTool, paymentReleaseTool, paymentResolveWalletTool, paymentIssueGrantTool, paymentAttenuateGrantTool, paymentRevokeGrantTool, } from './tier2/paymentTools.js';
+export { PAYMENT_TOOLS, paymentBalanceTool } from './tier2/paymentTools.js';
 export { CONNECTION_TOOLS, connectionProxyTool, connectionListGrantsTool, requestConnectionTool, } from './tier2/connectionTools.js';
 export { CONTEXT_TOOLS, contextReadTool, contextDelegateTool, contextExpandReachTool, contextDiscoverGrantableTool, } from './tier2/contextTools.js';
 // one grant lister across every rail (retires context_discover +

package/dist/server/tools/tier1/protocolRunner.js

@@ -63,7 +63,7 @@ cachedAgreements) {
                 return null;
             return agreementService.respond(payload.agreementId, payload.action);
         case 'agreement-claim': {
-            // the one claim verb — quest, standing offer, or link invite.
+            // the one claim verb — request, standing offer, or link invite.
             if (!payload.agreementId)
                 throw new Error('agreement-claim requires `agreementId`');
             return await agreementService.claim(payload.agreementId);
@@ -240,7 +240,7 @@ async function proposeAgreement(services, payload, chatId, _agents, actingAgentI
                 audience: payload.proposedTo === 'org' ? 'org' : 'everyone',
             });
         }
-        throw new Error('On a broadcast, providerId must be your own agent id (a standing offer) or omitted (a quest — the claiming agent fills the open side).');
+        throw new Error('On a broadcast, providerId must be your own agent id (a standing offer) or omitted (a request — the claiming agent fills the open side).');
     }
     const priced = applyFleetPricingForProtocol('agreement-propose', payload, actingAgentId);
     const { operation: _op, ...fields } = priced;

package/dist/server/tools/tier1/protocolTools.js

@@ -43,10 +43,10 @@ function handlerFor(toolName) {
         return result;
     };
 }
-export const agreementProposeTool = defineTool('agreement_propose', { description: { type: 'string', required: true }, proposedTo: { type: 'string', required: true }, engagementKind: { type: 'string', enum: ['hire', 'service'], description: 'Contract type. Defaults to service. For a bilateral trust link, use link_propose.' }, parentAgreementId: 'string', providerId: { type: 'string', description: AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION }, price: { type: 'number', description: 'Amount in CENTS — 500 means $5.00, shown as ϟ5.00 in the UI. Convert both ways: a human asking for "ϟ2" or "$2 per task" means 200, not 2. ϟ is the currency symbol, not a cent.' }, lifecycle: lifecycleParam, expiresAt: 'string', maxExecutions: 'integer', billing: { type: 'string', enum: ['total', 'per_task'], description: "How price reads: 'total' (default, escrowed and paid at the end) or 'per_task' (a rate settled as each task completes — standing agreements only, and the default for a hire)." }, agreementDescription: 'string' }, handlerFor('agreement_propose'), { description: 'Propose an agreement — direct, broadcast, or link; there are no separate publish tools. Engagement precedence (posted-first): 1) REUSE an active agreement on matching terms, 2) CLAIM the counterparty\'s listing (marketplace_view → agreement_claim; never counter a listing), 3) POST a quest broadcast here when nothing listed fits, 4) direct-propose ONLY for bespoke terms, renegotiation, or commissioning a named counterparty with no listing — most published agents are claim-only and refuse direct proposals with a pointer at their listing. Direction is stated, never guessed: providerId = your own id ("I work, you pay") or providerId = proposedTo ("you work, I pay") on direct proposals. Broadcast with proposedTo="everyone" (fully public) or "org" (your org only): no providerId publishes a QUEST any agent may claim; providerId = your own id publishes a STANDING OFFER (claiming is agreement_claim; browsing is marketplace_view). For a bilateral trust link, use link_propose (or link_create_invite when you lack the agent id). engagementKind defaults to service. Agreements are STANDING by default (no expiry, unlimited tasks under one agreement); set expiresAt or maxExecutions only when the engagement should end on its own.', isAgreementCreation: true });
-export const agreementSubcontractTool = defineTool('agreement_subcontract', { description: { type: 'string', required: true }, executorId: { type: 'string', required: true }, parentAgreementId: { type: 'string', required: true }, payerId: 'string', price: { type: 'number', description: 'Amount in CENTS — 500 means $5.00, shown as ϟ5.00 in the UI. Convert both ways: a human asking for "ϟ2" or "$2 per task" means 200, not 2. ϟ is the currency symbol, not a cent.' }, lifecycle: lifecycleParam, expiresAt: 'string', maxExecutions: 'integer', agreementDescription: 'string' }, handlerFor('agreement_subcontract'), { description: 'Delegate work to another agent under an existing parent agreement. Requires parentAgreementId.', isAgreementCreation: true });
-export const agreementRespondTool = defineTool('agreement_respond', { agreementId: { type: 'string', required: true }, action: { type: 'string', required: true, enum: ['approve', 'reject'] } }, handlerFor('agreement_respond'), { description: 'Approve or reject a pending DIRECT agreement proposal addressed to you. Open broadcasts (quests, standing offers, link invites) have no personal approval slot — claim those with agreement_claim instead, or ignore them to pass. ONE exception: a hand-off that pins YOU as provider carries your pending approval even as an open broadcast — approving consents to serving whoever claims it (the row stays open for claims); rejecting cancels the hand-off. Ignoring it leaves the hand-off unclaimable, so always respond.' });
-export const agreementClaimTool = defineTool('agreement_claim', { agreementId: { type: 'string', required: true, description: 'The open agreement to claim (quest / offer / link invite id)' } }, handlerFor('agreement_claim'), { description: '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.' });
+export const agreementProposeTool = defineTool('agreement_propose', { description: { type: 'string', required: true }, proposedTo: { type: 'string', required: true }, engagementKind: { type: 'string', enum: ['hire', 'service'], description: 'Contract type. Defaults to service. For a bilateral trust link, use link_propose.' }, parentAgreementId: 'string', providerId: { type: 'string', description: AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION }, price: { type: 'number', description: 'Price in POINTS, as an integer of hundredths — 500 means ϟ5.00. Convert both ways: a human asking for "ϟ2 per task" means 200, not 2. ϟ is the points symbol, not a hundredth.' }, lifecycle: lifecycleParam, expiresAt: 'string', maxExecutions: 'integer', billing: { type: 'string', enum: ['total', 'per_task'], description: "How price reads: 'total' (default, escrowed and paid at the end) or 'per_task' (a rate settled as each task completes — standing agreements only, and the default for a hire)." }, agreementDescription: 'string' }, handlerFor('agreement_propose'), { description: 'Propose an agreement — direct, broadcast, or link; there are no separate publish tools. Engagement precedence (posted-first): 1) REUSE an active agreement on matching terms, 2) CLAIM the counterparty\'s listing (marketplace_view → agreement_claim; never counter a listing), 3) POST a request broadcast here when nothing listed fits, 4) direct-propose ONLY for bespoke terms, renegotiation, or commissioning a named counterparty with no listing — most published agents are claim-only and refuse direct proposals with a pointer at their listing. Direction is stated, never guessed: providerId = your own id ("I work, you pay") or providerId = proposedTo ("you work, I pay") on direct proposals. Broadcast with proposedTo="everyone" (fully public) or "org" (your org only): no providerId publishes a REQUEST any agent may claim; providerId = your own id publishes a STANDING OFFER (claiming is agreement_claim; browsing is marketplace_view). For a bilateral trust link, use link_propose (or link_create_invite when you lack the agent id). engagementKind defaults to service. Agreements are STANDING by default (no expiry, unlimited tasks under one agreement); set expiresAt or maxExecutions only when the engagement should end on its own.', isAgreementCreation: true });
+export const agreementSubcontractTool = defineTool('agreement_subcontract', { description: { type: 'string', required: true }, executorId: { type: 'string', required: true }, parentAgreementId: { type: 'string', required: true }, payerId: 'string', price: { type: 'number', description: 'Price in POINTS, as an integer of hundredths — 500 means ϟ5.00. Convert both ways: a human asking for "ϟ2 per task" means 200, not 2. ϟ is the points symbol, not a hundredth.' }, lifecycle: lifecycleParam, expiresAt: 'string', maxExecutions: 'integer', agreementDescription: 'string' }, handlerFor('agreement_subcontract'), { description: 'Delegate work to another agent under an existing parent agreement. Requires parentAgreementId.', isAgreementCreation: true });
+export const agreementRespondTool = defineTool('agreement_respond', { agreementId: { type: 'string', required: true }, action: { type: 'string', required: true, enum: ['approve', 'reject'] } }, handlerFor('agreement_respond'), { description: 'Approve or reject a pending DIRECT agreement proposal addressed to you. Open broadcasts (requests, standing offers, link invites) have no personal approval slot — claim those with agreement_claim instead, or ignore them to pass. ONE exception: a hand-off that pins YOU as provider carries your pending approval even as an open broadcast — approving consents to serving whoever claims it (the row stays open for claims); rejecting cancels the hand-off. Ignoring it leaves the hand-off unclaimable, so always respond.' });
+export const agreementClaimTool = defineTool('agreement_claim', { agreementId: { type: 'string', required: true, description: 'The open agreement to claim (request / offer / link invite id)' } }, handlerFor('agreement_claim'), { description: 'Claim an open broadcast agreement by id — the DEFAULT way to engage: terms are already posted, consent is the claim, activation is instant, no negotiation turns. Claims a request (you do the work, the publisher pays), a standing offer (you buy, the publisher works), a hand-off (providerPinned: the publisher\'s hired agent works FOR you — you become the customer, and the payer when it is priced), or a link invite (bilateral trust forms immediately). You become the open party and the agreement activates. A hand-off is claimable only after its provider has accepted (409 until then). Find requests/offers with marketplace_view; listings are take-it-or-leave-it — never counter one. Direct proposals are approved with agreement_respond instead, not claimed.' });
 export const taskSetResultTool = defineTool('task_set_result', {
     taskId: { type: 'string', required: true },
     // same param name as MCP ziggs_task_set_result / PATCH /tasks/:id/state.
@@ -54,10 +54,10 @@ export const taskSetResultTool = defineTool('task_set_result', {
     // Same object contract as MCP ({ summary, status, links, … }).
     result: {
         type: 'object',
-        description: 'Outcome payload (summary, status, links, …). Finished work is the task result — never a chat message.',
+        description: 'Outcome payload (summary, status, links, …). This is what the next agent reads when it picks the work up from its own inbox.',
     },
-}, handlerFor('task_set_result'), { description: 'Transition a task to its terminal state — completed, failed, or cancelled — and record the result. Finished work is the task result: set it here as an object ({ summary, status, links }), never as a chat message. Pass state (not status).' });
-export const agreementCounterTool = defineTool('agreement_counter', { agreementId: { type: 'string', required: true }, price: { type: 'number', description: 'Amount in CENTS — 500 means $5.00, shown as ϟ5.00 in the UI. Convert both ways: a human asking for "ϟ2" or "$2 per task" means 200, not 2. ϟ is the currency symbol, not a cent.' }, agreementDescription: 'string', expiresAt: 'string', lifecycle: lifecycleParam, maxExecutions: 'integer', description: 'string' }, handlerFor('agreement_counter'), { description: 'Counter a pending proposal with revised terms instead of approving or rejecting. Check status first with agreement_get.' });
+}, handlerFor('task_set_result'), { description: 'Transition a task to its terminal state — completed, failed, or cancelled — and record the result. Set the result here as an object ({ summary, status, links }): a task the parties opted into is closed by this call, whatever else you also sent them. Pass state (not status).' });
+export const agreementCounterTool = defineTool('agreement_counter', { agreementId: { type: 'string', required: true }, price: { type: 'number', description: 'Price in POINTS, as an integer of hundredths — 500 means ϟ5.00. Convert both ways: a human asking for "ϟ2 per task" means 200, not 2. ϟ is the points symbol, not a hundredth.' }, agreementDescription: 'string', expiresAt: 'string', lifecycle: lifecycleParam, maxExecutions: 'integer', description: 'string' }, handlerFor('agreement_counter'), { description: 'Counter a pending proposal with revised terms instead of approving or rejecting. Check status first with agreement_get.' });
 export const agreementGetTool = defineTool('agreement_get', { agreementId: { type: 'string', required: true } }, handlerFor('agreement_get'), { description: 'Read the current proposal status for an agreement (pending, approved, rejected, countered, expired).' });
 export const agreementRevokeTool = defineTool('agreement_revoke', { agreementId: { type: 'string', required: true } }, handlerFor('agreement_revoke'), { description: 'Revoke a pending proposal you created so it can no longer be approved. Use when the user has clearly moved on to a different request before responding to the previous proposal card.' });
 export const agreementFulfillTool = defineTool('agreement_fulfill', { agreementId: { type: 'string', required: true } }, handlerFor('agreement_fulfill'), { description: 'END an agreement you provide — permanently. Fulfilling terminates the whole relationship, not one deliverable: every grant it conferred is revoked, its shared space is torn down, and it cannot be reopened. Finished WORK is reported via task_set_result (the task closes; the agreement stays standing for the next task). Only fulfill when the engagement\'s full scope is delivered and nothing more is expected — never a standing hire that just finished a task.' });

package/dist/server/tools/tier2/marketplaceTools.js

@@ -1,9 +1,9 @@
 import { MARKETPLACE_CAPABILITIES, marketplaceViewCapability } from '@ziggs-ai/api-client';
 import { toolFromCapability, toolsFromCapabilities } from '../../../tools/capabilityAdapter.js';
-// the marketplace read (quests AND standing offers),
+// the marketplace read (requests AND standing offers),
 // defined once in api-client's shared capability layer. Publishing is NOT
 // here: it is the tier-1 verb agreement_propose with proposedTo
-// "everyone" | "org" (providerId = own id for an offer, omitted for a quest);
+// "everyone" | "org" (providerId = own id for an offer, omitted for a request);
 // claiming is agreement_claim.
 export const marketplaceViewTool = toolFromCapability(marketplaceViewCapability);
 export const MARKETPLACE_TOOLS = toolsFromCapabilities(MARKETPLACE_CAPABILITIES);

package/dist/server/tools/tier2/mcpConnectionTools.d.ts

@@ -1,4 +1,37 @@
 import { type ToolDefinition } from '../../../tools/defineTool.js';
 export declare const mcpToolsListTool: ToolDefinition;
+/**
+ * How much of one MCP tool result a wake will carry.
+ *
+ * A remote MCP server hands back the upstream API's payload verbatim, and those
+ * are sized for programs, not for a context window: GitHub's `list_pull_requests`
+ * with no paging argument answered ~150,000 characters. Past the runtime's limit
+ * the result stops being a result — the Claude SDK spills an oversized tool
+ * result to a file, and a hosted agent has no filesystem tool to read it with, so
+ * the wake ends in "the answer was too big and I cannot see it". Same class of
+ * problem as an MCP server that ships a 30K-character tool description, one layer
+ * later.
+ *
+ * A bounded answer with a marker beats an unreadable one: the model can act on
+ * "truncated, narrow the call", and it cannot act on a file path.
+ */
+export declare const MAX_MCP_RESULT_CHARS = 24000;
+/**
+ * Tool schemas are bigger than tool results and are read once per wake, so they
+ * get their own, larger ceiling — a schema cut in half is worse than useless,
+ * because the half that survives looks complete.
+ */
+export declare const MAX_MCP_TOOLS_LIST_CHARS = 60000;
+/**
+ * Bound one MCP result, telling the model plainly what was cut.
+ *
+ * Text blocks are cut individually rather than the JSON being sliced, because a
+ * sliced JSON string is invalid and a model handed invalid JSON reports the
+ * server as broken.
+ */
+export declare function boundMcpResult(result: unknown, max?: number): {
+    result: unknown;
+    truncated?: Record<string, unknown>;
+};
 export declare const mcpToolCallTool: ToolDefinition;
 export declare const MCP_CONNECTION_TOOLS: ToolDefinition[];

package/dist/server/tools/tier2/mcpConnectionTools.js

@@ -89,19 +89,145 @@ export const mcpToolsListTool = defineTool('mcp_tools_list', {
         type: 'string',
         description: 'Grant to use. Omit to use the live grant found on that connection.',
     },
+    names: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Tool names to return the FULL parameters (inputSchema) for. Omit to get the names and descriptions only — a whole server of schemas is tens of thousands of characters and gets cut, which is worse than not asking.',
+    },
 }, async (args, ctx) => {
     const t = await resolveTarget(ctx, args['connectionId'], args['grantId']);
+    /**
+     * Names first, schemas on demand — the same two-step this platform's own MCP
+     * surface settled on. One Linear server answers 53 tools and 78,000
+     * characters of schema; asking for all of it fills a wake with parameters for
+     * tools the agent will not call, and the cut lands mid-schema where the half
+     * that survives still looks complete.
+     */
+    const wanted = args['names']?.filter((n) => typeof n === 'string' && n);
     const tools = await withClient(ctx, t.connectionId, t.grantId, async (c) => {
         const res = await c.listTools();
-        return (res.tools ?? []).map((tool) => ({
+        const rows = res.tools ?? [];
+        const picked = wanted?.length ? rows.filter((tool) => wanted.includes(tool.name)) : rows;
+        return picked.map((tool) => ({
             name: tool.name,
             description: tool.description ?? null,
+            /**
+             * The parameters, which this used to drop.
+             *
+             * Without them an agent has to GUESS what a tool takes, and a guessed
+             * argument is not an error — most servers ignore what they do not know
+             * and answer with an empty list. That empty list then reads as "nothing
+             * happened": a weekly digest reported one item shipped for a week with
+             * fifty, because `status`, `filter.state.name` and `updatedAfter` were
+             * all invented and all silently matched nothing.
+             */
+            ...(wanted?.length ? { inputSchema: tool.inputSchema ?? null } : {}),
         }));
     });
-    return { connectionId: t.connectionId, grantId: t.grantId, tools };
+    const missing = wanted?.filter((n) => !tools.some((row) => row.name === n)) ?? [];
+    const bounded = boundMcpResult({ tools }, MAX_MCP_TOOLS_LIST_CHARS);
+    return {
+        connectionId: t.connectionId,
+        grantId: t.grantId,
+        ...bounded.result,
+        ...(bounded.truncated ? { truncated: bounded.truncated } : {}),
+        ...(missing.length ? { notFound: missing } : {}),
+        ...(wanted?.length
+            ? {}
+            : {
+                note: 'Names and descriptions only. Call again with names:["<tool>"] to get that tool\'s parameters before you pass any arguments — a parameter the server does not declare is usually ignored, and the empty result reads as real emptiness.',
+            }),
+    };
 }, {
-    description: "List the tools a connected MCP server exposes, through the Ziggs gateway — the owner's credential stays server-side. The grant may allow only some of them; a call outside the grant is refused by the gateway, not by you.",
+    description: "List the tools a connected MCP server exposes, through the Ziggs gateway. Names and descriptions by default; pass names:[\"<tool>\"] for those tools' full parameters (inputSchema) — the owner's credential stays server-side. Read the schema before calling a tool with arguments: a parameter the server does not declare is usually ignored rather than rejected, so a guessed filter comes back as an empty result that looks like real emptiness. The grant may allow only some tools; a call outside it is refused by the gateway, not by you.",
 });
+/**
+ * How much of one MCP tool result a wake will carry.
+ *
+ * A remote MCP server hands back the upstream API's payload verbatim, and those
+ * are sized for programs, not for a context window: GitHub's `list_pull_requests`
+ * with no paging argument answered ~150,000 characters. Past the runtime's limit
+ * the result stops being a result — the Claude SDK spills an oversized tool
+ * result to a file, and a hosted agent has no filesystem tool to read it with, so
+ * the wake ends in "the answer was too big and I cannot see it". Same class of
+ * problem as an MCP server that ships a 30K-character tool description, one layer
+ * later.
+ *
+ * A bounded answer with a marker beats an unreadable one: the model can act on
+ * "truncated, narrow the call", and it cannot act on a file path.
+ */
+export const MAX_MCP_RESULT_CHARS = 24_000;
+/**
+ * Tool schemas are bigger than tool results and are read once per wake, so they
+ * get their own, larger ceiling — a schema cut in half is worse than useless,
+ * because the half that survives looks complete.
+ */
+export const MAX_MCP_TOOLS_LIST_CHARS = 60_000;
+const TRUNCATION_ADVICE = 'Narrow the call instead of repeating it: most servers take paging (perPage/page) ' +
+    'or filter arguments, and a named target usually has a narrower tool than a list.';
+/**
+ * Bound one MCP result, telling the model plainly what was cut.
+ *
+ * Text blocks are cut individually rather than the JSON being sliced, because a
+ * sliced JSON string is invalid and a model handed invalid JSON reports the
+ * server as broken.
+ */
+export function boundMcpResult(result, max = MAX_MCP_RESULT_CHARS) {
+    const whole = JSON.stringify(result) ?? '';
+    if (whole.length <= max)
+        return { result };
+    const content = result?.content;
+    if (!Array.isArray(content)) {
+        return {
+            result: { text: whole.slice(0, max) },
+            truncated: {
+                originalChars: whole.length,
+                keptChars: max,
+                note: `Result was ${whole.length} characters and is cut to ${max}. ${TRUNCATION_ADVICE}`,
+            },
+        };
+    }
+    const kept = [];
+    let used = 0;
+    let dropped = 0;
+    for (const block of content) {
+        const text = block?.text;
+        if (typeof text !== 'string') {
+            const size = (JSON.stringify(block) ?? '').length;
+            if (used + size > max) {
+                dropped += 1;
+                continue;
+            }
+            used += size;
+            kept.push(block);
+            continue;
+        }
+        const room = max - used;
+        if (room <= 0) {
+            dropped += 1;
+            continue;
+        }
+        if (text.length <= room) {
+            used += text.length;
+            kept.push(block);
+            continue;
+        }
+        kept.push({
+            ...block,
+            text: `${text.slice(0, room)}\n\n[…cut here: this block was ${text.length} characters]`,
+        });
+        used = max;
+    }
+    return {
+        result: { ...result, content: kept },
+        truncated: {
+            originalChars: whole.length,
+            keptChars: used,
+            droppedBlocks: dropped,
+            note: `Result was ${whole.length} characters, over the ${max}-character limit, so it is cut. What you have is the beginning, not the whole answer — do not report it as complete. ${TRUNCATION_ADVICE}`,
+        },
+    };
+}
 export const mcpToolCallTool = defineTool('mcp_tool_call', {
     tool: {
         type: 'string',
@@ -125,12 +251,18 @@ export const mcpToolCallTool = defineTool('mcp_tool_call', {
     if (!name)
         throw new Error('tool is required');
     const t = await resolveTarget(ctx, args['connectionId'], args['grantId']);
-    const result = await withClient(ctx, t.connectionId, t.grantId, (c) => c.callTool({
+    const raw = await withClient(ctx, t.connectionId, t.grantId, (c) => c.callTool({
         name,
         arguments: args['args'] ?? {},
     }));
-    return { connectionId: t.connectionId, tool: name, result };
+    const bounded = boundMcpResult(raw);
+    return {
+        connectionId: t.connectionId,
+        tool: name,
+        result: bounded.result,
+        ...(bounded.truncated ? { truncated: bounded.truncated } : {}),
+    };
 }, {
-    description: "Call one tool on a connected MCP server through the Ziggs gateway. Use this for a connection whose provider is a remote MCP server — connection_proxy is for named connectors (github, jira) and refuses these with \"Unknown provider: mcp\". The gateway injects the owner's token upstream and checks the tool name against your grant, so you never hold the credential. Discover names with mcp_tools_list, or read allowed_actions off the grant in grant_list.",
+    description: "Call one tool on a connected MCP server through the Ziggs gateway. Use this for a connection whose provider is a remote MCP server — connection_proxy is for named connectors (github, jira) and refuses these with \"Unknown provider: mcp\". The gateway injects the owner's token upstream and checks the tool name against your grant, so you never hold the credential. Discover names with mcp_tools_list, or read allowed_actions off the grant in grant_list. Results are bounded: a payload over the limit comes back cut, with a `truncated` field saying so — pass the server's paging or filter arguments rather than repeating the call.",
 });
 export const MCP_CONNECTION_TOOLS = [mcpToolsListTool, mcpToolCallTool];

package/dist/server/tools/tier2/paymentTools.d.ts

@@ -1,11 +1,3 @@
 import type { ToolDefinition } from '../../../tools/defineTool.js';
 export declare const paymentBalanceTool: ToolDefinition;
-export declare const paymentTransferTool: ToolDefinition;
-export declare const paymentWaitForApprovalTool: ToolDefinition;
-export declare const paymentHoldTool: ToolDefinition;
-export declare const paymentReleaseTool: ToolDefinition;
-export declare const paymentResolveWalletTool: ToolDefinition;
-export declare const paymentIssueGrantTool: ToolDefinition;
-export declare const paymentAttenuateGrantTool: ToolDefinition;
-export declare const paymentRevokeGrantTool: ToolDefinition;
 export declare const PAYMENT_TOOLS: ToolDefinition[];