@ziggs-ai/agent-sdk 0.1.3 → 0.1.4

package/src/tasks/TaskService.js

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

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

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

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

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