@ziggs-ai/agent-sdk 0.1.3

package/src/formatters/TaskFormatter.js

@@ -0,0 +1,180 @@
+/**
+ * TaskFormatter - Pluggable formatter for converting raw task 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 TaskFormatter {
+  constructor(options = {}) {
+    this.options = options;
+    this.shortIds = options.shortIds ?? false; // Always show full IDs by default
+    this.indentSize = options.indentSize ?? 2;
+  }
+
+  /**
+   * Format an array of tasks into readable text
+   * @param {Array} tasks - Array of tasks from context
+   * @param {string} agentId - The current agent's ID (for "You" labels)
+   * @returns {string} Formatted tasks text
+   */
+  format(tasks, agentId) {
+    if (!tasks?.length) return 'No active tasks.';
+    
+    // Separate pending proposals from active/other tasks
+    const pending = tasks.filter(t => 
+      t.state === 'proposal' && t.proposal?.status === 'pending'
+    );
+    const active = tasks.filter(t => 
+      t.state !== 'proposal' || t.proposal?.status !== 'pending'
+    );
+    
+    const sections = [];
+    
+    // Show pending proposals first (needs attention)
+    if (pending.length > 0) {
+      sections.push('Pending Proposals (waiting for approval):');
+      pending.forEach(t => {
+        sections.push(this.formatTask(t, agentId, this._indent(1)));
+      });
+    }
+    
+    // Show active tasks
+    if (active.length > 0) {
+      if (sections.length > 0) sections.push('');
+      sections.push('Active Tasks:');
+      active.forEach(t => {
+        sections.push(this.formatTask(t, agentId, this._indent(1)));
+      });
+    }
+    
+    return sections.join('\n');
+  }
+
+  /**
+   * Format a single task
+   */
+  formatTask(task, agentId, indent = '') {
+    const state = (task.state || 'unknown').toUpperCase();
+    const id = this.shortIds ? this.shortId(task.taskId) : task.taskId;
+    const desc = task.description || 'No description';
+    
+    const isOwner = task.agentId === agentId;
+    const isExecutor = task.executorId === agentId;
+    const proposedToYou = task.proposal?.proposedTo === agentId;
+    
+    const lines = [
+      `${indent}[${state}] ${desc}`,
+      `${indent}  ID: ${id}`,
+      `${indent}  Owner: ${isOwner ? 'You' : task.agentId}`,
+      `${indent}  Executor: ${isExecutor ? 'You' : task.executorId}`,
+      `${indent}  Payer: ${task.payerId || 'N/A'}`
+    ];
+    
+    // Add proposal info if present
+    if (task.proposal) {
+      const proposalStatus = task.proposal.status || 'unknown';
+      const proposedTo = proposedToYou ? 'You' : task.proposal.proposedTo;
+      lines.push(`${indent}  Proposal: ${proposalStatus} (to ${proposedTo})`);
+    }
+    
+    // Add parent task reference if this is a subtask
+    if (task.parentTaskId) {
+      const parentId = this.shortIds ? this.shortId(task.parentTaskId) : task.parentTaskId;
+      lines.push(`${indent}  Parent: ${parentId}`);
+    }
+
+    // Orchestration uses contract.specialistAgentId without lifecycle
+    const c = task.contract;
+    if (c && typeof c === 'object') {
+      const contractParts = [];
+      if (c.specialistAgentId) contractParts.push(`specialistAgentId: ${c.specialistAgentId}`);
+      if (Array.isArray(c.specialistAgentIds) && c.specialistAgentIds.length > 0) {
+        contractParts.push(`specialistAgentIds: [${c.specialistAgentIds.join(', ')}]`);
+      }
+      if (c.lifecycle && c.lifecycle !== 'open') {
+        contractParts.push(`lifecycle: ${c.lifecycle}`);
+        if (c.maxExecutions != null) contractParts.push(`maxExecutions: ${c.maxExecutions}`);
+        if (c.expiresAt) contractParts.push(`expiresAt: ${c.expiresAt}`);
+      }
+      if (contractParts.length > 0) {
+        lines.push(`${indent}  Contract: ${contractParts.join(', ')}`);
+      }
+    }
+
+    // Add perspective info if present (cross-chat reporting)
+    if (task.perspective?.ownerChatId) {
+      lines.push(`${indent}  Report to: ${task.perspective.ownerChatId}`);
+    }
+
+    
+    // Add result if completed/failed
+    if (task.result && (task.state === 'completed' || task.state === 'failed')) {
+      const resultPreview = task.result.length > 100 
+        ? task.result.slice(0, 100) + '...' 
+        : task.result;
+      lines.push(`${indent}  Result: ${resultPreview}`);
+    }
+    
+    // Add plan steps if present
+    if (task.plan?.steps?.length > 0) {
+      const sorted = [...task.plan.steps].sort((a, b) => a.order - b.order);
+      lines.push(`${indent}  Plan (${sorted.filter(s => s.status === 'completed').length}/${sorted.length} completed):`);
+      sorted.forEach(step => {
+        const icon = { pending: '○', in_progress: '●', completed: '✓', skipped: '–' }[step.status] || '?';
+        const resultNote = 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}${resultNote}`);
+      });
+    }
+
+    // Add subtasks if present
+    if (task.subtasks?.length > 0) {
+      lines.push(`${indent}  Subtasks (${task.subtasks.length}):`);
+      task.subtasks.forEach(subtask => {
+        lines.push(this.formatSubtask(subtask, agentId, indent + '    '));
+      });
+    }
+    
+    return lines.join('\n');
+  }
+
+  /**
+   * Format a subtask (simplified version)
+   */
+  formatSubtask(subtask, agentId, indent = '') {
+    const state = (subtask.state || 'unknown').toUpperCase();
+    const id = this.shortIds ? this.shortId(subtask.taskId) : subtask.taskId;
+    const desc = subtask.description || 'No description';
+    const isExecutor = subtask.executorId === agentId;
+    
+    return `${indent}[${state}] ${desc} (${id}, executor: ${isExecutor ? 'You' : subtask.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;
+  }
+
+  /**
+   * Generate indentation string
+   */
+  _indent(level) {
+    return ' '.repeat(level * this.indentSize);
+  }
+}
+
+// Default instance for easy import
+export const taskFormatter = new TaskFormatter();

package/src/formatters/index.js

@@ -0,0 +1,9 @@
+/**
+ * Formatters - Pluggable formatting utilities for agent prompts
+ * 
+ * These formatters convert raw data into readable text for the prompt.
+ * They are external and pluggable - can be swapped with custom implementations.
+ */
+
+export { HistoryFormatter, historyFormatter } from './HistoryFormatter.js';
+export { TaskFormatter, taskFormatter } from './TaskFormatter.js';

package/src/index.js

@@ -0,0 +1,76 @@
+/**
+ * Package entry. Domain layout (imports flow downward only):
+ *
+ *   ziggs/     WebSocket + DI + ZiggsAgent / createAgent / defineAgent
+ *   agent/     Process: Agent, EventQueue, OutboxBuffer
+ *   workflow/  AgentMachine, WorkflowRuntime
+ *   cognition/ runTurn, PromptBuilder, resolveActionTool
+ *   ingress/   normalizeIncomingEvent (wire → envelope)
+ *   context/   batch, routing flags, applyEffects, workflow labels
+ *   tasks/     TaskService + Ziggs task protocol tools
+ *   tools/     ToolManager, defineTool
+ *   adapters/ OpenAIAdapter
+ *   formatters/ history + task text for prompts
+ *   utils/     jsonExtractor
+ *   shared/    types, ids
+ */
+
+export {
+  ZiggsAgent,
+  createAgent,
+  defineAgent,
+} from './ziggs/runtime.js';
+
+export { Agent } from './agent/Agent.js';
+export { EventQueue } from './agent/EventQueue.js';
+export { OutboxBuffer } from './agent/OutboxBuffer.js';
+export { normalizeIncomingEvent } from './ingress/normalizeIncoming.js';
+export * from './shared/types.js';
+
+export { AgentMachine } from './workflow/AgentMachine.js';
+export { WorkflowRuntime } from './workflow/WorkflowRuntime.js';
+export { agent, parseDsl } from './workflow/dsl.js';
+export { runTurn } from './cognition/runTurn.js';
+export { resolveActionTool } from './cognition/resolveActionTool.js';
+export { PromptBuilder } from './cognition/PromptBuilder.js';
+export {
+  TASK_PROTOCOL_TOOLS,
+  taskMakeTaskTool,
+  taskMakeSubTasksTool,
+  taskUpdateTaskTool,
+  taskRespondProposalTool,
+  taskUpdatePlanStepTool,
+} from './tasks/taskProtocolTools.js';
+export {
+  TASK_PROTOCOL_TOOL_NAMES,
+  TASK_PROTOCOL_TOOL_TO_OPERATION,
+  mapTaskProtocolToolToOperation,
+  isTaskProtocolToolName,
+} from './tasks/taskProtocolRegistry.js';
+export { executeTaskPayload } from './tasks/taskProtocolRunner.js';
+export { classifyIncomingEvent } from './context/classifyEnvelope.js';
+export { buildContextUpdates, CONTEXT_RESET } from './context/applyEffects.js';
+export { getBatchEvents, isTaskResultRelevantToAgent } from './context/batch.js';
+export {
+  classifyWorkflowEvent,
+  findTaskResult,
+  unwrapBatchEvent,
+  findIncomingTaskResult,
+} from './context/routingLabels.js';
+
+export { TaskService } from './tasks/TaskService.js';
+export { ToolManager } from './tools/ToolManager.js';
+export { ToolProvider } from './tools/ToolProvider.js';
+export { defineTool } from './tools/defineTool.js';
+export { OpenAIAdapter } from './adapters/OpenAIAdapter.js';
+export { extractJSON, safeParseJSON } from './utils/jsonExtractor.js';
+export { HistoryFormatter, historyFormatter, TaskFormatter, taskFormatter } from './formatters/index.js';
+export { WebSocketClient, ContextReader, ContextWriter, AgentSearchClient, getBackendUrl, getWebSocketUrl } from '@ziggs-ai/api-client';
+
+export { default } from './ziggs/runtime.js';
+
+// ConnectionPool — opt-in lazy WebSocket pool for large-scale dynamic agent fleets.
+// Use via createAgent(configs, { lazy: true }) or by direct construction.
+export { ConnectionPool } from './ConnectionPool.js';
+export { createHealthServer } from './createHealthServer.js';
+export { runLauncher } from './runLauncher.js';

package/src/ingress/normalizeIncoming.js

@@ -0,0 +1,70 @@
+/**
+ * Converts external metadata + text into canonical event payloads and routing hints.
+ */
+
+import { OPEN_PROPOSAL_TARGET } from '../tasks/taskCore.js';
+
+function normalizeChatId(metadata, taskData) {
+  return metadata.chatId || metadata.chat_id || taskData?.chatId || taskData?.perspective?.ownerChatId || null;
+}
+
+function normalizeReceiverId(metadata, taskData) {
+  return metadata.receiver?.id || metadata.receiverId || metadata.to?.id || taskData?.executorId || taskData?.proposedTo || null;
+}
+
+function isTaskRelated(metadata, taskData) {
+  if (!taskData?.taskId) return false;
+  const entryType = metadata.entryType || 'message';
+  const contentType = metadata.content_type || metadata.contentType || 'text';
+  return (
+    entryType === 'notification' || entryType === 'task_history'
+    || contentType === 'task' || contentType === 'task_update'
+    || Boolean(taskData.state || taskData.proposal || taskData.parentTaskId || taskData.executorId || taskData.agentId || taskData.payerId || taskData.createdBy)
+  );
+}
+
+function isRelevantForAgent(ids, ownAgentId) {
+  if (!ownAgentId) return true;
+  return ids.includes(ownAgentId) || ids.includes(OPEN_PROPOSAL_TARGET);
+}
+
+export function normalizeIncomingEvent({ text, metadata = {}, ownAgentId = null }) {
+  const taskData = metadata.service?.task || metadata.task || null;
+  const chatId = normalizeChatId(metadata, taskData);
+  const receiverId = normalizeReceiverId(metadata, taskData);
+  const senderType = metadata.sender?.type ? String(metadata.sender.type).toUpperCase() : undefined;
+
+  const base = {
+    senderId: metadata.sender?.id,
+    senderType,
+    receiverId: receiverId || undefined,
+    timestamp: Date.now(),
+  };
+
+  if (isTaskRelated(metadata, taskData)) {
+    const receiverFromMeta = metadata.receiver?.id || metadata.receiverId || null;
+    const candidateIds = [
+      taskData.agentId,
+      taskData.executorId,
+      taskData.payerId,
+      taskData.proposedTo,
+      taskData.createdBy,
+      receiverFromMeta,
+    ].filter(Boolean);
+    const relevant = isRelevantForAgent(candidateIds, ownAgentId);
+    return {
+      chatId,
+      event: { ...base, type: 'task_result', result: taskData, text },
+      shouldProcess: relevant,
+      reason: relevant ? null : 'task_not_targeted_to_agent',
+    };
+  }
+
+  const relevant = !ownAgentId || !receiverId || receiverId === ownAgentId || receiverId === OPEN_PROPOSAL_TARGET;
+  return {
+    chatId,
+    event: { ...base, type: 'message', text },
+    shouldProcess: relevant,
+    reason: relevant ? null : 'message_not_targeted_to_agent',
+  };
+}

package/src/runLauncher.js

@@ -0,0 +1,159 @@
+/**
+ * runLauncher — one entry point to run an agent or a fleet.
+ *
+ *   runLauncher(config,      opts)   → single eager agent (hello-world)
+ *   runLauncher([c1, c2, …], opts)   → fleet: ConnectionPool + control socket + health server
+ *
+ * For a single config, the agent connects directly and stays online. No pool,
+ * no wake-on-demand, no yellow-dot "available" state — just one green socket.
+ *
+ * For a fleet, agents register lazily: they show as "available" until messaged,
+ * then the backend pushes a wake frame over the one launcher control socket
+ * and the addressed agent's own socket opens on demand.
+ *
+ * Both shapes share: SIGTERM cleanup, optional health server, optional extra
+ * `onShutdown` hook. The fleet form additionally wires control socket,
+ * optional always-on orchestrator, and optional preWake.
+ *
+ * Usage (single):
+ *   await runLauncher({ ...config, operatorKey, openaiKey });
+ *
+ * Usage (fleet):
+ *   await runLauncher(configs, {
+ *     operatorKey: process.env.ZIGGS_OPERATOR_KEY,
+ *     label:    'council',
+ *     orchestrator: orchConfig,
+ *     preWake:  ['newton', 'einstein'],
+ *     onShutdown: async () => mongo.close(),
+ *   });
+ */
+
+import { ConnectionPool } from './ConnectionPool.js';
+import { ZiggsAgent } from './ziggs/runtime.js';
+import { createHealthServer } from './createHealthServer.js';
+
+/**
+ * @param {object|object[]} configOrConfigs - a single defineAgent config or an array of them
+ * @param {object}   [opts]
+ * @param {string}   [opts.operatorKey]               Credential for the control socket (fleet form only). Falls back to scanning configs.
+ * @param {string}   [opts.wsUrl=process.env.WS_URL]   Backend WebSocket URL
+ * @param {number}   [opts.port=process.env.PORT||8080] Health check port (set to 0 to skip)
+ * @param {boolean}  [opts.healthServer=true]          Start a 200-OK HTTP server on `port`. Default true for both shapes; set false to skip.
+ * @param {string}   [opts.label='launcher']           Log prefix
+ * @param {Array<object>} [opts.agentMeta]             (fleet only) Metadata keyed by agentId for pool.query()
+ * @param {object|Function} [opts.orchestrator]       (fleet only) Always-on extra agent config, or a builder (pool) => config
+ * @param {Array<string>} [opts.preWake=[]]           (fleet only) AgentIds to wake on boot
+ * @param {object}   [opts.poolOptions]               (fleet only) { maxActive, idleTimeoutMs }
+ * @param {Function} [opts.onShutdown]                Extra async cleanup on SIGTERM
+ * @returns {Promise<
+ *   { agent: ZiggsAgent, healthServer?: import('http').Server } |
+ *   { pool: ConnectionPool, orchestrator: ZiggsAgent|null, healthServer?: import('http').Server }
+ * >}
+ */
+export async function runLauncher(configOrConfigs, opts = {}) {
+  if (Array.isArray(configOrConfigs)) {
+    return runFleet(configOrConfigs, opts);
+  }
+  return runSingle(configOrConfigs, opts);
+}
+
+async function runSingle(config, {
+  operatorKey,
+  label        = 'agent',
+  port         = process.env.PORT || 8080,
+  healthServer = true,
+  onShutdown,
+} = {}) {
+  const effectiveKey = operatorKey ?? process.env.ZIGGS_OPERATOR_KEY;
+  const decorated = effectiveKey && !config.operatorKey
+    ? { ...config, operatorKey: effectiveKey }
+    : config;
+  const agent = new ZiggsAgent(decorated);
+  await agent.connectAsync();
+  console.log(`[${label}] "${agent.options.ownAgentId ?? agent.options.name ?? 'agent'}" connected`);
+
+  const server = healthServer ? createHealthServer({ port, label }) : null;
+
+  process.on('SIGTERM', async () => {
+    console.log(`[${label}] SIGTERM — shutting down`);
+    agent.disconnect();
+    try { await onShutdown?.(); } catch (err) { console.warn(`[${label}] onShutdown error: ${err.message}`); }
+    server?.close();
+    process.exit(0);
+  });
+
+  return { agent, healthServer: server ?? undefined };
+}
+
+async function runFleet(configs, {
+  operatorKey,
+  wsUrl        = process.env.WS_URL,
+  port         = process.env.PORT || 8080,
+  healthServer = true,
+  label        = 'launcher',
+  agentMeta,
+  orchestrator: orchestratorConfig,
+  preWake      = [],
+  poolOptions,
+  onShutdown,
+} = {}) {
+  const pool = new ConnectionPool(poolOptions);
+  // Decorate each config with operatorKey so agent sockets pick it up when they connect.
+  const effectiveKey = operatorKey ?? process.env.ZIGGS_OPERATOR_KEY;
+  const decoratedConfigs = effectiveKey
+    ? configs.map(c => (c.operatorKey ? c : { ...c, operatorKey: effectiveKey }))
+    : configs;
+  pool.register(decoratedConfigs, agentMeta);
+  const server = healthServer ? createHealthServer({ port, label }) : null;
+
+  // Optional always-on orchestrator (own socket; not managed by pool idle-eviction).
+  // Accept either a plain config or a builder (pool) => config — orchestrators
+  // whose tools reference the pool need the builder form.
+  let resolvedOrchConfig = typeof orchestratorConfig === 'function'
+    ? orchestratorConfig(pool)
+    : orchestratorConfig;
+  if (resolvedOrchConfig && effectiveKey && !resolvedOrchConfig.operatorKey) {
+    resolvedOrchConfig = { ...resolvedOrchConfig, operatorKey: effectiveKey };
+  }
+
+  // Control socket: single WS that registers all agentIds as "available" and
+  // receives launcher:wake frames from the backend. Prefer explicit opts.operatorKey;
+  // fall back to scanning configs so hello-world callers need no extra wiring.
+  const controlKey = effectiveKey
+    ?? configs.find(c => c.operatorKey)?.operatorKey
+    ?? resolvedOrchConfig?.operatorKey;
+  if (controlKey) {
+    pool.startControl({ wsUrl, operatorKey: controlKey });
+  } else {
+    console.warn(`[${label}] No operatorKey provided — skipping control socket`);
+  }
+
+  let orchestrator = null;
+  if (resolvedOrchConfig) {
+    orchestrator = new ZiggsAgent(resolvedOrchConfig);
+    await orchestrator.connectAsync();
+    console.log(`[${label}] Orchestrator "${resolvedOrchConfig.name || resolvedOrchConfig.ownAgentId || 'orchestrator'}" connected`);
+  }
+
+  if (preWake.length > 0) {
+    await Promise.all(preWake.map(id =>
+      pool.wake(id)
+        .then(() => console.log(`[${label}] Pre-woke "${id}"`))
+        .catch(err => console.warn(`[${label}] Could not pre-wake "${id}": ${err.message}`))
+    ));
+  }
+
+  console.log(`[${label}] Ready — ${pool.size} agent(s) registered, ${pool.listActive().length} connected`);
+
+  process.on('SIGTERM', async () => {
+    console.log(`[${label}] SIGTERM — shutting down`);
+    pool.stopControl();
+    orchestrator?.disconnect();
+    await pool.disconnectAll();
+    try { await onShutdown?.(); } catch (err) { console.warn(`[${label}] onShutdown error: ${err.message}`); }
+    server?.close();
+    process.exit(0);
+  });
+
+  return { pool, orchestrator, healthServer: server ?? undefined };
+}

package/src/shared/ids.js

@@ -0,0 +1,7 @@
+/**
+ * Shared id helpers (e.g. operation ids for tool runs).
+ */
+
+export function generateId() {
+  return `${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+}

package/src/shared/types.js

@@ -0,0 +1,86 @@
+/**
+ * Centralized type constants and magic strings used throughout the Agent system
+ *
+ * This file contains two main type systems:
+ * 1. Agent Types: Types used by the Agent core system (events, tasks, etc.)
+ * 2. Timeline Types: Re-exported from @ziggs-ai/api-client for convenience
+ */
+
+// Re-export timeline types from api-client
+export { EntryTypes, ContentTypes } from '@ziggs-ai/api-client';
+
+// ============================================================================
+// AGENT TYPES SYSTEM
+// ============================================================================
+
+// Event Types
+export const EventTypes = {
+  MESSAGE: 'message',
+  TOOL_RESULT: 'tool_result',
+  TOOL_ERROR: 'tool_error',
+  TASK_RESULT: 'task_result',
+  TASK_ERROR: 'task_error',
+};
+
+// ⚠️  SYNC: Task states re-exported from taskCore.js — see backend/src/tasks/task-core.ts
+export { TaskState as TaskStates, TERMINAL_STATES, OPEN_PROPOSAL_TARGET } from '../tasks/taskCore.js';
+
+// Task Operations
+export const TaskOperations = {
+  MAKE_TASK: 'make-task',
+  MAKE_SUB_TASKS: 'make-sub-tasks',
+  UPDATE_TASK: 'update-task',
+  RESPOND_PROPOSAL: 'respond-proposal',
+};
+
+// Context Properties
+export const ContextProperties = {
+  HISTORY: 'history',
+  ACTIVE_TASKS: 'activeTasks',
+  AGENTS: 'agents',
+  USERS: 'users',
+};
+
+// Decision Properties
+export const DecisionProperties = {
+  TASK: 'task',
+  ACTION: 'action',
+  REASONING: 'reasoning',
+};
+
+// Task Properties
+export const TaskProperties = {
+  STATE: 'state',
+  SUBTASKS: 'subtasks',
+  TASK_ID: 'taskId',
+  DESCRIPTION: 'description',
+  OPERATION: 'operation',
+  STATUS: 'status',
+  RESULT: 'result',
+  EXECUTOR_ID: 'executorId',
+  TYPE: 'type',
+};
+
+// Operation Types
+export const OperationTypes = {
+  TOOL: 'tool',
+};
+
+// Operation States
+export const OperationStates = {
+  STARTED: 'started',
+  COMPLETED: 'completed',
+  ERROR: 'error',
+};
+
+// Participant Types
+// Sender IDs
+export const SenderIds = {
+  SYSTEM: 'system',
+  AGENT: 'agent',
+};
+
+// Task Types
+export const TaskTypes = {
+  CONVERSATION: 'conversation',
+};