@ziggs-ai/agent-sdk 0.1.7 → 0.1.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/agent-sdk",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Agent framework SDK for building autonomous agents on the Ziggs platform",
   "type": "module",
   "main": "src/index.ts",
@@ -16,6 +16,7 @@
     "test:watch": "node --experimental-test-module-mocks --import tsx/esm --test --watch test/*.test.ts"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@ziggs-ai/api-client": "^0.1.9",
     "ajv": "^8.17.1",
     "dotenv": "^17.2.3",

package/src/adapters/McpAdapter.ts

@@ -0,0 +1,203 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { AgentHost, type AgentHostOptions } from '../AgentHost.js';
+import type { ToolDefinition } from '../tools/defineTool.js';
+import { thinkingDefaults } from '../runtime/defaults.js';
+import type { Workflow } from '../types.js';
+
+export type McpTransportConfig =
+  | { type: 'stdio'; command: string; args?: string[]; env?: Record<string, string> }
+  | { type: 'http'; url: string };
+
+export interface CreateMcpAgentOptions extends Omit<AgentHostOptions, 'tools' | 'workflow' | 'states' | 'initial'> {
+  /** MCP server connection — stdio (local process) or HTTP (remote). */
+  transport: McpTransportConfig;
+  /** Additional Ziggs tools to register alongside the MCP-derived ones. */
+  extraTools?: ToolDefinition[];
+  /** Override the default single-state thinking workflow. */
+  workflow?: Workflow;
+}
+
+export interface McpAgentHandle {
+  host: AgentHost;
+  /** Disconnect the MCP client (call on shutdown alongside host.disconnect()). */
+  closeMcp: () => Promise<void>;
+  /** Names of MCP tools that were mapped to Ziggs tools on startup. */
+  toolNames: string[];
+}
+
+function buildTransport(config: McpTransportConfig) {
+  if (config.type === 'stdio') {
+    return new StdioClientTransport({
+      command: config.command,
+      args: config.args ?? [],
+      env: config.env,
+    });
+  }
+  return new StreamableHTTPClientTransport(new URL(config.url));
+}
+
+type McpTool = {
+  name: string;
+  description?: string;
+  inputSchema?: Record<string, unknown>;
+};
+
+type McpContent = { type: string; text?: string };
+
+function mcpContentToResult(content: McpContent[]): unknown {
+  const text = content
+    .map(c => (c.type === 'text' ? c.text ?? '' : JSON.stringify(c)))
+    .join('\n');
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+function mapMcpTools(client: Client, tools: McpTool[]): ToolDefinition[] {
+  return tools.map(tool => ({
+    schema: {
+      type: 'function' as const,
+      function: {
+        name: tool.name,
+        description: tool.description ?? '',
+        parameters: tool.inputSchema ?? { type: 'object', properties: {} },
+      },
+    },
+    handler: async (args: Record<string, unknown>) => {
+      const result = await client.callTool({ name: tool.name, arguments: args }) as {
+        isError?: boolean;
+        content: McpContent[];
+      };
+      if (result.isError) {
+        throw new Error(mcpContentToResult(result.content) as string);
+      }
+      return mcpContentToResult(result.content);
+    },
+    isGenericFallback: true,
+  }));
+}
+
+/**
+ * Wraps any MCP server as a Ziggs AgentHost.
+ *
+ * 1. Opens a connection to the MCP server (stdio or HTTP).
+ * 2. Calls tools/list and maps each tool to a Ziggs ToolDefinition.
+ * 3. Returns an AgentHost pre-loaded with those tools, ready to connectAsync().
+ *
+ * Usage:
+ *   const { host, closeMcp } = await createMcpAgent({
+ *     transport: { type: 'stdio', command: 'npx', args: ['-y', '@modelcontextprotocol/server-github'] },
+ *     agentId: 'my-github-agent',
+ *     name: 'GitHub Agent',
+ *     description: 'Wraps the GitHub MCP server',
+ *   });
+ *   await host.connectAsync();
+ *
+ *   process.on('SIGTERM', async () => {
+ *     host.disconnect();
+ *     await host.drain();
+ *     await closeMcp();
+ *   });
+ */
+function buildDefaultWorkflow(description: string, mcpTools: McpTool[]): Workflow {
+  const dflt = thinkingDefaults({ initial: 'idle' });
+  // Bind each MCP tool as an explicit action so runTurn includes them in the
+  // LLM API call and the decision schema. Without this, allowedToolNames is
+  // empty and the tools array passed to the LLM is also empty.
+  const toolActions = Object.fromEntries(
+    mcpTools.map(t => [t.name, {
+      tool: t.name,
+      prompt: { when: t.description || `Use ${t.name}` },
+    }]),
+  );
+  return {
+    id: 'mcp-agent',
+    description: description || 'MCP-backed agent',
+    initial: 'idle',
+    states: {
+      idle: {
+        kind: 'thinking',
+        prompt: {
+          role: 'You are a helpful agent powered by an MCP server.',
+          goal: description || 'Help the user by calling the available tools.',
+          constraints: 'Use your tools to answer the user\'s request. After gathering results, use "respond" to send the answer. Use "wait" only when no action is needed.',
+        },
+        actions: {
+          ...dflt.actions,
+          ...toolActions,
+          respond: {
+            prompt: {
+              instruction: 'Send your final answer to the user.',
+              when: 'You have gathered enough information and are ready to reply to the user.',
+              format: 'args: { receiverId: "<userId>", message: "<your answer>" }',
+            },
+            produces: 'message-sent',
+          },
+        },
+        transitions: [
+          { to: 'idle', when: (o) => o.kind === 'wait' },
+          { to: 'idle', when: (o) => o.kind === 'error' },
+          { to: 'done', when: (o) => o.kind === 'message-sent' },
+        ],
+      },
+      done: {
+        kind: 'parked',
+        transitions: [
+          { to: 'idle', when: (o) => o.kind === 'message-received' },
+        ],
+      },
+    },
+  };
+}
+
+/**
+ * Wraps any MCP server as a Ziggs AgentHost.
+ *
+ * 1. Opens a connection to the MCP server (stdio or HTTP).
+ * 2. Calls tools/list and maps each tool to a Ziggs ToolDefinition.
+ * 3. Returns an AgentHost pre-loaded with those tools, ready to connectAsync().
+ *
+ * Usage:
+ *   const { host, closeMcp } = await createMcpAgent({
+ *     transport: { type: 'stdio', command: 'npx', args: ['-y', '@modelcontextprotocol/server-github'] },
+ *     agentId: 'my-github-agent',
+ *     name: 'GitHub Agent',
+ *     description: 'Wraps the GitHub MCP server',
+ *   });
+ *   await host.connectAsync();
+ *
+ *   process.on('SIGTERM', async () => {
+ *     host.disconnect();
+ *     await host.drain();
+ *     await closeMcp();
+ *   });
+ */
+export async function createMcpAgent(options: CreateMcpAgentOptions): Promise<McpAgentHandle> {
+  const { transport: transportConfig, extraTools = [], workflow, ...hostOptions } = options;
+
+  const transport = buildTransport(transportConfig);
+  const client = new Client({ name: 'ziggs-mcp-agent', version: '1.0.0' });
+
+  await client.connect(transport);
+
+  const { tools: rawTools } = await client.listTools();
+  const mcpTools = mapMcpTools(client, rawTools as McpTool[]);
+
+  const resolvedWorkflow = workflow ?? buildDefaultWorkflow(hostOptions.description ?? '', rawTools as McpTool[]);
+
+  const host = new AgentHost({
+    ...hostOptions,
+    workflow: resolvedWorkflow,
+    tools: [...mcpTools, ...extraTools],
+  });
+
+  return {
+    host,
+    closeMcp: () => client.close(),
+    toolNames: rawTools.map((t: McpTool) => t.name),
+  };
+}

package/src/adapters/OpenAIAdapter.ts

@@ -62,49 +62,85 @@ export class OpenAIAdapter {
       : undefined;
 
     try {
-      const { usage: _u, ...restOptions } = options as Record<string, unknown>;
-      // Verbose LLM request/response logging — commented out to reduce log noise.
-      // Re-enable by uncommenting to see full prompt/output blocks per LLM call.
-      // const divider = '─'.repeat(80);
-      // console.log(`\n${divider}`);
-      // console.log(`📤 LLM REQUEST → ${this.model}  (${messages.length} msg${messages.length === 1 ? '' : 's'})`);
-      // console.log(divider);
-      // for (const m of messages) {
-      //   const content = typeof m.content === 'string' ? m.content : JSON.stringify(m.content);
-      //   const len = content?.length ?? 0;
-      //   console.log(`\n[${m.role.toUpperCase()}]  ${len} chars`);
-      //   console.log(content ?? '');
-      // }
-      // console.log(`${divider}\n`);
+      const { usage: _u, response_format: _explicitResponseFormat, ...restOptions } = options as Record<string, unknown>;
+      const responseFormat = openAITools
+        ? undefined
+        : ((_explicitResponseFormat as OpenAI.ResponseFormatJSONObject) ?? { type: 'json_object' });
+
+      // OpenAI 400s response_format:{type:'json_object'} unless the word "json"
+      // appears somewhere in the messages. Callers are expected to mention it
+      // in their system prompt, but that's an implicit cross-file contract —
+      // guarantee it here instead of trusting every call site to remember.
+      let finalMessages = messages;
+      if (
+        responseFormat?.type === 'json_object' &&
+        !messages.some(m => {
+          const c = typeof m.content === 'string' ? m.content : JSON.stringify(m.content ?? '');
+          return /json/i.test(c);
+        })
+      ) {
+        finalMessages = [...messages, { role: 'system', content: 'Respond with valid JSON.' }];
+      }
+
+      // Verbose LLM request/response logging — enabled for debugging.
+      // Comment out again to reduce log noise.
+      const divider = '─'.repeat(80);
+      console.log(`\n${divider}`);
+      console.log(`📤 LLM REQUEST → ${this.model}  (${finalMessages.length} msg${finalMessages.length === 1 ? '' : 's'})`);
+      console.log(divider);
+      for (const m of finalMessages) {
+        const content = typeof m.content === 'string' ? m.content : JSON.stringify(m.content);
+        const len = content?.length ?? 0;
+        console.log(`\n[${m.role.toUpperCase()}]  ${len} chars`);
+        console.log(content ?? '');
+      }
+      console.log(`${divider}\n`);
       const res = await this.client.chat.completions.create({
         model: this.model,
-        messages,
+        messages: finalMessages,
         stream: false,
-        max_completion_tokens: 3000,
-        response_format: openAITools ? undefined : ((restOptions['response_format'] as OpenAI.ResponseFormatJSONObject) ?? { type: 'json_object' }),
+        // 25000 reserves room for hidden reasoning tokens on reasoning models
+        // (gpt-5.x/o-series) — they're billed against this cap before any
+        // visible content, so a low cap can exhaust the budget and return
+        // empty content with finish_reason "length".
+        max_completion_tokens: 25000,
+        response_format: responseFormat,
         ...(openAITools && { tools: openAITools }),
         ...restOptions,
       } as OpenAI.Chat.ChatCompletionCreateParamsNonStreaming);
 
       const msg = res.choices[0].message;
+      const finishReason = res.choices[0].finish_reason;
       const content = msg.content?.trim() ?? null;
       const toolCalls = msg.tool_calls?.length ? msg.tool_calls : null;
-      // Verbose LLM response logging — commented out to reduce log noise.
-      // console.log(`\n${divider}`);
-      // console.log(`📥 LLM RESPONSE ← ${this.model}`);
-      // console.log(divider);
-      // if (content) {
-      //   console.log(`\n[CONTENT]  ${content.length} chars`);
-      //   console.log(content);
-      // }
-      // if (toolCalls) {
-      //   console.log(`\n[TOOL CALLS]  ${toolCalls.length}`);
-      //   for (const tc of toolCalls) {
-      //     console.log(`  → ${tc.function.name}(${tc.function.arguments})`);
-      //   }
-      // }
-      // if (!content && !toolCalls) console.log('\n(no content, no tool calls)');
-      // console.log(`${divider}\n`);
+      // Verbose LLM response logging — enabled for debugging.
+      // Comment out again to reduce log noise.
+      console.log(`\n${divider}`);
+      console.log(`📥 LLM RESPONSE ← ${this.model}  finish=${finishReason}`);
+      console.log(divider);
+      if (content) {
+        console.log(`\n[CONTENT]  ${content.length} chars`);
+        console.log(content);
+      }
+      if (toolCalls) {
+        console.log(`\n[TOOL CALLS]  ${toolCalls.length}`);
+        for (const tc of toolCalls) {
+          console.log(`  → ${tc.function.name}(${tc.function.arguments})`);
+        }
+      }
+      if (!content && !toolCalls) console.log('\n(no content, no tool calls)');
+      if (res.usage) {
+        const u = res.usage as OpenAI.CompletionUsage & { completion_tokens_details?: { reasoning_tokens?: number } };
+        console.log(`\n[USAGE]  prompt=${u.prompt_tokens} completion=${u.completion_tokens}${u.completion_tokens_details?.reasoning_tokens != null ? ` (reasoning=${u.completion_tokens_details.reasoning_tokens})` : ''} total=${u.total_tokens}`);
+      }
+      console.log(`${divider}\n`);
+      if (!content && !toolCalls && finishReason === 'length') {
+        const u = res.usage as (OpenAI.CompletionUsage & { completion_tokens_details?: { reasoning_tokens?: number } }) | undefined;
+        throw new Error(
+          `LLM returned no usable output — completion token budget exhausted before any content ` +
+          `(finish_reason=length, reasoning_tokens=${u?.completion_tokens_details?.reasoning_tokens ?? 'unknown'})`,
+        );
+      }
       return {
         content,
         tool_calls: toolCalls,
@@ -131,7 +167,7 @@ export class OpenAIAdapter {
       model: this.model,
       messages,
       stream: true,
-      max_completion_tokens: 3000,
+      max_completion_tokens: 25000,
     });
     let text = '';
     for await (const chunk of stream) {

package/src/formatters/HistoryFormatter.ts

@@ -116,7 +116,13 @@ export class HistoryFormatter {
 
   formatParticipant(participant: AnyObj | null | undefined, agentId: string): string {
     if (!participant) return 'unknown';
-    const id = (participant['id'] as string) || 'unknown';
+    // Message.sender is stored as {agentId, underAgreementId} (no `id`, no
+    // `type`) while Message.receiver is {id, type} — two different shapes on
+    // the same document (see backend Message schema). Without this fallback,
+    // every sender renders as "unknown (unknown)" and self-sent history rows
+    // never match `id === agentId`, so the agent can't recognize its own
+    // past messages in <history>.
+    const id = (participant['id'] as string) || (participant['agentId'] as string) || 'unknown';
     if (participant['type'] === 'system') return 'System';
     if (id === agentId) return 'You';
     return `${id} (${participant['type'] || 'unknown'})`;

package/src/index.ts

@@ -9,6 +9,8 @@
  */
 
 export { defineAgent } from './defineAgent.js';
+export { createMcpAgent } from './adapters/McpAdapter.js';
+export type { CreateMcpAgentOptions, McpAgentHandle, McpTransportConfig } from './adapters/McpAdapter.js';
 export { AgentHost, createAgent, createAgentPool } from './AgentHost.js';
 export { Agent } from './agent/Agent.js';
 export type { TickInput, TickOutput, AgentOptions } from './agent/Agent.js';

package/src/pricing/fleetDefaults.ts

@@ -144,11 +144,18 @@ export function applyFleetAgreementPricing(
   return next;
 }
 
-/** Default tier price when a fleet agent counters without an explicit `price`. */
-export function applyFleetCounterPricing(
-  payload: ProtocolPricingPayload,
+/**
+ * Default tier price when a fleet agent counters without an explicit `price`.
+ *
+ * Generic over the payload shape so the precise field types of the caller's
+ * payload survive the round-trip — this helper only ever sets `price`, so a
+ * richer input type (e.g. protocolRunner's `ProtocolPayload`) must come back
+ * out unwidened by `ProtocolPricingPayload`'s `[key: string]: unknown` index.
+ */
+export function applyFleetCounterPricing<T extends ProtocolPricingPayload>(
+  payload: T,
   actingAgentId: string,
-): ProtocolPricingPayload {
+): T {
   if (payload.price != null && payload.price !== undefined) {
     return payload;
   }
@@ -157,7 +164,7 @@ export function applyFleetCounterPricing(
     payload.description ?? payload.agreementDescription,
   );
   if (cents == null) return payload;
-  return { ...payload, price: cents };
+  return { ...payload, price: cents } as T;
 }
 
 /** User or agent direct-create / marketplace: default from provider specialist. */

package/src/runtime/PromptBuilder.ts

@@ -208,7 +208,9 @@ ${this._renderDecisionSchemaFromActions(actions, senderMeta, ctxObj, omitMessage
     const content = event.text || event.result || event.content;
     if (!content) return `<event type="${eventType}" from="${from}">(Empty)</event>`;
     const str = typeof content === 'object' ? JSON.stringify(content) : String(content);
-    const display = str.length > 1000 ? str.slice(0, 1000) + '...' : str;
+    // Matches MAX_MSG_CHARS in runTurn.ts — the incoming instruction shouldn't
+    // be truncated tighter than what the agent itself is allowed to send back.
+    const display = str.length > 3500 ? str.slice(0, 3500) + '...' : str;
     return `<event type="${eventType}" from="${from}">\n${display}\n</event>`;
   }
 

package/src/runtime/runTurn.ts

@@ -424,9 +424,13 @@ function eventsAreTerminal(events: EmittedEvent[]): boolean {
       // (api-client now returns Agreement directly, not wrapped in { agreement }).
       const ag = (r.agreement ?? (r.agreementId ? r : null)) as Record<string, unknown> | null | undefined;
       const task = (r.task || (r.taskId ? r : null)) as Record<string, unknown> | null | undefined;
+      // Agreement's own status lives flat as `proposalStatus` (see api-client
+      // Agreement type) — not nested under `.proposal.status`. Check both so
+      // a successful agreement_propose is recognized as terminal instead of
+      // being re-issued by the LLM on the next loop iteration.
       const agProposal = ag?.proposal as Record<string, unknown> | undefined;
       const taskProposal = task?.proposal as Record<string, unknown> | undefined;
-      const proposalStatus = agProposal?.status || taskProposal?.status;
+      const proposalStatus = ag?.proposalStatus ?? agProposal?.status ?? taskProposal?.status;
       if (proposalStatus === 'pending' || proposalStatus === 'approved') return true;
       const state = task?.state || r.state;
       if (state === 'active' || state === 'in-progress' ||
@@ -445,10 +449,11 @@ function eventsContainAgreementCreation(events: EmittedEvent[]): boolean {
     if (r.success === false || r.error) return false;
     // Support both nested { agreement: {...} } and flat Agreement objects.
     const ag = (r.agreement ?? (r.agreementId ? r : null)) as Record<string, unknown> | undefined;
+    // See eventsAreTerminal above: proposalStatus is flat on Agreement, not nested.
     const agProposal = ag?.proposal as Record<string, unknown> | undefined;
     const task = r.task as Record<string, unknown> | undefined;
     const taskProposal = task?.proposal as Record<string, unknown> | undefined;
-    const proposalStatus = agProposal?.status || taskProposal?.status;
+    const proposalStatus = ag?.proposalStatus ?? agProposal?.status ?? taskProposal?.status;
     return proposalStatus === 'pending' || proposalStatus === 'approved';
   });
 }

package/src/runtime/validateWorkflow.ts

@@ -169,7 +169,7 @@ export function validateWorkflow(workflow: Workflow): ValidationResult {
         });
         if (!hasErrorFallthrough) {
           warnings.push(
-            `thinking state "${name}" has no fallthrough for { kind: 'error' } — empty/failed turns may silently recurse until the depth guard (ZIG-303). Add an error transition or spread thinkingDefaults().transitions.`,
+            `thinking state "${name}" has no fallthrough for { kind: 'error' } — empty/failed turns may silently recurse until the depth guard. Add an error transition or spread thinkingDefaults().transitions.`,
           );
         }
       }

package/src/server/InboxCatchUp.ts

@@ -171,7 +171,14 @@ export async function runInboxCatchUp(deps: InboxCatchUpDeps): Promise<InboxCatc
   const toAck: InboxAck[] = [];
 
   if (envelope.truncatedScopes > 0) {
-    warn(label, `inbox truncatedScopes=${envelope.truncatedScopes} — skipping ack until narrowed`);
+    // Informational only — does NOT block acking the scopes actually
+    // returned below. truncatedScopes just means the caller's total reach
+    // exceeded the server's per-call scope cap (backend/src/inbox/inbox.service.ts,
+    // INBOX_MAX_SCOPES); each entry in envelope.scopes is still an
+    // independently accurate, safe-to-ack unit of news for that scope. Never
+    // acking here meant a busy long-lived agent (reach > cap) would never ack
+    // anything and re-deliver its entire backlog on every reconnect forever.
+    warn(label, `inbox truncatedScopes=${envelope.truncatedScopes} (reach exceeds per-call cap — examined scopes are still acked normally)`);
   }
 
   for (const scope of envelope.scopes) {
@@ -202,11 +209,7 @@ export async function runInboxCatchUp(deps: InboxCatchUpDeps): Promise<InboxCatc
       }
     }
 
-    if (
-      envelope.truncatedScopes === 0 &&
-      scope.latestAt &&
-      (scope.newMessages > 0 || scope.newArtifacts > 0)
-    ) {
+    if (scope.latestAt && (scope.newMessages > 0 || scope.newArtifacts > 0)) {
       toAck.push({
         kind: scope.scope.kind,
         id: scope.scope.id,

package/src/server/agreements/AgreementService.ts

@@ -3,13 +3,13 @@ import {
   getAgreementStatus, listAgreements, getMyAgreements, getAgreement,
   publishOffer as publishOfferApi, createAgreement, revokeAgreement, getAgreementsByChat, linkAgreementToChat,
   getChatsForAgreement, joinAgreement, linkArtifactToAgreement, getArtifactsForAgreement,
-  linkUserToAgreement, getUsersForAgreement, createContract,
+  linkUserToAgreement, getUsersForAgreement,
   type Creds, type Agreement,
   type ProposeAgreementData, type ProposeDirectInput, type ProposeBroadcastInput,
   type PublishOfferPayload,
   type DelegateAgreementData, type CounterAgreementData,
   type CreateAgreementBody, type ListAgreementsFilters, type GetMyAgreementsFilters,
-  type ChatLinkType, type ArtifactLinkType, type UserRole, type CreateContractInput,
+  type ChatLinkType, type ArtifactLinkType, type UserRole,
 } from '@ziggs-ai/api-client';
 
 export class AgreementService {
@@ -21,11 +21,6 @@ export class AgreementService {
     this.creds = { operatorKey, agentId };
   }
 
-  /** @deprecated Prefer {@link proposeDirect} or {@link proposeBroadcast}. */
-  contract(input: CreateContractInput): Promise<Agreement> {
-    return createContract(input, this.creds);
-  }
-
   /** 1:1 proposal. Server defaults engagementKind to `service` when omitted. */
   proposeDirect(payload: ProposeDirectInput): Promise<Agreement> {
     return proposeAgreement(payload, this.creds);

package/src/server/tasks/TaskService.ts

@@ -1,7 +1,7 @@
 import {
   createTask, getTask, getActiveTasksForAgent, getActiveTasksForChat, getSubtasks,
   updateTaskState, cancelTask,
-  claimLedgerTask, reportTask, setTaskSatisfaction, countTasks,
+  reportTask, setTaskSatisfaction, countTasks,
   type Creds, type Task, type TaskState,
 } from '@ziggs-ai/api-client';
 import type { CountTasksFilters } from '@ziggs-ai/api-client';
@@ -50,7 +50,7 @@ export class TaskService {
     return getSubtasks(parentTaskId, this.creds);
   }
 
-  async spawnUnderAgreement(agreementId: string, taskData: { description: string; parentTaskId?: string; plan?: unknown; planReviewTiming?: string; requireMidWorkPlanAck?: boolean }): Promise<Task> {
+  async spawnUnderAgreement(agreementId: string, taskData: { description: string; parentTaskId?: string; plan?: unknown; planReviewTiming?: string; requireMidWorkPlanAck?: boolean; assigneeId?: string }): 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);
@@ -85,17 +85,6 @@ export class TaskService {
     }
   }
 
-  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);
   }

package/src/server/tools/index.ts

@@ -42,6 +42,5 @@ export {
 export {
   CONTEXT_TOOLS,
   contextDiscoverTool,
-  contextListGrantsTool,
   contextDelegateTool,
 } from './tier2/contextTools.js';

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

@@ -32,6 +32,7 @@ interface ProtocolPayload {
   parentAgreementId?: string;
   parentTaskId?: string;
   taskId?: string;
+  assigneeId?: string;
   status?: string;
   result?: unknown;
   plan?: unknown;
@@ -95,6 +96,7 @@ export async function dispatchProtocolOp(
         plan: payload.plan,
         planReviewTiming: payload.planReviewTiming,
         requireMidWorkPlanAck: payload.requireMidWorkPlanAck,
+        assigneeId: payload.assigneeId,
       });
     case 'task-update':
       if (!payload.taskId || !payload.status) return null;

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

@@ -87,9 +87,9 @@ export const taskUpdatePlanStepTool: ToolDefinition = defineTool(
 
 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' },
+  { agreementId: { type: 'string', required: true }, description: { type: 'string', required: true }, parentTaskId: 'string', assigneeId: { type: 'string', description: 'Explicitly hand this task to one specific agent (e.g. a worker your orchestrator selected via agent search) instead of leaving it unassigned. Must be a party on the agreement (payer, provider, creator, or creator agent).' }, 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.' },
+  { description: 'Spawn a new task under an existing approved agreement. Use when the contract is already in place. Pass assigneeId to delegate the task to a specific agent rather than leaving it open.' },
 );
 
 export const PROTOCOL_TOOLS: ToolDefinition[] = [

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

@@ -18,17 +18,7 @@ export const contextDiscoverTool: ToolDefinition = defineTool(
   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.',
+      'List every context grant this agent holds, as scope descriptors — grantId, scope, temporal, watermarkAt, expiresAt (no message or artifact content).',
   },
 );
 
@@ -69,6 +59,5 @@ export const contextDelegateTool: ToolDefinition = defineTool(
 
 export const CONTEXT_TOOLS = [
   contextDiscoverTool,
-  contextListGrantsTool,
   contextDelegateTool,
 ] as const;

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

@@ -1,5 +1,5 @@
 import { defineTool, type ToolDefinition } from '../../../tools/defineTool.js';
-import { pullFromLedger } from '@ziggs-ai/api-client';
+import { pullQuests } from '@ziggs-ai/api-client';
 
 type Ctx = Record<string, unknown>;
 
@@ -18,7 +18,7 @@ export const marketplaceViewTool: ToolDefinition = defineTool('marketplace_view'
       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 });
+    const quests = await pullQuests(options, { operatorKey, agentId });
     return { quests, count: quests.length };
   },
   { description: 'Browse open quests on the marketplace — work buyers have broadcast to willing agents. Returns public quests plus any org-scoped quests in your org. To claim a quest, use agreement_respond on the returned agreementId. To publish your own, use agreement_propose({ proposedTo: "everyone" }) for a public quest or proposedTo: "org" to keep it inside your org.' },

package/src/server/ziggscontext/ZiggsContextClient.ts

@@ -69,14 +69,6 @@ export class ZiggsContextClient {
     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');