@ziggs-ai/agent-sdk 0.14.0 → 0.16.1

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

@@ -1,4 +1,4 @@
-import { isBroadcastTarget, partyActorIds, } from '@ziggs-ai/api-client';
+import { isBroadcastTarget, partyActorIds, presentClaimResult, } from '@ziggs-ai/api-client';
 import { applyFleetCounterPricing, applyFleetPricingForProtocol, } from '../../../pricing/fleetDefaults.js';
 // the link-summary rule lives in AgreementClient, at the point the
 // document is parsed. Every verb here inherits it through the client instead of
@@ -71,11 +71,16 @@ cachedAgreements) {
             // claim; it does not re-parent the row, which stays in the publisher's
             // tree.
             const declaredMandate = payload.mandateAgreementId;
-            return await agreementService.claim(payload.agreementId, {
+            const { agreement, kind } = await agreementService.claim(payload.agreementId, {
                 ...(typeof declaredMandate === 'string' && declaredMandate
                     ? { mandateAgreementId: declaredMandate }
                     : {}),
             });
+            return presentClaimResult(agreement, kind, {
+                creds: { operatorKey: 'sdk', agentId: actorId ?? 'agent' },
+                surface: 'sdk',
+                webUrl: process.env.ZIGGS_WEB_URL,
+            });
         }
         case 'agreement-counter-proposal':
             if (!payload.agreementId)
@@ -221,38 +226,16 @@ async function proposeAgreement(services, payload, chatId, _agents, actingAgentI
         throw new Error('agreement-propose requires `description`');
     if (!payload.proposedTo)
         throw new Error('agreement-propose requires `proposedTo` (userId or agentId). To create a task under an existing agreement, use `task_create` instead.');
-    const isBroadcast = isBroadcastTarget(payload.proposedTo);
     // a link proposal is an agreement with engagementKind 'link' —
     // no chat, no money; the target owner approves. Folds the old request_link.
+    // The shared propose grammar no longer has a link arm (link_propose owns it).
     if (payload.engagementKind === 'link') {
-        if (isBroadcast) {
+        if (isBroadcastTarget(payload.proposedTo)) {
             throw new Error('A broadcast link is an invite — use link_propose with no target instead; it returns a share link.');
         }
         return services.agreementService.requestLink(payload.proposedTo, payload.description);
     }
-    if (!isBroadcast && !payload.providerId) {
-        throw new Error('agreement-propose requires `providerId` — name who does the work: your own id (you are offering to work) or the proposedTo id (you are commissioning the recipient).');
-    }
-    if (isBroadcast && payload.providerId) {
-        // providerId = self on a broadcast publishes a STANDING OFFER
-        // (seller side open to any claimer). Any other providerId stays an error.
-        if (actingAgentId && payload.providerId === actingAgentId) {
-            const priced = applyFleetPricingForProtocol('agreement-propose', payload, actingAgentId);
-            return services.agreementService.publishOffer({
-                description: String(priced.description ?? ''),
-                price: typeof priced.price === 'number' ? priced.price : undefined,
-                lifecycle: typeof priced.lifecycle === 'string' ? priced.lifecycle : undefined,
-                expiresAt: typeof priced.expiresAt === 'string' ? priced.expiresAt : undefined,
-                maxExecutions: typeof priced.maxExecutions === 'number' ? priced.maxExecutions : undefined,
-                engagementKind: priced.engagementKind === 'hire' ? 'hire' : priced.engagementKind === 'service' ? 'service' : undefined,
-                billing: priced['billing'] === 'per_task' ? 'per_task' : priced['billing'] === 'total' ? 'total' : undefined,
-                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 request — the claiming agent fills the open side).');
-    }
     const priced = applyFleetPricingForProtocol('agreement-propose', payload, actingAgentId);
-    const { operation: _op, ...fields } = priced;
     // Wake-derived idempotency key (delivery law): a crash-replay re-issuing this
     // propose resolves to the already-created agreement server-side instead of
     // minting a duplicate proposal. Keyed on what the proposal writes, so
@@ -263,7 +246,30 @@ async function proposeAgreement(services, payload, chatId, _agents, actingAgentI
         description: payload.description,
         parentAgreementId: payload.parentAgreementId,
     });
-    return services.agreementService.propose({ ...fields, chatId, idempotencyKey });
+    const engagementKind = priced.engagementKind === 'hire' || priced.engagementKind === 'service'
+        ? priced.engagementKind
+        : undefined;
+    const billing = priced['billing'] === 'per_task' || priced['billing'] === 'total'
+        ? priced['billing']
+        : undefined;
+    const { agreement, shape } = await services.agreementService.proposeUnified({
+        proposedTo: priced.proposedTo ?? payload.proposedTo,
+        chatId: chatId ?? undefined,
+        description: String(priced.description ?? payload.description),
+        providerId: priced.providerId,
+        price: typeof priced.price === 'number' ? priced.price : undefined,
+        lifecycle: typeof priced.lifecycle === 'string' ? priced.lifecycle : undefined,
+        expiresAt: typeof priced.expiresAt === 'string' ? priced.expiresAt : undefined,
+        maxExecutions: typeof priced.maxExecutions === 'number' ? priced.maxExecutions : undefined,
+        billing,
+        agreementDescription: priced.agreementDescription,
+        parentAgreementId: priced.parentAgreementId,
+        engagementKind,
+        idempotencyKey,
+    });
+    // Keep the agreement fields at the top level (the shape agents already
+    // read) and add the discriminant the shared flow returns.
+    return { ...agreement, shape };
 }
 // ── deterministic sub-agreement resolution ─────────────────────────
 // The orchestrator delegates one task per worker, but the LLM inconsistently

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

@@ -1,7 +1,7 @@
 import { defineTool } from '../../../tools/defineTool.js';
 import { requireProtocolOperation } from '../../../tasks/protocolRegistry.js';
 import { dispatchProtocolOp } from './protocolRunner.js';
-import { AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION, } from '@ziggs-ai/api-client';
+import { AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION, agreementClaimCapability, } from '@ziggs-ai/api-client';
 /** keep these enums in lockstep with MCP ziggs_agreement_* / ziggs_task_create. */
 const LIFECYCLE_ENUM = ['open', 'time-bound', 'count-bound'];
 const PLAN_REVIEW_TIMING_ENUM = ['with_proposal', 'before_execution'];
@@ -46,12 +46,7 @@ function handlerFor(toolName) {
 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: it takes an email or an agent id, or neither for a share link. 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)' },
-    // The job this claim is part of. Filled in from the task this wake is
-    // executing when the agent does not name one itself.
-    mandateAgreementId: { type: 'string', description: 'The active agreement whose work this claim is part of — the job you are doing. Claiming for a job your human already approved needs no second approval from them, but you have to name the job: the server checks you are a party to it, and a wrong name simply earns nothing. Leave it out when the claim belongs to no job.' },
-}, 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 agreementClaimTool = defineTool('agreement_claim', agreementClaimCapability.params, handlerFor('agreement_claim'), { description: agreementClaimCapability.descriptions.sdk });
 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.

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

@@ -0,0 +1,6 @@
+import type { ToolDefinition } from '../../../tools/defineTool.js';
+export declare const introductionMintTool: ToolDefinition;
+export declare const introductionRedeemTool: ToolDefinition;
+export declare const introductionListTool: ToolDefinition;
+export declare const introductionRevokeTool: ToolDefinition;
+export declare const INTRODUCTION_TOOLS: ToolDefinition[];

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

@@ -0,0 +1,12 @@
+import { INTRODUCTION_CAPABILITIES, mintIntroductionCapability, redeemIntroductionCapability, listIntroductionsCapability, revokeIntroductionCapability, } from '@ziggs-ai/api-client';
+import { toolFromCapability, toolsFromCapabilities } from '../../../tools/capabilityAdapter.js';
+// Introduction tokens: what an agent hands over when it meets another
+// agent somewhere Ziggs does not own. Defined once in api-client's capability
+// layer; this file only adapts them onto the SDK. They sit beside the link tools
+// because a redeemed introduction becomes a link — this rail is how a meeting
+// off-platform turns into one.
+export const introductionMintTool = toolFromCapability(mintIntroductionCapability);
+export const introductionRedeemTool = toolFromCapability(redeemIntroductionCapability);
+export const introductionListTool = toolFromCapability(listIntroductionsCapability);
+export const introductionRevokeTool = toolFromCapability(revokeIntroductionCapability);
+export const INTRODUCTION_TOOLS = toolsFromCapabilities(INTRODUCTION_CAPABILITIES);

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

@@ -0,0 +1,3 @@
+import type { ToolDefinition } from '../../../tools/defineTool.js';
+export declare const listTasksTool: ToolDefinition;
+export declare const TASK_TOOLS: ToolDefinition[];

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

@@ -0,0 +1,6 @@
+import { listTasksCapability, TASK_CAPABILITIES } from '@ziggs-ai/api-client';
+import { toolFromCapability, toolsFromCapabilities } from '../../../tools/capabilityAdapter.js';
+// GET /tasks, defined once in api-client. MCP ziggs_task_list and this
+// hosted-Claude tool used to re-declare the same filters.
+export const listTasksTool = toolFromCapability(listTasksCapability);
+export const TASK_TOOLS = toolsFromCapabilities(TASK_CAPABILITIES);

package/dist/tools/recordReport.d.ts

@@ -38,6 +38,11 @@ export interface RecordReportResult {
  * When `deliverable` is provided, also writes a task-bound result artifact
  * via ArtifactsClient so it is retrievable as `via=task:<taskId>`.
  *
+ * One deliverable per task: the idempotency key is `task-result:<taskId>`.
+ * A retry after a partial failure reuses that row (intentional). A later
+ * revision of the same task still returns the original artifact — change the
+ * key if you mean a new deliverable; do not change this helper's key.
+ *
  * Implements the B1 convention (Agents/REPORTING.md).
  */
 export declare function recordReport(input: RecordReportInput): Promise<RecordReportResult>;

package/dist/tools/recordReport.js

@@ -6,6 +6,11 @@ import { ArtifactsClient, updateTaskState, } from '@ziggs-ai/api-client';
  * When `deliverable` is provided, also writes a task-bound result artifact
  * via ArtifactsClient so it is retrievable as `via=task:<taskId>`.
  *
+ * One deliverable per task: the idempotency key is `task-result:<taskId>`.
+ * A retry after a partial failure reuses that row (intentional). A later
+ * revision of the same task still returns the original artifact — change the
+ * key if you mean a new deliverable; do not change this helper's key.
+ *
  * Implements the B1 convention (Agents/REPORTING.md).
  */
 export async function recordReport(input) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/agent-sdk",
-  "version": "0.14.0",
+  "version": "0.16.1",
   "description": "Agent framework SDK for building autonomous agents on the Ziggs platform",
   "type": "module",
   "main": "dist/index.js",
@@ -26,7 +26,7 @@
     "@anthropic-ai/claude-agent-sdk": "^0.3.204",
     "@anthropic-ai/sdk": "^0.110.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@ziggs-ai/api-client": "0.13.0",
+    "@ziggs-ai/api-client": "0.15.1",
     "ajv": "^8.17.1",
     "dotenv": "^17.2.3",
     "openai": "^4.0.0",