@ziggs-ai/agent-sdk 0.1.10 → 0.1.12

package/src/server/InboxCatchUp.ts

@@ -3,6 +3,7 @@ import {
   ContextDiscoveryClient,
   InboxClient,
   getChatsForAgreement,
+  getAgreementStatus,
   type InboxScopeEntry,
   type InboxAck,
   type Creds,
@@ -40,6 +41,22 @@ function warn(label: string, msg: string): void {
   runtimeLog.warn(label, msg);
 }
 
+const TERMINAL_AGREEMENT_STATUSES = new Set(['fulfilled', 'cancelled', 'refunded']);
+
+/** ZIG-832 P4: is this agreement finished (so its backlog must not be re-run)? */
+async function isTerminalAgreement(agreementId: string, creds: Creds): Promise<boolean> {
+  try {
+    const res = (await getAgreementStatus(agreementId, creds)) as
+      | { status?: string; agreement?: { status?: string } }
+      | undefined;
+    const status = res?.status ?? res?.agreement?.status;
+    return status != null && TERMINAL_AGREEMENT_STATUSES.has(status);
+  } catch {
+    // On lookup failure, don't skip — fall through to normal delivery.
+    return false;
+  }
+}
+
 /** Map Mongo message row → wire metadata for normalizeIncomingEvent. */
 function rowToMetadata(row: WireRow, chatId: string): Record<string, unknown> {
   const senderRaw = row.sender as { agentId?: string; id?: string; type?: string } | undefined;
@@ -182,6 +199,26 @@ export async function runInboxCatchUp(deps: InboxCatchUpDeps): Promise<InboxCatc
   }
 
   for (const scope of envelope.scopes) {
+    // ZIG-832 P4: a re-host runs catch-up from the server watermark and would
+    // re-deliver an already-finished agreement's backlog, re-running a completed
+    // pipeline and burning tokens. If this is an agreement scope that has reached
+    // a terminal status, ack it (so it drops out of future catch-ups) and skip
+    // re-delivery. Only agreement scopes — chat scopes may carry genuinely new
+    // conversation, so those are never skipped on status. (The deeper fix, acking
+    // the watermark on the live-push path so nothing re-delivers, is tracked
+    // separately.)
+    if (
+      scope.scope.kind === 'agreement' &&
+      (scope.newMessages > 0 || scope.newArtifacts > 0) &&
+      (await isTerminalAgreement(scope.scope.id, deps.creds))
+    ) {
+      if (scope.latestAt) {
+        toAck.push({ kind: scope.scope.kind, id: scope.scope.id, upTo: scope.latestAt });
+      }
+      log(label, `scope agreement:${scope.scope.id} terminal — acked, not re-delivered`);
+      continue;
+    }
+
     const chatIds = await chatIdsForScope(scope, deps.creds, deps.baseUrl, discovery);
     if (!chatIds.length && (scope.newMessages > 0 || scope.newArtifacts > 0)) {
       warn(

package/src/server/StateTimers.ts

@@ -0,0 +1,85 @@
+import { runtimeLog } from '../shared/runtimeLog.js';
+
+export interface StateTimeoutEvent {
+  type: 'state-timeout';
+  state: string;
+  waitedMs: number;
+  epoch: number;
+}
+
+interface ArmedTimer {
+  epoch: number;
+  state: string;
+  timeoutMs: number;
+  armedAt: number;
+  handle: ReturnType<typeof setTimeout>;
+}
+
+/**
+ * Per-lane liveness timers for parked states declaring timeoutMs. Owned by
+ * AgentHost. A firing timer enqueues a state-timeout frame on the SAME lane
+ * (caller-provided enqueue → EventQueue), so it serializes behind any real
+ * event and can never race one. Epochs make stale frames identifiable: a
+ * queued timeout frame whose epoch is not the lane's currently-armed epoch was
+ * superseded (a tick ran after it fired) and must be dropped.
+ *
+ * In-memory only: process restart loses all timers; each lane re-arms on its
+ * next real event (sessionStore persists { ctx, state } but not timers).
+ */
+export class StateTimers {
+  private _timers = new Map<string, ArmedTimer>();
+  private _epoch = 0;
+  private _enqueue: (event: StateTimeoutEvent, laneKey: string) => void;
+
+  constructor(enqueue: (event: StateTimeoutEvent, laneKey: string) => void) {
+    this._enqueue = enqueue;
+  }
+
+  /** Re-arm is idempotent: any previously armed timer for the lane is cancelled first. */
+  arm(laneKey: string, state: string, timeoutMs: number): void {
+    this.clear(laneKey);
+    const epoch = ++this._epoch;
+    const handle = setTimeout(() => {
+      runtimeLog.debug('StateTimers', `fired laneKey=${laneKey} state=${state} waitedMs=${timeoutMs} epoch=${epoch}`);
+      this._enqueue({ type: 'state-timeout', state, waitedMs: timeoutMs, epoch }, laneKey);
+    }, timeoutMs);
+    (handle as unknown as { unref?: () => void }).unref?.();
+    this._timers.set(laneKey, { epoch, state, timeoutMs, armedAt: Date.now(), handle });
+  }
+
+  clear(laneKey: string): void {
+    const t = this._timers.get(laneKey);
+    if (!t) return;
+    clearTimeout(t.handle);
+    this._timers.delete(laneKey);
+  }
+
+  clearAll(): void {
+    for (const key of [...this._timers.keys()]) this.clear(key);
+  }
+
+  /**
+   * Drop stale state-timeout events from an incoming frame (single event or an
+   * EventQueue-coalesced { type: 'batch', events } frame). Returns null when
+   * nothing survives (pure stale-timeout frame — the lane's live timer, if any,
+   * must be left untouched by the caller in that case).
+   */
+  stripStale(event: unknown, laneKey: string): unknown | null {
+    const pending = this._timers.get(laneKey);
+    const fresh = (ev: unknown): boolean => {
+      const e = ev as { type?: string; epoch?: number };
+      if (e?.type !== 'state-timeout') return true;
+      const ok = pending !== undefined && e.epoch === pending.epoch;
+      if (!ok) runtimeLog.debug('StateTimers', `dropping stale state-timeout laneKey=${laneKey} epoch=${e.epoch} armed=${pending?.epoch ?? 'none'}`);
+      return ok;
+    };
+    const b = event as { type?: string; events?: unknown[] };
+    if (b?.type === 'batch' && Array.isArray(b.events)) {
+      const kept = b.events.filter(fresh);
+      if (kept.length === 0) return null;
+      if (kept.length === b.events.length) return event;
+      return kept.length === 1 ? kept[0] : { type: 'batch', events: kept };
+    }
+    return fresh(event) ? event : null;
+  }
+}

package/src/server/ZiggsEffectHandler.ts

@@ -1,10 +1,11 @@
 /**
  * Ziggs-flavored EffectHandler.
  *
- * Translates the Agent's pure Effect requests into concrete calls against
- * Ziggs backend primitives (MessagesClient, ArtifactsClient, ScopeClient,
- * taskService, agreementService, messageSender) and the OpenAI adapter. This
- * is the only place where Agent intent meets backend reality.
+ * Translates the Agent's pure Effect requests into concrete backend calls:
+ * reads go through the grant-fenced ContextReadClient snapshot, writes through
+ * artifactsClient / taskService / agreementService / messageSender, and LLM
+ * turns through the adapter. This is the only place where Agent intent meets
+ * backend reality.
  *
  * Lives in agent-sdk for now alongside `Agent`; destined for a separate
  * `@ziggs-ai/agent-server` package once the SDK split is complete.
@@ -18,15 +19,14 @@ import { runtimeLog } from '../shared/runtimeLog.js';
 /** Minimal LLM adapter contract — OpenAIAdapter satisfies this. */
 interface LlmAdapter {
   chatMessages(messages: LlmMessage[], tools?: LlmToolSchema[], options?: Record<string, unknown>): Promise<LlmResponse>;
-  chatMessagesStream?(messages: LlmMessage[], onChunk: (text: string) => void): Promise<string>;
+  chatMessagesStream?(messages: LlmMessage[], onChunk: (text: string) => void): Promise<{ text: string; usage?: LlmResponse['usage'] }>;
 }
 import type { TaskService } from './tasks/TaskService.js';
 import type { AgreementService } from './agreements/AgreementService.js';
 import type { ToolManager } from '../tools/ToolManager.js';
 import type {
-  MessagesClient,
   ArtifactsClient,
-  ScopeClient,
+  ContextReadClient,
   TelemetryClient,
 } from '@ziggs-ai/api-client';
 import {
@@ -37,10 +37,15 @@ import {
 } from './telemetryIngest.js';
 
 export interface ZiggsEffectDeps {
-  llm: LlmAdapter;
-  messagesClient: MessagesClient;
+  /**
+   * LLM adapter for `llm-call` / `stream-text`. Optional: the Claude brain
+   * drives its own model via `query()` and emits neither effect, so it wires
+   * no adapter. Those two cases throw if reached without one.
+   */
+  llm?: LlmAdapter;
   artifactsClient: ArtifactsClient;
-  scopeClient: ScopeClient;
+  /** Grant-fenced aggregate read backbone — sources the read-context snapshot. */
+  contextReadClient: ContextReadClient;
   taskService: TaskService;
   agreementService: AgreementService;
   messageSender: (text: string, receiverId: string, sessionId: string, messageId?: string) => Promise<unknown>;
@@ -58,69 +63,47 @@ export interface ZiggsEffectDeps {
 const CONTEXT_CACHE_MAX = 256;
 
 /**
- * Compose a `ContextSnapshot` for a chatId by fanning out to scope + messages
- * primitives. Replaces the single `/context/read` aggregator with parallel
- * pulls. The shape stays the same so PromptBuilder / cognition code doesn't
- * change.
+ * Compose a `ContextSnapshot` for a chatId via the grant-fenced aggregate read
+ * (`GET /context/snapshot`, ZIG-775 follow-up). The backend assembles history +
+ * agreements + roster through the same `assertScopeAccess` + temporal fence as
+ * the per-type context reads, and annotates `*IsYou` / self server-side against
+ * the acting agent. This function only preserves the never-throw/degrade
+ * contract that the cognition code depends on — the shape is unchanged.
  */
-const annotateAgreement = (ag: Record<string, unknown>, agentId: string): Record<string, unknown> => {
-  const parties = (ag?.parties ?? {}) as { creator?: string; provider?: string; payer?: string; proposedTo?: string };
-  return {
-    ...ag,
-    creatorIsYou: parties.creator === agentId,
-    providerIsYou: parties.provider === agentId,
-    payerIsYou: parties.payer === agentId,
-    proposedToIsYou: parties.proposedTo === agentId,
-  };
-};
+const emptySnapshot = (agentId: string, chatMissing = false): ContextSnapshot => ({
+  history: [],
+  agreements: [],
+  users: [],
+  agents: [{ agentId, role: 'self', isYou: true }],
+  latestSequence: null,
+  ...(chatMissing ? { chatMissing: true } : {}),
+});
 
 async function buildSnapshot(
   deps: ZiggsEffectDeps,
   chatId: string,
   agentId: string,
-  opts: { after?: string; limit?: number } = {},
+  opts: { limit?: number } = {},
 ): Promise<ContextSnapshot> {
-  const [scope, msgs, chatAgreements] = await Promise.all([
-    deps.scopeClient.get('chat', chatId).catch((err: unknown) => {
-      runtimeLog.warn('ZiggsEffectHandler', `scope fetch failed: ${(err as Error)?.message ?? err}`);
-      return null;
-    }),
-    deps.messagesClient
-      .list(chatId, { after: opts.after, limit: opts.limit })
-      .catch((err: unknown) => {
-        runtimeLog.warn('ZiggsEffectHandler', `messages fetch failed: ${(err as Error)?.message ?? err}`);
-        return { messages: [], latestSequence: null };
-      }),
-    deps.agreementService.getByChat(chatId).catch((err: unknown) => {
-      runtimeLog.warn('ZiggsEffectHandler', `agreements fetch failed: ${(err as Error)?.message ?? err}`);
-      return [] as unknown[];
-    }),
-  ]);
-
-  const counterparties = (scope?.accessible?.counterparties ?? []) as Array<{
-    id: string;
-    role: string;
-    principalType?: 'user' | 'agent';
-  }>;
-
-  const others = counterparties.filter((c) => c.id !== agentId);
-  const users = others
-    .filter((c) => c.principalType === 'user')
-    .map((c) => ({ userId: c.id, role: c.role }));
-  const agents = others
-    .filter((c) => c.principalType !== 'user') // 'agent' or missing → treat as agent
-    .map((c) => ({ agentId: c.id, role: c.role, isYou: false }));
-  agents.push({ agentId, role: 'self', isYou: true });
-
-  const agreements = (chatAgreements as Record<string, unknown>[]).map((ag) => annotateAgreement(ag, agentId));
-
-  return {
-    history: msgs.messages as Record<string, unknown>[],
-    agreements,
-    agents,
-    users,
-    latestSequence: msgs.latestSequence,
-  };
+  try {
+    // Server returns 200 + chatMissing:true for a deleted chat, so its
+    // annotations (roster, *IsYou, self) are already applied — pass through.
+    const snap = await deps.contextReadClient.snapshot(chatId, {
+      maxMessages: opts.limit,
+    });
+    return snap as ContextSnapshot;
+  } catch (err: unknown) {
+    // Defensive: server normally signals a dead chat as 200 + chatMissing, but
+    // a raw 404 degrades the same way so message wakes still skip it.
+    if ((err as { status?: number })?.status === 404) {
+      return emptySnapshot(agentId, true);
+    }
+    runtimeLog.warn(
+      'ZiggsEffectHandler',
+      `snapshot fetch failed: ${(err as Error)?.message ?? err}`,
+    );
+    return emptySnapshot(agentId);
+  }
 }
 
 const OP_ARTIFACT_MAX_CHARS = 900;
@@ -178,6 +161,126 @@ async function emitToolOperationArtifact(
   }
 }
 
+/**
+ * The single tool-execution path for BOTH cognitions (ZIG-775).
+ *
+ * Executing a tool is more than calling its handler: it emits the operation
+ * timeline artifacts (started / completed / error) and tool telemetry, and
+ * resolves the invoking user + roster. The FSM reaches this via
+ * `eff({ kind: 'tool-call' })` inside `runTurn`; the Claude Agent SDK bridge
+ * (`toolManagerToSdkMcp`) emits the SAME effect — so a hosted Claude-brain
+ * agent's tool activity is as observable as an FSM agent's (needed for
+ * hired-agent visibility, ZIG-535). A caller cannot run a tool and skip these
+ * side effects — that is the whole point of funneling both paths here.
+ *
+ * `eff` is threaded into the tool context so eff-backed tools
+ * (`ziggs_context_snapshot`, `ziggs_send_message`) resolve through this same path
+ * regardless of which cognition invoked them.
+ */
+export async function executeToolWithSideEffects(
+  deps: Pick<
+    ZiggsEffectDeps,
+    | 'toolManager'
+    | 'artifactsClient'
+    | 'telemetryClient'
+    | 'telemetryIngest'
+    | 'operatorKey'
+    | 'agentId'
+    | 'taskService'
+    | 'agreementService'
+    | 'contextReadClient'
+    | 'messageSender'
+  >,
+  eff: EffectHandler,
+  effect: Extract<Effect, { kind: 'tool-call' }>,
+  roster: { agents: unknown[]; users: unknown[] },
+): Promise<ToolCallResult> {
+  const toolT0 = Date.now();
+  const args = (effect.args as Record<string, unknown>) || {};
+  const argsPreview = previewToolArgs(args);
+  await emitToolOperationArtifact(deps.artifactsClient, effect.sessionId, 'started', {
+    state: 'started',
+    tool: effect.name,
+    ...(argsPreview ? { args: argsPreview } : {}),
+  });
+  try {
+    const lastUser = (roster.users as Array<{ userId?: string; id?: string }>).find(
+      (u) => u.userId || u.id,
+    );
+    // Accumulate token usage from any nested LLM call the tool makes (llmTool),
+    // so it can be folded into the turn's authoritative token count (ZIG-813).
+    let nestedUsage: { prompt_tokens: number; completion_tokens: number; total_tokens: number } | undefined;
+    const reportUsage = (u: LlmResponse['usage']): void => {
+      if (!u) return;
+      const p = u.prompt_tokens ?? u.promptTokens ?? 0;
+      const c = u.completion_tokens ?? u.completionTokens ?? 0;
+      const t = u.total_tokens ?? u.totalTokens ?? p + c;
+      nestedUsage = {
+        prompt_tokens: (nestedUsage?.prompt_tokens ?? 0) + p,
+        completion_tokens: (nestedUsage?.completion_tokens ?? 0) + c,
+        total_tokens: (nestedUsage?.total_tokens ?? 0) + t,
+      };
+    };
+    const result = await deps.toolManager.executeTool(effect.name, args, {
+      operatorKey: deps.operatorKey,
+      agentId: deps.agentId,
+      chatId: effect.sessionId,
+      taskService: deps.taskService,
+      agreementService: deps.agreementService,
+      contextReadClient: deps.contextReadClient,
+      sendMessage: deps.messageSender,
+      eff,
+      agents: roster.agents,
+      users: roster.users,
+      senderId: effect.senderId ?? lastUser?.userId ?? lastUser?.id,
+      senderType: effect.senderType ?? (lastUser ? 'USER' : undefined),
+      onBehalfOfAgreementId: effect.onBehalfOfAgreementId,
+      memory: effect.memory,
+      reportUsage,
+      turnScratch: {},
+    });
+    await emitToolOperationArtifact(deps.artifactsClient, effect.sessionId, 'completed', {
+      state: 'completed',
+      tool: effect.name,
+      result: clipForOperationArtifact(result),
+    });
+    sendTelemetry(
+      deps.telemetryClient,
+      buildToolIngestPayload({
+        sessionId: effect.sessionId,
+        tool: effect.name,
+        durationMs: Date.now() - toolT0,
+        ok: true,
+        runId: effect.runId,
+        stateId: effect.stateId,
+      }),
+      isTelemetryIngestEnabled(deps.telemetryIngest),
+    );
+    return { ok: true, result, ...(nestedUsage ? { usage: nestedUsage } : {}) } satisfies ToolCallResult;
+  } catch (error: unknown) {
+    const errMsg = (error as Error)?.message ?? String(error);
+    runtimeLog.warn('ZiggsEffectHandler', `tool-call "${effect.name}" failed: ${errMsg}`);
+    await emitToolOperationArtifact(deps.artifactsClient, effect.sessionId, 'error', {
+      state: 'failed',
+      tool: effect.name,
+      error: errMsg,
+    });
+    sendTelemetry(
+      deps.telemetryClient,
+      buildToolIngestPayload({
+        sessionId: effect.sessionId,
+        tool: effect.name,
+        durationMs: Date.now() - toolT0,
+        ok: false,
+        runId: effect.runId,
+        stateId: effect.stateId,
+      }),
+      isTelemetryIngestEnabled(deps.telemetryIngest),
+    );
+    return { ok: false, error: errMsg } satisfies ToolCallResult;
+  }
+}
+
 /**
  * Build a single shared EffectHandler. The handler is stateful — it caches
  * the latest ContextSnapshot per sessionId so tool-call effects can resolve
@@ -209,10 +312,10 @@ export function createZiggsEffectHandler(deps: ZiggsEffectDeps): EffectHandler {
   const dispatch = async (effect: Effect): Promise<unknown> => {
     switch (effect.kind) {
       case 'read-context': {
-        // Composite: assembles ContextSnapshot from scope + messages.
-        // Each agent runtime still gets the same shape, but the backend has
-        // no `/context/read` — assembly happens here, where the agent's
-        // identity is in scope.
+        // Grant-fenced aggregate read: the backend composes the ContextSnapshot
+        // (GET /context/snapshot) through the same access + temporal fence as
+        // the per-type reads. Every producer — ClaudeSdkAgent.tick, runTurn,
+        // and the on-demand ziggs_context_snapshot tool — routes through here.
         const snap = await buildSnapshot(deps, effect.sessionId, deps.agentId, {
           limit: effect.opts?.maxMessages,
         });
@@ -222,44 +325,9 @@ export function createZiggsEffectHandler(deps: ZiggsEffectDeps): EffectHandler {
         return snap;
       }
 
-      case 'list-messages': {
-        return deps.messagesClient.list(effect.chatId, {
-          after: effect.after,
-          limit: effect.limit,
-        });
-      }
-
-      case 'list-artifacts': {
-        return deps.artifactsClient.list(
-          { chatId: effect.chatId, agreementId: effect.agreementId },
-          { after: effect.after, limit: effect.limit },
-        );
-      }
-
-      case 'list-task-history': {
-        const url = new URL(
-          `${process.env.ZIGGS_BACKEND_URL ?? 'http://localhost:3000'}/tasks/${effect.taskId}/history`,
-        );
-        if (effect.after) url.searchParams.set('after', effect.after);
-        if (effect.limit != null) url.searchParams.set('limit', String(effect.limit));
-        const res = await fetch(url.toString(), {
-          headers: {
-            'content-type': 'application/json',
-            Authorization: `Bearer ${deps.operatorKey}`,
-            'X-Agent-Id': deps.agentId,
-          },
-        });
-        if (!res.ok) {
-          throw new Error(`list-task-history ${res.status} ${res.statusText}`);
-        }
-        return res.json();
-      }
-
-      case 'get-scope': {
-        return deps.scopeClient.get(effect.via.kind, effect.via.id);
-      }
 
       case 'llm-call': {
+        if (!deps.llm) throw new Error('llm-call effect requires an LLM adapter — none configured for this cognition');
         const t0 = Date.now();
         const r: LlmResponse = await deps.llm.chatMessages(effect.messages, effect.tools);
         sendTelemetry(
@@ -276,94 +344,44 @@ export function createZiggsEffectHandler(deps: ZiggsEffectDeps): EffectHandler {
       }
 
       case 'stream-text': {
+        if (!deps.llm) throw new Error('stream-text effect requires an LLM adapter — none configured for this cognition');
         const { sessionId, receiverId, messageId, messages } = effect;
         let text = '';
+        let usage: LlmResponse['usage'];
         if (deps.llm.chatMessagesStream) {
-          text = await deps.llm.chatMessagesStream(messages as LlmMessage[], (chunk) => {
-            deps.chunkSender?.(sessionId, receiverId, chunk, messageId);
+          const streamed = await deps.llm.chatMessagesStream(messages as LlmMessage[], (chunk) => {
+            // Live-stream display is best-effort. The transport's send rejects
+            // empty/whitespace-only content (WebSocketClient: content.trim() === ''),
+            // and a whitespace-only chunk (e.g. a leading newline) is truthy yet
+            // still throws — which, uncaught, aborts the whole stream and loses the
+            // entire reply (e.g. a composer's final synthesis). Swallow chunk-send
+            // failures; `text` accumulates independently and the final send-message
+            // (below, in runTurn) carries the full reply regardless.
+            try {
+              if (chunk && chunk.trim()) deps.chunkSender?.(sessionId, receiverId, chunk, messageId);
+            } catch { /* ignore — streaming display only */ }
           });
+          text = streamed.text;
+          usage = streamed.usage;
         } else {
           const r = await deps.llm.chatMessages(messages as LlmMessage[]);
           text = r.content ?? '';
+          usage = r.usage;
           if (text) deps.chunkSender?.(sessionId, receiverId, text, messageId);
         }
-        return { text };
+        return { text, usage };
       }
 
       case 'tool-call': {
-        const toolT0 = Date.now();
+        // Roster comes from the cached snapshot (populated by read-context). Both
+        // cognitions land here — the FSM via runTurn's executeTool, the Claude
+        // Agent SDK via the toolManagerToSdkMcp bridge — so tool side effects are
+        // emitted exactly once, in one place (ZIG-775).
         const cached = cacheGet(effect.sessionId);
-        const agents = (cached?.agents as unknown[]) || [];
-        const users = (cached?.users as unknown[]) || [];
-        const args = (effect.args as Record<string, unknown>) || {};
-        const argsPreview = previewToolArgs(args);
-        await emitToolOperationArtifact(deps.artifactsClient, effect.sessionId, 'started', {
-          state: 'started',
-          tool: effect.name,
-          ...(argsPreview ? { args: argsPreview } : {}),
+        return executeToolWithSideEffects(deps, handler as EffectHandler, effect, {
+          agents: (cached?.agents as unknown[]) || [],
+          users: (cached?.users as unknown[]) || [],
         });
-        try {
-          const lastUser = (users as Array<{ userId?: string; id?: string }>).find(
-            (u) => u.userId || u.id,
-          );
-          const result = await deps.toolManager.executeTool(
-            effect.name,
-            args,
-            {
-              operatorKey: deps.operatorKey,
-              agentId: deps.agentId,
-              chatId: effect.sessionId,
-              taskService: deps.taskService,
-              agreementService: deps.agreementService,
-              sendMessage: deps.messageSender,
-              agents,
-              users,
-              senderId: effect.senderId ?? lastUser?.userId ?? lastUser?.id,
-              senderType: effect.senderType ?? (lastUser ? 'USER' : undefined),
-              memory: effect.memory,
-              turnScratch: {},
-            },
-          );
-          await emitToolOperationArtifact(deps.artifactsClient, effect.sessionId, 'completed', {
-            state: 'completed',
-            tool: effect.name,
-            result: clipForOperationArtifact(result),
-          });
-          sendTelemetry(
-            deps.telemetryClient,
-            buildToolIngestPayload({
-              sessionId: effect.sessionId,
-              tool: effect.name,
-              durationMs: Date.now() - toolT0,
-              ok: true,
-              runId: effect.runId,
-              stateId: effect.stateId,
-            }),
-            isTelemetryIngestEnabled(deps.telemetryIngest),
-          );
-          return { ok: true, result } satisfies ToolCallResult;
-        } catch (error: unknown) {
-          const errMsg = (error as Error)?.message ?? String(error);
-          runtimeLog.warn('ZiggsEffectHandler', `tool-call "${effect.name}" failed: ${errMsg}`);
-          await emitToolOperationArtifact(deps.artifactsClient, effect.sessionId, 'error', {
-            state: 'failed',
-            tool: effect.name,
-            error: errMsg,
-          });
-          sendTelemetry(
-            deps.telemetryClient,
-            buildToolIngestPayload({
-              sessionId: effect.sessionId,
-              tool: effect.name,
-              durationMs: Date.now() - toolT0,
-              ok: false,
-              runId: effect.runId,
-              stateId: effect.stateId,
-            }),
-            isTelemetryIngestEnabled(deps.telemetryIngest),
-          );
-          return { ok: false, error: errMsg } satisfies ToolCallResult;
-        }
       }
 
       case 'send-message': {

package/src/server/agreements/AgreementService.ts

@@ -1,7 +1,7 @@
 import {
   proposeAgreement, proposeBroadcast as proposeBroadcastApi, delegateAgreement, respondToAgreement, counterAgreement,
   getAgreementStatus, listAgreements, getMyAgreements, getAgreement,
-  publishOffer as publishOfferApi, createAgreement, revokeAgreement, getAgreementsByChat, linkAgreementToChat,
+  publishOffer as publishOfferApi, createAgreement, revokeAgreement, fulfillAgreement, linkAgreementToChat,
   getChatsForAgreement, joinAgreement, linkArtifactToAgreement, getArtifactsForAgreement,
   linkUserToAgreement, getUsersForAgreement,
   type Creds, type Agreement,
@@ -84,8 +84,8 @@ export class AgreementService {
     return revokeAgreement(agreementId, this.creds);
   }
 
-  getByChat(chatId: string): Promise<unknown[]> {
-    return getAgreementsByChat(chatId, this.creds);
+  fulfill(agreementId: string): Promise<{ ok: boolean; agreement: Agreement }> {
+    return fulfillAgreement(agreementId, this.creds);
   }
 
   linkToChat(agreementId: string, chatId: string, linkType: ChatLinkType = 'mention'): Promise<unknown | null> {

package/src/server/tasks/TaskService.ts

@@ -1,6 +1,6 @@
 import {
   createTask, getTask, getActiveTasksForAgent, getActiveTasksForChat, getSubtasks,
-  updateTaskState, cancelTask,
+  updateTaskState, updateTaskPlanStep, cancelTask,
   reportTask, setTaskSatisfaction, countTasks,
   type Creds, type Task, type TaskState,
 } from '@ziggs-ai/api-client';
@@ -50,14 +50,15 @@ export class TaskService {
     return getSubtasks(parentTaskId, this.creds);
   }
 
-  async spawnUnderAgreement(agreementId: string, taskData: { description: string; parentTaskId?: string; plan?: unknown; planReviewTiming?: string; requireMidWorkPlanAck?: boolean; assigneeId?: string }): Promise<Task> {
+  async spawnUnderAgreement(agreementId: string, taskData: { description: string; parentTaskId?: string; plan?: unknown; planReviewTiming?: string; requireMidWorkPlanAck?: boolean; assigneeId?: string; inputArtifactIds?: 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);
       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}`);
+      const e = error as { message?: string; status?: number; body?: string };
+      runtimeLog.error('TaskService', `Task spawn failed (agreement ${agreementId}, assignee ${taskData.assigneeId ?? '-'}): status=${e.status ?? '?'} ${e.message}${e.body ? ` | body=${e.body}` : ''}`);
       throw error;
     }
   }
@@ -74,6 +75,17 @@ export class TaskService {
     }
   }
 
+  async updatePlanStep(taskId: string, stepId: string, status: string, result?: unknown): Promise<Task> {
+    try {
+      const updated = await updateTaskPlanStep(taskId, stepId, status, result, this.creds);
+      runtimeLog.info('TaskService', `Task plan step: ${taskId}/${stepId} → ${status}`);
+      return updated;
+    } catch (error) {
+      runtimeLog.error('TaskService', `Task plan step update failed: ${(error as Error).message}`);
+      throw error;
+    }
+  }
+
   async cancel(taskId: string): Promise<Task> {
     try {
       const updated = await cancelTask(taskId, this.creds);