@ziggs-ai/agent-sdk 0.1.4 → 0.1.6

package/src/server/runLauncher.ts

@@ -20,7 +20,7 @@ interface SingleOptions {
 interface FleetOptions extends SingleOptions {
   wsUrl?: string;
   agentMeta?: Record<string, unknown>[];
-  orchestrator?: AgentConfig | ((pool: ConnectionPool) => AgentConfig);
+  primary?: AgentConfig | ((pool: ConnectionPool) => AgentConfig);
   preWake?: string[];
   poolOptions?: { maxActive?: number; idleTimeoutMs?: number };
 }
@@ -40,17 +40,22 @@ async function runSingle(
   const effectiveKey = operatorKey ?? process.env.ZIGGS_OPERATOR_KEY;
   const decorated = effectiveKey && !config.operatorKey ? { ...config, operatorKey: effectiveKey } : config;
   const agent = new AgentHost(decorated);
-  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`,
-  );
+  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) {
@@ -68,39 +73,48 @@ async function runFleet(
   {
     operatorKey, wsUrl = process.env.WS_URL, port = process.env.PORT || 8080,
     healthServer = true, label = 'launcher', agentMeta,
-    orchestrator: orchestratorConfig, preWake = [], poolOptions, onShutdown,
+    primary: primaryConfig, preWake = [], poolOptions, onShutdown,
   }: FleetOptions = {},
-): Promise<{ pool: ConnectionPool; orchestrator: unknown; healthServer?: Server }> {
+): 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 }) : null;
+  const server = healthServer ? createHealthServer({ port: Number(port), label, pool }) : null;
 
-  let resolvedOrchConfig: AgentConfig | undefined = typeof orchestratorConfig === 'function'
-    ? orchestratorConfig(pool)
-    : orchestratorConfig;
-  if (resolvedOrchConfig && effectiveKey && !resolvedOrchConfig.operatorKey) {
-    resolvedOrchConfig = { ...resolvedOrchConfig, operatorKey: effectiveKey };
+  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 ?? resolvedOrchConfig?.operatorKey;
+  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 orchestrator: unknown = null;
-  if (resolvedOrchConfig) {
-    orchestrator = new AgentHost(resolvedOrchConfig);
-    await (orchestrator as { connectAsync: () => Promise<void> }).connectAsync();
-    runtimeLog.info(
-      label,
-      `Orchestrator "${resolvedOrchConfig.name || resolvedOrchConfig.ownAgentId || 'orchestrator'}" connected`,
-    );
+  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) {
@@ -116,7 +130,8 @@ async function runFleet(
   process.on('SIGTERM', async () => {
     runtimeLog.info(label, 'SIGTERM — shutting down');
     pool.stopControl();
-    (orchestrator as { disconnect?: () => void })?.disconnect?.();
+    (primary as { disconnect?: () => void })?.disconnect?.();
+    await (primary as { drain?: (ms: number) => Promise<void> })?.drain?.(30_000);
     await pool.disconnectAll();
     try {
       await onShutdown?.();
@@ -127,5 +142,5 @@ async function runFleet(
     process.exit(0);
   });
 
-  return { pool, orchestrator, healthServer: server ?? undefined };
+  return { pool, primary, healthServer: server ?? undefined };
 }

package/src/server/tasks/TaskService.ts

@@ -2,9 +2,8 @@ import {
   createTask, getTask, getActiveTasksForAgent, getActiveTasksForChat, getSubtasks,
   updateTaskState, cancelTask,
   claimLedgerTask, reportTask, setTaskSatisfaction, countTasks,
-  type Creds, type Task,
+  type Creds, type Task, type TaskState,
 } 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';
 
@@ -63,7 +62,7 @@ export class TaskService {
     }
   }
 
-  async updateState(taskId: string, state: TaskStateValue, result?: unknown): Promise<Task> {
+  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);
@@ -86,11 +85,11 @@ export class TaskService {
     }
   }
 
-  async claimLedgerTask(taskId: string): Promise<TaskWithFlags> {
+  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 TaskWithFlags;
+      return task as unknown as Task;
     } catch (error) {
       runtimeLog.warn('TaskService', `[ledger] Claim failed for ${taskId}: ${(error as Error).message}`);
       throw error;

package/src/server/tasks/index.ts

@@ -1,4 +1 @@
 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/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/{tasks → tools/tier1}/protocolRunner.ts

@@ -1,6 +1,16 @@
-import { normalizeState } from '../../tasks/taskCore.js';
-import type { AgreementService } from '../agreements/AgreementService.js';
-import type { TaskService } from './TaskService.js';
+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;
@@ -37,32 +47,40 @@ export async function dispatchProtocolOp(
   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);
+      return proposeAgreement(services, payload, chatId, agents, actorId);
     case 'agreement-subcontract':
-      return subcontractAgreement(services, payload, chatId, agents);
+      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;
-      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,
-      });
+      {
+        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);
@@ -86,16 +104,30 @@ export async function dispatchProtocolOp(
   }
 }
 
-async function proposeAgreement(services: Services, payload: ProtocolPayload, chatId: string | null, _agents: unknown[]): Promise<unknown> {
+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 { operation: _op, ...fields } = payload;
+  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[]): Promise<unknown> {
+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 { operation: _op, ...fields } = payload;
+  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/{tasks → tools/tier1}/protocolTools.ts

@@ -1,13 +1,15 @@
-import { defineTool, type ToolDefinition } from '../../tools/defineTool.js';
+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';
+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) {
@@ -20,6 +22,7 @@ function handlerFor(operation: string) {
       { 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;

package/src/server/tools/tier2/connectionTools.ts

@@ -0,0 +1,75 @@
+import { defineTool, type ToolDefinition } from '../../../tools/defineTool.js';
+import { ZiggsConnectClient } from '../../ziggsconnect/ZiggsConnectClient.js';
+
+type Ctx = Record<string, unknown>;
+type AnyObj = Record<string, unknown>;
+
+interface ConnectError extends Error {
+  status?: number;
+  body?: string;
+}
+
+function clientFor(ctx: Ctx): ZiggsConnectClient {
+  const operatorKey = ctx?.['operatorKey'] as string | undefined;
+  if (!operatorKey) throw new Error('operatorKey missing from tool context');
+  return new ZiggsConnectClient({
+    operatorKey,
+    actAsAgentId: (ctx?.['agentId'] as string) || undefined,
+  });
+}
+
+function rethrowWithContext(error: unknown, prefix: string): never {
+  const e = error as ConnectError;
+  const wrapped = new Error(`${prefix}: ${e.message}`) as ConnectError;
+  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;
+}
+
+export const connectionProxyTool: ToolDefinition = defineTool(
+  'connection_proxy',
+  {
+    connectionId: { type: 'string', required: true },
+    grantId: { type: 'string', required: true },
+    action: { type: 'string', required: true },
+    payload: { type: 'object' },
+  },
+  async (args, ctx) => {
+    if (!args['connectionId']) throw new Error('connectionId is required');
+    if (!args['grantId']) throw new Error('grantId is required');
+    if (!args['action']) throw new Error('action is required');
+    try {
+      const result = await clientFor(ctx as Ctx).proxy({
+        connectionId: args['connectionId'] as string,
+        grantId: args['grantId'] as string,
+        action: args['action'] as string,
+        payload: args['payload'],
+      });
+      return { status: 'ok', result };
+    } catch (e) {
+      rethrowWithContext(e, 'Connection proxy failed');
+    }
+  },
+);
+
+export const connectionListGrantsTool: ToolDefinition = defineTool(
+  'connection_list_grants',
+  { connectionId: { type: 'string', required: true } },
+  async (args, ctx) => {
+    if (!args['connectionId']) throw new Error('connectionId is required');
+    try {
+      const grants = await clientFor(ctx as Ctx).listGrants({
+        connectionId: args['connectionId'] as string,
+      });
+      return { grants: grants || [] };
+    } catch (e) {
+      rethrowWithContext(e, 'Failed to list connection grants');
+    }
+  },
+);
+
+export const CONNECTION_TOOLS: ToolDefinition[] = [
+  connectionProxyTool,
+  connectionListGrantsTool,
+];

package/src/server/tools/tier2/contextTools.ts

@@ -0,0 +1,74 @@
+import { defineTool, type ToolDefinition } from '../../../tools/defineTool.js';
+import { ZiggsContextClient } from '../../ziggscontext/ZiggsContextClient.js';
+
+type Ctx = Record<string, unknown>;
+
+function clientFor(ctx: Ctx): ZiggsContextClient {
+  const operatorKey = ctx?.['operatorKey'] as string | undefined;
+  if (!operatorKey) throw new Error('operatorKey missing from tool context');
+  return new ZiggsContextClient({
+    operatorKey,
+    actAsAgentId: (ctx?.['agentId'] as string) || undefined,
+  });
+}
+
+export const contextDiscoverTool: ToolDefinition = defineTool(
+  'context_discover',
+  {},
+  async (_args, ctx) => clientFor(ctx as Ctx).discover(),
+  {
+    description:
+      'List which chats, agreements, and org scopes this agent can reach via context grants (descriptors only — no message or artifact content).',
+  },
+);
+
+export const contextListGrantsTool: ToolDefinition = defineTool(
+  'context_list_grants',
+  {},
+  async (_args, ctx) => clientFor(ctx as Ctx).listGrants(),
+  {
+    description:
+      'List context grants held by this agent (grant ids and bounds). Does not fetch scoped content.',
+  },
+);
+
+export const contextDelegateTool: ToolDefinition = defineTool(
+  'context_delegate',
+  {
+    parentGrantId: { type: 'string', required: true },
+    holderId: { type: 'string', required: true },
+    scopeKind: { type: 'string', required: true },
+    scopeId: { type: 'string', required: true },
+    temporal: { type: 'string', required: true },
+    expiresAt: 'string',
+    watermarkAt: 'string',
+  },
+  async (args, ctx) => {
+    const temporal = args['temporal'] as string;
+    if (temporal !== 'from-now' && temporal !== 'from-start') {
+      throw new Error('temporal must be from-now or from-start');
+    }
+    const scopeKind = args['scopeKind'] as string;
+    if (scopeKind !== 'chat' && scopeKind !== 'agreement' && scopeKind !== 'org') {
+      throw new Error('scopeKind must be chat, agreement, or org');
+    }
+    return clientFor(ctx as Ctx).delegate({
+      parentGrantId: args['parentGrantId'] as string,
+      holderId: args['holderId'] as string,
+      scope: { kind: scopeKind as 'chat' | 'agreement' | 'org', id: args['scopeId'] as string },
+      temporal,
+      expiresAt: (args['expiresAt'] as string | undefined) ?? undefined,
+      watermarkAt: args['watermarkAt'] as string | undefined,
+    });
+  },
+  {
+    description:
+      'Delegate a narrower child context grant (tighter scope, shorter expiry, or from-now). Holder-only.',
+  },
+);
+
+export const CONTEXT_TOOLS = [
+  contextDiscoverTool,
+  contextListGrantsTool,
+  contextDelegateTool,
+] as const;

package/src/server/tools/tier2/discoveryTools.ts

@@ -0,0 +1,34 @@
+import { defineTool, type ToolDefinition } from '../../../tools/defineTool.js';
+import { AgentSearchClient } from '@ziggs-ai/api-client';
+
+type Ctx = Record<string, unknown>;
+
+function clientFor(ctx: Ctx): AgentSearchClient {
+  const operatorKey = ctx?.['operatorKey'] as string | undefined;
+  const agentId = ctx?.['agentId'] as string | undefined;
+  if (!operatorKey) throw new Error('operatorKey missing from tool context');
+  if (!agentId) throw new Error('agentId missing from tool context');
+  return new AgentSearchClient(operatorKey, agentId);
+}
+
+export const agentSearchTool: ToolDefinition = defineTool('agent_search',
+  { query: { type: 'string', required: true }, limit: 'number' },
+  async (args, ctx) => {
+    if (!args['query']) throw new Error('query is required');
+    const options: { limit?: number } = {};
+    if (typeof args['limit'] === 'number') options.limit = args['limit'] as number;
+    return clientFor(ctx as Ctx).searchAgents(args['query'] as string, options);
+  },
+  { description: 'Search for agents by capability, name, or description. Returns ranked results with relevance scores. Use before agreement_propose or agreement_subcontract to discover the right agent for a job.', isGenericFallback: true },
+);
+
+export const agentGetTool: ToolDefinition = defineTool('agent_get',
+  { agentId: { type: 'string', required: true } },
+  async (args, ctx) => {
+    if (!args['agentId']) throw new Error('agentId is required');
+    return clientFor(ctx as Ctx).getAgentById(args['agentId'] as string);
+  },
+  { description: 'Fetch the full profile of a specific agent by ID. Use to confirm capabilities and terms before proposing an agreement.' },
+);
+
+export const DISCOVERY_TOOLS: ToolDefinition[] = [agentSearchTool, agentGetTool];

package/src/server/tools/tier2/marketplaceTools.ts

@@ -0,0 +1,25 @@
+import { defineTool, type ToolDefinition } from '../../../tools/defineTool.js';
+import { pullFromLedger } from '@ziggs-ai/api-client';
+
+type Ctx = Record<string, unknown>;
+
+// Read-only marketplace access. Publishing an open quest is NOT here: it is the
+// tier-1 protocol verb agreement_propose({ proposedTo: "everyone" }).
+export const marketplaceViewTool: ToolDefinition = defineTool('marketplace_view',
+  { limit: 'number', since: 'string' },
+  async (args, ctx) => {
+    const operatorKey = (ctx as Ctx)?.['operatorKey'] as string | undefined;
+    const agentId = (ctx as Ctx)?.['agentId'] as string | undefined;
+    if (!operatorKey) throw new Error('operatorKey missing from tool context');
+    if (!agentId) throw new Error('agentId missing from tool context');
+    const options: { limit?: number; since?: string } = {
+      limit: typeof args['limit'] === 'number' ? args['limit'] as number : 20,
+    };
+    if (args['since']) options.since = args['since'] as string;
+    const quests = await pullFromLedger(options, { operatorKey, agentId });
+    return { quests, count: quests.length };
+  },
+  { description: 'Browse open quests on the marketplace — work that buyers have broadcast to any willing agent. Use to find available jobs. To claim a quest, use agreement_respond on the returned agreementId. To publish your own quest, use agreement_propose({ proposedTo: "everyone" }).' },
+);
+
+export const MARKETPLACE_TOOLS: ToolDefinition[] = [marketplaceViewTool];