feat: Give the runtime-specific API its own OpenAPI specification

[Pijukatel]

Closes #40.

The problem

The /actor-runtime/* endpoints — live dev folder, debug mode, browser view, migration emulation, upstream API fallback, the per-run events channel — have no counterpart on the Apify platform, so nothing described them except prose scattered through requirements/api.md. A client pointed at a runtime had no way to ask what that runtime supports.

The proposal

Turn the namespace into an OpenAPI 3.1 document, src/api/openapi/actor-runtime.json, and make that document be the namespace — it holds the contract, the runtime serves it, and the runtime answers from it.

1. The whole contract moves into the document, not just the schemas: each operation's description carries the behaviour that used to be requirements prose — the migration window and its counters, the full upstream-fallback contract (eligibility mapping, all-methods, marker headers, fail-closed, token forwarding), the dev-folder re-check at run start, the events channel's lifecycle. Runtime behaviour grafted onto otherwise faithful platform endpoints (?devFolder=false on run start, ?gracefully= on abort, reboot, the Actor object's locally shaped standbyUrl) is listed at the document root under x-actor-runtime-platform-notes, so a client enumerating the document still sees every local deviation.

requirements/api.md's Actor-runtime section is 22 lines, down from 174 — what the namespace is, where its specification lives, how it is served, and what an undescribed path answers. Nothing about those endpoints is restated there.

2. The runtime serves its own specification (both unauthenticated: the document is static, identical for every caller, carries no user data):

endpoint	what it returns
GET /actor-runtime	the document in the usual {data} envelope, so apify api GET /actor-runtime prints it
GET /actor-runtime/openapi.json	the same document bare, for OpenAPI tooling pointed at the URL

The real platform answers 404 page-not-found on /v2/actor-runtime (verified against api.apify.com), so the same call also answers "am I pointed at a local runtime, and which one?" — info.version is the runtime's own version.

3. Anything the document does not describe is answered from the document, instead of falling through to the app-level catch-all that only knows the emulated platform surface:

GET  /actor-runtime/nope          -> 404 not-found       ("GET /actor-runtime lists every endpoint it has")
GET  /actor-runtime/debug/<id>    -> 405 method-not-allowed, Allow: POST
GET  /actor-runtime/events/<id>   -> 426 upgrade-required (a websocket path reached without a handshake)

This is the namespace-local counterpart of what spec-table.ts already does for the emulated /v2 surface. The 426 route is registered from the document itself, before the namespace's auth(), because that operation declares no security — a 401 there would contradict the document the same caller can read.

What keeps it honest

test/integration/actor-runtime-spec.test.ts drives every documented operation against a running server: a route added without a document entry loses its 404/405 contract, and a document entry added without a route answers 501. Neither can drift silently. The unit test also checks every $ref resolves, that the platform notes are complete, and that info.version tracks package.json.

Notes for review

• Code comments and tests that cited the now-deleted api.md headings ("Upstream fallback", "Migration emulation", "Graceful abort") cite the corresponding operation in the document instead.
• One existing assertion changed: api-fallback.test.ts's case-varied PUT /v2/ACTOR-RUNTIME/api-fallback now gets 405 method-not-allowed rather than 404 not-found. The guarantee that test exists for — the namespace is never relayed upstream — is unchanged and still asserted (stub.hitCount() === 0).
• The document is a JSON file under src/ so tsc emits it into dist/ and the existing COPY --from=builder dist ships it; no build-step or Dockerfile change needed.
• Open question for you: GET /actor-runtime being unauthenticated is a deliberate call (discovery before a token). Say the word if you would rather it sat behind auth() like the rest of the namespace.

Merges from master

master moved under this branch thirteen times, so it carries thirteen merge commits. Six of them needed a matching change in the document — it is normative, so an upstream change to something it describes makes it wrong rather than merely stale.

Onto the Agent Skill work (#54) — three conflicts, and one addition they made necessary:

• CLAUDE.MD — Ship Agent Skill documentation in runtime image #54 moved every usage instruction into skills/actor-runtime/SKILL.md and left the file a pointer. The discovery note this branch had added there moves into SKILL.md's "Inspecting state directly" rather than being restated in a file that no longer documents endpoints.
• requirements/api.md — kept this branch's 22-line section. The per-endpoint prose Ship Agent Skill documentation in runtime image #54 edited is the prose this branch deletes in favour of the document.
• src/api/server.ts — kept both mounts. The public /skill router stays registered first, and has to stay a separate router: this branch's namespace router ends in a terminal handler that would otherwise answer /skill itself.
• GET /actor-runtime/skill is now in the document (with its ?format=json parameter, a SkillDocument schema, and the 500 skill-unavailable case), and the unit test's endpoint list names it. Without that, the document would have stopped being the whole namespace — which is this PR's entire claim.

Onto responsive abort (#64) — three conflicts, all downstream of that behaviour change:

• requirements/api.md — kept this branch's section again. fix: Make Abort responsive #64's edit lands entirely inside the ## Graceful abort heading this branch deletes.
• src/services/runs.ts — took fix: Make Abort responsive #64's new wording (the call returns the ABORTING record straight away; a hard abort cancels the window rather than escalating), with the citation pointed at the spec's abort note.
• test/integration/graceful-abort.test.ts — took fix: Make Abort responsive #64's rewritten tests wholesale, since the behaviour changed and their assertions are the correct ones; retargeted the four requirements/api.md citations the rewrite reintroduced.

The spec's abort note was updated to match #64. It still said the request "stays open until" the window elapsed and that a hard abort "escalates". No conflict flagged that — the document is normative for ?gracefully=, so leaving it would have made the specification wrong.

Onto resource addressing by name (#67) — one conflict, and one change it made necessary:

• skills/actor-runtime/SKILL.md — both sides added a bullet under "Inspecting state directly". Kept both, feat: Add storage addressing by username~name and userId~name #67's addressing rule first, since it follows straight on from the apify api examples above it.
• The document's actorId parameter was updated to match feat: Add storage addressing by username~name and userId~name #67. That change routes /actor-runtime/dev-folder/:actorId, /debug/:actorId and /browser-view/:actorId through the new resolveActorParam, so those paths now accept ~name, username~name and userId~name as well. No conflict flagged it — the three routes took the new resolver cleanly — but the document is normative for that parameter, so it now names every accepted form, the case-insensitive match, and the empty-name 400.

Also retargeted three api.md citations in dev-folder.ts and debug-mode.ts that this branch had left pointing at prose it had itself deleted (the dev-folder body shape, the debug-mode field rules, and the deliberate absence of a GET).

Onto the runs/last shortcuts (#68) — one conflict, splitting three ways:

• requirements/api.md — feat: Implement the runs/last shortcuts #68's spec-list entry and its new "Last-run shortcuts" section sit outside the section this branch deletes, and are kept exactly as feat: Implement the runs/last shortcuts #68 wrote them. Its third hunk adds a fallback rule inside the prose this branch deletes, so that rule moves into the document instead.
• The document's fallback contract was extended to match feat: Implement the runs/last shortcuts #68. setApiFallbackState's description now carries the one-source rule: where one request resolves several records in turn (runs/last resolves the Actor, then its newest run, then that run's log or storage), the first record decides where all of them come from. No conflict flagged it — api-fallback.ts grew pinRequestToLocal cleanly — but the document is normative for that contract, so leaving it out would have made the specification incomplete.
• No x-actor-runtime-platform-notes entry was added: runs/last is an ordinary platform endpoint implemented faithfully, with nothing grafted on locally.

Onto pay-per-event pricing (#69) and the docs guides (#39) — one conflict, and no document change:

• requirements/api.md — both sides added a bullet to the "exceptions to the {data} envelope" list: this branch's GET /actor-runtime/openapi.json and feat: Support pay-per-event pricing and estimate run cost #69's POST /v2/actor-runs/:runId/charge. Kept both, and corrected the count the two independent additions left wrong — four becomes five.
• The document needs nothing from feat: Support pay-per-event pricing and estimate run cost #69. Its events-channel.ts edit only adds internal counters and a read-only telemetry accessor, so the frames a websocket client receives are unchanged; and POST /v2/actor-runs/:runId/charge is a faithful platform endpoint on the emulated /v2 surface (spec-table.ts), with nothing grafted on locally, so it warrants no platform note either. Checked rather than assumed — the two merges before it each needed exactly such a change.

Onto input-schema validation (#72) — two conflicts, and one change it made necessary:

• requirements/api.md — feat: Validate Actor input and apply input-schema defaults #72's run-start validation bullet sits outside the section this branch deletes, so it is kept as feat: Validate Actor input and apply input-schema defaults #72 wrote it; the Actor-runtime section is this branch's, as before.
• The document's fallback contract was extended to match feat: Validate Actor input and apply input-schema defaults #72. It adds two error types, invalid-input and invalid-input-schema, and neither is ever relayed — so setApiFallbackState's list, which states it is exhaustive, now names them. No conflict flagged it: feat: Validate Actor input and apply input-schema defaults #72's own edit to that same list lands inside the prose this branch deletes.
• No platform note: input validation is faithful to the platform, message for message.

Onto the README/CONTRIBUTING split (#73) — one conflict, and no document change:

• README.md — docs: Focus README on local-only use cases, move developer docs to CONTRIBUTING.md #73 rewrote it around "what you can do only locally" and moved the developer material into CONTRIBUTING.md. Took docs: Focus README on local-only use cases, move developer docs to CONTRIBUTING.md #73's README wholesale and re-added this branch's specification note in the new shape: four lines right under that feature list, where the endpoints behind those features are introduced, instead of the 18-line section this branch had put between the Podman notes and the dev-loop walkthrough — both of which have since moved or gone.
• CONTRIBUTING.md — its new "Specification" section says the behavioural spec lives in requirements/*.md, which stops being the whole truth on this branch. It now names the OpenAPI document as the contract for the /actor-runtime/* namespace, with api.md pointing at it.
• The document needs nothing from docs: Focus README on local-only use cases, move developer docs to CONTRIBUTING.md #73: documentation only, no behaviour it is normative for.

Onto run memory from .actor/actor.json (#74) — no conflicts, and no document change:

• A clean merge: feat: Size runs by the memory fields of .actor/actor.json #74's edits to runs.ts and SKILL.md land away from this branch's.
• The document needs nothing from feat: Size runs by the memory fields of .actor/actor.json #74. Memory sizing is platform-faithful behaviour on the emulated /v2 surface, not runtime behaviour grafted onto an endpoint, so it warrants no platform note — the same call as for feat: Validate Actor input and apply input-schema defaults #72, feat: Support pay-per-event pricing and estimate run cost #69 and feat: Implement the runs/last shortcuts #68. Its local differences (the run-log notes, no plan cap, a bad memory field failing the build) are emulation-fidelity notes, which live in requirements/actor-driver.md, where feat: Size runs by the memory fields of .actor/actor.json #74 put them.

Onto Actor Standby (#76) — no conflicts, and the largest document change since the initial commit:

• feat: Emulate single-tenant Actor Standby #76 adds a new path inside this namespace: /actor-runtime/standby/<label>, the addressing for clients that cannot resolve *.localhost. Git merged it cleanly, but the document is normative for the namespace and said nothing about it, so the document had stopped being the whole namespace.
• proxyStandbyRequest is now in the document, with a standbyLabel parameter, both addressings (the path form and the platform-shaped http://<label>.localhost:3333/), the fact that every method, sub-path and websocket upgrade reaches the Actor — the single GET entry is the forwarding operation, not a request shape this API defines — the token sources, and the errors this router produces before the Actor is reached (standby-not-enabled, standby-bad-gateway, standby-run-failed, standby-run-finished, standby-run-not-ready, …).
• The fallback contract was extended again. setApiFallbackState's exhaustive never-relayed list now states that the standby addresses are answered by a router mounted ahead of the fallback, so no standby-* error can reach it — matching api.md's new "Actor Standby" section.
• A fourth platform note, for GET /v2/actors/{actorId}: an Actor's standbyUrl is a local address, and is picked from the request's own Host (container alias vs. host), which the platform's value never is. Standby itself — the pool, the per-run limits, the idle timeout, the configuration on the Actor — is faithful, so nothing else is noted.
• api.md's Actor-runtime section names both in its two pointer bullets; the unit test's endpoint list and platform-note list name them too.

Onto the dev-folder build-log line (#79) — no conflicts, and no document change: it adds a line to the end of a successful build's log, and changes nothing the document states about setActorDevFolder — registration, the re-check at every run start, the ownership scoping, the read-back response and the ?devFolder=false opt-out all still hold. The document describes no endpoint's log output.

Onto configurable ports (#80) and the release workflows (#81) — no conflicts, and one change #80 made necessary:

• The document needs nothing from ci: Generate the changelog and create GitHub releases #81: CI and release workflows only, plus the generated CHANGELOG.md.
• The document's servers entry was corrected for feat: Make the API and console ports configurable #80. It called the API port "fixed" and cited system.md for it — but feat: Make the API and console ports configurable #80 deleted that requirement ("Both ports are fixed and not configurable") and made the ports settable through ACTOR_RUNTIME_API_PORT and ACTOR_RUNTIME_CONSOLE_PORT. No conflict flagged it, and the document is normative for the namespace it mounts, so the claim would have stayed wrong. The entry now says the port is 3333 unless the env var moves it, and states once that every :3333 elsewhere in the document is that same default — which covers the two standby addresses (proxyStandbyRequest and the standbyUrl platform note), whose literal examples match the README's own.
• No new platform note and no endpoint change: the ports are the runtime's own configuration, not behaviour grafted onto an endpoint, so the endpoint list in the unit test is untouched.

Onto the samples reorganization (#82) — no conflicts, and no document change: it moves sample_actor_* to samples/actor_* and retargets the paths that named them (e2e tests, SKILL.md, README, .gitignore, the eslint config, two requirements files). The document describes API endpoints, not repository layout, and names no sample directory anywhere; neither do the spec tests or actor-runtime-spec.ts. Checked rather than assumed, as for every merge before it.

Onto human-readable names in the console (#83) — no conflicts, and no document change: it renders owners by username, Actors as username~actorname linked to their detail view, and a run's build by its build number. The document mentions the console in five places and none is about how an identifier is rendered — the console's own dev-folder and debug-mode forms (still console-local unauthenticated routes accepting exactly what the API endpoints accept), the browser-view viewer URL served on the console's port, the Migrate button on the run detail view, and the dev-folder response field being the same path the Actor detail page shows. That path is not an id, and #83 does not touch it.

Verified locally after the latest merge: pnpm run build, pnpm run lint, pnpm run format:check all clean, and pnpm test green — 1032 tests across 74 files, all passing.

🤖 Generated with Claude Code

https://claude.ai/code/session_016VvUV6661cyYbxoHZv2Pby