@bpmsoftwaresolutions/ai-engine-client

Full-surface npm client for the AI Engine. The SDK is now workflow-oriented and composed from focused domain modules, shared transport, and compatibility aliases.

No repo clone required. Install the package, point it at the Azure service, and call any method. Replit can stay around as a sandbox or development target, but production examples below use Azure Container Apps.

Install

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

import { AIEngineClient } from '@bpmsoftwaresolutions/ai-engine-client';

const client = new AIEngineClient({
  baseUrl: 'https://resume-generator-api.politehill-3458aba1.eastus.azurecontainerapps.io',
  // pass the key via a custom header or interceptor
});

// Health
const health = await client.ping();

// Load current SQL memory projection (startup hydration)
const memory = await client.getLatestMemoryProjection();

// Create a project charter (writes to durable SQL memory)
const charter = await client.createProjectCharter({
  projectName: 'Data-Driven UI',
  objective: 'Build a Postgres-backed data-driven UI system with a stable renderer and live operator panel.',
  businessContext: 'Enables live demo edits during sales calls without code deploys.',
  successCriteria: 'Pages, blocks, and tokens are fully CRUD-managed via API. Renderer is frozen.',
  priority: 'high',
  inScope: ['pages', 'blocks', 'style tokens', 'versions', 'operator panel'],
  outOfScope: ['drag-and-drop builder', 'custom animation engine'],
});

// 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 claimed = await client.startClaimedWork({
  claimName: 'spring-boot-gateway-charter-commit',
  actorId: 'operator:sid',
  intentId: 'code_mutation',
  declaredScopeFiles: ['scripts/run_charter.py'],
  allowedMutationSurfaces: ['project_roadmap_task'],
  executionPurpose: 'Commit the Spring Boot charter work through a governed claim.',
});

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'],
});

const telemetry = await client.getExecutionTelemetryCurrent();
const processRuns = await client.listExecutionProcessRuns({ limit: 25 });
const generatedUsability = await client.getGeneratedExecutionUsability();
const logaUsability = await client.getLogaGeneratedExecutionUsabilityProjection();

For local sandbox work, point baseUrl at your Replit endpoint or set AI_ENGINE_BASE_URL to a sandbox URL. For production and shared consumers, prefer the verified Azure Container Apps FQDN through AI_ENGINE_BASE_URL, AI_ENGINE_API_BASE_URL, or DEP_AI_ENGINE_BASE_URL.

Architecture Overview

The composed SDK follows this flow:

AIEngineClient → composed namespaces → focused domain modules → shared transport → compatibility aliases → governed request-contract testing

| File | Role | |---|---| | index.js | Public barrel only. Re-exports the client, version, and constants. | | client.js | Constructor, composition root, transport bridge, namespace attachment, and thin compatibility wiring. | | domains/* | Canonical implementation ownership for endpoint bodies and workflow helpers. | | compat/* | Compatibility alias and facade preservation. | | transport/* | Shared request execution, auth header handling, and response shaping. | | utils/* | Shared normalization, parsing, and helper utilities used across domains. | | test/request-contract-fixtures.* | Request-contract parity fixtures that guard the public surface. |

Domain Topology

| Namespace | Responsibility | |---|---| | projects | Project lifecycle, bundle surfaces, closure readiness, and completion views | | projectChartering | Project charter creation and roadmap bootstrap helpers | | roadmaps | Roadmap state, active item lookup, and task-surface visibility | | implementationPackets | Implementation packet operations and workflow binding | | implementationItems | Item status, activity, and verified mutation surfaces | | implementationChecks | Acceptance-check retrieval and status updates | | implementationArtifacts | Artifact manifest, decision packets, and verification | | implementationEvidence | Evidence attachment and proof collection | | implementationGates | Gate decisions for implementation packet review | | agentComms | Governed multi-agent communication and transfer primitives | | collaboration | Collaboration proposals, blockers, ownership, and heartbeats | | executionTelemetry | Execution telemetry, process runs, and monitoring views | | projections | LOGA/runtime markdown projections and navigation surfaces | | retrieval | Symbol and code retrieval helpers | | workflows | Workflow definitions and workflow-run surfaces | | workflowComposition | Legacy modernization composition helpers and compatibility surface | | database | Query, backups, and schema inspection helpers | | skills | Skill contracts and skill governance | | toolRegistry | Tool registry lookup and tool-governance surfaces | | capabilities | Capability discovery and smoke-test surfaces | | performance | Session performance and benchmark summaries | | designIntelligence | Design decision, critique, promotion, and recommendation surfaces | | notesLab | Note submission and review workflow | | searchContacts | Organization and contact lookup | | benchmarks | Benchmark run history and trend lookup |

Workflow-Oriented SDK Model

The SDK is workflow-oriented, not a pile of 370+ isolated methods. Domain namespaces compose into executable workflows, and those workflows map to governed AI Engine operations.

Common workflow families include:

• Agent Session Startup
• Project Chartering
• Governed Work / Claims
• Roadmap Item Execution
• Commit Governance
• Agent Communication
• Work Transfer & Handoff
• Workflow Governance
• Code Analysis & Refactoring
• Retrieval-Augmented Prompt Assembly
• Warehouse Modernization Pipeline

For full workflow chains, see docs/sdk-workflow-taxonomy.md.

Namespace paths are canonical. Top-level methods remain supported compatibility aliases.

Workflow Example

const client = AIEngineClient.fromEnv();

const startup = await client.projectResume.resumeProjectWork({
  projectIdentifier: 'my-project',
  actorMode: 'agent',
  executionIntent: 'continue roadmap delivery',
});

const activeItem = await client.roadmaps.getProjectRoadmapActiveItem(
  startup.project.project_id,
);

const checks = await client.implementationChecks.getImplementationItemAcceptanceChecks(
  activeItem.implementation_item_id,
);

Workflow and Governance Posture

The SDK is not just CRUD transport. It wraps workflow orchestration, governed execution, claims, session governance, multi-agent coordination, LOGA projections, and evidence-backed workflow delivery.

Execution substrate primitives such as startWork(), completeTurn(), and runCharter() exist to move work through governed stages instead of leaving the caller to assemble those chains manually.

GitShip Workflow Pack

GitShip is exposed as a reusable workflow pack on client.gitShip.

Use the pack when you want to evaluate the SQL-backed promotion authority, inspect the selected run, replay the evidence trail, and close a governed promotion without manually stitching those reads together.

const client = AIEngineClient.fromEnv();

const pack = await client.gitShip.runGitShipPromotion({
  claimId: 'claim-1',
  workflowRunId: 'workflow-1',
  gitshipRunId: 'gitship-run-1',
  headSha: 'abc123',
});

console.log(pack.authority.status);
console.log(pack.inspection.gitship_run.gitship_run_id);

The pack surfaces the following helpers:

• client.gitShip.evaluateGitShipAuthority(...)
• client.gitShip.inspectGitShipRun(...)
• client.gitShip.replayGitShipEvidence(...)
• client.gitShip.runGitShipPromotion(...)
• client.gitShip.closeGitShipPromotion(...)

The same helpers are also grouped under client.gitShip.workflowPack for code that wants a dedicated workflow-pack namespace.

The npm aliases mirror the same workflow pack entry points:

• npm run gitship:run
• npm run gitship:inspect
• npm run gitship:replay
• npm run gitship:evaluate
• npm run gitship:close

Repo-less Retrieval Posture

The retrieval and code-intelligence namespaces are designed for bounded retrieval, symbol lookup, intent discovery, repo-less operation, and governed code-context assembly.

That means the SDK can be used against deployed service state without requiring a local repo clone, while still preserving provenance and the workflow boundaries that make the result safe to execute.

Multi-Agent Coordination

Transfer packets, communication channels, receipts, message watches, presence, handoffs, and collaboration proposals are exposed as governed coordination primitives.

The SDK intentionally models these flows as structured workflows rather than free-form chat so that every cross-agent exchange remains auditable and tied to a bounded work surface.

Namespaces

The extracted domain namespaces are the preferred way to navigate the SDK. Top-level compatibility methods remain available for backward compatibility.

• client.portfolio for portfolio status and closure-readiness views
• client.workflowComposition for modernization and workflow-composition helpers
• client.warehouse as a legacy compatibility alias for the workflow-composition helpers
• client.projects, client.roadmaps, client.projectChartering, and other domain namespaces for the thinner wrapper surfaces

Preferred usage is namespace-first:

await client.projects.getProjectBundle(projectId);
await client.roadmaps.getProjectRoadmap(projectId);
await client.executionTelemetry.getExecutionTelemetryCurrent();
await client.agentComms.openTransferChannel({ projectIdentifier: projectId });

Workspace Projection Preview

The client exposes a bounded read-only workspace projection surface at client.workspaceProjection.

const inspection = await client.workspaceProjection.inspect('11111111-1111-4111-8111-111111111111');

console.log(inspection.packet.projection_id);
console.log(inspection.packet.projection_grants_ship_authority);
console.log(inspection.packet.manifest_required_for_ship);

const preview = await client.workspaceProjection.renderPreview(inspection);
console.table(preview.preview_items);

The projection packet is a bounded work view from SQL truth. It does not grant ship authority, does not grant execution authority, does not expose full repo access, and does not silently materialize a workspace. Artifact preview entries are metadata-only and report whether file content is included or omitted. Disallowed artifacts can appear as omitted metadata, but they are not exposed as accessible workspace content.

The legacy top-level methods still work, so existing callers can move gradually:

await client.getPortfolioClosureReadiness();
await client.workflowComposition.decideModernizationGate();
await client.warehouse.requestModernizationWrapperExecution();

Compatibility Map

The post-split client intentionally keeps the legacy call styles available while exposing the normalized namespace paths:

• client.ping() and client.health.ping() remain available.
• client.query() and client.gateway.query() remain available.
• client.getPortfolioClosureReadiness() and client.portfolio.getPortfolioClosureReadiness() remain available.
• client.registerModernizationAsset() and client.warehouse.registerModernizationAsset() remain available.
• client.workflowComposition.* is the normalized modernization namespace, with client.warehouse.* preserved as the compatibility alias.
• Auth behavior remains unchanged: bearer token auth wins when accessToken or tokenProvider is configured, otherwise the client falls back to the compatibility API key headers.
• Download helpers still return the same markdown and binary payload metadata through the top-level methods.

Surface Map

For quick discovery, the public surface groups like this:

• Top-level aliases: client.ping(), client.query(), client.getPortfolioClosureReadiness(), and the rest of the legacy wrappers.
• Health and query namespaces: client.health, client.gateway, and client.operatorStatus.
• Project delivery namespaces: client.projects, client.projectChartering, client.roadmaps, client.implementationPackets, client.implementationItems, client.implementationArtifacts, client.implementationEvidence, and client.implementationGates.
• Workflow and governance namespaces: client.agentComms, client.collaboration, client.transferChannels, client.presence, client.receipts, client.messageWatch, client.claims, client.sessionGovernance, client.contextOrientation, client.commitGovernance, client.governedImplementation, client.verifiedMutations, client.workflowTurns, and client.charters.
• Compatibility alias: client.warehouse.* still mirrors the modernization helpers, while client.workflowComposition.* is the normalized namespace.

Project Continuation Runtime

Once you know the project identity, use resumeProjectWork() as the canonical startup and hydration call for project work.

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.

Roadmap Closure Workflow

Use closeRoadmapItemWorkflow(...) when you want the client to compose the full roadmap-closure path end to end.

const closure = await client.closeRoadmapItemWorkflow({
  projectIdentifier: charter.project_id,
  claimId: existingClaimId,
});

The helper:

• resumes the project
• loads the active roadmap item
• validates a supplied claim with claimIsValid(claimId)
• starts a fresh claim when the supplied claim is missing or inactive
• loads and verifies acceptance checks
• verifies the required artifacts
• records the implementation gate decision
• advances the item to terminal status
• attaches closure evidence
• signs off the claim
• reloads the active item
• closes the active project when no open tasks remain

The backend still does not expose a project-scoped getActiveClaim(projectId) helper. This client records that gap and uses claimIsValid(claimId) plus claim creation when it needs a governed fallback path.

Agent Communication Channels

Use establishAgentCommunicationChannel(...) when you want the client to compose the governed transfer-channel handshake end to end for a project or work packet.

const channel = await client.establishAgentCommunicationChannel({
  projectIdentifier: charter.project_id,
});

The helper composes:

• resumeProjectWork(...) or startWork(...)
• transferWorkPacket(...)
• openTransferChannel(...)
• joinTransferChannel(...) or resumeTransferChannel(...)
• postCollaborationHeartbeat(...)
• getTransferChannelProjection(...) when available

The returned result includes missing_surfaces[] so the client can record any absent transfer-channel projection or lifecycle surface while still returning a safe partial view tied to governed work.

Inter-Agent Messaging Loop

Use runInterAgentMessagingLoop(...) when a governed transfer channel already exists and the agent needs to send a reply, start an expected-message watch, acknowledge the observed message, heartbeat the channel, and close it only when closure criteria are explicit.

const loop = await client.runInterAgentMessagingLoop({
  channelId: channel.channel_id,
  workTransferPacketId: channel.transfer_packet_id,
  replyBodyMarkdown: 'Confirmed. Proceeding with the next step.',
  closeWhenAcknowledged: true,
});

The helper composes:

• resumeTransferChannel(...)
• replyToTransferChannel(...)
• startMessageWatch(...)
• acknowledgeExpectedMessage(...)
• postCollaborationHeartbeat(...)
• closeTransferChannel(...) when the closure criteria are explicit and satisfied
• getTransferChannelProjection(...) when available

missing_surfaces[] records any absent reply/watch/ack/close/projection surface so the helper can return a safe partial result rather than inventing a free-floating message flow.

Cross-Agent Remediation Tickets

Use createCrossAgentRemediationTicket(...) when one agent needs to file a governed remediation ticket for another agent from an existing channel, finding, blocker, failed check, or workflow gap.

const ticket = await client.createCrossAgentRemediationTicket({
  channelId: channel.channel_id,
  workTransferPacketId: channel.transfer_packet_id,
  assignedTo: 'agent-upstream',
  requestedBy: 'agent-downstream',
  sourceRef: 'finding-42',
  blockerSummary: 'Remediation ownership needs to move upstream.',
  expectedResponse: 'Assignee acknowledgement',
});

The helper composes:

• resumeTransferChannel(...) when a channel is supplied
• transferWorkPacket(...) when ownership must move
• raiseCollaborationBlocker(...)
• reviewCollaborationProposal(...) when a proposal id is supplied
• startMessageWatch(...)
• postCollaborationHeartbeat(...)
• getTransferChannelProjection(...) when available

The helper returns remediation_ticket_id or blocker_id, plus missing_surfaces[] so callers can see any absent governed surface without pretending the ticket was fully established.

Refactoring Bundle Transfer

Use transferRefactoringBundle(...) when one agent needs to package a governed refactoring/remediation bundle and hand it to another agent through the transfer substrate.

const bundle = await client.transferRefactoringBundle({
  projectIdentifier: 'project-1',
  sourceAgent: 'agent-downstream',
  targetAgent: 'agent-upstream',
  sourceRef: 'refactor-42',
  problemStatement: 'Extract the transport orchestration into a shared helper.',
  affectedFilesOrSymbols: ['src/index.js', 'transferRefactoringBundle'],
  recommendedAction: 'Create a shared transfer orchestration helper.',
  acceptanceCriteria: ['bundle received', 'ownership assigned', 'acknowledgement posted'],
  evidenceRefs: ['commit:abc123'],
  riskLevel: 'medium',
  handoffNotes: 'Please review and wire the new helper into the bundle flow.',
});

The helper composes:

• resumeProjectWork(...) or startWork(...)
• transferWorkPacket(...)
• openTransferChannel(...) or resumeTransferChannel(...)
• assignCollaborationOwnership(...)
• postCollaborationProposal(...)
• startMessageWatch(...)
• postCollaborationHeartbeat(...)
• getTransferChannelProjection(...) when available

The helper returns missing_surfaces[] for any absent transfer, ownership, proposal, watch, heartbeat, or projection surface, and it fails closed if no explicit target agent is supplied.

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.

tokenProvider is the preferred boundary for short-lived bearer credentials, with API-key compatibility mode preserved for deployments that still rely on shared keys. The service is expected to migrate toward bearer-oriented OIDC/OAuth flows, but the client preserves the legacy auth shape so existing deployments keep working.

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.

Governed Claim Startup

Use startClaimedWork() when you want the engine to open the oriented context session, create the session-governance state, declare scope, and return the active claim envelope through one promoted surface.

const claimed = await client.startClaimedWork({
  claimName: 'spring-boot-gateway-charter-commit',
  actorId: 'operator:sid',
  intentId: 'code_mutation',
  declaredScopeFiles: [
    'scripts/run_charter.py',
    'src/contracts/charters/spring-boot-governed-execution-gateway.charter.json',
  ],
  allowedMutationSurfaces: ['project_roadmap_task'],
  runtimeSessionId: 'codex:main:charter-work',
  executionPurpose: 'Persist the charter-runner fix and Spring Boot charter packet.',
  successCriteria: 'Claim is active and scoped to the intended mutation surface.',
});

console.log(claimed.claim_id, claimed.context_session_id);

This complements the lower-level flow exposed by openContextSession(), acknowledgeReminder(), completeOrientation(), lockContextSessionClaim(), claimWorkItem(), and signoffClaim().

For closure and write preflights, call claimIsValid(claimId) before you attempt roadmap mutations. The client does not yet expose a project-scoped getActiveClaim(projectId) helper because the backend currently only offers claim reads by claim id or by context session.

Text and Binary Downloads

Some methods do not return plain JSON:

• Markdown download helpers return { text, contentType, fileName, headers }.
• LOGA projection helpers return markdown plus governed projection metadata: { text, contentType, headers, logaContract, interactionContract, projectionType, projectionVersion, sourceTruth, sourceVersion, correlationId, refreshPolicy, generatedAt, provenance }.
• Binary download helpers return { arrayBuffer, contentType, fileName }.

Examples:

import fs from 'node:fs';

const markdown = await client.downloadProjectCharterReportMarkdown(projectId);
console.log(markdown.fileName, markdown.contentType);
console.log(markdown.text);

const logaRoadmap = await client.getLogaProjectRoadmapProjection(projectId);
console.log(logaRoadmap.projectionType, logaRoadmap.projectionVersion);
console.log(logaRoadmap.provenance.sourceTruth, logaRoadmap.correlationId);
console.log(logaRoadmap.text);

const logaRoadmapItem = await client.getLogaRoadmapItemProjection(projectId, 'execute-scope-1');
console.log(logaRoadmapItem.projectionType, logaRoadmapItem.provenance.sourceVersion);
console.log(logaRoadmapItem.text);

const audio = await client.downloadExternalAudioRender(audioRenderRunId);
await fs.promises.writeFile('render.mp3', Buffer.from(audio.arrayBuffer));

LOGA Projection Contract

LOGA should use the getLoga*Projection() methods for runtime documents. These endpoints are governed AI Engine transformations: durable SQL state is normalized into typed projection models, transformed into versioned structured markdown, and served with provenance, refresh, and action metadata for LOGA to render.

The flow is:

SQL truth → projection generation → structured markdown → LOGA runtime rendering

Markdown is projection, not authority. Provenance metadata is preserved so renderers can validate origin, version, and refresh behavior before displaying the result. These projections are versioned runtime documents, not free-form documentation files.

The client exposes the transport metadata from response headers so LOGA can validate the contract before rendering:

• logaContract: currently ai-engine-ui/v1
• interactionContract: currently loga-choreography/v1
• projectionType: for example operator.project_roadmap
• projectionWorkflow: currently loga-document-projection
• projectionVersion
• sourceTruth: normally sql
• sourceVersion
• correlationId
• refreshPolicy
• generatedAt
• provenance: grouped copy of the source/projection/version fields

Example:

import {
  AIEngineClient,
  LOGA_CONTRACT,
  LOGA_INTERACTION_CONTRACT,
} from '@bpmsoftwaresolutions/ai-engine-client';

const client = AIEngineClient.fromEnv();
const projection = await client.getLogaProjectRoadmapProjection(projectId);

if (projection.logaContract !== LOGA_CONTRACT) {
  throw new Error(`Unsupported LOGA contract: ${projection.logaContract}`);
}

console.log(projection.interactionContract === LOGA_INTERACTION_CONTRACT);
renderLogaMarkdown(projection.text, {
  projectionType: projection.projectionType,
  provenance: projection.provenance,
});

Execution Telemetry Monitoring

Use the telemetry methods when you want downstream consumers to read the governed API instead of generated files.

const current = await client.getExecutionTelemetryCurrent();
const runs = await client.listExecutionProcessRuns({ limit: 25, artifactKind: 'generated_script' });
const run = await client.getExecutionProcessRun('process-run-1');
const generated = await client.getGeneratedExecutionUsability();
const logaProjection = await client.getLogaGeneratedExecutionUsabilityProjection();

console.log(current.status, runs.process_run_count, run.process_run_id);
console.log(generated.projection_type, logaProjection.projectionType);

The telemetry and LOGA surfaces are read-only and SQL-backed:

• getExecutionTelemetryCurrent()
• listExecutionProcessRuns({ limit, artifactKind, status, since })
• getExecutionProcessRun(processRunId)
• getGeneratedExecutionUsability()
• getLogaGeneratedExecutionUsabilityProjection()

Example shell consumer:

• examples/monitoring/read-execution-telemetry.mjs

Run it with:

AI_ENGINE_BASE_URL="..." AI_ENGINE_ACCESS_TOKEN="..." npm run example:monitoring

fromEnv

const client = AIEngineClient.fromEnv();
// Reads: AI_ENGINE_BASE_URL, AI_ENGINE_ACCESS_TOKEN, AI_ENGINE_API_KEY,
// AI_ENGINE_CLIENT_ID, AI_ENGINE_ACTOR_ID

Constructor Options

| Option | Type | Description | |---|---|---| | baseUrl | string | Required. Base URL of the AI Engine service. | | 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

const client = new AIEngineClient({
  baseUrl: process.env.AI_ENGINE_BASE_URL,
  tokenProvider: async () => {
    const token = await acquireAccessToken();
    return { token };
  },
});

API Key Compatibility

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:

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:

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 import a packet and immediately materialize a visible roadmap surface, use importImplementationPacketAndMaterializeRoadmap(). If you only need the task records, use ensureProjectRoadmapTaskSurface() or createImplementationTask().

A copyable example payload is packaged at examples/implementation-plan-packet.minimal.json.

External Audio Render Example

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

const manifest = await client.listExternalWorkflowRunArtifacts('run-123');
const packet = await client.downloadExternalWorkflowRunArtifact('run-123', 'package_payload');

Methods

Health

| 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. | | claimWorkItem(body) | Bind an oriented, claim-locked context session to a concrete work item and return the active claim envelope. | | claimIsValid(claimId) | Read a claim by id and confirm that it is still active before attempting a governed write. | | 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. | | 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 | |---|---| | currentWorkflowStatus() | Current workflow run state. | | currentArchitectureIntegrityStatus() | Architecture integrity scan results. | | currentSecurityGovernanceStatus({ environment, topN }) | Security governance findings. | | currentCodebaseShapeStatus() | Codebase shape analysis. | | 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. |

LOGA Projections

| Method | Endpoint | Description | |---|---|---| | getLogaOperatorHomeProjection() | GET /api/operator/projections/home | Governed operator home runtime markdown document. | | getLogaProjectCatalogProjection() | GET /api/operator/projections/project-catalog | Governed project catalog runtime markdown document. | | getLogaProjectPortfolioProjection() | GET /api/operator/projections/project-portfolio | Governed portfolio rollup runtime markdown document with SQL-backed completion metrics and project buckets. | | getLogaProjectRoadmapProjection(projectId) | GET /api/operator/projections/projects/:projectId/roadmap.md | Governed project roadmap runtime markdown document. | | getLogaRoadmapItemProjection(projectId, itemKey) | GET /api/operator/projections/projects/:projectId/roadmap/items/:itemKey | Governed roadmap item runtime markdown document with item-level navigation, related documents, actions, and evidence. | | getLogaWorkflowRunProjection(workflowRunId) | GET /api/operator/projections/workflow-runs/:workflowRunId | Governed workflow run runtime markdown document. | | getLogaEvidencePacketProjection(packetKey) | GET /api/operator/projections/evidence-packets/:packetKey | Governed evidence packet runtime markdown document. | | submitUxGateRemediation(body) / client.loga.submitUxGateRemediation(body) | POST /api/loga/ux-gate-remediations | Create a governed SQL-backed remediation ticket for a UX gate failure. | | listUxGateRemediations({ projectionType, status }) / client.loga.listUxGateRemediations(...) | GET /api/loga/ux-gate-remediations | List governed UX gate remediation tickets. | | getUxGateRemediation(remediationId) / client.loga.getUxGateRemediation(...) | GET /api/loga/ux-gate-remediations/:remediationId | Read one governed UX gate remediation ticket. | | appendUxRemediationTicketNote(remediationId, body) / client.loga.appendUxRemediationTicketNote(...) | POST /api/loga/ux-gate-remediations/:remediationId/notes | Append a governed downstream-facing remediation note to a UX gate remediation ticket. | | listUxRemediationTicketNotes(remediationId) / client.loga.listUxRemediationTicketNotes(...) | GET /api/loga/ux-gate-remediations/:remediationId/notes | List governed remediation notes for a UX gate remediation ticket. | | promoteUxGateRemediationImplementationCandidate(remediationId, { promotedBy }) / client.loga.promoteUxGateRemediationImplementationCandidate(...) | POST /api/loga/ux-gate-remediations/:remediationId/implementation-candidate | Promote a governed UX remediation ticket into a durable implementation packet candidate. | | getLogaUxGateRemediationProjection(remediationId) / client.loga.getUxGateRemediationProjection(...) | GET /api/operator/projections/ux-gate-remediations/:remediationId | Review a governed UX remediation ticket and its linked implementation candidate as a LOGA runtime document. |

These methods return markdown as text and expose projection headers as top-level fields plus provenance. LOGA should render the markdown emitted by AI Engine and use these metadata fields for contract validation, refresh behavior, evidence display, and action choreography.

UX gate remediation is not a generic note or implementation-item evidence path. LOGA clients should use submitUxGateRemediation() when a projection fails a UX gate and should include sourceTruth: 'sql', the projection identity, affected finding ids, and client evidence about the failing gate.

Generated Scripts

| Method | Endpoint | Description | |---|---|---| | generateScript(body) / client.scripts.generate(body) | POST /api/scripts/generate | Create a governed diagnostic-only helper script bound to claim, session, or workflow context. | | renderScript(scriptId) / client.scripts.render(scriptId) | GET /api/scripts/:scriptId/render | Read the rendered helper script, shell-safe usage guidance, and SQL provenance. | | submitScriptArtifact(scriptId, body) / client.scripts.submitArtifact(scriptId, body) | POST /api/scripts/:scriptId/artifacts | Submit governed execution evidence and attach a workflow artifact for the generated script run. | | getScriptRunEvidence({ workflowRunId, scriptId }) / client.scripts.getRunEvidence(...) | GET /api/scripts/run-evidence | List SQL-backed generated script runs and their evidence for a workflow run or one script id. |

Generated scripts are ephemeral helpers, not source-of-truth. The server keeps SQL authority over the run ledger and defaults each script to diagnostic_only, local_helper, and file/stdin-safe usage instead of fragile long inline commands.

Retrieval Wrapper

| Method | Description | |---|---| | getCommandCard({ commandKey, alias, intentText, requestedBy }) | Resolve a command card by key, alias, or intent. | | resolveOperatingProcedure({ procedureKey, intentText, requestedBy }) | Resolve an operating procedure. | | getSymbolDefinition({ symbolName, qualifiedName, ... }) | Symbol/code definition lookup. | | getRelatedCode({ symbolKey, qualifiedName, relationshipType, ... }) | Related code lookup. |

Repo Inventory

| Method | Description | |---|---| | listRepositories({ limit }) | List inventoried repositories. | | getRepository(repositoryId) | Get repository detail. | | listProjects({ repositoryId, repoKey, limit }) | List inventoried projects. | | 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 | |---|---| | getRetrievalStatus() | Retrieval status dashboard. | | getRetrievalProfileMetrics() | Profile-level retrieval metrics. | | getRetrievalFeedbackMetrics() | Feedback signal metrics. | | getRetrievalQuery(id) | Get retrieval query detail. | | getRetrievalPacket(id) | Get retrieval packet detail. | | generateRetrievalCandidates(body) | Generate candidate packets. | | selectRetrievalPacket(body) | Select a packet for use. | | recordRetrievalFeedback(body) | Record feedback on a retrieval result. | | deriveRetrievalOptimizationCandidates(body) | Derive optimization candidates. | | validatePromptAssembly(body) | Validate a prompt assembly. |

Workflows

| Method | Description | |---|---| | listWorkflows({ status, includeSteps }) | List workflows. | | createWorkflow({ name, slug, description, goal, ... }) | Create a workflow draft. | | getWorkflow(workflowId) | Get workflow detail. | | replaceWorkflowSteps(workflowId, steps) | Replace workflow steps. | | publishWorkflow(workflowId) | Publish a workflow. | | cloneWorkflow(workflowId) | Clone a workflow. |

Workflow Governance

| Method | Description | |---|---| | evaluateWorkflowGovernance(workflowId) | Run governance evaluation. | | listWorkflowGovernanceDecisions(workflowId) | List governance decisions. | | getWorkflowGovernanceSimulation(workflowId) | Governance simulation packet. | | listWorkflowGovernanceBundles(workflowId) | Gate bundles. | | listWorkflowGovernanceApprovals(workflowId) | Gate approvals. | | listWorkflowGovernanceEvents(workflowId) | Gate events. | | getWorkflowGovernanceReview(workflowId) | Governance review. | | createWorkflowGovernanceReviewDecision(workflowId, body) | Record a review decision. |

Workflow Runs

| Method | Description | |---|---| | createWorkflowRun(body) | Start a workflow run. | | 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. |

Manual & Approval Tasks

| Method | Description | |---|---| | listManualTasks() | List tasks awaiting manual completion. | | listApprovalTasks() | List tasks awaiting approval. | | completeManualTask(stepRunId, body) | Complete a manual step. | | approveTask(stepRunId, body) | Approve a step. |

Projects & Chartering

| Method | Description | |---|---| | 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. | | resumeProjectWork({ projectIdentifier, actorMode, executionIntent, requireClaim, workflowRunLimit }) | Resume the governed continuation brief for a project. |

Roadmaps

| Method | Description | |---|---| | listProjectRoadmaps({ includeInactive }) | List all project roadmaps. | | getProjectRoadmap(projectId) | Get full roadmap for a project. | | getProjectRoadmapSummary(projectId) | Roadmap summary. | | getProjectRoadmapActiveItem(projectId) | Current active roadmap item. | | closeRoadmapItemWorkflow({ projectIdentifier, claimId, actorMode, executionIntent, workflowRunLimit, requiredArtifacts, requiredAcceptanceCheckStatus, terminalItemStatus, gateType, gateDecision, closeProjectIfNoRemainingOpenItems }) | Compose roadmap closure end to end: resume, claim fallback, verify checks/artifacts, record a gate decision, sign off, and close the project when nothing remains open. | | 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. | | importImplementationPacketAndMaterializeRoadmap(packetPayload, { importedBy, requestedBy, createdBy, workflowId, bindingRole, assignedTo, notes, createAcceptanceSubtasks }) | Import a governed implementation packet, bind it to the project workflow, and materialize the roadmap projection. | | listProjectOpenTasks(projectId) | Open tasks for a project. | | getProjectPerformanceMetrics(projectId, { workflowId, workflowRunId, sinceUtc }) | Performance metrics. |

Implementation Tasks

| 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. | | assignImplementationTask(taskId, { assignedTo, assignedBy }) | Assign a task. | | completeImplementationTask(taskId, { completedBy }) | Mark complete. |

Governed Implementation

Current package version: 1.1.71.

| Method | Description | |---|---| | importImplementationPacket(body) | Import an implementation packet. | | listImplementationPackets({ status, packetType }) | List packets. | | getImplementationPacket(packetId) | Packet detail. | | updateImplementationItemStatus(itemId, body) | Update item status. | | addImplementationItemEvidence(itemId, body) | Add evidence link. | | addImplementationItemActivity(itemId, body) | Add activity entry. | | listImplementationItemActivity(itemId) | List item activity. | | updateAcceptanceCheckStatus(itemId, checkId, body) | Update acceptance check. | | createImplementationPacketGateDecision(packetId, body) | Record gate decision. | | bindImplementationPacketToWorkflow(workflowId, body) | Bind packet to workflow. | | importImplementationPacketAndMaterializeRoadmap(packetPayload, { importedBy, requestedBy, createdBy, workflowId, bindingRole, assignedTo, notes, createAcceptanceSubtasks }) | Import, bind, materialize tasks, and read back roadmap counts in one call. | | getWorkflowImplementationRoadmap(workflowId) | Workflow-linked roadmap. | | getWorkflowResumeContext(workflowId) | Resume context. |

Governed roadmap item mutations must carry claim context. Include the active claim in the request body:

await client.updateImplementationItemStatus(itemId, {
  status: 'done',
  status_reason: 'Evidence attached and gates passed.',
  updated_by: 'operator:loga',
  claimed_item_id: itemId,
  agent_session_id: 'agent-session-id',
  claim_workflow_run_id: 'workflow-run-id',
});

The same claim envelope applies to addImplementationItemEvidence(), addImplementationItemActivity(), and updateAcceptanceCheckStatus(). If the claim is missing, AI Engine returns 409 with error: missing_governed_claim. If the claim exists but unresolved gates remain, AI Engine returns the required gate and next action.

Skills

| Method | Description | |---|---| | currentSkillRegistryStatus() | Current skill registry status. | | getSkillContract({ skillId, skillKey }) | Skill contract. | | getSkillGovernance({ skillId, skillKey, skillVersionId }) | Skill governance posture. | | createSkillContractDraft(body) | Create a skill contract draft. | | recordSkillPatternReview(skillVersionId, body) | Record pattern review. | | approveSkillContract(skillVersionId, body) | Approve skill contract. | | createWorkflowSkillContract(body) | Create workflow skill contract. | | listWorkflowSkillBindings(workflowId, { workflowStepId }) | List skill bindings. | | seedFrequentOperationSkills({ createdBy }) | Seed frequent operation skills. |

Skill Governance

| Method | Description | |---|---| | createSkillGovernanceChange(body) | Create a skill governance change. | | listSkillGovernanceChanges({ limit, processStatus, changeStatus }) | List changes. | | getSkillGovernanceChange(governanceChangeId) | Change detail. |

Capabilities

| Method | Description | |---|---| | listCapabilities() | List capabilities. | | createCapability(body) | Create a capability. | | testCapability(capabilityId, body) | Test a capability. |

Tool Registry

| Method | Description | |---|---| | currentToolRegistryStatus() | Current tool registry status. | | getWorkflowToolRegistry({ workflowId, workflowSlug }) | Workflow-scoped tool registry. | | currentAssistantToolContext() | Current assistant tool context. | | getTool(toolKey) | Tool definition detail. | | getToolHistory(toolKey) | Tool version history. | | getToolInvocations(toolKey) | Tool invocation history. | | getToolGovernance(toolKey) | Tool governance posture. | | getToolEventReplayBundle(toolEventSummaryId) | Tool execution replay bundle. | | createToolReviewDecision(toolKey, body) | Create tool review decision. | | createToolGateDecision(toolKey, body) | Create tool gate decision. |

Context Assembly

| Method | Description | |---|---| | getContextAssemblyContract(workflowRunId, { stepRunId }) | Context assembly contract. | | getContextAssemblyStatus(workflowRunId, { stepRunId }) | Context assembly status. | | getOperatorContext(workflowRunId, { stepRunId }) | Operator context for a run. | | getContextFragments(workflowRunId, { stepRunId }) | Context fragments. | | getContextReuse(workflowRunId, { stepRunId }) | Context reuse metrics. | | listPromptAssemblies(workflowRunId) | Prompt assembly history. |

Performance

| Method | Description | |---|---| | getSessionPerformanceMetrics({ clientType, workflowRunId, sessionId }) | Session metrics. | | captureBenchmarkSnapshot(body) | Capture benchmark snapshot. | | listBenchmarks({ benchmarkScope }) | List benchmarks. | | getBenchmarkMetrics(benchmarkName) | Metrics for a benchmark. | | getBenchmarkDelta({ baseline, current }) | Compare two benchmarks. | | getBenchmarkTrend({ metricKey, dimensionValue, limit }) | Metric trend. | | getPerformanceDashboard({ clientType, workflowRunId }) | Performance dashboard. |

Portfolio

| Method | Description | |---|---| | getPortfolioStatus({ projectId }) | Portfolio status. | | getPortfolioSummary() | Portfolio summary. | | getPortfolioExceptions() | Portfolio exceptions. | | getPortfolioProject(projectId) | Project detail via portfolio. | | getPortfolioReport() | Full portfolio report. | | getPortfolioBundle() | Portfolio bundle. | | getPortfolioClosureReadiness({ projectLimit, includeInactive, includeLogaPortfolioProjection, includeLogaRoadmapProjections }) | Read-only portfolio readiness view that composes bundle, project list, roadmap summaries, active items, and open task counts into a conservative closure-ready flag. |

Warehouse

| Method | Description | |---|---| | registerModernizationAsset({ projectIdentifier, assetName, assetType, sourceRef, originSystem, businessContext, suspectedValue, knownRisks, relatedProjectId, evidenceRefs, handoffNotes, assignedClassifier, classificationRequired }) | Register a modernization asset intake record when the backend surface exists, attach governed intake evidence or observations when available, and optionally hand off classification to another agent through the transfer substrate. Missing asset-intake or observation surfaces are recorded in missing_surfaces[], and generated markdown projections are treated only as display metadata. | | classifyModernizationAsset({ projectIdentifier, assetId, intakeRecordId, assetType, sourceRef, classificationCategory, domainArea, reusePotential, modernizationNeed, knownRisks, evidenceRefs, recommendedNextStep, classificationConfidence, reviewRequired, assignedReviewer, handoffNotes }) | Classify a registered modernization asset into reusable warehouse categories using caller-supplied evidence only. The helper looks up the registered asset or intake record when that backend surface exists, records missing classification surfaces in missing_surfaces[], and can hand the review to another agent through the transfer substrate without treating generated projections as authority. | | discoverSalvageCandidates({ projectIdentifier, assetId, intakeRecordId, classificationId, sourceRef, classificationCategory, domainArea, reusePotential, modernizationNeed, knownRisks, evidenceRefs, recommendedNextStep, reviewRequired, assignedReviewer, relatedSymbols, relatedQualifiedNames, relatedFilePaths, candidateSearchIntent, candidateSearchQuery, maxCandidates }) | Identify salvage candidates from a classified modernization asset using governed inventory and retrieval surfaces only. The helper records missing code-discovery surfaces in missing_surfaces[], composes symbol and related-code lookup when available, and can hand the candidate review to another agent without inspecting local files or generated projections as authority. | | createModernizationWorkPacket({ projectIdentifier, assetId, intakeRecordId, classificationId, selectedCandidates, candidateIds, sourceRef, packetTitle, problemStatement, recommendedModernization, affectedFilesOrSymbols, acceptanceCriteria, riskLevel, evidenceRefs, wrapperExecutionRequired, handoffNotes, targetAgent, assignedOwner, collaborationRequired, channelId, transferChannelId }) | Convert selected salvage candidates into a governed modernization work packet. The helper prefers governed packet and candidate records when available, falls back to transferWorkPacket(...) when the dedicated packet surface is missing, and records any absent packet, candidate, proposal, channel, watch, or heartbeat surfaces in missing_surfaces[]. Generated projections remain display metadata only. | | requestModernizationWrapperExecution({ projectIdentifier, modernizationPacketId, wrapperName, wrapperContractRef, sourceRef, executionScope, allowedBlastRadius, requiredEvidence, acceptanceCriteria, riskLevel, targetAgent, handoffNotes, collaborationRequired, channelId, transferChannelId, wrapperExecutionRequired }) | Turn a modernization work packet into a governed wrapper execution request. The helper prefers a dedicated wrapper-request surface when available, falls back to transferWorkPacket(...) as the safe governed handoff when that surface is missing, and records missing packet, wrapper-request, channel, ownership, watch, or heartbeat surfaces in missing_surfaces[]. Generated projections remain display metadata only. | | getModernizationWrapperEvidence({ projectIdentifier, modernizationPacketId, wrapperExecutionRequestId, wrapperExecutionId, sourceRef, includeOperations, includeFileManifest, includeVerificationSummary, includeProjection }) | Read back wrapper evidence for a modernization packet or wrapper execution request without inventing evidence or treating projections as authority. The helper prefers a governed wrapper-evidence bundle when available, falls back to component reads only when those surfaces exist, and records missing packet, request, evidence, operation-log, manifest, verification, or projection surfaces in missing_surfaces[]. | | decideModernizationGate({ projectIdentifier, modernizationPacketId, wrapperExecutionRequestId, wrapperExecutionId, sourceRef, requiredEvidence, acceptanceCriteria, decisionMode, decisionBand, reviewer, reviewRequired, riskLevel, rationale, recordDecision, reviewChannelId, implementationItemId, submittedBy }) | Turn wrapper evidence into a conservative modernization gate recommendation or recorded gate decision. The helper requires complete wrapper evidence before it can recommend a pass, records missing packet, evidence, acceptance-criteria, gate-decision, evidence-link, watch, heartbeat, or projection surfaces in missing_surfaces[], and treats generated projections as display metadata only. |

Self-Learning

| Method | Description | |---|---| | getSelfLearningPosture({ workflowRunId, limit }) | Self-learning posture. | | listLearningRecords({ workflowRunId, learningCategory, promotionReadiness, limit }) | Learning records. | | getLearningRecord(learningRecordId) | Learning record detail. | | listPromotionCandidates({ workflowRunId, learningCategory, promotionReadiness, limit }) | Promotion candidates. | | getPromotionCandidate(candidateKey) | Candidate detail. | | listPromotionFlows({ flowStatus, targetType, candidateKey, limit }) | Promotion flows. |

Self-Optimization

| Method | Description | |---|---| | getSelfOptimizationDashboard() | Self-optimization dashboard. | | getSelfOptimizationCandidateQueue({ objectiveCategory, impactPosture, blockedByDefault, limit }) | Candidate queue. | | getSelfOptimizationBacklogPosture({ snapshotKey }) | Backlog posture. | | getSelfOptimizationPendingHandoffs({ downstreamLane }) | Pending handoffs. |

Governance

| Method | Description | |---|---| | getAntiPatternRules() | SQL-backed governance anti-pattern rules. |

Design Intelligence

| Method | Description | |---|---| | getDesignIntelligenceDashboard() | Design intelligence dashboard. | | listDesignDecisions() | List design decisions. | | getDesignDecision(decisionId) | Decision detail. | | getDesignDecisionVariants(decisionId) | Decision variants. | | getDesignDecisionCritique(decisionId) | Decision critique. | | getDesignDecisionLineage(decisionId) | Decision lineage. | | listDesignPatterns() | Design patterns. | | getDecisionLabCanvas() | Decision lab canvas. | | getDesignRecommendations() | Design recommendations. | | getDesignPromotions() | Design promotions. | | previewDesignPromotion(body) | Preview promotion action. | | getDesignIntelligenceMetrics() | Design intelligence metrics. |

Script Discovery

| Method | Description | |---|---| | scanScripts(body) | Scan for discoverable scripts. | | listDiscoveredScriptAssets({ limit }) | Discovered script assets. | | listDiscoveredCapabilities({ limit }) | Discovered capabilities. | | listWorkflowCandidates({ limit }) | Workflow candidates. | | promoteWorkflowCandidate(workflowCandidateId, body) | Promote a workflow candidate. |

Notes Lab

| Method | Description | |---|---|