@ziggs-ai/agent-sdk 0.1.3 → 0.1.5

package/src/types.ts

@@ -0,0 +1,407 @@
+/**
+ * Foundation types for the agent SDK workflow runtime.
+ *
+ * One outcome vocabulary, one ctx shape, one transition signature.
+ * Every state — parked or thinking — re-enters with exactly one Outcome.
+ */
+
+// ── Refs (opaque payloads from the protocol layer) ───────────────────────────
+
+export interface AgreementRef {
+  agreementId: string;
+  parties?: {
+    creator?: string;
+    provider?: string;
+    payer?: string;
+    proposedTo?: string;
+  };
+  proposal?: { status?: 'pending' | 'approved' | 'rejected' | 'cancelled' };
+  money?: { price?: number; paymentStatus?: string };
+}
+
+export interface TaskRef {
+  taskId: string;
+  agreementId?: string;
+  agreement?: AgreementRef;
+  state?: string;
+  description?: string;
+  parentTaskId?: string;
+  proposal?: { status?: 'pending' | 'approved' | 'rejected' | 'cancelled' };
+  proposedToIsYou?: boolean;
+  providerIsYou?: boolean;
+  creatorIsYou?: boolean;
+  payerIsYou?: boolean;
+}
+
+export interface ProposalRef {
+  agreementId: string;
+  agreement?: AgreementRef;
+}
+
+// ── Outcomes (hybrid: closed core + extension) ───────────────────────────────
+
+export type OutcomeKind =
+  | 'enter'
+  | 'wait'
+  | 'timeout'
+  | 'message-sent'
+  | 'message-received'
+  | 'task-assigned'
+  | 'task-delegated'
+  | 'task-closed'
+  | 'subtask-finished'
+  | 'proposal-made'
+  | 'proposal-resolved'
+  | 'tool-result'
+  | 'error'
+  | 'extension';
+
+export type Outcome =
+  | { kind: 'enter' }
+  | { kind: 'wait' }
+  | { kind: 'timeout' }
+  | { kind: 'message-sent'; text?: string; receiverId?: string }
+  | { kind: 'message-received'; text?: string; senderId?: string; senderType?: string }
+  | { kind: 'task-assigned'; task: TaskRef }
+  | { kind: 'task-delegated'; task: TaskRef }
+  | { kind: 'task-closed'; status: 'completed' | 'failed'; result?: unknown }
+  | { kind: 'subtask-finished'; status: 'completed' | 'failed'; task: TaskRef; result?: unknown }
+  | { kind: 'proposal-made'; proposal: ProposalRef }
+  | { kind: 'proposal-resolved'; action: 'approve' | 'reject'; proposal: ProposalRef }
+  | { kind: 'tool-result'; tool: string; result: unknown }
+  | {
+      kind: 'error';
+      source: 'llm' | 'tool' | 'protocol' | 'validation' | 'unknown';
+      cause: unknown;
+      retryable: boolean;
+    }
+  | { kind: 'extension'; name: string; payload: unknown };
+
+// ── Ctx (memory only — no event-derived flags) ───────────────────────────────
+
+/**
+ * A session is the Server-side abstraction the Agent operates against:
+ * `{ sessionId, ctx, queue, parked }`. `Identity` is the Agent's view of
+ * which session this tick belongs to. `sessionId` is opaque to the Agent —
+ * it's a string the Server uses to route inbound events and outbound
+ * effects. (Today, the Ziggs transport derives sessionId from `chatId` at
+ * the wire boundary; non-chat surfaces will produce sessionIds of other
+ * shapes.)
+ */
+export interface Identity {
+  agentId: string;
+  sessionId: string;
+  laneKey: string;
+}
+
+export interface HistoryEntry {
+  entryType?: string;
+  text?: string;
+  sender?: { id?: string; type?: string };
+  receiver?: { id?: string };
+  timestamp?: number;
+  [key: string]: unknown;
+}
+
+export interface ToolResultEntry {
+  tool: string;
+  result?: unknown;
+  error?: string;
+}
+
+/**
+ * Per-lane runtime state. Outcome is "what just happened"; Ctx is "what I know."
+ *
+ * Persistent identifiers (activeAgreementId, pendingProposalAgreementId,
+ * delegatedTaskIds) survive across outcomes — they're the memory of which
+ * agreement the agent is currently bound to and which subtasks it's awaiting.
+ */
+export interface Ctx {
+  identity: Identity;
+
+  // Persistent protocol state
+  activeAgreementId: string | null;
+  activeTaskId: string | null;
+  pendingProposalAgreementId: string | null;
+  delegatedAgreementIds: string[];
+  delegatedTaskIds: string[];
+
+  // Per-turn working memory
+  toolResults: ToolResultEntry[];
+
+  // Last event/turn that caused this entry
+  lastOutcome: Outcome;
+
+  // Server-provided context (history, agreements, agents, users) is fetched
+  // on demand inside runTurn; not persisted on Ctx.
+}
+
+// ── Workflow shape ───────────────────────────────────────────────────────────
+
+export interface PromptDef {
+  role?: string;
+  goal?: string;
+  context?: string;
+  constraints?: string;
+}
+
+export interface ActionPrompt {
+  instruction: string;
+  format?: string;
+  when?: string;
+  examples?: Array<{ scenario?: string; input?: string; output?: string; query?: string }>;
+}
+
+/**
+ * `produces` is the outcome-kind contract for an action. Static form for
+ * actions that always emit the same kind (most common); function form for
+ * tool-bound actions where the result determines the kind (e.g. success vs
+ * error). The runtime composes the kind with action metadata to build the
+ * full Outcome.
+ */
+export type ProducesFn = (result: unknown, args: unknown) => OutcomeKind;
+export type Produces = OutcomeKind | ProducesFn;
+
+export interface Action {
+  prompt: ActionPrompt;
+  tool?: string | null;
+  produces: Produces;
+  /**
+   * When true, the tool loop exits immediately after this action's tool result,
+   * even if the result is non-terminal. Prevents the LLM from issuing additional
+   * tool calls in the same turn (e.g. calling agreement_subcontract right after
+   * agent_search before the FSM can route to evaluatingCandidates).
+   */
+  terminatesLoop?: boolean;
+}
+
+export interface Transition {
+  to: string;
+  when?: (outcome: Outcome, ctx: Ctx) => boolean;
+}
+
+export interface ParkedState {
+  kind: 'parked';
+  transitions: Transition[];
+}
+
+export interface ThinkingState {
+  kind: 'thinking';
+  prompt: PromptDef;
+  actions: Record<string, Action>;
+  transitions: Transition[];
+  /**
+   * Opt out of the validateWorkflow warning that flags thinking states
+   * missing a `wait` action / activeWait fallthrough. Use sparingly — silent
+   * states that loop on themselves are usually a bug.
+   */
+  allowNoWait?: boolean;
+}
+
+export type State = ParkedState | ThinkingState;
+
+export interface Workflow {
+  id: string;
+  description: string;
+  initial: string;
+  states: Record<string, State>;
+}
+
+// ── Effects (the Agent ↔ Server boundary) ────────────────────────────────────
+//
+// The Agent is pure: its only side channel is `EffectHandler`. Every impure
+// operation — reading context, calling the LLM, executing a tool, sending a
+// message — is expressed as an Effect. The Server implements the handler;
+// the Agent emits effects via `await eff({ kind: ..., ... })` and consumes
+// the typed result. This is the Node.js-style "sync dress over async" loop:
+// `tick` reads top-to-bottom but every `await` is a yield to the Server.
+
+export interface LlmToolCall {
+  id: string;
+  function: { name: string; arguments: string };
+}
+
+export interface LlmMessage {
+  role: 'system' | 'user' | 'assistant' | 'tool';
+  content?: string;
+  tool_calls?: LlmToolCall[];
+  tool_call_id?: string;
+}
+
+export interface LlmToolSchema {
+  type: 'function';
+  function: { name: string; description?: string; parameters?: unknown };
+}
+
+export interface LlmResponse {
+  content?: string;
+  tool_calls?: LlmToolCall[];
+  usage?: {
+    total_tokens?: number;
+    prompt_tokens?: number;
+    completion_tokens?: number;
+    totalTokens?: number;
+    promptTokens?: number;
+    completionTokens?: number;
+  };
+}
+
+export interface ContextSnapshot {
+  history: HistoryEntry[];
+  agreements: unknown[];
+  agents: unknown[];
+  users: unknown[];
+  timelineSummary?: string | null;
+  latestSequence?: string | null;
+  unavailable?: boolean;
+  /** Index signature so PromptBuilder's `ServerContext` can accept it directly. */
+  [key: string]: unknown;
+}
+
+export interface ReadContextOpts {
+  maxMessages?: number;
+  maxCharacters?: number;
+  maxTaskHistory?: number;
+  summarize?: boolean;
+  sinceSequence?: string;
+}
+
+/**
+ * Result of executing a single tool. Tool execution may emit multiple
+ * "events" (terminal markers like `message_sent`, `waited`, etc.) that the
+ * cognition loop inspects to decide whether to keep looping. Those carry
+ * through here as `events`; `result` is the value returned to the LLM.
+ */
+export interface ToolCallResult {
+  ok: boolean;
+  result?: unknown;
+  error?: string;
+  events?: unknown[];
+}
+
+export interface RecordedEntry {
+  kind: string;
+  text?: string;
+  [k: string]: unknown;
+}
+
+import type { MemoryStore } from './memory/MemoryStore.js';
+
+export type EffectKind =
+  | 'read-context'
+  | 'llm-call'
+  | 'stream-text'
+  | 'tool-call'
+  | 'send-message'
+  | 'record-event'
+  | 'get-scope'
+  | 'list-messages'
+  | 'list-artifacts'
+  | 'list-task-history';
+
+export interface ScopeRef { kind: 'chat' | 'agreement' | 'task' | 'counterparty'; id: string }
+
+export type Effect =
+  | { kind: 'read-context'; sessionId: string; opts?: ReadContextOpts }
+  | {
+      kind: 'llm-call';
+      messages: LlmMessage[];
+      tools: LlmToolSchema[];
+      /** Chat/session id for monitoring ingest (ZIG-360). */
+      sessionId?: string;
+      /** Per-turn UUID grouping all LLM + tool calls in one turn (ZIG-440). */
+      runId?: string;
+      /** FSM state name at the time of this call (ZIG-440). */
+      stateId?: string;
+    }
+  | {
+      kind: 'stream-text';
+      sessionId: string;
+      receiverId: string;
+      /** Pre-allocated messageId shared across all chunks and the final send-message. */
+      messageId: string;
+      messages: LlmMessage[];
+    }
+  | {
+      kind: 'tool-call';
+      sessionId: string;
+      name: string;
+      args: unknown;
+      memory?: MemoryStore;
+      senderId?: string;
+      senderType?: string;
+      /** Per-turn UUID (ZIG-440). */
+      runId?: string;
+      /** FSM state name (ZIG-440). */
+      stateId?: string;
+    }
+  | { kind: 'send-message'; sessionId: string; receiverId: string; text: string; messageId?: string }
+  | { kind: 'record-event'; sessionId: string; entry: RecordedEntry }
+  | { kind: 'get-scope'; via: ScopeRef }
+  | { kind: 'list-messages'; chatId: string; after?: string; limit?: number }
+  | { kind: 'list-artifacts'; chatId?: string; agreementId?: string; after?: string; limit?: number }
+  | { kind: 'list-task-history'; taskId: string; after?: string; limit?: number };
+
+/**
+ * Typed result map. With this shape, `await eff({ kind: 'read-context', ... })`
+ * resolves to `ContextSnapshot`, not a union — the discriminant carries the
+ * result type. Tests and Server impls implement this map exhaustively.
+ */
+export interface EffectResultMap {
+  'read-context': ContextSnapshot;
+  'llm-call': LlmResponse;
+  'stream-text': { text: string };
+  'tool-call': ToolCallResult;
+  'send-message': { ok: true };
+  'record-event': { ok: true };
+  'get-scope': unknown;
+  'list-messages': { messages: unknown[]; latestSequence: string | null };
+  'list-artifacts': { artifacts: unknown[]; latestSequence: string | null };
+  'list-task-history': { taskId: string; history: unknown[]; latestSequence: string | null };
+}
+
+export type EffectResult<K extends EffectKind> = EffectResultMap[K];
+
+/** The single side-channel between Agent and Server. */
+export type EffectHandler = <K extends EffectKind>(
+  effect: Extract<Effect, { kind: K }>,
+) => Promise<EffectResult<K>>;
+
+// ── defineAgent input/output ─────────────────────────────────────────────────
+
+export interface ServicesConfig {
+  llm?: { model: string; temperature?: number };
+  tools?: unknown[];
+}
+
+export interface DefineAgentInput {
+  agentId: string;
+  description: string;
+  specialization?: string;
+  initial: string;
+  states: Record<string, State>;
+  tools?: unknown[];
+  services?: ServicesConfig;
+  operatorKey?: string;
+  taskTools?: 'all' | 'none' | string[];
+  [key: string]: unknown;
+}
+
+/**
+ * Frozen output of defineAgent. Consumed directly by AgentHost / createAgent.
+ * No mutation — defineAgent validates and returns; injection of defaults is
+ * the workflow author's responsibility (visible spread of `thinkingDefaults`).
+ */
+export interface AgentConfig {
+  openaiKey: string | undefined;
+  operatorKey?: string;
+  agentId: string;
+  description: string;
+  specialization?: string;
+  tools: unknown[];
+  model: string;
+  workflow: Workflow;
+  services?: ServicesConfig;
+  taskTools?: 'all' | 'none' | string[];
+  [key: string]: unknown;
+}

package/src/utils/jsonExtractor.ts

@@ -0,0 +1,100 @@
+import { runtimeLog } from '../shared/runtimeLog.js';
+
+export function extractJSON(content: string): string {
+  if (!content || typeof content !== 'string') return '';
+
+  const trimmed = content.trim();
+  if (!trimmed.startsWith('{') && !trimmed.startsWith('[')) {
+    const jsonBlockMatch = content.match(/```(?:json)?\s*([\s\S]*?)\s*```/);
+    if (jsonBlockMatch) {
+      content = jsonBlockMatch[1].trim();
+    }
+  }
+
+  const firstBrace = content.indexOf('{');
+  const firstBracket = content.indexOf('[');
+
+  let startIdx = -1;
+  let isArray = false;
+
+  if (firstBrace !== -1 && (firstBracket === -1 || firstBrace < firstBracket)) {
+    startIdx = firstBrace;
+    isArray = false;
+  } else if (firstBracket !== -1) {
+    startIdx = firstBracket;
+    isArray = true;
+  }
+
+  if (startIdx === -1) return content.trim();
+
+  const openChar = isArray ? '[' : '{';
+  const closeChar = isArray ? ']' : '}';
+  let depth = 0;
+  let endIdx = startIdx;
+
+  for (let i = startIdx; i < content.length; i++) {
+    const char = content[i];
+    if (char === openChar) {
+      depth++;
+    } else if (char === closeChar) {
+      depth--;
+      if (depth === 0) { endIdx = i + 1; break; }
+    } else if (char === '"') {
+      i++;
+      while (i < content.length && content[i] !== '"') {
+        if (content[i] === '\\') i++;
+        i++;
+      }
+    }
+  }
+
+  if (endIdx > startIdx) content = content.substring(startIdx, endIdx);
+
+  content = content.trim();
+  content = content.replace(/(?<!:)\/\/.*$/gm, '');
+  content = content.replace(/\/\*[\s\S]*?\*\//g, '');
+  content = content.replace(/,(\s*[}\]])/g, '$1');
+
+  return content;
+}
+
+function repairJsonStrings(jsonText: string): string {
+  if (!jsonText || typeof jsonText !== 'string') return jsonText;
+  const validEscapes = new Set(['"', '\\', '/', 'b', 'f', 'n', 'r', 't', 'u']);
+  let out = '';
+  let inString = false;
+
+  for (let i = 0; i < jsonText.length; i++) {
+    const ch = jsonText[i];
+    if (!inString) {
+      if (ch === '"') inString = true;
+      out += ch;
+      continue;
+    }
+    if (ch === '\\') {
+      const next = jsonText[i + 1];
+      out += (next && validEscapes.has(next)) ? ch : '\\\\';
+      continue;
+    }
+    if (ch === '"') { inString = false; out += ch; continue; }
+    if (ch === '\n') { out += '\\n'; continue; }
+    if (ch === '\r') { out += '\\r'; continue; }
+    out += ch;
+  }
+  return out;
+}
+
+export function safeParseJSON<T = unknown>(content: string, fallback: T | null = null): T | null {
+  try {
+    const extracted = extractJSON(content);
+    if (!extracted || extracted.trim().length === 0) throw new Error('Empty JSON content');
+    try {
+      return JSON.parse(extracted) as T;
+    } catch {
+      return JSON.parse(repairJsonStrings(extracted)) as T;
+    }
+  } catch {
+    runtimeLog.error('JSONExtractor', 'Error parsing JSON', content.length > 500 ? `${content.slice(0, 500)}…` : content);
+    return fallback ?? null;
+  }
+}

package/src/ConnectionPool.js

@@ -1,133 +0,0 @@
-/**
- * ConnectionPool — ZiggsAgent-aware wrapper around api-client's ConnectionManager.
- *
- * The actual pool mechanics (LRU, idle timeout, control socket) live in
- * api-client and know nothing about agents. This class just registers each
- * `defineAgent` config with the manager, supplying the open/close functions
- * that instantiate and tear down a `ZiggsAgent`.
- *
- * Usage:
- *   const pool = new ConnectionPool({ maxActive: 50, idleTimeoutMs: 60_000 });
- *   pool.register(agentConfigs, agentMetadata);
- *   pool.startControl({ wsUrl, operatorKey });   // optional, enables wake-on-demand
- *   const agent = await pool.wake('agent-42');
- *   await pool.sendTo('agent-42', text, metadata);
- */
-
-import { ConnectionManager } from '@ziggs-ai/api-client';
-import { ZiggsAgent } from './ziggs/runtime.js';
-
-export class ConnectionPool {
-  /**
-   * @param {object} opts
-   * @param {number} [opts.maxActive=50]
-   * @param {number} [opts.idleTimeoutMs=60000]
-   */
-  constructor({ maxActive = 50, idleTimeoutMs = 60_000 } = {}) {
-    this._mgr = new ConnectionManager({ maxActive, idleTimeoutMs });
-    // agentId → defineAgent config — kept for ZiggsAgent construction at wake time
-    this._configs = new Map();
-  }
-
-  // ---- registration ----
-
-  /**
-   * Register agents without connecting them. Pool keys use `config.agentId`,
-   * falling back to `config.workflow?.id` / `config.id`.
-   *
-   * @param {Array<object>} configs   defineAgent-compatible configs
-   * @param {Array<object>} [metaArr] Parallel metadata objects keyed by the resolved agentId
-   */
-  register(configs, metaArr = []) {
-    const metaByAgentId = Object.fromEntries(metaArr.map(m => [m.agentId, m]));
-    for (const config of configs) {
-      const agentId = config.agentId
-        ?? config.workflow?.id
-        ?? config.id;
-      if (!agentId) {
-        console.warn('[ConnectionPool] Skipping config with no resolvable agentId (need config.agentId)');
-        continue;
-      }
-      this._configs.set(agentId, config);
-      this._mgr.register(
-        agentId,
-        async () => {
-          const agent = new ZiggsAgent(this._configs.get(agentId));
-          await agent.connectAsync();
-          console.log(`[ConnectionPool] Woke "${agentId}" (active: ${this._mgr.listActive().length + 1}/${this._mgr.maxActive})`);
-          return agent;
-        },
-        (agent) => {
-          agent.disconnect();
-          console.log(`[ConnectionPool] Disconnected "${agentId}"`);
-        },
-        metaByAgentId[agentId],
-      );
-    }
-  }
-
-  // ---- connection lifecycle ----
-
-  async wake(agentId)   { return this._mgr.wake(agentId); }
-  async sleep(agentId)  { return this._mgr.sleep(agentId); }
-  async disconnectAll() { return this._mgr.sleepAll(); }
-
-  /**
-   * Wake an agent, deliver a message, and return the agent's response text.
-   * Awaits the full LLM turn before returning. Resets the idle timer after delivery.
-   */
-  async sendTo(agentId, text, metadata = {}, { timeoutMs = 30_000 } = {}) {
-    const agent = await this.wake(agentId);
-    const chatId = metadata.chatId;
-
-    const msgBuf = agent.agent?.messageBuffer?._pending;
-    const bufBefore = msgBuf?.get(chatId)?.length ?? 0;
-
-    const timeoutPromise = new Promise((_, reject) =>
-      setTimeout(() => reject(new Error(`sendTo timeout for "${agentId}" after ${timeoutMs}ms`)), timeoutMs)
-    );
-    await Promise.race([agent.handleMessage(text, metadata), timeoutPromise]);
-    this._mgr.touch(agentId);
-
-    const pending = msgBuf?.get(chatId);
-    if (pending && pending.length > bufBefore) {
-      const newEntries = pending.splice(bufBefore);
-      if (pending.length === 0) msgBuf.delete(chatId);
-      return newEntries.map(e => e.text).join('\n\n');
-    }
-    return null;
-  }
-
-  // ---- control socket ----
-
-  /**
-   * Open the launcher's control socket to the backend. Agents in this pool
-   * will show as "available" in the store and the backend will push
-   * `launcher:wake` events for them as needed.
-   */
-  startControl({ wsUrl, operatorKey } = {}) {
-    if (!wsUrl || !operatorKey) {
-      console.warn('[ConnectionPool] startControl: wsUrl and operatorKey are required — skipping');
-      return;
-    }
-    this._mgr._controlOpts = { wsUrl, operatorKey };
-    this._mgr.start();
-  }
-
-  /** Close the control socket. Agents flip to "offline" on the backend immediately. */
-  stopControl() {
-    this._mgr._controlHandle?.close();
-    this._mgr._controlHandle = null;
-  }
-
-  // ---- querying ----
-
-  query(filter)  { return this._mgr.query(filter); }
-  list()         { return this._mgr.list(); }
-  listActive()   { return this._mgr.listActive(); }
-  get size()     { return this._mgr.size; }
-  get maxActive() { return this._mgr.maxActive; }
-
-  // Legacy compatibility: p1000's list_agents tool reads _meta directly.
-  get _meta()    { return { get: (id) => this._mgr.getMeta(id) }; }
-}