@minicor/mcp-server 4.9.0 → 4.11.0

package/README.md

@@ -298,7 +298,7 @@ After a successful build:
 
 ## Blueprints (the spec front door)
 
-A **Blueprint** is the living spec + context library that owns a job. Instead of hand-writing a job definition, you feed the blueprint's library (SOPs, Loom videos, notes, transcripts, VM walkthrough sessions), let the service synthesize a spec proposal, review and apply it, then `blueprint_build` syncs the spec into a Job and hands the jobs toolset its coordinates (`middlewareId`/`routeId`/`buildId`). One ownership rule: when a route is blueprint-linked, never `register_job` / `update_job` / `add_test_case` on it directly - that trips reverse-drift detection (state `job_ahead`). Drive changes through the spec.
+A **Blueprint** is the living spec + context library that owns a job. Instead of hand-writing a job definition, you feed the blueprint's library (SOPs, Loom videos, notes, transcripts, VM walkthrough sessions), let the service synthesize a spec proposal, review and apply it, then `blueprint_build` syncs the spec into a Job and hands the jobs toolset its coordinates (`middlewareId`/`routeId`/`buildId`). One ownership rule: when a route is blueprint-linked, never `register_job` / `update_job` / `add_test_case` on it directly - that trips reverse-drift detection (state `job_ahead`). Drive changes through the spec. Sanctioned escape hatch for intentional direct edits (e.g. bulk job edits): pass `acknowledgeJobAhead: true` to `update_job` / `add_test_case`; the tool proceeds and the response carries a `job_ahead` warning with the fold-back options (`blueprint_import_cases`, or `blueprint_build` which overwrites the direct edits).
 
 ### The blueprint tools
 
@@ -354,13 +354,19 @@ A **Job** is a middleware route whose behavior is a structured `definition` (a s
 
 | Tool | What it does |
 | --- | --- |
-| `resolve_job_state` | The first call to make when picking up a job. Returns the job's state (draft vs published, test cases, latest test run, recent executions, active build) plus `nextActions` - the concrete next tool calls. A red test run is drilled automatically: failing case → failing step → its `workflowId` (a `dev_mode_load` hint) → a seeded `fromStepId` replay command. Blueprint-owned routes come back with a `blueprint` block: edit those through the spec (`resolve_blueprint_state`), not `update_job`/`add_test_case`. |
+| `resolve_job_state` | The first call to make when picking up a job. Returns the job's state (draft vs published, test cases, latest test run, recent executions, active build) plus `nextActions` - the concrete next tool calls. A red test run is drilled automatically: failing case → failing step → its `workflowId` (a `dev_mode_load` hint) → a seeded `fromStepId` replay command. Blueprint-owned routes come back with a `blueprint` block: edit those through the spec (`resolve_blueprint_state`), not `update_job`/`add_test_case` - or pass `acknowledgeJobAhead: true` to those tools for a sanctioned direct edit that returns a `job_ahead` warning with fold-back options. |
 | `list_middlewares` | List the routers (middlewares) in a workspace - jobs attach to one of these. |
 | `register_middleware` | Create a router jobs attach to. `autoConfigure` (default true) populates the router's `workspaceApiKey` from the workspace's first key; or pass `workspaceApiKey` explicitly. |
 | `register_job` | Create a job - a route backed by a structured `definition` (step graph). |
-| `update_job` | Update a job's `definition`, path, method, or description. `variant: "draft"` writes the draft definition (the teach/build working copy); `variant: "published"` (default) edits the live definition and snapshots a new route version. |
+| `update_job` | Update a job's `definition`, path, method, or description. `variant: "draft"` writes the draft definition (the teach/build working copy); `variant: "published"` (default) edits the live definition and snapshots a new route version. On a blueprint-linked route, pass `acknowledgeJobAhead: true` for an intentional direct edit; the response carries a `job_ahead` warning with fold-back options. |
 | `get_job` | Get a job (route) incl. its `definition` (and `draftDefinition` when one exists); omit `routeId` to list all routes on the router. |
-| `run_job` | Run a job once with an input, poll to completion, return the full `JobExecution` (per-step Minicor deep-links). `variant: "draft"` runs the draft definition. For step-range debugging, `fromStepId` / `toStepId` (both inclusive) run a slice of the step graph, and `seedExecutionId` hydrates `ctx` from a prior execution so mid-graph starts still resolve earlier steps' values. `waitForResult: false` returns the `jobExecutionId` immediately for runs you want to stop or monitor. |
+| `run_job` | Run a job once with an input, poll to completion, return the full `JobExecution` (per-step Minicor deep-links). `variant: "draft"` runs the draft definition. For step-range debugging, `fromStepId` / `toStepId` (both inclusive) run a slice of the step graph, and `seedExecutionId` hydrates `ctx` from a prior execution so mid-graph starts still resolve earlier steps' values. `waitForResult: false` returns the `jobExecutionId` immediately for runs you want to stop or monitor. `webhookId` publishes workflow progress and `job.completed` to a registered destination for that run. |
+| `list_job_webhooks` | List reusable webhook destinations on a router (url, masked auth, `workflowIds`, `includeJob`, plus subscribed `eventTypes`). |
+| `get_job_webhook_events` | Catalog of the five JSON payloads (`workflow.started`, `workflow.step.started`, `workflow.step.completed`, `workflow.completed`, `job.completed`) with examples. |
+| `register_job_webhook` | Register a destination. HTTPS URL only. Subscribe with `includeJob` (`job.completed`, default true) and/or `workflowIds` (`null` = all workflows, `[]` = none, `[ids]` = allow-list). Pass the returned `id` to `run_job`. Response includes example payloads for the events this destination will receive. |
+| `get_job_webhook` | Get one destination. Secrets are never returned. |
+| `update_job_webhook` | Update url, auth, `workflowIds`, and/or `includeJob`. |
+| `delete_job_webhook` | Delete a destination. |
 | `stop_job_execution` | Stop a queued/running execution. This is a cooperative cancel (there is no pause): a queued run cancels immediately; a running one stops at the runner's next checkpoint (between steps, between `forEach` items, or while waiting on a workflow). A workflow already running on the VM is not killed - it finishes on its own; the job just stops waiting. Idempotent for already-cancelled runs. |
 | `list_job_executions` | List a job's executions (paginated summaries, newest first). Filter by `status` (`queued`/`running`/`succeeded`/`partial`/`failed`/`cancelled`) and/or `trigger` (`test` = suite runs; `api,mcp,cron` = live traffic). Use to find a prior run to seed a range run from, a running execution to stop, or the latest failure to inspect. |
 | `get_job_execution` | Fetch one past execution's full trace: status, input, output, `ctx`, per-step results. |
@@ -371,7 +377,7 @@ A **Job** is a middleware route whose behavior is a structured `definition` (a s
 | `answer_build_question` | Answer a `needs_input` question on a build run (credentials choice, ambiguity, 2FA policy). When no open questions remain the build re-queues automatically. |
 | `cancel_build` | Stop a queued/running autonomous build run. The build flips to `failed` with a "stopped by user" summary; the job's draft definition is left as-is. Use it to take the loop over manually. |
 | `update_build_run` | Builder-facing: update a build run's lifecycle (`running` when you start, `green`/`failed` with a summary when done, `needs_input` with questions when blocked). |
-| `add_test_case` | Attach a test case to a job: named `input` + assertions (the green-gate). A test case is one sample API call; group it into a scenario with `scenarioId` (cases in a scenario share identical assertions; the legacy `scenario:<slug>` tag is dual-written). Assertions are `expr` (sandbox boolean) or `judge` (an LLM grades the execution against a natural-language `intent`). |
+| `add_test_case` | Attach a test case to a job: named `input` + assertions (the green-gate). A test case is one sample API call; group it into a scenario with `scenarioId` (cases in a scenario share identical assertions; the legacy `scenario:<slug>` tag is dual-written). Assertions are `expr` (sandbox boolean) or `judge` (an LLM grades the execution against a natural-language `intent`). On a blueprint-linked route, pass `acknowledgeJobAhead: true` for an intentional direct add; the response carries a `job_ahead` warning with fold-back options. |
 | `update_test_case` | Update an existing test case: tighten assertions as behavior firms up, move a case into a different scenario (`scenarioId`; `null` ungroups), or set `enabled: false` to disable a case without deleting its history. |
 | `list_scenarios` | List a job's scenarios, each with its member test cases embedded. Auto-created scenarios (from execution-path grouping) carry a `pathFingerprint` — rename them to describe the behavior. |
 | `create_scenario` | Create a scenario (name + optional slug/description; slug unique per route). Name it after the path/outcome, not the input. |
@@ -417,6 +423,7 @@ A job step supports `saveAs`, `when` (conditional skip), `forEach` (fan-out), `o
 
 - **Stopping:** there is no pause/resume. `stop_job_execution` is a cooperative cancel: a queued run cancels immediately; a running one stops at the runner's next checkpoint (between steps, between `forEach` items, or while waiting on a workflow). A workflow already running on a VM is not killed - it finishes on its own; the job just stops waiting and starts no new steps.
 - **Long or risky runs:** `run_job` with `waitForResult: false` returns the `jobExecutionId` immediately - poll it with `get_job_execution`, stop it with `stop_job_execution`.
+- **Progress webhooks:** destinations live on the router (`register_job_webhook` / `list_job_webhooks`). Pass `webhookId` on `run_job` to publish `workflow.started`, `workflow.step.started`, `workflow.step.completed` (failures included), `workflow.completed`, and optionally `job.completed` for that run. `workflowIds: null` means every workflow the router runs; `[]` means none; a list is an allow-list. `includeJob` (default true on create) adds `job.completed`. There is no `workflow.step.failed` - a failed flow is `workflow.step.completed` with `workflowStep.status: "FAILED"`. Call `get_job_webhook_events` (or `get_skill("job-webhooks")`) for the shared envelope and a full example of each payload.
 - **Step-range replays:** `run_job` with `fromStepId` / `toStepId` runs only a slice of the step graph (both inclusive, by step id). For any mid-graph start, pass `seedExecutionId` - it hydrates `ctx` from that prior execution so steps you aren't re-running still have their `ctx.*` values. The job's `output` block only runs when the range covers the last step.
 - **Finding runs:** `list_job_executions` returns paginated summaries with `status` and `trigger` filters - `trigger: "test"` isolates suite runs, `trigger: "api,mcp,cron"` isolates live traffic (the same split as the platform's Development/Production lenses).
 - **Autonomous builds:** watch with `get_build_status`, unblock with `answer_build_question`, take over with `cancel_build`. Don't edit the draft while a build is running - coordinate or cancel first.
@@ -630,7 +637,13 @@ See the **Blueprints (the spec front door)** section above for the loop and the
 | `register_job`        | Create a job - a middleware route backed by a structured `definition` (step graph)            |
 | `update_job`          | Update a job's `definition`, path, method, or description; `variant: "draft"` writes the draft |
 | `get_job`             | Get a job (route) incl. its `definition`; omit `routeId` to list all routes on the router     |
-| `run_job`             | Run a job once, poll to completion; `variant: "draft"` runs the draft. Step-range replays via `fromStepId`/`toStepId` + `seedExecutionId`; `waitForResult: false` returns the execution id immediately |
+| `run_job`             | Run a job once, poll to completion; `variant: "draft"` runs the draft. Step-range replays via `fromStepId`/`toStepId` + `seedExecutionId`; `webhookId` publishes progress events; `waitForResult: false` returns the execution id immediately |
+| `list_job_webhooks`   | List reusable webhook destinations on a router                                                                 |
+| `get_job_webhook_events` | Catalog of the five JSON payloads with examples                                                            |
+| `register_job_webhook`| Register a destination (`includeJob` + `workflowIds`); pass its `id` to `run_job`                             |
+| `get_job_webhook`     | Get one destination (secrets never returned)                                                                  |
+| `update_job_webhook`  | Update url, auth, `workflowIds`, and/or `includeJob`                                                          |
+| `delete_job_webhook`  | Delete a destination                                                                                          |
 | `stop_job_execution`  | Cooperative cancel of a queued/running execution (no pause; VM workflows finish on their own) |
 | `list_job_executions` | Paginated execution summaries with `status`/`trigger` filters (test vs live traffic)          |
 | `get_job_execution`   | Fetch one execution's full trace (status, input, output, `ctx`, per-step results)             |