@ziggs-ai/agent-sdk 0.1.3 → 0.1.4

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 ['creatorId', 'providerId']) {
+        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['creatorId'] === ownAgentId || parties['providerId'] === ownAgentId ||
+    parties['payerId'] === ownAgentId || parties['proposedToId'] === ownAgentId ||
+    parties['proposedToId'] === '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['providerId'] === 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['creatorId'] === 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['providerId'] === 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['creatorId'] as string, ag['creatorIsYou'] as boolean)}`,
+      `${indent}  Provider: ${this._labelParty(parties['providerId'] as string, ag['providerIsYou'] as boolean)}`,
+      `${indent}  Payer: ${this._labelParty(parties['payerId'] as string, ag['payerIsYou'] as boolean)}`,
+    ];
+    if (parties['proposedToId']) lines.push(`${indent}  Proposed to: ${this._labelParty(parties['proposedToId'] 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['providerId'] ?? '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();

package/src/formatters/HistoryFormatter.ts

@@ -0,0 +1,166 @@
+type AnyObj = Record<string, unknown>;
+
+interface HistoryFormatterOptions {
+  showTimestamps?: boolean;
+  shortIds?: boolean;
+}
+
+export class HistoryFormatter {
+  private showTimestamps: boolean;
+  private shortIds: boolean;
+
+  constructor(options: HistoryFormatterOptions = {}) {
+    this.showTimestamps = options.showTimestamps ?? true;
+    this.shortIds = options.shortIds ?? false;
+  }
+
+  format(history: AnyObj[] | null | undefined, agentId: string, options: { mode?: string } = {}): string {
+    if (!history?.length) return 'No previous activity.';
+    const labelTypes = options.mode === 'mission';
+    const sorted = [...history].sort((a, b) => {
+      const tA = a['timestamp'] ? new Date(a['timestamp'] as string).getTime() : 0;
+      const tB = b['timestamp'] ? new Date(b['timestamp'] as string).getTime() : 0;
+      return tA - tB;
+    });
+    return sorted.map(entry => this.formatEntry(entry, agentId, labelTypes)).join('\n');
+  }
+
+  formatEntry(entry: AnyObj, agentId: string, labelTypes = false): string {
+    const timestamp = this.showTimestamps ? this.formatTime(entry['timestamp'] as string | undefined) : '';
+    const timePrefix = timestamp ? `[${timestamp}] ` : '';
+    const entryType = entry['entryType'] as string | undefined;
+
+    if (entryType === 'message' || !entryType) {
+      const label = labelTypes ? '[CHAT] ' : '';
+      return `${label}${this.formatMessage(entry, agentId, timePrefix)}`;
+    }
+    if (entryType === 'task_history') {
+      const label = labelTypes ? '[TASK] ' : '';
+      return `${label}${this.formatTaskHistory(entry, agentId, timePrefix)}`;
+    }
+    if (entryType === 'artifact') {
+      const line = this.formatArtifact(entry, agentId, timePrefix);
+      if (labelTypes) {
+        if (entry['content_type'] === 'thought') return `[THOUGHT] ${line}`;
+        const text = (entry['text'] as string) || '';
+        const json = text.replace(/^operation_(?:started|completed|error):/, '');
+        const data = json ? this.safeParseJSON(json) : null;
+        const label = (data?.['type'] === 'tool' || text.includes('operation_error')) ? '[TOOL] ' : '[TASK] ';
+        return `${label}${line}`;
+      }
+      return line;
+    }
+    return `${timePrefix}${entry['text'] || 'Unknown entry'}`;
+  }
+
+  formatMessage(entry: AnyObj, agentId: string, timePrefix: string): string {
+    const from = this.formatParticipant(entry['sender'] as AnyObj | undefined, agentId);
+    const to = entry['receiver'] ? ` → ${this.formatParticipant(entry['receiver'] as AnyObj, agentId)}` : '';
+    return `${timePrefix}${from}${to}: ${entry['text'] || ''}`;
+  }
+
+  formatTaskHistory(entry: AnyObj, agentId: string, timePrefix: string): string {
+    const service = entry['service'] as AnyObj | undefined;
+    const task = service?.['task'] as AnyObj | undefined;
+    if (!task) return `${timePrefix}Update`;
+    const changeType = service?.['changeType'] as string | undefined;
+    const taskId = this.shortId(task['taskId'] as string);
+    const agreementId = task['agreementId'] ? this.shortId(task['agreementId'] as string) : null;
+    const desc = (task['description'] as string) || 'No description';
+    const ids = agreementId ? `agreement=${agreementId} task=${taskId}` : `task=${taskId}`;
+    switch (changeType) {
+      case 'created': {
+        const ag = task['agreement'] as AnyObj | undefined;
+        const parties = (ag?.['parties'] as AnyObj) || {};
+        return `${timePrefix}Task created under agreement: "${desc}" (${ids})\n    Owner: ${this.formatOwner(task, agentId)}\n    Executor: ${this.formatExecutor(task, agentId)}\n    Proposed to: ${parties['proposedToId'] || 'N/A'}`;
+      }
+      case 'state_changed': {
+        const prev = (service?.['previousState'] as AnyObj | undefined)?.['state'] || '?';
+        const next = (service?.['newState'] as AnyObj | undefined)?.['state'] || '?';
+        return `${timePrefix}Task "${desc}" (${ids}): ${prev} → ${next}`;
+      }
+      case 'proposal_responded': {
+        const action = (service?.['metadata'] as AnyObj | undefined)?.['action'] as string | undefined;
+        return `${timePrefix}Proposal ${action ?? 'responded'} for "${desc}" (${ids})`;
+      }
+      case 'processing_changed': {
+        const processing = (service?.['newState'] as AnyObj | undefined)?.['processing'];
+        return `${timePrefix}Task "${desc}" (${ids}): processing ${processing ? 'started' : 'stopped'}`;
+      }
+      default:
+        return `${timePrefix}${changeType}: "${desc}" (${ids})`;
+    }
+  }
+
+  formatArtifact(entry: AnyObj, _agentId: string, timePrefix: string): string {
+    const text = (entry['text'] as string) || '';
+    if (entry['content_type'] === 'thought') return `${timePrefix}Thought: ${text}`;
+    if (text.startsWith('operation_started:')) {
+      const data = this.safeParseJSON(text.replace('operation_started:', ''));
+      if (data?.['type'] === 'tool') return `${timePrefix}Tool starting: ${data['tool']}(${this.formatArgs(data['args'] as AnyObj)})`;
+      if (data?.['type'] === 'task') return `${timePrefix}Task operation: ${data['operation']}`;
+      return `${timePrefix}Operation started: ${data?.['type'] || 'unknown'}`;
+    }
+    if (text.startsWith('operation_completed:')) {
+      const data = this.safeParseJSON(text.replace('operation_completed:', ''));
+      if (data?.['type'] === 'tool') return `${timePrefix}Tool completed: ${data['tool']}`;
+      if (data?.['type'] === 'task') return `${timePrefix}Task operation completed: ${data['operation']}`;
+      return `${timePrefix}Operation completed: ${data?.['type'] || 'unknown'}`;
+    }
+    if (text.startsWith('operation_error:')) {
+      const data = this.safeParseJSON(text.replace('operation_error:', ''));
+      return `${timePrefix}ERROR: ${data?.['error'] || 'Unknown error'}`;
+    }
+    return `${timePrefix}${text}`;
+  }
+
+  formatParticipant(participant: AnyObj | null | undefined, agentId: string): string {
+    if (!participant) return 'unknown';
+    const id = (participant['id'] as string) || 'unknown';
+    if (participant['type'] === 'system') return 'System';
+    if (id === agentId) return 'You';
+    return `${id} (${participant['type'] || 'unknown'})`;
+  }
+
+  formatOwner(task: AnyObj, agentId: string): string {
+    const ag = task['agreement'] as AnyObj | undefined;
+    const creatorId = (ag?.['parties'] as AnyObj | undefined)?.['creatorId'] ?? task['agentId'];
+    return creatorId === agentId ? 'You' : String(creatorId ?? 'N/A');
+  }
+
+  formatExecutor(task: AnyObj, agentId: string): string {
+    const ag = task['agreement'] as AnyObj | undefined;
+    const providerId = (ag?.['parties'] as AnyObj | undefined)?.['providerId'] ?? task['executorId'];
+    return providerId === agentId ? 'You' : String(providerId ?? 'N/A');
+  }
+
+  shortId(id: string | null | undefined): string {
+    if (!id) return '?';
+    if (!this.shortIds) return id;
+    const parts = id.split('_');
+    if (parts.length >= 3) return `task_...${parts[parts.length - 1]}`;
+    return id.length > 20 ? id.slice(0, 20) + '...' : id;
+  }
+
+  formatTime(timestamp: string | null | undefined): string {
+    if (!timestamp) return '??:??';
+    const date = new Date(timestamp);
+    if (isNaN(date.getTime())) return '??:??';
+    return date.toLocaleTimeString('en-US', { hour: '2-digit', minute: '2-digit', second: '2-digit', hour12: false, timeZone: 'UTC' });
+  }
+
+  formatArgs(args: AnyObj | null | undefined): string {
+    if (!args || typeof args !== 'object') return '';
+    const entries = Object.entries(args);
+    if (entries.length === 0) return '';
+    if (entries.length <= 3) return entries.map(([k, v]) => `${k}=${JSON.stringify(v)}`).join(', ');
+    return JSON.stringify(args);
+  }
+
+  private safeParseJSON(str: string): AnyObj | null {
+    try { return JSON.parse(str) as AnyObj; }
+    catch { return null; }
+  }
+}
+
+export const historyFormatter = new HistoryFormatter();

package/src/formatters/index.ts

@@ -0,0 +1,2 @@
+export { HistoryFormatter, historyFormatter } from './HistoryFormatter.js';
+export { AgreementFormatter, agreementFormatter } from './AgreementFormatter.js';