@ziggs-ai/agent-sdk 0.1.3 → 0.1.5

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['proposedTo'] || '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)?.['creator'] ?? 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)?.['provider'] ?? 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';

package/src/index.ts

@@ -0,0 +1,105 @@
+/**
+ * @ziggs-ai/agent-sdk public surface.
+ *
+ * Foundation:
+ *   • Outcome union — discriminated, hybrid (closed core + extension)
+ *   • Workflow shape — explicit kind: 'parked' | 'thinking'
+ *   • Visible defaults — thinkingDefaults({ initial }) spread by author
+ *   • Validation at load — defineAgent throws on hard problems, warns on soft
+ */
+
+export { defineAgent } from './defineAgent.js';
+export { AgentHost, createAgent, createAgentPool } from './AgentHost.js';
+export { Agent } from './agent/Agent.js';
+export type { TickInput, TickOutput, AgentOptions } from './agent/Agent.js';
+export type { SessionResolver, AgentHostOptions } from './AgentHost.js';
+export { createZiggsEffectHandler } from './server/ZiggsEffectHandler.js';
+export type { ZiggsEffectDeps } from './server/ZiggsEffectHandler.js';
+export { EventQueue } from './server/EventQueue.js';
+export { OutboxBuffer } from './server/OutboxBuffer.js';
+export { normalizeIncomingEvent } from './ingress/normalizeIncoming.js';
+
+// Runtime primitives
+export { AgentMachine, type TransitionEvent } from './runtime/AgentMachine.js';
+export { runTurn } from './runtime/runTurn.js';
+export { PromptBuilder } from './runtime/PromptBuilder.js';
+export { thinkingDefaults, defineThinkingState, DEFAULT_WAIT_PROMPT } from './runtime/defaults.js';
+export { validateWorkflow, WorkflowValidationError } from './runtime/validateWorkflow.js';
+export { outcomeFromEvent, outcomeFromActionResult, applyOutcomeToCtx } from './runtime/buildOutcome.js';
+
+// Types
+export type {
+  Outcome, OutcomeKind,
+  Ctx, Identity, HistoryEntry, ToolResultEntry,
+  Workflow, State, ParkedState, ThinkingState,
+  Action, Transition, PromptDef, ActionPrompt, Produces, ProducesFn,
+  AgreementRef, TaskRef, ProposalRef,
+  AgentConfig, DefineAgentInput, ServicesConfig,
+  // Effects — Agent↔Server boundary
+  Effect, EffectKind, EffectResult, EffectResultMap, EffectHandler,
+  LlmMessage, LlmToolCall, LlmToolSchema, LlmResponse,
+  ContextSnapshot, ReadContextOpts, ToolCallResult, RecordedEntry,
+} from './types.js';
+
+export { default } from './AgentHost.js';
+
+// ── Supporting modules ──────────────────────────────────────────────────────
+
+export { validateContext, ContextWarning } from './cognition/validateContext.js';
+export { runLauncher } from './server/runLauncher.js';
+export { ConnectionPool } from './server/ConnectionPool.js';
+export { createHealthServer } from './server/createHealthServer.js';
+export { TaskService } from './server/tasks/TaskService.js';
+export { AgreementService } from './server/agreements/AgreementService.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, AgreementFormatter, agreementFormatter } from './formatters/index.js';
+export { ProactiveTrigger } from './server/proactive/ProactiveTrigger.js';
+export { ZiggsPayClient, createZiggsPayClient } from './server/ziggspay/ZiggsPayClient.js';
+export { ZiggsConnectClient, createZiggsConnectClient } from './server/ziggsconnect/ZiggsConnectClient.js';
+export { ZiggsContextClient } from './server/ziggscontext/ZiggsContextClient.js';
+export type {
+  ZiggsContextClientOptions,
+  ContextReachDescriptor,
+  DelegateContextGrantParams,
+} from './server/ziggscontext/ZiggsContextClient.js';
+// All agent tool bundles live under server/tools/ (tier1 = protocol grammar,
+// tier2 = opt-in HTTP capability bundles). Single home: server/tools/index.ts.
+export {
+  // Tier 1 — protocol grammar (framework-managed via taskTools).
+  PROTOCOL_TOOLS, agreementProposeTool, agreementSubcontractTool,
+  agreementRespondTool, agreementCounterProposalTool, agreementCheckProposalTool,
+  taskSpawnTool, taskUpdateTool, taskUpdatePlanStepTool,
+  dispatchProtocolOp,
+  // Tier 2 — opt-in capability bundles (spread into `tools:`).
+  PAYMENT_TOOLS, paymentBalanceTool, paymentTransferTool, paymentHoldTool, paymentReleaseTool, paymentResolveWalletTool,
+  CONNECTION_TOOLS, connectionProxyTool, connectionListGrantsTool,
+  DISCOVERY_TOOLS, agentSearchTool, agentGetTool,
+  MARKETPLACE_TOOLS, marketplaceViewTool,
+} from './server/tools/index.js';
+export { PROTOCOL_TOOL_NAMES, PROTOCOL_TOOL_TO_OPERATION, mapProtocolToolToOperation, isProtocolToolName } from './tasks/protocolRegistry.js';
+export { InMemoryStore, FileMemoryStore } from './memory/MemoryStore.js';
+export type { MemoryStore } from './memory/MemoryStore.js';
+export type { SessionStore } from './AgentHost.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 {
+  WebSocketClient,
+  MessagesClient,
+  ArtifactsClient,
+  ScopeClient,
+  AgentSearchClient,
+  getBackendUrl,
+  getWebSocketUrl,
+} from '@ziggs-ai/api-client';
+
+export { runInboxCatchUp } from './server/InboxCatchUp.js';
+export type { InboxCatchUpDeps, InboxCatchUpResult } from './server/InboxCatchUp.js';
+export { SeenMessages } from './server/SeenMessages.js';
+export { runtimeLog, resetRuntimeLogLevelCache } from './shared/runtimeLog.js';
+export type { RuntimeLogLevel } from './shared/runtimeLog.js';

package/src/ingress/normalizeIncoming.ts

@@ -0,0 +1,162 @@
+import { OPEN_AGREEMENT_TARGET } from '@ziggs-ai/api-client';
+
+/** Backend wire operations that map to FSM `proposal-resolved`. */
+const PROPOSAL_RESOLVED_OPERATIONS = new Set([
+  'proposal_approved',
+  'proposal_rejected',
+  'proposal_approved_execute',
+]);
+
+export interface NormalizedEvent {
+  chatId: string | null;
+  event: {
+    senderId?: string;
+    senderType?: string;
+    receiverId?: string;
+    timestamp: number;
+    type: 'task_result' | 'message' | 'agreement_lifecycle';
+    operation?: string;
+    agreementId?: string;
+    result?: unknown;
+    text?: string;
+  };
+  shouldProcess: boolean;
+  reason: string | null;
+}
+
+interface WireParties {
+  creator?: string;
+  provider?: string;
+  payer?: string;
+  proposedTo?: string;
+}
+
+interface WireTask {
+  taskId?: string;
+  agentId?: string;
+  executorId?: string;
+  payerId?: string;
+  proposedTo?: string;
+  createdBy?: string;
+  parentTaskId?: string;
+  state?: string;
+  proposal?: unknown;
+  agreement?: { parties?: WireParties };
+}
+
+interface WireMetadata {
+  chatId?: string;
+  chat_id?: string;
+  entryType?: string;
+  content_type?: string;
+  contentType?: string;
+  receiverId?: string;
+  operation?: string;
+  agreementId?: string;
+  sender?: { id?: string; type?: string };
+  receiver?: { id?: string };
+  to?: { id?: string };
+  task?: WireTask;
+  [key: string]: unknown;
+}
+
+interface NormalizeArgs {
+  text: string;
+  metadata?: WireMetadata;
+  ownAgentId?: string | null;
+}
+
+function normalizeChatId(metadata: WireMetadata): string | null {
+  return metadata.chatId || metadata.chat_id || null;
+}
+
+function normalizeReceiverId(metadata: WireMetadata, taskData: WireTask | null): string | null {
+  return metadata.receiver?.id || metadata.receiverId || metadata.to?.id || taskData?.executorId || taskData?.proposedTo || null;
+}
+
+function isTaskRelated(metadata: WireMetadata, taskData: WireTask | null): boolean {
+  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: (string | null | undefined)[], ownAgentId: string | null): boolean {
+  if (!ownAgentId) return true;
+  return ids.includes(ownAgentId) || ids.includes(OPEN_AGREEMENT_TARGET);
+}
+
+function isAgreementLifecycleNotification(metadata: WireMetadata): boolean {
+  const entryType = metadata.entryType || 'message';
+  const operation = metadata.operation;
+  return (
+    entryType === 'notification' &&
+    typeof operation === 'string' &&
+    PROPOSAL_RESOLVED_OPERATIONS.has(operation)
+  );
+}
+
+export function normalizeIncomingEvent({ text, metadata = {}, ownAgentId = null }: NormalizeArgs): NormalizedEvent {
+  const taskData = metadata.task || null;
+  const chatId = normalizeChatId(metadata);
+  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 (isAgreementLifecycleNotification(metadata)) {
+    const relevant =
+      !ownAgentId ||
+      !receiverId ||
+      receiverId === ownAgentId ||
+      receiverId === OPEN_AGREEMENT_TARGET;
+    const agreementId =
+      typeof metadata.agreementId === 'string' ? metadata.agreementId : '';
+    return {
+      chatId,
+      event: {
+        ...base,
+        type: 'agreement_lifecycle',
+        operation: metadata.operation,
+        agreementId,
+        text,
+      },
+      shouldProcess: relevant,
+      reason: relevant ? null : 'message_not_targeted_to_agent',
+    };
+  }
+
+  if (isTaskRelated(metadata, taskData)) {
+    const receiverFromMeta = metadata.receiver?.id || metadata.receiverId || null;
+    const parties = taskData!.agreement?.parties ?? {};
+    const candidateIds = [
+      parties.creator, parties.provider, parties.payer, parties.proposedTo,
+      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_AGREEMENT_TARGET;
+  return {
+    chatId,
+    event: { ...base, type: 'message', text },
+    shouldProcess: relevant,
+    reason: relevant ? null : 'message_not_targeted_to_agent',
+  };
+}

package/src/memory/MemoryStore.ts

@@ -0,0 +1,104 @@
+/**
+ * Agent-private long-term memory.
+ *
+ * This is the SDK's contract; the *storage* is operator-provided. The agent
+ * picks the key shape (often `counterparty:<id>`, sometimes `agreement:<id>:notes`,
+ * etc.) — the SDK does not enforce one.
+ *
+ * Reference implementations: `InMemoryStore` (default; non-durable) and
+ * `FileMemoryStore` (single JSON file; useful for local dev). Anything
+ * production-grade (sqlite, redis, postgres, …) is operator-owned.
+ *
+ * Aligns with the project's "agents are third-party" framing: an agent's
+ * private notes are its own concern, not the backend's.
+ */
+export interface MemoryStore {
+  get(key: string): Promise<unknown | undefined>;
+  put(key: string, value: unknown): Promise<void>;
+  list(prefix: string): Promise<{ key: string; value: unknown }[]>;
+  delete?(key: string): Promise<void>;
+}
+
+/** Non-durable reference impl. Per-process; lost on restart. */
+export class InMemoryStore implements MemoryStore {
+  private readonly store = new Map<string, unknown>();
+
+  async get(key: string): Promise<unknown | undefined> {
+    return this.store.get(key);
+  }
+
+  async put(key: string, value: unknown): Promise<void> {
+    this.store.set(key, value);
+  }
+
+  async list(prefix: string): Promise<{ key: string; value: unknown }[]> {
+    const out: { key: string; value: unknown }[] = [];
+    for (const [k, v] of this.store) {
+      if (k.startsWith(prefix)) out.push({ key: k, value: v });
+    }
+    return out;
+  }
+
+  async delete(key: string): Promise<void> {
+    this.store.delete(key);
+  }
+}
+
+/**
+ * Single-file JSON store. Reads on startup, writes on every put — fine for
+ * local dev and example agents; not for production (no concurrency control,
+ * no atomicity). Operators with serious durability needs ship their own
+ * `MemoryStore` (sqlite, redis, …) and pass it via `defineAgent({ memory })`.
+ */
+export class FileMemoryStore implements MemoryStore {
+  private cache: Record<string, unknown> | null = null;
+  private loading: Promise<void> | null = null;
+
+  constructor(private readonly path: string) {}
+
+  private async _ensureLoaded(): Promise<void> {
+    if (this.cache) return;
+    if (!this.loading) {
+      this.loading = (async () => {
+        try {
+          const fs = await import('fs/promises');
+          const txt = await fs.readFile(this.path, 'utf-8');
+          this.cache = JSON.parse(txt) as Record<string, unknown>;
+        } catch {
+          this.cache = {};
+        }
+      })();
+    }
+    await this.loading;
+  }
+
+  private async _flush(): Promise<void> {
+    if (!this.cache) return;
+    const fs = await import('fs/promises');
+    await fs.writeFile(this.path, JSON.stringify(this.cache, null, 2), 'utf-8');
+  }
+
+  async get(key: string): Promise<unknown | undefined> {
+    await this._ensureLoaded();
+    return this.cache![key];
+  }
+
+  async put(key: string, value: unknown): Promise<void> {
+    await this._ensureLoaded();
+    this.cache![key] = value;
+    await this._flush();
+  }
+
+  async list(prefix: string): Promise<{ key: string; value: unknown }[]> {
+    await this._ensureLoaded();
+    return Object.entries(this.cache!)
+      .filter(([k]) => k.startsWith(prefix))
+      .map(([key, value]) => ({ key, value }));
+  }
+
+  async delete(key: string): Promise<void> {
+    await this._ensureLoaded();
+    delete this.cache![key];
+    await this._flush();
+  }
+}