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

package/README.md

@@ -10,13 +10,25 @@ No repo clone required. Install the package, point it at the Azure service, and
 npm install @bpmsoftwaresolutions/ai-engine-client
 ```
 
+## Publishing
+
+This package is published automatically from GitHub Actions by `.github/workflows/publish-ai-engine-client.yml`.
+
+The workflow runs on pushes to `main` when files under `packages/ai-engine-client/**` change, and it can also be started manually with `workflow_dispatch`.
+
+Authentication supports either:
+
+- npm trusted publishing
+- a repository secret named `NPM_TOKEN`, `NPM_PUBLISH_TOKEN`, or `NODE_AUTH_TOKEN`
+
 ## Quick Start
 
 ```js
 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 +50,72 @@ 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'],
+});
+```
+
+## Integration Notes
+
+### Auth Modes
+
+The package supports two authentication patterns:
+
+1. Bearer-token auth for operator and governed routes.
+2. Compatibility API-key auth for migration-oriented external routes and deployments that still allow shared-key access.
+
+Header behavior is:
+
+- If `accessToken` or `tokenProvider` is configured, the client sends `Authorization: Bearer <token>`.
+- If bearer auth is not configured, the client sends `X-API-Key` when `apiKey` is provided.
+- If bearer auth is not configured and `clientId` is provided, the client also sends `X-Client-Id`.
+- The client always sends `X-Actor-Id` for audit trails unless overridden.
+
+That means this package wraps both operator/governed routes and selected external `/api/v1/*` routes. Pick the auth mode that matches the route family exposed by your deployment.
+
+### Route Families
+
+- Operator and governed routes are methods such as `createProjectCharter`, `getProjectBundle`, `importImplementationPacket`, and the workflow/portfolio/governance APIs.
+- External routes are the methods prefixed with `getExternal*`, `listExternal*`, `downloadExternal*`, plus `startSessionGovernance`, `persistAssistantTurn`, `createExternalAudioRender`, and `getLatestMemoryProjection`.
+
+If your deployment enforces bearer auth on operator routes, API-key-only construction will not work for those methods.
+
+### Text and Binary Downloads
+
+Some methods do not return plain JSON:
+
+- Markdown download helpers return `{ text, contentType, fileName }`.
+- Binary download helpers return `{ arrayBuffer, contentType, fileName }`.
+
+Examples:
+
+```js
+import fs from 'node:fs';
+
+const markdown = await client.downloadProjectCharterReportMarkdown(projectId);
+console.log(markdown.fileName, markdown.contentType);
+console.log(markdown.text);
+
+const audio = await client.downloadExternalAudioRender(audioRenderRunId);
+await fs.promises.writeFile('render.mp3', Buffer.from(audio.arrayBuffer));
 ```
 
 ### 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 +125,156 @@ 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.
+
+Some deployments accept a shared `X-API-Key` without `X-Client-Id`, while others require both `X-Client-Id` and `X-API-Key` for API-key auth. If your environment uses client-scoped API keys, provide both values.
+
+### Project Chartering Contract
+
+`createProjectCharter()` sends snake_case fields to `POST /api/projects/charter`. The method accepts:
+
+- `projectName`, `objective`
+- `businessContext`, `successCriteria`, `priority`
+- `constraints`, `inScope`, `outOfScope`, `assumptions`
+- `linkedWorkflows`, `linkedWorkflowSlug`
+- `testingStrategy`, `initialContext`
+- `requestedBy`
+- `ensureTaskSurface`, `assignedTo`, `createAcceptanceSubtasks`
+
+The response always includes the charter identifiers:
+
+- `project_id`
+- `workflow_id`
+- `workflow_run_id`
+- `implementation_packet_id`
+- `implementation_packet_key`
+- `status`
+
+If `ensureTaskSurface` is left as `true`, the server also attempts to attach `task_surface` for the active roadmap item. That field is only available when the server can resolve an active implementation item from the project roadmap. If roadmap state is incomplete in the deployment, charter creation can still succeed while `task_surface` is unavailable.
+
+Example:
+
+```js
+const charter = await client.createProjectCharter({
+  projectName: 'Loga Cognitive Interface Cockpit Delivery',
+  objective: 'Deliver the operator cockpit and playback experience.',
+  businessContext: 'Ground the first playback surface in convert-document-to-audio.',
+  linkedWorkflowSlug: 'convert-document-to-audio',
+  ensureTaskSurface: true,
+  createAcceptanceSubtasks: true,
+});
+
+console.log(charter.project_id);
+console.log(charter.implementation_packet_key);
+console.log(charter.task_surface?.active_item?.implementation_item_id ?? null);
+```
+
+### Implementation Packet Import Contract
+
+`importImplementationPacket(body)` expects the engine's `implementation_plan_packet` schema, not an arbitrary roadmap-shaped JSON document.
+
+Minimum required top-level fields:
+
+- `packetType`
+- `packetVersion`
+- `packetId`
+- `title`
+- `phases`
+- `governance.requiredGates`
+
+Minimum required fields for each item:
+
+- `itemKey`
+- `type`
+- `description`
+- `acceptanceChecks`
+
+Allowed packet statuses include `draft`, `approved`, `blocked`, `completed`, and other governed packet lifecycle states. Custom statuses such as `draft-local-artifact` are not valid for import.
+
+Minimal example:
+
+```js
+await client.importImplementationPacket({
+  packetType: 'implementation_plan_packet',
+  packetVersion: '1.0',
+  packetId: 'impl-loga-cockpit-v1',
+  title: 'Loga Cognitive Interface Cockpit Delivery',
+  status: 'draft',
+  governance: {
+    requiredGates: ['intent', 'structure', 'promotion'],
+  },
+  phases: [
+    {
+      phaseKey: 'phase_1_foundation',
+      title: 'Foundation',
+      items: [
+        {
+          itemKey: 'define-cockpit-surface',
+          type: 'ui_slice',
+          description: 'Define the first cockpit delivery slice.',
+          acceptanceChecks: [
+            { text: 'The initial slice is explicitly bounded.' },
+          ],
+        },
+      ],
+    },
+  ],
+});
+```
+
+The package does not auto-convert nested human planning structures like `tasks` and `subtasks` into durable implementation-item tasks. To create persisted task records after import, use `ensureProjectRoadmapTaskSurface()` or `createImplementationTask()`.
+
+A copyable example payload is packaged at `examples/implementation-plan-packet.minimal.json`.
+
+### 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 +283,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 +303,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 +338,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 +397,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 +416,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 +429,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 +439,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 +604,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 generally expect bearer-token authorization. The package also wraps selected external `/api/v1/*` routes that support migration-oriented auth modes such as bearer or API-key compatibility, depending on deployment configuration.

package/examples/implementation-plan-packet.minimal.json

@@ -0,0 +1,76 @@
+{
+  "packetType": "implementation_plan_packet",
+  "packetVersion": "1.0",
+  "packetId": "impl-example-governed-slice-v1",
+  "title": "Example Governed Slice Implementation Packet",
+  "status": "draft",
+  "createdBy": {
+    "kind": "operator",
+    "name": "sdk-example"
+  },
+  "sourceModel": {
+    "producer": "ai-engine-client-readme",
+    "purpose": "minimal_import_example"
+  },
+  "system": {
+    "slug": "example-governed-slice",
+    "domain": "project-chartering"
+  },
+  "scope": {
+    "productArea": "example-governed-slice",
+    "workflowIntent": "Demonstrate the minimum durable implementation packet contract.",
+    "targetSurface": "governed-project-execution",
+    "inScope": [
+      "first delivery slice"
+    ],
+    "outOfScope": [
+      "full product rollout"
+    ]
+  },
+  "northStar": {
+    "summary": "Define a small but valid governed implementation packet."
+  },
+  "governance": {
+    "requiredGates": [
+      "intent",
+      "structure",
+      "promotion"
+    ],
+    "reviewRequired": true,
+    "evidenceRequiredForCompletion": true
+  },
+  "completionPolicy": {
+    "requiresEvidence": true,
+    "requiresReview": true
+  },
+  "phases": [
+    {
+      "phaseKey": "phase_1_foundation",
+      "title": "Foundation",
+      "items": [
+        {
+          "itemKey": "define-first-slice",
+          "type": "delivery_slice",
+          "priority": "high",
+          "title": "Define first governed slice",
+          "description": "Define the first durable delivery slice and bind its acceptance criteria.",
+          "status": "not_started",
+          "dependsOn": [],
+          "artifactsExpected": [
+            "delivery-slice-definition.md"
+          ],
+          "acceptanceChecks": [
+            {
+              "text": "The slice is explicitly bounded.",
+              "status": "not_run"
+            },
+            {
+              "text": "The slice can be attached to durable task surfaces.",
+              "status": "not_run"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/package.json

@@ -1,28 +1,32 @@
-{
-  "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.11",
+  "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",
+    "examples"
+  ],
+  "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) {