@ziggs-ai/agent-sdk 0.1.3

package/README.md

@@ -0,0 +1,82 @@
+# @ziggs-ai/agent-sdk
+
+**What it is:** A small JavaScript framework for building **autonomous agents** that run on the **Ziggs** platform. You describe behavior as a **workflow** (states, prompts, actions, transitions), wire **tools**, and the SDK handles **LLM calls**, **context**, **tasks**, and optional **WebSocket** connectivity to Ziggs.
+
+It is **not** a generic chat wrapper: the core idea is a **lightweight state machine** (`AgentMachine`) that walks your definition, runs **`runTurn`** for "thinking" steps (prompt + structured actions), and updates **context** from events and `transitions` so routing stays explicit and predictable.
+
+---
+
+## Mental model
+
+| Piece | Role |
+|--------|------|
+| **`defineAgent` / workflow** | Declarative agent: `initial`, `states`, optional `id`, `description`, `specialization`, merged `tools` / `services`. |
+| **`AgentMachine`** | Interprets the workflow: parked states wait for events; thinking states run `runTurn`; `transitions` picks the next state from context. |
+| **`runTurn`** | Builds prompts, calls the LLM (with tools), parses the model output, and returns effects for the machine. |
+| **`ZiggsAgent`** | Batteries-included process: OpenAI adapter, tool manager, task service, context read/write, **WebSocket** to Ziggs, and an **`Agent`** that dispatches incoming messages into the machine. |
+| **`Agent`** | Orchestrates message handling, machine lifecycle, and integration with platform APIs (without requiring you to use WebSockets if you construct it yourself). |
+
+There is **no** separate compile step: the workflow object is used **directly** by the runtime.
+
+---
+
+## Workflow DSL (states)
+
+States are plain objects on `workflow.states`. Every state uses one unified concept:
+
+- **`transitions`** — an array of `{ to, when }` rules evaluated in order. The first rule whose `when(ctx)` returns true (or has no `when`) determines the next state. Supports a plain string shorthand: `'stateName'` is equivalent to `{ to: 'stateName' }`.
+
+Two kinds of state:
+
+- **Parked / waiting:** Has only `transitions`. The machine stops here and waits for the next event. When an event arrives it is classified into context flags (`approval`, `rejection`, `subtaskResult`, etc.) and `transitions` is evaluated to route forward.
+
+- **Thinking:** Has `prompt`, `actions`, and `transitions`. The machine runs an LLM turn via `runTurn`, applies the result into context flags (`messageSent`, `toolResults`, `taskCompleted`, etc.), then evaluates `transitions` to route forward.
+
+Both kinds use the same `transitions` array and the same context shape — the only difference is what filled the context before evaluation.
+
+Context flags available in transitions:
+
+| Set by incoming events (parked states) | Set by LLM turn results (thinking states) |
+|---------------------------------------|------------------------------------------|
+| `approval`, `rejection` | `messageSent`, `activeWait` |
+| `taskAssignment`, `subtaskResult` | `proposal`, `delegatedTask` |
+| `subtaskFailed`, `incomingMessage` | `taskCompleted`, `taskFailed` |
+| | `toolResults`, `lastError`, `respondedProposal` |
+
+The `wait` action is built-in: `defineAgent` automatically injects it into every thinking state that doesn't define one, and appends a `{ to: initial, when: ctx => ctx.activeWait }` transition if none exists.
+
+---
+
+## How you usually run an agent
+
+1. **`defineAgent({ ... })`** → options object including `workflow`.
+2. Pass **`openaiKey`**, **`operatorKey`** (Ziggs operator token), **`agentId`**, **`wsUrl`**, etc., and **`new ZiggsAgent(config)`** (or **`createAgent(config)`**).
+3. **`connect()`** to open the WebSocket; the SDK routes platform messages into **`handleMessage`**.
+
+Examples in the repo: `examples/agents/*.js` (e.g. coffee, expense, delivery agents).
+
+---
+
+## Main exports (entry: `src/index.js`)
+
+- **`ZiggsAgent`**, **`createAgent`**, **`defineAgent`**
+- **`Agent`**, **`AgentMachine`**, **`runTurn`**
+- **Prompt / tools:** `PromptBuilder`, `ToolManager`, `defineTool`
+- **Task tools:** `taskMakeTaskTool`, `taskUpdateTaskTool`, `taskRespondProposalTool`, `taskMakeSubTasksTool`, `taskUpdatePlanStepTool`, `TASK_PROTOCOL_TOOLS`
+- **Adapters / utils:** `OpenAIAdapter`, JSON helpers, formatters
+- **Re-exported** from `@ziggs-ai/api-client`: `WebSocketClient`, `ContextReader`, `ContextWriter`, URL helpers, etc.
+
+Package export: `"."` → `src/index.js` (see `package.json`).
+
+---
+
+## Requirements
+
+- **Node** ≥ 18
+- Env: **`OPENAI_API_KEY`** (and optionally **`OPENAI_MODEL`**) for `defineAgent` defaults; Ziggs **`ZIGGS_OPERATOR_KEY`** (operator token, scope `agents:impersonate`) for platform features.
+
+---
+
+## License
+
+MIT (see package metadata).

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@ziggs-ai/agent-sdk",
+  "version": "0.1.3",
+  "description": "Agent framework SDK for building autonomous agents on the Ziggs platform",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@ziggs-ai/api-client": "^0.1.3",
+    "ajv": "^8.17.1",
+    "dotenv": "^17.2.3",
+    "openai": "^4.0.0"
+  },
+  "keywords": ["ziggs", "agent", "sdk", "ai", "autonomous"],
+  "license": "MIT",
+  "files": ["src", "README.md"],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/ConnectionPool.js

@@ -0,0 +1,133 @@
+/**
+ * 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) }; }
+}

package/src/adapters/OpenAIAdapter.js

@@ -0,0 +1,73 @@
+import OpenAI from "openai";
+
+export class OpenAIAdapter {
+  constructor({key, model = "gpt-4o-mini"}) {
+    this.client = new OpenAI({apiKey: key});
+    this.model = model;
+  }
+
+  /**
+   * Single-turn chat. `prompt` is a string; wraps it as a user message.
+   * Kept for backward compatibility.
+   */
+  async chat(prompt, tools = [], temperature = 0.2, systemHints = [], options = {}) {
+    const messages = [
+      { role: "system", content: "Respond with valid JSON." },
+      ...systemHints,
+      { role: "user", content: prompt }
+    ];
+    return this.chatMessages(messages, tools, options);
+  }
+
+  /**
+   * Low-level chat that accepts a full messages array.
+   * Returns { content, tool_calls, message } where message is the raw assistant message.
+   */
+  async chatMessages(messages, tools = [], options = {}) {
+    const openAITools = tools.length > 0
+      ? tools.map(t => {
+          const schema = t.schema || t;
+          const fn = schema.function || schema;
+          const usageWhen = t.usage?.when ? ` Use when: ${t.usage.when}` : '';
+          return {
+            type: 'function',
+            function: {
+              ...fn,
+              description: (fn.description || '') + usageWhen
+            }
+          };
+        })
+      : undefined;
+
+    try {
+      const res = await this.client.chat.completions.create({
+        model: this.model,
+        messages,
+        max_completion_tokens: 3000,
+        response_format: openAITools ? undefined : (options.response_format ?? { type: 'json_object' }),
+        ...(openAITools && { tools: openAITools }),
+        ...options,
+        usage: undefined,  // strip internal field if accidentally passed
+      });
+
+      const msg = res.choices[0].message;
+      return {
+        content: msg.content?.trim() ?? null,
+        tool_calls: msg.tool_calls?.length ? msg.tool_calls : null,
+        message: msg,
+        usage: res.usage,
+      };
+    } catch (error) {
+      console.error(`❌ [OpenAIAdapter] LLM API call failed: ${error.message}`, {
+        model: this.model,
+        error: error.message,
+        errorType: error.constructor?.name || 'Error',
+        status: error.status || error.statusCode || 'unknown',
+        code: error.code || 'unknown',
+        ...(error.response && { response: error.response }),
+        stack: error.stack
+      });
+      throw error;
+    }
+  }
+}

package/src/adapters/index.js

@@ -0,0 +1 @@
+export { OpenAIAdapter } from './OpenAIAdapter.js';

package/src/agent/Agent.js

@@ -0,0 +1,121 @@
+import { runTurn } from '../cognition/runTurn.js';
+import { OutboxBuffer } from './OutboxBuffer.js';
+import { EventQueue } from './EventQueue.js';
+import { WorkflowRuntime } from '../workflow/WorkflowRuntime.js';
+import { normalizeIncomingEvent } from '../ingress/normalizeIncoming.js';
+
+/**
+ * Orchestrates one workflow instance per lane (ownAgentId:chatId).
+ * Each lane gets an AgentMachine; thinking states invoke `runTurn`.
+ */
+export class Agent {
+  constructor(options = {}) {
+    const {
+      llm, toolManager, contextReader, contextWriter,
+      taskService, messageSender, promptBuilder, operatorKey, agentId,
+    } = options;
+
+    if (!llm) throw new Error('Agent: llm is required');
+    if (!operatorKey) throw new Error('Agent: operatorKey is required');
+    if (!agentId) throw new Error('Agent: agentId is required');
+    if (!contextReader) throw new Error('Agent: contextReader is required');
+    if (!promptBuilder) throw new Error('Agent: promptBuilder is required');
+
+    this.ownAgentId = agentId;
+    this.messageBuffer = new OutboxBuffer();
+    this._laneMeta = new Map();
+    this.definition = options.workflow;
+    if (!this.definition?.states) throw new Error('Agent: workflow definition with states is required');
+
+    this._services = {
+      llm, toolManager, contextReader, contextWriter,
+      taskService, messageSender, messageBuffer: this.messageBuffer,
+      promptBuilder, operatorKey, agentId: this.ownAgentId,
+    };
+
+    this.runtime = new WorkflowRuntime({
+      definition: this.definition,
+      executionCore: runTurn,
+      services: this._services,
+      onSnapshot: (laneKey, snapshot) => this._onWorkflowChange(laneKey, snapshot),
+    });
+
+    this.eventQueue = new EventQueue((event, laneKey) => this._processEvent(event, laneKey));
+  }
+
+  async handleMessage(text, metadata = {}) {
+    const ownAgentId = this._resolveOwnAgentId(metadata);
+    const normalized = normalizeIncomingEvent({ text, metadata, ownAgentId });
+    if (!normalized.shouldProcess) {
+      console.log(`[Agent] Skip reason=${normalized.reason || 'not_relevant'} ownAgentId=${ownAgentId || 'unknown'}`);
+      return;
+    }
+    const chatId = normalized.chatId;
+    if (!chatId) { console.warn('[Agent] No chatId, skipping'); return; }
+
+    const laneKey = this._buildLaneKey(ownAgentId, chatId);
+    this._laneMeta.set(laneKey, { chatId, ownAgentId });
+    return this.eventQueue.enqueue(normalized.event, laneKey);
+  }
+
+  async _processEvent(event, laneKey) {
+    const meta = this._laneMeta.get(laneKey) || this._parseLaneKey(laneKey);
+    const chatId = meta?.chatId || null;
+    const ownAgentId = meta?.ownAgentId || this.ownAgentId || null;
+    if (!chatId) return;
+
+    await this.runtime.sendAndWaitForPark({
+      laneKey,
+      event: { type: 'INCOMING_EVENT', event, chatId, laneKey, ownAgentId },
+      timeoutMs: 120_000,
+      machineInput: { chatId, laneKey, ownAgentId },
+    });
+  }
+
+  _onWorkflowChange(laneKey, snapshot) {
+    if (!snapshot.context) return;
+    const machine = this.runtime.actors.get(laneKey);
+    if (!machine) return;
+
+    const prev = machine._prevSnapshot;
+    machine._prevSnapshot = snapshot;
+    if (!prev) return;
+
+    const wasActive = !this._isParkedSnapshot(prev);
+    const nowParked = this._isParkedSnapshot(snapshot);
+
+    if (wasActive && nowParked) {
+      console.log(`[workflow] parked laneKey=${laneKey} state=${JSON.stringify(snapshot.value)}`);
+      this._trackMessages(snapshot);
+    }
+  }
+
+  _isParkedSnapshot(snapshot) {
+    const sd = this.definition.states[snapshot.value];
+    return !(sd?.prompt && sd?.actions);
+  }
+
+  _trackMessages(snapshot) {
+    const ctx = snapshot.context;
+    if (!ctx?.chatId || !ctx.messageSent) return;
+    const r = ctx.lastActionResult;
+    if (r?.type === 'message_sent') {
+      this.messageBuffer.track(r.chatId || ctx.chatId, { text: r.message, receiverId: r.receiverId });
+    }
+  }
+
+  _resolveOwnAgentId(metadata = {}) {
+    return this.ownAgentId || metadata.self?.id || metadata.agent?.id || metadata.ziggsAgentId || null;
+  }
+
+  _buildLaneKey(ownAgentId, chatId) {
+    return `${ownAgentId || 'unknown-agent'}:${chatId}`;
+  }
+
+  _parseLaneKey(laneKey) {
+    if (!laneKey || typeof laneKey !== 'string') return null;
+    const idx = laneKey.lastIndexOf(':');
+    if (idx === -1) return { ownAgentId: null, chatId: laneKey };
+    return { ownAgentId: laneKey.slice(0, idx) || null, chatId: laneKey.slice(idx + 1) || null };
+  }
+}

package/src/agent/EventQueue.js

@@ -0,0 +1,68 @@
+/**
+ * Serializes and coalesces events per lane to prevent duplicate LLM turns.
+ */
+
+export class EventQueue {
+  constructor(processEventFn) {
+    this._processEvent = processEventFn;
+    /** @type {Map<string, { events: object[], processing: boolean }>} */
+    this._state = new Map();
+  }
+
+  enqueue(event, laneKey) {
+    if (!laneKey) {
+      console.warn('[EventQueue] enqueue called without laneKey, skipping');
+      return Promise.resolve();
+    }
+
+    let state = this._state.get(laneKey);
+    if (!state) {
+      state = { events: [], processing: false };
+      this._state.set(laneKey, state);
+    }
+
+    return new Promise((resolve) => {
+      state.events.push({ event, resolve });
+      console.log(`[EventQueue] enqueue laneKey=${laneKey}, queueLen=${state.events.length}, processing=${state.processing}`);
+      this._processIfNeeded(laneKey);
+    });
+  }
+
+  _processIfNeeded(laneKey) {
+    const state = this._state.get(laneKey);
+    if (!state || state.processing || state.events.length === 0) {
+      return;
+    }
+
+    state.processing = true;
+    this._processLoop(laneKey);
+  }
+
+  async _processLoop(laneKey) {
+    const state = this._state.get(laneKey);
+    if (!state) return;
+
+    while (state.events.length > 0) {
+      const batch = state.events.splice(0, state.events.length);
+      const events = batch.map(e => e.event);
+      const resolvers = batch.map(e => e.resolve);
+
+      const coalesced = events.length === 1
+        ? events[0]
+        : { type: 'batch', events };
+
+      try {
+        await this._processEvent(coalesced, laneKey);
+      } catch (error) {
+        console.error(`[EventQueue] processEvent error for laneKey=${laneKey}:`, error.message);
+        console.error(error.stack);
+      }
+
+      // Resolve all waiters for this batch (success or failure)
+      for (const r of resolvers) r();
+    }
+
+    state.processing = false;
+    console.log(`[EventQueue] processLoop done laneKey=${laneKey}`);
+  }
+}

package/src/agent/OutboxBuffer.js

@@ -0,0 +1,62 @@
+/**
+ * Tracks outbound messages locally until server history syncs, then merges into read context.
+ */
+
+export class OutboxBuffer {
+  constructor() {
+    this._pending = new Map();
+  }
+
+  track(chatId, { text, receiverId }) {
+    if (!this._pending.has(chatId)) {
+      this._pending.set(chatId, []);
+    }
+    this._pending.get(chatId).push({
+      text,
+      receiverId,
+      timestamp: Date.now()
+    });
+    console.log(`[OutboxBuffer] track: chatId=${chatId}, pending=${this._pending.get(chatId).length}, text="${text.slice(0, 60)}..."`);
+  }
+
+  merge(chatId, history, agentId) {
+    const pending = this._pending.get(chatId);
+    console.log(`[OutboxBuffer] merge: chatId=${chatId}, pending=${pending?.length || 0}, historyLen=${history.length}, agentId=${agentId}`);
+    if (!pending || pending.length === 0) return;
+
+    const matchedIndices = new Set();
+    const remaining = [];
+
+    for (const msg of pending) {
+      const matchIdx = history.findIndex((entry, idx) =>
+        !matchedIndices.has(idx) &&
+        entry.text === msg.text &&
+        entry.sender?.id === agentId
+      );
+
+      if (matchIdx !== -1) {
+        matchedIndices.add(matchIdx);
+      } else {
+        remaining.push(msg);
+      }
+    }
+
+    for (const msg of remaining) {
+      history.push({
+        entryType: 'message',
+        text: msg.text,
+        sender: { id: agentId, type: 'agent' },
+        receiver: { id: msg.receiverId },
+        timestamp: msg.timestamp
+      });
+    }
+
+    console.log(`[OutboxBuffer] merge result: matched=${pending.length - remaining.length}, appended=${remaining.length}, newHistoryLen=${history.length}`);
+
+    if (remaining.length === 0) {
+      this._pending.delete(chatId);
+    } else {
+      this._pending.set(chatId, remaining);
+    }
+  }
+}