@minicor/mcp-server 4.8.0 → 4.10.0

package/README.md

@@ -296,21 +296,77 @@ After a successful build:
 - Skills are stored per-workspace and available to future builds
 - Customer-specific quirks become reusable knowledge
 
+## 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.
+
+### The blueprint tools
+
+| Tool | What it does |
+| --- | --- |
+| `resolve_blueprint_state` | The first call to make when working a blueprint (the sibling of `resolve_job_state`, one layer up). One call fetches the blueprint (state + drift + proposal + open questions), the library's enrichment status, and the linked build run, then returns an unfolded state (`no_context` / `enriching` / `no_spec` / `proposal_pending` / `needs_answers` / `building` / `needs_input` / `build_failed` / `job_ahead` / `spec_stale` / `job_stale` / `in_sync` - every state maps to one verb), `blockers[]` (enrichment failures, a stalled builder, questions needing a human), and ordered `nextActions` with the concrete tool calls prefilled. |
+| `blueprint_list` | List a workspace's blueprints: id, name, computed state, drift flags, and the linked job coordinates. For any blueprint not `in_sync`, call `resolve_blueprint_state` on it and follow `nextActions`. |
+| `blueprint_create` | Create a blueprint. Two entry paths: create empty and feed the library (new automation), or pass `routeId` + `middlewareId` to link an existing job (backfill) - `blueprint_import_cases` then adopts its test cases into the spec. |
+| `blueprint_get` | Get a blueprint: the full spec document, computed state, both drift summaries, and the inbox (`document.openQuestions` + `pendingProposal`). `headVersion` here is the `baseVersion` for `blueprint_update`'s CAS. |
+| `blueprint_update` | Edit the spec directly: `document` replaces wholesale, `patch` is a section-level merge. Document edits require `baseVersion` (compare-and-swap: a 409 means the blueprint moved past your read - re-read and re-author, never retry blindly). Prefer the synthesize -> apply path for library-derived changes; direct edits are for surgical fixes. |
+| `blueprint_add_entry` | Add (or, with `entryId`, update) a library entry. Context kinds (doc/video/url/note/transcript/data-source/walkthrough) feed synthesis; resource kinds (screen-map/anchor/screenshot) are runtime-referenceable as `entry://<id>#<fragment>`. Enrichable kinds start `pending` and are enriched to text by a worker. Every write bumps `librarySeq`, so the spec goes `spec_stale` until the next synthesize. |
+| `blueprint_list_entries` | List a blueprint's library entries with enrichment status (`pending`/`processing` means the worker is still on it; `failed` carries the reason), or one entry via `entryId` (`revisions: true` adds its immutable history, `downloadUrl: true` adds a signed read URL for the uploaded blob). |
+| `blueprint_entry_upload_url` | Get a short-lived signed upload URL for a file that will become a library entry: returns `{ uploadUrl, blobRef, expiresOn }`; PUT the bytes (plain PUT with the file's Content-Type - works from inside a VM via `vm_execute_script`), then `blueprint_add_entry` with the returned `gs://` `blobRef`. |
+| `blueprint_synthesize` | Synthesize a spec proposal from the library (LLM). Produces ONE pending proposal for review - never applied silently. Answer all open questions first so one synthesis folds every answer in. Blocked responses are structured: `proposal_pending`, `entries_enriching`, `llm_unconfigured`, `library_empty`, plus retryable LLM-leg failures. |
+| `blueprint_get_proposal` | Read the pending proposal for review: the section-level patch, regenerated SOP, summary, and per-claim citations (provenance `extracted`/`inferred`/`ambiguous` - scrutinize the latter two). Returns the exact apply coordinates (`baseVersion` + `basedOnSeq`). |
+| `blueprint_apply_proposal` | Apply the reviewed proposal as one validated, version-snapshotted document update. Requires the reviewed proposal's `baseVersion` + `proposalBasedOnSeq`: the service atomically refuses (409 `proposal_mismatch`) if a concurrent resynthesize swapped the proposal after your review. After a successful apply the job is stale - `blueprint_build` is the next verb. |
+| `blueprint_reject_proposal` | Discard the pending proposal (bad synthesis, or the spec moved underneath it). A 404 is success-shaped: someone else already applied or rejected it. Follow with `blueprint_synthesize`, optionally with steering `instructions`. |
+| `blueprint_answer_question` | Answer ONE open synthesis question atomically: removed from `openQuestions`, stored as a note entry, version snapshotted. Answer ALL open questions, then synthesize ONCE - each answer bumps `librarySeq`, so never loop answer -> synthesize per question. Builder questions (`needs_input`) go to `answer_build_question` instead. |
+| `blueprint_build` | Sync the spec into its Job (the primary build verb): validates the spec, ensures the router + route exist, upserts judge test cases from `exampleCases` (content-hash idempotent), attaches spec + library as the builder artifact, and queues a build run. Returns the handoff coordinates `{ middlewareId, routeId, buildId, testCaseIds }` the jobs toolset takes over with. |
+| `blueprint_build_status` | Blueprint-side view of the linked build run (status `queued`/`running`/`green`/`failed`/`needs_input`, summary, open questions). `needs_input` questions come back with `answer_build_question` coordinates prefilled - try to answer them from the library first. |
+| `blueprint_import_cases` | Adopt the linked job's test cases into the spec's `exampleCases` (upsert by name) - the `job_ahead` fold-back arrow. The alternative exit is `blueprint_build` alone, which rebuilds from the spec and overwrites the direct edits. |
+| `blueprint_list_versions` | List the spec's version snapshots (newest first) - every document change snapshots one, with its note. Pass `version` to fetch one full snapshot (diff a proposal, or recover a document after a CAS 409). |
+
+### The blueprint loop - context entries -> synthesize -> review -> apply -> build
+
+The blueprint loop sits in front of the job build loop below. When in doubt about a blueprint, call `resolve_blueprint_state` - it returns the concrete next tool calls, exactly like `resolve_job_state` does for jobs.
+
+```
+1. FEED THE LIBRARY - blueprint_add_entry (SOPs, Looms, notes, transcripts, VM
+                      walkthroughs). Files: blueprint_entry_upload_url -> PUT the
+                      bytes -> blueprint_add_entry with the gs:// blobRef.
+                      Enrichable entries start pending - poll blueprint_list_entries.
+2. SYNTHESIZE       - blueprint_synthesize drafts ONE pending spec proposal (LLM).
+                      Never applied silently.
+3. REVIEW + ANSWER  - blueprint_get_proposal (patch + SOP + per-claim citations).
+                      Answer open questions with blueprint_answer_question - ALL
+                      of them, then ONE resynthesize.
+4. APPLY            - blueprint_apply_proposal with the reviewed proposal's
+                      baseVersion + proposalBasedOnSeq (409 proposal_mismatch if a
+                      concurrent resynthesize swapped it).
+5. BUILD            - blueprint_build syncs the spec into the Job: router + route +
+                      judge test cases + build run. Returns {middlewareId, routeId,
+                      buildId} - the jobs loop (resolve_job_state) takes over.
+```
+
+Two drift directions keep the spec and the job honest: `spec_stale` (the library moved past the spec - synthesize) and `job_stale` (the spec moved past the job - build). `job_ahead` means the job was edited directly behind the spec's back; exit with `blueprint_import_cases` (fold the edits back) or `blueprint_build` (overwrite them). To teach a blueprint from a live VM session, load `get_skill("blueprint-vm-walkthrough")`.
+
 ## Jobs (RPA orchestration)
 
-A **Job** is a middleware route whose behavior is a structured `definition` (a step graph) instead of freeform handler code. Jobs sit **above** workflows: a job step either calls an entire Minicor workflow (`kind: "workflow"`, by `workflowId`) or runs a code block (`kind: "code"`). The job never touches a workflow's internal steps - a workflow is an opaque callable with an input and an output. A job is the **macro zoom** (what ran, status, replays); a workflow → step is the **microscope**. This is the layer that turns one or more workflows into a versioned, testable, observable API endpoint.
+A **Job** is a middleware route whose behavior is a structured `definition` (a step graph) instead of freeform handler code. Jobs sit **above** workflows: a job step either calls an entire Minicor workflow (`kind: "workflow"`, by `workflowId`) or runs a code block (`kind: "code"`). The job never touches a workflow's internal steps - a workflow is an opaque callable with an input and an output. A job is the **macro zoom** (what ran, status, replays); a workflow → step is the **microscope**. This is the layer that turns one or more workflows into a versioned, testable, observable API endpoint. When a route is owned by a Blueprint (see above), drive changes through the spec, not the direct job tools.
 
 ### The job tools
 
 | 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. |
+| `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`. |
 | `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. |
 | `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. |
@@ -367,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.
@@ -434,6 +491,7 @@ Skills are reusable RPA patterns that accumulate as you build automations. The M
 | Skill                        | Purpose                                                                           |
 | ---------------------------- | --------------------------------------------------------------------------------- |
 | `job-build-loop`             | **Mandatory for job work.** The test-case-first build/debug loop: green-gate first, macroscope (job) → microscope (workflow steps), seeded range replays, stop semantics, publish gates |
+| `blueprint-vm-walkthrough`   | Guided VM walkthrough that teaches a blueprint: the user narrates a process on a live VM while you capture screens, ground UI anchors, and persist walkthrough + screenshot + screen-map entries |
 | `rpa-testing-workflow`       | **Mandatory.** Exact tool call sequences for testing through the Minicor executor |
 | `cdp-browser-automation`     | CDP starter template, React-safe setters, parallel execution                      |
 | `desktop-uiautomation`       | Framework selection, element selectors, wait/retry patterns                       |
@@ -542,18 +600,50 @@ On multi-session (broker) VMs every execute/screenshot call must name a `targetU
 | `preview_flow_changes` / `compare_flow_versions`           | Diff code before deploying                          |
 
 
+### Blueprints
+
+
+| Tool                          | What it does                                                                                   |
+| ----------------------------- | ---------------------------------------------------------------------------------------------- |
+| `resolve_blueprint_state`     | "Where am I in the blueprint loop?" - unfolded state + `blockers` + `nextActions`               |
+| `blueprint_list`              | List a workspace's blueprints with computed state, drift flags, and linked job coordinates      |
+| `blueprint_create`            | Create a blueprint (empty, or linked to an existing job via `routeId` + `middlewareId`)         |
+| `blueprint_get`               | Get the spec document, computed state, drift, and inbox (`openQuestions` + `pendingProposal`)   |
+| `blueprint_update`            | Direct spec edit (`document` or section-level `patch`); document edits require `baseVersion` CAS |
+| `blueprint_add_entry`         | Add or patch a library entry (context kinds feed synthesis; resource kinds are `entry://` refs) |
+| `blueprint_list_entries`      | List entries with enrichment status; `entryId` + `revisions`/`downloadUrl` for one entry        |
+| `blueprint_entry_upload_url`  | Signed upload handshake: `{ uploadUrl, blobRef }` -> PUT the bytes -> `blueprint_add_entry` with the `gs://` ref |
+| `blueprint_synthesize`        | LLM-draft a spec proposal from the library (one pending proposal; structured blocked reasons)   |
+| `blueprint_get_proposal`      | Read the pending proposal + per-claim citations; returns the exact apply coordinates            |
+| `blueprint_apply_proposal`    | Apply the reviewed proposal (`baseVersion` + `proposalBasedOnSeq`; 409 `proposal_mismatch` if swapped) |
+| `blueprint_reject_proposal`   | Discard the pending proposal; a 404 means someone already resolved it (success-shaped)          |
+| `blueprint_answer_question`   | Atomically answer one open question (stored as a note entry; then synthesize ONCE)              |
+| `blueprint_build`             | Sync spec -> Job; returns `{ middlewareId, routeId, buildId }` for the jobs toolset             |
+| `blueprint_build_status`      | Blueprint-side view of the linked build run (status, summary, open questions)                   |
+| `blueprint_import_cases`      | Fold the linked job's test cases back into the spec's `exampleCases` (the `job_ahead` exit)     |
+| `blueprint_list_versions`     | List spec version snapshots; pass `version` for one full snapshot                               |
+
+
+See the **Blueprints (the spec front door)** section above for the loop and the ownership rule.
+
 ### Jobs & Test Cases
 
 
 | Tool                  | What it does                                                                                  |
 | --------------------- | -------------------------------------------------------------------------------------------- |
-| `resolve_job_state`   | "Where am I in the build loop?" - job state + `nextActions` (the concrete next tool calls)    |
+| `resolve_job_state`   | "Where am I in the build loop?" - job state + `nextActions`; flags blueprint-owned routes     |
 | `list_middlewares`    | List the routers (middlewares) in a workspace - jobs attach to one of these                   |
 | `register_middleware` | Create a router (middleware) jobs attach to; `autoConfigure` populates its workspace API key  |
 | `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)             |
@@ -766,6 +856,8 @@ src/
     sync-tools.ts       - clone_workspace, init_project, pull/push, set_workspaces_root
     vm.ts, vm-rpa.ts    - VM and RPA tools
     core.ts             - Workflows, flows, executions
+    jobs.ts             - Jobs, test cases, scenarios, build runs
+    blueprints.ts       - Blueprints: spec + library + synthesize/apply + build sync
     ...
   prompts/
     workspace-session.ts - Workspace session guide prompt

package/dist/__live__/blueprints.live.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=blueprints.live.test.d.ts.map

package/dist/__live__/blueprints.live.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blueprints.live.test.d.ts","sourceRoot":"","sources":["../../src/__live__/blueprints.live.test.ts"],"names":[],"mappings":""}