@ziggs-ai/agent-sdk 0.1.3 → 0.1.4

package/src/workflow/motifs.js

@@ -1,435 +0,0 @@
-/**
- * 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

@@ -1,192 +0,0 @@
-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;