@ziggs-ai/agent-sdk 0.1.11 → 0.1.12

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,10 +344,12 @@ 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) => {
+          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
@@ -291,88 +361,27 @@ export function createZiggsEffectHandler(deps: ZiggsEffectDeps): EffectHandler {
               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

@@ -57,7 +57,8 @@ export class TaskService {
       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;
     }
   }