@ziggs-ai/agent-sdk 0.1.3 → 0.1.5

package/src/agent/Agent.ts

@@ -0,0 +1,101 @@
+import type { Ctx, Identity, Workflow, EffectHandler } from '../types.js';
+import { AgentMachine, type TransitionEvent } from '../runtime/AgentMachine.js';
+import { runTurn } from '../runtime/runTurn.js';
+import { PromptBuilder } from '../runtime/PromptBuilder.js';
+import type { MemoryStore } from '../memory/MemoryStore.js';
+import type { ToolManager } from '../tools/ToolManager.js';
+import type { RawEvent } from '../runtime/buildOutcome.js';
+
+export interface AgentOptions {
+  workflow: Workflow;
+  toolManager: ToolManager;
+  promptBuilder?: PromptBuilder;
+}
+
+export interface TickInput {
+  /** Wire event (already normalized: a `message` or `task_result`-style envelope). */
+  event: unknown;
+  /** Server-provided per-session state. Omit on the first tick — a fresh ctx is constructed. */
+  ctx?: Ctx;
+  /** Server-provided workflow state name. Omit on the first tick — defaults to `workflow.initial`. */
+  state?: string;
+  /** Who am I and what session am I running in. The Agent carries this through Ctx. */
+  identity: Identity;
+  /** The single side channel for I/O — LLM, context, tools, send, record. */
+  eff: EffectHandler;
+  /**
+   * Agent-private long-term memory. Operator-provided (default
+   * `InMemoryStore` when omitted by `AgentHost`). Key shape is the agent's
+   * choice — `counterparty:<id>`, `agreement:<id>:notes`, etc.
+   */
+  memory?: MemoryStore;
+  /** Optional tap for FSM transition events (ZIG-442). */
+  transitionTap?: (event: TransitionEvent) => void;
+}
+
+export interface TickOutput {
+  /** Updated ctx — Server persists this against the session. */
+  ctx: Ctx;
+  /** Workflow state name after the tick — Server persists this against the session. */
+  state: string;
+  /** Whether the machine settled at a parked state. */
+  parked: boolean;
+  /** Accumulated LLM call count and token usage for this tick. */
+  metrics: { llmCalls: number; tokens: { total: number; input: number; output: number } };
+}
+
+/**
+ * Pure agent: workflow definition + cognition machinery. No I/O, no transport,
+ * no services. The Agent's only side channel is the `eff` handler it receives
+ * on each `tick`. Server-side state (sessions, lanes, queue, outbox) lives in
+ * `AgentHost` — not here.
+ *
+ * The contract:
+ *
+ *   `tick({ event, ctx, state, identity, eff })` →
+ *   `{ ctx, state, parked }`
+ *
+ * Reads top-to-bottom like a synchronous function. Every `await eff(...)`
+ * inside the cognition core is a yield to the Server, which performs the
+ * impure operation and resumes the Agent with the result.
+ */
+export class Agent {
+  workflow: Workflow;
+  toolManager: ToolManager;
+  promptBuilder: PromptBuilder;
+
+  constructor({ workflow, toolManager, promptBuilder }: AgentOptions) {
+    if (!workflow?.states) throw new Error('Agent: workflow with states is required');
+    if (!toolManager) throw new Error('Agent: toolManager is required');
+    this.workflow = workflow;
+    this.toolManager = toolManager;
+    this.promptBuilder = promptBuilder || new PromptBuilder();
+  }
+
+  async tick({ event, ctx, state, identity, eff, memory, transitionTap }: TickInput): Promise<TickOutput> {
+    if (!identity?.sessionId) throw new Error('Agent.tick: identity.sessionId is required');
+    if (!eff) throw new Error('Agent.tick: eff is required');
+
+    const machine = new AgentMachine({
+      workflow: this.workflow,
+      executionCore: runTurn,
+      eff,
+      toolManager: this.toolManager,
+      promptBuilder: this.promptBuilder,
+      memory,
+      input: { identity, ctx, state },
+      transitionTap,
+    });
+
+    // `send` awaits the recursive _step until the machine settles at a
+    // parked state (or stops). When it returns, we have the final state.
+    await machine.send({ event: event as RawEvent | undefined, identity });
+
+    return {
+      ctx: machine.ctx,
+      state: machine.state,
+      parked: machine.isParked,
+      metrics: { llmCalls: machine.llmCalls, tokens: machine.tokens },
+    };
+  }
+}

package/src/cognition/validateContext.ts

@@ -0,0 +1,95 @@
+export class ContextWarning {
+  constructor(public path: string, public message: string) {}
+  toString(): string { return `[context] ${this.path}: ${this.message}`; }
+}
+
+type WarnFn = (path: string, msg: string) => void;
+
+export function validateContext(
+  ctx: unknown,
+  { logger }: { logger?: { warn: (msg: string) => void } } = {},
+): ContextWarning[] {
+  const warnings: ContextWarning[] = [];
+  const warn: WarnFn = (path, msg) => warnings.push(new ContextWarning(path, msg));
+
+  if (!ctx || typeof ctx !== 'object') {
+    warn('context', 'missing or not an object');
+    return warnings;
+  }
+
+  const c = ctx as Record<string, unknown>;
+  validateAgreements(c['agreements'], warn);
+  validateAgents(c['agents'], warn);
+  validateHistory(c['history'], warn);
+  validateUsers(c['users'], warn);
+
+  if (logger && warnings.length > 0) {
+    for (const w of warnings) logger.warn(w.toString());
+  }
+  return warnings;
+}
+
+function validateAgreements(agreements: unknown, warn: WarnFn): void {
+  if (!Array.isArray(agreements)) return;
+  for (let i = 0; i < agreements.length; i++) {
+    const ag = agreements[i] as Record<string, unknown>;
+    const path = `agreements[${i}]`;
+    if (!ag || typeof ag !== 'object') { warn(path, 'not an object'); continue; }
+    for (const key of ['agreementId', 'parties']) {
+      if (ag[key] == null) warn(`${path}.${key}`, 'missing');
+    }
+    if (ag['parties'] && typeof ag['parties'] === 'object') {
+      const parties = ag['parties'] as Record<string, unknown>;
+      for (const key of ['creator', 'provider']) {
+        if (!parties[key]) warn(`${path}.parties.${key}`, 'missing');
+      }
+    }
+    if (ag['proposal'] && typeof ag['proposal'] === 'object') {
+      if (!(ag['proposal'] as Record<string, unknown>)['status']) warn(`${path}.proposal.status`, 'missing');
+    }
+    if (ag['task'] && typeof ag['task'] === 'object') {
+      const t = ag['task'] as Record<string, unknown>;
+      if (!t['taskId']) warn(`${path}.task.taskId`, 'missing');
+      if (!t['state']) warn(`${path}.task.state`, 'missing');
+    }
+  }
+}
+
+function validateAgents(agents: unknown, warn: WarnFn): void {
+  if (!Array.isArray(agents)) return;
+  let youCount = 0;
+  for (let i = 0; i < agents.length; i++) {
+    const agent = agents[i] as Record<string, unknown>;
+    const path = `agents[${i}]`;
+    if (!agent || typeof agent !== 'object') { warn(path, 'not an object'); continue; }
+    if (!agent['agentId']) warn(`${path}.agentId`, 'missing');
+    if (agent['isYou']) youCount++;
+  }
+  if (agents.length > 0 && youCount === 0) warn('agents', 'no agent has isYou=true — agent identity will be unknown');
+  if (youCount > 1) warn('agents', `${youCount} agents have isYou=true — should be exactly 1`);
+}
+
+function validateHistory(history: unknown, warn: WarnFn): void {
+  if (!Array.isArray(history)) return;
+  for (let i = 0; i < history.length; i++) {
+    const entry = history[i] as Record<string, unknown>;
+    const path = `history[${i}]`;
+    if (!entry || typeof entry !== 'object') { warn(path, 'not an object'); continue; }
+    if (!entry['entryType'] && entry['entryType'] !== 0) warn(`${path}.entryType`, 'missing');
+    if (entry['entryType'] === 'message' && !entry['sender']) warn(`${path}.sender`, 'missing for message entry');
+    if (entry['entryType'] === 'task_history') {
+      const svc = entry['service'] as Record<string, unknown> | undefined;
+      if (!svc?.['task']) warn(`${path}.service.task`, 'missing for task_history entry');
+    }
+  }
+}
+
+function validateUsers(users: unknown, warn: WarnFn): void {
+  if (!Array.isArray(users)) return;
+  for (let i = 0; i < users.length; i++) {
+    const user = users[i] as Record<string, unknown>;
+    const path = `users[${i}]`;
+    if (!user || typeof user !== 'object') { warn(path, 'not an object'); continue; }
+    if (!user['userId']) warn(`${path}.userId`, 'missing');
+  }
+}

package/src/context/applyEffects.ts

@@ -0,0 +1,80 @@
+import { isProtocolToolName, mapProtocolToolToOperation } from '../tasks/protocolRegistry.js';
+
+function applyTaskOperationResultToContext(updates: Record<string, unknown>, operation: string | null, result: Record<string, unknown>): void {
+  const r = result || {};
+  const agreement = (r['agreement'] as Record<string, unknown>) ||
+    (r['agreementId'] ? r : null);
+  const task = (r['task'] as Record<string, unknown>) || (r['taskId'] ? r : null);
+
+  if (operation === 'agreement-propose' || operation === 'agreement-subcontract') {
+    // Agreement creation no longer spawns a task. The caller has made a
+    // proposal that the proposedTo party still needs to approve.
+    if (agreement) updates['proposal'] = r;
+  }
+  if (operation === 'task-spawn') {
+    if (task) {
+      updates['delegatedTask'] = r;
+      if (task['taskId']) {
+        if (!updates['_delegatedTaskIds']) updates['_delegatedTaskIds'] = [];
+        (updates['_delegatedTaskIds'] as string[]).push(task['taskId'] as string);
+      }
+    }
+  }
+  if (operation === 'task-update') {
+    const status = (task?.['state'] || r['state'] || r['status']) as string | undefined;
+    if (status === 'completed') updates['taskCompleted'] = true;
+    if (status === 'failed') updates['taskFailed'] = true;
+  }
+  if (operation === 'agreement-respond') updates['respondedProposal'] = r;
+}
+
+export const CONTEXT_RESET: Record<string, unknown> = Object.freeze({
+  messageSent: false, activeWait: false, proposal: null, taskCompleted: false,
+  taskFailed: false, subtaskResult: null, subtaskFailed: false, toolResults: null,
+  lastError: null, lastAction: null, lastActionResult: null, approval: false,
+  rejection: false, taskAssignment: null, incomingMessage: false,
+  respondedProposal: null, searchCompleted: false, boardResults: null, taskPublished: false,
+});
+
+export function buildContextUpdates(actionName: string, emittedEvents: unknown[]): Record<string, unknown> {
+  const updates: Record<string, unknown> = { ...CONTEXT_RESET, lastAction: actionName };
+  if (!Array.isArray(emittedEvents)) return updates;
+  const toolResults: unknown[] = [];
+
+  for (const ev of emittedEvents) {
+    if (!ev || typeof ev !== 'object') continue;
+    const events = Array.isArray(ev) ? ev : [ev];
+    for (const e of events) {
+      const event = e as Record<string, unknown>;
+      switch (event['type']) {
+        case 'tool_result':
+          toolResults.push({ tool: event['tool'], result: event['result'] });
+          updates['lastActionResult'] = event;
+          if (isProtocolToolName(event['tool'] as string)) {
+            applyTaskOperationResultToContext(updates, mapProtocolToolToOperation(event['tool'] as string), (event['result'] as Record<string, unknown>) || {});
+          }
+          break;
+        case 'tool_error':
+          toolResults.push({ tool: event['tool'], error: event['error'] });
+          updates['lastActionResult'] = event;
+          updates['lastError'] = event['error'];
+          break;
+        case 'message_sent':
+          updates['messageSent'] = true; updates['lastActionResult'] = event; break;
+        case 'message_duplicate_skipped':
+          updates['messageSent'] = true; break;
+        case 'waited':
+          updates['activeWait'] = true; break;
+        case 'task_result': {
+          updates['lastActionResult'] = event;
+          applyTaskOperationResultToContext(updates, (event['operation'] as string) || null, (event['result'] as Record<string, unknown>) || {});
+          break;
+        }
+        case 'task_error':
+          updates['lastError'] = event['error']; updates['lastActionResult'] = event; break;
+      }
+    }
+  }
+  if (toolResults.length > 0) updates['toolResults'] = toolResults;
+  return updates;
+}

package/src/context/batch.ts

@@ -0,0 +1,17 @@
+export function getBatchEvents(rawEvent: unknown): unknown[] {
+  if (!rawEvent) return [];
+  const e = rawEvent as Record<string, unknown>;
+  if (e['type'] === 'batch' && Array.isArray(e['events'])) return e['events'] as unknown[];
+  return [rawEvent];
+}
+
+export function isTaskResultRelevantToAgent(result: Record<string, unknown>, ownAgentId: string | null): boolean {
+  if (!ownAgentId) return true;
+  const parties = (result['agreement'] as Record<string, unknown> | undefined)?.['parties'] as Record<string, unknown> | undefined ?? {};
+  return !!(
+    result['creatorIsYou'] || result['providerIsYou'] || result['payerIsYou'] || result['proposedToIsYou'] ||
+    parties['creator'] === ownAgentId || parties['provider'] === ownAgentId ||
+    parties['payer'] === ownAgentId || parties['proposedTo'] === ownAgentId ||
+    parties['proposedTo'] === 'everyone'
+  );
+}

package/src/context/classifyEnvelope.ts

@@ -0,0 +1,38 @@
+import { CONTEXT_RESET } from './applyEffects.js';
+import { getBatchEvents, isTaskResultRelevantToAgent } from './batch.js';
+
+function isTaskAssignment(result: Record<string, unknown>, ownAgentId: string | null): boolean {
+  const parties = (result['agreement'] as Record<string, unknown> | undefined)?.['parties'] as Record<string, unknown> | undefined ?? {};
+  const isProvider = result['providerIsYou'] || parties['provider'] === ownAgentId;
+  return !!(isProvider && (result['state'] === 'active' || result['state'] === 'in-progress'));
+}
+
+export function classifyIncomingEvent(rawEvent: unknown, ownAgentId: string | null): Record<string, unknown> {
+  const flags: Record<string, unknown> = { ...CONTEXT_RESET };
+  if (!rawEvent) return flags;
+
+  for (const ev of getBatchEvents(rawEvent)) {
+    if (!ev) continue;
+    const e = ev as Record<string, unknown>;
+    if (e['type'] !== 'task_result') { flags['incomingMessage'] = true; continue; }
+
+    const result = (e['result'] as Record<string, unknown>) || {};
+    if (ownAgentId && !isTaskResultRelevantToAgent(result, ownAgentId) && e['receiverId'] !== ownAgentId) continue;
+
+    const state = result['state'] as string | undefined;
+    const ag = result['agreement'] as Record<string, unknown> | undefined;
+    const parties = (ag?.['parties'] as Record<string, unknown>) || {};
+    const proposalStatus = (ag?.['proposal'] as Record<string, unknown> | undefined)?.['status'];
+
+    if (state === 'active' && proposalStatus === 'approved' && ownAgentId && parties['creator'] === ownAgentId) {
+      flags['approval'] = true; flags['taskAssignment'] = result; continue;
+    }
+    if (isTaskAssignment(result, ownAgentId)) { flags['taskAssignment'] = result; flags['approval'] = true; continue; }
+    if (proposalStatus === 'approved' || (state === 'active' && proposalStatus === 'pending')) { flags['approval'] = true; flags['taskAssignment'] = result; continue; }
+    if (proposalStatus === 'rejected' || state === 'cancelled') { flags['rejection'] = true; continue; }
+    if (state === 'completed') { flags['subtaskResult'] = result; continue; }
+    if (state === 'failed') { flags['subtaskResult'] = result; flags['subtaskFailed'] = true; continue; }
+    flags['subtaskResult'] = result;
+  }
+  return flags;
+}

package/src/context/routingLabels.ts

@@ -0,0 +1,46 @@
+import { isProtocolToolName } from '../tasks/protocolRegistry.js';
+import { getBatchEvents, isTaskResultRelevantToAgent } from './batch.js';
+
+export function unwrapBatchEvent(event: unknown): unknown {
+  const e = event as Record<string, unknown> | null | undefined;
+  if (e?.['type'] === 'batch' && Array.isArray(e['events']) && e['events'][0]) return e['events'][0];
+  return event;
+}
+
+export function classifyWorkflowEvent(event: unknown, ownAgentId: string | null = null): string {
+  const events = getBatchEvents(event);
+  if (events.length === 0) return 'message';
+
+  let sawTaskResult = false, sawOwnTaskResult = false;
+
+  for (const ev of events) {
+    const e = ev as Record<string, unknown> | null | undefined;
+    if (e?.['type'] !== 'task_result') continue;
+    sawTaskResult = true;
+    const result = (e['result'] as Record<string, unknown>) || {};
+    if (!isTaskResultRelevantToAgent(result, ownAgentId)) continue;
+    sawOwnTaskResult = true;
+    const state = result['state'] as string | undefined;
+    const ag = result['agreement'] as Record<string, unknown> | undefined;
+    const parties = (ag?.['parties'] as Record<string, unknown>) || {};
+    const proposalStatus = ag?.['proposal'] ? (ag['proposal'] as Record<string, unknown>)['status'] : undefined;
+    const isProvider = result['providerIsYou'] || parties['provider'] === ownAgentId;
+    if (isProvider && (state === 'active' || state === 'in-progress')) return 'task_assignment';
+    if (proposalStatus === 'approved' || (state === 'active' && proposalStatus === 'pending')) return 'task_approved';
+    if (proposalStatus === 'rejected' || state === 'cancelled') return 'task_rejected';
+  }
+  if (sawOwnTaskResult || sawTaskResult) return 'task_update';
+  return 'message';
+}
+
+export function findTaskResult(output: Record<string, unknown> | null | undefined): unknown {
+  const events = (output?.['emittedEvents'] as unknown[]) ?? [];
+  return events.find(e => {
+    const ev = e as Record<string, unknown>;
+    return ev['type'] === 'task_result' || (ev['type'] === 'tool_result' && isProtocolToolName(ev['tool'] as string));
+  }) ?? null;
+}
+
+export function findIncomingTaskResult(incomingEvent: unknown): unknown {
+  return getBatchEvents(incomingEvent).find(e => (e as Record<string, unknown>)?.['type'] === 'task_result') ?? null;
+}

package/src/defineAgent.ts

@@ -0,0 +1,62 @@
+import type { AgentConfig, DefineAgentInput, Workflow } from './types.js';
+import { validateWorkflow } from './runtime/validateWorkflow.js';
+import { runtimeLog } from './shared/runtimeLog.js';
+
+/**
+ * Validates the workflow synchronously, resolves merged tools and model, and
+ * returns a frozen AgentConfig. Does NOT mutate the input — `wait` action and
+ * `activeWait` transitions are the workflow author's responsibility (visible
+ * spread of `thinkingDefaults`).
+ *
+ * Validation throws WorkflowValidationError on hard problems and logs warnings
+ * on soft ones (e.g. missing wait fallthrough).
+ */
+export function defineAgent(input: DefineAgentInput): AgentConfig {
+  if (!input?.agentId) throw new Error('[defineAgent] agentId is required');
+  if (!input?.description) throw new Error('[defineAgent] description is required');
+  if (!input?.states) throw new Error('[defineAgent] states is required');
+  if (!input?.initial) throw new Error('[defineAgent] initial state is required');
+
+  const workflow: Workflow = {
+    id: input.agentId,
+    description: input.description,
+    initial: input.initial,
+    states: input.states,
+  };
+
+  const { warnings } = validateWorkflow(workflow);
+  for (const w of warnings) runtimeLog.warn('defineAgent', w);
+
+  const tools = [
+    ...(Array.isArray(input.tools) ? input.tools : []),
+    ...(Array.isArray(input.services?.tools) ? input.services!.tools! : []),
+  ];
+
+  const model =
+    input.services?.llm?.model ||
+    process.env.OPENAI_MODEL ||
+    'gpt-5.4';
+
+  // Strip the structural fields we already consumed; pass through everything
+  // else (operatorKey, taskTools, custom keys consumed by AgentHost).
+  const {
+    agentId, description, specialization, services: _services, initial: _initial,
+    states: _states, tools: _tools, operatorKey, taskTools, ...rest
+  } = input;
+
+  const config: AgentConfig = {
+    openaiKey: process.env.OPENAI_API_KEY,
+    ...(operatorKey ? { operatorKey } : {}),
+    agentId,
+    description,
+    ...(specialization ? { specialization } : {}),
+    tools,
+    model,
+    workflow,
+    ...(input.services ? { services: input.services } : {}),
+    ...(taskTools !== undefined ? { taskTools } : {}),
+    ...rest,
+  };
+
+  return Object.freeze(config) as AgentConfig;
+}

package/src/formatters/AgreementFormatter.ts

@@ -0,0 +1,111 @@
+interface AgreementFormatterOptions {
+  shortIds?: boolean;
+  indentSize?: number;
+}
+
+type AnyObj = Record<string, unknown>;
+
+export class AgreementFormatter {
+  private shortIds: boolean;
+  private indentSize: number;
+
+  constructor(options: AgreementFormatterOptions = {}) {
+    this.shortIds = options.shortIds ?? false;
+    this.indentSize = options.indentSize ?? 2;
+  }
+
+  format(agreements: AnyObj[] | null | undefined): string {
+    if (!agreements?.length) return 'No active agreements.';
+    const pending = agreements.filter(a => (a['proposal'] as AnyObj | undefined)?.['status'] === 'pending' && a['proposedToIsYou']);
+    const standing = agreements.filter(a => !a['task']);
+    const active = agreements.filter(a => a['task'] && !((a['proposal'] as AnyObj | undefined)?.['status'] === 'pending' && a['proposedToIsYou']));
+    const sections: string[] = [];
+    if (pending.length > 0) { sections.push('Pending Proposals (awaiting your response):'); for (const ag of pending) sections.push(this.formatAgreement(ag, this._indent(1))); }
+    if (active.length > 0) { if (sections.length > 0) sections.push(''); sections.push('Active Agreements:'); for (const ag of active) sections.push(this.formatAgreement(ag, this._indent(1))); }
+    if (standing.length > 0) { if (sections.length > 0) sections.push(''); sections.push('Standing Agreements (no execution running):'); for (const ag of standing) sections.push(this.formatAgreement(ag, this._indent(1))); }
+    return sections.join('\n');
+  }
+
+  formatAgreement(ag: AnyObj, indent = ''): string {
+    const status = ((ag['status'] as string) || 'unknown').toUpperCase();
+    const agId = this.shortId(ag['agreementId'] as string);
+    const parties = (ag['parties'] as AnyObj) || {};
+    const lines = [
+      `${indent}[${status}] Agreement ${agId}`,
+      `${indent}  Creator: ${this._labelParty(parties['creator'] as string, ag['creatorIsYou'] as boolean)}`,
+      `${indent}  Provider: ${this._labelParty(parties['provider'] as string, ag['providerIsYou'] as boolean)}`,
+      `${indent}  Payer: ${this._labelParty(parties['payer'] as string, ag['payerIsYou'] as boolean)}`,
+    ];
+    if (parties['proposedTo']) lines.push(`${indent}  Proposed to: ${this._labelParty(parties['proposedTo'] as string, ag['proposedToIsYou'] as boolean)}`);
+    const proposal = ag['proposal'] as AnyObj | undefined;
+    if (proposal?.['status']) lines.push(`${indent}  Proposal: ${proposal['status']}${proposal['respondedBy'] ? ` (by ${proposal['respondedBy']})` : ''}`);
+    const money = ag['money'] as AnyObj | undefined;
+    if (typeof money?.['price'] === 'number' && (money['price'] as number) > 0) {
+      const parts = [`${money['price']} cents`];
+      if (money['paymentStatus'] && money['paymentStatus'] !== 'none') parts.push(money['paymentStatus'] as string);
+      lines.push(`${indent}  Money: ${parts.join(', ')}`);
+    }
+    const terms = ag['terms'] as AnyObj | undefined;
+    if (terms) {
+      const tparts: string[] = [];
+      if (terms['lifecycle'] && terms['lifecycle'] !== 'open') tparts.push(`lifecycle: ${terms['lifecycle']}`);
+      if (terms['maxExecutions'] != null) tparts.push(`maxExecutions: ${terms['maxExecutions']}`);
+      if (terms['expiresAt']) tparts.push(`expiresAt: ${terms['expiresAt']}`);
+      if (terms['description']) tparts.push(`"${terms['description']}"`);
+      if (tparts.length > 0) lines.push(`${indent}  Terms: ${tparts.join(', ')}`);
+    }
+    if (ag['task']) { lines.push(''); lines.push(`${indent}  Execution:`); lines.push(this._renderTaskExecution(ag['task'] as AnyObj, indent + '    ')); }
+    else lines.push(`${indent}  Execution: (none yet)`);
+    return lines.join('\n');
+  }
+
+  _renderTaskExecution(task: AnyObj, indent = ''): string {
+    const state = ((task['state'] as string) || 'unknown').toUpperCase();
+    const id = this.shortId(task['taskId'] as string);
+    const lines = [`${indent}[${state}] ${task['description'] || 'No description'}`, `${indent}  Task ID: ${id}`];
+    if (task['parentTaskId']) lines.push(`${indent}  Parent task: ${task['parentTaskId']}`);
+    if (task['result'] && (task['state'] === 'completed' || task['state'] === 'failed')) {
+      const r = String(task['result']);
+      lines.push(`${indent}  Result: ${r.length > 100 ? r.slice(0, 100) + '...' : r}`);
+    }
+    const plan = task['plan'] as AnyObj | undefined;
+    const steps = plan?.['steps'] as AnyObj[] | undefined;
+    if (steps?.length) {
+      const sorted = [...steps].sort((a, b) => (a['order'] as number) - (b['order'] as number));
+      const done = sorted.filter(s => s['status'] === 'completed').length;
+      lines.push(`${indent}  Plan (${done}/${sorted.length} done):`);
+      for (const step of sorted) {
+        const icon = ({ pending: '○', in_progress: '●', completed: '✓', skipped: '–' } as Record<string, string>)[step['status'] as string] || '?';
+        const note = step['status'] === 'completed' && step['result'] ? ` → ${String(step['result']).slice(0, 60)}${String(step['result']).length > 60 ? '...' : ''}` : '';
+        lines.push(`${indent}    ${step['order']}. [${icon}] ${step['description'] || step['stepId']}${note}`);
+      }
+    }
+    const subtasks = task['subtasks'] as AnyObj[] | undefined;
+    if (subtasks?.length) {
+      lines.push(`${indent}  Subtasks (${subtasks.length}):`);
+      for (const st of subtasks) {
+        const sstate = ((st['state'] as string) || 'unknown').toUpperCase();
+        const sid = this.shortId(st['taskId'] as string);
+        lines.push(`${indent}    [${sstate}] ${st['description'] || sid} (${sid}, provider: ${st['providerIsYou'] ? 'You' : (st['provider'] ?? 'unassigned')})`);
+      }
+    }
+    return lines.join('\n');
+  }
+
+  _labelParty(id: string | null | undefined, isYou: boolean | undefined): string {
+    if (!id) return 'N/A';
+    return isYou ? `You (${id})` : id;
+  }
+
+  shortId(id: string | null | undefined): string {
+    if (!id) return '?';
+    if (!this.shortIds) return id;
+    return id.length > 20 ? id.slice(0, 20) + '...' : id;
+  }
+
+  private _indent(level: number): string {
+    return ' '.repeat(level * this.indentSize);
+  }
+}
+
+export const agreementFormatter = new AgreementFormatter();