@ziggs-ai/agent-sdk 0.1.3

package/src/workflow/motifs.js

@@ -0,0 +1,435 @@
+/**
+ * Motifs — higher-level DSL over the AgentMachine "assembly".
+ *
+ * Each motif returns a Fragment:
+ *   { entry: string, states: { [name]: stateDef } }
+ *
+ * A Fragment's transitions use the sentinel target '__NEXT__' for outbound
+ * edges. `seq(...)` rewrites '__NEXT__' to the next fragment's entry; the
+ * final fragment rewrites to opts.end (default 'idle').
+ *
+ * `compile(shape, { initial, end })` returns a states map ready for
+ * defineAgent.
+ */
+
+const NEXT = '__NEXT__';
+
+// ── Low-level helpers ─────────────────────────────────────────────────────
+
+const prefixState = (prefix, name) => (prefix ? `${prefix}_${name}` : name);
+
+function mapTargets(stateDef, fn) {
+  if (!stateDef.transitions) return stateDef;
+  return {
+    ...stateDef,
+    transitions: stateDef.transitions.map(t =>
+      typeof t === 'string' ? { to: fn(t) } : { ...t, to: fn(t.to) }
+    ),
+  };
+}
+
+function withPrefix(fragment, prefix) {
+  if (!prefix) return fragment;
+  const states = {};
+  for (const [name, def] of Object.entries(fragment.states)) {
+    const rewritten = mapTargets(def, t => (t === NEXT ? NEXT : prefixState(prefix, t)));
+    states[prefixState(prefix, name)] = rewritten;
+  }
+  return { entry: prefixState(prefix, fragment.entry), states };
+}
+
+// ── Service-tier motifs ───────────────────────────────────────────────────
+
+/**
+ * listen() — idle-style park. Routes to __NEXT__ on a delegated task,
+ * otherwise parks waiting for incoming messages that populate ctx flags.
+ */
+export function listen() {
+  return {
+    entry: 'idle',
+    states: {
+      idle: {
+        transitions: [
+          {
+            to: NEXT,
+            when: ctx =>
+              ctx.approval &&
+              ctx.taskAssignment &&
+              (ctx.taskAssignment.state === 'active' ||
+                ctx.taskAssignment.state === 'in-progress') &&
+              !!ctx.taskAssignment.parentTaskId,
+          },
+          { to: 'listening_hold' },
+        ],
+      },
+      listening_hold: {
+        // Placeholder: a paired `propose()` replaces this with the real
+        // listening state. If compiled alone, stays parked.
+        transitions: [{ to: 'idle' }],
+      },
+    },
+  };
+}
+
+/**
+ * propose({ prompt, constraints }) — user-facing listening + approval gate.
+ */
+export function propose({ role, goal, context = '', constraints = '' } = {}) {
+  return {
+    entry: 'listening',
+    states: {
+      listening: {
+        prompt: {
+          role: role ?? 'A helpful assistant',
+          goal: goal ?? 'Understand the user and propose a task for concrete requests.',
+          context,
+          constraints:
+            constraints ||
+            'Respond in the user\'s language. Only propose once per pending request.',
+        },
+        actions: {
+          proposeTask: {
+            prompt: {
+              instruction:
+                'Create a task proposal. Set proposedTo to the human user id from <recipients><users>.',
+              format: '{"description": "...", "proposedTo": "<userId>"}',
+              when: 'The user has a concrete request and there is no pending delegation.',
+            },
+            tool: 'task_make_task',
+          },
+          respondToProposal: {
+            prompt: {
+              instruction: 'Accept or reject a pending delegation directed at you.',
+              when: 'A proposal is pending and directed at you (taskAssignment has parentTaskId).',
+            },
+            tool: 'task_respond_proposal',
+          },
+          sendMessage: {
+            prompt: {
+              instruction: 'Respond directly for greetings or trivial queries.',
+              when: 'The request does not need a task.',
+            },
+          },
+        },
+        transitions: [
+          { to: 'awaitingApproval', when: ctx => ctx.proposal != null },
+          {
+            to: NEXT,
+            when: ctx =>
+              ctx.respondedProposal != null &&
+              ctx.respondedProposal.action !== 'reject',
+          },
+          { to: 'idle', when: ctx => ctx.messageSent || ctx.activeWait },
+        ],
+      },
+      awaitingApproval: {
+        transitions: [
+          { to: NEXT, when: ctx => ctx.approval },
+          { to: 'idle', when: ctx => ctx.rejection },
+          { to: 'listening' },
+        ],
+      },
+    },
+  };
+}
+
+/**
+ * execute({ role, goal, context, constraints, toolHint, askWhen }) —
+ * the "do the work" state. Calls tools, messages user, closes task. If
+ * details are missing, loops through an `ask()`-compatible park state.
+ */
+export function execute({
+  role = 'Executing a task',
+  goal = 'Use the available tools to complete the task, report to the user, then close the task.',
+  context = '',
+  constraints = 'Report results to the user before closing the task. Fail with a clear reason on domain mismatch.',
+  toolHint,
+  name = 'executing',
+} = {}) {
+  const parkName = `${name}_await`;
+  return {
+    entry: name,
+    states: {
+      [name]: {
+        prompt: { role, goal, context, constraints },
+        actions: {
+          ...(toolHint && {
+            runTool: {
+              prompt: {
+                instruction: `Call ${toolHint} to execute the task.`,
+                when: 'You have enough details.',
+              },
+              tool: toolHint,
+            },
+          }),
+          askForDetails: {
+            prompt: {
+              instruction: 'Ask the user (from <recipients><users>) for the missing details.',
+              when: 'The task is underspecified and you have NOT already asked.',
+            },
+          },
+          task_update_task: {
+            prompt: {
+              instruction:
+                'Close the task: status "completed" with a result summary on success, or "failed" with a reason.',
+              when: 'After tool execution you are done or must abandon.',
+            },
+            tool: 'task_update_task',
+          },
+          sendMessage: {
+            prompt: {
+              instruction: 'Send the outcome to the user.',
+              when: 'You have results or need a quick update.',
+            },
+          },
+        },
+        transitions: [
+          { to: NEXT, when: ctx => ctx.taskCompleted || ctx.taskFailed },
+          { to: NEXT, when: ctx => ctx.activeWait },
+          { to: parkName, when: ctx => ctx.messageSent },
+          { to: name, when: ctx => ctx.toolResults?.length > 0 },
+          { to: parkName }, // catch-all park
+        ],
+      },
+      [parkName]: {
+        transitions: [{ to: name }],
+      },
+    },
+  };
+}
+
+// ── Orchestrator motifs ───────────────────────────────────────────────────
+
+/**
+ * plan({ maxItems, label }) — discovery + prepare_agents stage.
+ */
+export function plan({
+  role = 'An orchestrator planning work',
+  goal = 'Identify the steps and specialists needed. Use list_agents then prepare_agents.',
+  context = '',
+  constraints = 'Match agents to steps by domain.',
+  maxItems = 5,
+  name = 'planning',
+} = {}) {
+  return {
+    entry: name,
+    states: {
+      [name]: {
+        prompt: {
+          role,
+          goal,
+          context: context || `Up to ${maxItems} items.`,
+          constraints,
+        },
+        actions: {
+          list_agents: {
+            prompt: {
+              instruction: 'Search for specialists by domain.',
+              when: 'You need to find agents.',
+            },
+            tool: 'list_agents',
+          },
+          prepare_agents: {
+            prompt: {
+              instruction: 'Wake the chosen agents.',
+              when: 'You have identified all agents needed.',
+            },
+            tool: 'prepare_agents',
+          },
+          sendMessage: {
+            prompt: {
+              instruction: 'Explain the plan to the user.',
+              when: 'You have a plan ready.',
+            },
+          },
+        },
+        transitions: [
+          {
+            to: NEXT,
+            when: ctx => ctx.toolResults?.some(r => r.name === 'prepare_agents'),
+          },
+          { to: name, when: ctx => ctx.toolResults?.length > 0 },
+          { to: NEXT, when: ctx => ctx.messageSent },
+        ],
+      },
+    },
+  };
+}
+
+/**
+ * dispatch({ parallel, label }) — send subtasks to workers.
+ */
+export function dispatch({
+  parallel = false,
+  role,
+  goal,
+  context = '',
+  constraints,
+  name = parallel ? 'mapping' : 'delegating',
+} = {}) {
+  return {
+    entry: name,
+    states: {
+      [name]: {
+        prompt: {
+          role: role ?? (parallel ? 'Dispatching parallel work' : 'Executing steps sequentially'),
+          goal: goal ?? (parallel
+            ? 'Send all chunks in a single dispatch_to_agents call.'
+            : 'Send the current step. Include prior results as context.'),
+          context,
+          constraints: constraints ?? (parallel
+            ? 'Dispatch all in one call. Each chunk must stand alone.'
+            : 'One step at a time. Include previous step outputs.'),
+        },
+        actions: {
+          dispatch_to_agents: {
+            prompt: {
+              instruction: parallel
+                ? 'Send all chunks to their agents in parallel.'
+                : 'Send the current step to the specialist.',
+              when: 'Ready to execute.',
+            },
+            tool: 'dispatch_to_agents',
+          },
+          sendMessage: {
+            prompt: { instruction: 'Update the user on progress.', when: 'A step completed.' },
+          },
+        },
+        transitions: [
+          {
+            to: NEXT,
+            when: ctx => ctx.toolResults?.some(r => r.name === 'dispatch_to_agents'),
+          },
+          { to: NEXT },
+        ],
+      },
+    },
+  };
+}
+
+/**
+ * awaitSubtasks({ mode }) — park until subtaskResult(s) arrive.
+ * mode='one' (pipeline step), mode='all' (map-reduce / voting).
+ */
+export function awaitSubtasks({ mode = 'one', name = 'awaitingSubtasks' } = {}) {
+  return {
+    entry: name,
+    states: {
+      [name]: {
+        transitions: [
+          { to: NEXT, when: ctx => ctx.subtaskResult },
+          { to: NEXT, when: ctx => ctx.subtaskFailed },
+          ...(mode === 'all'
+            ? [{ to: name }]
+            : [{ to: NEXT }]),
+        ],
+      },
+    },
+  };
+}
+
+/**
+ * synthesize({ role, goal }) — merge + close task.
+ */
+export function synthesize({
+  role = 'Synthesizing results',
+  goal = 'Merge results into a coherent final answer, present to user, then close the task.',
+  context = '',
+  constraints = 'Synthesize — do not concatenate. Dedupe. Resolve conflicts explicitly.',
+  name = 'synthesizing',
+} = {}) {
+  return {
+    entry: name,
+    states: {
+      [name]: {
+        prompt: { role, goal, context, constraints },
+        actions: {
+          sendMessage: {
+            prompt: {
+              instruction: 'Present the final result to the user.',
+              when: 'You have everything merged.',
+            },
+          },
+          task_update_task: {
+            prompt: {
+              instruction: 'Close the task with the final result.',
+              when: 'After presenting the result.',
+            },
+            tool: 'task_update_task',
+          },
+        },
+        transitions: [
+          { to: NEXT, when: ctx => ctx.taskCompleted || ctx.taskFailed },
+          { to: NEXT, when: ctx => ctx.messageSent || ctx.activeWait },
+        ],
+      },
+    },
+  };
+}
+
+// ── Composition ───────────────────────────────────────────────────────────
+
+/**
+ * seq(...fragments) — chain fragments: each fragment's __NEXT__ rewrites to
+ * the next fragment's entry. Last fragment's __NEXT__ is left unresolved
+ * (compile() will rewrite to `end`).
+ */
+export function seq(...fragments) {
+  if (!fragments.length) throw new Error('seq() needs at least one fragment');
+  const states = {};
+  for (let i = 0; i < fragments.length; i++) {
+    const frag = fragments[i];
+    const nextEntry = i + 1 < fragments.length ? fragments[i + 1].entry : NEXT;
+    for (const [name, def] of Object.entries(frag.states)) {
+      states[name] = mapTargets(def, t => (t === NEXT ? nextEntry : t));
+    }
+  }
+  return { entry: fragments[0].entry, states };
+}
+
+/**
+ * loop(n, ...fragments) — repeat a sub-sequence n times. Each iteration is
+ * state-prefixed so states don't collide. Exit after iteration n.
+ */
+export function loop(n, ...fragments) {
+  if (n < 1) throw new Error('loop() needs n >= 1');
+  const iterations = [];
+  for (let i = 0; i < n; i++) {
+    iterations.push(withPrefix(seq(...fragments), `i${i}`));
+  }
+  return seq(...iterations);
+}
+
+/**
+ * compile(fragment, { end }) — rewrite trailing __NEXT__ to `end` (default
+ * 'idle') and return { initial, states }.
+ */
+export function compile(fragment, { end = 'idle' } = {}) {
+  const states = {};
+  for (const [name, def] of Object.entries(fragment.states)) {
+    states[name] = mapTargets(def, t => (t === NEXT ? end : t));
+  }
+  // Ensure an `idle` terminal exists if `end` is 'idle' and absent.
+  if (end === 'idle' && !states.idle) {
+    states.idle = { transitions: [{ to: fragment.entry }] };
+  }
+  return { initial: 'idle', states };
+}
+
+// Convenience: the ubiquitous "service agent" shape in one call.
+export function service({
+  role,
+  goal,
+  context,
+  constraints,
+  toolHint,
+  workName = 'executing',
+  proposeContext,
+  proposeConstraints,
+} = {}) {
+  return seq(
+    listen(),
+    propose({ role, goal, context: proposeContext ?? context, constraints: proposeConstraints }),
+    execute({ role, goal: undefined, context, constraints, toolHint, name: workName }),
+  );
+}

package/src/ziggs/runtime.js

@@ -0,0 +1,192 @@
+import { Agent } from '../agent/Agent.js';
+import { ToolManager } from '../tools/ToolManager.js';
+import { TASK_PROTOCOL_TOOLS } from '../tasks/taskProtocolTools.js';
+import { OpenAIAdapter } from '../adapters/OpenAIAdapter.js';
+import { WebSocketClient, ContextReader, ContextWriter, TelemetryClient } from '@ziggs-ai/api-client';
+import { PromptBuilder } from '../cognition/PromptBuilder.js';
+import { TaskService } from '../tasks/TaskService.js';
+import { ConnectionPool } from '../ConnectionPool.js';
+
+function createToolManager(options) {
+  const toolManager = new ToolManager();
+  const userTools = options.tools || options.services?.tools || [];
+  const taskTools = options.taskTools !== false ? TASK_PROTOCOL_TOOLS : [];
+  toolManager.registerAll([...taskTools, ...(Array.isArray(userTools) ? userTools : [])]);
+  return toolManager;
+}
+
+function createServices(options) {
+  const toolManager = createToolManager(options);
+  const llm = new OpenAIAdapter({ key: options.openaiKey, model: options.services?.llm?.model || options.model });
+  const contextReader = new ContextReader(options.operatorKey, options.agentId);
+  const contextWriter = new ContextWriter(options.operatorKey, options.agentId);
+  const promptBuilder = new PromptBuilder({ description: options.description, specialization: options.specialization });
+  const taskService = new TaskService(options.operatorKey, options.agentId);
+  const telemetryClient = new TelemetryClient(options.operatorKey, options.agentId);
+  return { toolManager, llm, contextReader, contextWriter, promptBuilder, taskService, telemetryClient };
+}
+
+export class ZiggsAgent {
+  constructor(options = {}) {
+    this.options = {
+      openaiKey: options.openaiKey,
+      model: options.model || options.services?.llm?.model || 'gpt-4o-mini',
+      operatorKey: options.operatorKey || process.env.ZIGGS_OPERATOR_KEY || null,
+      agentId: options.agentId || null,
+      name: options.name || null,
+      wsUrl: options.wsUrl,
+      description: options.description || 'A helpful assistant',
+      specialization: options.specialization || null,
+      tools: options.tools || [],
+      taskTools: options.taskTools,
+      states: options.states || null,
+      initial: options.initial || null,
+      services: options.services || null,
+      workflow: options.workflow || null,
+    };
+    this._validate();
+    this._setup();
+  }
+
+  _validate() {
+    if (!this.options.openaiKey) throw new Error('openaiKey is required');
+    if (!this.options.operatorKey) {
+      throw new Error(
+        'operatorKey is required — pass { operatorKey } or set ZIGGS_OPERATOR_KEY. ' +
+        'Mint one via Agents/scripts/mint-operator-key.js (scope: agents:impersonate).',
+      );
+    }
+    if (!this.options.agentId) {
+      throw new Error('agentId is required — every agent must declare its stable kebab-case agentId in its config.');
+    }
+  }
+
+  _setup() {
+    const services = createServices(this.options);
+    this.toolManager = services.toolManager;
+    this.llm = services.llm;
+
+    this.wsClient = new WebSocketClient({
+      wsUrl: this.options.wsUrl,
+      operatorKey: this.options.operatorKey,
+      agentId: this.options.agentId,
+      label: this.options.name || 'agent',
+      name: this.options.name || null,
+    });
+
+    const messageSender = (message, receiverId, chatId) => {
+      this.wsClient.sendResponse(message, { receiverId, chatId });
+    };
+
+    let definition = this.options.workflow;
+    if (!definition && this.options.states) {
+      definition = {
+        id: this.options.agentId,
+        description: this.options.description,
+        initial: this.options.initial || 'idle',
+        states: this.options.states,
+      };
+    }
+    if (!definition?.states) {
+      throw new Error('ZiggsAgent: states definition or workflow is required');
+    }
+
+    this.agent = new Agent({
+      llm: services.llm,
+      toolManager: services.toolManager,
+      contextReader: services.contextReader,
+      contextWriter: services.contextWriter,
+      taskService: services.taskService,
+      messageSender,
+      promptBuilder: services.promptBuilder,
+      operatorKey: this.options.operatorKey,
+      agentId: this.options.agentId,
+      workflow: definition,
+    });
+
+    this.wsClient.setMessageHandler(async (text, metadata) => {
+      await this.agent.handleMessage(text, metadata);
+    });
+  }
+
+  connect() { this.wsClient.connect(); return this; }
+  connectAsync(timeout) { return this.wsClient.connectAsync(timeout); }
+  disconnect() { this.wsClient.disconnect(); }
+  registerTool(tool) { return this.toolManager.register(tool); }
+  async handleMessage(text, metadata = {}) { return await this.agent.handleMessage(text, metadata); }
+  isConnected() { return this.wsClient.isConnected(); }
+}
+
+/**
+ * Factory for a single agent or a fleet.
+ *
+ *   createAgent(config)         → ZiggsAgent       (hello-world / single agent)
+ *   createAgent([cfg1, cfg2])   → ConnectionPool   (any fleet — lazy, one control socket)
+ *
+ * Pool agents stay disconnected until `pool.wake(id)` — or until the backend
+ * pushes a `launcher:wake` frame over the control socket opened by
+ * `pool.startControl({ wsUrl, operatorKey })`. For the full boot sequence
+ * (control socket, health server, orchestrator, SIGTERM), use `runLauncher`.
+ *
+ * @param {object|object[]} options
+ * @param {object}  [opts]
+ * @param {object}  [opts.poolOptions]  Forwarded to `new ConnectionPool(...)` when options is an array
+ */
+export function createAgent(options = {}, { poolOptions } = {}) {
+  if (Array.isArray(options)) {
+    const pool = new ConnectionPool(poolOptions);
+    pool.register(options);
+    return pool;
+  }
+  return new ZiggsAgent(options);
+}
+
+const DEFAULT_WAIT_PROMPT = Object.freeze({
+  instruction: 'Do nothing - wait for the next event.',
+  when: 'No action is needed, you are waiting for external input, or you should pause without repeating yourself.',
+  format: '{"thought": "...", "action": "wait"}',
+});
+
+function injectWaitActions(states, initial) {
+  for (const [, stateDef] of Object.entries(states)) {
+    if (!stateDef.prompt || !stateDef.actions) continue;
+    if (!stateDef.actions.wait) {
+      stateDef.actions.wait = { prompt: { ...DEFAULT_WAIT_PROMPT } };
+    }
+    if (Array.isArray(stateDef.transitions)) {
+      const checksActiveWait = stateDef.transitions.some(
+        d => typeof d !== 'string' && d.when && /activeWait/.test(d.when.toString())
+      );
+      if (!checksActiveWait) {
+        stateDef.transitions.push({ to: initial, when: ctx => ctx.activeWait });
+      }
+    }
+  }
+}
+
+export function defineAgent({
+  agentId, description, specialization, services: agentServices,
+  initial, states, tools = [], operatorKey, ...rest
+}) {
+  if (!agentId) throw new Error('[defineAgent] agentId is required (stable kebab-case, same id registered with backend)');
+  if (!description) throw new Error('[defineAgent] description is required');
+  if (!states) throw new Error('[defineAgent] states is required');
+  if (!initial) throw new Error('[defineAgent] initial state is required');
+
+  injectWaitActions(states, initial);
+
+  return {
+    openaiKey: process.env.OPENAI_API_KEY,
+    ...(operatorKey && { operatorKey }),
+    agentId,
+    description,
+    ...(specialization && { specialization }),
+    tools: [...tools, ...(agentServices?.tools || [])],
+    model: agentServices?.llm?.model || process.env.OPENAI_MODEL || 'gpt-4o-mini',
+    workflow: { id: agentId, description, initial, states },
+    services: agentServices,
+    ...rest,
+  };
+}
+
+export default ZiggsAgent;