@ziggs-ai/agent-sdk 0.1.3

package/src/context/applyEffects.js

@@ -0,0 +1,133 @@
+/**
+ * Maps action results into context fields for transition conditions, and holds CONTEXT_RESET.
+ */
+
+import { isTaskProtocolToolName, mapTaskProtocolToolToOperation } from '../tasks/taskProtocolRegistry.js';
+
+function applyTaskOperationResultToContext(updates, operation, result) {
+  const r = result || {};
+  if (operation === 'make-task' || operation === 'make-sub-tasks') {
+    const isProposal = r.state === 'proposal' || r.proposal?.status === 'pending';
+    if (isProposal) {
+      // executorIdIsYou is a backend read-time field — absent from creation responses.
+      // Fallback: proposeToDoWork sets agentId === executorId (you are both owner and executor);
+      //           delegateToAgent sets agentId !== executorId (specialist is the executor).
+      const isOwnProposal = r.executorIdIsYou || (r.agentId && r.agentId === r.executorId);
+      if (isOwnProposal) {
+        updates.proposal = r;
+      } else if (r.executorId) {
+        updates.delegatedTask = r;
+        if (r.taskId) {
+          if (!updates._delegatedTaskIds) updates._delegatedTaskIds = [];
+          updates._delegatedTaskIds.push(r.taskId);
+        }
+      }
+    } else if (r.executorId) {
+      updates.delegatedTask = r;
+      // Accumulate all delegated task IDs for parallel batch delegation
+      if (r.taskId) {
+        if (!updates._delegatedTaskIds) updates._delegatedTaskIds = [];
+        updates._delegatedTaskIds.push(r.taskId);
+      }
+    }
+  }
+  if (operation === 'update-task') {
+    const status = r.state || r.status;
+    if (status === 'completed') updates.taskCompleted = true;
+    if (status === 'failed') updates.taskFailed = true;
+  }
+  if (operation === 'respond-proposal') {
+    updates.respondedProposal = r;
+  }
+}
+
+export const CONTEXT_RESET = Object.freeze({
+  messageSent: false,
+  activeWait: false,
+  proposal: null,
+  delegatedTask: null,
+  taskCompleted: false,
+  taskFailed: false,
+  subtaskResult: null,
+  subtaskFailed: false,
+  toolResults: null,
+  lastError: null,
+  lastAction: null,
+  lastActionResult: null,
+  approval: false,
+  rejection: false,
+  taskAssignment: null,
+  /** User-approved orchestration root: specialist id from task.contract (see AgentMachine). */
+  orchestrationSpecialistAgentId: null,
+  /** When true, a delegated subtask finished and another specialist in the chain should run next. */
+  orchestrationContinueChain: false,
+  incomingMessage: false,
+  respondedProposal: null,
+  searchCompleted: false,
+  boardResults: null,
+  taskPublished: false,
+});
+
+export function buildContextUpdates(actionName, emittedEvents) {
+  const updates = { ...CONTEXT_RESET, lastAction: actionName };
+
+  if (!Array.isArray(emittedEvents)) return updates;
+
+  const toolResults = [];
+
+  for (const ev of emittedEvents) {
+    if (!ev || typeof ev !== 'object') continue;
+    const events = Array.isArray(ev) ? ev : [ev];
+
+    for (const e of events) {
+      switch (e.type) {
+        case 'tool_result':
+          toolResults.push({ tool: e.tool, result: e.result });
+          updates.lastActionResult = e;
+          if (isTaskProtocolToolName(e.tool)) {
+            applyTaskOperationResultToContext(updates, mapTaskProtocolToolToOperation(e.tool), e.result);
+          }
+          break;
+
+        case 'tool_error':
+          toolResults.push({ tool: e.tool, error: e.error });
+          updates.lastActionResult = e;
+          updates.lastError = e.error;
+          break;
+
+        case 'message_sent':
+          updates.messageSent = true;
+          updates.lastActionResult = e;
+          break;
+
+        case 'message_duplicate_skipped':
+          updates.messageSent = true;
+          break;
+
+        case 'waited':
+          updates.activeWait = true;
+          break;
+
+        case 'task_result': {
+          const result = e.result || {};
+          const operation = e.operation;
+          updates.lastActionResult = e;
+          applyTaskOperationResultToContext(updates, operation, result);
+          break;
+        }
+
+        case 'task_error':
+          updates.lastError = e.error;
+          updates.lastActionResult = e;
+          break;
+
+        default:
+          break;
+      }
+    }
+  }
+
+  if (toolResults.length > 0) updates.toolResults = toolResults;
+
+  return updates;
+}

package/src/context/batch.js

@@ -0,0 +1,25 @@
+/**
+ * Unwrap batched events and task-result relevance for routing / workflow.
+ */
+
+export function getBatchEvents(rawEvent) {
+  if (!rawEvent) return [];
+  if (rawEvent.type === 'batch' && Array.isArray(rawEvent.events)) {
+    return rawEvent.events;
+  }
+  return [rawEvent];
+}
+
+/**
+ * Whether a task_result payload is relevant to the current agent (routing / workflow).
+ */
+export function isTaskResultRelevantToAgent(result, ownAgentId) {
+  if (!ownAgentId) return true;
+  return (
+    result.executorIdIsYou || result.agentIdIsYou || result.proposedToIsYou
+    || result.payerIdIsYou || result.createdByIsYou
+    || result.executorId === ownAgentId || result.agentId === ownAgentId
+    || result.payerId === ownAgentId || result.proposedTo === ownAgentId
+    || result.createdBy === ownAgentId || result.proposedTo === 'everyone'
+  );
+}

package/src/context/classifyEnvelope.js

@@ -0,0 +1,82 @@
+/**
+ * Classifies incoming events (routing states) into flags merged into machine context.
+ */
+
+import { CONTEXT_RESET } from './applyEffects.js';
+import { getBatchEvents, isTaskResultRelevantToAgent } from './batch.js';
+
+function isTaskAssignment(result, ownAgentId) {
+  return (
+    (result.executorIdIsYou || result.executorId === ownAgentId)
+    && (result.state === 'active' || result.state === 'in-progress')
+  );
+}
+
+export function classifyIncomingEvent(rawEvent, ownAgentId) {
+  const flags = { ...CONTEXT_RESET };
+
+  if (!rawEvent) return flags;
+
+  const events = getBatchEvents(rawEvent);
+
+  for (const ev of events) {
+    if (!ev) continue;
+
+    if (ev.type === 'task_result') {
+      const result = ev.result || {};
+      if (
+        ownAgentId &&
+        !isTaskResultRelevantToAgent(result, ownAgentId) &&
+        ev.receiverId !== ownAgentId
+      ) {
+        continue;
+      }
+
+      const state = result.state;
+      const proposalStatus = result.proposal?.status;
+
+      // User approved your orchestration proposal: you remain agentId + executorId on the task.
+      // Keep this before isTaskAssignment so we still classify if IsYou flags were computed for another viewer.
+      if (
+        state === 'active' &&
+        proposalStatus === 'approved' &&
+        ownAgentId &&
+        result.agentId === 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;
+      continue;
+    }
+
+    flags.incomingMessage = true;
+  }
+
+  return flags;
+}

package/src/context/routingLabels.js

@@ -0,0 +1,54 @@
+/**
+ * Higher-level workflow labels derived from batched incoming events.
+ */
+
+import { isTaskProtocolToolName } from '../tasks/taskProtocolRegistry.js';
+import { getBatchEvents, isTaskResultRelevantToAgent } from './batch.js';
+
+export function unwrapBatchEvent(event) {
+  if (event?.type === 'batch' && event.events?.[0]) return event.events[0];
+  return event;
+}
+
+export function classifyWorkflowEvent(event, ownAgentId = null) {
+  const events = getBatchEvents(event);
+  if (events.length === 0) return 'message';
+
+  let sawTaskResult = false;
+  let sawOwnTaskResult = false;
+
+  for (const ev of events) {
+    if (ev?.type !== 'task_result') continue;
+    sawTaskResult = true;
+
+    const result = ev.result || {};
+    if (!isTaskResultRelevantToAgent(result, ownAgentId)) continue;
+    sawOwnTaskResult = true;
+
+    const state = result.state;
+    const proposalStatus = result.proposal?.status;
+
+    if (
+      (result.executorIdIsYou || (!result.executorIdIsYou && result.executorId === ownAgentId))
+      && (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) {
+  return output?.emittedEvents?.find(e =>
+    e.type === 'task_result' || (e.type === 'tool_result' && isTaskProtocolToolName(e.tool))
+  ) ?? null;
+}
+
+export function findIncomingTaskResult(incomingEvent) {
+  const events = getBatchEvents(incomingEvent);
+  return events.find(e => e?.type === 'task_result') ?? null;
+}

package/src/createHealthServer.js

@@ -0,0 +1,28 @@
+/**
+ * createHealthServer — minimal HTTP server for platform health checks.
+ *
+ * Previously this file also served a wake webhook; wake events now travel over
+ * the launcher's control WebSocket (see ConnectionPool.startControl), so this
+ * server only answers 200 OK for anything. Keep it for Cloud Run-style
+ * platforms that require a listening HTTP port on the launcher container.
+ *
+ * Usage:
+ *   createHealthServer({ label: 'launcher' });
+ */
+
+import { createServer } from 'http';
+
+/**
+ * @param {object} [opts]
+ * @param {number} [opts.port]   - defaults to process.env.PORT || 8080
+ * @param {string} [opts.label]  - log prefix
+ * @returns {import('http').Server}
+ */
+export function createHealthServer({ port = process.env.PORT || 8080, label = 'agents' } = {}) {
+  const server = createServer((_req, res) => {
+    res.writeHead(200);
+    res.end('ok');
+  });
+  server.listen(port, () => console.log(`[${label}] health server on port ${port}`));
+  return server;
+}

package/src/formatters/HistoryFormatter.js

@@ -0,0 +1,257 @@
+/**
+ * HistoryFormatter - Pluggable formatter for converting raw MongoDB history data to readable text.
+ * 
+ * This formatter is external and pluggable - can be swapped with custom implementations
+ * by passing a different formatter to PromptBuilder.
+ */
+export class HistoryFormatter {
+  constructor(options = {}) {
+    this.options = options;
+    this.showTimestamps = options.showTimestamps ?? true;
+    this.shortIds = options.shortIds ?? false; // Always show full IDs by default
+  }
+
+  /**
+   * Format an array of history entries into readable text
+   * @param {Array} history - Array of history entries from context
+   * @param {string} agentId - The current agent's ID (for "You" labels)
+   * @param {Object} options - Optional: { mode } - when mode is 'mission', prefixes each line with [CHAT], [TOOL], or [TASK]
+   * @returns {string} Formatted history text
+   */
+  format(history, agentId, options = {}) {
+    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).getTime() : 0;
+      const tB = b.timestamp ? new Date(b.timestamp).getTime() : 0;
+      return tA - tB;
+    });
+    return sorted.map(entry => this.formatEntry(entry, agentId, labelTypes)).join('\n');
+  }
+
+  /**
+   * Format a single history entry based on its type
+   * @param {boolean} labelTypes - When true, prefix with [CHAT], [TOOL], or [TASK]
+   */
+  formatEntry(entry, agentId, labelTypes = false) {
+    const timestamp = this.showTimestamps ? this.formatTime(entry.timestamp) : '';
+    const timePrefix = timestamp ? `[${timestamp}] ` : '';
+    let typeLabel = '';
+
+    // Message entries
+    if (entry.entryType === 'message' || !entry.entryType) {
+      const line = this.formatMessage(entry, agentId, timePrefix);
+      typeLabel = labelTypes ? '[CHAT] ' : '';
+      return `${typeLabel}${line}`;
+    }
+
+    // Task history entries
+    if (entry.entryType === 'task_history') {
+      const line = this.formatTaskHistory(entry, agentId, timePrefix);
+      typeLabel = labelTypes ? '[TASK] ' : '';
+      return `${typeLabel}${line}`;
+    }
+
+    // Artifact entries (operation tracking, or agent thought)
+    if (entry.entryType === 'artifact') {
+      const line = this.formatArtifact(entry, agentId, timePrefix);
+      if (labelTypes) {
+        if (entry.content_type === 'thought') {
+          typeLabel = '[THOUGHT] ';
+        } else {
+          const text = entry.text || '';
+          const json = text.replace(/^operation_(?:started|completed|error):/, '');
+          const data = json ? this.safeParseJSON(json) : null;
+          typeLabel = (data?.type === 'tool' || text.includes('operation_error')) ? '[TOOL] ' : '[TASK] ';
+        }
+      }
+      return `${typeLabel}${line}`;
+    }
+
+    return `${timePrefix}${entry.text || 'Unknown entry'}`;
+  }
+
+  /**
+   * Format a message entry
+   */
+  formatMessage(entry, agentId, timePrefix) {
+    const from = this.formatParticipant(entry.sender, agentId);
+    const to = entry.receiver ? ` → ${this.formatParticipant(entry.receiver, agentId)}` : '';
+    const text = entry.text || '';
+    
+    return `${timePrefix}${from}${to}: ${text}`;
+  }
+
+  /**
+   * Format a task history entry (created, state_changed, proposal_responded, etc.)
+   */
+  formatTaskHistory(entry, agentId, timePrefix) {
+    const task = entry.service?.task;
+    if (!task) return `${timePrefix}Task update`;
+    
+    const changeType = entry.service?.changeType;
+    const taskId = this.shortIds ? this.shortId(task.taskId) : task.taskId;
+    const desc = task.description || 'No description';
+    
+    switch (changeType) {
+      case 'created':
+        return `${timePrefix}Task created: "${desc}" (${taskId})
+    Owner: ${this.formatOwner(task, agentId)}
+    Executor: ${this.formatExecutor(task, agentId)}
+    Proposed to: ${task.proposal?.proposedTo || 'N/A'}`;
+      
+      case 'state_changed': {
+        const oldState = entry.service?.previousState?.state || '?';
+        const newState = entry.service?.newState?.state || '?';
+        return `${timePrefix}Task "${desc}" (${taskId}): ${oldState} → ${newState}`;
+      }
+      
+      case 'proposal_responded': {
+        const action = entry.service?.metadata?.action;
+        return `${timePrefix}Proposal ${action}: "${desc}" (${taskId})`;
+      }
+      
+      case 'processing_changed': {
+        const processing = entry.service?.newState?.processing;
+        return `${timePrefix}Task "${desc}" (${taskId}): processing ${processing ? 'started' : 'stopped'}`;
+      }
+      
+      default:
+        return `${timePrefix}Task ${changeType}: "${desc}" (${taskId})`;
+    }
+  }
+
+  /**
+   * Format an artifact entry (operation tracking, or agent thought)
+   */
+  formatArtifact(entry, agentId, timePrefix) {
+    const text = entry.text || '';
+
+    // Agent thought (chain-of-thought reasoning)
+    if (entry.content_type === 'thought') {
+      return `${timePrefix}Thought: ${text}`;
+    }
+
+    // Parse and simplify operation_started messages
+    if (text.startsWith('operation_started:')) {
+      const data = this.safeParseJSON(text.replace('operation_started:', ''));
+      if (data?.type === 'tool') {
+        const argsStr = this.formatArgs(data.args);
+        return `${timePrefix}Tool starting: ${data.tool}(${argsStr})`;
+      }
+      if (data?.type === 'task') {
+        return `${timePrefix}Task operation: ${data.operation}`;
+      }
+      return `${timePrefix}Operation started: ${data?.type || 'unknown'}`;
+    }
+    
+    // Parse and simplify operation_completed messages
+    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'}`;
+    }
+    
+    // Parse and simplify operation_error messages
+    if (text.startsWith('operation_error:')) {
+      const data = this.safeParseJSON(text.replace('operation_error:', ''));
+      return `${timePrefix}ERROR: ${data?.error || 'Unknown error'}`;
+    }
+    
+    // Default: return text as-is
+    return `${timePrefix}${text}`;
+  }
+
+  /**
+   * Format a participant (sender/receiver) with "You" label if applicable
+   */
+  formatParticipant(participant, agentId) {
+    if (!participant) return 'unknown';
+    const id = participant.id || 'unknown';
+    const type = participant.type || 'unknown';
+    const isYou = id === agentId;
+    
+    if (type === 'system') return 'System';
+    if (isYou) return 'You';
+    return `${id} (${type})`;
+  }
+
+  /**
+   * Format task owner with "You" label if applicable
+   */
+  formatOwner(task, agentId) {
+    return task.agentId === agentId ? 'You' : task.agentId;
+  }
+
+  /**
+   * Format task executor with "You" label if applicable
+   */
+  formatExecutor(task, agentId) {
+    return task.executorId === agentId ? 'You' : task.executorId;
+  }
+
+  /**
+   * Return full task ID (or shortened if shortIds option is enabled)
+   */
+  shortId(taskId) {
+    if (!taskId) return '?';
+    
+    // If shortIds is disabled, always return full ID
+    if (!this.shortIds) return taskId;
+    
+    // Otherwise, shorten it
+    const parts = taskId.split('_');
+    if (parts.length >= 3) {
+      return `task_...${parts[parts.length - 1]}`;
+    }
+    return taskId.length > 20 ? taskId.slice(0, 20) + '...' : taskId;
+  }
+
+  /**
+   * Format timestamp as readable time
+   */
+  formatTime(timestamp) {
+    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 
+    });
+  }
+
+  /**
+   * Format args object for display
+   */
+  formatArgs(args) {
+    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);
+  }
+
+  /**
+   * Safely parse JSON, returning null on failure
+   */
+  safeParseJSON(str) {
+    try {
+      return JSON.parse(str);
+    } catch {
+      return null;
+    }
+  }
+}
+
+// Default instance for easy import
+export const historyFormatter = new HistoryFormatter();