@ziggs-ai/agent-sdk 0.1.3

package/src/tasks/TaskService.js

@@ -0,0 +1,247 @@
+import {
+  createTask as apiCreateTask,
+  updateTaskState,
+  updatePlanStep as apiUpdatePlanStep,
+  proposeToDoWork as apiProposeToDoWork,
+  delegateToAgent as apiDelegateToAgent,
+  assignTask as apiAssignTask,
+  respondToProposal as apiRespondToProposal,
+  claimLedgerTask as apiClaimLedgerTask
+} from '@ziggs-ai/api-client';
+
+/** @typedef {import('./taskCore.js').Task} Task */
+/** @typedef {import('./taskCore.js').TaskWithFlags} TaskWithFlags */
+/** @typedef {import('./taskCore.js').TaskContract} TaskContract */
+/** @typedef {import('./taskCore.js').TaskPerspective} TaskPerspective */
+
+function safeJsonStringify(value) {
+  if (value === null || value === undefined) return value;
+  if (typeof value === 'string') return value;
+  if (typeof value !== 'object') return String(value);
+
+  const seen = new WeakSet();
+  try {
+    return JSON.stringify(
+      value,
+      (key, val) => {
+        if (typeof val === 'object' && val !== null) {
+          if (seen.has(val)) return '[Circular]';
+          seen.add(val);
+        }
+        return val;
+      },
+      2
+    );
+  } catch {
+    return String(value);
+  }
+}
+
+/**
+ * TaskService — thin wrapper over API client.
+ *
+ * Methods accept a single `payload` object that is forwarded to the API client
+ * with minimal mutation. The payload shape matches the backend DTOs directly
+ * so callers (taskProtocolRunner) can pass the LLM-produced args through.
+ *
+ * All methods return a {@link Task} or {@link TaskWithFlags} — the same shape
+ * the backend persists in MongoDB.
+ */
+export class TaskService {
+  constructor(operatorKey, agentId) {
+    if (!operatorKey) {
+      throw new Error('TaskService: operatorKey is required');
+    }
+    if (!agentId) {
+      throw new Error('TaskService: agentId is required (operator-token impersonation)');
+    }
+    this.creds = { operatorKey, agentId };
+  }
+
+  /**
+   * Propose work to a user or agent for approval.
+   * Creates a task in state='proposal' with proposal.status='pending'.
+   *
+   * @param {Object} payload
+   * @param {string}            payload.description
+   * @param {string}            payload.proposedTo     - userId or agentId to approve
+   * @param {string}            payload.chatId
+   * @param {TaskContract}      [payload.contract]
+   * @param {TaskPerspective}   [payload.perspective]
+   * @param {string}            [payload.parentTaskId]
+   * @param {string}            [payload.payerId]
+   * @returns {Promise<TaskWithFlags>}
+   */
+  async proposeToDoWork(payload) {
+    try {
+      const result = await apiProposeToDoWork(payload, this.creds);
+      console.log(`✅ Proposal created (you do the work): ${result?.taskId || 'unknown'}`);
+      return result;
+    } catch (error) {
+      console.error(`❌ Proposal creation failed: ${error.message}`);
+      throw error;
+    }
+  }
+
+  /**
+   * Assign task directly (no proposal step). Requires parentTaskId (user approval chain).
+   * Creates a task in state='active' immediately.
+   *
+   * @param {Object} payload
+   * @param {string}            payload.description
+   * @param {string}            payload.executorId     - agentId who will execute
+   * @param {string}            payload.chatId
+   * @param {string}            payload.parentTaskId   - required (proves user approval)
+   * @param {TaskContract}      [payload.contract]
+   * @param {TaskPerspective}   [payload.perspective]
+   * @param {string}            [payload.payerId]
+   * @returns {Promise<TaskWithFlags>}
+   */
+  async assignTask(payload) {
+    try {
+      const result = await apiAssignTask(payload, this.creds);
+      console.log(`⚡ Task directly assigned (no proposal): ${result?.taskId || 'unknown'}`);
+      return result;
+    } catch (error) {
+      console.error(`❌ Task assignment failed: ${error.message}`);
+      throw error;
+    }
+  }
+
+  /**
+   * Delegate task to another agent (creates proposal to executor). Requires parentTaskId.
+   * Creates a task in state='proposal' where proposedTo=executorId.
+   *
+   * @param {Object} payload
+   * @param {string}            payload.description
+   * @param {string}            payload.executorId     - agentId to delegate to
+   * @param {string}            payload.chatId
+   * @param {string}            payload.parentTaskId   - required (proves user approval)
+   * @param {TaskContract}      [payload.contract]
+   * @param {TaskPerspective}   [payload.perspective]
+   * @param {string}            [payload.payerId]
+   * @returns {Promise<TaskWithFlags>}
+   */
+  async delegateToAgent(payload) {
+    try {
+      const result = await apiDelegateToAgent(payload, this.creds);
+      console.log(`✅ Proposal created (delegated): ${result?.taskId || 'unknown'}`);
+      return result;
+    } catch (error) {
+      console.error(`❌ Proposal creation failed: ${error.message}`);
+      throw error;
+    }
+  }
+
+  /**
+   * Create a standalone task (no proposal workflow). State starts as 'active'.
+   *
+   * @param {Object} taskData
+   * @param {string}            taskData.description
+   * @param {string}            [taskData.executorId]
+   * @param {string}            [taskData.payerId]
+   * @param {string}            [taskData.parentTaskId]
+   * @param {TaskContract}      [taskData.contract]
+   * @param {TaskPerspective}   [taskData.perspective]
+   * @param {{steps?: {stepId: string, description: string, order: number}[]}} [taskData.plan]
+   * @param {string} chatId
+   * @returns {Promise<Task>}
+   */
+  async createTask(taskData, chatId) {
+    try {
+      const result = await apiCreateTask({
+        ...taskData,
+        chatId
+      }, this.creds);
+
+      console.log(`✅ Task created: ${result?.taskId || 'unknown'}`);
+      return result;
+    } catch (error) {
+      console.error(`❌ Task creation failed: ${error.message}`);
+      throw error;
+    }
+  }
+
+  /**
+   * Respond to a proposal — approve or reject.
+   * approve: transitions state proposal→active, sets proposal.status='approved'
+   * reject:  transitions state proposal→cancelled, sets proposal.status='rejected'
+   *
+   * @param {string} taskId
+   * @param {'approve'|'reject'} action
+   * @param {string} [chatId]
+   * @returns {Promise<TaskWithFlags>}
+   */
+  async respondToProposal(taskId, action, chatId) {
+    try {
+      const result = await apiRespondToProposal(taskId, action, this.creds);
+      console.log(`✅ Proposal ${action}d: ${taskId}`);
+      return result;
+    } catch (error) {
+      console.error(`❌ Proposal response failed: ${error.message}`);
+      throw error;
+    }
+  }
+
+  /**
+   * Update a plan step within a task.
+   *
+   * @param {string} taskId
+   * @param {string} stepId
+   * @param {'pending'|'in_progress'|'completed'|'skipped'} status
+   * @param {*}      [result]
+   * @returns {Promise<Task|null>}
+   */
+  async updatePlanStep(taskId, stepId, status, result) {
+    try {
+      const updated = await apiUpdatePlanStep(taskId, stepId, status, result, this.creds);
+      console.log(`✅ Plan step updated: ${taskId} / ${stepId} -> ${status}`);
+      return updated;
+    } catch (error) {
+      console.error(`❌ Plan step update failed: ${error.message}`);
+      throw error;
+    }
+  }
+
+  /**
+   * Transition a task's state. Only valid transitions are accepted by the backend:
+   *   proposal → active | cancelled
+   *   active   → completed | failed | cancelled
+   *
+   * @param {string} taskId
+   * @param {'completed'|'failed'|'cancelled'} status  - target state
+   * @param {*}      [result]                           - task result (stored in task.result)
+   * @param {string} [chatId]
+   * @returns {Promise<Task|null>}
+   */
+  async updateTask(taskId, status, result, chatId) {
+    try {
+      const data = result ? { result: safeJsonStringify(result) } : {};
+      const updated = await updateTaskState(taskId, status, data, this.creds);
+
+      console.log(`✅ Task updated: ${taskId} -> ${status}`);
+      return updated;
+    } catch (error) {
+      console.error(`❌ Task update failed: ${error.message}`);
+      throw error;
+    }
+  }
+
+  /**
+   * Claim an open ledger task (proposal.proposedTo='everyone').
+   * Atomically sets executorId to the claiming agent and transitions to state='active'.
+   *
+   * @param {string} taskId
+   * @returns {Promise<TaskWithFlags>}
+   */
+  async claimLedgerTask(taskId) {
+    try {
+      const task = await apiClaimLedgerTask(taskId, this.creds);
+      console.log(`✅ [ledger] Claimed task ${taskId}`);
+      return task;
+    } catch (error) {
+      console.warn(`⚠️ [ledger] Claim failed for ${taskId}: ${error.message}`);
+      throw error;
+    }
+  }
+}

package/src/tasks/index.js

@@ -0,0 +1,9 @@
+export { TaskService } from './TaskService.js';
+export { TASK_PROTOCOL_TOOLS } from './taskProtocolTools.js';
+export {
+  TASK_PROTOCOL_TOOL_NAMES,
+  TASK_PROTOCOL_TOOL_TO_OPERATION,
+  mapTaskProtocolToolToOperation,
+  isTaskProtocolToolName,
+} from './taskProtocolRegistry.js';
+export { executeTaskPayload } from './taskProtocolRunner.js';

package/src/tasks/taskCore.js

@@ -0,0 +1,229 @@
+/**
+ * Canonical Task definitions — states, state machine, shapes, and helpers.
+ *
+ * This is the single source of truth for what a Task looks like in the Ziggs system.
+ * Every layer (DB, API, SDK, frontend) must conform to these definitions.
+ *
+ * ⚠️  SYNC: Keep in sync with backend/src/tasks/task-core.ts
+ */
+
+// ---------------------------------------------------------------------------
+// States
+// ---------------------------------------------------------------------------
+
+export const TaskState = {
+  PROPOSAL: 'proposal',
+  ACTIVE: 'active',
+  COMPLETED: 'completed',
+  FAILED: 'failed',
+  CANCELLED: 'cancelled',
+};
+
+export const TASK_STATES = ['proposal', 'active', 'completed', 'failed', 'cancelled'];
+
+export const TERMINAL_STATES = ['completed', 'failed', 'cancelled'];
+
+// ---------------------------------------------------------------------------
+// State Machine
+// ---------------------------------------------------------------------------
+
+export const VALID_TRANSITIONS = {
+  proposal: ['active', 'cancelled'],
+  active: ['completed', 'failed', 'cancelled'],
+};
+
+export function isTerminal(state) {
+  return TERMINAL_STATES.includes(state);
+}
+
+export function canTransitionTo(from, to) {
+  if (isTerminal(from)) return false;
+  const allowed = VALID_TRANSITIONS[from];
+  if (!allowed) return false;
+  return allowed.includes(to);
+}
+
+/**
+ * Normalize legacy state aliases.
+ * 'done' → 'completed', 'error' → 'failed'.
+ * Passthrough for canonical states.
+ */
+export function normalizeState(state) {
+  if (state === 'done') return TaskState.COMPLETED;
+  if (state === 'error') return TaskState.FAILED;
+  return state;
+}
+
+/**
+ * Returns true if `state` is a valid canonical TaskState value.
+ */
+export function isValidState(state) {
+  return TASK_STATES.includes(state);
+}
+
+// ---------------------------------------------------------------------------
+// Proposal
+// ---------------------------------------------------------------------------
+
+export const ProposalStatus = {
+  PENDING: 'pending',
+  APPROVED: 'approved',
+  REJECTED: 'rejected',
+};
+
+export const OPEN_PROPOSAL_TARGET = 'everyone';
+
+// ---------------------------------------------------------------------------
+// Plan Step
+// ---------------------------------------------------------------------------
+
+export const PlanStepStatus = {
+  PENDING: 'pending',
+  IN_PROGRESS: 'in_progress',
+  COMPLETED: 'completed',
+  SKIPPED: 'skipped',
+};
+
+export const PLAN_STEP_STATUSES = ['pending', 'in_progress', 'completed', 'skipped'];
+
+// ---------------------------------------------------------------------------
+// History
+// ---------------------------------------------------------------------------
+
+export const HistoryChangeType = {
+  CREATED: 'created',
+  STATE_CHANGED: 'state_changed',
+  PROCESSING_CHANGED: 'processing_changed',
+  PROPOSAL_RESPONDED: 'proposal_responded',
+  PLAN_STEP_CHANGED: 'plan_step_changed',
+};
+
+// ---------------------------------------------------------------------------
+// Contract lifecycle
+// ---------------------------------------------------------------------------
+
+export const ContractLifecycle = {
+  OPEN: 'open',
+  TIME_BOUND: 'time-bound',
+  COUNT_BOUND: 'count-bound',
+};
+
+// ---------------------------------------------------------------------------
+// Task shape — JSDoc mirrors backend ITask interface exactly.
+// These are not runtime constructs, just documentation so SDK devs
+// see the same field names the backend uses.
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {Object} TaskContract
+ * @property {'open'|'time-bound'|'count-bound'} lifecycle
+ * @property {string|null}  expiresAt            - ISO date string or null
+ * @property {number|null}  maxExecutions
+ * @property {string}       description
+ * @property {string}       [specialistAgentId]   - single specialist
+ * @property {string[]}     [specialistAgentIds]  - multi-specialist orchestration
+ */
+
+/**
+ * @typedef {Object} TaskProposal
+ * @property {string|null}                          proposedTo   - userId/agentId or 'everyone' for ledger
+ * @property {'pending'|'approved'|'rejected'|null} status
+ * @property {string|null}                          respondedBy
+ * @property {string|null}                          proposedAt   - ISO date string
+ * @property {string|null}                          respondedAt  - ISO date string
+ */
+
+/**
+ * @typedef {Object} TaskPlanStep
+ * @property {string} stepId
+ * @property {string} description
+ * @property {number} order
+ * @property {'pending'|'in_progress'|'completed'|'skipped'} status
+ * @property {*}      result
+ */
+
+/**
+ * @typedef {Object} TaskPlan
+ * @property {TaskPlanStep[]} steps
+ * @property {string}         createdAt  - ISO date string
+ * @property {string}         updatedAt  - ISO date string
+ */
+
+/**
+ * @typedef {Object} TaskHistoryEntry
+ * @property {'created'|'state_changed'|'processing_changed'|'proposal_responded'|'plan_step_changed'} changeType
+ * @property {*}                previousState
+ * @property {*}                newState
+ * @property {string}           timestamp  - ISO date string
+ * @property {Object}           metadata
+ */
+
+/**
+ * @typedef {Object} TaskPerspective
+ * @property {string|null} ownerChatId
+ */
+
+/**
+ * The canonical Task object returned by all API endpoints.
+ * Mirrors backend ITask exactly — same fields, same names, same nesting.
+ *
+ * @typedef {Object} Task
+ * @property {string}             taskId
+ * @property {string}             description
+ * @property {string|null}        chatId
+ * @property {string|null}        agentId        - who created/proposed the task
+ * @property {string|null}        executorId     - who executes the task
+ * @property {string|null}        payerId        - who pays/approves
+ * @property {TaskContract}       contract
+ * @property {TaskPerspective}    perspective
+ * @property {'proposal'|'active'|'completed'|'failed'|'cancelled'} state
+ * @property {TaskProposal}       proposal
+ * @property {boolean}            processing     - atomic lock for concurrent execution
+ * @property {boolean}            deleted        - soft-delete flag
+ * @property {*}                  result
+ * @property {string|null}        errorMessage
+ * @property {string}             createdAt      - ISO date string
+ * @property {string}             updatedAt      - ISO date string
+ * @property {string|null}        parentTaskId
+ * @property {string|null}        rootTaskId
+ * @property {TaskPlan}           plan
+ * @property {TaskHistoryEntry[]} history
+ */
+
+/**
+ * Task with "isYou" perspective flags (added by backend when requesting agent is known).
+ * Mirrors backend ITaskWithFlags.
+ *
+ * @typedef {Task & {
+ *   agentIdIsYou?:    boolean,
+ *   executorIdIsYou?: boolean,
+ *   payerIdIsYou?:    boolean,
+ *   proposedToIsYou?: boolean,
+ * }} TaskWithFlags
+ */
+
+// ---------------------------------------------------------------------------
+// Defaults — use these when constructing task payloads to match backend defaults.
+// ---------------------------------------------------------------------------
+
+/** Default contract shape (matches Mongoose schema defaults). */
+export const DEFAULT_CONTRACT = {
+  lifecycle: ContractLifecycle.OPEN,
+  expiresAt: null,
+  maxExecutions: null,
+  description: '',
+};
+
+/** Default perspective shape (matches Mongoose schema defaults). */
+export const DEFAULT_PERSPECTIVE = {
+  ownerChatId: null,
+};
+
+/** Default proposal shape (matches Mongoose schema defaults). */
+export const DEFAULT_PROPOSAL = {
+  proposedTo: null,
+  status: null,
+  respondedBy: null,
+  proposedAt: null,
+  respondedAt: null,
+};

package/src/tasks/taskProtocolRegistry.js

@@ -0,0 +1,22 @@
+/**
+ * Maps built-in task protocol tool names (task_*) to task service operation strings.
+ */
+
+export const TASK_PROTOCOL_TOOL_TO_OPERATION = Object.freeze({
+  task_make_task: 'make-task',
+  task_make_sub_tasks: 'make-sub-tasks',
+  task_update_task: 'update-task',
+  task_respond_proposal: 'respond-proposal',
+  task_update_plan_step: 'update-plan-step',
+});
+
+export const TASK_PROTOCOL_TOOL_NAMES = Object.freeze(Object.keys(TASK_PROTOCOL_TOOL_TO_OPERATION));
+
+export function mapTaskProtocolToolToOperation(toolName) {
+  if (!toolName || typeof toolName !== 'string') return null;
+  return TASK_PROTOCOL_TOOL_TO_OPERATION[toolName] || null;
+}
+
+export function isTaskProtocolToolName(toolName) {
+  return mapTaskProtocolToolToOperation(toolName) != null;
+}

package/src/tasks/taskProtocolRunner.js

@@ -0,0 +1,107 @@
+/**
+ * Shared task-service execution used by the workflow engine and task protocol tools.
+ *
+ * The LLM produces a task object (e.g. { description, proposedTo, contract, ... }).
+ * This module routes it to the right TaskService method with minimal mutation —
+ * the original payload flows through to the API client almost untouched.
+ */
+
+import { normalizeState } from './taskCore.js';
+
+function specialistIdFromTurnScratch(toolCtx) {
+  const hit = toolCtx?.turnScratch?.agentSearchLastResult;
+  if (!hit || hit.operation !== 'search' || hit.success === false) return null;
+  const outer = hit.data;
+  if (!outer || typeof outer !== 'object') return null;
+  const inner = outer.data && typeof outer.data === 'object' ? outer.data : outer;
+  const list = inner.agents;
+  if (!Array.isArray(list) || list.length === 0) return null;
+  const first = list[0];
+  const id = first?.agentId ?? first?.id;
+  return typeof id === 'string' && id.length > 0 ? id : null;
+}
+
+export async function executeTaskPayload(taskService, task, chatId, agents = [], toolCtx = {}) {
+  if (!task?.operation) return null;
+  const { operation } = task;
+
+  switch (operation) {
+    case 'make-task':
+      return await createSingleTask(taskService, task, chatId, agents, toolCtx);
+    case 'make-sub-tasks':
+      return await createTaskWithSubtasks(taskService, task, chatId);
+    case 'update-task':
+      if (!task.taskId || !task.status) return null;
+      return await taskService.updateTask(task.taskId, normalizeState(task.status), task.result, chatId);
+    case 'respond-proposal':
+      if (!task.taskId || !task.action) return null;
+      return await taskService.respondToProposal(task.taskId, task.action, chatId);
+    case 'update-plan-step':
+      if (!task.taskId || !task.stepId || !task.status) return null;
+      return await taskService.updatePlanStep(task.taskId, task.stepId, task.status, task.result);
+    default:
+      return null;
+  }
+}
+
+export async function createSingleTask(taskService, task, chatId, agents = [], toolCtx = {}) {
+  if (!task.description) return null;
+
+  // Build the payload from the LLM-produced fields — pass through, don't restructure.
+  // Only `operation` is SDK-internal and gets stripped.
+  const { operation: _op, ...fields } = task;
+  const inferred = specialistIdFromTurnScratch(toolCtx);
+  const mergedContract = { ...(task.contract || {}) };
+  const hasMulti =
+    Array.isArray(mergedContract.specialistAgentIds) &&
+    mergedContract.specialistAgentIds.length > 0;
+  if (!mergedContract.specialistAgentId && !hasMulti && inferred) {
+    mergedContract.specialistAgentId = inferred;
+  }
+  const payload = { ...fields, chatId, contract: mergedContract };
+
+  const parentTaskId = task.parentTaskId || null;
+
+  if (task.proposedTo && !task.executorId) {
+    const target = agents.find(a => a.agentId === task.proposedTo);
+    const caps = target?.capabilities || {};
+    // Users are never in `agents[]` as agentId — treating !target as "assign" wrongly called assignTask
+    // (requires parentTaskId) and broke user proposal cards (proposeToDoWork).
+    // Direct assign only after an approved chain: parentTaskId + (off-context executor OR tAcceptDecline false).
+    const useDirectAssign =
+      parentTaskId && (!target || caps.tAcceptDecline === false);
+    if (useDirectAssign) {
+      return await taskService.assignTask({ ...payload, executorId: task.proposedTo });
+    }
+    return await taskService.proposeToDoWork(payload);
+  }
+
+  if (task.executorId) {
+    const target = agents.find(a => a.agentId === task.executorId);
+    const caps = target?.capabilities || {};
+    const useDirectAssign =
+      parentTaskId && (!target || caps.tAcceptDecline === false);
+    if (useDirectAssign) {
+      return await taskService.assignTask(payload);
+    }
+    return await taskService.delegateToAgent(payload);
+  }
+
+  return await taskService.createTask(task, chatId);
+}
+
+export async function createTaskWithSubtasks(taskService, task, chatId) {
+  if (!task.description || !Array.isArray(task.subtasks) || !task.subtasks.length) return null;
+  const parent = await taskService.createTask(
+    { description: task.description, contract: task.contract || {}, perspective: task.perspective || {}, parentTaskId: task.parentTaskId || null },
+    chatId
+  );
+  if (!parent?.taskId) return null;
+  const results = await Promise.all(
+    task.subtasks.map(s => {
+      const desc = typeof s === 'string' ? s : (s.description || '');
+      return taskService.createTask({ description: desc, parentTaskId: parent.taskId }, chatId);
+    })
+  );
+  return { ...parent, subtasks: results.filter(r => r?.taskId) };
+}