[knihit]

Description

Part 1 of 3 of the Execution tab (#116 is part 2, #93 part 3). This part adds the code that reads and models a run. It has no UI: nothing here changes what the page shows.

API client (src/api/):

• WorkflowApi gains startRun and getRun. createHttpApi sends the goal as { "params": { "goal": ... } }, reads run_id, and reads a run into an ordered list of stages. A reply that breaks the contract is a bad reply: a run id outside the RunId pattern, a status it does not name, an exit_code that is not an integer or null, a stage name twice in order, a stage in stages that order lacks, or a status that does not fit the exit code and the stage states (running with an exit code, passed with a stage not passed, halted without exactly one stage blocked). The fix of an error body is added to its sentence. A start with no answer, or a 2xx start whose reply cannot be read, is told to the core as RunStartUnsure: the run may have started. The run id is encoded in the path. ApiError carries the run_id of an error body when it has the shape of a run id; the contract uses it in the 409 already_running. Each run call takes an AbortSignal, and every call gives up after 15 seconds; a body that stops arriving counts as no answer (status 0).
• loadWorkflow ties the run calls to the session token, so only those calls hold it. It turns a 409 already_running with a run id into RunAlreadyActive, and a 4xx or unreadable reply on a read into RunReadRefused.

Run core (src/execution/core/, no IO):

• The state of the tab and its reducer, startAndFollow (starts a run, or follows the one that is already active, then reads it every 1000 ms until it is no longer running; a read that fails with no answer, a 5xx, 408 or 429 is tried again, up to 3 in a row, while a refused read or a reading of another run ends the run with an error), the state of each node, the status sentences, and the goal check (1 to 2048 characters).
• A failed event names the run it belongs to, and the reducer ignores one that names another run or none once a run is being followed, so a second loop that was refused cannot end the state of the first.
• Its ports are RunPort (start and read a run, each with a signal) and Scheduler (wait for some milliseconds). Tests use a fake scheduler that they move by hand, so no test sleeps.
• test-support/execution-purity.test.ts holds the core to the same rule as the graph core: it imports only its own modules, the graph core and the wire types, and reads no clock, randomness, environment or network.

Docs: the README names the four calls of the port, the retry and timeout rules and the purity test of the run core.

Graph (src/graph/): withStatuses adds a status to the nodes it names. buildGraph is unchanged.

Type of Change

• Other: the run core and API client of the workflow canvas, in workflow-canvas/

Testing

• Root npm test (tests/scripts/**/*.test.js): not run; this PR changes only workflow-canvas/.
• If cli/ changed: not applicable
• Smoke tested affected agent(s): not applicable, no agent changed
• If an agent's or skill's behavior changed: not applicable
• New or changed code files carry the required SPDX header (see AGENTS.md's License headers rule)

Checked in workflow-canvas/ at b4e0f06: npm run lint, npm run typecheck and npm test (52 files, 886 tests) pass. The e2e suite is run on the top of the stack, as no page changes here.

Tests added: getRun and startRun (request shape, token, encoded id, parsing, bad replies including a wrong exit_code and a repeated stage name, error sentences, the run_id of a 409); the reducer (every state, an event that does not fit is ignored, a reading or a failure of another run is ignored); startAndFollow with the fake scheduler (polls every 1000 ms, no wait before the first read, stops on passed and on halted, retries and gives up, a refused read, joining an active run, two overlapping loops, a read that never answers and is aborted, nothing emitted after an abort); the HTTP adapter with a signal, a timeout, a dropped body and a hung body; node states for a running, passed and halted run; status sentences; the goal check; withStatuses; the no-IO rule of the core.

Checklist

• My code follows the style guidelines of this project (see AGENTS.md's Code Style & Conventions)
• I have performed a self-review of my own changes
• I have commented my code where necessary
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added or updated tests that prove my change works (see Testing above for the exact commands)

Notes for Reviewers

• Stacked on Give the workflow canvas the docs theme, with light and dark modes #85 (wc/05b-theme); this PR is six commits (the first is the original change; the others answer reviews). Part 2 is Draw the run on the Execution tab with a Run button and live node states #116 (wc/06b-run-panel), and Run the workflow from the Execution tab with live node states #93 (wc/06-execution) is part 3.
• What to review: the wire parsing in src/api/parse.ts (strictness about unknown statuses), the reducer and startAndFollow transitions, and that the core imports nothing from React or the UI.
• The 1000 ms poll interval is a plain constant; the contract does not set it.

Fixes from the second adversarial review

• Rebased onto the new wc/05b-theme; the test fakes of the source tests now include the run calls.
• Rejected: a status sentence for the error state (the specific message is shown by Draw the run on the Execution tab with a Run button and live node states #116's alert), and a guard for a throwing emit (the port says it must not throw).

Fixes from the third adversarial review

• A start that got no clear answer ends as an error that says the run may have started (RunStartUnsure, maybeStarted), instead of "did not start".
• 408 and 429 are tried again like a 5xx; a run_id in an error body must look like a run id.
• FollowRequest says the caller runs one loop at a time, and startAndFollow says it rejects only when emit throws. The README says "each run call" takes a signal.
• Rebased onto the new wc/05b-theme.
• Rejected: the nits N2 to N7 of the first re-review (test helper loops, a positional constructor, repeated unions, a nested ternary in a fixture, the queued name for a node that did not run, trimming the goal): no behaviour.

Restack

• Rebased onto the new head of Give the workflow canvas the docs theme, with light and dark modes #85. No change of its own.

Round 6

Rebased on #85. A 401 on a run start or a run read now clears the kept session through the guard added in #83 and fails with the "server no longer knows this session" message (before, only the load did). New tests: start and read forget the session, a failure that is not a 401 keeps it, a newer session is not forgotten. The earlier test that expected the raw 401 sentence on a read is replaced.

Round 7: no change to the product code. One test of the refused-address notice builds its API with the helper that has every method.

Round 8: rebased on #85. The tests added in #83 for a pasted session build their API with the helper that has every method. npm test (55 files, 969 tests), lint and typecheck pass.

Round 9: rebased on #85. One test of the pending session builds its API with the helper that has every method. npm test (55 files, 980 tests), lint and typecheck pass.