@ziggs-ai/agent-sdk 0.1.11 → 0.1.12

package/src/agent/hostedAgentConnection.ts

@@ -0,0 +1,41 @@
+/**
+ * Hosted fleet agents connect via api-client (AgentHost), never inbound ziggs-mcp.
+ * @see ZIG-781
+ */
+
+export type McpServerSpec = {
+  type?: string;
+  command?: string;
+  args?: string[];
+};
+
+export function looksLikeInboundZiggsMcp(command: string, args: string[] = []): boolean {
+  const joined = `${command} ${args.join(' ')}`;
+  return /ziggs-mcp|@ziggs-ai\/ziggs-mcp/i.test(joined);
+}
+
+/**
+ * Reject wiring a hosted agent to the inbound Ziggs MCP stdio surface.
+ * Claude SDK agents must use in-process ToolManager tools (createSdkMcpServer).
+ */
+export function assertHostedAgentZiggsTools(
+  mcpServers: Record<string, McpServerSpec | unknown> | undefined,
+): void {
+  if (!mcpServers) return;
+  for (const [name, raw] of Object.entries(mcpServers)) {
+    if (!raw || typeof raw !== 'object') continue;
+    const spec = raw as McpServerSpec;
+    if (spec.type === 'stdio') {
+      throw new Error(
+        `Hosted Ziggs agents must not use stdio MCP (server "${name}"). ` +
+          'Connect via api-client / AgentHost in-process tools.',
+      );
+    }
+    if (looksLikeInboundZiggsMcp(String(spec.command ?? ''), spec.args ?? [])) {
+      throw new Error(
+        `Hosted Ziggs agents must not spawn ziggs-mcp (inbound MCP server "${name}"). ` +
+          'Use AgentHost + in-process tools.',
+      );
+    }
+  }
+}

package/src/agent/toolManagerToSdkMcp.ts

@@ -0,0 +1,136 @@
+import { z } from 'zod';
+import { createSdkMcpServer } from '@anthropic-ai/claude-agent-sdk';
+import type { SdkMcpToolDefinition } from '@anthropic-ai/claude-agent-sdk';
+import type { ToolDefinition } from '../tools/defineTool.js';
+import type { ClaudeSdkToolContext } from './claudeSdkTools.js';
+
+type JsonSchema = Record<string, unknown>;
+
+type CallToolResult = {
+  content: Array<{ type: 'text'; text: string }>;
+  isError?: boolean;
+};
+
+function jsonTypeToZod(field: JsonSchema): z.ZodTypeAny {
+  const t = field['type'];
+  if (t === 'string') {
+    let s: z.ZodTypeAny = z.string();
+    if (Array.isArray(field['enum'])) {
+      const vals = field['enum'] as string[];
+      if (vals.length > 0) s = z.enum(vals as [string, ...string[]]);
+    }
+    if (typeof field['description'] === 'string') s = s.describe(field['description']);
+    return s;
+  }
+  if (t === 'number' || t === 'integer') {
+    let n: z.ZodTypeAny = z.number();
+    if (typeof field['description'] === 'string') n = n.describe(field['description']);
+    return n;
+  }
+  if (t === 'boolean') return z.boolean();
+  if (t === 'array') {
+    const items = (field['items'] as JsonSchema | undefined) ?? { type: 'string' };
+    return z.array(jsonTypeToZod(items));
+  }
+  if (t === 'object') {
+    const props = (field['properties'] as Record<string, JsonSchema> | undefined) ?? {};
+    const required = new Set((field['required'] as string[] | undefined) ?? []);
+    const shape: Record<string, z.ZodTypeAny> = {};
+    for (const [key, val] of Object.entries(props)) {
+      let node = jsonTypeToZod(val);
+      if (!required.has(key)) node = node.optional();
+      shape[key] = node;
+    }
+    return z.object(shape).passthrough();
+  }
+  return z.unknown();
+}
+
+function parametersToZodShape(parameters: JsonSchema | undefined): z.ZodRawShape {
+  if (!parameters || parameters['type'] !== 'object') return {};
+  const props = (parameters['properties'] as Record<string, JsonSchema> | undefined) ?? {};
+  const required = new Set((parameters['required'] as string[] | undefined) ?? []);
+  const shape: Record<string, z.ZodTypeAny> = {};
+  for (const [key, val] of Object.entries(props)) {
+    let node = jsonTypeToZod(val);
+    if (!required.has(key)) node = node.optional();
+    shape[key] = node;
+  }
+  return shape;
+}
+
+function toCallToolResult(value: unknown): CallToolResult {
+  const text = typeof value === 'string' ? value : JSON.stringify(value, null, 2);
+  return { content: [{ type: 'text', text }] };
+}
+
+function toCallToolError(err: unknown): CallToolResult {
+  const message = err instanceof Error ? err.message : String(err);
+  return { content: [{ type: 'text', text: message }], isError: true };
+}
+
+/**
+ * Map Ziggs `ToolDefinition`s to Claude Agent SDK MCP tools. Each handler routes
+ * execution through `eff({ kind: 'tool-call' })` — the shared executor (ZIG-775).
+ */
+export function buildSdkToolDefs(
+  toolDefs: ToolDefinition[],
+  getContext: () => ClaudeSdkToolContext,
+): Array<SdkMcpToolDefinition> {
+  return toolDefs.map((def) => {
+    const fn = def.schema.function;
+    const name = String(fn['name'] ?? '');
+    const description = String(fn['description'] ?? name);
+    const shape = parametersToZodShape(fn['parameters'] as JsonSchema | undefined);
+    const inputSchema = Object.keys(shape).length > 0
+      ? shape
+      : { _: z.record(z.string(), z.unknown()).optional() };
+
+    return {
+      name,
+      description,
+      inputSchema,
+      _meta: { 'anthropic/alwaysLoad': true },
+      handler: async (args: Record<string, unknown>) => {
+        try {
+          const ctx = getContext();
+          const payload = args._ != null && Object.keys(args).length === 1
+            ? (args._ as Record<string, unknown>)
+            : args;
+          const eff = ctx.eff;
+          if (!eff) return toCallToolError(`tool "${name}": missing eff in tool context`);
+          const sessionId = ctx.chatId ?? ctx.sessionId;
+          if (!sessionId) return toCallToolError(`tool "${name}": missing sessionId in tool context`);
+          const r = await eff({
+            kind: 'tool-call',
+            sessionId,
+            name,
+            args: payload ?? {},
+            senderId: ctx.senderId,
+            senderType: ctx.senderType,
+            onBehalfOfAgreementId: ctx.onBehalfOfAgreementId as string | undefined,
+            runId: ctx.runId,
+          });
+          if (r.ok) return toCallToolResult(r.result);
+          return toCallToolError(r.error ?? `tool "${name}" failed`);
+        } catch (err) {
+          return toCallToolError(err);
+        }
+      },
+    };
+  });
+}
+
+export function buildZiggsSdkMcpServer(
+  toolDefs: ToolDefinition[],
+  getContext: () => ClaudeSdkToolContext,
+  options: { name?: string; instructions?: string } = {},
+) {
+  return createSdkMcpServer({
+    name: options.name ?? 'ziggs',
+    version: '1.0.0',
+    instructions: options.instructions,
+    tools: buildSdkToolDefs(toolDefs, getContext),
+    alwaysLoad: true,
+  });
+}

package/src/defineAgent.ts

@@ -1,7 +1,9 @@
 import type { AgentConfig, DefineAgentInput, Workflow } from './types.js';
 import { validateWorkflow } from './runtime/validateWorkflow.js';
 import { injectKickoffDefault } from './runtime/kickoff.js';
+import { deriveRespondsToProposals } from './runtime/deriveRespondsToProposals.js';
 import { runtimeLog } from './shared/runtimeLog.js';
+import { DEFAULT_MODEL } from './AgentHost.js';
 
 /**
  * Validates the workflow synchronously, resolves merged tools and model, and
@@ -38,11 +40,14 @@ export function defineAgent(input: DefineAgentInput): AgentConfig {
     ...(Array.isArray(input.services?.tools) ? input.services!.tools! : []),
   ];
 
+  // Model resolution, most-specific-first: a per-agent pin, then the
+  // fleet-wide `LLM_MODEL` lever, then the single `DEFAULT_MODEL` fallback (the
+  // ONE place the default lives — see AgentHost). The id also picks the provider
+  // (claude-* → Anthropic). No agent hardcodes its own fallback.
   const model =
     input.services?.llm?.model ||
     process.env.LLM_MODEL ||
-    process.env.OPENAI_MODEL ||
-    'gpt-5.4';
+    DEFAULT_MODEL;
 
   // Strip the structural fields we already consumed; pass through everything
   // else (operatorKey, taskTools, custom keys consumed by AgentHost).
@@ -61,6 +66,8 @@ export function defineAgent(input: DefineAgentInput): AgentConfig {
     tools,
     model,
     workflow,
+    respondsToProposals:
+      input.respondsToProposals ?? deriveRespondsToProposals(workflow),
     ...(input.services ? { services: input.services } : {}),
     ...(taskTools !== undefined ? { taskTools } : {}),
     ...rest,

package/src/index.ts

@@ -3,7 +3,7 @@
  *
  * Foundation:
  *   • Outcome union — discriminated, hybrid (closed core + extension)
- *   • Workflow shape — explicit kind: 'parked' | 'thinking'
+ *   • Workflow shape — explicit kind: 'parked' | 'thinking' | 'mechanical'
  *   • Visible defaults — thinkingDefaults({ initial }) spread by author
  *   • Validation at load — defineAgent throws on hard problems, warns on soft
  */
@@ -11,8 +11,10 @@
 export { defineAgent } from './defineAgent.js';
 export { createMcpAgent, resolveZiggsGatewayTarget, wrapGatewayFetch, ZiggsGatewayError } from './adapters/McpAdapter.js';
 export type { CreateMcpAgentOptions, McpAgentHandle, McpTransportConfig } from './adapters/McpAdapter.js';
-export { AgentHost, createAgent, createAgentPool } from './AgentHost.js';
+export { AgentHost, createAgent, createAgentPool, DEFAULT_MODEL } from './AgentHost.js';
 export { Agent } from './agent/Agent.js';
+export { ClaudeSdkAgent } from './agent/ClaudeSdkAgent.js';
+export type { CognitionKind } from './agent/ClaudeSdkAgent.js';
 export type { TickInput, TickOutput, AgentOptions } from './agent/Agent.js';
 export type { SessionResolver, AgentHostOptions } from './AgentHost.js';
 export { createZiggsEffectHandler } from './server/ZiggsEffectHandler.js';
@@ -26,17 +28,22 @@ export { normalizeIncomingEvent } from './ingress/normalizeIncoming.js';
 // Runtime primitives
 export { AgentMachine, type TransitionEvent } from './runtime/AgentMachine.js';
 export { runTurn } from './runtime/runTurn.js';
+export { runMechanical } from './runtime/runMechanical.js';
 export { PromptBuilder } from './runtime/PromptBuilder.js';
-export { thinkingDefaults, defineThinkingState, DEFAULT_WAIT_PROMPT } from './runtime/defaults.js';
+export { thinkingDefaults, defineThinkingState, defineMechanicalState, DEFAULT_WAIT_PROMPT } from './runtime/defaults.js';
 export { KICKOFF_STATE, injectKickoffDefault, buildKickoffState } from './runtime/kickoff.js';
 export { validateWorkflow, WorkflowValidationError } from './runtime/validateWorkflow.js';
+export {
+  deriveRespondsToProposals,
+  statesRespondToProposals,
+} from './runtime/deriveRespondsToProposals.js';
 export { outcomeFromEvent, outcomeFromActionResult, applyOutcomeToCtx } from './runtime/buildOutcome.js';
 
 // Types
 export type {
   Outcome, OutcomeKind,
   Ctx, Identity, HistoryEntry, ToolResultEntry,
-  Workflow, State, ParkedState, ThinkingState,
+  Workflow, State, ParkedState, ThinkingState, MechanicalState,
   Action, Transition, PromptDef, ActionPrompt, Produces, ProducesFn,
   AgreementRef, TaskRef, ProposalRef,
   AgentConfig, DefineAgentInput, ServicesConfig,
@@ -99,7 +106,6 @@ export {
   WebSocketClient,
   MessagesClient,
   ArtifactsClient,
-  ScopeClient,
   AgentSearchClient,
   getBackendUrl,
   getWebSocketUrl,

package/src/runtime/AgentMachine.ts

@@ -2,7 +2,9 @@ import type { Ctx, Outcome, Workflow, Identity, EffectHandler } from '../types.j
 import { runtimeLog } from '../shared/runtimeLog.js';
 import { applyOutcomeToCtx, outcomeFromEvent, type RawEvent } from './buildOutcome.js';
 import type { runTurn as RunTurnFn } from './runTurn.js';
+import { runMechanical } from './runMechanical.js';
 import { PromptBuilder } from './PromptBuilder.js';
+import { bootstrapCtx } from './bootstrapCtx.js';
 import type { MemoryStore } from '../memory/MemoryStore.js';
 import type { ToolManager } from '../tools/ToolManager.js';
 
@@ -16,9 +18,20 @@ export type TransitionEvent =
   | { kind: 'transition'; fromState: string; toState: string; outcomeKind: string; depth: number }
   | { kind: 'no-match'; state: string; outcomeKind: string; depth: number }
   | { kind: 'depth-guard'; state: string; depth: number }
+  | { kind: 'turn-budget-guard'; state: string; turns: number }
   | { kind: 'error-escape'; fromState: string; toState: string }
   | { kind: 'timeout-unhandled'; state: string; waitedMs: number };
 
+/**
+ * Max thinking turns a session may run without any human (USER) input before it
+ * is treated as a runaway loop and parked (ZIG-768). The depth-guard only bounds
+ * re-entries within a single event chain; this bounds turns ACROSS events, which
+ * is how a supervising session ran 436 turns in a day. The counter resets on
+ * every USER frame, so human-driven conversations are never affected — only
+ * autonomous agent↔agent loops accumulate toward it.
+ */
+const DEFAULT_MAX_TURNS_WITHOUT_USER_INPUT = 100;
+
 interface MachineInput {
   identity: Identity;
   /** Server-provided ctx for an existing session. If omitted, a fresh ctx is built. */
@@ -40,6 +53,8 @@ interface MachineOptions {
   input: MachineInput;
   /** Optional tap for FSM transition events — called synchronously on each transition. */
   transitionTap?: (event: TransitionEvent) => void;
+  /** Runaway-loop backstop: max thinking turns without human input before parking. Default 100. */
+  maxTurnsWithoutUserInput?: number;
 }
 
 interface IncomingFrame {
@@ -81,12 +96,15 @@ export class AgentMachine {
   _lastUserSenderId: string | null = null;
   _stateTimeoutUnhandled = false;
   _transitionTap: ((event: TransitionEvent) => void) | undefined;
+  /** Thinking turns run since the last human (USER) frame. Reset on USER input. */
+  _turnsSinceUserInput = 0;
+  _maxTurnsWithoutUserInput: number;
 
   get llmCalls(): number { return this._llmCalls; }
   get tokens(): { total: number; input: number; output: number } { return this._tokens; }
   get stateTimeoutUnhandled(): boolean { return this._stateTimeoutUnhandled; }
 
-  constructor({ workflow, executionCore, eff, toolManager, promptBuilder, memory, input, transitionTap }: MachineOptions) {
+  constructor({ workflow, executionCore, eff, toolManager, promptBuilder, memory, input, transitionTap, maxTurnsWithoutUserInput }: MachineOptions) {
     this.workflow = workflow;
     this.executionCore = executionCore;
     this.eff = eff;
@@ -94,28 +112,9 @@ export class AgentMachine {
     this.promptBuilder = promptBuilder;
     this.memory = memory;
     this._transitionTap = transitionTap;
+    this._maxTurnsWithoutUserInput = maxTurnsWithoutUserInput ?? DEFAULT_MAX_TURNS_WITHOUT_USER_INPUT;
     this.state = input.state || workflow.initial;
-    this.ctx = input.ctx
-      ? {
-          ...input.ctx,
-          identity: input.identity,
-          // Sessions persisted before pendingSubtasks/collectedResults existed
-          // (DynamoDB rows live up to SESSION_TTL_SECONDS = 24h) restore without
-          // these fields. Default them ONCE here — nowhere else.
-          pendingSubtasks: input.ctx.pendingSubtasks ?? {},
-          collectedResults: input.ctx.collectedResults ?? [],
-        }
-      : {
-          identity: input.identity,
-          activeAgreementId: null,
-          activeTaskId: null,
-          pendingProposalAgreementId: null,
-          delegatedAgreementIds: [],
-          pendingSubtasks: {},
-          collectedResults: [],
-          toolResults: [],
-          lastOutcome: { kind: 'enter' },
-        };
+    this.ctx = bootstrapCtx(input.identity, input.ctx);
   }
 
   getSnapshot(): MachineSnapshot {
@@ -168,6 +167,8 @@ export class AgentMachine {
     this._lastIncomingEvent = ev ?? null;
     if (ev?.senderId && String(ev?.senderType ?? '').toUpperCase() === 'USER') {
       this._lastUserSenderId = String(ev.senderId);
+      // Human input is real progress — reset the runaway-loop budget (ZIG-768).
+      this._turnsSinceUserInput = 0;
     }
     runtimeLog.debug(
       'FSM',
@@ -243,6 +244,70 @@ export class AgentMachine {
       return;
     }
 
+    if (sd.kind === 'mechanical') {
+      if (depth >= 12) {
+        runtimeLog.warn(
+          'AgentMachine',
+          `state=${this.state} runaway mechanical loop (depth=${depth}); parking`,
+        );
+        this._transitionTap?.({ kind: 'depth-guard', state: this.state, depth });
+        await this._sendFallbackIfUserWaiting('Something went wrong. Please try again.');
+        this._notify();
+        return;
+      }
+      if (this._turnsSinceUserInput >= this._maxTurnsWithoutUserInput) {
+        runtimeLog.warn(
+          'AgentMachine',
+          `state=${this.state} runaway loop: ${this._turnsSinceUserInput} turns without user input (cap ${this._maxTurnsWithoutUserInput}); parking`,
+        );
+        this._transitionTap?.({ kind: 'turn-budget-guard', state: this.state, turns: this._turnsSinceUserInput });
+        await this._sendFallbackIfUserWaiting('I got stuck in a loop and paused. Please send another message to continue.');
+        this._notify();
+        return;
+      }
+      runtimeLog.debug('FSM', `_step mechanical state=${this.state} — run tool`);
+      this._running = true;
+      try {
+        const { outcome: turnOutcome, toolResults, llmCalls, tokens } = await runMechanical({
+          stateId: this.state,
+          state: sd,
+          ctx: this.ctx,
+          eff: this.eff,
+          memory: this.memory,
+          incomingEvent: this._lastIncomingEvent,
+        });
+        this.ctx.toolResults = toolResults;
+        this._llmCalls += llmCalls;
+        this._turnsSinceUserInput += 1;
+        this._tokens.total += tokens.total;
+        this._tokens.input += tokens.input;
+        this._tokens.output += tokens.output;
+        applyOutcomeToCtx(this.ctx, turnOutcome);
+        this._running = false;
+        this._notify();
+        await this._step(turnOutcome, depth + 1);
+      } catch (error: unknown) {
+        runtimeLog.error('AgentMachine', `mechanical state=${this.state} error: ${(error as Error)?.message || error}`);
+        const errOutcome: Outcome = {
+          kind: 'error',
+          source: 'unknown',
+          cause: (error as Error)?.message || String(error),
+          retryable: false,
+        };
+        applyOutcomeToCtx(this.ctx, errOutcome);
+        this._running = false;
+        this._notify();
+        const fallback = this._evaluateTransitions(errOutcome);
+        if (fallback && fallback !== this.state) {
+          this.state = fallback;
+          this._notify();
+        } else {
+          await this._sendFallbackIfUserWaiting('Something went wrong. Please try again.');
+        }
+      }
+      return;
+    }
+
     // A thinking turn that yields an outcome no transition handles must not
     // silently re-enter the same state and burn another LLM call (ZIG-303).
     // Explicit self-loops still match (target is non-null, even if target === state).
@@ -282,6 +347,22 @@ export class AgentMachine {
       this._notify();
       return;
     }
+    // Cross-event runaway guard (ZIG-768). The depth-guard above only bounds
+    // one event chain; a supervising session that keeps waking on agent/system
+    // messages re-enters at depth 0 each time and never trips it. Bound the
+    // total thinking turns since the last human input instead — a runaway
+    // agent↔agent loop climbs toward the cap while a human conversation resets
+    // it on every user message.
+    if (this._turnsSinceUserInput >= this._maxTurnsWithoutUserInput) {
+      runtimeLog.warn(
+        'AgentMachine',
+        `state=${this.state} runaway loop: ${this._turnsSinceUserInput} turns without user input (cap ${this._maxTurnsWithoutUserInput}); parking`,
+      );
+      this._transitionTap?.({ kind: 'turn-budget-guard', state: this.state, turns: this._turnsSinceUserInput });
+      await this._sendFallbackIfUserWaiting('I got stuck in a loop and paused. Please send another message to continue.');
+      this._notify();
+      return;
+    }
     runtimeLog.debug('FSM', `_step thinking state=${this.state} — run turn`);
 
     // Thinking: run a turn, produce an outcome, re-step.
@@ -302,6 +383,7 @@ export class AgentMachine {
 
       this.ctx.toolResults = toolResults;
       this._llmCalls += llmCalls;
+      this._turnsSinceUserInput += 1;
       this._tokens.total += tokens.total;
       this._tokens.input += tokens.input;
       this._tokens.output += tokens.output;

package/src/runtime/PromptBuilder.ts

@@ -46,11 +46,21 @@ export interface PromptBuilderOptions {
   description?: string;
   specialization?: string | null;
   maxHistoryEntries?: number;
+  /**
+   * Token budget for the <history> block. History is included newest-first up
+   * to this many (estimated) tokens, so a few large turns can't blow the prompt
+   * up to tens of thousands of input tokens (ZIG-769). maxHistoryEntries still
+   * applies as a secondary hard ceiling.
+   */
+  maxHistoryTokens?: number;
   historyFormatter?: HistoryFormatterI;
   agreementFormatter?: AgreementFormatterI;
   logger?: LoggerI | null | { warn: (msg: string) => void };
 }
 
+/** Rough chars-per-token ratio for budgeting (English/JSON averages ~4). */
+const CHARS_PER_TOKEN = 4;
+
 /**
  * Builds the XML prompt for a thinking-state turn:
  *   <agent><self/><world/><decision_schema/></agent>
@@ -63,6 +73,7 @@ export class PromptBuilder {
   description: string;
   specialization: string | null;
   maxHistoryEntries: number;
+  maxHistoryTokens: number;
   historyFormatter: HistoryFormatterI;
   agreementFormatter: AgreementFormatterI;
   logger: LoggerI | null;
@@ -71,11 +82,17 @@ export class PromptBuilder {
     this.description = options.description || 'A capable agent ready to assist';
     this.specialization = options.specialization ?? null;
     this.maxHistoryEntries = options.maxHistoryEntries ?? 50;
+    this.maxHistoryTokens = options.maxHistoryTokens ?? 8000;
     this.historyFormatter = options.historyFormatter || new HistoryFormatter();
     this.agreementFormatter = (options.agreementFormatter || new AgreementFormatter()) as AgreementFormatterI;
     this.logger = options.logger as LoggerI | null || null;
   }
 
+  // Section order is deliberate and cache-stable (ZIG-769): <self> (identity,
+  // state, tools) is stable per agent+state and comes first, so OpenAI automatic
+  // prompt caching can reuse it as a prefix across a conversation's turns. All
+  // volatile content (the incoming event, history, and currentTime) lives later
+  // in <world>, so it never invalidates that cacheable prefix.
   buildFromState(args: BuildArgs): string {
     const { statePrompt, actions, serverContext, incomingEvent, definition, stateId, ctx, omitMessageFromRespond } = args;
     const ctxObj = serverContext?.context || {};
@@ -270,16 +287,36 @@ ${this._renderDecisionSchemaFromActions(actions, senderMeta, ctxObj, omitMessage
   }
 
   _renderHistory(history: AnyObj[] | undefined, agentId: string | null): string {
-    let entries = history || [];
-    let truncNote = '';
-    if (entries.length > this.maxHistoryEntries) {
-      truncNote = `[Showing last ${this.maxHistoryEntries} of ${entries.length} entries]\n\n`;
-      entries = entries.slice(-this.maxHistoryEntries);
+    const all = history || [];
+    const charBudget = this.maxHistoryTokens * CHARS_PER_TOKEN;
+
+    // Include entries newest-first, bounded by BOTH a token budget and the
+    // entry-count ceiling. The newest entry is always kept even if it alone
+    // exceeds the budget, so the most recent turn is never dropped.
+    let startIdx = all.length;
+    let usedChars = 0;
+    for (let i = all.length - 1; i >= 0; i--) {
+      if (all.length - i > this.maxHistoryEntries) break;
+      const size = this._estimateEntryChars(all[i]);
+      if (startIdx < all.length && usedChars + size > charBudget) break;
+      usedChars += size;
+      startIdx = i;
     }
+
+    const entries = all.slice(startIdx);
+    const dropped = all.length - entries.length;
+    const truncNote = dropped > 0
+      ? `[Showing last ${entries.length} of ${all.length} entries — older turns dropped to fit the context budget]\n\n`
+      : '';
     const formatted = this.historyFormatter.format(entries, agentId ?? '', {});
     return `<history>\n${truncNote}${formatted}\n</history>`;
   }
 
+  /** Rough character size of one history entry, used for the token budget. */
+  _estimateEntryChars(entry: AnyObj): number {
+    try { return JSON.stringify(entry)?.length ?? 0; } catch { return 0; }
+  }
+
   _renderAgreements(agreements: AnyObj[]): string {
     const formatted = this.agreementFormatter.format(agreements || []);
     return `<agreements>\n${formatted}\n</agreements>`;

package/src/runtime/bootstrapCtx.ts

@@ -0,0 +1,39 @@
+import type { Ctx, Identity } from '../types.js';
+
+/**
+ * The one place a per-lane `Ctx` is constructed.
+ *
+ * Both cognitions bootstrap the same Ctx: the FSM (`AgentMachine` constructor)
+ * and the Claude Agent SDK brain (`ClaudeSdkAgent.tick`). Before this, each
+ * carried its own copy of the fresh-Ctx literal and the restore-path defaulting,
+ * and they had already drifted (the "default them ONCE here" comment in
+ * AgentMachine no longer held). Keep it here so the shape lives in a single spot.
+ *
+ * - No `existing` → a fresh Ctx for a brand-new session.
+ * - `existing` present → restore it, re-stamping `identity` and defaulting the
+ *   fields that sessions persisted before they existed may lack. Sessions live
+ *   up to SESSION_TTL_SECONDS (24h) in DynamoDB, so an old row can come back
+ *   without `pendingSubtasks` / `collectedResults`; default them here, nowhere
+ *   else.
+ */
+export function bootstrapCtx(identity: Identity, existing?: Ctx | null): Ctx {
+  if (existing) {
+    return {
+      ...existing,
+      identity,
+      pendingSubtasks: existing.pendingSubtasks ?? {},
+      collectedResults: existing.collectedResults ?? [],
+    };
+  }
+  return {
+    identity,
+    activeAgreementId: null,
+    activeTaskId: null,
+    pendingProposalAgreementId: null,
+    delegatedAgreementIds: [],
+    pendingSubtasks: {},
+    collectedResults: [],
+    toolResults: [],
+    lastOutcome: { kind: 'enter' },
+  };
+}

package/src/runtime/defaults.ts

@@ -1,4 +1,4 @@
-import type { Action, Transition, ThinkingState } from '../types.js';
+import type { Action, Ctx, MechanicalState, Outcome, Produces, Transition, ThinkingState } from '../types.js';
 
 /**
  * Defaults that workflow authors spread into thinking states explicitly.
@@ -73,3 +73,14 @@ export function defineThinkingState(
     transitions: [...state.transitions, ...dflt.transitions],
   };
 }
+
+/** ZIG-764: mechanical state — one tool call, zero LLM turns. */
+export function defineMechanicalState(state: {
+  tool: string;
+  args?: Record<string, unknown>;
+  buildArgs?: (ctx: Ctx, outcome: Outcome) => Record<string, unknown>;
+  produces: Produces;
+  transitions: Transition[];
+}): MechanicalState {
+  return { kind: 'mechanical', ...state };
+}

package/src/runtime/deriveRespondsToProposals.ts

@@ -0,0 +1,35 @@
+import type { State, ThinkingState, Workflow } from '../types.js';
+
+/**
+ * ZIG-826: true when the workflow exposes `agreement_respond` on a thinking
+ * action — the agent can approve/reject inbound proposals directed at it.
+ * Kickoff-only states (proposer-side approval → task_spawn) do not count.
+ */
+export function deriveRespondsToProposals(workflow: Workflow): boolean {
+  if (!workflow?.states) return false;
+  for (const state of Object.values(workflow.states)) {
+    if (state.kind !== 'thinking') continue;
+    const actions = (state as ThinkingState).actions;
+    if (!actions) continue;
+    for (const action of Object.values(actions)) {
+      if (action?.tool === 'agreement_respond') return true;
+    }
+  }
+  return false;
+}
+
+/** Scan custom states (pre-defineAgent) for agreement_respond actions. */
+export function statesRespondToProposals(
+  states: Record<string, State> | undefined,
+): boolean {
+  if (!states) return false;
+  for (const state of Object.values(states)) {
+    if (state.kind !== 'thinking') continue;
+    const actions = (state as ThinkingState).actions;
+    if (!actions) continue;
+    for (const action of Object.values(actions)) {
+      if (action?.tool === 'agreement_respond') return true;
+    }
+  }
+  return false;
+}