dominus-sdk-nodejs 1.28.0 → 1.28.3

package/docs/usage-reference.md

@@ -2,7 +2,7 @@
 
 Generated from `src/namespaces/**/*.ts` method signatures and JSDoc comments.
 
-Total namespaced commands: **367**.
+Total namespaced commands: **379**.
 
 Columns: `Command` is the method path on the singleton, `Params` is the expected parameter signature, `Returns` is the declared TypeScript return type, `Route` is the backend endpoint (or local behavior), and `What it does` is the method summary.
 
@@ -54,20 +54,20 @@ Source: `src/namespaces/redis.ts` (RedisNamespace)
 
 | Command | Params | Returns | Route | What it does |
 |---|---|---|---|---|
-| `dominus.redis.set` | `key: string, value: unknown, ttl?: number, category?: string` | `Promise<SetResult>` | `POST /api/whisperer/set` | Set a value with TTL. |
-| `dominus.redis.get` | `key: string, options?: { category?: string; nudge?: boolean; ttl?: number }` | `Promise<GetResult>` | `POST /api/whisperer/get` | Get a value, optionally refreshing TTL. |
-| `dominus.redis.delete` | `key: string, category?: string` | `Promise<{ deleted: boolean }>` | `POST /api/whisperer/delete` | Delete a key. |
-| `dominus.redis.list` | `options?: { prefix?: string; category?: string; limit?: number; cursor?: string; }` | `Promise<ListResult>` | `POST /api/whisperer/list` | List keys by prefix with pagination. |
-| `dominus.redis.mget` | `keys: Array<{ logical_path: string; category?: string }>` | `Promise<{ results: Array<GetResult> }>` | `POST /api/whisperer/mget` | Get multiple keys at once. |
-| `dominus.redis.setnx` | `key: string, value: unknown, ttl?: number, category?: string` | `Promise<SetnxResult>` | `POST /api/whisperer/setnx` | Set if not exists (for distributed locks). |
-| `dominus.redis.incr` | `key: string, delta?: number, ttl?: number, category?: string` | `Promise<IncrResult>` | `POST /api/whisperer/incr` | Increment counter (creates if not exists). |
-| `dominus.redis.hset` | `key: string, field: string, value: unknown, ttl?: number, category?: string` | `Promise<HsetResult>` | `POST /api/whisperer/hset` | Set a hash field. |
-| `dominus.redis.hget` | `key: string, field: string, category?: string` | `Promise<GetResult>` | `POST /api/whisperer/hget` | Get a hash field. |
-| `dominus.redis.hgetall` | `key: string, category?: string` | `Promise<HgetallResult>` | `POST /api/whisperer/hgetall` | Get all fields from a hash. |
-| `dominus.redis.hdel` | `key: string, field: string, category?: string` | `Promise<{ deleted: boolean }>` | `POST /api/whisperer/hdel` | Delete a hash field. |
-| `dominus.redis.type` | `key: string, category?: string` | `Promise<TypeResult>` | `POST /api/whisperer/type` | Get the Redis data type of a key. |
-| `dominus.redis.smembers` | `key: string, category?: string` | `Promise<SmembersResult>` | `POST /api/whisperer/smembers` | Get all members of a Redis set. |
-| `dominus.redis.lrange` | `key: string, options?: { start?: number; stop?: number; category?: string }` | `Promise<LrangeResult>` | `POST /api/whisperer/lrange` | Get a range of items from a Redis list. |
+| `dominus.redis.set` | `key: string, value: unknown, ttl?: number, category?: string` | `Promise<SetResult>` | `POST /api/redis/set` | Set a value with TTL. |
+| `dominus.redis.get` | `key: string, options?: { category?: string; nudge?: boolean; ttl?: number }` | `Promise<GetResult>` | `POST /api/redis/get` | Get a value, optionally refreshing TTL. |
+| `dominus.redis.delete` | `key: string, category?: string` | `Promise<{ deleted: boolean }>` | `POST /api/redis/delete` | Delete a key. |
+| `dominus.redis.list` | `options?: { prefix?: string; category?: string; limit?: number; cursor?: string; }` | `Promise<ListResult>` | `POST /api/redis/list` | List keys by prefix with pagination. |
+| `dominus.redis.mget` | `keys: Array<{ logical_path: string; category?: string }>` | `Promise<{ results: Array<GetResult> }>` | `POST /api/redis/mget` | Get multiple keys at once. |
+| `dominus.redis.setnx` | `key: string, value: unknown, ttl?: number, category?: string` | `Promise<SetnxResult>` | `POST /api/redis/setnx` | Set if not exists (for distributed locks). |
+| `dominus.redis.incr` | `key: string, delta?: number, ttl?: number, category?: string` | `Promise<IncrResult>` | `POST /api/redis/incr` | Increment counter (creates if not exists). |
+| `dominus.redis.hset` | `key: string, field: string, value: unknown, ttl?: number, category?: string` | `Promise<HsetResult>` | `POST /api/redis/hset` | Set a hash field. |
+| `dominus.redis.hget` | `key: string, field: string, category?: string` | `Promise<GetResult>` | `POST /api/redis/hget` | Get a hash field. |
+| `dominus.redis.hgetall` | `key: string, category?: string` | `Promise<HgetallResult>` | `POST /api/redis/hgetall` | Get all fields from a hash. |
+| `dominus.redis.hdel` | `key: string, field: string, category?: string` | `Promise<{ deleted: boolean }>` | `POST /api/redis/hdel` | Delete a hash field. |
+| `dominus.redis.type` | `key: string, category?: string` | `Promise<TypeResult>` | `POST /api/redis/type` | Get the Redis data type of a key. |
+| `dominus.redis.smembers` | `key: string, category?: string` | `Promise<SmembersResult>` | `POST /api/redis/smembers` | Get all members of a Redis set. |
+| `dominus.redis.lrange` | `key: string, options?: { start?: number; stop?: number; category?: string }` | `Promise<LrangeResult>` | `POST /api/redis/lrange` | Get a range of items from a Redis list. |
 
 ## dominus.files
 
@@ -472,15 +472,15 @@ Source: `src/namespaces/ai.ts` (WorkflowSubNamespace)
 
 | Command | Params | Returns | Route | What it does |
 |---|---|---|---|---|
-| `dominus.ai.workflow.execute` | `options: WorkflowExecuteOptions` | `Promise<WorkflowResult>` | `POST /api/orchestration/execute` | Execute a multi-agent workflow. |
-| `dominus.ai.workflow.streamExecute` | `options: Omit<WorkflowExecuteOptions, 'mode'>` | `AsyncGenerator<Record<string, unknown>, void, unknown>` | `POST /api/orchestration/execute` | Execute a workflow with SSE streaming. |
+| `dominus.ai.workflow.execute` | `options: WorkflowExecuteOptions` | `Promise<WorkflowResult>` | `POST /api/orchestration/execute` | Execute a raw inline multi-agent workflow definition. |
+| `dominus.ai.workflow.streamExecute` | `options: Omit<WorkflowExecuteOptions, 'mode'>` | `AsyncGenerator<Record<string, unknown>, void, unknown>` | `POST /api/orchestration/execute` | Execute a raw inline workflow definition with SSE streaming. |
 | `dominus.ai.workflow.validate` | `workflowDefinition: WorkflowDefinition \| Record<string, unknown>` | `Promise<WorkflowValidationResult>` | `POST /api/orchestration/validate` | Validate a workflow definition without executing. |
 | `dominus.ai.workflow.messages` | `executionId: string, options?: { count?: number }` | `Promise<Message[]>` | `GET /api/orchestration/messages/${executionId}?count=${count}` | Get agent messages from an execution. |
 | `dominus.ai.workflow.events` | `executionId: string, fromId?: string` | `Promise<Record<string, unknown>[]>` | `GET /api/orchestration/events/${executionId}[?from_id=...]` | Replay events from an execution (for reconnection). |
 | `dominus.ai.workflow.status` | `executionId: string` | `Promise<WorkflowExecutionStatus>` | `GET /api/orchestration/status/${executionId}` | Get async execution status (for polling). |
 | `dominus.ai.workflow.output` | `executionId: string` | `Promise<WorkflowExecutionOutput>` | `GET /api/orchestration/output/${executionId}` | Get final execution output (for async mode). |
 | `dominus.ai.workflow.cancel` | `executionId: string` | `Promise<WorkflowCancelResult>` | `POST /api/orchestration/cancel/${executionId}` | Cancel a running workflow execution. |
-| `dominus.ai.workflow.createRun` | `options: CreateRunOptions` | `Promise<WorkflowRun>` | `POST /api/orchestration/runs` | Phase 1: Create a workflow run and get the run_id. |
+| `dominus.ai.workflow.createRun` | `options: CreateRunOptions` | `Promise<WorkflowRun>` | `POST /api/orchestration/runs` | Phase 1: Create a raw inline workflow run and get the run_id. |
 | `dominus.ai.workflow.startRun` | `runId: string, options?: StartRunOptions` | `Promise<WorkflowResult>` | `POST /api/orchestration/runs/${runId}/start` | Phase 2: Start a workflow run after artifacts are uploaded. |
 | `dominus.ai.workflow.getRun` | `runId: string` | `Promise<WorkflowRun>` | `GET /api/orchestration/runs/${runId}` | Get the run status and details. |
 | `dominus.ai.workflow.getManifest` | `runId: string` | `Promise<RunManifest>` | `GET /api/orchestration/runs/${runId}/manifest` | Get the initialization manifest for a run. |
@@ -508,9 +508,18 @@ Source: `src/namespaces/workflow.ts` (WorkflowNamespace)
 | `dominus.workflow.listTemplates` | `none` | `Promise<WorkflowMetadata[]>` | `GET /api/workflow/templates` | List available templates. |
 | `dominus.workflow.getTemplate` | `templateId: string, options?: { includeContent?: boolean }` | `Promise<WorkflowWithContent>` | `GET /api/workflow/templates/${templateId}[?include_content=true]` | Get a template by ID. |
 | `dominus.workflow.copyTemplate` | `templateId: string, options?: { name?: string; tenantSlug?: string }` | `Promise<WorkflowMetadata>` | `POST /api/workflow/templates/${templateId}/copy` | Copy a template to create a new workflow. |
-| `dominus.workflow.execute` | `workflowId: string, context?: Record<string, unknown>` | `Promise<ExecutionResult>` | `POST /api/workflow/execute/workflow` | Execute a workflow synchronously. |
-| `dominus.workflow.executeAsync` | `workflowId: string, options?: { context?: Record<string, unknown>; callbackUrl?: string }` | `Promise<AsyncExecutionResult>` | `POST /api/workflow/execute/workflow` | Execute a workflow asynchronously. |
-| `dominus.workflow.executePipeline` | `pipelineId: string, options?: { context?: Record<string, unknown>; callbackUrl?: string }` | `Promise<AsyncExecutionResult>` | `POST /api/workflow/execute/pipeline` | Execute a pipeline (all workflows in sequence). |
+| `dominus.workflow.createRun` | `options: CreateWorkflowRunOptions` | `Promise<WorkflowRunRecord>` | `POST /api/workflow/runs` | Create a saved-workflow run through the workflow-manager facade. |
+| `dominus.workflow.getRun` | `runId: string` | `Promise<WorkflowRunRecord>` | `GET /api/workflow/runs/${runId}` | Get saved-workflow run state. |
+| `dominus.workflow.getManifest` | `runId: string` | `Promise<WorkflowRunManifest>` | `GET /api/workflow/runs/${runId}/manifest` | Get the artifact manifest for a saved-workflow run. |
+| `dominus.workflow.registerArtifact` | `runId: string, options: RegisterWorkflowArtifactOptions` | `Promise<WorkflowRunRecord>` | `POST /api/workflow/runs/${runId}/artifacts` | Register a source artifact with a saved-workflow run. |
+| `dominus.workflow.validateRun` | `runId: string` | `Promise<WorkflowRunValidationResult>` | `POST /api/workflow/runs/${runId}/validate` | Validate that a saved-workflow run is ready to start. |
+| `dominus.workflow.startRun` | `runId: string, options?: StartWorkflowRunOptions` | `Promise<WorkflowRunStartResult>` | `POST /api/workflow/runs/${runId}/start` | Start a saved-workflow run. |
+| `dominus.workflow.streamStartRun` | `runId: string, options?: Omit<StartWorkflowRunOptions, 'mode'>` | `AsyncGenerator<Record<string, unknown>, void, unknown>` | `POST /api/workflow/runs/${runId}/start` | Start a saved-workflow run with SSE streaming. |
+| `dominus.workflow.status` | `executionId: string` | `Promise<WorkflowExecutionStatusResult>` | `GET /api/workflow/executions/${executionId}/status` | Get execution status for a started saved-workflow run. |
+| `dominus.workflow.output` | `executionId: string` | `Promise<WorkflowExecutionOutputResult>` | `GET /api/workflow/executions/${executionId}/output` | Get final execution output for a started saved-workflow run. |
+| `dominus.workflow.messages` | `executionId: string, options?: { count?: number }` | `Promise<Message[]>` | `GET /api/workflow/executions/${executionId}/messages?count=${count}` | Get execution messages for a started saved-workflow run. |
+| `dominus.workflow.events` | `executionId: string, options?: { fromId?: string; count?: number }` | `Promise<Record<string, unknown>[]>` | `GET /api/workflow/executions/${executionId}/events[?from_id=...&count=...]` | Replay execution events for a started saved-workflow run. |
+| `dominus.workflow.cancel` | `executionId: string` | `Promise<CancelWorkflowExecutionResult>` | `POST /api/workflow/executions/${executionId}/cancel` | Cancel a started saved-workflow execution. |
 | `dominus.workflow.seed` | `options?: SeedOptions` | `Promise<SeedResult>` | `POST /api/workflow/admin/seed` | Seed workflow storage with base templates and builtin tools. |
 | `dominus.workflow.factoryReset` | `options: FactoryResetOptions` | `Promise<FactoryResetResult>` | `POST /api/workflow/admin/factory-reset` | Factory reset all workflow data - deletes workflows, tools, and B2 objects. |
 | `dominus.workflow.listTools` | `options?: ListToolsOptions` | `Promise<Tool[]>` | `GET /api/workflow/tools?{filters}` | List tools in the registry. |

package/docs/workflow-hard-cut-release.md

@@ -0,0 +1,23 @@
+# Workflow Hard-Cut Release Notes
+
+## Release Scope
+
+This SDK release aligns the public guidance with the saved-workflow facade, the structured deterministic orchestration cutover, and the native pipeline runner.
+
+Keep describing the workflow surfaces this way:
+
+- `dominus.workflow.*` is the saved-workflow facade
+- `dominus.ai.workflow.*` is raw inline orchestration only
+- `dominus.workflow.executePipeline()` is the supported ordered-pipeline surface
+
+## Release Checklist
+
+1. Build and test the SDK
+2. Verify lifecycle examples still use `createRun -> registerArtifact -> validateRun -> startRun`
+3. Publish release notes that describe the hard cutover and the native pipeline runner surface
+4. Confirm examples use the saved-workflow run lifecycle and `executePipeline()`
+
+## Rollback
+
+- Downgrade target: the previously published production SDK version
+- Rollback trigger: customer reports that saved-workflow runs or native pipelines cannot start

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dominus-sdk-nodejs",
-  "version": "1.28.0",
+  "version": "1.28.3",
   "description": "Node.js SDK for the Dominus Orchestrator Platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,7 +20,7 @@
     "dev": "tsc --watch",
     "clean": "rm -rf dist",
     "prepublishOnly": "npm run build",
-    "test": "node --test",
+    "test": "npm run build && node --test tests/workflow-lifecycle.test.js",
     "lint": "tsc --noEmit"
   },
   "keywords": [