@ziggs-ai/api-client 0.1.3 → 0.1.4

package/src/http/ContextWriter.js

@@ -1,98 +0,0 @@
-import 'dotenv/config';
-import { EntryTypes, ContentTypes } from '../types.js';
-import { getBackendUrl } from '../utils/urlUtils.js';
-
-export class ContextWriter {
-  constructor(operatorKey, agentId) {
-    if (!operatorKey) {
-      throw new Error('ContextWriter: operatorKey is required');
-    }
-    if (!agentId) {
-      throw new Error('ContextWriter: agentId is required (operator-token impersonation)');
-    }
-    this.operatorKey = operatorKey;
-    this.agentId = agentId;
-  }
-
-  _getBaseUrl() {
-    const route = process.env.HISTORY_SERVICE_ROUTE || 'context';
-    return `${getBackendUrl()}/${route}`;
-  }
-
-  async recordOperation(chatId, operation) {
-    if (!chatId) return;
-
-    const prefix = operation.state === 'completed'
-      ? 'operation_completed:'
-      : operation.state === 'failed'
-        ? 'operation_error:'
-        : 'operation_started:';
-
-    const text = prefix + JSON.stringify(operation);
-
-    try {
-      await fetch(`${this._getBaseUrl()}/ingest`, {
-        method: 'POST',
-        headers: this._buildHeaders(),
-        body: JSON.stringify({
-          chatId,
-          text,
-          entryType: EntryTypes.ARTIFACT,
-          content_type: ContentTypes.OPERATION
-        })
-      });
-    } catch (error) {
-      console.warn(`⚠️ Failed to record operation: ${error.message}`);
-    }
-  }
-
-  async recordMessage(chatId, message) {
-    if (!chatId) return;
-
-    try {
-      await fetch(`${this._getBaseUrl()}/ingest`, {
-        method: 'POST',
-        headers: this._buildHeaders(),
-        body: JSON.stringify({
-          chatId,
-          text: message.text,
-          entryType: EntryTypes.MESSAGE,
-          content_type: ContentTypes.TEXT
-        })
-      });
-    } catch (error) {
-      console.warn(`⚠️ Failed to record message: ${error.message}`);
-    }
-  }
-
-  /**
-   * Send agent thought (reasoning) as artifact so it appears in timeline and frontend.
-   * Backend stores with entryType=artifact, content_type=thought. Sender is taken from JWT.
-   */
-  async recordThought(chatId, thoughtText) {
-    if (!chatId || thoughtText == null || String(thoughtText).trim() === '') return;
-
-    try {
-      await fetch(`${this._getBaseUrl()}/ingest`, {
-        method: 'POST',
-        headers: this._buildHeaders(),
-        body: JSON.stringify({
-          chatId,
-          text: String(thoughtText).trim(),
-          entryType: EntryTypes.ARTIFACT,
-          content_type: ContentTypes.THOUGHT
-        })
-      });
-    } catch (error) {
-      console.warn(`⚠️ Failed to record thought artifact: ${error.message}`);
-    }
-  }
-
-  _buildHeaders() {
-    return {
-      'content-type': 'application/json',
-      'Authorization': `Bearer ${this.operatorKey}`,
-      'X-Agent-Id': this.agentId,
-    };
-  }
-}

package/src/http/TaskClient.js

@@ -1,612 +0,0 @@
-/**
- * HTTP client for the Tasks API.
- *
- * Every function returns a Task object matching the backend ITask shape:
- * { taskId, description, chatId, agentId, executorId, payerId, contract,
- *   perspective, state, proposal, processing, deleted, result, errorMessage,
- *   createdAt, updatedAt, parentTaskId, rootTaskId, plan, history }
- *
- * ⚠️  SYNC: Field names must match backend/src/tasks/task-core.ts ITask interface.
- */
-
-import 'dotenv/config';
-import { getBackendUrl } from '../utils/urlUtils.js';
-
-const baseUrl = getBackendUrl();
-const TASK_BASE_URL = `${baseUrl}/tasks`;
-
-/**
- * @typedef {{ operatorKey: string, agentId: string }} Creds
- */
-
-function buildHeaders(creds) {
-  const { operatorKey, agentId } = creds || {};
-  if (!operatorKey) {
-    throw new Error('operatorKey is required for task service requests');
-  }
-  if (!agentId) {
-    throw new Error('agentId is required for task service requests (operator-token impersonation)');
-  }
-  return {
-    'content-type': 'application/json',
-    Authorization: `Bearer ${operatorKey}`,
-    'X-Agent-Id': agentId,
-  };
-}
-
-function assertCreds(creds, op) {
-  if (!creds?.operatorKey) throw new Error(`operatorKey is required for ${op}`);
-  if (!creds?.agentId) throw new Error(`agentId is required for ${op}`);
-}
-
-/**
- * Parse error message from API response.
- * Checks for details, error, or message fields in JSON response.
- * Falls back to raw body or default message.
- */
-function parseErrorMessage(responseBody, defaultMessage) {
-  if (!responseBody) return defaultMessage;
-  try {
-    const errorData = JSON.parse(responseBody);
-    return errorData.details || errorData.error || errorData.message || defaultMessage;
-  } catch {
-    return responseBody || defaultMessage;
-  }
-}
-
-function throwApiError(response, responseBody, defaultMessage) {
-  const errorMessage = parseErrorMessage(responseBody, defaultMessage);
-  const error = new Error(errorMessage);
-  error.status = response.status;
-  error.body = responseBody;
-  throw error;
-}
-
-/**
- * Extract the Task object from an API response.
- * Handles both shapes: `{ task: {...} }` (POST /tasks, PATCH) and direct task (GET, proposal endpoints).
- * @returns {Object|null} The task object, or null if not found.
- */
-function extractTask(data) {
-  if (!data) return null;
-  // Wrapped: { status: '...', task: { taskId, ... } }
-  if (data.task && data.task.taskId) return data.task;
-  // Direct: { taskId, description, ... }
-  if (data.taskId) return data;
-  return null;
-}
-
-// ---------------------------------------------------------------------------
-// CRUD
-// ---------------------------------------------------------------------------
-
-/**
- * Create a standalone task (state='active').
- * POST /tasks
- *
- * @param {Object} taskData
- * @param {string}  taskData.description
- * @param {string}  [taskData.chatId]
- * @param {string}  [taskData.executorId]
- * @param {string}  [taskData.payerId]
- * @param {string}  [taskData.parentTaskId]
- * @param {Object}  [taskData.contract]
- * @param {Object}  [taskData.perspective]
- * @param {Object}  [taskData.plan]
- * @param {string}  operatorKey
- * @returns {Promise<Object>} Task object
- */
-export async function createTask(taskData, creds) {
-  if (!taskData) throw new Error('Task data is required for task creation');
-  assertCreds(creds, 'task creation');
-
-  const res = await fetch(`${TASK_BASE_URL}`, {
-    method: 'POST',
-    headers: buildHeaders(creds),
-    body: JSON.stringify(taskData),
-  });
-
-  if (!res.ok) {
-    const body = await res.text().catch(() => '');
-    throwApiError(res, body, `Task creation failed: ${res.status} ${res.statusText}`);
-  }
-
-  const data = await res.json().catch(() => null);
-  const task = extractTask(data);
-  if (!task) throw new Error('Invalid response: task data not found');
-  return task;
-}
-
-/**
- * Get a single task by ID.
- * GET /tasks/:taskId
- *
- * @param {string} taskId
- * @param {string} operatorKey
- * @returns {Promise<Object|null>} Task object or null
- */
-export async function getTask(taskId, creds) {
-  if (!taskId) return null;
-  assertCreds(creds, 'task retrieval');
-
-  try {
-    const res = await fetch(`${TASK_BASE_URL}/${taskId}`, {
-      method: 'GET',
-      headers: buildHeaders(creds),
-    });
-
-    if (!res.ok) {
-      const body = await res.text().catch(() => '');
-      console.warn(`⚠️ Task get failed: ${res.status} ${res.statusText} ${body}`);
-      return null;
-    }
-
-    const data = await res.json().catch(() => null);
-    return extractTask(data);
-  } catch (e) {
-    console.warn(`⚠️ Task get failed: ${e.message}`);
-    return null;
-  }
-}
-
-/**
- * Update a task's state.
- * PATCH /tasks/:taskId/state
- *
- * Valid transitions (enforced by backend):
- *   proposal → active | cancelled
- *   active   → completed | failed | cancelled
- *
- * @param {string} taskId
- * @param {'proposal'|'active'|'completed'|'failed'|'cancelled'} state
- * @param {Object} [data]
- * @param {*}      [data.result]
- * @param {string} [data.errorMessage]
- * @param {string} operatorKey
- * @returns {Promise<Object|null>} Updated task or null
- */
-export async function updateTaskState(taskId, state, data = {}, creds) {
-  if (!taskId || !state) return null;
-  assertCreds(creds, 'task state update');
-
-  try {
-    const res = await fetch(`${TASK_BASE_URL}/${taskId}/state`, {
-      method: 'PATCH',
-      headers: buildHeaders(creds),
-      body: JSON.stringify({ state, ...data }),
-    });
-
-    if (!res.ok) {
-      const body = await res.text().catch(() => '');
-      console.warn(`⚠️ Task state update failed: ${res.status} ${res.statusText} ${body}`);
-      return null;
-    }
-
-    const result = await res.json().catch(() => null);
-    return extractTask(result);
-  } catch (e) {
-    console.warn(`⚠️ Task state update failed: ${e.message}`);
-    return null;
-  }
-}
-
-/**
- * Get active tasks, optionally filtered by chatId and/or agentId.
- * GET /tasks?state=active[&chatId=...][&agentId=...]
- *
- * @param {string|null} chatId
- * @param {string}      operatorKey
- * @param {string|null} [agentId]
- * @returns {Promise<Object[]>} Array of Task objects
- */
-export async function getActiveTasks(chatId = null, creds, filterAgentId = null) {
-  assertCreds(creds, 'getting active tasks');
-
-  try {
-    const url = new URL(`${TASK_BASE_URL}`);
-    url.searchParams.set('state', 'active');
-    if (chatId) url.searchParams.set('chatId', chatId);
-    if (filterAgentId) url.searchParams.set('agentId', filterAgentId);
-
-    const res = await fetch(url.toString(), {
-      method: 'GET',
-      headers: buildHeaders(creds),
-    });
-
-    if (!res.ok) {
-      const body = await res.text().catch(() => '');
-      console.warn(`⚠️ Get active tasks failed: ${res.status} ${res.statusText} ${body}`);
-      return [];
-    }
-
-    const data = await res.json().catch(() => null);
-    return Array.isArray(data?.tasks) ? data.tasks : [];
-  } catch (e) {
-    console.warn(`⚠️ Get active tasks failed: ${e.message}`);
-    return [];
-  }
-}
-
-/**
- * Acquire or release the atomic processing lock on a task.
- * PATCH /tasks/:taskId/processing
- *
- * @param {string}  taskId
- * @param {boolean} processing - true to acquire, false to release
- * @param {string}  operatorKey
- * @returns {Promise<{acquired: boolean, task: Object|null}>}
- */
-export async function markTaskProcessing(taskId, processing, creds) {
-  if (!taskId) return { acquired: false, task: null };
-  assertCreds(creds, 'task processing lock');
-
-  try {
-    const res = await fetch(`${TASK_BASE_URL}/${taskId}/processing`, {
-      method: 'PATCH',
-      headers: buildHeaders(creds),
-      body: JSON.stringify({ processing }),
-    });
-
-    if (!res.ok) {
-      const body = await res.text().catch(() => '');
-      console.warn(`⚠️ Task processing lock failed: ${res.status} ${res.statusText} ${body}`);
-      return { acquired: false, task: null };
-    }
-
-    const data = await res.json().catch(() => null);
-    return {
-      acquired: data?.acquired ?? false,
-      task: data?.task || null,
-    };
-  } catch (e) {
-    console.warn(`⚠️ Task processing lock failed: ${e.message}`);
-    return { acquired: false, task: null };
-  }
-}
-
-/**
- * Cancel a task (transitions to state='cancelled').
- * PATCH /tasks/:taskId/cancel
- *
- * @param {string} taskId
- * @param {string} operatorKey
- * @returns {Promise<Object|null>} Cancelled task or null
- */
-export async function cancelTask(taskId, creds) {
-  if (!taskId) return null;
-  assertCreds(creds, 'task cancellation');
-
-  try {
-    const res = await fetch(`${TASK_BASE_URL}/${taskId}/cancel`, {
-      method: 'PATCH',
-      headers: buildHeaders(creds),
-    });
-
-    if (!res.ok) {
-      const body = await res.text().catch(() => '');
-      console.warn(`⚠️ Task cancel failed: ${res.status} ${res.statusText} ${body}`);
-      return null;
-    }
-
-    const result = await res.json().catch(() => null);
-    return extractTask(result);
-  } catch (e) {
-    console.warn(`⚠️ Task cancel failed: ${e.message}`);
-    return null;
-  }
-}
-
-/**
- * Get subtasks for a parent task.
- * GET /tasks?parentTaskId=...
- *
- * @param {string} parentTaskId
- * @param {string} operatorKey
- * @returns {Promise<Object[]>} Array of Task objects
- */
-export async function getSubtasks(parentTaskId, creds) {
-  if (!parentTaskId) return [];
-  assertCreds(creds, 'getting subtasks');
-
-  try {
-    const url = new URL(`${TASK_BASE_URL}`);
-    url.searchParams.set('parentTaskId', parentTaskId);
-
-    const res = await fetch(url.toString(), {
-      method: 'GET',
-      headers: buildHeaders(creds),
-    });
-
-    if (!res.ok) {
-      const body = await res.text().catch(() => '');
-      console.warn(`⚠️ Get subtasks failed: ${res.status} ${res.statusText} ${body}`);
-      return [];
-    }
-
-    const data = await res.json().catch(() => null);
-    return Array.isArray(data?.tasks) ? data.tasks : [];
-  } catch (e) {
-    console.warn(`⚠️ Get subtasks failed: ${e.message}`);
-    return [];
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Proposal workflow
-// ---------------------------------------------------------------------------
-
-/**
- * Propose work to a user or agent for approval.
- * POST /tasks/proposeToDoWork
- *
- * Creates a task with state='proposal', proposal.status='pending'.
- *
- * @param {Object} proposalData
- * @param {string}  proposalData.description
- * @param {string}  proposalData.proposedTo     - userId or agentId to approve
- * @param {string}  proposalData.chatId
- * @param {Object}  [proposalData.contract]
- * @param {Object}  [proposalData.perspective]
- * @param {string}  [proposalData.parentTaskId]
- * @param {string}  [proposalData.payerId]
- * @param {string}  operatorKey
- * @returns {Promise<Object>} TaskWithFlags object
- */
-export async function proposeToDoWork(proposalData, creds) {
-  if (!proposalData) throw new Error('Proposal data is required for proposal creation');
-  assertCreds(creds, 'proposal creation');
-
-  const { description, proposedTo, chatId, contract, perspective, parentTaskId, payerId } = proposalData;
-  const res = await fetch(`${baseUrl}/tasks/proposeToDoWork`, {
-    method: 'POST',
-    headers: buildHeaders(creds),
-    body: JSON.stringify({ description, proposedTo, chatId, contract, perspective, parentTaskId, payerId }),
-  });
-
-  if (!res.ok) {
-    const body = await res.text().catch(() => '');
-    throwApiError(res, body, `Proposal creation failed: ${res.status} ${res.statusText}`);
-  }
-
-  const data = await res.json().catch(() => null);
-  const task = extractTask(data);
-  if (!task) throw new Error('Invalid response: proposal data not found');
-  return task;
-}
-
-/**
- * Assign task directly (no proposal step). Requires parentTaskId.
- * POST /tasks/assignTask
- *
- * Creates a task with state='active' immediately.
- *
- * @param {Object} assignData
- * @param {string}  assignData.description
- * @param {string}  assignData.executorId
- * @param {string}  assignData.chatId
- * @param {string}  assignData.parentTaskId     - required (proves user approval)
- * @param {Object}  [assignData.contract]
- * @param {Object}  [assignData.perspective]
- * @param {string}  [assignData.payerId]
- * @param {string}  operatorKey
- * @returns {Promise<Object>} TaskWithFlags object
- */
-export async function assignTask(assignData, creds) {
-  if (!assignData) throw new Error('Assign data is required');
-  assertCreds(creds, 'task assignment');
-
-  const { description, executorId, chatId, contract, perspective, parentTaskId, payerId } = assignData;
-  const res = await fetch(`${baseUrl}/tasks/assignTask`, {
-    method: 'POST',
-    headers: buildHeaders(creds),
-    body: JSON.stringify({ description, executorId, chatId, contract, perspective, parentTaskId, payerId }),
-  });
-
-  if (!res.ok) {
-    const body = await res.text().catch(() => '');
-    throwApiError(res, body, `Task assignment failed: ${res.status} ${res.statusText}`);
-  }
-
-  const data = await res.json().catch(() => null);
-  const task = extractTask(data);
-  if (!task) throw new Error('Invalid response: assignment data not found');
-  return task;
-}
-
-/**
- * Delegate task to another agent (creates proposal to executor). Requires parentTaskId.
- * POST /tasks/delegateToAgent
- *
- * Creates a task with state='proposal', proposedTo=executorId.
- *
- * @param {Object} proposalData
- * @param {string}  proposalData.description
- * @param {string}  proposalData.executorId
- * @param {string}  proposalData.chatId
- * @param {string}  proposalData.parentTaskId   - required (proves user approval)
- * @param {Object}  [proposalData.contract]
- * @param {Object}  [proposalData.perspective]
- * @param {string}  [proposalData.payerId]
- * @param {string}  operatorKey
- * @returns {Promise<Object>} TaskWithFlags object
- */
-export async function delegateToAgent(proposalData, creds) {
-  if (!proposalData) throw new Error('Proposal data is required for delegation');
-  assertCreds(creds, 'proposal creation');
-
-  const { description, executorId, chatId, contract, perspective, parentTaskId, payerId } = proposalData;
-  const res = await fetch(`${baseUrl}/tasks/delegateToAgent`, {
-    method: 'POST',
-    headers: buildHeaders(creds),
-    body: JSON.stringify({ description, executorId, chatId, contract, perspective, parentTaskId, payerId }),
-  });
-
-  if (!res.ok) {
-    const body = await res.text().catch(() => '');
-    throwApiError(res, body, `Delegation failed: ${res.status} ${res.statusText}`);
-  }
-
-  const data = await res.json().catch(() => null);
-  const task = extractTask(data);
-  if (!task) throw new Error('Invalid response: delegation data not found');
-  return task;
-}
-
-/**
- * Update a plan step within a task.
- * PATCH /tasks/:taskId/plan
- *
- * @param {string} taskId
- * @param {string} stepId
- * @param {'pending'|'in_progress'|'completed'|'skipped'} status
- * @param {*}      [result]
- * @param {string} operatorKey
- * @returns {Promise<Object|null>} Updated task or null
- */
-export async function updatePlanStep(taskId, stepId, status, result, creds) {
-  if (!taskId || !stepId || !status) return null;
-  assertCreds(creds, 'plan step update');
-
-  try {
-    const body = { stepId, status };
-    if (result !== undefined) body.result = result;
-
-    const res = await fetch(`${TASK_BASE_URL}/${taskId}/plan`, {
-      method: 'PATCH',
-      headers: buildHeaders(creds),
-      body: JSON.stringify(body),
-    });
-
-    if (!res.ok) {
-      const responseBody = await res.text().catch(() => '');
-      console.warn(`⚠️ Plan step update failed: ${res.status} ${res.statusText} ${responseBody}`);
-      return null;
-    }
-
-    const data = await res.json().catch(() => null);
-    return extractTask(data);
-  } catch (e) {
-    console.warn(`⚠️ Plan step update failed: ${e.message}`);
-    return null;
-  }
-}
-
-/**
- * Respond to a proposal — approve or reject.
- * POST /tasks/respondToProposal
- *
- * approve: state proposal→active, proposal.status='approved'
- * reject:  state proposal→cancelled, proposal.status='rejected'
- *
- * @param {string} taskId
- * @param {'approve'|'reject'} action
- * @param {string} operatorKey
- * @returns {Promise<Object>} TaskWithFlags object
- */
-export async function respondToProposal(taskId, action, creds) {
-  if (!taskId || !action) throw new Error('Task ID and action are required for proposal response');
-  assertCreds(creds, 'proposal response');
-
-  const res = await fetch(`${baseUrl}/tasks/respondToProposal`, {
-    method: 'POST',
-    headers: buildHeaders(creds),
-    body: JSON.stringify({ taskId, action }),
-  });
-
-  if (!res.ok) {
-    const body = await res.text().catch(() => '');
-    throwApiError(res, body, `Proposal response failed: ${res.status} ${res.statusText}`);
-  }
-
-  const data = await res.json().catch(() => null);
-  const task = extractTask(data);
-  if (!task) throw new Error('Invalid response: proposal response data not found');
-  return task;
-}
-
-// ---------------------------------------------------------------------------
-// Shared Task Ledger (Pub/Sub)
-// ---------------------------------------------------------------------------
-
-/**
- * Publish a task to the shared ledger (open for any agent to pull/claim).
- * POST /tasks/ledger/publish
- *
- * Creates a task with state='proposal', proposal.proposedTo='everyone'.
- *
- * @param {Object} payload
- * @param {string}  payload.description
- * @param {string}  [payload.chatId]
- * @param {string}  [payload.payerId]
- * @param {string}  [payload.parentTaskId]
- * @param {Object}  [payload.contract]
- * @param {Object}  [payload.perspective]
- * @param {string}  operatorKey
- * @returns {Promise<Object>} Task object
- */
-export async function publishToLedger(payload, creds) {
-  assertCreds(creds, 'ledger publish');
-  const res = await fetch(`${TASK_BASE_URL}/ledger/publish`, {
-    method: 'POST',
-    headers: buildHeaders(creds),
-    body: JSON.stringify(payload || {}),
-  });
-  if (!res.ok) {
-    const body = await res.text().catch(() => '');
-    throwApiError(res, body, `Ledger publish failed: ${res.status}`);
-  }
-  const data = await res.json().catch(() => null);
-  return extractTask(data);
-}
-
-/**
- * Pull open tasks from the ledger (for agents to accept/ignore or claim).
- * POST /tasks/ledger/pull
- *
- * @param {Object}  [options]
- * @param {number}  [options.limit]   - max tasks to return (default 50, max 100)
- * @param {string}  [options.since]   - ISO date string, only return tasks created after this
- * @param {string}  operatorKey
- * @returns {Promise<Object[]>} Array of Task objects
- */
-export async function pullFromLedger(options, creds) {
-  const headers = buildHeaders(creds);
-  const res = await fetch(`${TASK_BASE_URL}/ledger/pull`, {
-    method: 'POST',
-    headers,
-    body: JSON.stringify(options || {}),
-  });
-  if (!res.ok) {
-    const body = await res.text().catch(() => '');
-    throwApiError(res, body, `Ledger pull failed: ${res.status}`);
-  }
-  const data = await res.json().catch(() => null);
-  return data?.tasks ?? [];
-}
-
-/**
- * Claim a ledger task so only this agent works on it.
- * POST /tasks/ledger/claim
- *
- * Atomically sets executorId and transitions state proposal→active.
- *
- * @param {string} taskId
- * @param {string} operatorKey
- * @returns {Promise<Object>} TaskWithFlags object
- */
-export async function claimLedgerTask(taskId, creds) {
-  if (!taskId) throw new Error('taskId is required');
-  assertCreds(creds, 'ledger claim');
-  const res = await fetch(`${TASK_BASE_URL}/ledger/claim`, {
-    method: 'POST',
-    headers: buildHeaders(creds),
-    body: JSON.stringify({ taskId }),
-  });
-  if (!res.ok) {
-    const body = await res.text().catch(() => '');
-    throwApiError(res, body, `Ledger claim failed: ${res.status}`);
-  }
-  const data = await res.json().catch(() => null);
-  if (!data?.ok) throw new Error(data?.error || 'Claim failed');
-  return data.task;
-}