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

package/README.md

@@ -16,7 +16,8 @@ npm install @bpmsoftwaresolutions/ai-engine-client
 import { AIEngineClient } from '@bpmsoftwaresolutions/ai-engine-client';
 
 const client = new AIEngineClient({
-  baseUrl: 'https://resume-generator-api.politehill-3458aba1.eastus.azurecontainerapps.io'
+  baseUrl: 'https://55e8b585-6076-4992-a164-a5398899efdb-00-c56xlmp9cuq9.worf.replit.dev',
+  // pass the key via a custom header or interceptor
 });
 
 // Health
@@ -38,13 +39,27 @@ const charter = await client.createProjectCharter({
 
 // Read the resulting project roadmap
 const roadmap = await client.getProjectRoadmap(charter.project_id);
+
+const startup = await client.startSessionGovernance({
+  objective: 'Persist governed assistant turns for the charter project.',
+  allowed_mutation_surfaces: ['src/', 'scripts/'],
+});
+
+const persistedTurn = await client.persistAssistantTurn({
+  project_id: charter.project_id,
+  session_key: startup.session_key,
+  user_request: 'Proceed with the next roadmap slice.',
+  assistant_summary: 'Completed the implementation step and persisted the governed turn.',
+  changed_files: ['src/web/app.py'],
+});
 ```
 
 ### fromEnv
 
 ```js
 const client = AIEngineClient.fromEnv();
-// Reads: AI_ENGINE_BASE_URL, AI_ENGINE_API_KEY, AI_ENGINE_ACTOR_ID
+// Reads: AI_ENGINE_BASE_URL, AI_ENGINE_ACCESS_TOKEN, AI_ENGINE_API_KEY,
+// AI_ENGINE_CLIENT_ID, AI_ENGINE_ACTOR_ID
 ```
 
 ---
@@ -54,11 +69,57 @@ const client = AIEngineClient.fromEnv();
 | Option | Type | Description |
 |---|---|---|
 | `baseUrl` | string | **Required.** Base URL of the AI Engine service. |
-| `apiKey` | string | Bearer token sent as `Authorization` header. |
+| `accessToken` | string | Static bearer token sent as `Authorization`. |
+| `tokenProvider` | function | Async callback that returns a bearer token string or `{ token }` / `{ accessToken }` per request. |
+| `apiKey` | string | Compatibility API key sent as `X-API-Key` when bearer auth is not configured. |
+| `clientId` | string | Compatibility client id sent as `X-Client-Id` when bearer auth is not configured. |
 | `actorId` | string | Sent as `X-Actor-Id` for audit trails. Default: `sdk:npm-ai-engine-client`. |
 | `fetchImpl` | function | Custom fetch (Node 18+ built-in used by default). |
 | `timeoutMs` | number | Per-request timeout in ms. Default: 30000. |
 
+### Token Provider
+
+```js
+const client = new AIEngineClient({
+  baseUrl: process.env.AI_ENGINE_BASE_URL,
+  tokenProvider: async () => {
+    const token = await acquireAccessToken();
+    return { token };
+  },
+});
+```
+
+### API Key Compatibility
+
+```js
+const client = new AIEngineClient({
+  baseUrl: process.env.AI_ENGINE_BASE_URL,
+  clientId: process.env.AI_ENGINE_CLIENT_ID,
+  apiKey: process.env.AI_ENGINE_API_KEY,
+});
+```
+
+When `accessToken` or `tokenProvider` is present, the client prefers bearer auth. API key headers are only sent when bearer auth is not configured.
+
+### External Audio Render Example
+
+```js
+const render = await client.createExternalAudioRender({
+  text: '# Weekly Update\n\nThe platform migration is on track.',
+  voice: 'alloy',
+});
+
+const status = await client.getExternalAudioRender(render.audio_render_run_id);
+const audio = await client.downloadExternalAudioRender(render.audio_render_run_id);
+```
+
+### External Workflow Artifact Example
+
+```js
+const manifest = await client.listExternalWorkflowRunArtifacts('run-123');
+const packet = await client.downloadExternalWorkflowRunArtifact('run-123', 'package_payload');
+```
+
 ---
 
 ## Methods
@@ -67,6 +128,18 @@ const client = AIEngineClient.fromEnv();
 | Method | Description |
 |---|---|
 | `ping()` | Health check + current workflow name/status. |
+| `startSessionGovernance(body)` | Start a governed external session and return the `session_key` required for mutation-capable assistant turns. |
+| `persistAssistantTurn(body)` | Persist an assistant turn to durable SQL through the API and return refreshed status projections. |
+| `createExternalAudioRender({ text, voice, model, speed, file })` | Create a client-scoped external audio render using inline text or multipart upload. |
+| `getExternalAudioRender(audioRenderRunId)` | Read external audio render status for the authenticated client. |
+| `downloadExternalAudioRender(audioRenderRunId)` | Download the rendered MP3 artifact for the authenticated client. |
+| `listExternalWorkflowRunArtifacts(workflowRunId)` | List signed external artifact descriptors for an authenticated external workflow run. |
+| `downloadExternalWorkflowRunArtifact(workflowRunId, artifactType)` | Download one authenticated external workflow-run artifact by type. |
+| `getExternalProjectStatus(projectId)` | API-key-compatible project status read through the external `/api/v1` boundary. |
+| `getExternalProjectRoadmapSummary(projectId)` | API-key-compatible roadmap summary read through the external `/api/v1` boundary. |
+| `getExternalProjectRoadmapActiveItem(projectId)` | API-key-compatible active roadmap item read through the external `/api/v1` boundary. |
+| `listExternalProjectOpenTasks(projectId)` | API-key-compatible open task read through the external `/api/v1` boundary. |
+| `getExternalProjectStatusBundle(projectId)` | One-call API-key-compatible bundle for project status, roadmap summary, active item, and open tasks. |
 
 ### Operator Status
 | Method | Description |
@@ -75,9 +148,24 @@ const client = AIEngineClient.fromEnv();
 | `currentArchitectureIntegrityStatus()` | Architecture integrity scan results. |
 | `currentSecurityGovernanceStatus({ environment, topN })` | Security governance findings. |
 | `currentCodebaseShapeStatus()` | Codebase shape analysis. |
-| `getLatestMemoryProjection()` | Current SQL memory projection (startup hydration source). |
+| `getLatestMemoryProjection()` | Current SQL memory projection (startup hydration source) through the general external `/api/v1/latest-memory-projection` route. |
+| `currentProjectStatus({ projectId })` | Current project status projection from SQL memory. |
+| `createDatabaseBackup({ databaseName, outputName, noWait })` | Start a database backup using server-owned Azure backup defaults. |
+| `listDatabaseBackups({ prefix, limit })` | List recent backups from the server-owned backup storage location. |
+| `getDatabaseBackup({ backupId })` | Get one backup artifact by backup id. |
+| `listDatabaseBackupOperations({ databaseName, operationFilter, limit })` | List backup/export operations using server-owned Azure defaults. |
 | `getDashboard()` | Operator dashboard payload. |
 
+Preferred backup contract: use `createDatabaseBackup`, `listDatabaseBackups`, `getDatabaseBackup`, and `listDatabaseBackupOperations`. Those routes let the service own Azure storage, SQL server, resource group, subscription, and credential resolution.
+
+Low-level compatibility methods:
+
+| Method | Description |
+|---|---|
+| `runAzureSqlBacpacBackup({ databaseName, storageAccount, ... })` | Start an Azure SQL BACPAC export through the legacy infra-shaped operator API. |
+| `listAzureSqlBacpacBackups({ storageAccount, container, ... })` | List BACPAC exports through the legacy infra-shaped operator API. |
+| `listAzureSqlBacpacBackupOperations({ databaseName, resourceGroup, serverName, ... })` | List Azure SQL operations through the legacy infra-shaped operator API. |
+
 ### Retrieval Wrapper
 | Method | Description |
 |---|---|
@@ -95,10 +183,21 @@ const client = AIEngineClient.fromEnv();
 | `getProject(projectId)` | Get project detail. |
 | `listCodeFiles({ repositoryId, projectId, language, pathPrefix, page, pageSize })` | Page through inventoried code files. |
 | `getCodeFile(fileId)` | Get file detail. |
+| `getCodeFileContentWindow(fileId, { startLine, endLine })` | Read a bounded file content window from inventory-backed content. |
 | `listCodeSymbolsByFile(fileId, { limit })` | List symbols discovered in a file. |
 | `getCodeSymbol(symbolId, { includeCode, maxLines })` | Get symbol detail. |
 | `searchSymbols({ query, projectScope, maxResults })` | Search inventoried symbols. |
 | `getSymbolRelationships(symbolId, { relationshipType, depth })` | Read symbol relationships from the inventory graph. |
+| `listCodeRelationships({ repositoryId, projectId, relationshipType, limit })` | Read repository/project scoped graph relationships. |
+| `listActionObservations({ repositoryId, projectPath, filePath, symbolId, actionKind, limit })` | Read latest action-grammar observations for a repo scope. |
+| `listCodebaseShapeFindings({ repositoryId, projectPath, filePath, severity, status, limit })` | List latest codebase-shape findings for the selected repo scope. |
+| `listObjectFlowObservations({ repositoryId, projectPath, filePath, objectKind, boundaryKind, limit })` | List latest object-flow observations for the selected repo scope. |
+| `getChangeAnalysis({ fileId, symbolId, limit })` | Aggregate relationships, findings, and structural observations for one file or symbol. |
+| `listRefactorCandidates({ repositoryRoot, limit })` | List governed refactor candidates derived from SQL-backed findings. |
+| `analyzeRefactorCandidate({ filePath, requestedBy, packetId, refactorIntent })` | Build a replayable refactor packet preview for one candidate file. |
+| `getRepoRetrievalPacket(retrievalPacketId)` | Read a retrieval packet through the repo boundary. |
+| `getRepoRetrievalPacketFragments(retrievalPacketId)` | Read the packet fragments for a retrieval packet. |
+| `evaluateProposalScope({ filePath, projectId, changeType, requestedBy, refactorIntent })` | Evaluate governance, scope, and open-task posture for a proposed refactor slice. |
 
 ### Retrieval Management
 | Method | Description |
@@ -143,6 +242,7 @@ const client = AIEngineClient.fromEnv();
 | `getWorkflowRun(workflowRunId)` | Get run detail. |
 | `listWorkflowArtifacts(workflowRunId)` | List run artifacts. |
 | `getWorkflowRunSubstrate(workflowRunId)` | Get run substrate (sessions, turns). |
+| `getWorkflowPlayback(workflowRunId)` | Get the playback-lite workflow timeline view derived from step runs and artifacts. |
 | `resumeWorkflowRun(workflowRunId, body)` | Resume a paused run. |
 | `listRecentInspectorRuns({ limit })` | List recent runs via inspector. |
 | `inspectWorkflowRun(workflowRunId)` | Full inspector view of a run. |
@@ -161,6 +261,11 @@ const client = AIEngineClient.fromEnv();
 | `createProjectCharter({ projectName, objective, businessContext, successCriteria, priority, constraints, inScope, outOfScope, assumptions, linkedWorkflows, testingStrategy, initialContext, requestedBy })` | Charter a project (writes to durable SQL memory). |
 | `listProjects({ limit, includeInactive, processStatus, charterStatus })` | List projects. |
 | `getProject(projectId)` | Get project detail. |
+| `getProjectCharterReport(projectId)` | Get the SQL-backed charter report payload for a project. |
+| `createProjectMarkdownDownload(projectId, { reportType, includeMarkdown })` | Create a markdown download descriptor for `charter` or `implementation_roadmap`. |
+| `downloadProjectMarkdownReport(projectId, reportType)` | Download a rendered markdown report as text plus filename metadata. |
+| `downloadProjectCharterReportMarkdown(projectId)` | Download the charter markdown report. |
+| `getProjectBundle(projectId)` | Get current status, charter report, and roadmap report in one payload. |
 
 ### Roadmaps
 | Method | Description |
@@ -169,6 +274,9 @@ const client = AIEngineClient.fromEnv();
 | `getProjectRoadmap(projectId)` | Get full roadmap for a project. |
 | `getProjectRoadmapSummary(projectId)` | Roadmap summary. |
 | `getProjectRoadmapActiveItem(projectId)` | Current active roadmap item. |
+| `getProjectImplementationRoadmapReport(projectId)` | Get the SQL-backed implementation roadmap report payload. |
+| `downloadProjectImplementationRoadmapReportMarkdown(projectId)` | Download the implementation roadmap markdown report. |
+| `ensureProjectRoadmapTaskSurface(projectId, { requestedBy, assignedTo, createAcceptanceSubtasks })` | Materialize the active roadmap item's parent task and acceptance subtasks. |
 | `listProjectOpenTasks(projectId)` | Open tasks for a project. |
 | `getProjectPerformanceMetrics(projectId, { workflowId, workflowRunId, sinceUtc })` | Performance metrics. |
 
@@ -176,6 +284,8 @@ const client = AIEngineClient.fromEnv();
 | Method | Description |
 |---|---|
 | `createImplementationTask(implementationItemId, { title, implementationPacketId, ... })` | Create a task on a roadmap item. |
+
+`createProjectCharter()` now also accepts `linkedWorkflowSlug`, `ensureTaskSurface`, `assignedTo`, and `createAcceptanceSubtasks` so new API-chartered projects can immediately surface an attachable implementation item and durable task tree.
 | `listImplementationTasks(implementationItemId)` | List tasks. |
 | `listImplementationSubtasks(taskId)` | List subtasks. |
 | `updateImplementationTask(taskId, updates)` | Update a task. |
@@ -339,4 +449,4 @@ const client = AIEngineClient.fromEnv();
 
 The package talks to the AI Engine web service. All routes listed above are registered unconditionally in the Flask app and served by the deployed Azure Container App.
 
-Operator routes (`/api/operator/*`) use network-trust protection. The external v1 API (`/api/v1/*`) requires `X-Client-Id` and `X-API-Key` headers and is intentionally not wrapped by this client.
+Operator and governed routes expect bearer-token authorization. The external v1 API (`/api/v1/*`) still supports its migration auth modes separately and is intentionally not wrapped by this client.

package/package.json

@@ -1,28 +1,31 @@
-{
-  "name": "@bpmsoftwaresolutions/ai-engine-client",
-  "version": "1.0.0-beta.1",
-  "description": "Thin npm client for the AI Engine operator and retrieval APIs",
-  "type": "module",
-  "main": "./src/index.js",
-  "exports": {
-    ".": "./src/index.js"
-  },
-  "files": [
-    "src",
-    "README.md"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "keywords": [
-    "ai-engine",
-    "sdk",
-    "client",
-    "retrieval",
-    "workflow"
-  ],
-  "license": "UNLICENSED",
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@bpmsoftwaresolutions/ai-engine-client",
+  "version": "1.0.0-beta.10",
+  "description": "Thin npm client for the AI Engine operator and retrieval APIs",
+  "type": "module",
+  "main": "./src/index.js",
+  "scripts": {
+    "test": "node --test"
+  },
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "ai-engine",
+    "sdk",
+    "client",
+    "retrieval",
+    "workflow"
+  ],
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.js

@@ -20,11 +20,42 @@ async function readJson(response) {
   return { message: text };
 }
 
+function parseContentDispositionFilename(headerValue) {
+  const value = String(headerValue || '');
+  const quotedMatch = value.match(/filename="([^"]+)"/i);
+  if (quotedMatch) return quotedMatch[1];
+  const plainMatch = value.match(/filename=([^;]+)/i);
+  return plainMatch ? plainMatch[1].trim() : null;
+}
+
+function isFormDataBody(value) {
+  return typeof FormData !== 'undefined' && value instanceof FormData;
+}
+
+function isBinaryBody(value) {
+  return (
+    value instanceof ArrayBuffer
+    || ArrayBuffer.isView(value)
+    || (typeof Blob !== 'undefined' && value instanceof Blob)
+    || value instanceof URLSearchParams
+    || typeof value === 'string'
+  );
+}
+
+function isJsonBody(value) {
+  if (value === undefined || value === null) return false;
+  if (isFormDataBody(value) || isBinaryBody(value)) return false;
+  return typeof value === 'object';
+}
+
 export class AIEngineClient {
-  constructor({ baseUrl, apiKey, actorId, fetchImpl, timeoutMs } = {}) {
+  constructor({ baseUrl, accessToken, tokenProvider, apiKey, clientId, actorId, fetchImpl, timeoutMs } = {}) {
     if (!baseUrl) throw new Error('baseUrl is required.');
     this.baseUrl = trimTrailingSlash(baseUrl);
+    this.accessToken = accessToken || null;
+    this.tokenProvider = tokenProvider || null;
     this.apiKey = apiKey || null;
+    this.clientId = clientId || null;
     this.actorId = actorId || 'sdk:npm-ai-engine-client';
     this.fetchImpl = fetchImpl || globalThis.fetch;
     this.timeoutMs = timeoutMs || DEFAULT_TIMEOUT_MS;
@@ -36,7 +67,10 @@ export class AIEngineClient {
   static fromEnv(options = {}) {
     return new AIEngineClient({
       baseUrl: options.baseUrl || process.env.AI_ENGINE_BASE_URL || process.env.AI_ENGINE_API_BASE_URL,
+      accessToken: options.accessToken || process.env.AI_ENGINE_ACCESS_TOKEN || null,
+      tokenProvider: options.tokenProvider || null,
       apiKey: options.apiKey || process.env.AI_ENGINE_API_KEY || null,
+      clientId: options.clientId || process.env.AI_ENGINE_CLIENT_ID || null,
       actorId: options.actorId || process.env.AI_ENGINE_ACTOR_ID || 'sdk:npm-ai-engine-client',
     });
   }
@@ -77,13 +111,189 @@ export class AIEngineClient {
   }
 
   async getLatestMemoryProjection() {
-    return this._request('/api/operator/latest-memory-projection');
+    return this._request('/api/v1/latest-memory-projection');
+  }
+
+  async currentProjectStatus({ projectId } = {}) {
+    return this._request('/api/operator/current-project-status', {
+      query: { project_id: projectId },
+    });
+  }
+
+  async createDatabaseBackup({ databaseName, outputName, noWait } = {}) {
+    return this._request('/api/operator/database/backups', {
+      method: 'POST',
+      body: {
+        database_name: databaseName,
+        output_name: outputName,
+        no_wait: noWait,
+      },
+    });
+  }
+
+  async listDatabaseBackups({ prefix, limit } = {}) {
+    return this._request('/api/operator/database/backups', {
+      query: {
+        prefix,
+        limit,
+      },
+    });
+  }
+
+  async getDatabaseBackup({ backupId } = {}) {
+    return this._request(`/api/operator/database/backups/${encodeURIComponent(backupId)}`);
+  }
+
+  async listDatabaseBackupOperations({ databaseName, operationFilter, limit } = {}) {
+    return this._request('/api/operator/database/backups/operations', {
+      query: {
+        database_name: databaseName,
+        operation_filter: operationFilter,
+        limit,
+      },
+    });
+  }
+
+  async runAzureSqlBacpacBackup({
+    databaseName,
+    storageAccount,
+    container,
+    resourceGroup,
+    serverName,
+    outputName,
+    adminUser,
+    adminPassword,
+    subscription,
+    storageKey,
+    skipContainerCreate,
+    noWait,
+  } = {}) {
+    return this._request('/api/operator/database/backups/azure-sql-bacpac', {
+      method: 'POST',
+      body: {
+        database_name: databaseName,
+        storage_account: storageAccount,
+        container,
+        resource_group: resourceGroup,
+        server_name: serverName,
+        output_name: outputName,
+        admin_user: adminUser,
+        admin_password: adminPassword,
+        subscription,
+        storage_key: storageKey,
+        skip_container_create: skipContainerCreate,
+        no_wait: noWait,
+      },
+    });
+  }
+
+  async listAzureSqlBacpacBackups({
+    storageAccount,
+    container,
+    resourceGroup,
+    serverName,
+    subscription,
+    storageKey,
+    prefix,
+    limit,
+  } = {}) {
+    return this._request('/api/operator/database/backups/azure-sql-bacpac', {
+      query: {
+        storage_account: storageAccount,
+        container,
+        resource_group: resourceGroup,
+        server_name: serverName,
+        subscription,
+        storage_key: storageKey,
+        prefix,
+        limit,
+      },
+    });
+  }
+
+  async listAzureSqlBacpacBackupOperations({
+    databaseName,
+    resourceGroup,
+    serverName,
+    subscription,
+    operationFilter,
+    limit,
+  } = {}) {
+    return this._request('/api/operator/database/backups/azure-sql-bacpac/operations', {
+      query: {
+        database_name: databaseName,
+        resource_group: resourceGroup,
+        server_name: serverName,
+        subscription,
+        operation_filter: operationFilter,
+        limit,
+      },
+    });
   }
 
   async getDashboard() {
     return this._request('/api/dashboard');
   }
 
+  async startSessionGovernance(body) {
+    return this._request('/api/v1/session-governance/startup', { method: 'POST', body });
+  }
+
+  async persistAssistantTurn(body) {
+    return this._request('/api/v1/assistant-turns', { method: 'POST', body });
+  }
+
+  async getExternalProjectStatus(projectId) {
+    return this._request(`/api/v1/projects/${projectId}/status`);
+  }
+
+  async getExternalProjectRoadmapSummary(projectId) {
+    return this._request(`/api/v1/projects/${projectId}/implementation-roadmap/summary`);
+  }
+
+  async getExternalProjectRoadmapActiveItem(projectId) {
+    return this._request(`/api/v1/projects/${projectId}/implementation-roadmap/active-item`);
+  }
+
+  async listExternalProjectOpenTasks(projectId) {
+    return this._request(`/api/v1/projects/${projectId}/open-tasks`);
+  }
+
+  async getExternalProjectStatusBundle(projectId) {
+    return this._request(`/api/v1/projects/${projectId}/status-bundle`);
+  }
+
+  async createExternalAudioRender({ text, voice, model, speed, file } = {}) {
+    if (file) {
+      const form = new FormData();
+      form.append('file', file);
+      if (voice !== undefined) form.append('voice', String(voice));
+      if (model !== undefined) form.append('model', String(model));
+      if (speed !== undefined) form.append('speed', String(speed));
+      return this._request('/api/v1/audio-renders', { method: 'POST', body: form });
+    }
+    return this._request('/api/v1/audio-renders', {
+      method: 'POST',
+      body: { text, voice, model, speed },
+    });
+  }
+
+  async getExternalAudioRender(audioRenderRunId) {
+    return this._request(`/api/v1/audio-renders/${audioRenderRunId}`);
+  }
+
+  async downloadExternalAudioRender(audioRenderRunId) {
+    return this._requestBinary(`/api/v1/audio-renders/${audioRenderRunId}/download`);
+  }
+
+  async listExternalWorkflowRunArtifacts(workflowRunId) {
+    return this._request(`/api/v1/runs/${workflowRunId}/artifacts`);
+  }
+
+  async downloadExternalWorkflowRunArtifact(workflowRunId, artifactType) {
+    return this._requestBinary(`/api/v1/runs/${workflowRunId}/artifacts/${artifactType}/download`);
+  }
+
   // ─── Retrieval Wrapper ─────────────────────────────────────────────────────
 
   async getCommandCard({ commandKey, alias, intentText, requestedBy } = {}) {
@@ -165,6 +375,12 @@ export class AIEngineClient {
     return this._request(`/api/repo/files/${fileId}`);
   }
 
+  async getCodeFileContentWindow(fileId, { startLine = 1, endLine } = {}) {
+    return this._request(`/api/repo/files/${fileId}/content-window`, {
+      query: { start_line: startLine, end_line: endLine ?? startLine },
+    });
+  }
+
   async listCodeSymbolsByFile(fileId, { limit = 500 } = {}) {
     return this._request(`/api/repo/files/${fileId}/symbols`, {
       query: { limit },
@@ -189,6 +405,64 @@ export class AIEngineClient {
     });
   }
 
+  async listCodeRelationships({ repositoryId, projectId, relationshipType, limit = 100 } = {}) {
+    return this._request('/api/repo/relationships', {
+      query: { repository_id: repositoryId, project_id: projectId, relationship_type: relationshipType, limit },
+    });
+  }
+
+  async listActionObservations({ repositoryId, projectPath, filePath, symbolId, actionKind, limit = 100 } = {}) {
+    return this._request('/api/repo/action-observations', {
+      query: { repository_id: repositoryId, project_path: projectPath, file_path: filePath, symbol_id: symbolId, action_kind: actionKind, limit },
+    });
+  }
+
+  async listCodebaseShapeFindings({ repositoryId, projectPath, filePath, severity, status, limit = 100 } = {}) {
+    return this._request('/api/repo/shape/findings', {
+      query: { repository_id: repositoryId, project_path: projectPath, file_path: filePath, severity, status, limit },
+    });
+  }
+
+  async listObjectFlowObservations({ repositoryId, projectPath, filePath, objectKind, boundaryKind, limit = 100 } = {}) {
+    return this._request('/api/repo/object-flow-observations', {
+      query: { repository_id: repositoryId, project_path: projectPath, file_path: filePath, object_kind: objectKind, boundary_kind: boundaryKind, limit },
+    });
+  }
+
+  async getChangeAnalysis({ fileId, symbolId, limit = 25 } = {}) {
+    return this._request('/api/repo/change-analysis', {
+      query: { file_id: fileId, symbol_id: symbolId, limit },
+    });
+  }
+
+  async listRefactorCandidates({ repositoryRoot, limit = 10 } = {}) {
+    return this._request('/api/repo/refactor-candidates', {
+      query: { repository_root: repositoryRoot, limit },
+    });
+  }
+
+  async analyzeRefactorCandidate({ filePath, requestedBy, packetId, refactorIntent } = {}) {
+    return this._request('/api/repo/refactor-candidate-analysis', {
+      method: 'POST',
+      body: { file_path: filePath, requested_by: requestedBy, packet_id: packetId, refactor_intent: refactorIntent },
+    });
+  }
+
+  async getRepoRetrievalPacket(retrievalPacketId) {
+    return this._request(`/api/repo/retrieval/packets/${retrievalPacketId}`);
+  }
+
+  async getRepoRetrievalPacketFragments(retrievalPacketId) {
+    return this._request(`/api/repo/retrieval/packets/${retrievalPacketId}/fragments`);
+  }
+
+  async evaluateProposalScope({ filePath, projectId, changeType = 'refactor', requestedBy, refactorIntent } = {}) {
+    return this._request('/api/repo/proposal-scope-evaluation', {
+      method: 'POST',
+      body: { file_path: filePath, project_id: projectId, change_type: changeType, requested_by: requestedBy, refactor_intent: refactorIntent },
+    });
+  }
+
   // ─── Retrieval Management ──────────────────────────────────────────────────
 
   async getRetrievalStatus() {
@@ -316,6 +590,10 @@ export class AIEngineClient {
     return this._request(`/api/workflow-runs/${workflowRunId}/substrate`);
   }
 
+  async getWorkflowPlayback(workflowRunId) {
+    return this._request(`/api/operator/workflow-runs/${workflowRunId}/playback`);
+  }
+
   async resumeWorkflowRun(workflowRunId, body = {}) {
     return this._request(`/api/workflow-runs/${workflowRunId}/resume`, { method: 'POST', body });
   }
@@ -361,9 +639,13 @@ export class AIEngineClient {
     outOfScope = [],
     assumptions = [],
     linkedWorkflows = [],
+    linkedWorkflowSlug,
     testingStrategy = {},
     initialContext = {},
     requestedBy,
+    ensureTaskSurface = true,
+    assignedTo,
+    createAcceptanceSubtasks = true,
   } = {}) {
     return this._request('/api/projects/charter', {
       method: 'POST',
@@ -378,9 +660,13 @@ export class AIEngineClient {
         out_of_scope: outOfScope,
         assumptions,
         linked_workflows: linkedWorkflows,
+        linked_workflow_slug: linkedWorkflowSlug,
         testing_strategy: testingStrategy,
         initial_context: initialContext,
         requested_by: requestedBy,
+        ensure_task_surface: ensureTaskSurface,
+        assigned_to: assignedTo,
+        create_acceptance_subtasks: createAcceptanceSubtasks,
       },
     });
   }
@@ -400,6 +686,29 @@ export class AIEngineClient {
     return this._request(`/api/operator/projects/${projectId}`);
   }
 
+  async getProjectCharterReport(projectId) {
+    return this._request(`/api/operator/projects/${projectId}/charter/report`);
+  }
+
+  async createProjectMarkdownDownload(projectId, { reportType, includeMarkdown = false } = {}) {
+    return this._request(`/api/operator/projects/${projectId}/markdown-report-downloads`, {
+      method: 'POST',
+      body: { report_type: reportType, include_markdown: includeMarkdown },
+    });
+  }
+
+  async downloadProjectMarkdownReport(projectId, reportType) {
+    return this._requestText(`/api/operator/projects/${projectId}/markdown-reports/${reportType}/download`);
+  }
+
+  async downloadProjectCharterReportMarkdown(projectId) {
+    return this.downloadProjectMarkdownReport(projectId, 'charter');
+  }
+
+  async getProjectBundle(projectId) {
+    return this._request(`/api/operator/projects/${projectId}/bundle`);
+  }
+
   // ─── Roadmaps ──────────────────────────────────────────────────────────────
 
   async listProjectRoadmaps({ includeInactive } = {}) {
@@ -420,6 +729,29 @@ export class AIEngineClient {
     return this._request(`/api/operator/projects/${projectId}/implementation-roadmap/active-item`);
   }
 
+  async getProjectImplementationRoadmapReport(projectId) {
+    return this._request(`/api/operator/projects/${projectId}/implementation-roadmap/report`);
+  }
+
+  async downloadProjectImplementationRoadmapReportMarkdown(projectId) {
+    return this.downloadProjectMarkdownReport(projectId, 'implementation_roadmap');
+  }
+
+  async ensureProjectRoadmapTaskSurface(projectId, {
+    requestedBy,
+    assignedTo,
+    createAcceptanceSubtasks = true,
+  } = {}) {
+    return this._request(`/api/operator/projects/${projectId}/implementation-roadmap/task-surface`, {
+      method: 'POST',
+      body: {
+        requested_by: requestedBy,
+        assigned_to: assignedTo,
+        create_acceptance_subtasks: createAcceptanceSubtasks,
+      },
+    });
+  }
+
   async listProjectOpenTasks(projectId) {
     return this._request(`/api/operator/projects/${projectId}/open-tasks`);
   }
@@ -976,21 +1308,45 @@ export class AIEngineClient {
 
   // ─── Core HTTP ─────────────────────────────────────────────────────────────
 
+  async _resolveAccessToken() {
+    if (typeof this.tokenProvider === 'function') {
+      const provided = await this.tokenProvider();
+      if (!provided) return null;
+      if (typeof provided === 'string') return provided;
+      if (typeof provided === 'object' && typeof provided.token === 'string') return provided.token;
+      if (typeof provided === 'object' && typeof provided.accessToken === 'string') return provided.accessToken;
+      throw new Error('tokenProvider must return a token string or an object with a token or accessToken field.');
+    }
+    return this.accessToken;
+  }
+
+  async _buildHeaders({ headers, body, accept }) {
+    const token = await this._resolveAccessToken();
+    const resolvedHeaders = {
+      accept: accept || 'application/json',
+      'x-actor-id': this.actorId,
+      ...(isJsonBody(body) ? { 'content-type': 'application/json' } : {}),
+      ...(token ? { authorization: `Bearer ${token}` } : {}),
+      ...(!token && this.clientId ? { 'x-client-id': this.clientId } : {}),
+      ...(!token && this.apiKey ? { 'x-api-key': this.apiKey } : {}),
+      ...headers,
+    };
+    for (const [key, value] of Object.entries(resolvedHeaders)) {
+      if (value === undefined) delete resolvedHeaders[key];
+    }
+    return resolvedHeaders;
+  }
+
   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 resolvedHeaders = await this._buildHeaders({ headers, body, accept: 'application/json' });
       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,
+        headers: resolvedHeaders,
+        body: isJsonBody(body) ? JSON.stringify(body) : body,
         signal: controller.signal,
       });
       const payload = await readJson(response);
@@ -1005,6 +1361,81 @@ export class AIEngineClient {
       clearTimeout(timeoutHandle);
     }
   }
+
+  async _requestText(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 resolvedHeaders = await this._buildHeaders({
+        headers,
+        body,
+        accept: 'text/markdown, text/plain;q=0.9, application/json;q=0.8',
+      });
+      const response = await this.fetchImpl(url, {
+        method,
+        headers: resolvedHeaders,
+        body: isJsonBody(body) ? JSON.stringify(body) : body,
+        signal: controller.signal,
+      });
+      const contentType = response.headers.get('content-type') || '';
+      const contentDisposition = response.headers.get('content-disposition') || '';
+      if (!response.ok) {
+        const payload = contentType.includes('application/json')
+          ? await response.json()
+          : { message: await response.text() };
+        const error = new Error(payload?.message || payload?.error || `Request failed with status ${response.status}.`);
+        error.status = response.status;
+        error.payload = payload;
+        throw error;
+      }
+      return {
+        text: await response.text(),
+        contentType,
+        fileName: parseContentDispositionFilename(contentDisposition),
+      };
+    } finally {
+      clearTimeout(timeoutHandle);
+    }
+  }
+
+  async _requestBinary(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 resolvedHeaders = await this._buildHeaders({
+        headers,
+        body,
+        accept: 'audio/mpeg, application/octet-stream;q=0.9, application/json;q=0.8',
+      });
+      const response = await this.fetchImpl(url, {
+        method,
+        headers: resolvedHeaders,
+        body: isJsonBody(body) ? JSON.stringify(body) : body,
+        signal: controller.signal,
+      });
+      const contentType = response.headers.get('content-type') || '';
+      const contentDisposition = response.headers.get('content-disposition') || '';
+      if (!response.ok) {
+        const payload = contentType.includes('application/json')
+          ? await response.json()
+          : { message: await response.text() };
+        const error = new Error(payload?.message || payload?.error || `Request failed with status ${response.status}.`);
+        error.status = response.status;
+        error.payload = payload;
+        throw error;
+      }
+      const arrayBuffer = await response.arrayBuffer();
+      return {
+        arrayBuffer,
+        contentType,
+        fileName: parseContentDispositionFilename(contentDisposition),
+      };
+    } finally {
+      clearTimeout(timeoutHandle);
+    }
+  }
 }
 
 export function createAIEngineClient(options) {