@bpmsoftwaresolutions/ai-engine-client 1.1.38 → 1.1.41

package/README.md

@@ -79,6 +79,21 @@ const generatedUsability = await client.getGeneratedExecutionUsability();
 const logaUsability = await client.getLogaGeneratedExecutionUsabilityProjection();
 ```
 
+## Project Continuation Runtime
+
+Once you know the project identity, use `resumeProjectWork()` as the canonical startup and hydration call for project work.
+
+```js
+const continuation = await client.resumeProjectWork({
+  projectIdentifier: charter.project_name,
+  actorMode: 'operator',
+  executionIntent: 'continue governed work',
+  requireClaim: true,
+});
+```
+
+That call resolves the canonical project, active roadmap state, workflow context, tool bindings, and the continuation brief in one governed response. Use the returned `continuation_brief_markdown` as the primary focus surface for LOGA and operator startup flows.
+
 ## Integration Notes
 
 ### Auth Modes
@@ -408,6 +423,7 @@ const packet = await client.downloadExternalWorkflowRunArtifact('run-123', 'pack
 | `startSessionGovernance(body)` | Start a governed external session and return the `session_key` required for mutation-capable assistant turns. |
 | `claimWorkItem(body)` | Bind an oriented, claim-locked context session to a concrete work item and return the active claim envelope. |
 | `persistAssistantTurn(body)` | Persist an assistant turn to durable SQL through the API and return refreshed status projections. |
+| `resumeProjectWork({ projectIdentifier, actorMode, executionIntent, requireClaim, workflowRunLimit })` | Canonical project startup and hydration call that resolves the continuation brief, active item, required tools, allowed scope, and next governed action from a project identifier. |
 | `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. |
@@ -418,6 +434,7 @@ const packet = await client.downloadExternalWorkflowRunArtifact('run-123', 'pack
 | `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. |
+| `getExternalProjectResumeContext(projectId, { actorMode, executionIntent, requireClaim, workflowRunLimit })` | API-key-compatible continuation bootstrap through the external `/api/v1/projects/:projectId/resume-context` boundary. |
 
 ### Operator Status
 | Method | Description |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bpmsoftwaresolutions/ai-engine-client",
-  "version": "1.1.38",
+  "version": "1.1.41",
   "description": "Thin npm client for the AI Engine operator and retrieval APIs",
   "type": "module",
   "main": "./src/index.js",

package/src/index.js

@@ -1,5 +1,5 @@
 const DEFAULT_TIMEOUT_MS = 30000;
-export const AI_ENGINE_CLIENT_VERSION = '1.1.38';
+export const AI_ENGINE_CLIENT_VERSION = '1.1.41';
 export const GOVERNED_MUTATION_REQUIRED_CAPABILITIES = [
   'executeVerifiedMutation',
   'post_mutation_verification',
@@ -1541,6 +1541,76 @@ export class AIEngineClient {
     return this._request(`/api/operator/projects/${projectId}`);
   }
 
+  async listProjectWorkflowRuns(projectId, { limit = 25 } = {}) {
+    return this._request(`/api/operator/projects/${projectId}/workflow-runs`, {
+      query: { limit },
+    });
+  }
+
+  async closeProject(projectId, {
+    workflowId,
+    workflowRunIds,
+    reason,
+    operatorIdentity,
+    runTerminalStatus = 'failed',
+  } = {}) {
+    const normalizedProjectId = cleanText(projectId);
+    if (!normalizedProjectId) {
+      throw new Error('projectId is required.');
+    }
+    const normalizedReason = cleanText(reason) || 'close active project';
+    const normalizedOperatorIdentity = cleanText(operatorIdentity) || this.actorId;
+    const resolvedRuns = Array.isArray(workflowRunIds) ? cleanList(workflowRunIds) : [];
+    let resolvedWorkflowId = cleanText(workflowId);
+
+    if (!resolvedWorkflowId || resolvedRuns.length === 0) {
+      const projectPayload = await this.getProject(normalizedProjectId);
+      const summary = isPlainObject(projectPayload?.summary) ? projectPayload.summary : {};
+      if (!resolvedWorkflowId) {
+        resolvedWorkflowId = cleanText(summary.workflow_id) || cleanText(summary.workflowId);
+      }
+      if (resolvedRuns.length === 0) {
+        const workflowRuns = await this.listProjectWorkflowRuns(normalizedProjectId, { limit: 100 });
+        const activeStatuses = new Set(['queued', 'running', 'blocked', 'open', 'active', 'ping-review']);
+        const activeRuns = Array.isArray(workflowRuns)
+          ? workflowRuns.filter((run) => activeStatuses.has(String(run?.status || '').trim().toLowerCase()))
+          : [];
+        for (const run of activeRuns) {
+          const runId = cleanText(run.workflow_run_id || run.workflowRunId);
+          if (runId && !resolvedRuns.includes(runId)) {
+            resolvedRuns.push(runId);
+          }
+          if (!resolvedWorkflowId) {
+            resolvedWorkflowId = cleanText(run.workflow_id || run.workflowId) || resolvedWorkflowId;
+          }
+        }
+      }
+    }
+
+    if (!resolvedWorkflowId) {
+      throw new Error('workflowId could not be resolved for project cleanup.');
+    }
+    if (resolvedRuns.length === 0) {
+      throw new Error('workflowRunIds could not be resolved for project cleanup.');
+    }
+
+    return this._request('/api/operator/cleanup', {
+      method: 'POST',
+      body: {
+        project_id: normalizedProjectId,
+        workflow_id: resolvedWorkflowId,
+        workflow_run_ids: resolvedRuns,
+        reason: normalizedReason,
+        operator_identity: normalizedOperatorIdentity,
+        run_terminal_status: cleanText(runTerminalStatus) || 'failed',
+      },
+    });
+  }
+
+  async closeActiveProject(projectId, options = {}) {
+    return this.closeProject(projectId, options);
+  }
+
   async getProjectCharterReport(projectId) {
     return this._request(`/api/operator/projects/${projectId}/charter/report`);
   }