@ziggs-ai/agent-sdk 0.1.4 → 0.1.6

package/src/server/{tasks → tools/tier2}/paymentTools.ts

@@ -1,5 +1,5 @@
-import { defineTool, type ToolDefinition } from '../../tools/defineTool.js';
-import { ZiggsPayClient } from '../ziggspay/ZiggsPayClient.js';
+import { defineTool, type ToolDefinition } from '../../../tools/defineTool.js';
+import { ZiggsPayClient } from '../../ziggspay/ZiggsPayClient.js';
 
 type Ctx = Record<string, unknown>;
 type AnyObj = Record<string, unknown>;
@@ -35,17 +35,18 @@ export const paymentBalanceTool: ToolDefinition = defineTool('payment_balance',
     try { return await clientFor(ctx as Ctx).balance(); }
     catch (e) { rethrowWithContext(e, 'Failed to get balance'); }
   },
+  { description: "Check the caller's current wallet balance and available balance (total minus active holds). Use before a transfer to confirm sufficient funds." },
 );
 
 export const paymentTransferTool: ToolDefinition = defineTool('payment_transfer',
-  { toWalletId: { type: 'string', required: true }, amount: { type: 'number', required: true }, description: 'string', idempotencyKey: 'string', capabilityTokenId: 'string' },
+  { toWalletId: { type: 'string', required: true }, amount: { type: 'number', required: true }, description: 'string', idempotencyKey: 'string', paymentGrantId: 'string' },
   async (args, ctx) => {
     if (!args['toWalletId']) throw new Error('toWalletId is required');
     if (!args['amount'] || (args['amount'] as number) <= 0) throw new Error('amount must be positive');
     const client = clientFor(ctx as Ctx);
     let result: AnyObj;
     try {
-      result = await client.transfer({ to: args['toWalletId'] as string, amount: Math.round(args['amount'] as number), description: (args['description'] as string) || 'Agent-initiated transfer', idempotencyKey: args['idempotencyKey'] as string | undefined, capabilityTokenId: args['capabilityTokenId'] as string | undefined }) as AnyObj;
+      result = await client.transfer({ to: args['toWalletId'] as string, amount: Math.round(args['amount'] as number), description: (args['description'] as string) || 'Agent-initiated transfer', idempotencyKey: args['idempotencyKey'] as string | undefined, paymentGrantId: args['paymentGrantId'] as string | undefined }) as AnyObj;
     } catch (e) { rethrowWithContext(e, 'Transfer failed'); }
     if (result!['status'] === 'approval_required') {
       return { status: 'approval_required', approvalId: result!['approvalId'] || null, expiresAt: result!['expiresAt'] || null, reason: result!['reason'] || null, amount: args['amount'], toWalletId: result!['toWalletId'],
@@ -76,6 +77,7 @@ export const paymentResolveWalletTool: ToolDefinition = defineTool('payment_reso
       return { walletId: wallet?.['walletId'] || null, ownerId: wallet?.['ownerId'] || null, currency: wallet?.['currency'] || 'pez', status: wallet?.['status'] || null };
     } catch (e) { rethrowWithContext(e, 'Failed to resolve wallet'); }
   },
+  { description: 'Look up a walletId by userId or agentId. Use before a transfer when you only know the recipient by their platform ID.' },
 );
 
 export const paymentHoldTool: ToolDefinition = defineTool('payment_hold',
@@ -87,6 +89,7 @@ export const paymentHoldTool: ToolDefinition = defineTool('payment_hold',
       return { status: 'held', transactionId: (result['transaction'] as AnyObj | undefined)?.['transactionId'] || null, amount: args['amount'] };
     } catch (e) { rethrowWithContext(e, 'Hold failed'); }
   },
+  { description: 'Pre-authorize (escrow) funds without moving them. Use to reserve payment at agreement formation; release with payment_release once work is complete or to refund if work is cancelled.' },
 );
 
 export const paymentReleaseTool: ToolDefinition = defineTool('payment_release',
@@ -100,57 +103,91 @@ export const paymentReleaseTool: ToolDefinition = defineTool('payment_release',
       return { status: args['action'] === 'complete' ? 'settled' : 'refunded', transactionId: (result['transaction'] as AnyObj | undefined)?.['transactionId'] || null, holdId: args['holdId'], action: args['action'] };
     } catch (e) { rethrowWithContext(e, 'Release failed'); }
   },
+  { description: "Settle or refund an escrow hold. Use action='complete' to transfer held funds to toWalletId (work done), or action='refund' to return funds to the sender (work cancelled)." },
 );
 
+const issueGrantHandler = async (args: AnyObj, ctx: Ctx) => {
+  if (!args['holderId']) throw new Error('holderId is required');
+  try {
+    const caveats = buildCaveats(args);
+    const result = await clientFor(ctx).issueGrant({ holderId: args['holderId'] as string, caveats }) as AnyObj;
+    const grant = result['grant'] as AnyObj | undefined;
+    return { grantId: grant?.['grantId'] || null, holderId: grant?.['holderId'] || args['holderId'], caveats: grant?.['caveats'] || caveats, expiresAt: grant?.['expiresAt'] || null };
+  } catch (e) { rethrowWithContext(e, 'Failed to issue payment grant'); }
+};
+
+export const paymentIssueGrantTool: ToolDefinition = defineTool('payment_issue_grant',
+  { holderId: { type: 'string', required: true }, maxAmount: 'number', dailyBudget: 'number', allowedRecipients: ['string'], expiresInSeconds: 'number' },
+  issueGrantHandler,
+);
+
+/** @deprecated Use payment_issue_grant */
 export const paymentIssueTokenTool: ToolDefinition = defineTool('payment_issue_token',
   { holderId: { type: 'string', required: true }, maxAmount: 'number', dailyBudget: 'number', allowedRecipients: ['string'], expiresInSeconds: 'number' },
-  async (args, ctx) => {
-    if (!args['holderId']) throw new Error('holderId is required');
-    try {
-      const caveats = buildCaveats(args);
-      const result = await clientFor(ctx as Ctx).issueToken({ holderId: args['holderId'] as string, caveats }) as AnyObj;
-      const token = result['token'] as AnyObj | undefined;
-      return { tokenId: token?.['tokenId'] || null, holderId: token?.['holderId'] || args['holderId'], caveats: token?.['caveats'] || caveats, expiresAt: token?.['expiresAt'] || null };
-    } catch (e) { rethrowWithContext(e, 'Failed to issue capability token'); }
-  },
+  issueGrantHandler,
 );
 
+const attenuateGrantHandler = async (args: AnyObj, ctx: Ctx) => {
+  const grantId = (args['grantId'] || args['tokenId']) as string;
+  if (!grantId) throw new Error('grantId is required');
+  if (!args['holderId']) throw new Error('holderId is required');
+  try {
+    const caveats = buildCaveats(args);
+    const result = await clientFor(ctx).attenuateGrant({ grantId, holderId: args['holderId'] as string, caveats }) as AnyObj;
+    const grant = result['grant'] as AnyObj | undefined;
+    return { grantId: grant?.['grantId'] || null, parentGrantId: grant?.['parentGrantId'] || grantId, holderId: grant?.['holderId'] || args['holderId'], caveats: grant?.['caveats'] || caveats, expiresAt: grant?.['expiresAt'] || null };
+  } catch (e) { rethrowWithContext(e, 'Failed to attenuate payment grant'); }
+};
+
+export const paymentAttenuateGrantTool: ToolDefinition = defineTool('payment_attenuate_grant',
+  { grantId: { type: 'string', required: true }, holderId: { type: 'string', required: true }, maxAmount: 'number', dailyBudget: 'number', allowedRecipients: ['string'], expiresInSeconds: 'number' },
+  attenuateGrantHandler,
+);
+
+/** @deprecated Use payment_attenuate_grant */
 export const paymentAttenuateTokenTool: ToolDefinition = defineTool('payment_attenuate_token',
   { tokenId: { type: 'string', required: true }, holderId: { type: 'string', required: true }, maxAmount: 'number', dailyBudget: 'number', allowedRecipients: ['string'], expiresInSeconds: 'number' },
-  async (args, ctx) => {
-    if (!args['tokenId']) throw new Error('tokenId is required');
-    if (!args['holderId']) throw new Error('holderId is required');
-    try {
-      const caveats = buildCaveats(args);
-      const result = await clientFor(ctx as Ctx).attenuateToken({ tokenId: args['tokenId'] as string, holderId: args['holderId'] as string, caveats }) as AnyObj;
-      const token = result['token'] as AnyObj | undefined;
-      return { tokenId: token?.['tokenId'] || null, parentTokenId: token?.['parentTokenId'] || args['tokenId'], holderId: token?.['holderId'] || args['holderId'], caveats: token?.['caveats'] || caveats, expiresAt: token?.['expiresAt'] || null };
-    } catch (e) { rethrowWithContext(e, 'Failed to attenuate capability token'); }
-  },
+  attenuateGrantHandler,
 );
 
+const revokeGrantHandler = async (args: AnyObj, ctx: Ctx) => {
+  const grantId = (args['grantId'] || args['tokenId']) as string;
+  if (!grantId) throw new Error('grantId is required');
+  try {
+    const result = await clientFor(ctx).revokeGrant(grantId) as AnyObj;
+    return { status: 'revoked', grantId, revoked: result['revoked'] ?? null };
+  } catch (e) { rethrowWithContext(e, 'Failed to revoke payment grant'); }
+};
+
+export const paymentRevokeGrantTool: ToolDefinition = defineTool('payment_revoke_grant',
+  { grantId: { type: 'string', required: true } },
+  revokeGrantHandler,
+);
+
+/** @deprecated Use payment_revoke_grant */
 export const paymentRevokeTokenTool: ToolDefinition = defineTool('payment_revoke_token',
   { tokenId: { type: 'string', required: true } },
-  async (args, ctx) => {
-    if (!args['tokenId']) throw new Error('tokenId is required');
-    try {
-      const result = await clientFor(ctx as Ctx).revokeToken(args['tokenId'] as string) as AnyObj;
-      return { status: 'revoked', tokenId: args['tokenId'], revoked: result['revoked'] ?? null };
-    } catch (e) { rethrowWithContext(e, 'Failed to revoke capability token'); }
-  },
+  revokeGrantHandler,
 );
 
+const listGrantsHandler = async (_args: AnyObj, ctx: Ctx) => {
+  try {
+    const result = await clientFor(ctx).listGrants();
+    return { grants: result || [] };
+  } catch (e) { rethrowWithContext(e, 'Failed to list payment grants'); }
+};
+
+export const paymentListGrantsTool: ToolDefinition = defineTool('payment_list_grants', {},
+  listGrantsHandler,
+);
+
+/** @deprecated Use payment_list_grants */
 export const paymentListTokensTool: ToolDefinition = defineTool('payment_list_tokens', {},
-  async (_args, ctx) => {
-    try {
-      const result = await clientFor(ctx as Ctx).listTokens();
-      return { tokens: result || [] };
-    } catch (e) { rethrowWithContext(e, 'Failed to list capability tokens'); }
-  },
+  listGrantsHandler,
 );
 
 export const PAYMENT_TOOLS: ToolDefinition[] = [
   paymentBalanceTool, paymentTransferTool, paymentWaitForApprovalTool,
   paymentHoldTool, paymentReleaseTool, paymentResolveWalletTool,
-  paymentIssueTokenTool, paymentAttenuateTokenTool, paymentRevokeTokenTool, paymentListTokensTool,
+  paymentIssueGrantTool, paymentAttenuateGrantTool, paymentRevokeGrantTool, paymentListGrantsTool,
 ];

package/src/server/ziggsconnect/ZiggsConnectClient.ts

@@ -0,0 +1,126 @@
+import 'dotenv/config';
+
+function getDefaultBaseUrl(): string {
+  return process.env.BACKEND_URL || process.env.ZIGGS_BACKEND_URL || 'http://localhost:3000';
+}
+
+function parseError(text: string, fallback: string): string {
+  if (!text) return fallback;
+  try {
+    const parsed = JSON.parse(text) as Record<string, unknown>;
+    return (parsed['message'] as string) || (parsed['error'] as string) || text;
+  } catch {
+    return text;
+  }
+}
+
+interface ConnectError extends Error {
+  status?: number;
+  body?: string;
+}
+
+export interface ZiggsConnectClientOptions {
+  operatorKey: string;
+  actAsAgentId?: string;
+  baseUrl?: string;
+}
+
+export interface ProxyParams {
+  connectionId: string;
+  grantId: string;
+  action: string;
+  payload?: unknown;
+}
+
+export class ZiggsConnectClient {
+  private operatorKey: string;
+  private actAsAgentId: string | null;
+  private baseUrl: string;
+
+  constructor({ operatorKey, actAsAgentId, baseUrl }: ZiggsConnectClientOptions) {
+    if (!operatorKey || typeof operatorKey !== 'string') {
+      throw new Error('ZiggsConnectClient requires an operatorKey');
+    }
+    this.operatorKey = operatorKey;
+    this.actAsAgentId = actAsAgentId || null;
+    this.baseUrl = baseUrl || getDefaultBaseUrl();
+  }
+
+  /**
+   * Present a ConnectionGrant to the broker and perform a provider action.
+   * Returns the provider result — never the raw OAuth token.
+   */
+  async proxy({ connectionId, grantId, action, payload }: ProxyParams): Promise<unknown> {
+    if (!connectionId) throw new Error('proxy: connectionId is required');
+    if (!grantId) throw new Error('proxy: grantId is required');
+    if (!action) throw new Error('proxy: action is required');
+    if (!this.actAsAgentId) {
+      throw new Error(
+        'proxy: actAsAgentId is required — connection broker calls must impersonate the grant holder agent',
+      );
+    }
+    const res = (await this._post(`/connections/${encodeURIComponent(connectionId)}/proxy`, {
+      grantId,
+      action,
+      payload: payload ?? {},
+    })) as Record<string, unknown>;
+    return res['result'] ?? res;
+  }
+
+  /**
+   * List ConnectionGrants held by this agent for a connection.
+   * Requires actAsAgentId; filters server rows to holderId === agent.
+   */
+  async listGrants({ connectionId }: { connectionId: string }): Promise<unknown[]> {
+    if (!connectionId) throw new Error('listGrants: connectionId is required');
+    if (!this.actAsAgentId) {
+      throw new Error(
+        'listGrants: actAsAgentId is required — grants are scoped to the impersonated agent',
+      );
+    }
+    const res = (await this._get(
+      `/connections/${encodeURIComponent(connectionId)}/grants`,
+    )) as Record<string, unknown>;
+    const grants = (res['grants'] as Array<Record<string, unknown>>) || [];
+    return grants.filter((g) => g['holderId'] === this.actAsAgentId);
+  }
+
+  private _buildHeaders(extra: Record<string, string> = {}): Record<string, string> {
+    const h: Record<string, string> = { Authorization: `Bearer ${this.operatorKey}`, ...extra };
+    if (this.actAsAgentId) h['X-Agent-Id'] = this.actAsAgentId;
+    return h;
+  }
+
+  private async _request(method: string, path: string, body: unknown): Promise<unknown> {
+    const init: RequestInit = {
+      method,
+      headers: this._buildHeaders(
+        body !== undefined ? { 'content-type': 'application/json' } : {},
+      ),
+    };
+    if (body !== undefined) init.body = JSON.stringify(body);
+    const response = await fetch(`${this.baseUrl}${path}`, init);
+    const text = await response.text();
+    if (!response.ok) {
+      const err = new Error(parseError(text, `HTTP ${response.status}`)) as ConnectError;
+      err.status = response.status;
+      err.body = text;
+      throw err;
+    }
+    return text ? JSON.parse(text) : null;
+  }
+
+  private _get(path: string): Promise<unknown> {
+    return this._request('GET', path, undefined);
+  }
+
+  private _post(path: string, body: unknown): Promise<unknown> {
+    return this._request('POST', path, body ?? {});
+  }
+}
+
+export function createZiggsConnectClient(
+  opts: ZiggsConnectClientOptions,
+): ZiggsConnectClient {
+  return new ZiggsConnectClient(opts);
+}

package/src/server/ziggscontext/ZiggsContextClient.ts

@@ -0,0 +1,137 @@
+import 'dotenv/config';
+
+function getDefaultBaseUrl(): string {
+  return process.env.BACKEND_URL || process.env.ZIGGS_BACKEND_URL || 'http://localhost:3000';
+}
+
+function parseError(text: string, fallback: string): string {
+  if (!text) return fallback;
+  try {
+    const parsed = JSON.parse(text) as Record<string, unknown>;
+    return (parsed['message'] as string) || (parsed['error'] as string) || text;
+  } catch {
+    return text;
+  }
+}
+
+interface ContextError extends Error {
+  status?: number;
+  body?: string;
+}
+
+export interface ZiggsContextClientOptions {
+  operatorKey: string;
+  actAsAgentId?: string;
+  baseUrl?: string;
+}
+
+export interface ContextReachDescriptor {
+  grantId: string;
+  scope: { kind: 'chat' | 'agreement' | 'org'; id: string };
+  temporal: 'from-now' | 'from-start';
+  watermarkAt: string;
+  expiresAt: string | null;
+  parentGrantId: string | null;
+  createdAt: string;
+}
+
+export interface DelegateContextGrantParams {
+  parentGrantId: string;
+  holderId: string;
+  scope: { kind: 'chat' | 'agreement' | 'org'; id: string };
+  temporal: 'from-now' | 'from-start';
+  expiresAt?: string | null;
+  watermarkAt?: string;
+}
+
+/**
+ * HTTP client for context grants (ZIG-413).
+ * Presentation model (signed bytes vs grant id) is intentionally not baked in here.
+ */
+export class ZiggsContextClient {
+  private operatorKey: string;
+  private actAsAgentId: string | null;
+  private baseUrl: string;
+
+  constructor({ operatorKey, actAsAgentId, baseUrl }: ZiggsContextClientOptions) {
+    if (!operatorKey || typeof operatorKey !== 'string') {
+      throw new Error('ZiggsContextClient requires an operatorKey');
+    }
+    this.operatorKey = operatorKey;
+    this.actAsAgentId = actAsAgentId || null;
+    this.baseUrl = baseUrl || getDefaultBaseUrl();
+  }
+
+  /** ZIG-412: scope descriptors for what this agent can reach (no content). */
+  async discover(): Promise<ContextReachDescriptor[]> {
+    this.requireActAsAgent('discover');
+    const res = (await this._get('/context/discovery')) as Record<string, unknown>;
+    return (res['reach'] as ContextReachDescriptor[]) || [];
+  }
+
+  /** List persisted grant rows held by this agent (may include signedBytes). */
+  async listGrants(): Promise<unknown[]> {
+    this.requireActAsAgent('listGrants');
+    const res = (await this._get('/context/grants')) as Record<string, unknown>;
+    const grants = (res['grants'] as Array<Record<string, unknown>>) || [];
+    return grants.filter((g) => g['holderId'] === this.actAsAgentId);
+  }
+
+  /** Holder delegates a narrower child grant. */
+  async delegate(params: DelegateContextGrantParams): Promise<unknown> {
+    this.requireActAsAgent('delegate');
+    if (!params.parentGrantId) throw new Error('delegate: parentGrantId is required');
+    if (!params.holderId) throw new Error('delegate: holderId is required');
+    if (!params.scope?.kind || !params.scope?.id) {
+      throw new Error('delegate: scope { kind, id } is required');
+    }
+    return this._post(`/context/grants/${encodeURIComponent(params.parentGrantId)}/delegate`, {
+      holderId: params.holderId,
+      scope: params.scope,
+      temporal: params.temporal,
+      expiresAt: params.expiresAt,
+      watermarkAt: params.watermarkAt,
+    });
+  }
+
+  private requireActAsAgent(method: string): void {
+    if (!this.actAsAgentId) {
+      throw new Error(
+        `${method}: actAsAgentId is required — context grant calls must impersonate the grant holder agent`,
+      );
+    }
+  }
+
+  private _buildHeaders(extra: Record<string, string> = {}): Record<string, string> {
+    const h: Record<string, string> = { Authorization: `Bearer ${this.operatorKey}`, ...extra };
+    if (this.actAsAgentId) h['X-Agent-Id'] = this.actAsAgentId;
+    return h;
+  }
+
+  private async _request(method: string, path: string, body: unknown): Promise<unknown> {
+    const init: RequestInit = {
+      method,
+      headers: this._buildHeaders(
+        body !== undefined ? { 'content-type': 'application/json' } : {},
+      ),
+    };
+    if (body !== undefined) init.body = JSON.stringify(body);
+    const res = await fetch(`${this.baseUrl}${path}`, init);
+    const text = await res.text();
+    if (!res.ok) {
+      const err = new Error(parseError(text, `${method} ${path} failed (${res.status})`)) as ContextError;
+      err.status = res.status;
+      err.body = text;
+      throw err;
+    }
+    return text ? JSON.parse(text) : {};
+  }
+
+  private _get(path: string): Promise<unknown> {
+    return this._request('GET', path, undefined);
+  }
+
+  private _post(path: string, body: unknown): Promise<unknown> {
+    return this._request('POST', path, body);
+  }
+}

package/src/server/ziggspay/ZiggsPayClient.ts

@@ -51,17 +51,17 @@ export class ZiggsPayClient {
     return res['wallet'] || null;
   }
 
-  async transfer({ to, amount, idempotencyKey, description, capabilityTokenId }: { to: string; amount: number; idempotencyKey?: string; description?: string; capabilityTokenId?: string }): Promise<unknown> {
+  async transfer({ to, amount, idempotencyKey, description, paymentGrantId }: { to: string; amount: number; idempotencyKey?: string; description?: string; paymentGrantId?: string }): Promise<unknown> {
     if (!to) throw new Error('transfer: `to` is required');
     if (!(Number.isInteger(amount) && amount > 0)) throw new Error('transfer: `amount` must be a positive integer (cents)');
-    if (this.actAsAgentId && !capabilityTokenId) throw new Error('transfer: capabilityTokenId is required for agent-impersonated transfers. The wallet owner must have issued a capability token to this agentId.');
+    if (this.actAsAgentId && !paymentGrantId) throw new Error('transfer: paymentGrantId is required for agent-impersonated transfers. The wallet owner must have issued a payment grant to this agentId.');
     let toWalletId = to;
     if (!to.startsWith('wal_')) {
       const w = await this.resolve(to.startsWith('agent_') ? { agentId: to } : { userId: to }) as Record<string, unknown> | null;
       if (!w?.['walletId']) throw new Error(`transfer: could not resolve wallet for "${to}"`);
       toWalletId = w['walletId'] as string;
     }
-    const result = await this._post('/payments/transfer', { toWalletId, amount, idempotencyKey: idempotencyKey || randomIdempotencyKey('xfer'), description, capabilityTokenId }) as Record<string, unknown>;
+    const result = await this._post('/payments/transfer', { toWalletId, amount, idempotencyKey: idempotencyKey || randomIdempotencyKey('xfer'), description, paymentGrantId }) as Record<string, unknown>;
     if (result?.['status'] === 'approval_required') {
       const approval = (result['approval'] as Record<string, unknown>) || {};
       return { status: 'approval_required', approvalId: approval['approvalId'] || null, expiresAt: approval['expiresAt'] || null, reason: approval['reason'] || 'Amount exceeds auto-approve threshold', toWalletId, amount };
@@ -87,21 +87,21 @@ export class ZiggsPayClient {
     return this._get('/payments/history' + (q.toString() ? `?${q}` : ''));
   }
 
-  async issueToken({ holderId, caveats }: { holderId: string; caveats?: unknown }): Promise<unknown> {
-    return this._post('/payments/tokens', { holderId, caveats });
+  async issueGrant({ holderId, caveats }: { holderId: string; caveats?: unknown }): Promise<unknown> {
+    return this._post('/payments/grants', { holderId, caveats });
   }
 
-  async attenuateToken({ tokenId, holderId, caveats }: { tokenId: string; holderId: string; caveats?: unknown }): Promise<unknown> {
-    return this._post(`/payments/tokens/${tokenId}/attenuate`, { holderId, caveats });
+  async attenuateGrant({ grantId, holderId, caveats }: { grantId: string; holderId: string; caveats?: unknown }): Promise<unknown> {
+    return this._post(`/payments/grants/${grantId}/attenuate`, { holderId, caveats });
   }
 
-  async revokeToken(tokenId: string): Promise<unknown> {
-    return this._request('DELETE', `/payments/tokens/${tokenId}`, undefined);
+  async revokeGrant(grantId: string): Promise<unknown> {
+    return this._request('DELETE', `/payments/grants/${grantId}`, undefined);
   }
 
-  async listTokens(): Promise<unknown[]> {
-    const res = await this._get('/payments/tokens') as Record<string, unknown>;
-    return (res['tokens'] as unknown[]) || [];
+  async listGrants(): Promise<unknown[]> {
+    const res = await this._get('/payments/grants') as Record<string, unknown>;
+    return (res['grants'] as unknown[]) || [];
   }
 
   async createTopUpIntent({ amount, description, currency }: { amount?: number; description?: string; currency?: string } = {}): Promise<unknown> {

package/src/shared/types.ts

@@ -21,8 +21,6 @@ export const ContentTypes = {
 
 export type ContentType = (typeof ContentTypes)[keyof typeof ContentTypes];
 
-export { TaskState, TERMINAL_STATES, OPEN_AGREEMENT_TARGET } from '../tasks/taskCore.js';
-
 export const ContextProperties = {
   HISTORY:    'history',
   AGREEMENTS: 'agreements',

package/src/tools/index.ts

@@ -1,5 +1,7 @@
 export { ToolManager } from './ToolManager.js';
 export { ToolProvider } from './ToolProvider.js';
 export { defineTool } from './defineTool.js';
+export { recordReport } from './recordReport.js';
+export type { RecordReportInput, RecordReportResult, TaskReport } from './recordReport.js';
 // Pure protocol-tool name registry (no handlers, no services).
 export { PROTOCOL_TOOL_NAMES, PROTOCOL_TOOL_TO_OPERATION, mapProtocolToolToOperation, isProtocolToolName } from '../tasks/protocolRegistry.js';

package/src/tools/recordReport.ts

@@ -0,0 +1,82 @@
+import {
+  ArtifactsClient,
+  updateTaskState,
+  type Creds,
+} from '@ziggs-ai/api-client';
+
+/**
+ * The canonical report shape (B1 convention — ZIG-561).
+ * Matches Task.result as set by ziggs_set_task_result.
+ */
+export interface TaskReport {
+  summary: string;
+  status?: string;
+  links?: string[];
+}
+
+export interface RecordReportInput {
+  creds: Creds;
+  taskId: string;
+  report: TaskReport;
+  /**
+   * Primary artifact scope — required when `deliverable` is provided.
+   * Pass exactly one of chatId or agreementId.
+   */
+  chatId?: string;
+  agreementId?: string;
+  /**
+   * Heavy deliverable text (document, diff, data).
+   * When present, writes a `content_type=result` artifact bound to the task
+   * alongside setting Task.result.
+   */
+  deliverable?: string;
+}
+
+export interface RecordReportResult {
+  taskId: string;
+  artifactId?: string;
+}
+
+/**
+ * Record a conformant report for a completed task (B2 — ZIG-562).
+ *
+ * Always sets Task.result via updateTaskState (the canonical done payload).
+ * When `deliverable` is provided, also writes a task-bound result artifact
+ * via ArtifactsClient so it is retrievable as `via=task:<taskId>`.
+ *
+ * Implements the B1 convention (Agents/REPORTING.md).
+ */
+export async function recordReport(
+  input: RecordReportInput,
+): Promise<RecordReportResult> {
+  const { creds, taskId, report, chatId, agreementId, deliverable } = input;
+
+  if (deliverable && !chatId && !agreementId) {
+    throw new Error(
+      'recordReport: chatId or agreementId is required when deliverable is provided',
+    );
+  }
+
+  await updateTaskState(
+    taskId,
+    'completed',
+    { result: { summary: report.summary, status: report.status ?? 'ok', links: report.links ?? [] } },
+    creds,
+  );
+
+  if (!deliverable) {
+    return { taskId };
+  }
+
+  const artifactsClient = new ArtifactsClient(creds.operatorKey, creds.agentId);
+  await artifactsClient.write({
+    text: deliverable,
+    content_type: 'result',
+    taskId,
+    chatId,
+    agreementId,
+    visibility: 'chat',
+  });
+
+  return { taskId };
+}