@ziggs-ai/agent-sdk 0.1.3 → 0.1.5

package/src/server/runLauncher.ts

@@ -0,0 +1,146 @@
+import { ConnectionPool } from './ConnectionPool.js';
+import { AgentHost, type AgentHostOptions } from '../AgentHost.js';
+import { createHealthServer } from './createHealthServer.js';
+import { runtimeLog } from '../shared/runtimeLog.js';
+import type { Server } from 'http';
+
+type AgentConfig = AgentHostOptions & {
+  ownAgentId?: string;
+  options?: { ownAgentId?: string; name?: string };
+};
+
+interface SingleOptions {
+  operatorKey?: string;
+  label?: string;
+  port?: number | string;
+  healthServer?: boolean;
+  onShutdown?: () => Promise<void>;
+}
+
+interface FleetOptions extends SingleOptions {
+  wsUrl?: string;
+  agentMeta?: Record<string, unknown>[];
+  primary?: AgentConfig | ((pool: ConnectionPool) => AgentConfig);
+  preWake?: string[];
+  poolOptions?: { maxActive?: number; idleTimeoutMs?: number };
+}
+
+export async function runLauncher(
+  configOrConfigs: AgentConfig | AgentConfig[],
+  opts: FleetOptions = {},
+): Promise<unknown> {
+  if (Array.isArray(configOrConfigs)) return runFleet(configOrConfigs, opts);
+  return runSingle(configOrConfigs, opts as SingleOptions);
+}
+
+async function runSingle(
+  config: AgentConfig,
+  { operatorKey, label = 'agent', port = process.env.PORT || 8080, healthServer = true, onShutdown }: SingleOptions = {},
+): Promise<{ agent: unknown; healthServer?: Server }> {
+  const effectiveKey = operatorKey ?? process.env.ZIGGS_OPERATOR_KEY;
+  const decorated = effectiveKey && !config.operatorKey ? { ...config, operatorKey: effectiveKey } : config;
+  const agent = new AgentHost(decorated);
+  try {
+    await agent.connectAsync();
+    runtimeLog.info(
+      label,
+      `"${(agent as unknown as Record<string, unknown>)['options'] ? ((agent as unknown as Record<string, {agentId?: string; name?: string | null}>)['options']?.agentId ?? (agent as unknown as Record<string, {name?: string | null}>)['options']?.name) : 'agent'}" connected`,
+    );
+  } catch (err) {
+    runtimeLog.warn(label, `Agent failed to connect at startup: ${(err as Error).message} — will retry`);
+  }
+
+  const server = healthServer ? createHealthServer({ port: Number(port), label }) : null;
+
+  process.on('SIGTERM', async () => {
+    runtimeLog.info(label, 'SIGTERM — shutting down');
+    agent.disconnect();
+    await agent.drain(30_000);
+    try {
+      await onShutdown?.();
+    } catch (err) {
+      runtimeLog.warn(label, `onShutdown error: ${(err as Error).message}`);
+    }
+    server?.close();
+    process.exit(0);
+  });
+
+  return { agent, healthServer: server ?? undefined };
+}
+
+async function runFleet(
+  configs: AgentConfig[],
+  {
+    operatorKey, wsUrl = process.env.WS_URL, port = process.env.PORT || 8080,
+    healthServer = true, label = 'launcher', agentMeta,
+    primary: primaryConfig, preWake = [], poolOptions, onShutdown,
+  }: FleetOptions = {},
+): Promise<{ pool: ConnectionPool; primary: unknown; healthServer?: Server }> {
+  const pool = new ConnectionPool(poolOptions);
+  const effectiveKey = operatorKey ?? process.env.ZIGGS_OPERATOR_KEY;
+  const decoratedConfigs = effectiveKey
+    ? configs.map(c => (c.operatorKey ? c : { ...c, operatorKey: effectiveKey }))
+    : configs;
+  pool.register(decoratedConfigs, agentMeta as Record<string, unknown>[]);
+  const server = healthServer ? createHealthServer({ port: Number(port), label, pool }) : null;
+
+  let resolvedPrimaryConfig: AgentConfig | undefined = typeof primaryConfig === 'function'
+    ? primaryConfig(pool)
+    : primaryConfig;
+  if (resolvedPrimaryConfig && effectiveKey && !resolvedPrimaryConfig.operatorKey) {
+    resolvedPrimaryConfig = { ...resolvedPrimaryConfig, operatorKey: effectiveKey };
+  }
+
+  const controlKey = effectiveKey ?? configs.find(c => c.operatorKey)?.operatorKey ?? resolvedPrimaryConfig?.operatorKey;
+  if (controlKey) {
+    pool.startControl({ wsUrl, operatorKey: controlKey });
+  } else {
+    runtimeLog.warn(label, 'No operatorKey provided — skipping control socket');
+  }
+
+  let primary: unknown = null;
+  if (resolvedPrimaryConfig) {
+    primary = new AgentHost(resolvedPrimaryConfig);
+    try {
+      await (primary as { connectAsync: () => Promise<void> }).connectAsync();
+      runtimeLog.info(
+        label,
+        `Primary agent "${resolvedPrimaryConfig.name || resolvedPrimaryConfig.ownAgentId || 'primary'}" connected`,
+      );
+    } catch (err) {
+      // Backend may not be ready yet — socket.io reconnects automatically.
+      // Don't crash the process; the primary agent will be live once it reconnects.
+      runtimeLog.warn(
+        label,
+        `Primary agent "${resolvedPrimaryConfig.name || resolvedPrimaryConfig.ownAgentId || 'primary'}" failed to connect at startup: ${(err as Error).message} — will retry`,
+      );
+    }
+  }
+
+  if (preWake.length > 0) {
+    await Promise.all(preWake.map(id =>
+      pool.wake(id)
+        .then(() => runtimeLog.debug(label, `Pre-woke "${id}"`))
+        .catch(err => runtimeLog.warn(label, `Could not pre-wake "${id}": ${(err as Error).message}`)),
+    ));
+  }
+
+  runtimeLog.info(label, `Ready — ${pool.size} agent(s) registered, ${pool.listActive().length} connected`);
+
+  process.on('SIGTERM', async () => {
+    runtimeLog.info(label, 'SIGTERM — shutting down');
+    pool.stopControl();
+    (primary as { disconnect?: () => void })?.disconnect?.();
+    await (primary as { drain?: (ms: number) => Promise<void> })?.drain?.(30_000);
+    await pool.disconnectAll();
+    try {
+      await onShutdown?.();
+    } catch (err) {
+      runtimeLog.warn(label, `onShutdown error: ${(err as Error).message}`);
+    }
+    server?.close();
+    process.exit(0);
+  });
+
+  return { pool, primary, healthServer: server ?? undefined };
+}

package/src/server/tasks/TaskService.ts

@@ -0,0 +1,110 @@
+import {
+  createTask, getTask, getActiveTasksForAgent, getActiveTasksForChat, getSubtasks,
+  updateTaskState, cancelTask,
+  claimLedgerTask, reportTask, setTaskSatisfaction, countTasks,
+  type Creds, type Task, type TaskState,
+} from '@ziggs-ai/api-client';
+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: TaskState, 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<Task> {
+    try {
+      const task = await claimLedgerTask(taskId, this.creds);
+      runtimeLog.info('TaskService', `[ledger] Claimed task ${taskId}`);
+      return task as unknown as Task;
+    } 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 @@
+export { TaskService } from './TaskService.js';

package/src/server/telemetryIngest.ts

@@ -0,0 +1,91 @@
+import type { LlmResponse } from '../types.js';
+import type { TelemetryClient } from '@ziggs-ai/api-client';
+
+export function isTelemetryIngestEnabled(
+  explicit?: boolean,
+): boolean {
+  if (explicit === false) return false;
+  if (explicit === true) return true;
+  const env = process.env.ZIGGS_TELEMETRY_INGEST;
+  if (env === '0' || env === 'false') return false;
+  return true;
+}
+
+export function usageFromLlmResponse(response: LlmResponse): {
+  tokensTotal: number;
+  tokensInput: number;
+  tokensOutput: number;
+} {
+  const u = response.usage;
+  const tokensInput =
+    Number(u?.prompt_tokens ?? u?.promptTokens ?? 0) || 0;
+  const tokensOutput =
+    Number(u?.completion_tokens ?? u?.completionTokens ?? 0) || 0;
+  const tokensTotal =
+    Number(u?.total_tokens ?? u?.totalTokens ?? 0) ||
+    tokensInput + tokensOutput;
+  return { tokensTotal, tokensInput, tokensOutput };
+}
+
+export function buildLlmIngestPayload(
+  response: LlmResponse,
+  ctx: { sessionId?: string; durationMs: number; runId?: string; stateId?: string },
+): Record<string, unknown> {
+  const { tokensTotal, tokensInput, tokensOutput } =
+    usageFromLlmResponse(response);
+  const chatId = ctx.sessionId ?? null;
+  return {
+    source: 'agent',
+    chatId,
+    sessionId: chatId,
+    execution: {
+      llmCallsTotal: 1,
+      tokensTotal,
+      tokensInput,
+      tokensOutput,
+      ...(tokensTotal > 0 ? { tokensPerLlmCall: [tokensTotal] } : {}),
+    },
+    resource: { durationMs: Math.max(0, Math.round(ctx.durationMs)) },
+    meta: {
+      effect: 'llm-call',
+      ...(ctx.runId ? { runId: ctx.runId } : {}),
+      ...(ctx.stateId ? { stateId: ctx.stateId } : {}),
+    },
+  };
+}
+
+export function buildToolIngestPayload(
+  ctx: {
+    sessionId: string;
+    tool: string;
+    durationMs: number;
+    ok: boolean;
+    runId?: string;
+    stateId?: string;
+  },
+): Record<string, unknown> {
+  return {
+    source: 'agent',
+    chatId: ctx.sessionId,
+    sessionId: ctx.sessionId,
+    execution: { executionLoops: 1 },
+    resource: { durationMs: Math.max(0, Math.round(ctx.durationMs)) },
+    meta: {
+      effect: 'tool-call',
+      tool: ctx.tool,
+      ok: ctx.ok,
+      ...(ctx.runId ? { runId: ctx.runId } : {}),
+      ...(ctx.stateId ? { stateId: ctx.stateId } : {}),
+    },
+  };
+}
+
+/** Fire-and-forget; never throws to the effect handler. */
+export function sendTelemetry(
+  client: TelemetryClient | undefined,
+  payload: Record<string, unknown>,
+  enabled: boolean,
+): void {
+  if (!enabled || !client) return;
+  void client.send(payload).catch(() => {});
+}

package/src/server/tools/index.ts

@@ -0,0 +1,46 @@
+/**
+ * Agent tool bundles, in two tiers. Single home for everything an agent can
+ * "speak" or "do" over the wire.
+ *
+ * Tier 1 — protocol grammar (tier1/). The verbs every agent uses to participate
+ * in the agreement/task system. Framework-managed: attached via the `taskTools`
+ * config (default 'all'), dispatched to in-process services (taskService /
+ * agreementService) injected into tool context — NOT passed in the user `tools:`
+ * array. Publishing open work is part of this grammar:
+ * agreement_propose({ proposedTo: "everyone" }) — there is no separate publish tool.
+ *
+ * Tier 2 — capability bundles (tier2/). Opt-in, HTTP-backed tool bundles an agent
+ * chooses to have. Off by default; an agent gains a bundle by spreading it into
+ * its `tools:` array. Each tool reads operatorKey/agentId from tool context and
+ * wraps a backend HTTP client — no per-agent plumbing.
+ */
+
+// ── Tier 1: protocol grammar ────────────────────────────────────────────────
+export {
+  PROTOCOL_TOOLS,
+  agreementProposeTool, agreementSubcontractTool, agreementRespondTool,
+  agreementCounterProposalTool, agreementCheckProposalTool, agreementRevokeTool,
+  taskSpawnTool, taskUpdateTool, taskUpdatePlanStepTool,
+} from './tier1/protocolTools.js';
+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,
+  paymentIssueTokenTool, paymentAttenuateTokenTool, paymentRevokeTokenTool, paymentListTokensTool,
+} from './tier2/paymentTools.js';
+export {
+  CONNECTION_TOOLS,
+  connectionProxyTool,
+  connectionListGrantsTool,
+} from './tier2/connectionTools.js';
+export {
+  CONTEXT_TOOLS,
+  contextDiscoverTool,
+  contextListGrantsTool,
+  contextDelegateTool,
+} from './tier2/contextTools.js';

package/src/server/tools/tier1/protocolRunner.ts

@@ -0,0 +1,133 @@
+import type { AgreementService } from '../../agreements/AgreementService.js';
+import type { TaskService } from '../../tasks/TaskService.js';
+import {
+  applyFleetCounterPricing,
+  applyFleetPricingForProtocol,
+} from '../../../pricing/fleetDefaults.js';
+
+// Map legacy task-state aliases onto the canonical set.
+function normalizeState(state: string): string {
+  if (state === 'done') return 'completed';
+  if (state === 'error') return 'failed';
+  return state;
+}
+
+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[] = [],
+  actingAgentId: string | null = null,
+): Promise<unknown> {
+  if (!payload?.operation) return null;
+  const { operation } = payload;
+  const { agreementService, taskService } = services;
+  const actorId = actingAgentId?.trim() || null;
+
+  switch (operation) {
+    case 'agreement-propose':
+      return proposeAgreement(services, payload, chatId, agents, actorId);
+    case 'agreement-subcontract':
+      return subcontractAgreement(services, payload, chatId, agents, actorId);
+    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;
+      {
+        const counterPayload =
+          actorId != null
+            ? applyFleetCounterPricing(payload, actorId)
+            : payload;
+        return agreementService.counter(payload.agreementId, {
+          price: counterPayload.price,
+          agreementDescription: counterPayload.agreementDescription,
+          expiresAt: counterPayload.expiresAt,
+          lifecycle: counterPayload.lifecycle,
+          maxExecutions: counterPayload.maxExecutions,
+          description: counterPayload.description,
+          plan: counterPayload.plan,
+          planReviewTiming: counterPayload.planReviewTiming as import('@ziggs-ai/api-client').PlanReviewTiming | undefined,
+          requireMidWorkPlanAck: counterPayload.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[],
+  actingAgentId: string | null,
+): 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 priced = applyFleetPricingForProtocol('agreement-propose', payload, actingAgentId);
+  const { operation: _op, ...fields } = priced;
+  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[],
+  actingAgentId: string | null,
+): Promise<unknown> {
+  if (!payload.description || !payload.executorId) return null;
+  const priced = applyFleetPricingForProtocol('agreement-subcontract', payload, actingAgentId);
+  const { operation: _op, ...fields } = priced;
+  return services.agreementService.delegate({ ...fields, chatId } as Parameters<typeof services.agreementService.delegate>[0]);
+}
+

package/src/server/tools/tier1/protocolTools.ts

@@ -0,0 +1,99 @@
+import { defineTool, type ToolDefinition } from '../../../tools/defineTool.js';
+import { dispatchProtocolOp } from './protocolRunner.js';
+import type { AgreementService } from '../../agreements/AgreementService.js';
+import type { TaskService } from '../../tasks/TaskService.js';
+
+interface ToolContext extends Record<string, unknown> {
+  taskService: TaskService;
+  agreementService: AgreementService;
+  chatId?: string | null;
+  agents?: unknown[];
+  /** Acting agent (ZIG-368 default pricing). */
+  agentId?: string;
+}
+
+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 ?? [],
+      typeof c.agentId === 'string' ? c.agentId : null,
+    );
+    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,
+];