@bpmsoftwaresolutions/ai-engine-client 0.1.0 → 1.0.0-beta.1

package/src/index.js

@@ -1,162 +1,1012 @@
-const DEFAULT_TIMEOUT_MS = 30000;
-
-function trimTrailingSlash(value) {
-  return String(value || '').replace(/\/+$/, '');
-}
-
-function appendQuery(url, query) {
-  const target = new URL(url);
-  for (const [key, value] of Object.entries(query || {})) {
-    if (value === undefined || value === null || value === '') {
-      continue;
-    }
-    target.searchParams.set(key, String(value));
-  }
-  return target;
-}
-
-async function readJson(response) {
-  const contentType = response.headers.get('content-type') || '';
-  if (contentType.includes('application/json')) {
-    return response.json();
-  }
-  const text = await response.text();
-  return { message: text };
-}
-
-export class AIEngineClient {
-  constructor({ baseUrl, apiKey, actorId, fetchImpl, timeoutMs } = {}) {
-    if (!baseUrl) {
-      throw new Error('baseUrl is required.');
-    }
-    this.baseUrl = trimTrailingSlash(baseUrl);
-    this.apiKey = apiKey || null;
-    this.actorId = actorId || 'sdk:npm-ai-engine-client';
-    this.fetchImpl = fetchImpl || globalThis.fetch;
-    this.timeoutMs = timeoutMs || DEFAULT_TIMEOUT_MS;
-    if (typeof this.fetchImpl !== 'function') {
-      throw new Error('A fetch implementation is required. Use Node 18+ or supply fetchImpl.');
-    }
-  }
-
-  static fromEnv(options = {}) {
-    return new AIEngineClient({
-      baseUrl: options.baseUrl || process.env.AI_ENGINE_BASE_URL || process.env.AI_ENGINE_API_BASE_URL,
-      apiKey: options.apiKey || process.env.AI_ENGINE_API_KEY || null,
-      actorId: options.actorId || process.env.AI_ENGINE_ACTOR_ID || 'sdk:npm-ai-engine-client'
-    });
-  }
-
-  async ping() {
-    const [health, workflow] = await Promise.all([
-      this._request('/healthz'),
-      this.currentWorkflowStatus()
-    ]);
-    return {
-      status: health.status || 'ok',
-      workflow_name: workflow?.summary?.workflow_name || null,
-      run_status: workflow?.summary?.run_status || null,
-      base_url: this.baseUrl
-    };
-  }
-
-  async currentWorkflowStatus() {
-    return this._request('/api/operator/current-workflow-status');
-  }
-
-  async currentArchitectureIntegrityStatus() {
-    return this._request('/api/operator/current-architecture-integrity-status');
-  }
-
-  async currentSecurityGovernanceStatus({ environment, topN } = {}) {
-    return this._request('/api/operator/current-security-governance-status', {
-      query: {
-        environment,
-        top_n: topN
-      }
-    });
-  }
-
-  async getCommandCard({ commandKey, alias, intentText, requestedBy } = {}) {
-    return this._request('/api/operator/retrieval/wrapper/command-card', {
-      query: {
-        command_key: commandKey,
-        alias,
-        intent_text: intentText,
-        requested_by: requestedBy
-      }
-    });
-  }
-
-  async resolveOperatingProcedure({ procedureKey, intentText, requestedBy } = {}) {
-    return this._request('/api/operator/retrieval/wrapper/operating-procedure', {
-      query: {
-        procedure_key: procedureKey,
-        intent_text: intentText,
-        requested_by: requestedBy
-      }
-    });
-  }
-
-  async getSymbolDefinition({ symbolKey, qualifiedName, symbolName, projectScope, includeCode = true, maxLines = 120, requestedBy } = {}) {
-    return this._request('/api/operator/retrieval/wrapper/symbol-definition', {
-      query: {
-        symbol_key: symbolKey,
-        qualified_name: qualifiedName,
-        symbol_name: symbolName,
-        project_scope: projectScope,
-        include_code: includeCode,
-        max_lines: maxLines,
-        requested_by: requestedBy
-      }
-    });
-  }
-
-  async getRelatedCode({ symbolKey, qualifiedName, relationshipType, depth = 1, includeCode = false, maxLines = 80, requestedBy } = {}) {
-    return this._request('/api/operator/retrieval/wrapper/related-code', {
-      query: {
-        symbol_key: symbolKey,
-        qualified_name: qualifiedName,
-        relationship_type: relationshipType,
-        depth,
-        include_code: includeCode,
-        max_lines: maxLines,
-        requested_by: requestedBy
-      }
-    });
-  }
-
-  async _request(path, { method = 'GET', query, headers, body } = {}) {
-    const url = appendQuery(`${this.baseUrl}${path}`, query);
-    const controller = new AbortController();
-    const timeoutHandle = setTimeout(() => controller.abort(), this.timeoutMs);
-    try {
-      const response = await this.fetchImpl(url, {
-        method,
-        headers: {
-          accept: 'application/json',
-          'content-type': body ? 'application/json' : undefined,
-          'x-actor-id': this.actorId,
-          authorization: this.apiKey ? `Bearer ${this.apiKey}` : undefined,
-          ...headers
-        },
-        body: body ? JSON.stringify(body) : undefined,
-        signal: controller.signal
-      });
-      const payload = await readJson(response);
-      if (!response.ok) {
-        const error = new Error(payload?.message || payload?.error || `Request failed with status ${response.status}.`);
-        error.status = response.status;
-        error.payload = payload;
-        throw error;
-      }
-      return payload;
-    } finally {
-      clearTimeout(timeoutHandle);
-    }
-  }
-}
-
-export function createAIEngineClient(options) {
-  return new AIEngineClient(options);
-}
+const DEFAULT_TIMEOUT_MS = 30000;
+
+function trimTrailingSlash(value) {
+  return String(value || '').replace(/\/+$/, '');
+}
+
+function appendQuery(url, query) {
+  const target = new URL(url);
+  for (const [key, value] of Object.entries(query || {})) {
+    if (value === undefined || value === null || value === '') continue;
+    target.searchParams.set(key, String(value));
+  }
+  return target;
+}
+
+async function readJson(response) {
+  const contentType = response.headers.get('content-type') || '';
+  if (contentType.includes('application/json')) return response.json();
+  const text = await response.text();
+  return { message: text };
+}
+
+export class AIEngineClient {
+  constructor({ baseUrl, apiKey, actorId, fetchImpl, timeoutMs } = {}) {
+    if (!baseUrl) throw new Error('baseUrl is required.');
+    this.baseUrl = trimTrailingSlash(baseUrl);
+    this.apiKey = apiKey || null;
+    this.actorId = actorId || 'sdk:npm-ai-engine-client';
+    this.fetchImpl = fetchImpl || globalThis.fetch;
+    this.timeoutMs = timeoutMs || DEFAULT_TIMEOUT_MS;
+    if (typeof this.fetchImpl !== 'function') {
+      throw new Error('A fetch implementation is required. Use Node 18+ or supply fetchImpl.');
+    }
+  }
+
+  static fromEnv(options = {}) {
+    return new AIEngineClient({
+      baseUrl: options.baseUrl || process.env.AI_ENGINE_BASE_URL || process.env.AI_ENGINE_API_BASE_URL,
+      apiKey: options.apiKey || process.env.AI_ENGINE_API_KEY || null,
+      actorId: options.actorId || process.env.AI_ENGINE_ACTOR_ID || 'sdk:npm-ai-engine-client',
+    });
+  }
+
+  // ─── Health ────────────────────────────────────────────────────────────────
+
+  async ping() {
+    const [health, workflow] = await Promise.all([
+      this._request('/healthz'),
+      this.currentWorkflowStatus(),
+    ]);
+    return {
+      status: health.status || 'ok',
+      workflow_name: workflow?.summary?.workflow_name || null,
+      run_status: workflow?.summary?.run_status || null,
+      base_url: this.baseUrl,
+    };
+  }
+
+  // ─── Operator Status ───────────────────────────────────────────────────────
+
+  async currentWorkflowStatus() {
+    return this._request('/api/operator/current-workflow-status');
+  }
+
+  async currentArchitectureIntegrityStatus() {
+    return this._request('/api/operator/current-architecture-integrity-status');
+  }
+
+  async currentSecurityGovernanceStatus({ environment, topN } = {}) {
+    return this._request('/api/operator/current-security-governance-status', {
+      query: { environment, top_n: topN },
+    });
+  }
+
+  async currentCodebaseShapeStatus() {
+    return this._request('/api/operator/current-codebase-shape-status');
+  }
+
+  async getLatestMemoryProjection() {
+    return this._request('/api/operator/latest-memory-projection');
+  }
+
+  async getDashboard() {
+    return this._request('/api/dashboard');
+  }
+
+  // ─── Retrieval Wrapper ─────────────────────────────────────────────────────
+
+  async getCommandCard({ commandKey, alias, intentText, requestedBy } = {}) {
+    return this._request('/api/operator/retrieval/wrapper/command-card', {
+      query: { command_key: commandKey, alias, intent_text: intentText, requested_by: requestedBy },
+    });
+  }
+
+  async resolveOperatingProcedure({ procedureKey, intentText, requestedBy } = {}) {
+    return this._request('/api/operator/retrieval/wrapper/operating-procedure', {
+      query: { procedure_key: procedureKey, intent_text: intentText, requested_by: requestedBy },
+    });
+  }
+
+  async getSymbolDefinition({ symbolKey, qualifiedName, symbolName, projectScope, includeCode = true, maxLines = 120, requestedBy } = {}) {
+    return this._request('/api/operator/retrieval/wrapper/symbol-definition', {
+      query: {
+        symbol_key: symbolKey,
+        qualified_name: qualifiedName,
+        symbol_name: symbolName,
+        project_scope: projectScope,
+        include_code: includeCode,
+        max_lines: maxLines,
+        requested_by: requestedBy,
+      },
+    });
+  }
+
+  async getRelatedCode({ symbolKey, qualifiedName, relationshipType, depth = 1, includeCode = false, maxLines = 80, requestedBy } = {}) {
+    return this._request('/api/operator/retrieval/wrapper/related-code', {
+      query: {
+        symbol_key: symbolKey,
+        qualified_name: qualifiedName,
+        relationship_type: relationshipType,
+        depth,
+        include_code: includeCode,
+        max_lines: maxLines,
+        requested_by: requestedBy,
+      },
+    });
+  }
+
+  // ─── Repo Inventory ───────────────────────────────────────────────────────
+
+  async listRepositories({ limit } = {}) {
+    return this._request('/api/repo/repositories', {
+      query: { limit },
+    });
+  }
+
+  async getRepository(repositoryId) {
+    return this._request(`/api/repo/repositories/${repositoryId}`);
+  }
+
+  async listProjects({ repositoryId, repoKey, limit } = {}) {
+    return this._request('/api/repo/projects', {
+      query: { repository_id: repositoryId, repo_key: repoKey, limit },
+    });
+  }
+
+  async getProject(projectId) {
+    return this._request(`/api/repo/projects/${projectId}`);
+  }
+
+  async listCodeFiles({ repositoryId, projectId, language, pathPrefix, page = 1, pageSize = 50 } = {}) {
+    return this._request('/api/repo/files', {
+      query: {
+        repository_id: repositoryId,
+        project_id: projectId,
+        language,
+        path_prefix: pathPrefix,
+        page,
+        page_size: pageSize,
+      },
+    });
+  }
+
+  async getCodeFile(fileId) {
+    return this._request(`/api/repo/files/${fileId}`);
+  }
+
+  async listCodeSymbolsByFile(fileId, { limit = 500 } = {}) {
+    return this._request(`/api/repo/files/${fileId}/symbols`, {
+      query: { limit },
+    });
+  }
+
+  async getCodeSymbol(symbolId, { includeCode = false, maxLines = 120 } = {}) {
+    return this._request(`/api/repo/symbols/${symbolId}`, {
+      query: { include_code: includeCode, max_lines: maxLines },
+    });
+  }
+
+  async searchSymbols({ query, projectScope, maxResults = 10 } = {}) {
+    return this._request('/api/repo/symbols/search', {
+      query: { query, project_scope: projectScope, max_results: maxResults },
+    });
+  }
+
+  async getSymbolRelationships(symbolId, { relationshipType, depth = 1 } = {}) {
+    return this._request(`/api/repo/symbols/${symbolId}/relationships`, {
+      query: { relationship_type: relationshipType, depth },
+    });
+  }
+
+  // ─── Retrieval Management ──────────────────────────────────────────────────
+
+  async getRetrievalStatus() {
+    return this._request('/api/operator/retrieval/status');
+  }
+
+  async getRetrievalProfileMetrics() {
+    return this._request('/api/operator/retrieval/profiles/metrics');
+  }
+
+  async getRetrievalFeedbackMetrics() {
+    return this._request('/api/operator/retrieval/feedback-metrics');
+  }
+
+  async getRetrievalQuery(retrievalQueryId) {
+    return this._request(`/api/operator/retrieval/queries/${retrievalQueryId}`);
+  }
+
+  async getRetrievalPacket(retrievalPacketId) {
+    return this._request(`/api/operator/retrieval/packets/${retrievalPacketId}`);
+  }
+
+  async generateRetrievalCandidates(body) {
+    return this._request('/api/operator/retrieval/generate-candidates', { method: 'POST', body });
+  }
+
+  async selectRetrievalPacket(body) {
+    return this._request('/api/operator/retrieval/select-packet', { method: 'POST', body });
+  }
+
+  async recordRetrievalFeedback(body) {
+    return this._request('/api/operator/retrieval/feedback', { method: 'POST', body });
+  }
+
+  async deriveRetrievalOptimizationCandidates(body) {
+    return this._request('/api/operator/retrieval/optimization-candidates', { method: 'POST', body });
+  }
+
+  async validatePromptAssembly(body) {
+    return this._request('/api/operator/retrieval/validate-prompt-assembly', { method: 'POST', body });
+  }
+
+  // ─── Workflows ─────────────────────────────────────────────────────────────
+
+  async listWorkflows({ status, includeSteps } = {}) {
+    return this._request('/api/workflows', {
+      query: { status, include_steps: includeSteps },
+    });
+  }
+
+  async createWorkflow({ name, slug, description, goal, governanceProfile, steps = [] } = {}) {
+    return this._request('/api/workflows', {
+      method: 'POST',
+      body: { name, slug, description, goal, governance_profile: governanceProfile, steps },
+    });
+  }
+
+  async getWorkflow(workflowId) {
+    return this._request(`/api/workflows/${workflowId}`);
+  }
+
+  async replaceWorkflowSteps(workflowId, steps) {
+    return this._request(`/api/workflows/${workflowId}/steps`, { method: 'PUT', body: { steps } });
+  }
+
+  async publishWorkflow(workflowId) {
+    return this._request(`/api/workflows/${workflowId}/publish`, { method: 'POST' });
+  }
+
+  async cloneWorkflow(workflowId) {
+    return this._request(`/api/workflows/${workflowId}/clone`, { method: 'POST' });
+  }
+
+  // ─── Workflow Governance ───────────────────────────────────────────────────
+
+  async evaluateWorkflowGovernance(workflowId) {
+    return this._request(`/api/workflows/${workflowId}/governance/evaluate`, { method: 'POST' });
+  }
+
+  async listWorkflowGovernanceDecisions(workflowId) {
+    return this._request(`/api/workflows/${workflowId}/governance/decisions`);
+  }
+
+  async getWorkflowGovernanceSimulation(workflowId) {
+    return this._request(`/api/workflows/${workflowId}/governance/simulation`);
+  }
+
+  async listWorkflowGovernanceBundles(workflowId) {
+    return this._request(`/api/workflows/${workflowId}/governance/bundles`);
+  }
+
+  async listWorkflowGovernanceApprovals(workflowId) {
+    return this._request(`/api/workflows/${workflowId}/governance/approvals`);
+  }
+
+  async listWorkflowGovernanceEvents(workflowId) {
+    return this._request(`/api/workflows/${workflowId}/governance/events`);
+  }
+
+  async getWorkflowGovernanceReview(workflowId) {
+    return this._request(`/api/workflows/${workflowId}/governance/review`);
+  }
+
+  async createWorkflowGovernanceReviewDecision(workflowId, body) {
+    return this._request(`/api/workflows/${workflowId}/governance/review-decisions`, {
+      method: 'POST', body,
+    });
+  }
+
+  // ─── Workflow Runs ─────────────────────────────────────────────────────────
+
+  async createWorkflowRun(body) {
+    return this._request('/api/workflow-runs', { method: 'POST', body });
+  }
+
+  async getWorkflowRun(workflowRunId) {
+    return this._request(`/api/workflow-runs/${workflowRunId}`);
+  }
+
+  async listWorkflowArtifacts(workflowRunId) {
+    return this._request(`/api/workflow-runs/${workflowRunId}/artifacts`);
+  }
+
+  async getWorkflowRunSubstrate(workflowRunId) {
+    return this._request(`/api/workflow-runs/${workflowRunId}/substrate`);
+  }
+
+  async resumeWorkflowRun(workflowRunId, body = {}) {
+    return this._request(`/api/workflow-runs/${workflowRunId}/resume`, { method: 'POST', body });
+  }
+
+  // ─── Workflow Inspector ────────────────────────────────────────────────────
+
+  async listRecentInspectorRuns({ limit } = {}) {
+    return this._request('/api/workflow-inspector/runs/recent', { query: { limit } });
+  }
+
+  async inspectWorkflowRun(workflowRunId) {
+    return this._request(`/api/workflow-inspector/runs/${workflowRunId}`);
+  }
+
+  // ─── Manual & Approval Tasks ───────────────────────────────────────────────
+
+  async listManualTasks() {
+    return this._request('/api/manual-tasks');
+  }
+
+  async listApprovalTasks() {
+    return this._request('/api/approval-tasks');
+  }
+
+  async completeManualTask(stepRunId, body = {}) {
+    return this._request(`/api/manual-tasks/${stepRunId}/complete`, { method: 'POST', body });
+  }
+
+  async approveTask(stepRunId, body = {}) {
+    return this._request(`/api/approval-tasks/${stepRunId}/approve`, { method: 'POST', body });
+  }
+
+  // ─── Projects & Chartering ─────────────────────────────────────────────────
+
+  async createProjectCharter({
+    projectName,
+    objective,
+    businessContext,
+    successCriteria,
+    priority,
+    constraints = [],
+    inScope = [],
+    outOfScope = [],
+    assumptions = [],
+    linkedWorkflows = [],
+    testingStrategy = {},
+    initialContext = {},
+    requestedBy,
+  } = {}) {
+    return this._request('/api/projects/charter', {
+      method: 'POST',
+      body: {
+        project_name: projectName,
+        objective,
+        business_context: businessContext,
+        success_criteria: successCriteria,
+        priority,
+        constraints,
+        in_scope: inScope,
+        out_of_scope: outOfScope,
+        assumptions,
+        linked_workflows: linkedWorkflows,
+        testing_strategy: testingStrategy,
+        initial_context: initialContext,
+        requested_by: requestedBy,
+      },
+    });
+  }
+
+  async listProjects({ limit, includeInactive, processStatus, charterStatus } = {}) {
+    return this._request('/api/operator/projects', {
+      query: {
+        limit,
+        include_inactive: includeInactive,
+        process_status: processStatus,
+        charter_status: charterStatus,
+      },
+    });
+  }
+
+  async getProject(projectId) {
+    return this._request(`/api/operator/projects/${projectId}`);
+  }
+
+  // ─── Roadmaps ──────────────────────────────────────────────────────────────
+
+  async listProjectRoadmaps({ includeInactive } = {}) {
+    return this._request('/api/operator/projects/implementation-roadmaps', {
+      query: { include_inactive: includeInactive },
+    });
+  }
+
+  async getProjectRoadmap(projectId) {
+    return this._request(`/api/operator/projects/${projectId}/implementation-roadmap`);
+  }
+
+  async getProjectRoadmapSummary(projectId) {
+    return this._request(`/api/operator/projects/${projectId}/implementation-roadmap/summary`);
+  }
+
+  async getProjectRoadmapActiveItem(projectId) {
+    return this._request(`/api/operator/projects/${projectId}/implementation-roadmap/active-item`);
+  }
+
+  async listProjectOpenTasks(projectId) {
+    return this._request(`/api/operator/projects/${projectId}/open-tasks`);
+  }
+
+  async getProjectPerformanceMetrics(projectId, { workflowId, workflowRunId, sinceUtc } = {}) {
+    return this._request(`/api/operator/projects/${projectId}/performance-metrics`, {
+      query: { workflow_id: workflowId, workflow_run_id: workflowRunId, since_utc: sinceUtc },
+    });
+  }
+
+  // ─── Implementation Tasks ──────────────────────────────────────────────────
+
+  async createImplementationTask(implementationItemId, {
+    title,
+    implementationPacketId,
+    description,
+    priority,
+    assignedTo,
+    assignedBy,
+    dueAt,
+    sortOrder,
+    notes,
+    createdBy,
+    parentTaskId,
+  } = {}) {
+    return this._request(`/api/operator/implementation-items/${implementationItemId}/tasks`, {
+      method: 'POST',
+      body: {
+        title,
+        implementation_packet_id: implementationPacketId,
+        description,
+        priority,
+        assigned_to: assignedTo,
+        assigned_by: assignedBy,
+        due_at: dueAt,
+        sort_order: sortOrder,
+        notes,
+        created_by: createdBy,
+        parent_task_id: parentTaskId,
+      },
+    });
+  }
+
+  async listImplementationTasks(implementationItemId) {
+    return this._request(`/api/operator/implementation-items/${implementationItemId}/tasks`);
+  }
+
+  async listImplementationSubtasks(taskId) {
+    return this._request(`/api/operator/implementation-item-tasks/${taskId}/subtasks`);
+  }
+
+  async updateImplementationTask(taskId, updates) {
+    return this._request(`/api/operator/implementation-item-tasks/${taskId}`, {
+      method: 'PATCH',
+      body: updates,
+    });
+  }
+
+  async assignImplementationTask(taskId, { assignedTo, assignedBy } = {}) {
+    return this._request(`/api/operator/implementation-item-tasks/${taskId}/assign`, {
+      method: 'POST',
+      body: { assigned_to: assignedTo, assigned_by: assignedBy },
+    });
+  }
+
+  async completeImplementationTask(taskId, { completedBy } = {}) {
+    return this._request(`/api/operator/implementation-item-tasks/${taskId}/complete`, {
+      method: 'POST',
+      body: { completed_by: completedBy },
+    });
+  }
+
+  // ─── Governed Implementation ───────────────────────────────────────────────
+
+  async importImplementationPacket(body) {
+    return this._request('/api/governed-implementation/packets/import', { method: 'POST', body });
+  }
+
+  async listImplementationPackets({ status, packetType } = {}) {
+    return this._request('/api/governed-implementation/packets', {
+      query: { status, packet_type: packetType },
+    });
+  }
+
+  async getImplementationPacket(packetId) {
+    return this._request(`/api/governed-implementation/packets/${packetId}`);
+  }
+
+  async updateImplementationItemStatus(implementationItemId, body) {
+    return this._request(`/api/governed-implementation/items/${implementationItemId}/status`, {
+      method: 'PATCH', body,
+    });
+  }
+
+  async addImplementationItemEvidence(implementationItemId, body) {
+    return this._request(`/api/governed-implementation/items/${implementationItemId}/evidence`, {
+      method: 'POST', body,
+    });
+  }
+
+  async addImplementationItemActivity(implementationItemId, body) {
+    return this._request(`/api/governed-implementation/items/${implementationItemId}/activity`, {
+      method: 'POST', body,
+    });
+  }
+
+  async listImplementationItemActivity(implementationItemId) {
+    return this._request(`/api/governed-implementation/items/${implementationItemId}/activity`);
+  }
+
+  async updateAcceptanceCheckStatus(implementationItemId, acceptanceCheckId, body) {
+    return this._request(
+      `/api/governed-implementation/items/${implementationItemId}/acceptance-checks/${acceptanceCheckId}/status`,
+      { method: 'PATCH', body }
+    );
+  }
+
+  async createImplementationPacketGateDecision(packetId, body) {
+    return this._request(`/api/governed-implementation/packets/${packetId}/gate-decisions`, {
+      method: 'POST', body,
+    });
+  }
+
+  async bindImplementationPacketToWorkflow(workflowId, body) {
+    return this._request(`/api/governed-implementation/workflows/${workflowId}/bindings`, {
+      method: 'POST', body,
+    });
+  }
+
+  async getWorkflowImplementationRoadmap(workflowId) {
+    return this._request(`/api/governed-implementation/workflows/${workflowId}/roadmap`);
+  }
+
+  async getWorkflowResumeContext(workflowId) {
+    return this._request(`/api/governed-implementation/workflows/${workflowId}/resume-context`);
+  }
+
+  // ─── Skills ────────────────────────────────────────────────────────────────
+
+  async currentSkillRegistryStatus() {
+    return this._request('/api/operator/current-skill-registry-status');
+  }
+
+  async getSkillContract({ skillId, skillKey } = {}) {
+    return this._request('/api/skills/contract', { query: { skill_id: skillId, skill_key: skillKey } });
+  }
+
+  async getSkillGovernance({ skillId, skillKey, skillVersionId } = {}) {
+    return this._request('/api/operator/skills/governance', {
+      query: { skill_id: skillId, skill_key: skillKey, skill_version_id: skillVersionId },
+    });
+  }
+
+  async createSkillContractDraft(body) {
+    return this._request('/api/operator/skills/contracts/drafts', { method: 'POST', body });
+  }
+
+  async recordSkillPatternReview(skillVersionId, body) {
+    return this._request(`/api/operator/skills/contracts/${skillVersionId}/pattern-reviews`, {
+      method: 'POST', body,
+    });
+  }
+
+  async approveSkillContract(skillVersionId, body = {}) {
+    return this._request(`/api/operator/skills/contracts/${skillVersionId}/approve`, {
+      method: 'POST', body,
+    });
+  }
+
+  async createWorkflowSkillContract(body) {
+    return this._request('/api/skills/workflow-contracts', { method: 'POST', body });
+  }
+
+  async listWorkflowSkillBindings(workflowId, { workflowStepId } = {}) {
+    return this._request(`/api/workflows/${workflowId}/skill-bindings`, {
+      query: { workflow_step_id: workflowStepId },
+    });
+  }
+
+  async seedFrequentOperationSkills({ createdBy } = {}) {
+    return this._request('/api/operator/skills/seed-frequent-operations', {
+      method: 'POST',
+      body: { created_by: createdBy },
+    });
+  }
+
+  // ─── Skill Governance ──────────────────────────────────────────────────────
+
+  async createSkillGovernanceChange(body) {
+    return this._request('/api/operator/skill-governance/changes', { method: 'POST', body });
+  }
+
+  async listSkillGovernanceChanges({ limit, processStatus, changeStatus } = {}) {
+    return this._request('/api/operator/skill-governance/changes', {
+      query: { limit, process_status: processStatus, change_status: changeStatus },
+    });
+  }
+
+  async getSkillGovernanceChange(governanceChangeId) {
+    return this._request(`/api/operator/skill-governance/changes/${governanceChangeId}`);
+  }
+
+  // ─── Capabilities ──────────────────────────────────────────────────────────
+
+  async listCapabilities() {
+    return this._request('/api/capabilities');
+  }
+
+  async createCapability(body) {
+    return this._request('/api/capabilities', { method: 'POST', body });
+  }
+
+  async testCapability(capabilityId, body = {}) {
+    return this._request(`/api/capabilities/${capabilityId}/test`, { method: 'POST', body });
+  }
+
+  // ─── Tool Registry ─────────────────────────────────────────────────────────
+
+  async currentToolRegistryStatus() {
+    return this._request('/api/operator/current-tool-registry-status');
+  }
+
+  async getWorkflowToolRegistry({ workflowId, workflowSlug } = {}) {
+    return this._request('/api/operator/workflow-tool-registry', {
+      query: { workflow_id: workflowId, workflow_slug: workflowSlug },
+    });
+  }
+
+  async currentAssistantToolContext() {
+    return this._request('/api/operator/current-assistant-tool-context');
+  }
+
+  async getTool(toolKey) {
+    return this._request(`/api/tools/${toolKey}`);
+  }
+
+  async getToolHistory(toolKey) {
+    return this._request(`/api/tools/${toolKey}/history`);
+  }
+
+  async getToolInvocations(toolKey) {
+    return this._request(`/api/tools/${toolKey}/invocations`);
+  }
+
+  async getToolGovernance(toolKey) {
+    return this._request(`/api/tools/${toolKey}/governance`);
+  }
+
+  async getToolEventReplayBundle(toolEventSummaryId) {
+    return this._request(`/api/operator/tool-events/${toolEventSummaryId}/replay-bundle`);
+  }
+
+  async createToolReviewDecision(toolKey, body) {
+    return this._request(`/api/governance/tools/${toolKey}/review-decisions`, {
+      method: 'POST', body,
+    });
+  }
+
+  async createToolGateDecision(toolKey, body) {
+    return this._request(`/api/governance/tools/${toolKey}/gate-decisions`, {
+      method: 'POST', body,
+    });
+  }
+
+  // ─── Context Assembly ──────────────────────────────────────────────────────
+
+  async getContextAssemblyContract(workflowRunId, { stepRunId } = {}) {
+    return this._request(`/api/context-assembly/workflow-runs/${workflowRunId}/contract`, {
+      query: { step_run_id: stepRunId },
+    });
+  }
+
+  async getContextAssemblyStatus(workflowRunId, { stepRunId } = {}) {
+    return this._request(`/api/context-assembly/workflow-runs/${workflowRunId}/status`, {
+      query: { step_run_id: stepRunId },
+    });
+  }
+
+  async getOperatorContext(workflowRunId, { stepRunId } = {}) {
+    return this._request(`/api/operator/runs/${workflowRunId}/context`, {
+      query: { step_run_id: stepRunId },
+    });
+  }
+
+  async getContextFragments(workflowRunId, { stepRunId } = {}) {
+    return this._request(`/api/operator/runs/${workflowRunId}/context/fragments`, {
+      query: { step_run_id: stepRunId },
+    });
+  }
+
+  async getContextReuse(workflowRunId, { stepRunId } = {}) {
+    return this._request(`/api/operator/runs/${workflowRunId}/context/reuse`, {
+      query: { step_run_id: stepRunId },
+    });
+  }
+
+  async listPromptAssemblies(workflowRunId) {
+    return this._request(`/api/operator/workflow-runs/${workflowRunId}/prompt-assemblies`);
+  }
+
+  // ─── Performance ───────────────────────────────────────────────────────────
+
+  async getSessionPerformanceMetrics({ clientType, workflowRunId, sessionId } = {}) {
+    return this._request('/api/operator/performance/sessions', {
+      query: { client_type: clientType, workflow_run_id: workflowRunId, session_id: sessionId },
+    });
+  }
+
+  async captureBenchmarkSnapshot(body) {
+    return this._request('/api/operator/performance/benchmarks', { method: 'POST', body });
+  }
+
+  async listBenchmarks({ benchmarkScope } = {}) {
+    return this._request('/api/operator/performance/benchmarks', {
+      query: { benchmark_scope: benchmarkScope },
+    });
+  }
+
+  async getBenchmarkMetrics(benchmarkName) {
+    return this._request(`/api/operator/performance/benchmarks/${benchmarkName}/metrics`);
+  }
+
+  async getBenchmarkDelta({ baseline, current } = {}) {
+    return this._request('/api/operator/performance/delta', { query: { baseline, current } });
+  }
+
+  async getBenchmarkTrend({ metricKey, dimensionValue, limit } = {}) {
+    return this._request('/api/operator/performance/trend', {
+      query: { metric_key: metricKey, dimension_value: dimensionValue, limit },
+    });
+  }
+
+  async getPerformanceDashboard({ clientType, workflowRunId } = {}) {
+    return this._request('/api/operator/performance/dashboard', {
+      query: { client_type: clientType, workflow_run_id: workflowRunId },
+    });
+  }
+
+  // ─── Portfolio ─────────────────────────────────────────────────────────────
+
+  async getPortfolioStatus({ projectId } = {}) {
+    return this._request('/api/operator/portfolio/status', { query: { project_id: projectId } });
+  }
+
+  async getPortfolioSummary() {
+    return this._request('/api/operator/portfolio/summary');
+  }
+
+  async getPortfolioExceptions() {
+    return this._request('/api/operator/portfolio/exceptions');
+  }
+
+  async getPortfolioProject(projectId) {
+    return this._request(`/api/operator/portfolio/projects/${projectId}`);
+  }
+
+  async getPortfolioReport() {
+    return this._request('/api/operator/portfolio/report');
+  }
+
+  async getPortfolioBundle() {
+    return this._request('/api/operator/portfolio/bundle');
+  }
+
+  // ─── Self-Learning ─────────────────────────────────────────────────────────
+
+  async getSelfLearningPosture({ workflowRunId, limit } = {}) {
+    return this._request('/api/operator/self-learning/posture', {
+      query: { workflow_run_id: workflowRunId, limit },
+    });
+  }
+
+  async listLearningRecords({ workflowRunId, learningCategory, promotionReadiness, limit } = {}) {
+    return this._request('/api/operator/self-learning/records', {
+      query: {
+        workflow_run_id: workflowRunId,
+        learning_category: learningCategory,
+        promotion_readiness: promotionReadiness,
+        limit,
+      },
+    });
+  }
+
+  async getLearningRecord(learningRecordId) {
+    return this._request(`/api/operator/self-learning/records/${learningRecordId}`);
+  }
+
+  async listPromotionCandidates({ workflowRunId, learningCategory, promotionReadiness, limit } = {}) {
+    return this._request('/api/operator/self-learning/promotion-candidates', {
+      query: {
+        workflow_run_id: workflowRunId,
+        learning_category: learningCategory,
+        promotion_readiness: promotionReadiness,
+        limit,
+      },
+    });
+  }
+
+  async getPromotionCandidate(candidateKey) {
+    return this._request(`/api/operator/self-learning/promotion-candidates/${candidateKey}`);
+  }
+
+  async listPromotionFlows({ flowStatus, targetType, candidateKey, limit } = {}) {
+    return this._request('/api/operator/self-learning/promotion-flows', {
+      query: {
+        flow_status: flowStatus,
+        target_type: targetType,
+        candidate_key: candidateKey,
+        limit,
+      },
+    });
+  }
+
+  // ─── Self-Optimization ─────────────────────────────────────────────────────
+
+  async getSelfOptimizationDashboard() {
+    return this._request('/api/operator/self-optimization/dashboard');
+  }
+
+  async getSelfOptimizationCandidateQueue({ objectiveCategory, impactPosture, blockedByDefault, limit } = {}) {
+    return this._request('/api/operator/self-optimization/candidate-queue', {
+      query: {
+        objective_category: objectiveCategory,
+        impact_posture: impactPosture,
+        blocked_by_default: blockedByDefault,
+        limit,
+      },
+    });
+  }
+
+  async getSelfOptimizationBacklogPosture({ snapshotKey } = {}) {
+    return this._request('/api/operator/self-optimization/backlog-posture', {
+      query: { snapshot_key: snapshotKey },
+    });
+  }
+
+  async getSelfOptimizationPendingHandoffs({ downstreamLane } = {}) {
+    return this._request('/api/operator/self-optimization/pending-handoffs', {
+      query: { downstream_lane: downstreamLane },
+    });
+  }
+
+  // ─── Design Intelligence ───────────────────────────────────────────────────
+
+  async getDesignIntelligenceDashboard() {
+    return this._request('/api/design-intelligence/dashboard');
+  }
+
+  async listDesignDecisions() {
+    return this._request('/api/design-intelligence/decisions');
+  }
+
+  async getDesignDecision(decisionId) {
+    return this._request(`/api/design-intelligence/decisions/${decisionId}`);
+  }
+
+  async getDesignDecisionVariants(decisionId) {
+    return this._request(`/api/design-intelligence/decisions/${decisionId}/variants`);
+  }
+
+  async getDesignDecisionCritique(decisionId) {
+    return this._request(`/api/design-intelligence/decisions/${decisionId}/critique`);
+  }
+
+  async getDesignDecisionLineage(decisionId) {
+    return this._request(`/api/design-intelligence/decisions/${decisionId}/lineage`);
+  }
+
+  async listDesignPatterns() {
+    return this._request('/api/design-intelligence/patterns');
+  }
+
+  async getDecisionLabCanvas() {
+    return this._request('/api/design-intelligence/decision-lab/canvas');
+  }
+
+  async getDesignRecommendations() {
+    return this._request('/api/design-intelligence/recommendations');
+  }
+
+  async getDesignPromotions() {
+    return this._request('/api/design-intelligence/promotions');
+  }
+
+  async previewDesignPromotion(body) {
+    return this._request('/api/design-intelligence/promotions/preview', { method: 'POST', body });
+  }
+
+  async getDesignIntelligenceMetrics() {
+    return this._request('/api/design-intelligence/metrics');
+  }
+
+  // ─── Script Discovery ──────────────────────────────────────────────────────
+
+  async scanScripts(body = {}) {
+    return this._request('/api/script-discovery/scan', { method: 'POST', body });
+  }
+
+  async listDiscoveredScriptAssets({ limit } = {}) {
+    return this._request('/api/script-discovery/script-assets', { query: { limit } });
+  }
+
+  async listDiscoveredCapabilities({ limit } = {}) {
+    return this._request('/api/script-discovery/discovered-capabilities', { query: { limit } });
+  }
+
+  async listWorkflowCandidates({ limit } = {}) {
+    return this._request('/api/script-discovery/workflow-candidates', { query: { limit } });
+  }
+
+  async promoteWorkflowCandidate(workflowCandidateId, body = {}) {
+    return this._request(`/api/script-discovery/workflow-candidates/${workflowCandidateId}/promote`, {
+      method: 'POST', body,
+    });
+  }
+
+  // ─── Notes Lab ─────────────────────────────────────────────────────────────
+
+  async getNotesLabConfig() {
+    return this._request('/api/notes-lab/config');
+  }
+
+  async submitNote(body) {
+    return this._request('/api/notes-lab/submit', { method: 'POST', body });
+  }
+
+  async approveNoteReview(body) {
+    return this._request('/api/notes-lab/approve-review', { method: 'POST', body });
+  }
+
+  // ─── Search & Contacts ─────────────────────────────────────────────────────
+
+  async search(query) {
+    return this._request('/api/search', { query: { q: query } });
+  }
+
+  async getOrganization(entityId) {
+    return this._request(`/api/organizations/${entityId}`);
+  }
+
+  async getContact(contactId) {
+    return this._request(`/api/contacts/${contactId}`);
+  }
+
+  // ─── Benchmarks ────────────────────────────────────────────────────────────
+
+  async listRecentBenchmarkRuns({ limit } = {}) {
+    return this._request('/api/benchmarks/reasoners/runs/recent', { query: { limit } });
+  }
+
+  async getBenchmarkRun(benchmarkRunId) {
+    return this._request(`/api/benchmarks/reasoners/runs/${benchmarkRunId}`);
+  }
+
+  // ─── Core HTTP ─────────────────────────────────────────────────────────────
+
+  async _request(path, { method = 'GET', query, headers, body } = {}) {
+    const url = appendQuery(`${this.baseUrl}${path}`, query);
+    const controller = new AbortController();
+    const timeoutHandle = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const response = await this.fetchImpl(url, {
+        method,
+        headers: {
+          accept: 'application/json',
+          'content-type': body ? 'application/json' : undefined,
+          'x-actor-id': this.actorId,
+          authorization: this.apiKey ? `Bearer ${this.apiKey}` : undefined,
+          ...headers,
+        },
+        body: body ? JSON.stringify(body) : undefined,
+        signal: controller.signal,
+      });
+      const payload = await readJson(response);
+      if (!response.ok) {
+        const error = new Error(payload?.message || payload?.error || `Request failed with status ${response.status}.`);
+        error.status = response.status;
+        error.payload = payload;
+        throw error;
+      }
+      return payload;
+    } finally {
+      clearTimeout(timeoutHandle);
+    }
+  }
+}
+
+export function createAIEngineClient(options) {
+  return new AIEngineClient(options);
+}