@ziggs-ai/agent-sdk 0.1.11 → 0.1.12

package/src/runtime/runMechanical.ts

@@ -0,0 +1,106 @@
+import type {
+  Action,
+  Ctx,
+  EffectHandler,
+  MechanicalState,
+  Outcome,
+  ToolResultEntry,
+} from '../types.js';
+import type { MemoryStore } from '../memory/MemoryStore.js';
+import { outcomeFromActionResult, type EmittedEvent, type RawEvent, type WireResult } from './buildOutcome.js';
+import { runtimeLog } from '../shared/runtimeLog.js';
+import type { ToolCallResult } from '../types.js';
+
+export interface RunMechanicalResult {
+  outcome: Outcome;
+  toolResults: ToolResultEntry[];
+  llmCalls: number;
+  tokens: { total: number; input: number; output: number };
+}
+
+/**
+ * ZIG-764: run a mechanical state — invoke one bound tool with no LLM turn.
+ * Used by dumb coordinators whose only job is a fixed tool call on task-assigned.
+ */
+export async function runMechanical(input: {
+  stateId: string;
+  state: MechanicalState;
+  ctx: Ctx;
+  eff: EffectHandler;
+  memory?: MemoryStore;
+  incomingEvent: RawEvent | null;
+}): Promise<RunMechanicalResult> {
+  const { stateId, state, ctx, eff, memory, incomingEvent } = input;
+  const sessionId = ctx.identity.sessionId;
+  const runId = crypto.randomUUID();
+
+  const effWithTrace: typeof eff = (effect) => {
+    if (effect.kind === 'tool-call') {
+      return eff({ ...effect, runId, stateId } as typeof effect);
+    }
+    return eff(effect);
+  };
+
+  runtimeLog.info('runMechanical', `enter state=${stateId} tool=${state.tool}`);
+
+  const args =
+    typeof state.buildArgs === 'function'
+      ? state.buildArgs(ctx, ctx.lastOutcome)
+      : { ...(state.args ?? {}) };
+
+  const pseudoAction: Action = {
+    prompt: { instruction: '' },
+    tool: state.tool,
+    produces: state.produces,
+  };
+
+  let emitted: EmittedEvent[] = [];
+  try {
+    const r = await effWithTrace({
+      kind: 'tool-call',
+      sessionId,
+      name: state.tool,
+      args,
+      memory,
+      senderId: incomingEvent?.senderId != null ? String(incomingEvent.senderId) : undefined,
+      senderType: incomingEvent?.senderType != null ? String(incomingEvent.senderType) : undefined,
+    }) as ToolCallResult;
+
+    if (!r.ok) {
+      emitted = [{ type: 'tool_error', tool: state.tool, error: r.error || 'unknown', senderId: 'system' }];
+    } else if (r.events && (r.events as unknown[]).length > 0) {
+      emitted = r.events as unknown as EmittedEvent[];
+    } else {
+      emitted = [{ type: 'tool_result', tool: state.tool, result: r.result as WireResult | undefined, senderId: 'system' }];
+    }
+  } catch (error: unknown) {
+    emitted = [
+      {
+        type: 'tool_error',
+        tool: state.tool,
+        error: (error as Error)?.message ?? String(error),
+        senderId: 'system',
+      },
+    ];
+  }
+
+  const toolResults: ToolResultEntry[] = [];
+  let outcome = outcomeFromActionResult('__mechanical__', pseudoAction, args, emitted, toolResults);
+  if (emitted.some((e) => e?.type === 'tool_error')) {
+    outcome = {
+      kind: 'error',
+      source: 'tool',
+      cause: emitted.find((e) => e?.type === 'tool_error')?.error ?? 'tool failed',
+      retryable: false,
+    };
+  }
+
+  runtimeLog.info('runMechanical', `done state=${stateId} outcome=${outcome.kind} llmCalls=0`);
+
+  return {
+    outcome,
+    toolResults,
+    llmCalls: 0,
+    tokens: { total: 0, input: 0, output: 0 },
+  };
+}

package/src/runtime/runTurn.ts

@@ -68,7 +68,14 @@ interface RunTurnInput {
    */
   memory?: MemoryStore;
   definition: { description?: string };
-  /** When true, respond actions use 2-call streaming: Call 1 picks action+receiverId, Call 2 streams the text (ZIG-471). */
+  /**
+   * Respond actions use 2-call streaming: Call 1 picks action+receiverId,
+   * Call 2 streams the text (ZIG-471). On by default (ZIG-838); pass false
+   * (or set ENABLE_LLM_STREAMING=false) to fold the reply text back into the
+   * single decision call. The env flag is a deployment kill-switch — the
+   * streaming path once broke long replies in production, so ops keeps a way
+   * to disable it without a code change.
+   */
   streamRespondActions?: boolean;
 }
 
@@ -97,7 +104,10 @@ interface RunTurnResult {
  */
 export async function runTurn(input: RunTurnInput): Promise<RunTurnResult> {
   const { stateId, statePrompt, actions, incomingEvent, ctx, eff, toolManager, promptBuilder, memory, definition } = input;
-  const streamRespondActions = input.streamRespondActions ?? (process.env.ENABLE_LLM_STREAMING === 'true');
+  // Default on (ZIG-838); ENABLE_LLM_STREAMING=false is the deployment
+  // kill-switch. Any other value (unset, 'true', …) streams.
+  const streamRespondActions =
+    input.streamRespondActions ?? process.env.ENABLE_LLM_STREAMING !== 'false';
   const sessionId = ctx.identity.sessionId;
   const runId = crypto.randomUUID();
 
@@ -143,6 +153,22 @@ export async function runTurn(input: RunTurnInput): Promise<RunTurnResult> {
   const serverContext = await effWithTrace({ kind: 'read-context', sessionId, opts: {} });
   const ctxObj = normalizeContextSnapshot(serverContext);
 
+  // A message wake whose chat no longer resolves (deleted, or never visible
+  // to this agent) has no world to decide over — deciding anyway means
+  // reasoning about a fabricated empty history plus whatever stale scraps
+  // other fetches returned. Skip the LLM and park. Gated on message wakes
+  // only: agreement-keyed task lanes (sessionId = agreementId) always trip
+  // chatMissing and must still run.
+  if (ctxObj.chatMissing && ctx.lastOutcome?.kind === 'message-received') {
+    runtimeLog.warn('runTurn', `chat ${sessionId} not found on backend — skipping message wake (state=${stateId})`);
+    return {
+      outcome: { kind: 'wait' },
+      toolResults: [],
+      llmCalls: 0,
+      tokens: { total: 0, input: 0, output: 0 },
+    };
+  }
+
   const prompt = promptBuilder.buildFromState({
     statePrompt, actions,
     serverContext: { context: ctxObj as Record<string, unknown>, tools: tools as unknown as Record<string, unknown>[] },
@@ -165,6 +191,15 @@ export async function runTurn(input: RunTurnInput): Promise<RunTurnResult> {
   let lastArgs: unknown = null;
   let llmCallsTotal = 0;
   let tokensTotal = 0, tokensInput = 0, tokensOutput = 0;
+  // Fold a tool's nested LLM usage (llmTool) into the turn's authoritative
+  // token count so tool-internal spend reaches result.metrics (ZIG-813).
+  const addToolUsage = (u: LlmResponse['usage']): void => {
+    if (!u) return;
+    llmCallsTotal++;
+    tokensTotal  += (u.total_tokens  ?? u.totalTokens)  || 0;
+    tokensInput  += (u.prompt_tokens ?? u.promptTokens) || 0;
+    tokensOutput += (u.completion_tokens ?? u.completionTokens) || 0;
+  };
   // Tracks whether a successful agreement creation has already happened in
   // this turn. Used by annotateToolCallDedup to reject any second creation
   // attempt across iterations of the tool loop.
@@ -265,7 +300,7 @@ export async function runTurn(input: RunTurnInput): Promise<RunTurnResult> {
         try { args = JSON.parse(tc.function.arguments || '{}'); } catch {}
         const decision = { action: matchingAction, tool: toolName, args };
 
-        const result = await executeDecision(decision, actionDef, effWithTrace, sessionId, memory);
+        const result = await executeDecision(decision, actionDef, effWithTrace, sessionId, memory, null, addToolUsage);
         toolCallResults.push({ tc, matchingAction, result, args, actionDef });
       }
 
@@ -349,7 +384,19 @@ export async function runTurn(input: RunTurnInput): Promise<RunTurnResult> {
         try {
           const streamResult = await eff({ kind: 'stream-text', sessionId, receiverId: decision.receiverId, messageId: streamMessageId, messages: streamMessages });
           replyText = streamResult.text ?? '';
-          runtimeLog.info('runTurn', `stream-text done chars=${replyText.length}`);
+          // Count the streamed reply only when it actually produced the text we
+          // send (an empty resolve falls through to the llm-call fallback below,
+          // which counts itself). The streamed reply is a real billed completion
+          // (call 2 of ZIG-471 2-call streaming) — count it or the largest single
+          // output of the turn leaks from every usage/cost sink (ZIG-813).
+          if (replyText) {
+            llmCallsTotal++;
+            const su = streamResult.usage;
+            tokensTotal  += (su?.total_tokens  ?? su?.totalTokens)  || 0;
+            tokensInput  += (su?.prompt_tokens ?? su?.promptTokens) || 0;
+            tokensOutput += (su?.completion_tokens ?? su?.completionTokens) || 0;
+            runtimeLog.info('runTurn', `stream-text done chars=${replyText.length} tokens=${(su?.total_tokens ?? su?.totalTokens) || 0}`);
+          }
         } catch (err) {
           // Streaming transport failed before the reply text existed (call 2
           // runs inside the stream-text effect). Fall back to a plain
@@ -385,7 +432,7 @@ export async function runTurn(input: RunTurnInput): Promise<RunTurnResult> {
 
       let result: EmittedEvent[] | EmittedEvent | null;
       try {
-        result = await executeDecision(decision, actionDef, eff, sessionId, memory);
+        result = await executeDecision(decision, actionDef, eff, sessionId, memory, null, addToolUsage);
       } catch (err) {
         // Only outbound sends can throw out of executeDecision — executeTool
         // traps its own errors into tool_error events. A throw here means the
@@ -613,17 +660,18 @@ async function executeDecision(
   sessionId: string,
   memory?: MemoryStore,
   incomingEvent: RawEvent | null = null,
+  onUsage?: (usage: LlmResponse['usage']) => void,
 ): Promise<EmittedEvent[] | EmittedEvent | null> {
   const boundTool = actionDef?.tool || null;
 
   if (boundTool) {
     decision.tool = boundTool;
-    return await executeTool(decision, eff, sessionId, memory, incomingEvent);
+    return await executeTool(decision, eff, sessionId, memory, incomingEvent, onUsage);
   }
   if (decision.action === '_genericDiscoveryTool' && decision.tool) {
-    return await executeTool(decision, eff, sessionId, memory, incomingEvent);
+    return await executeTool(decision, eff, sessionId, memory, incomingEvent, onUsage);
   }
-  if (decision.tool) return await executeTool(decision, eff, sessionId, memory, incomingEvent);
+  if (decision.tool) return await executeTool(decision, eff, sessionId, memory, incomingEvent, onUsage);
   if (decision.messages && Array.isArray(decision.messages) && decision.messages.length > 0) {
     return await executeSendMessages(decision, eff, sessionId);
   }
@@ -722,6 +770,7 @@ async function executeTool(
   sessionId: string,
   memory?: MemoryStore,
   incomingEvent: RawEvent | null = null,
+  onUsage?: (usage: LlmResponse['usage']) => void,
 ): Promise<EmittedEvent[] | EmittedEvent | null> {
   const { tool, args } = decision;
   if (!tool) return null;
@@ -734,7 +783,15 @@ async function executeTool(
       memory,
       senderId: incomingEvent?.senderId != null ? String(incomingEvent.senderId) : undefined,
       senderType: incomingEvent?.senderType != null ? String(incomingEvent.senderType) : undefined,
+      // ZIG-831: the subcontract agreement this wake is under (task events carry
+      // it under `result.agreementId`) so a delegated per-user MCP call can
+      // resolve the originating end-user, not the delegating agent (senderId).
+      onBehalfOfAgreementId: (() => {
+        const aid = (incomingEvent?.result as { agreementId?: unknown } | undefined)?.agreementId;
+        return typeof aid === 'string' && aid ? aid : undefined;
+      })(),
     }) as ToolCallResult;
+    if (r.usage) onUsage?.(r.usage);
     if (!r.ok) return { type: 'tool_error', tool, error: r.error || 'unknown', senderId: 'system' };
     // Tools may emit terminal markers (e.g. `message_sent`, `waited`) via
     // `events` — propagate so the loop can detect terminal turns.

package/src/runtime/validateWorkflow.ts

@@ -1,16 +1,8 @@
-import type { Ctx, OutcomeKind, Workflow, ThinkingState, ParkedState } from '../types.js';
+import type { Ctx, OutcomeKind, Workflow, ThinkingState, ParkedState, MechanicalState } from '../types.js';
+import { bootstrapCtx } from './bootstrapCtx.js';
 
-export const PROBE_CTX: Ctx = {
-  identity: { agentId: '', sessionId: '', laneKey: '' },
-  activeAgreementId: null,
-  activeTaskId: null,
-  pendingProposalAgreementId: null,
-  delegatedAgreementIds: [],
-  pendingSubtasks: {},
-  collectedResults: [],
-  toolResults: [],
-  lastOutcome: { kind: 'enter' },
-};
+/** Static probe ctx for evaluating transition `when` guards during validation. */
+export const PROBE_CTX: Ctx = bootstrapCtx({ agentId: '', sessionId: '', laneKey: '' });
 
 // 'state-timeout' is intentionally absent: it is a runtime-generated liveness
 // outcome, never something an action's `produces` may declare.
@@ -74,8 +66,8 @@ export function validateWorkflow(workflow: Workflow): ValidationResult {
       errors.push(`state "${name}" is not an object`);
       continue;
     }
-    if (state.kind !== 'parked' && state.kind !== 'thinking') {
-      errors.push(`state "${name}" must declare kind: 'parked' | 'thinking'`);
+    if (state.kind !== 'parked' && state.kind !== 'thinking' && state.kind !== 'mechanical') {
+      errors.push(`state "${name}" must declare kind: 'parked' | 'thinking' | 'mechanical'`);
       continue;
     }
 
@@ -111,6 +103,33 @@ export function validateWorkflow(workflow: Workflow): ValidationResult {
         errors.push(`state "${name}" is thinking but declares timeoutMs — liveness timers apply to parked states only (thinking turns are bounded by AgentHost tickTimeoutMs)`);
       }
     }
+    if (state.kind === 'mechanical') {
+      const mech = state as MechanicalState;
+      if (!mech.tool || typeof mech.tool !== 'string') {
+        errors.push(`mechanical state "${name}" requires a tool name`);
+      }
+      if (mech.buildArgs !== undefined && typeof mech.buildArgs !== 'function') {
+        errors.push(`mechanical state "${name}" buildArgs must be a function`);
+      }
+      if ((mech as unknown as ThinkingState).prompt) {
+        errors.push(`state "${name}" is mechanical but has a prompt — use kind: 'thinking' instead`);
+      }
+      if ((mech as unknown as ThinkingState).actions) {
+        errors.push(`state "${name}" is mechanical but has actions — use kind: 'thinking' instead`);
+      }
+      const p = mech.produces;
+      if (p === 'state-timeout') {
+        errors.push(`mechanical state "${name}" produces "state-timeout" — reserved for runtime liveness timers`);
+      } else if (typeof p === 'string') {
+        if (!KNOWN_OUTCOME_KINDS.has(p as OutcomeKind)) {
+          errors.push(
+            `mechanical state "${name}" produces unknown outcome kind "${p}" — use one of: ${[...KNOWN_OUTCOME_KINDS].join(', ')}`,
+          );
+        }
+      } else if (typeof p !== 'function') {
+        errors.push(`mechanical state "${name}" requires produces (OutcomeKind or fn)`);
+      }
+    }
 
     if (!Array.isArray(state.transitions)) {
       errors.push(`state "${name}" requires a transitions array`);

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(