@ziggs-ai/agent-sdk 0.1.3 → 0.1.4

package/src/server/tasks/TaskService.ts

@@ -0,0 +1,111 @@
+import {
+  createTask, getTask, getActiveTasksForAgent, getActiveTasksForChat, getSubtasks,
+  updateTaskState, cancelTask,
+  claimLedgerTask, reportTask, setTaskSatisfaction, countTasks,
+  type Creds, type Task,
+} from '@ziggs-ai/api-client';
+import type { TaskWithFlags, TaskStateValue } from '../../tasks/taskCore.js';
+import type { CountTasksFilters } from '@ziggs-ai/api-client';
+import { runtimeLog } from '../../shared/runtimeLog.js';
+
+function safeJsonStringify(value: unknown): unknown {
+  if (value === null || value === undefined) return value;
+  if (typeof value === 'string') return value;
+  if (typeof value !== 'object') return String(value);
+  const seen = new WeakSet();
+  try {
+    return JSON.stringify(value, (_key, val) => {
+      if (typeof val === 'object' && val !== null) {
+        if (seen.has(val)) return '[Circular]';
+        seen.add(val);
+      }
+      return val;
+    }, 2);
+  } catch {
+    return String(value);
+  }
+}
+
+export class TaskService {
+  private creds: Creds;
+
+  constructor(operatorKey: string, agentId: string) {
+    if (!operatorKey) throw new Error('TaskService: operatorKey is required');
+    if (!agentId) throw new Error('TaskService: agentId is required (operator-token impersonation)');
+    this.creds = { operatorKey, agentId };
+  }
+
+  async getTask(taskId: string): Promise<Task> {
+    return getTask(taskId, this.creds);
+  }
+
+  async getActiveTasksForAgent(agentId: string): Promise<Task[]> {
+    return getActiveTasksForAgent(agentId, this.creds);
+  }
+
+  async getActiveTasksForChat(chatId: string): Promise<Task[]> {
+    return getActiveTasksForChat(chatId, this.creds);
+  }
+
+  async getSubtasks(parentTaskId: string): Promise<Task[]> {
+    return getSubtasks(parentTaskId, this.creds);
+  }
+
+  async spawnUnderAgreement(agreementId: string, taskData: { description: string; parentTaskId?: string; plan?: unknown; planReviewTiming?: string; requireMidWorkPlanAck?: boolean }): Promise<Task> {
+    if (!agreementId) throw new Error('TaskService.spawnUnderAgreement: agreementId is required');
+    try {
+      const result = await createTask({ ...taskData, agreementId } as Parameters<typeof createTask>[0], this.creds);
+      runtimeLog.info('TaskService', `Task spawned under agreement ${agreementId}: ${result?.taskId || 'unknown'}`);
+      return result;
+    } catch (error) {
+      runtimeLog.error('TaskService', `Task spawn failed: ${(error as Error).message}`);
+      throw error;
+    }
+  }
+
+  async updateState(taskId: string, state: TaskStateValue, result?: unknown): Promise<Task> {
+    try {
+      const data = result !== undefined ? { result: safeJsonStringify(result) } : {};
+      const updated = await updateTaskState(taskId, state, data, this.creds);
+      runtimeLog.info('TaskService', `Task state: ${taskId} → ${state}`);
+      return updated;
+    } catch (error) {
+      runtimeLog.error('TaskService', `Task state update failed: ${(error as Error).message}`);
+      throw error;
+    }
+  }
+
+  async cancel(taskId: string): Promise<Task> {
+    try {
+      const updated = await cancelTask(taskId, this.creds);
+      runtimeLog.info('TaskService', `Task cancelled: ${taskId}`);
+      return updated;
+    } catch (error) {
+      runtimeLog.error('TaskService', `Task cancel failed: ${(error as Error).message}`);
+      throw error;
+    }
+  }
+
+  async claimLedgerTask(taskId: string): Promise<TaskWithFlags> {
+    try {
+      const task = await claimLedgerTask(taskId, this.creds);
+      runtimeLog.info('TaskService', `[ledger] Claimed task ${taskId}`);
+      return task as unknown as TaskWithFlags;
+    } catch (error) {
+      runtimeLog.warn('TaskService', `[ledger] Claim failed for ${taskId}: ${(error as Error).message}`);
+      throw error;
+    }
+  }
+
+  async report(taskId: string, message = ''): Promise<Task> {
+    return reportTask(taskId, message, this.creds);
+  }
+
+  async setSatisfaction(taskId: string, satisfaction: 'positive' | 'negative'): Promise<Task> {
+    return setTaskSatisfaction(taskId, satisfaction, this.creds);
+  }
+
+  async count(filters: CountTasksFilters = {}): Promise<number> {
+    return countTasks(filters, this.creds);
+  }
+}

package/src/server/tasks/index.ts

@@ -0,0 +1,4 @@
+export { TaskService } from './TaskService.js';
+export { PROTOCOL_TOOLS } from './protocolTools.js';
+export { PROTOCOL_TOOL_NAMES, PROTOCOL_TOOL_TO_OPERATION, mapProtocolToolToOperation, isProtocolToolName } from '../../tasks/protocolRegistry.js';
+export { dispatchProtocolOp } from './protocolRunner.js';

package/src/server/tasks/paymentTools.ts

@@ -0,0 +1,156 @@
+import { defineTool, type ToolDefinition } from '../../tools/defineTool.js';
+import { ZiggsPayClient } from '../ziggspay/ZiggsPayClient.js';
+
+type Ctx = Record<string, unknown>;
+type AnyObj = Record<string, unknown>;
+
+function clientFor(ctx: Ctx): ZiggsPayClient {
+  const operatorKey = ctx?.['operatorKey'] as string | undefined;
+  if (!operatorKey) throw new Error('operatorKey missing from tool context');
+  return new ZiggsPayClient({ operatorKey, actAsAgentId: (ctx?.['agentId'] as string) || undefined });
+}
+
+interface PayError extends Error { status?: number; body?: string; }
+
+function rethrowWithContext(error: unknown, prefix: string): never {
+  const e = error as PayError;
+  const wrapped = new Error(`${prefix}: ${e.message}`) as PayError;
+  if (e.status !== undefined) wrapped.status = e.status;
+  if (e.body !== undefined) wrapped.body = e.body;
+  (wrapped as unknown as AnyObj)['cause'] = error;
+  throw wrapped;
+}
+
+function buildCaveats(args: AnyObj): AnyObj[] {
+  const caveats: AnyObj[] = [];
+  if (args['maxAmount'] != null) caveats.push({ type: 'max_amount', value: args['maxAmount'] });
+  if (args['dailyBudget'] != null) caveats.push({ type: 'daily_budget', value: args['dailyBudget'] });
+  if (args['allowedRecipients'] != null) caveats.push({ type: 'allowed_recipients', value: args['allowedRecipients'] });
+  if (args['expiresInSeconds'] != null) caveats.push({ type: 'expires_at', value: Date.now() + (args['expiresInSeconds'] as number) * 1000 });
+  return caveats;
+}
+
+export const paymentBalanceTool: ToolDefinition = defineTool('payment_balance', {},
+  async (_args, ctx) => {
+    try { return await clientFor(ctx as Ctx).balance(); }
+    catch (e) { rethrowWithContext(e, 'Failed to get balance'); }
+  },
+);
+
+export const paymentTransferTool: ToolDefinition = defineTool('payment_transfer',
+  { toWalletId: { type: 'string', required: true }, amount: { type: 'number', required: true }, description: 'string', idempotencyKey: 'string', capabilityTokenId: '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;
+    } 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'],
+        message: 'Transfer paused: the wallet owner must approve this amount.',
+        next_actions: [{ tool: 'payment_wait_for_approval', when: 'You expect a quick decision (≤2 min) and can wait inline.', args: { approvalId: result!['approvalId'], timeoutMs: 120000 } }, { tool: 'task_update_plan_step', when: 'You want to abandon the transfer and route around it.' }] };
+    }
+    return { status: 'transferred', transactionId: result!['transactionId'] || null, amount: args['amount'], toWalletId: result!['toWalletId'] };
+  },
+);
+
+export const paymentWaitForApprovalTool: ToolDefinition = defineTool('payment_wait_for_approval',
+  { approvalId: { type: 'string', required: true }, timeoutMs: 'number', pollMs: 'number' },
+  async (args, ctx) => {
+    if (!args['approvalId']) throw new Error('approvalId is required');
+    try {
+      const result = await clientFor(ctx as Ctx).waitForApproval(args['approvalId'] as string, { timeoutMs: args['timeoutMs'] as number | undefined, pollMs: args['pollMs'] as number | undefined }) as AnyObj;
+      return { status: result['status'], approvalId: args['approvalId'], transactionId: result['transactionId'] || null, approval: result['approval'] || null };
+    } catch (e) { rethrowWithContext(e, 'wait_for_approval failed'); }
+  },
+);
+
+export const paymentResolveWalletTool: ToolDefinition = defineTool('payment_resolve_wallet',
+  { userId: 'string', agentId: 'string' },
+  async (args, ctx) => {
+    if (!args['userId'] && !args['agentId']) throw new Error('Provide userId or agentId to resolve a wallet');
+    try {
+      const wallet = await clientFor(ctx as Ctx).resolve({ userId: args['userId'] as string | undefined, agentId: args['agentId'] as string | undefined }) as AnyObj | null;
+      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'); }
+  },
+);
+
+export const paymentHoldTool: ToolDefinition = defineTool('payment_hold',
+  { amount: { type: 'number', required: true }, description: 'string', idempotencyKey: 'string' },
+  async (args, ctx) => {
+    if (!args['amount'] || (args['amount'] as number) <= 0) throw new Error('amount must be positive');
+    try {
+      const result = await clientFor(ctx as Ctx).hold({ amount: Math.round(args['amount'] as number), description: (args['description'] as string) || 'Agent escrow hold', idempotencyKey: args['idempotencyKey'] as string | undefined }) as AnyObj;
+      return { status: 'held', transactionId: (result['transaction'] as AnyObj | undefined)?.['transactionId'] || null, amount: args['amount'] };
+    } catch (e) { rethrowWithContext(e, 'Hold failed'); }
+  },
+);
+
+export const paymentReleaseTool: ToolDefinition = defineTool('payment_release',
+  { holdId: { type: 'string', required: true }, action: { type: 'string', required: true }, toWalletId: 'string', idempotencyKey: 'string' },
+  async (args, ctx) => {
+    if (!args['holdId']) throw new Error('holdId is required');
+    if (args['action'] !== 'complete' && args['action'] !== 'refund') throw new Error("action must be 'complete' or 'refund'");
+    if (args['action'] === 'complete' && !args['toWalletId']) throw new Error('toWalletId is required when action=complete');
+    try {
+      const result = await clientFor(ctx as Ctx).release({ holdId: args['holdId'] as string, action: args['action'] as string, toWalletId: args['toWalletId'] as string | undefined, idempotencyKey: args['idempotencyKey'] as string | undefined }) as AnyObj;
+      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'); }
+  },
+);
+
+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'); }
+  },
+);
+
+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'); }
+  },
+);
+
+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'); }
+  },
+);
+
+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'); }
+  },
+);
+
+export const PAYMENT_TOOLS: ToolDefinition[] = [
+  paymentBalanceTool, paymentTransferTool, paymentWaitForApprovalTool,
+  paymentHoldTool, paymentReleaseTool, paymentResolveWalletTool,
+  paymentIssueTokenTool, paymentAttenuateTokenTool, paymentRevokeTokenTool, paymentListTokensTool,
+];

package/src/server/tasks/protocolRunner.ts

@@ -0,0 +1,101 @@
+import { normalizeState } from '../../tasks/taskCore.js';
+import type { AgreementService } from '../agreements/AgreementService.js';
+import type { TaskService } from './TaskService.js';
+
+interface Services {
+  agreementService: AgreementService;
+  taskService: TaskService;
+}
+
+interface ProtocolPayload {
+  operation?: string;
+  agreementId?: string;
+  description?: string;
+  proposedTo?: string;
+  executorId?: string;
+  action?: 'approve' | 'reject';
+  price?: number;
+  lifecycle?: string;
+  expiresAt?: string;
+  maxExecutions?: number;
+  agreementDescription?: string;
+  parentAgreementId?: string;
+  parentTaskId?: string;
+  taskId?: string;
+  status?: string;
+  result?: unknown;
+  plan?: unknown;
+  planReviewTiming?: string;
+  requireMidWorkPlanAck?: boolean;
+  engagementKind?: 'hire' | 'service';
+  subtasks?: (string | { description?: string })[];
+  [key: string]: unknown;
+}
+
+export async function dispatchProtocolOp(
+  services: Services,
+  payload: ProtocolPayload,
+  chatId: string | null,
+  agents: unknown[] = [],
+): Promise<unknown> {
+  if (!payload?.operation) return null;
+  const { operation } = payload;
+  const { agreementService, taskService } = services;
+
+  switch (operation) {
+    case 'agreement-propose':
+      return proposeAgreement(services, payload, chatId, agents);
+    case 'agreement-subcontract':
+      return subcontractAgreement(services, payload, chatId, agents);
+    case 'agreement-respond':
+      if (!payload.agreementId || !payload.action) return null;
+      return agreementService.respond(payload.agreementId, payload.action);
+    case 'agreement-counter-proposal':
+      if (!payload.agreementId) return null;
+      return agreementService.counter(payload.agreementId, {
+        price: payload.price,
+        agreementDescription: payload.agreementDescription,
+        expiresAt: payload.expiresAt,
+        lifecycle: payload.lifecycle,
+        maxExecutions: payload.maxExecutions,
+        description: payload.description,
+        plan: payload.plan,
+        planReviewTiming: payload.planReviewTiming as import('@ziggs-ai/api-client').PlanReviewTiming | undefined,
+        requireMidWorkPlanAck: payload.requireMidWorkPlanAck,
+      });
+    case 'agreement-check-proposal':
+      if (!payload.agreementId) return null;
+      return agreementService.getStatus(payload.agreementId);
+    case 'agreement-revoke':
+      if (!payload.agreementId) return null;
+      return agreementService.revoke(payload.agreementId);
+    case 'task-spawn':
+      if (!payload.agreementId || !payload.description) return null;
+      return taskService.spawnUnderAgreement(payload.agreementId, {
+        description: payload.description,
+        parentTaskId: payload.parentTaskId,
+        plan: payload.plan,
+        planReviewTiming: payload.planReviewTiming,
+        requireMidWorkPlanAck: payload.requireMidWorkPlanAck,
+      });
+    case 'task-update':
+      if (!payload.taskId || !payload.status) return null;
+      return taskService.updateState(payload.taskId, normalizeState(payload.status) as Parameters<typeof taskService.updateState>[1], payload.result);
+    default:
+      return null;
+  }
+}
+
+async function proposeAgreement(services: Services, payload: ProtocolPayload, chatId: string | null, _agents: unknown[]): Promise<unknown> {
+  if (!payload.description) throw new Error('agreement-propose requires `description`');
+  if (!payload.proposedTo) throw new Error('agreement-propose requires `proposedTo` (userId or agentId). To spawn a task under an existing agreement, use `task_spawn` instead.');
+  const { operation: _op, ...fields } = payload;
+  return services.agreementService.propose({ ...fields, chatId } as Parameters<typeof services.agreementService.propose>[0]);
+}
+
+async function subcontractAgreement(services: Services, payload: ProtocolPayload, chatId: string | null, _agents: unknown[]): Promise<unknown> {
+  if (!payload.description || !payload.executorId) return null;
+  const { operation: _op, ...fields } = payload;
+  return services.agreementService.delegate({ ...fields, chatId } as Parameters<typeof services.agreementService.delegate>[0]);
+}
+

package/src/server/tasks/protocolTools.ts

@@ -0,0 +1,96 @@
+import { defineTool, type ToolDefinition } from '../../tools/defineTool.js';
+import { dispatchProtocolOp } from './protocolRunner.js';
+import type { AgreementService } from '../agreements/AgreementService.js';
+import type { TaskService } from './TaskService.js';
+
+interface ToolContext extends Record<string, unknown> {
+  taskService: TaskService;
+  agreementService: AgreementService;
+  chatId?: string | null;
+  agents?: unknown[];
+}
+
+function handlerFor(operation: string) {
+  return async (args: Record<string, unknown>, ctx: Record<string, unknown>): Promise<unknown> => {
+    const c = ctx as ToolContext;
+    if (!c.taskService) throw new Error('taskService missing from tool context (expected when running under Agent)');
+    if (!c.agreementService) throw new Error('agreementService missing from tool context (expected when running under Agent)');
+    const result = await dispatchProtocolOp(
+      { taskService: c.taskService, agreementService: c.agreementService },
+      { operation, ...args },
+      c.chatId ?? null,
+      c.agents ?? [],
+    );
+    if (result == null) throw new Error(`Operation ${operation} returned no result`);
+    return result;
+  };
+}
+
+export const agreementProposeTool: ToolDefinition = 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 when omitted.' }, parentAgreementId: 'string', parentTaskId: 'string', payerId: 'string', providerId: 'string', price: 'number', lifecycle: 'string', expiresAt: 'string', maxExecutions: 'number', agreementDescription: 'string', plan: { type: 'object' }, planReviewTiming: 'string', requireMidWorkPlanAck: 'boolean' },
+  handlerFor('agreement-propose'),
+  { description: 'Propose a contract to a user, agent, or everyone (proposedTo="everyone" for open broadcast). engagementKind defaults to service.', isAgreementCreation: true },
+);
+
+export const agreementSubcontractTool: ToolDefinition = defineTool(
+  'agreement_subcontract',
+  { description: { type: 'string', required: true }, executorId: { type: 'string', required: true }, parentAgreementId: { type: 'string', required: true }, parentTaskId: 'string', payerId: 'string', price: 'number', lifecycle: 'string', expiresAt: 'string', maxExecutions: 'number', agreementDescription: 'string', plan: { type: 'object' }, planReviewTiming: 'string', requireMidWorkPlanAck: 'boolean' },
+  handlerFor('agreement-subcontract'),
+  { description: 'Delegate work to another agent under an existing parent agreement. Requires parentAgreementId.', isAgreementCreation: true },
+);
+
+export const agreementRespondTool: ToolDefinition = 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 agreement proposal.' },
+);
+
+export const taskUpdateTool: ToolDefinition = defineTool(
+  'task_update',
+  { taskId: { type: 'string', required: true }, status: { type: 'string', required: true, enum: ['completed', 'failed', 'cancelled'] }, result: 'string' },
+  handlerFor('task-update'),
+  { description: 'Transition a task to completed, failed, or cancelled. Include a result string for completed tasks.' },
+);
+
+export const agreementCounterProposalTool: ToolDefinition = defineTool(
+  'agreement_counter_proposal',
+  { agreementId: { type: 'string', required: true }, price: 'number', agreementDescription: 'string', expiresAt: 'string', lifecycle: 'string', maxExecutions: 'number', description: 'string', plan: { type: 'object' }, planReviewTiming: 'string', requireMidWorkPlanAck: 'boolean' },
+  handlerFor('agreement-counter-proposal'),
+  { description: 'Counter a pending proposal with revised terms instead of approving or rejecting. Check status first with agreement_check_proposal.' },
+);
+
+export const agreementCheckProposalTool: ToolDefinition = defineTool(
+  'agreement_check_proposal',
+  { agreementId: { type: 'string', required: true } },
+  handlerFor('agreement-check-proposal'),
+  { description: 'Read the current proposal status for an agreement (pending, approved, rejected, countered, expired).' },
+);
+
+export const agreementRevokeTool: ToolDefinition = 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 taskUpdatePlanStepTool: ToolDefinition = defineTool(
+  'task_update_plan_step',
+  { taskId: { type: 'string', required: true }, stepId: { type: 'string', required: true }, status: { type: 'string', required: true }, result: 'string' },
+  handlerFor('task-update-plan-step'),
+  { description: "Update the status of a single step within a task's plan." },
+);
+
+export const taskSpawnTool: ToolDefinition = defineTool(
+  'task_spawn',
+  { agreementId: { type: 'string', required: true }, description: { type: 'string', required: true }, parentTaskId: 'string', plan: { type: 'object' }, planReviewTiming: 'string', requireMidWorkPlanAck: 'boolean' },
+  handlerFor('task-spawn'),
+  { description: 'Spawn a new task under an existing approved agreement. Use when the contract is already in place.' },
+);
+
+export const PROTOCOL_TOOLS: ToolDefinition[] = [
+  agreementProposeTool, agreementSubcontractTool,
+  agreementRespondTool, agreementCounterProposalTool, agreementCheckProposalTool, agreementRevokeTool,
+  taskSpawnTool, taskUpdateTool, taskUpdatePlanStepTool,
+];

package/src/server/ziggspay/ZiggsPayClient.ts

@@ -0,0 +1,193 @@
+import 'dotenv/config';
+
+function getDefaultBaseUrl(): string {
+  return process.env.BACKEND_URL || process.env.ZIGGS_BACKEND_URL || 'http://localhost:3000';
+}
+
+function randomIdempotencyKey(prefix = 'op'): string {
+  return `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+
+function parseError(text: string, fallback: string): string {
+  if (!text) return fallback;
+  try {
+    const parsed = JSON.parse(text) as Record<string, unknown>;
+    return (parsed['error'] as string) || (parsed['message'] as string) || text;
+  } catch { return text; }
+}
+
+interface PayError extends Error { status?: number; body?: string; }
+
+export interface ZiggsPayClientOptions {
+  operatorKey: string;
+  actAsAgentId?: string;
+  baseUrl?: string;
+}
+
+export class ZiggsPayClient {
+  private operatorKey: string;
+  private actAsAgentId: string | null;
+  private baseUrl: string;
+
+  constructor({ operatorKey, actAsAgentId, baseUrl }: ZiggsPayClientOptions) {
+    if (!operatorKey || typeof operatorKey !== 'string') throw new Error('ZiggsPayClient requires an operatorKey');
+    this.operatorKey = operatorKey;
+    this.actAsAgentId = actAsAgentId || null;
+    this.baseUrl = baseUrl || getDefaultBaseUrl();
+  }
+
+  async balance(): Promise<{ walletId: string | null; currency: string; balance: number; availableBalance: number }> {
+    const w = await this._get('/payments/wallet') as Record<string, unknown>;
+    const wallet = w['wallet'] as Record<string, unknown> | undefined;
+    return { walletId: (wallet?.['walletId'] as string) || null, currency: (wallet?.['currency'] as string) || 'pez', balance: (w['balance'] as number) ?? 0, availableBalance: (w['availableBalance'] as number) ?? 0 };
+  }
+
+  async resolve({ userId, agentId }: { userId?: string; agentId?: string } = {}): Promise<unknown> {
+    if (!userId && !agentId) throw new Error('resolve: provide userId or agentId');
+    const params = new URLSearchParams();
+    if (userId) params.set('userId', userId);
+    if (agentId) params.set('agentId', agentId);
+    const res = await this._get(`/payments/wallets/resolve?${params}`) as Record<string, unknown>;
+    return res['wallet'] || null;
+  }
+
+  async transfer({ to, amount, idempotencyKey, description, capabilityTokenId }: { to: string; amount: number; idempotencyKey?: string; description?: string; capabilityTokenId?: 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.');
+    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>;
+    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 };
+    }
+    const tx = result?.['transaction'] as Record<string, unknown> | undefined;
+    return { status: 'transferred', transactionId: tx?.['transactionId'] || null, toWalletId, amount };
+  }
+
+  async hold({ amount, idempotencyKey, description }: { amount: number; idempotencyKey?: string; description?: string }): Promise<unknown> {
+    if (!(Number.isInteger(amount) && amount > 0)) throw new Error('hold: `amount` must be a positive integer (cents)');
+    return this._post('/payments/hold', { amount, idempotencyKey: idempotencyKey || randomIdempotencyKey('hold'), description });
+  }
+
+  async release({ holdId, action = 'complete', toWalletId, idempotencyKey }: { holdId: string; action?: string; toWalletId?: string; idempotencyKey?: string }): Promise<unknown> {
+    return this._post(`/payments/release/${holdId}`, { idempotencyKey: idempotencyKey || randomIdempotencyKey('rel'), action, toWalletId });
+  }
+
+  async history(params: { limit?: number; offset?: number; type?: string } = {}): Promise<unknown> {
+    const q = new URLSearchParams();
+    if (params.limit != null) q.set('limit', String(params.limit));
+    if (params.offset != null) q.set('offset', String(params.offset));
+    if (params.type) q.set('type', params.type);
+    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 attenuateToken({ tokenId, holderId, caveats }: { tokenId: string; holderId: string; caveats?: unknown }): Promise<unknown> {
+    return this._post(`/payments/tokens/${tokenId}/attenuate`, { holderId, caveats });
+  }
+
+  async revokeToken(tokenId: string): Promise<unknown> {
+    return this._request('DELETE', `/payments/tokens/${tokenId}`, undefined);
+  }
+
+  async listTokens(): Promise<unknown[]> {
+    const res = await this._get('/payments/tokens') as Record<string, unknown>;
+    return (res['tokens'] as unknown[]) || [];
+  }
+
+  async createTopUpIntent({ amount, description, currency }: { amount?: number; description?: string; currency?: string } = {}): Promise<unknown> {
+    return this._post('/payments/onramp/intent', { amount, description, currency });
+  }
+
+  async confirmMockIntent(intentId: string): Promise<unknown> {
+    return this._post(`/payments/onramp/mock-confirm/${intentId}`, {});
+  }
+
+  async faucet({ amount, description = 'Faucet', idempotencyKey }: { amount?: number; description?: string; idempotencyKey?: string } = {}): Promise<unknown> {
+    return this._post('/payments/wallet/fund', { amount, idempotencyKey: idempotencyKey || randomIdempotencyKey('faucet'), description });
+  }
+
+  async approvals({ status = 'pending' }: { status?: string } = {}): Promise<unknown[]> {
+    const res = await this._get(`/payments/approvals?status=${encodeURIComponent(status)}`) as Record<string, unknown>;
+    return (res['approvals'] as unknown[]) || [];
+  }
+
+  async getApproval(approvalId: string): Promise<unknown | null> {
+    if (!approvalId) throw new Error('getApproval: approvalId is required');
+    try {
+      const res = await this._get(`/payments/approvals/${approvalId}`) as Record<string, unknown>;
+      return res?.['approval'] || null;
+    } catch (err) {
+      if ((err as PayError).status === 404) return null;
+      throw err;
+    }
+  }
+
+  async decide(approvalId: string, decision: string, note = ''): Promise<unknown> {
+    return this._post(`/payments/approvals/${approvalId}/decide`, { decision, note });
+  }
+
+  async waitForApproval(approvalId: string, opts: { pollMs?: number; timeoutMs?: number; signal?: AbortSignal } = {}): Promise<unknown> {
+    const pollMs = Math.max(500, opts.pollMs ?? 3_000);
+    const timeoutMs = Math.max(pollMs, opts.timeoutMs ?? 120_000);
+    const signal = opts.signal;
+    const deadline = Date.now() + timeoutMs;
+
+    const sleep = (ms: number) => new Promise<void>((resolve, reject) => {
+      const timer = setTimeout(resolve, ms);
+      if (signal) {
+        if (signal.aborted) { clearTimeout(timer); reject(new Error('aborted')); return; }
+        signal.addEventListener('abort', () => { clearTimeout(timer); reject(new Error('aborted')); }, { once: true });
+      }
+    });
+
+    while (true) {
+      if (signal?.aborted) throw new Error('aborted');
+      const approval = await this.getApproval(approvalId) as Record<string, unknown> | null;
+      if (!approval) return { status: 'gone' };
+      const s = approval['status'];
+      if (s === 'executed') return { status: 'executed', approval, transactionId: approval['executedTransactionId'] || null };
+      if (s === 'rejected') return { status: 'rejected', approval };
+      if (s === 'expired') return { status: 'expired', approval };
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) return { status: 'timeout', approval };
+      await sleep(Math.min(pollMs, remaining));
+    }
+  }
+
+  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 PayError;
+      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 createZiggsPayClient(opts: ZiggsPayClientOptions): ZiggsPayClient {
+  return new ZiggsPayClient(opts);
+}