@ziggs-ai/agent-sdk 0.1.3

package/src/tasks/taskProtocolTools.js

@@ -0,0 +1,87 @@
+import { defineTool } from '../tools/defineTool.js';
+import { executeTaskPayload } from './taskProtocolRunner.js';
+
+/**
+ * Built-in task protocol tools — handlers call TaskService via `executeTaskPayload`.
+ * Registered like any other tool; runTurn runs them through ToolManager and emits
+ * `tool_result`. Context updates come from `buildContextUpdates` when `tool` is a task protocol name.
+ */
+
+function handlerFor(operation) {
+  return async (args, ctx) => {
+    const taskService = ctx.taskService;
+    if (!taskService) {
+      throw new Error('taskService missing from tool context (expected when running under Agent)');
+    }
+    const chatId = ctx.chatId;
+    const agents = ctx.agents || [];
+    const task = { operation, ...args };
+    const result = await executeTaskPayload(taskService, task, chatId, agents, ctx);
+    if (result == null) throw new Error(`Task operation ${operation} returned no result`);
+    return result;
+  };
+}
+
+export const taskMakeTaskTool = defineTool(
+  'task_make_task',
+  {
+    description: { type: 'string', required: true },
+    proposedTo: 'string',
+    executorId: 'string',
+    parentTaskId: 'string',
+    payerId: 'string',
+    contract: { type: 'object' },
+    perspective: { type: 'object' },
+  },
+  handlerFor('make-task')
+);
+
+export const taskMakeSubTasksTool = defineTool(
+  'task_make_sub_tasks',
+  {
+    description: { type: 'string', required: true },
+    subtasks: ['string'],
+    contract: { type: 'object' },
+    perspective: { type: 'object' },
+    parentTaskId: 'string',
+  },
+  handlerFor('make-sub-tasks')
+);
+
+export const taskUpdateTaskTool = defineTool(
+  'task_update_task',
+  {
+    taskId: { type: 'string', required: true },
+    status: { type: 'string', required: true, enum: ['completed', 'failed', 'cancelled'] },
+    result: 'string',
+  },
+  handlerFor('update-task')
+);
+
+export const taskRespondProposalTool = defineTool(
+  'task_respond_proposal',
+  {
+    taskId: { type: 'string', required: true },
+    action: { type: 'string', required: true },
+  },
+  handlerFor('respond-proposal')
+);
+
+export const taskUpdatePlanStepTool = defineTool(
+  'task_update_plan_step',
+  {
+    taskId: { type: 'string', required: true },
+    stepId: { type: 'string', required: true },
+    status: { type: 'string', required: true },
+    result: 'string',
+  },
+  handlerFor('update-plan-step')
+);
+
+export const TASK_PROTOCOL_TOOLS = [
+  taskMakeTaskTool,
+  taskMakeSubTasksTool,
+  taskUpdateTaskTool,
+  taskRespondProposalTool,
+  taskUpdatePlanStepTool,
+];

package/src/tools/ToolManager.js

@@ -0,0 +1,79 @@
+import Ajv from 'ajv';
+import { ToolProvider } from './ToolProvider.js';
+
+const ajv = new Ajv({ allErrors: true, strict: false });
+
+export class ToolManager extends ToolProvider {
+  constructor() {
+    super();
+    this.tools = new Map();
+  }
+
+  register(tool) {
+    if (!tool?.schema) {
+      throw new Error('Tool must have a schema');
+    }
+    if (typeof tool.handler !== 'function') {
+      throw new Error('Tool must have a handler function');
+    }
+
+    const name = tool.schema.function?.name || tool.schema.name;
+    if (!name) {
+      throw new Error('Tool schema must have a name');
+    }
+
+    this.tools.set(name, tool);
+    return name;
+  }
+
+  registerAll(tools = []) {
+    for (const tool of tools) {
+      this.register(tool);
+    }
+  }
+
+  async getAvailableTools() {
+    return Array.from(this.tools.values());
+  }
+
+  getTool(name) {
+    const normalized = this._normalizeName(name);
+    return this.tools.get(normalized) || null;
+  }
+
+  async executeTool(name, args = {}, context = {}) {
+    const normalized = this._normalizeName(name);
+    const tool = this.tools.get(normalized);
+
+    if (!tool) {
+      const err = new Error(`Tool not found: ${name}`);
+      err.type = 'tool_not_found';
+      throw err;
+    }
+
+    this._validateArgs(tool, args);
+
+    try {
+      return await tool.handler(args, context);
+    } catch (error) {
+      const err = new Error(`Tool "${name}" failed: ${error.message}`);
+      err.type = 'tool_error';
+      err.cause = error;
+      throw err;
+    }
+  }
+
+  _validateArgs(tool, args) {
+    const parameters = tool.schema.function?.parameters || tool.schema.parameters;
+    if (!parameters) return;
+
+    const validate = ajv.compile(parameters);
+    if (!validate(args)) {
+      const name = tool.schema.function?.name || tool.schema.name;
+      const err = new Error(`Invalid args for "${name}": ${ajv.errorsText(validate.errors)}`);
+      err.type = 'validation_error';
+      err.data = { errors: validate.errors };
+      throw err;
+    }
+  }
+}

package/src/tools/ToolProvider.js

@@ -0,0 +1,29 @@
+/**
+ * Base class for tool providers.
+ * ToolManager and any custom providers extend this.
+ */
+export class ToolProvider {
+  async getAvailableTools() {
+    throw new Error('getAvailableTools must be implemented');
+  }
+
+  async executeTool(name, args = {}, context = {}) {
+    throw new Error('executeTool must be implemented');
+  }
+
+  getTool(name) {
+    throw new Error('getTool must be implemented');
+  }
+
+  _normalizeName(name) {
+    if (!name || typeof name !== 'string') return name;
+
+    const prefixes = ['functions.', 'tools.', 'function.', 'tool.'];
+    for (const prefix of prefixes) {
+      if (name.startsWith(prefix)) {
+        return name.substring(prefix.length);
+      }
+    }
+    return name;
+  }
+}

package/src/tools/defineTool.js

@@ -0,0 +1,82 @@
+const PRIMITIVES = new Set(['string', 'number', 'boolean', 'integer']);
+
+function convertField(value) {
+  if (typeof value === 'string') {
+    if (!PRIMITIVES.has(value)) throw new Error(`Unknown type shorthand: "${value}"`);
+    return { schema: { type: value }, required: false };
+  }
+
+  if (Array.isArray(value)) {
+    if (value.length !== 1) throw new Error('Array shorthand must have exactly one element describing the item type');
+    const inner = value[0];
+    if (typeof inner === 'string') {
+      return { schema: { type: 'array', items: { type: inner } }, required: false };
+    }
+    const obj = convertObject(inner);
+    return { schema: { type: 'array', items: obj }, required: false };
+  }
+
+  if (typeof value === 'object' && value !== null) {
+    if (value.type && PRIMITIVES.has(value.type)) {
+      const { required: isReq, ...rest } = value;
+      return { schema: rest, required: !!isReq };
+    }
+    if (value.type === 'array') {
+      const { required: isReq, ...rest } = value;
+      return { schema: rest, required: !!isReq };
+    }
+    if (value.type === 'object') {
+      const { required: isReq, ...rest } = value;
+      return { schema: rest, required: !!isReq };
+    }
+    const obj = convertObject(value);
+    return { schema: obj, required: false };
+  }
+
+  throw new Error(`Cannot convert field value: ${JSON.stringify(value)}`);
+}
+
+function convertObject(fields) {
+  const properties = {};
+  const required = [];
+
+  for (const [key, value] of Object.entries(fields)) {
+    if (key === 'required') continue;
+    const { schema, required: isReq } = convertField(value);
+    properties[key] = schema;
+    if (isReq) required.push(key);
+  }
+
+  const result = { type: 'object', properties };
+  if (required.length > 0) result.required = required;
+  return result;
+}
+
+/**
+ * Concise tool definition that produces the { schema, handler } format
+ * expected by ToolManager.register().
+ *
+ *   defineTool('my_tool', {
+ *     query: { type: 'string', required: true },
+ *     limit: 'number',
+ *     tags:  ['string'],
+ *     nested: [{ name: { type: 'string', required: true }, score: 'number' }],
+ *   }, async (args, ctx) => { ... })
+ *
+ * @param {object} [options]
+ * @param {boolean} [options.echoUserSummaryOnSuccess] — When true, runTurn sends `result.message`
+ *   to the primary user if the model did not already send chat this turn (opt-in per tool).
+ */
+export function defineTool(name, params, handler, options = {}) {
+  if (!name || typeof name !== 'string') throw new Error('defineTool: name is required');
+  if (!handler || typeof handler !== 'function') throw new Error('defineTool: handler function is required');
+
+  const parameters = convertObject(params || {});
+  const echoUserSummaryOnSuccess = options.echoUserSummaryOnSuccess === true;
+
+  return {
+    schema: { type: 'function', function: { name, parameters } },
+    handler,
+    ...(echoUserSummaryOnSuccess ? { echoUserSummaryOnSuccess: true } : {}),
+  };
+}

package/src/tools/index.js

@@ -0,0 +1,11 @@
+export { ToolManager } from './ToolManager.js';
+export { ToolProvider } from './ToolProvider.js';
+export { defineTool } from './defineTool.js';
+export { TASK_PROTOCOL_TOOLS } from '../tasks/taskProtocolTools.js';
+export {
+  TASK_PROTOCOL_TOOL_NAMES,
+  TASK_PROTOCOL_TOOL_TO_OPERATION,
+  mapTaskProtocolToolToOperation,
+  isTaskProtocolToolName,
+} from '../tasks/taskProtocolRegistry.js';
+export { executeTaskPayload } from '../tasks/taskProtocolRunner.js';

package/src/utils/jsonExtractor.js

@@ -0,0 +1,139 @@
+export function extractJSON(content) {
+  if (!content || typeof content !== 'string') return '';
+
+  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();
+
+  // Don't match // inside URLs (e.g. https://...); use (?<!:) to skip ://
+  content = content.replace(/(?<!:)\/\/.*$/gm, '');
+  content = content.replace(/\/\*[\s\S]*?\*\//g, '');
+
+  content = content.replace(/,(\s*[}\]])/g, '$1');
+
+  return content;
+}
+
+function repairJsonStrings(jsonText) {
+  if (!jsonText || typeof jsonText !== 'string') return jsonText;
+
+  // Valid JSON escape characters after backslash
+  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;
+    }
+
+    // Inside a string
+    if (ch === '\\') {
+      const next = jsonText[i + 1];
+      if (next && validEscapes.has(next)) {
+        // Valid escape sequence - keep as-is
+        out += ch;
+      } else {
+        // Invalid escape (e.g., "\ " or "\x") - escape the backslash itself
+        out += '\\\\';
+      }
+      continue;
+    }
+
+    if (ch === '"') {
+      inString = false;
+      out += ch;
+      continue;
+    }
+
+    // JSON does not allow raw newlines in strings; repair them.
+    if (ch === '\n') {
+      out += '\\n';
+      continue;
+    }
+    if (ch === '\r') {
+      out += '\\r';
+      continue;
+    }
+
+    out += ch;
+  }
+
+  return out;
+}
+
+export function safeParseJSON(content, fallback = null) {
+  try {
+    const extracted = extractJSON(content);
+    if (!extracted || extracted.trim().length === 0) {
+      throw new Error('Empty JSON content');
+    }
+    try {
+      return JSON.parse(extracted);
+    } catch (e) {
+      // Common LLM failure modes: raw newlines, invalid escape sequences
+      const repaired = repairJsonStrings(extracted);
+      return JSON.parse(repaired);
+    }
+  } catch (error) {
+    console.error(`❌ [JSON Extractor] Error parsing JSON:`, content);
+    return fallback || null;
+  }
+}

package/src/workflow/AgentMachine.js

@@ -0,0 +1,250 @@
+/**
+ * Interprets workflow definitions: parked states (transitions only) and thinking states (prompt + actions + transitions).
+ */
+
+import { classifyIncomingEvent } from '../context/classifyEnvelope.js';
+import { CONTEXT_RESET } from '../context/applyEffects.js';
+
+export class AgentMachine {
+  constructor({ definition, executionCore, services, input }) {
+    this.definition = definition;
+    this.executionCore = executionCore;
+    this.state = definition.initial;
+    this.status = 'active';
+    this._running = false;
+    this._subscribers = new Set();
+
+    this.context = {
+      chatId: input?.chatId ?? null,
+      laneKey: input?.laneKey ?? null,
+      ownAgentId: input?.ownAgentId ?? null,
+      incomingEvent: null,
+      activeTaskId: null,
+      pendingProposalId: null,
+      perspectiveId: null,
+      delegatedTaskIds: [],
+      ...CONTEXT_RESET,
+      _services: services || {},
+      _definition: definition,
+    };
+  }
+
+  getSnapshot() {
+    return { value: this.state, context: this.context, status: this.status };
+  }
+
+  get isParked() {
+    if (this._running) return false;
+    const sd = this.definition.states[this.state];
+    return !(sd?.prompt && sd?.actions);
+  }
+
+  subscribe(fn) {
+    this._subscribers.add(fn);
+    return { unsubscribe: () => this._subscribers.delete(fn) };
+  }
+
+  send(event) {
+    if (this.status !== 'active') return Promise.resolve();
+    this._storeEvent(event);
+    this._classifyEvent(event);
+    const target = this._evaluateTransitions();
+    if (target) return this._transition(target);
+    return Promise.resolve();
+  }
+
+  async _transition(target) {
+    this.state = target;
+    this._notify();
+
+    const sd = this.definition.states[this.state];
+    if (!sd?.prompt || !sd?.actions) return; // parked — done
+
+    // Thinking state: run LLM
+    this._running = true;
+    try {
+      const result = await this.executionCore({
+        stateId: this.state,
+        statePrompt: sd.prompt,
+        actions: sd.actions,
+        chatId: this.context.chatId,
+        incomingEvent: this.context.incomingEvent,
+        _services: this.context._services,
+        _definition: this.context._definition,
+        machineContext: this.context,
+      });
+
+      const updates = result?.contextUpdates || {};
+      Object.assign(this.context, CONTEXT_RESET, updates, extractPersistentUpdates(this.context, updates));
+      this._running = false;
+      this._notify();
+
+      const next = this._evaluateTransitions();
+      if (next) await this._transition(next);
+    } catch (error) {
+      console.error(`[workflow] state=${this.state} error:`, error.message);
+      Object.assign(this.context, CONTEXT_RESET, { lastError: error.message || String(error) });
+      this._running = false;
+      this._notify();
+
+      // Catch-all: find last unconditional transition as fallback
+      if (sd.transitions) {
+        const catchall = [...sd.transitions].reverse().find(rule => {
+          if (typeof rule === 'string') return true;
+          return !rule.when;
+        });
+        if (catchall) {
+          const fallback = typeof catchall === 'string' ? resolveTarget(catchall) : resolveTarget(catchall.to);
+          await this._transition(fallback);
+        }
+      }
+    }
+  }
+
+  _evaluateTransitions() {
+    const sd = this.definition.states[this.state];
+    if (!sd?.transitions) return null;
+    for (const rule of sd.transitions) {
+      if (typeof rule === 'string') return resolveTarget(rule);
+      const { to, when } = rule;
+      if (!when || when(this.context)) return resolveTarget(to);
+    }
+    return null;
+  }
+
+  _storeEvent(event) {
+    if (event.event !== undefined) this.context.incomingEvent = event.event;
+    if (event.chatId != null) this.context.chatId = event.chatId;
+    if (event.laneKey != null) this.context.laneKey = event.laneKey;
+    if (event.ownAgentId != null) this.context.ownAgentId = event.ownAgentId;
+  }
+
+  _classifyEvent(event) {
+    const flags = classifyIncomingEvent(event.event, this.context.ownAgentId);
+
+    // Delegated-subtask awareness: if a task_result wasn't recognised as
+    // relevant by the generic check but its taskId IS one we delegated,
+    // promote it so the supervising → evaluatingResult transition fires.
+    if (!flags.subtaskResult && event.event?.type === 'task_result' && event.event?.result?.taskId) {
+      const delegated = this.context.delegatedTaskIds || [];
+      if (delegated.includes(event.event.result.taskId)) {
+        const result = event.event.result;
+        flags.subtaskResult = result;
+        if (result.state === 'failed') flags.subtaskFailed = true;
+      }
+    }
+
+    Object.assign(this.context, CONTEXT_RESET, flags, extractPersistentFromEvent(this.context, flags));
+    applyOrchestrationChainProgress(this.context, flags);
+    // Avoid re-entering evaluatingResult on the same completed subtask after handing off to the next specialist.
+    if (this.context.orchestrationContinueChain) {
+      this.context.subtaskResult = null;
+      this.context.subtaskFailed = false;
+    }
+  }
+
+  _notify() {
+    const snapshot = this.getSnapshot();
+    for (const fn of this._subscribers) {
+      try { fn(snapshot); } catch {}
+    }
+  }
+}
+
+function resolveTarget(target) {
+  if (!target || typeof target !== 'string') return target;
+  return target.startsWith('#') ? target.slice(1) : target;
+}
+
+function extractPersistentUpdates(ctx, updates) {
+  const p = {};
+  if (updates.proposal?.taskId) p.pendingProposalId = updates.proposal.taskId;
+  // Collect all delegated task IDs — handles both single and batch parallel delegation
+  const newIds = updates._delegatedTaskIds?.length
+    ? updates._delegatedTaskIds
+    : updates.delegatedTask?.taskId ? [updates.delegatedTask.taskId] : [];
+  if (newIds.length > 0) {
+    const existing = ctx.delegatedTaskIds || [];
+    const merged = [...existing];
+    for (const id of newIds) { if (!merged.includes(id)) merged.push(id); }
+    p.delegatedTaskIds = merged;
+    p.orchestrationContinueChain = false;
+  }
+  if (updates.taskCompleted || updates.taskFailed) {
+    p.activeTaskId = null;
+    p.pendingProposalId = null;
+    p.perspectiveId = null;
+    p.orchestrationSpecialistAgentId = null;
+    p.orchestrationSpecialistAgentIds = [];
+    p.orchestrationActiveStepIndex = 0;
+    p.orchestrationContinueChain = false;
+  } else {
+    const sid = ctx.orchestrationSpecialistAgentId;
+    if (typeof sid === 'string' && sid.length > 0) {
+      p.orchestrationSpecialistAgentId = sid;
+    }
+  }
+  return p;
+}
+
+function normalizeSpecialistIdList(contract) {
+  if (!contract || typeof contract !== 'object') return [];
+  const raw = contract.specialistAgentIds;
+  const ids = [];
+  if (Array.isArray(raw)) {
+    for (const id of raw) {
+      if (typeof id === 'string' && id.length > 0 && !ids.includes(id)) ids.push(id);
+    }
+  }
+  const single = contract.specialistAgentId;
+  if (ids.length === 0 && typeof single === 'string' && single.length > 0) {
+    ids.push(single);
+  }
+  return ids;
+}
+
+function extractPersistentFromEvent(ctx, flags) {
+  const p = {};
+  if (flags.approval) {
+    const t = flags.taskAssignment || {};
+    const tid =
+      t.taskId ||
+      t.id ||
+      (t._id != null ? String(t._id) : null) ||
+      ctx.pendingProposalId;
+    if (tid) {
+      p.activeTaskId = tid;
+      p.pendingProposalId = null;
+      p.perspectiveId = t.perspective?.ownerChatId || null;
+    }
+    const contract = t.contract && typeof t.contract === 'object' ? t.contract : null;
+    const ids = normalizeSpecialistIdList(contract);
+    if (ids.length > 0) {
+      p.orchestrationSpecialistAgentIds = ids;
+      p.orchestrationSpecialistAgentId = ids[0];
+      p.orchestrationActiveStepIndex = 0;
+    }
+  }
+  if (flags.rejection) {
+    p.pendingProposalId = null;
+    p.orchestrationSpecialistAgentIds = [];
+    p.orchestrationActiveStepIndex = 0;
+    p.orchestrationSpecialistAgentId = null;
+  }
+  return p;
+}
+
+/**
+ * After a delegated subtask succeeds, advance multi-specialist orchestration so the next agent can run.
+ */
+function applyOrchestrationChainProgress(ctx, flags) {
+  ctx.orchestrationContinueChain = false;
+  if (!flags.subtaskResult || flags.subtaskFailed) return;
+  const ids = ctx.orchestrationSpecialistAgentIds;
+  if (!Array.isArray(ids) || ids.length <= 1) return;
+  const step = typeof ctx.orchestrationActiveStepIndex === 'number' ? ctx.orchestrationActiveStepIndex : 0;
+  if (step + 1 >= ids.length) return;
+  ctx.orchestrationActiveStepIndex = step + 1;
+  ctx.orchestrationSpecialistAgentId = ids[step + 1];
+  ctx.orchestrationContinueChain = true;
+}