@aifabrix/builder 2.51.0 → 2.52.0

package/lib/api/index.js

@@ -79,7 +79,7 @@ class ApiClient {
       headers['Content-Type'] = 'application/json';
     }
 
-    // User token (bearer) → Authorization: Bearer; application token (client-token) → x-client-token
+    // User token (bearer) → Authorization: Bearer; app token (client-token) → x-client-token.
     if (this.authConfig.type === 'bootstrap' && this.authConfig.encryptionKey) {
       headers['x-encryption-key'] = String(this.authConfig.encryptionKey);
     } else if (this.authConfig.token) {
@@ -160,7 +160,10 @@ class ApiClient {
       transport.timeoutMs = options.timeoutMs;
     }
 
-    if (this.authConfig.type === 'bearer' || this.authConfig.type === 'client-token') {
+    if (
+      this.authConfig.type === 'bearer' ||
+      this.authConfig.type === 'client-token'
+    ) {
       // Pass full authConfig to enable proper token refresh using controller URL
       return await authenticatedApiCall(url, transport, this.authConfig);
     }
@@ -213,7 +216,10 @@ class ApiClient {
       requestOptions.timeoutMs = options.timeoutMs;
     }
 
-    if (this.authConfig.type === 'bearer' || this.authConfig.type === 'client-token') {
+    if (
+      this.authConfig.type === 'bearer' ||
+      this.authConfig.type === 'client-token'
+    ) {
       // Pass full authConfig to enable proper token refresh using controller URL
       return await authenticatedApiCall(url, requestOptions, this.authConfig);
     }
@@ -241,7 +247,9 @@ class ApiClient {
       body: formData
     };
 
-    const hasToken = this.authConfig.type === 'bearer' || this.authConfig.type === 'client-token';
+    const hasToken =
+      this.authConfig.type === 'bearer' ||
+      this.authConfig.type === 'client-token';
     if (hasToken && this.authConfig.token) {
       return await authenticatedApiCall(url, requestOptions, this.authConfig);
     }
@@ -272,7 +280,10 @@ class ApiClient {
       requestOptions.body = JSON.stringify(options.body);
     }
 
-    if (this.authConfig.type === 'bearer' || this.authConfig.type === 'client-token') {
+    if (
+      this.authConfig.type === 'bearer' ||
+      this.authConfig.type === 'client-token'
+    ) {
       // Pass full authConfig to enable proper token refresh using controller URL
       return await authenticatedApiCall(url, requestOptions, this.authConfig);
     }
@@ -303,7 +314,10 @@ class ApiClient {
       requestOptions.body = JSON.stringify(options.body);
     }
 
-    if (this.authConfig.type === 'bearer' || this.authConfig.type === 'client-token') {
+    if (
+      this.authConfig.type === 'bearer' ||
+      this.authConfig.type === 'client-token'
+    ) {
       // Pass full authConfig to enable proper token refresh using controller URL
       return await authenticatedApiCall(url, requestOptions, this.authConfig);
     }
@@ -329,7 +343,10 @@ class ApiClient {
       headers
     };
 
-    if (this.authConfig.type === 'bearer' || this.authConfig.type === 'client-token') {
+    if (
+      this.authConfig.type === 'bearer' ||
+      this.authConfig.type === 'client-token'
+    ) {
       // Pass full authConfig to enable proper token refresh using controller URL
       return await authenticatedApiCall(url, requestOptions, this.authConfig);
     }

package/lib/api/pipeline.api.js

@@ -249,13 +249,51 @@ async function testDatasourceViaPipeline({ dataplaneUrl, systemKey, datasourceKe
  */
 /** Multi-datasource publish often exceeds the default 30s HTTP timeout. */
 const PIPELINE_UPLOAD_TIMEOUT_MS = 300000;
+const PIPELINE_UPLOAD_TIMEOUT_MIN_MS = 5000;
+const PIPELINE_UPLOAD_TIMEOUT_MAX_MS = 45 * 60 * 1000;
 
-async function uploadApplicationViaPipeline(dataplaneUrl, authConfig, payload) {
+/**
+ * Resolve pipeline upload timeout (ms) for HTTP + dataplane budget.
+ * @param {number|string|undefined|null} raw
+ * @returns {number}
+ */
+function resolvePipelineUploadTimeoutMs(raw) {
+  if (raw === undefined || raw === null || raw === '') {
+    return PIPELINE_UPLOAD_TIMEOUT_MS;
+  }
+  const n = typeof raw === 'number' ? raw : Number(raw);
+  if (!Number.isFinite(n) || n <= 0) {
+    throw new Error(
+      `--timeout must be a positive number of milliseconds (got ${String(raw)})`
+    );
+  }
+  return Math.min(
+    PIPELINE_UPLOAD_TIMEOUT_MAX_MS,
+    Math.max(PIPELINE_UPLOAD_TIMEOUT_MIN_MS, Math.floor(n))
+  );
+}
+
+/**
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {Object} payload
+ * @param {Object} [options]
+ * @param {number|string} [options.timeoutMs] - HTTP + dataplane publish budget (default 300000)
+ */
+async function uploadApplicationViaPipeline(
+  dataplaneUrl,
+  authConfig,
+  payload,
+  options = {}
+) {
   const body = { ...payload, status: payload.status ?? 'draft' };
+  const timeoutMs = resolvePipelineUploadTimeoutMs(options.timeoutMs);
   const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.post('/api/v1/pipeline/upload', {
     body,
-    timeoutMs: PIPELINE_UPLOAD_TIMEOUT_MS
+    timeoutMs,
+    params: { timeoutMs: String(timeoutMs) },
+    headers: { 'X-Aifabrix-Timeout-Ms': String(timeoutMs) }
   });
 }
 
@@ -268,6 +306,8 @@ module.exports = {
   validatePipelineConfig,
   testSystemViaPipeline,
   testDatasourceViaPipeline,
-  uploadApplicationViaPipeline
+  uploadApplicationViaPipeline,
+  resolvePipelineUploadTimeoutMs,
+  PIPELINE_UPLOAD_TIMEOUT_MS
 };
 

package/lib/api/records-bulk.api.js

@@ -7,6 +7,26 @@
 const { createDataplaneApiClient } = require('./index');
 const { unwrapApiData } = require('../utils/external-system-readiness-core');
 
+/** Default HTTP budget for records/bulk (ABAC projection can exceed 30s under load). */
+const DEFAULT_BULK_SYNC_TIMEOUT_MS = 120000;
+
+/**
+ * Resolve per-request timeout for bulk sync.
+ * @param {Object} [transportOpts]
+ * @returns {number}
+ */
+function resolveBulkSyncTimeoutMs(transportOpts = {}) {
+  const raw = transportOpts.timeoutMs ?? transportOpts.timeout;
+  if (raw === undefined || raw === null || raw === '') {
+    return DEFAULT_BULK_SYNC_TIMEOUT_MS;
+  }
+  const n = typeof raw === 'number' ? raw : parseInt(String(raw), 10);
+  if (!Number.isFinite(n) || n <= 0) {
+    return DEFAULT_BULK_SYNC_TIMEOUT_MS;
+  }
+  return n;
+}
+
 /**
  * Bulk sync external records for a datasource.
  * POST /api/v1/data-storage/{sourceIdOrKey}/records/bulk
@@ -16,13 +36,16 @@ const { unwrapApiData } = require('../utils/external-system-readiness-core');
  * @param {string} sourceIdOrKey
  * @param {Object} authConfig
  * @param {import('./types/records-bulk.types').ExternalRecordBulkRequest} body
+ * @param {Object} [transportOpts]
+ * @param {number} [transportOpts.timeoutMs] - Per-request HTTP timeout (default 120000)
  * @returns {Promise<import('./types/records-bulk.types').ExternalRecordBulkResponse>}
  */
-async function bulkSyncRecords(dataplaneUrl, sourceIdOrKey, authConfig, body) {
+async function bulkSyncRecords(dataplaneUrl, sourceIdOrKey, authConfig, body, transportOpts = {}) {
   const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const timeoutMs = resolveBulkSyncTimeoutMs(transportOpts);
   const res = await client.post(
     `/api/v1/data-storage/${encodeURIComponent(sourceIdOrKey)}/records/bulk`,
-    { body }
+    { body, timeoutMs }
   );
   if (res && res.success === false) {
     const msg =
@@ -39,5 +62,7 @@ async function bulkSyncRecords(dataplaneUrl, sourceIdOrKey, authConfig, body) {
 }
 
 module.exports = {
-  bulkSyncRecords
+  bulkSyncRecords,
+  resolveBulkSyncTimeoutMs,
+  DEFAULT_BULK_SYNC_TIMEOUT_MS
 };

package/lib/api/types/evidence.types.js

@@ -1,11 +1,11 @@
 /**
  * @fileoverview JSDoc types for Evidence Fabrix dataplane API.
  * @author AI Fabrix Team
- * @version 1.0.0
+ * @version 1.1.0
  */
 
 /**
- * @typedef {'active' | 'disabled'} EvidenceStatus
+ * @typedef {'candidate' | 'active' | 'disabled' | 'archived'} EvidenceStatus
  */
 
 /**
@@ -19,11 +19,44 @@
  * @property {string|null} [roleKey]
  */
 
+/**
+ * @typedef {Object} EvidenceContributionOverride
+ * @property {string} contributionKey
+ * @property {number} referenceValue
+ */
+
+/**
+ * @typedef {Object} EvidenceValueProposal
+ * @property {number|null} [primaryReferenceValue]
+ * @property {string|null} [primaryContributionKey]
+ * @property {string|null} [unit]
+ * @property {string|null} [rationale]
+ * @property {EvidenceContributionOverride[]} [overrides]
+ */
+
+/**
+ * @typedef {Object} EvidenceContributionProjectionItem
+ * @property {string} contributionKey
+ * @property {string|null} [typeRef]
+ * @property {string|null} [unit]
+ * @property {boolean} [primary]
+ * @property {number|null} [inheritedReferenceValue]
+ * @property {number|null} [effectiveReferenceValue]
+ * @property {boolean} [overridden]
+ * @property {string|null} [attributionKey]
+ * @property {string|null} [attributionBoundary]
+ * @property {string|null} [kindKey]
+ * @property {string|null} [kindVersion]
+ */
+
 /**
  * @typedef {Object} EvidenceRow
  * @property {string} id
- * @property {string} resourceType
+ * @property {string|null} [key]
+ * @property {string|null} [resourceType]
  * @property {string|null} [roleKey]
+ * @property {string|null} [kindKey]
+ * @property {string|null} [kindVersion]
  * @property {string} title
  * @property {string|null} [description]
  * @property {string} when
@@ -32,23 +65,34 @@
  * @property {EvidenceStatus} status
  * @property {number|null} [generationConfidence]
  * @property {string|null} [suggestionExplanation]
+ * @property {EvidenceContributionOverride[]|null} [contributionOverrides]
+ * @property {EvidenceValueProposal|null} [valueProposal]
+ * @property {EvidenceContributionProjectionItem[]|null} [contributionProjection]
+ * @property {string|null} [fingerprint]
+ * @property {Object|null} [provenanceSummary]
+ * @property {Object|null} [trustProjections]
  * @property {EvidenceApprovalPolicy} approval
- * @property {'human' | 'assistant'} createdByType
- * @property {string} createdById
- * @property {string} createdAt
- * @property {string} updatedAt
+ * @property {'human' | 'assistant'} [createdByType]
+ * @property {string|Object} [createdById]
+ * @property {string} [createdAt]
+ * @property {string} [updatedAt]
  */
 
 /**
  * @typedef {Object} EvidenceCreatePayload
- * @property {string} resourceType
+ * @property {string|null} [key]
+ * @property {string|null} [resourceType]
  * @property {string|null} [roleKey]
+ * @property {string|null} [kindKey]
+ * @property {string|null} [kindVersion]
  * @property {string} title
  * @property {string|null} [description]
  * @property {string} when
  * @property {string} expectedBehavior
  * @property {number|null} [order]
  * @property {EvidenceStatus} [status]
+ * @property {EvidenceContributionOverride[]} [contributionOverrides]
+ * @property {string|null} [suggestionExplanation]
  * @property {EvidenceApprovalPolicy} [approval]
  */
 
@@ -62,6 +106,110 @@
  * @property {string} [roleKey]
  * @property {boolean} [genericOnly]
  * @property {EvidenceStatus} [status]
+ * @property {string} [kindKey]
+ * @property {string} [aspect]
+ * @property {string} [search]
+ * @property {number} [limit]
+ * @property {number} [offset]
+ */
+
+/**
+ * @typedef {Object} EvidenceMetadataKind
+ * @property {string|null} key
+ * @property {string|null} version
+ * @property {string|null} [displayName]
+ * @property {string|null} [purpose]
+ */
+
+/**
+ * @typedef {Object} EvidenceMetadataResourceType
+ * @property {string|null} key
+ * @property {string|null} [displayName]
+ * @property {string|null} [category]
+ */
+
+/**
+ * @typedef {Object} EvidenceAuthoringMetadata
+ * @property {string} roleKey
+ * @property {EvidenceMetadataKind[]} evidenceKinds
+ * @property {string[]} aspects
+ * @property {EvidenceMetadataResourceType[]} resourceTypes
+ * @property {string[]} assistantCapabilities
+ * @property {string[]} writableFields
+ * @property {string[]} requiredFields
+ * @property {Object} constraints
+ * @property {Object} constraints.certification
+ * @property {string} constraints.certification.validationStatus
+ * @property {string} constraints.certification.candidateStatus
+ * @property {Object} constraints.activation
+ * @property {boolean} constraints.activation.requiresCertified
+ * @property {boolean} constraints.activation.requiresAuthority
+ */
+
+/**
+ * @typedef {EvidenceListParams & { roleKey: string }} EvidenceDownloadParams
+ */
+
+/**
+ * @typedef {Object} EvidenceDownloadResponse
+ * @property {string} roleKey
+ * @property {number} count
+ * @property {EvidenceRow[]} data
+ */
+
+/**
+ * @typedef {Object} EvidenceUploadRequest
+ * @property {string} roleKey
+ * @property {EvidenceCreatePayload[]} rows
+ * @property {string} [comment]
+ */
+
+/**
+ * @typedef {Object} EvidenceUploadAcceptedItem
+ * @property {number} index
+ * @property {string} evidenceRef
+ * @property {string} status
+ */
+
+/**
+ * @typedef {Object} EvidenceUploadRejectedItem
+ * @property {number} index
+ * @property {string} error
+ * @property {string} [evidenceRef]
+ * @property {Object[]} [issues]
+ */
+
+/**
+ * @typedef {Object} EvidenceUploadCertifiedItem
+ * @property {number} index
+ * @property {string} evidenceRef
+ * @property {string} status
+ * @property {Object} data
+ */
+
+/**
+ * @typedef {Object} EvidenceUploadResponse
+ * @property {string} roleKey
+ * @property {number} inserted
+ * @property {number} updated
+ * @property {EvidenceUploadAcceptedItem[]} accepted
+ * @property {EvidenceUploadRejectedItem[]} rejected
+ * @property {Object[]} warnings
+ * @property {EvidenceUploadCertifiedItem[]} certified
+ * @property {boolean} readyToActivate
+ */
+
+/**
+ * @typedef {Object} EvidenceActivateRequest
+ * @property {string[]} evidenceIds
+ */
+
+/**
+ * @typedef {Object} EvidenceActivateResponse
+ * @property {number} requested
+ * @property {Array<{ evidenceId: string, result: Object }>} activated
+ * @property {Array<{ evidenceId: string, error: string, status: number|null }>} failed
+ * @property {boolean} success
  */
 
 module.exports = {};

package/lib/api/work.api.js

@@ -0,0 +1,283 @@
+/**
+ * @fileoverview Dataplane work runtime API client for role-assistant test flows.
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { createDataplaneApiClient } = require('./index');
+const { unwrapApiData } = require('../utils/external-system-readiness-core');
+
+/** Work Hub plan create runs LLM planning; 30s default is too short under load/reload. */
+const WORK_PLAN_TIMEOUT_MS = 120000;
+/** Task poll / result fetch can wait on Celery + CIP. */
+const WORK_TASK_TIMEOUT_MS = 60000;
+
+/**
+ * Some dataplane work routes return `{ data: { … } }` while ApiClient already
+ * wraps once — peel a nested `data` envelope when top-level identity is missing.
+ */
+function unwrapWorkPayload(res) {
+  const cur = unwrapApiData(res);
+  if (!cur || typeof cur !== 'object' || Array.isArray(cur)) {
+    return cur;
+  }
+  if (cur.planId || cur.taskId || cur.processExecutionId || cur.status || cur.schemaVersion) {
+    return cur;
+  }
+  if (cur.data && typeof cur.data === 'object' && !Array.isArray(cur.data)) {
+    return cur.data;
+  }
+  return cur;
+}
+
+function extractApiErrorMessage(res, fallbackMessage) {
+  return (
+    (res &&
+      res.error &&
+      (res.error.formattedError || res.error.error || res.error.message || res.error.detail)) ||
+    (res && (res.formattedError || res.error || res.message)) ||
+    fallbackMessage
+  );
+}
+
+function assertObjectShape(value, fallbackMessage) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(fallbackMessage);
+  }
+}
+
+/**
+ * POST /api/v1/work/start
+ * @requiresPermission {Dataplane} worker-task:create
+ * @async
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {Object} body
+ * @returns {Promise<Object>}
+ */
+async function startWorkIntent(dataplaneUrl, authConfig, body) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.post('/api/v1/work/start', { body });
+  if (res && res.success === false) {
+    throw new Error(extractApiErrorMessage(res, 'work.start request failed'));
+  }
+  const unwrapped = unwrapWorkPayload(res);
+  assertObjectShape(unwrapped, 'work.start returned an unexpected response shape');
+  return unwrapped;
+}
+
+/**
+ * GET /api/v1/work/executions/{processExecutionId}
+ * @requiresPermission {Dataplane} worker-task:read
+ * @async
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {string} processExecutionId
+ * @returns {Promise<Object>}
+ */
+async function getWorkExecutionStatus(dataplaneUrl, authConfig, processExecutionId) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const encodedId = encodeURIComponent(String(processExecutionId));
+  const res = await client.get(`/api/v1/work/executions/${encodedId}`, {
+    timeoutMs: WORK_TASK_TIMEOUT_MS
+  });
+  if (res && res.success === false) {
+    throw new Error(extractApiErrorMessage(res, 'work.status request failed'));
+  }
+  const unwrapped = unwrapWorkPayload(res);
+  assertObjectShape(unwrapped, 'work.status returned an unexpected response shape');
+  return unwrapped;
+}
+
+/**
+ * POST /api/v1/work/executions/{processExecutionId}/respond
+ * @requiresPermission {Dataplane} worker-task:update
+ * @async
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {string} processExecutionId
+ * @param {Object} body
+ * @returns {Promise<Object>}
+ */
+async function respondWorkExecution(dataplaneUrl, authConfig, processExecutionId, body) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const encodedId = encodeURIComponent(String(processExecutionId));
+  const res = await client.post(`/api/v1/work/executions/${encodedId}/respond`, {
+    body,
+    timeoutMs: WORK_TASK_TIMEOUT_MS
+  });
+  if (res && res.success === false) {
+    throw new Error(extractApiErrorMessage(res, 'work.respond request failed'));
+  }
+  const unwrapped = unwrapWorkPayload(res);
+  assertObjectShape(unwrapped, 'work.respond returned an unexpected response shape');
+  return unwrapped;
+}
+
+/**
+ * POST /api/v1/work/executions/{processExecutionId}/continue
+ * @requiresPermission {Dataplane} worker-task:update
+ * @async
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {string} processExecutionId
+ * @param {Object} [body]
+ * @returns {Promise<Object>}
+ */
+async function continueWorkExecution(dataplaneUrl, authConfig, processExecutionId, body = {}) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const encodedId = encodeURIComponent(String(processExecutionId));
+  const res = await client.post(`/api/v1/work/executions/${encodedId}/continue`, {
+    body,
+    timeoutMs: WORK_TASK_TIMEOUT_MS
+  });
+  if (res && res.success === false) {
+    throw new Error(extractApiErrorMessage(res, 'work.continue request failed'));
+  }
+  const unwrapped = unwrapWorkPayload(res);
+  assertObjectShape(unwrapped, 'work.continue returned an unexpected response shape');
+  return unwrapped;
+}
+
+/**
+ * GET /api/v1/work/executions/{processExecutionId}/result
+ * @requiresPermission {Dataplane} worker-task:read
+ * @async
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {string} processExecutionId
+ * @param {Object} [query]
+ * @returns {Promise<Object>}
+ */
+async function getWorkExecutionResult(dataplaneUrl, authConfig, processExecutionId, query = {}) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const encodedId = encodeURIComponent(String(processExecutionId));
+  const params = {};
+  if (query && typeof query === 'object') {
+    if (query.requestedDepth) {
+      params.requestedDepth = String(query.requestedDepth);
+    }
+    if (query.format) {
+      params.format = String(query.format);
+    }
+    if (query.projection) {
+      params.projection = String(query.projection);
+    }
+  }
+  const res = await client.get(`/api/v1/work/executions/${encodedId}/result`, {
+    params,
+    timeoutMs: WORK_TASK_TIMEOUT_MS
+  });
+  if (res && res.success === false) {
+    throw new Error(extractApiErrorMessage(res, 'work.result request failed'));
+  }
+  const unwrapped = unwrapWorkPayload(res);
+  assertObjectShape(unwrapped, 'work.result returned an unexpected response shape');
+  return unwrapped;
+}
+
+/**
+ * POST /api/v1/work/tasks/plan — Work Hub plan (objective → Role Assistant).
+ * @requiresPermission {Dataplane} worker-task:create
+ */
+async function createWorkTaskPlan(dataplaneUrl, authConfig, body) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.post('/api/v1/work/tasks/plan', {
+    body,
+    timeoutMs: WORK_PLAN_TIMEOUT_MS
+  });
+  if (res && res.success === false) {
+    throw new Error(extractApiErrorMessage(res, 'work.tasks.plan request failed'));
+  }
+  const unwrapped = unwrapWorkPayload(res);
+  assertObjectShape(unwrapped, 'work.tasks.plan returned an unexpected response shape');
+  return unwrapped;
+}
+
+/**
+ * POST /api/v1/work/tasks/plan/{planId}/activate-assistant
+ * @requiresPermission {Dataplane} worker-task:update
+ */
+async function activateWorkPlanAssistant(dataplaneUrl, authConfig, planId, body) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const encodedId = encodeURIComponent(String(planId));
+  const res = await client.post(`/api/v1/work/tasks/plan/${encodedId}/activate-assistant`, {
+    body,
+    timeoutMs: WORK_TASK_TIMEOUT_MS
+  });
+  if (res && res.success === false) {
+    throw new Error(extractApiErrorMessage(res, 'work.tasks.plan.activate-assistant failed'));
+  }
+  const unwrapped = unwrapWorkPayload(res);
+  assertObjectShape(unwrapped, 'activate-assistant returned an unexpected response shape');
+  return unwrapped;
+}
+
+/**
+ * POST /api/v1/work/tasks/plan/{planId}/accept
+ * @requiresPermission {Dataplane} worker-task:update
+ */
+async function acceptWorkTaskPlan(dataplaneUrl, authConfig, planId, body = {}) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const encodedId = encodeURIComponent(String(planId));
+  const res = await client.post(`/api/v1/work/tasks/plan/${encodedId}/accept`, {
+    body: { planId, ...body },
+    timeoutMs: WORK_PLAN_TIMEOUT_MS
+  });
+  if (res && res.success === false) {
+    throw new Error(extractApiErrorMessage(res, 'work.tasks.plan.accept failed'));
+  }
+  const unwrapped = unwrapWorkPayload(res);
+  assertObjectShape(unwrapped, 'work.tasks.plan.accept returned an unexpected response shape');
+  return unwrapped;
+}
+
+/**
+ * GET /api/v1/work/tasks/{taskId}
+ * @requiresPermission {Dataplane} worker-task:read
+ */
+async function getWorkTask(dataplaneUrl, authConfig, taskId) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const encodedId = encodeURIComponent(String(taskId));
+  const res = await client.get(`/api/v1/work/tasks/${encodedId}`, {
+    timeoutMs: WORK_TASK_TIMEOUT_MS
+  });
+  if (res && res.success === false) {
+    throw new Error(extractApiErrorMessage(res, 'work.tasks.get failed'));
+  }
+  const unwrapped = unwrapWorkPayload(res);
+  assertObjectShape(unwrapped, 'work.tasks.get returned an unexpected response shape');
+  return unwrapped;
+}
+
+/**
+ * POST /api/v1/work/tasks/{taskId}/approve
+ * @requiresPermission {Dataplane} worker-task:update
+ */
+async function approveWorkTask(dataplaneUrl, authConfig, taskId, body = {}) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const encodedId = encodeURIComponent(String(taskId));
+  const res = await client.post(`/api/v1/work/tasks/${encodedId}/approve`, {
+    body: { taskId, ...body },
+    timeoutMs: WORK_TASK_TIMEOUT_MS
+  });
+  if (res && res.success === false) {
+    throw new Error(extractApiErrorMessage(res, 'work.tasks.approve failed'));
+  }
+  return unwrapWorkPayload(res);
+}
+
+module.exports = {
+  startWorkIntent,
+  getWorkExecutionStatus,
+  respondWorkExecution,
+  continueWorkExecution,
+  getWorkExecutionResult,
+  createWorkTaskPlan,
+  activateWorkPlanAssistant,
+  acceptWorkTaskPlan,
+  getWorkTask,
+  approveWorkTask
+};