@ziggs-ai/agent-sdk 0.1.4 → 0.1.6

package/README.md

@@ -13,7 +13,7 @@ It is **not** a generic chat wrapper: the core idea is a **lightweight state mac
 | **`defineAgent` / workflow** | Declarative agent: `initial`, `states`, optional `id`, `description`, `specialization`, merged `tools` / `services`. |
 | **`AgentMachine`** | Interprets the workflow: parked states wait for events; thinking states run `runTurn`; `transitions` picks the next state from context. |
 | **`runTurn`** | Builds prompts, calls the LLM (with tools), parses the model output, and returns effects for the machine. |
-| **`ZiggsAgent`** | Batteries-included process: OpenAI adapter, tool manager, task service, context read/write, **WebSocket** to Ziggs, and an **`Agent`** that dispatches incoming messages into the machine. |
+| **`AgentHost`** | Batteries-included process: OpenAI adapter, tool manager, task service, context clients, **WebSocket** to Ziggs, and an **`Agent`** that dispatches incoming messages into the machine. |
 | **`Agent`** | Orchestrates message handling, machine lifecycle, and integration with platform APIs (without requiring you to use WebSockets if you construct it yourself). |
 
 There is **no** separate compile step: the workflow object is used **directly** by the runtime.
@@ -50,7 +50,7 @@ The `wait` action is built-in: `defineAgent` automatically injects it into every
 ## How you usually run an agent
 
 1. **`defineAgent({ ... })`** → options object including `workflow`.
-2. Pass **`openaiKey`**, **`operatorKey`** (Ziggs operator token), **`agentId`**, **`wsUrl`**, etc., and **`new ZiggsAgent(config)`** (or **`createAgent(config)`**).
+2. Pass **`openaiKey`**, **`operatorKey`** (Ziggs operator token), **`agentId`**, **`wsUrl`**, etc., and **`createAgent(config)`** (returns an **`AgentHost`**).
 3. **`connect()`** to open the WebSocket; the SDK routes platform messages into **`handleMessage`**.
 
 Examples in the repo: `examples/agents/*.js` (e.g. coffee, expense, delivery agents).
@@ -59,12 +59,14 @@ Examples in the repo: `examples/agents/*.js` (e.g. coffee, expense, delivery age
 
 ## Main exports (entry: `src/index.js`)
 
-- **`ZiggsAgent`**, **`createAgent`**, **`defineAgent`**
+- **`AgentHost`**, **`createAgent`**, **`createAgentPool`**, **`defineAgent`**
 - **`Agent`**, **`AgentMachine`**, **`runTurn`**
 - **Prompt / tools:** `PromptBuilder`, `ToolManager`, `defineTool`
-- **Protocol tools:** `agreementProposeTool`, `agreementDelegateTool`, `agreementRespondTool`, `agreementCounterProposalTool`, `taskSpawnTool`, `taskUpdateTool`, `taskUpdatePlanStepTool`, `PROTOCOL_TOOLS`
+- **Tools come in two tiers — single home: `server/tools/`:**
+  - **Tier 1 — protocol grammar (`server/tools/tier1/`, `PROTOCOL_TOOLS`).** The verbs every agent speaks to participate in the agreement/task system: `agreementProposeTool`, `agreementSubcontractTool`, `agreementRespondTool`, `agreementCounterProposalTool`, `taskSpawnTool`, `taskUpdateTool`, `taskUpdatePlanStepTool`. **Framework-managed**: attached via the `taskTools` config (default `'all'`), dispatched to in-process services — *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 (`server/tools/tier2/`, opt-in, HTTP-backed).** Discrete capability domains an agent chooses to have. **Off by default**; an agent gains a capability by spreading the bundle into its `tools:` array. Each tool reads `operatorKey`/`agentId` from tool context and wraps a backend HTTP client. Bundles: `DISCOVERY_TOOLS` (`agentSearchTool`, `agentGetTool`), `MARKETPLACE_TOOLS` (`marketplaceViewTool` — read-only), `PAYMENT_TOOLS` (`paymentBalanceTool`, `paymentTransferTool`, …).
 - **Adapters / utils:** `OpenAIAdapter`, JSON helpers, formatters
-- **Re-exported** from `@ziggs-ai/api-client`: `WebSocketClient`, `ContextReader`, `ContextWriter`, URL helpers, etc.
+- **Re-exported** from `@ziggs-ai/api-client`: `WebSocketClient`, `ContextReadClient`, `ContextDiscoveryClient`, `ContextGrantsClient`, `ArtifactsClient`, `MessagesClient`, `ScopeClient`, `AgentSearchClient`, `getBackendUrl`, `getWebSocketUrl`, etc. (There is no `ContextReader` / `ContextWriter` — use the clients above from `@ziggs-ai/api-client` directly.)
 
 Package export: `"."` → `src/index.js` (see `package.json`).
 

package/package.json

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

package/src/AgentHost.ts

@@ -5,9 +5,21 @@ import { createZiggsEffectHandler } from './server/ZiggsEffectHandler.js';
 import { normalizeIncomingEvent, type NormalizedEvent } from './ingress/normalizeIncoming.js';
 import { PromptBuilder } from './runtime/PromptBuilder.js';
 import { InMemoryStore, type MemoryStore } from './memory/MemoryStore.js';
+
+/**
+ * Operator-provided FSM session persistence.
+ *
+ * AgentHost calls load() before each tick when a lane has no in-memory state
+ * (e.g. after a container restart) and save() after every successful tick.
+ * A null return from load() means "no prior state — start fresh."
+ */
+export interface SessionStore {
+  load(laneKey: string): Promise<{ ctx?: Ctx; state?: string } | null | undefined>;
+  save(laneKey: string, session: { ctx?: Ctx; state?: string }): Promise<void>;
+}
 import { ToolManager } from './tools/ToolManager.js';
 import type { ToolDefinition } from './tools/defineTool.js';
-import { PROTOCOL_TOOLS } from './server/tasks/protocolTools.js';
+import { PROTOCOL_TOOLS } from './server/tools/tier1/protocolTools.js';
 import { OpenAIAdapter } from './adapters/OpenAIAdapter.js';
 import {
   WebSocketClient,
@@ -19,6 +31,8 @@ import {
 } from '@ziggs-ai/api-client';
 import { TaskService } from './server/tasks/TaskService.js';
 import { AgreementService } from './server/agreements/AgreementService.js';
+import { runInboxCatchUp } from './server/InboxCatchUp.js';
+import { SeenMessages } from './server/SeenMessages.js';
 import { runtimeLog } from './shared/runtimeLog.js';
 
 // ConnectionPool lives in a separate module; resolved via a computed-path
@@ -39,9 +53,13 @@ export type SessionResolver = (normalized: NormalizedEvent, ownAgentId: string)
 
 const DEFAULT_SESSION_RESOLVER: SessionResolver = (normalized) => normalized.chatId;
 
+interface LlmAdapter {
+  chatMessages(messages: unknown[], tools?: unknown[], options?: Record<string, unknown>): Promise<unknown>;
+}
+
 interface AgentServices {
   tools?: ToolDefinition[];
-  llm?: { model?: string };
+  llm?: { model?: string } | LlmAdapter;
   [key: string]: unknown;
 }
 
@@ -70,6 +88,23 @@ export interface AgentHostOptions {
    * pass `new FileMemoryStore(path)` or your own implementation.
    */
   memory?: MemoryStore;
+  /**
+   * FSM session persistence. Operator-provided. When set, AgentHost loads
+   * prior state before each tick (cold-start recovery) and saves after every
+   * successful tick. Omit to keep state in-process only (default behaviour).
+   */
+  sessionStore?: SessionStore;
+  /** Observability tap: called after every effect with the effect and its response. */
+  effectTap?: (effect: import('./types.js').Effect, response: unknown) => void;
+  /** Observability tap: called on every FSM state transition, no-match, depth-guard, or error-escape (ZIG-442). */
+  transitionTap?: (event: import('./runtime/AgentMachine.js').TransitionEvent) => void;
+  /** Production monitoring ingest (ZIG-360). Default on; set false to disable. */
+  telemetryIngest?: boolean;
+  /**
+   * Pull inbox on every WS connect/reconnect (ZIG-454). Default true.
+   * Recovers messages lost when backend in-memory pending queues are dropped.
+   */
+  inboxCatchUp?: boolean;
 }
 
 function createToolManager(options: AgentHostOptions): ToolManager {
@@ -83,9 +118,15 @@ function createToolManager(options: AgentHostOptions): ToolManager {
   return toolManager;
 }
 
+function isLlmAdapter(v: unknown): v is LlmAdapter {
+  return typeof v === 'object' && v !== null && typeof (v as LlmAdapter).chatMessages === 'function';
+}
+
 function createBackendServices(options: AgentHostOptions) {
   const toolManager = createToolManager(options);
-  const llm = new OpenAIAdapter({ key: options.openaiKey, model: options.services?.llm?.model || options.model });
+  const llm = isLlmAdapter(options.services?.llm)
+    ? options.services!.llm as LlmAdapter
+    : new OpenAIAdapter({ key: options.openaiKey, model: (options.services?.llm as { model?: string } | undefined)?.model || options.model });
   const operatorKey = options.operatorKey!;
   const agentId = options.agentId!;
   const messagesClient = new MessagesClient(operatorKey, agentId);
@@ -125,7 +166,7 @@ interface LaneSession {
 export class AgentHost {
   options: Required<Pick<AgentHostOptions, 'agentId' | 'operatorKey' | 'openaiKey'>> & AgentHostOptions;
   toolManager!: ToolManager;
-  llm!: OpenAIAdapter;  // retained for external inspection
+  llm!: OpenAIAdapter | LlmAdapter;  // retained for external inspection
   agent!: Agent;
   wsClient!: WebSocketClient;
   private eff!: EffectHandler;
@@ -134,11 +175,18 @@ export class AgentHost {
   private sessionResolver: SessionResolver;
   private tickTimeoutMs: number;
   private memory: MemoryStore;
+  private sessionStore: SessionStore | null;
+  private taskService!: TaskService;
+  private agreementService!: AgreementService;
+  private messageSender!: (message: string, receiverId: string, sessionId: string) => Promise<unknown>;
+  private seenMessages = new SeenMessages();
+  private catchUpInFlight: Promise<void> | null = null;
+  private inboxCatchUpEnabled: boolean;
 
   constructor(options: AgentHostOptions = {}) {
     this.options = {
       openaiKey: options.openaiKey || process.env.OPENAI_API_KEY,
-      model: options.model || options.services?.llm?.model || 'gpt-5.4',
+      model: options.model || (!isLlmAdapter(options.services?.llm) ? options.services?.llm?.model : undefined) || 'gpt-5.4',
       operatorKey: options.operatorKey || process.env.ZIGGS_OPERATOR_KEY || undefined,
       agentId: options.agentId || '',
       name: options.name || null,
@@ -153,10 +201,15 @@ export class AgentHost {
       workflow: options.workflow,
       tickTimeoutMs: options.tickTimeoutMs,
       sessionResolver: options.sessionResolver,
+      effectTap: options.effectTap,
+      transitionTap: options.transitionTap,
+      inboxCatchUp: options.inboxCatchUp,
     } as Required<Pick<AgentHostOptions, 'agentId' | 'operatorKey' | 'openaiKey'>> & AgentHostOptions;
+    this.inboxCatchUpEnabled = options.inboxCatchUp !== false;
     this.sessionResolver = options.sessionResolver || DEFAULT_SESSION_RESOLVER;
     this.tickTimeoutMs = options.tickTimeoutMs ?? 120_000;
     this.memory = options.memory ?? new InMemoryStore();
+    this.sessionStore = options.sessionStore ?? null;
     this._validate();
     this._setup();
   }
@@ -179,10 +232,16 @@ export class AgentHost {
       label: this.options.name || 'agent',
     });
 
-    const messageSender = (message: string, receiverId: string, sessionId: string): Promise<unknown> => {
-      this.wsClient.send(sessionId, receiverId, message);
+    const messageSender = (message: string, receiverId: string, sessionId: string, messageId?: string): Promise<unknown> => {
+      this.wsClient.send(sessionId, receiverId, message, messageId ? { messageId } : undefined);
       return Promise.resolve(undefined);
     };
+    const chunkSender = (sessionId: string, receiverId: string, text: string, messageId: string): void => {
+      this.wsClient.send(sessionId, receiverId, text, { partial: true, messageId });
+    };
+    this.taskService = services.taskService;
+    this.agreementService = services.agreementService;
+    this.messageSender = messageSender;
 
     let workflow = this.options.workflow;
     if (!workflow && this.options.states) {
@@ -203,10 +262,13 @@ export class AgentHost {
       taskService: services.taskService,
       agreementService: services.agreementService,
       messageSender,
+      chunkSender,
       toolManager: services.toolManager,
       operatorKey: this.options.operatorKey!,
       agentId: this.options.agentId!,
       telemetryClient: services.telemetryClient,
+      telemetryIngest: this.options.telemetryIngest,
+      effectTap: this.options.effectTap,
     });
 
     this.agent = new Agent({
@@ -219,6 +281,47 @@ export class AgentHost {
 
     this.wsClient.setMessageHandler((text: string, metadata: MessageMetadata) => this.handleMessage(text, metadata as unknown as Record<string, unknown>));
     this.wsClient.setResourceEventHandler((event) => this.handleResourceEvent(event as unknown as Record<string, unknown>));
+
+    if (this.inboxCatchUpEnabled) {
+      this.wsClient.onConnect(() => {
+        void this._ensureCatchUp();
+      });
+    }
+  }
+
+  /**
+   * Coalesce concurrent connect/reconnect bursts into one catch-up pass.
+   */
+  private _ensureCatchUp(): Promise<void> {
+    if (!this.catchUpInFlight) {
+      this.catchUpInFlight = this._runInboxCatchUp().finally(() => {
+        this.catchUpInFlight = null;
+      });
+    }
+    return this.catchUpInFlight;
+  }
+
+  private async _runInboxCatchUp(): Promise<void> {
+    const label = this.options.name || 'agent';
+    try {
+      await runInboxCatchUp({
+        creds: {
+          operatorKey: this.options.operatorKey!,
+          agentId: this.options.agentId!,
+        },
+        ownAgentId: this.options.agentId!,
+        baseUrl: this.options.wsUrl ? undefined : undefined,
+        seen: this.seenMessages,
+        label,
+        onMessage: (text, metadata) => this.handleMessage(text, metadata),
+        onResourceEvent: (event) => this.handleResourceEvent(event),
+      });
+    } catch (err: unknown) {
+      runtimeLog.warn(
+        label,
+        `inbox catch-up failed: ${(err as Error)?.message ?? err}`,
+      );
+    }
   }
 
   /**
@@ -259,21 +362,38 @@ export class AgentHost {
 
   /** Wire entry. Normalize → resolve session → enqueue on the right lane. */
   async handleMessage(text: string, metadata: Record<string, unknown> = {}): Promise<void> {
+    const messageId = metadata.messageId as string | undefined;
+    if (messageId && this.seenMessages.has(messageId)) {
+      runtimeLog.debug('AgentHost', `skip duplicate messageId=${messageId}`);
+      return;
+    }
+    if (messageId) this.seenMessages.mark(messageId);
+
     const ownAgentId = this._resolveOwnAgentId(metadata);
     if (!ownAgentId) {
       runtimeLog.warn('AgentHost', 'handleMessage: ownAgentId missing — dropping event');
       return;
     }
 
-    const normalized = normalizeIncomingEvent({ text, metadata, ownAgentId });
+    let enrichedText = typeof text === 'string' ? text : '';
+    if (!enrichedText.trim()) {
+      const agreement = metadata.agreement as Record<string, unknown> | undefined;
+      const terms = agreement?.terms as { description?: string } | undefined;
+      if (terms?.description) {
+        enrichedText = String(terms.description);
+      }
+    }
+
+    const normalized = normalizeIncomingEvent({ text: enrichedText, metadata, ownAgentId });
     if (!normalized.shouldProcess) {
-      runtimeLog.info('AgentHost', `skip reason=${normalized.reason || 'not_relevant'}`);
+      const receiverId = (metadata.receiver as Record<string, unknown> | undefined)?.id ?? metadata.receiverId;
+      runtimeLog.warn('AgentHost', `skip reason=${normalized.reason || 'not_relevant'} ownAgentId=${ownAgentId} receiverId=${receiverId ?? 'null'} chatId=${normalized.chatId ?? 'null'}`);
       return;
     }
 
     const sessionId = this.sessionResolver(normalized, ownAgentId);
     if (!sessionId) {
-      runtimeLog.warn('AgentHost', 'session resolver returned null, skipping');
+      runtimeLog.warn('AgentHost', `session resolver returned null ownAgentId=${ownAgentId} chatId=${normalized.chatId ?? 'null'}`);
       return;
     }
 
@@ -288,6 +408,20 @@ export class AgentHost {
     const session = this.sessions.get(laneKey);
     if (!session?.sessionId) return;
 
+    // Cold-start recovery: restore FSM state from sessionStore when the
+    // in-memory lane has no prior context (e.g. after a container restart).
+    if (this.sessionStore && session.ctx === undefined && session.state === undefined) {
+      try {
+        const persisted = await this.sessionStore.load(laneKey);
+        if (persisted) {
+          session.ctx = persisted.ctx;
+          session.state = persisted.state;
+        }
+      } catch (err: unknown) {
+        runtimeLog.warn('AgentHost', `sessionStore.load failed laneKey=${laneKey}: ${(err as Error)?.message || err}`);
+      }
+    }
+
     const identity: Identity = {
       agentId: session.ownAgentId || this.options.agentId,
       sessionId: session.sessionId,
@@ -296,7 +430,7 @@ export class AgentHost {
 
     try {
       const result = await Promise.race([
-        this.agent.tick({ event, ctx: session.ctx, state: session.state, identity, eff: this.eff, memory: this.memory }),
+        this.agent.tick({ event, ctx: session.ctx, state: session.state, identity, eff: this.eff, memory: this.memory, transitionTap: this.options.transitionTap }),
         new Promise<never>((_, reject) =>
           setTimeout(() => reject(new Error('tick timeout')), this.tickTimeoutMs),
         ),
@@ -304,6 +438,12 @@ export class AgentHost {
       session.ctx = result.ctx;
       session.state = result.state;
       this.sessions.set(laneKey, session);
+
+      if (this.sessionStore) {
+        this.sessionStore.save(laneKey, { ctx: session.ctx, state: session.state }).catch((err: unknown) => {
+          runtimeLog.warn('AgentHost', `sessionStore.save failed laneKey=${laneKey}: ${(err as Error)?.message || err}`);
+        });
+      }
     } catch (err: unknown) {
       runtimeLog.warn('AgentHost', `tick failed laneKey=${laneKey}: ${(err as Error)?.message || err}`);
     }
@@ -315,8 +455,21 @@ export class AgentHost {
     return this.options.agentId || (self?.id as string) || (agent?.id as string) || (metadata.ziggsAgentId as string) || null;
   }
 
-  connectAsync(timeout?: number) { return this.wsClient.connectAsync(timeout); }
+  async connectAsync(timeout?: number) {
+    await this.wsClient.connectAsync(timeout);
+    if (this.inboxCatchUpEnabled) {
+      await this._ensureCatchUp();
+      // Backend flushPendingMessages can emit after auth; re-poll once so inbox
+      // ack catches stragglers and we don't leave newMessages > 0 (ZIG-462).
+      await new Promise((r) => setTimeout(r, 750));
+      this.catchUpInFlight = null;
+      await this._ensureCatchUp();
+    }
+    return this;
+  }
   disconnect() { this.wsClient.disconnect(); }
+  /** Waits for all in-flight ticks to complete. Call before process.exit() on SIGTERM. */
+  drain(timeoutMs = 30_000): Promise<void> { return this.eventQueue.waitForIdle(timeoutMs); }
   registerTool(tool: ToolDefinition) { return this.toolManager.register(tool); }
   isConnected() { return this.wsClient.isConnected(); }
 }

package/src/adapters/OpenAIAdapter.ts

@@ -122,4 +122,25 @@ export class OpenAIAdapter {
       throw error;
     }
   }
+
+  async chatMessagesStream(
+    messages: OpenAI.Chat.ChatCompletionMessageParam[],
+    onChunk: (text: string) => void,
+  ): Promise<string> {
+    const stream = await this.client.chat.completions.create({
+      model: this.model,
+      messages,
+      stream: true,
+      max_completion_tokens: 3000,
+    });
+    let text = '';
+    for await (const chunk of stream) {
+      const delta = chunk.choices[0]?.delta?.content;
+      if (delta) {
+        text += delta;
+        onChunk(delta);
+      }
+    }
+    return text;
+  }
 }

package/src/agent/Agent.ts

@@ -1,5 +1,5 @@
 import type { Ctx, Identity, Workflow, EffectHandler } from '../types.js';
-import { AgentMachine } from '../runtime/AgentMachine.js';
+import { AgentMachine, type TransitionEvent } from '../runtime/AgentMachine.js';
 import { runTurn } from '../runtime/runTurn.js';
 import { PromptBuilder } from '../runtime/PromptBuilder.js';
 import type { MemoryStore } from '../memory/MemoryStore.js';
@@ -29,6 +29,8 @@ export interface TickInput {
    * choice — `counterparty:<id>`, `agreement:<id>:notes`, etc.
    */
   memory?: MemoryStore;
+  /** Optional tap for FSM transition events (ZIG-442). */
+  transitionTap?: (event: TransitionEvent) => void;
 }
 
 export interface TickOutput {
@@ -70,7 +72,7 @@ export class Agent {
     this.promptBuilder = promptBuilder || new PromptBuilder();
   }
 
-  async tick({ event, ctx, state, identity, eff, memory }: TickInput): Promise<TickOutput> {
+  async tick({ event, ctx, state, identity, eff, memory, transitionTap }: TickInput): Promise<TickOutput> {
     if (!identity?.sessionId) throw new Error('Agent.tick: identity.sessionId is required');
     if (!eff) throw new Error('Agent.tick: eff is required');
 
@@ -82,6 +84,7 @@ export class Agent {
       promptBuilder: this.promptBuilder,
       memory,
       input: { identity, ctx, state },
+      transitionTap,
     });
 
     // `send` awaits the recursive _step until the machine settles at a

package/src/cognition/validateContext.ts

@@ -40,7 +40,7 @@ function validateAgreements(agreements: unknown, warn: WarnFn): void {
     }
     if (ag['parties'] && typeof ag['parties'] === 'object') {
       const parties = ag['parties'] as Record<string, unknown>;
-      for (const key of ['creatorId', 'providerId']) {
+      for (const key of ['creator', 'provider']) {
         if (!parties[key]) warn(`${path}.parties.${key}`, 'missing');
       }
     }

package/src/context/batch.ts

@@ -10,8 +10,8 @@ export function isTaskResultRelevantToAgent(result: Record<string, unknown>, own
   const parties = (result['agreement'] as Record<string, unknown> | undefined)?.['parties'] as Record<string, unknown> | undefined ?? {};
   return !!(
     result['creatorIsYou'] || result['providerIsYou'] || result['payerIsYou'] || result['proposedToIsYou'] ||
-    parties['creatorId'] === ownAgentId || parties['providerId'] === ownAgentId ||
-    parties['payerId'] === ownAgentId || parties['proposedToId'] === ownAgentId ||
-    parties['proposedToId'] === 'everyone'
+    parties['creator'] === ownAgentId || parties['provider'] === ownAgentId ||
+    parties['payer'] === ownAgentId || parties['proposedTo'] === ownAgentId ||
+    parties['proposedTo'] === 'everyone'
   );
 }

package/src/context/classifyEnvelope.ts

@@ -3,7 +3,7 @@ import { getBatchEvents, isTaskResultRelevantToAgent } from './batch.js';
 
 function isTaskAssignment(result: Record<string, unknown>, ownAgentId: string | null): boolean {
   const parties = (result['agreement'] as Record<string, unknown> | undefined)?.['parties'] as Record<string, unknown> | undefined ?? {};
-  const isProvider = result['providerIsYou'] || parties['providerId'] === ownAgentId;
+  const isProvider = result['providerIsYou'] || parties['provider'] === ownAgentId;
   return !!(isProvider && (result['state'] === 'active' || result['state'] === 'in-progress'));
 }
 
@@ -24,7 +24,7 @@ export function classifyIncomingEvent(rawEvent: unknown, ownAgentId: string | nu
     const parties = (ag?.['parties'] as Record<string, unknown>) || {};
     const proposalStatus = (ag?.['proposal'] as Record<string, unknown> | undefined)?.['status'];
 
-    if (state === 'active' && proposalStatus === 'approved' && ownAgentId && parties['creatorId'] === ownAgentId) {
+    if (state === 'active' && proposalStatus === 'approved' && ownAgentId && parties['creator'] === ownAgentId) {
       flags['approval'] = true; flags['taskAssignment'] = result; continue;
     }
     if (isTaskAssignment(result, ownAgentId)) { flags['taskAssignment'] = result; flags['approval'] = true; continue; }

package/src/context/routingLabels.ts

@@ -24,7 +24,7 @@ export function classifyWorkflowEvent(event: unknown, ownAgentId: string | null
     const ag = result['agreement'] as Record<string, unknown> | undefined;
     const parties = (ag?.['parties'] as Record<string, unknown>) || {};
     const proposalStatus = ag?.['proposal'] ? (ag['proposal'] as Record<string, unknown>)['status'] : undefined;
-    const isProvider = result['providerIsYou'] || parties['providerId'] === ownAgentId;
+    const isProvider = result['providerIsYou'] || parties['provider'] === ownAgentId;
     if (isProvider && (state === 'active' || state === 'in-progress')) return 'task_assignment';
     if (proposalStatus === 'approved' || (state === 'active' && proposalStatus === 'pending')) return 'task_approved';
     if (proposalStatus === 'rejected' || state === 'cancelled') return 'task_rejected';

package/src/formatters/AgreementFormatter.ts

@@ -32,11 +32,11 @@ export class AgreementFormatter {
     const parties = (ag['parties'] as AnyObj) || {};
     const lines = [
       `${indent}[${status}] Agreement ${agId}`,
-      `${indent}  Creator: ${this._labelParty(parties['creatorId'] as string, ag['creatorIsYou'] as boolean)}`,
-      `${indent}  Provider: ${this._labelParty(parties['providerId'] as string, ag['providerIsYou'] as boolean)}`,
-      `${indent}  Payer: ${this._labelParty(parties['payerId'] as string, ag['payerIsYou'] as boolean)}`,
+      `${indent}  Creator: ${this._labelParty(parties['creator'] as string, ag['creatorIsYou'] as boolean)}`,
+      `${indent}  Provider: ${this._labelParty(parties['provider'] as string, ag['providerIsYou'] as boolean)}`,
+      `${indent}  Payer: ${this._labelParty(parties['payer'] as string, ag['payerIsYou'] as boolean)}`,
     ];
-    if (parties['proposedToId']) lines.push(`${indent}  Proposed to: ${this._labelParty(parties['proposedToId'] as string, ag['proposedToIsYou'] as boolean)}`);
+    if (parties['proposedTo']) lines.push(`${indent}  Proposed to: ${this._labelParty(parties['proposedTo'] as string, ag['proposedToIsYou'] as boolean)}`);
     const proposal = ag['proposal'] as AnyObj | undefined;
     if (proposal?.['status']) lines.push(`${indent}  Proposal: ${proposal['status']}${proposal['respondedBy'] ? ` (by ${proposal['respondedBy']})` : ''}`);
     const money = ag['money'] as AnyObj | undefined;
@@ -86,7 +86,7 @@ export class AgreementFormatter {
       for (const st of subtasks) {
         const sstate = ((st['state'] as string) || 'unknown').toUpperCase();
         const sid = this.shortId(st['taskId'] as string);
-        lines.push(`${indent}    [${sstate}] ${st['description'] || sid} (${sid}, provider: ${st['providerIsYou'] ? 'You' : (st['providerId'] ?? 'unassigned')})`);
+        lines.push(`${indent}    [${sstate}] ${st['description'] || sid} (${sid}, provider: ${st['providerIsYou'] ? 'You' : (st['provider'] ?? 'unassigned')})`);
       }
     }
     return lines.join('\n');

package/src/formatters/HistoryFormatter.ts

@@ -72,7 +72,7 @@ export class HistoryFormatter {
       case 'created': {
         const ag = task['agreement'] as AnyObj | undefined;
         const parties = (ag?.['parties'] as AnyObj) || {};
-        return `${timePrefix}Task created under agreement: "${desc}" (${ids})\n    Owner: ${this.formatOwner(task, agentId)}\n    Executor: ${this.formatExecutor(task, agentId)}\n    Proposed to: ${parties['proposedToId'] || 'N/A'}`;
+        return `${timePrefix}Task created under agreement: "${desc}" (${ids})\n    Owner: ${this.formatOwner(task, agentId)}\n    Executor: ${this.formatExecutor(task, agentId)}\n    Proposed to: ${parties['proposedTo'] || 'N/A'}`;
       }
       case 'state_changed': {
         const prev = (service?.['previousState'] as AnyObj | undefined)?.['state'] || '?';
@@ -124,13 +124,13 @@ export class HistoryFormatter {
 
   formatOwner(task: AnyObj, agentId: string): string {
     const ag = task['agreement'] as AnyObj | undefined;
-    const creatorId = (ag?.['parties'] as AnyObj | undefined)?.['creatorId'] ?? task['agentId'];
+    const creatorId = (ag?.['parties'] as AnyObj | undefined)?.['creator'] ?? task['agentId'];
     return creatorId === agentId ? 'You' : String(creatorId ?? 'N/A');
   }
 
   formatExecutor(task: AnyObj, agentId: string): string {
     const ag = task['agreement'] as AnyObj | undefined;
-    const providerId = (ag?.['parties'] as AnyObj | undefined)?.['providerId'] ?? task['executorId'];
+    const providerId = (ag?.['parties'] as AnyObj | undefined)?.['provider'] ?? task['executorId'];
     return providerId === agentId ? 'You' : String(providerId ?? 'N/A');
   }
 

package/src/index.ts

@@ -20,7 +20,7 @@ export { OutboxBuffer } from './server/OutboxBuffer.js';
 export { normalizeIncomingEvent } from './ingress/normalizeIncoming.js';
 
 // Runtime primitives
-export { AgentMachine } from './runtime/AgentMachine.js';
+export { AgentMachine, type TransitionEvent } from './runtime/AgentMachine.js';
 export { runTurn } from './runtime/runTurn.js';
 export { PromptBuilder } from './runtime/PromptBuilder.js';
 export { thinkingDefaults, defineThinkingState, DEFAULT_WAIT_PROMPT } from './runtime/defaults.js';
@@ -54,21 +54,38 @@ export { AgreementService } from './server/agreements/AgreementService.js';
 export { ToolManager } from './tools/ToolManager.js';
 export { ToolProvider } from './tools/ToolProvider.js';
 export { defineTool } from './tools/defineTool.js';
+export { recordReport } from './tools/recordReport.js';
+export type { RecordReportInput, RecordReportResult, TaskReport } from './tools/recordReport.js';
 export { OpenAIAdapter } from './adapters/OpenAIAdapter.js';
 export { extractJSON, safeParseJSON } from './utils/jsonExtractor.js';
 export { HistoryFormatter, historyFormatter, AgreementFormatter, agreementFormatter } from './formatters/index.js';
 export { ProactiveTrigger } from './server/proactive/ProactiveTrigger.js';
 export { ZiggsPayClient, createZiggsPayClient } from './server/ziggspay/ZiggsPayClient.js';
+export { ZiggsConnectClient, createZiggsConnectClient } from './server/ziggsconnect/ZiggsConnectClient.js';
+export { ZiggsContextClient } from './server/ziggscontext/ZiggsContextClient.js';
+export type {
+  ZiggsContextClientOptions,
+  ContextReachDescriptor,
+  DelegateContextGrantParams,
+} from './server/ziggscontext/ZiggsContextClient.js';
+// All agent tool bundles live under server/tools/ (tier1 = protocol grammar,
+// tier2 = opt-in HTTP capability bundles). Single home: server/tools/index.ts.
 export {
+  // Tier 1 — protocol grammar (framework-managed via taskTools).
   PROTOCOL_TOOLS, agreementProposeTool, agreementSubcontractTool,
   agreementRespondTool, agreementCounterProposalTool, agreementCheckProposalTool,
   taskSpawnTool, taskUpdateTool, taskUpdatePlanStepTool,
-} from './server/tasks/protocolTools.js';
-export { PAYMENT_TOOLS, paymentBalanceTool, paymentTransferTool, paymentHoldTool, paymentReleaseTool, paymentResolveWalletTool } from './server/tasks/paymentTools.js';
+  dispatchProtocolOp,
+  // Tier 2 — opt-in capability bundles (spread into `tools:`).
+  PAYMENT_TOOLS, paymentBalanceTool, paymentTransferTool, paymentHoldTool, paymentReleaseTool, paymentResolveWalletTool,
+  CONNECTION_TOOLS, connectionProxyTool, connectionListGrantsTool,
+  DISCOVERY_TOOLS, agentSearchTool, agentGetTool,
+  MARKETPLACE_TOOLS, marketplaceViewTool,
+} from './server/tools/index.js';
 export { PROTOCOL_TOOL_NAMES, PROTOCOL_TOOL_TO_OPERATION, mapProtocolToolToOperation, isProtocolToolName } from './tasks/protocolRegistry.js';
-export { dispatchProtocolOp } from './server/tasks/protocolRunner.js';
 export { InMemoryStore, FileMemoryStore } from './memory/MemoryStore.js';
 export type { MemoryStore } from './memory/MemoryStore.js';
+export type { SessionStore } from './AgentHost.js';
 export { classifyIncomingEvent } from './context/classifyEnvelope.js';
 export { buildContextUpdates, CONTEXT_RESET } from './context/applyEffects.js';
 export { getBatchEvents, isTaskResultRelevantToAgent } from './context/batch.js';
@@ -83,4 +100,8 @@ export {
   getWebSocketUrl,
 } from '@ziggs-ai/api-client';
 
+export { runInboxCatchUp } from './server/InboxCatchUp.js';
+export type { InboxCatchUpDeps, InboxCatchUpResult } from './server/InboxCatchUp.js';
+export { SeenMessages } from './server/SeenMessages.js';
 export { runtimeLog, resetRuntimeLogLevelCache } from './shared/runtimeLog.js';
+export type { RuntimeLogLevel } from './shared/runtimeLog.js';