feat: Split get-actor-run into data + -widget tools

[jirispilka]

PR chain — part of #577

Step 6 of 6 in the #577 umbrella rollout.
Stacked on #724 (branch claude/call-actor-split-I2C7T); rebase to master once #720–#724 merge.

#	Issue	PR	Status
1	#714 — Rename openai → apps	#720	in review
2	#715 — Capability auto-detect + gating	#721	in review
3	#716 — fetch-actor-details split (pilot)	#722	in review
4	#717 — search-actors split	#723	in review
5	#718 — call-actor split	#724	in review
6	#719 — get-actor-run split	this PR	in review

Closes #719. Completes the umbrella.

---

Summary

Final application of the decoupled pattern validated in #722 / #723 / #724.

• get-actor-run is now mode-independent and data-only. No tool-level widget _meta in
  either mode; the runs category entry is a plain ToolEntry instead of a mode map.
• New get-actor-run-widget (apps-only) renders the live progress widget. Input is
  strict: { runId } only. Tool- and response-level widget _meta with
  ui.resourceUri = ui://widget/actor-run.html, visibility = ['model','app'], non-empty
  csp. Reuses the shared buildGetActorRunSuccessResponse({ widget: true }) helper.
• buildGetActorRunSuccessResponse widget branch now also sets openai/widgetDescription
  on response _meta, matching the other three widget tools.
• Server instructions: added the fourth disambiguation bullet pairing get-actor-run
  (silent data lookup) with get-actor-run-widget (live progress widget), using the same
  vocabulary as the three preceding splits. WORKFLOW_RULES untouched — the "NEVER poll
  get-actor-run after call-actor-widget" rule is orthogonal to this split and still
  valid under today's auto-polling call-actor-widget.
• Deleted src/tools/apps/get_actor_run.ts — widget rendering now lives in the sibling
  tool rather than a mode toggle on a shared handler.

No -internal equivalent existed for get-actor-run, so no deletion on that side.

Approach

Approach A, same as peers (#722 / #723 / #724). No design question — the decoupled
pattern has been validated three times and this is the final mechanical application.

Key changes

File	Change
src/tools/apps/get_actor_run_widget.ts	created
src/tools/apps/get_actor_run.ts	deleted
src/const.ts	add ACTOR_RUNS_GET_WIDGET = 'get-actor-run-widget'
src/tools/categories.ts	runs entry → plain defaultGetActorRun; ui[] gets { apps: getActorRunWidgetTool }
src/tools/core/get_actor_run_common.ts	drop widget _meta from getActorRunMetadata; trim stale "NEVER call in UI mode" block from the base description; add openai/widgetDescription to widget response _meta
src/utils/server-instructions/apps.ts	fourth disambiguation bullet
tests/unit/tools.get_actor_run.widget.response.test.ts	created — mirrors call_actor_widget.response.test.ts
tests/unit/tools.mode_contract.test.ts	get-actor-run-widget added to ui category expectations; get-actor-run added to the no-widget-meta list (runs category)
tests/unit/tools.categories.test.ts	flip not.toBe → toBe for get-actor-run (now mode-independent, same object)

Tests

• npm run type-check — passes
• npm run lint — passes
• npm run test:unit — 615 passed
• npm run build — passes

mcpc-style JSON-RPC probe matrix (stdio, raw tools/list)

A: default mode (node dist/stdio.js --tools=runs,actors,ui)

HAS_BASE=True, HAS_WIDGET=False
BASE_META=null (no ui.* keys)
BASE_INPUT_SCHEMA_KEYS=['runId']

B: apps mode (--ui=true)

HAS_BASE=True, HAS_WIDGET=True
BASE_META=null
WIDGET._meta.ui.resourceUri = ui://widget/actor-run.html
WIDGET._meta.ui.visibility  = ['model','app']
WIDGET._meta.ui.csp         = { connectDomains, resourceDomains } (non-empty)

Byte-identical base schemas across modes:

INPUT_SCHEMA_EQUAL:  True
OUTPUT_SCHEMA_EQUAL: True
DESCRIPTION_EQUAL:   True

Test plan

• npm run type-check
• npm run lint
• npm run test:unit
• npm run build
• mcpc probe matrix — default vs apps, base schema byte-compare
• Integration tests (npm run test:integration) — human-run per CLAUDE.md
• MCPJam widget parity — manual
• Live tools/call with a real APIFY_TOKEN and runId — manual

apify-mcp-server-internal impact

Purely additive surface on the widget side. Base get-actor-run keeps the same name and
byte-identical input/output schemas across modes, so the hosted server should continue
working with no edits. The only potentially-breaking rename is the shared
buildGetActorRunSuccessResponse now emits openai/widgetDescription on the response —
harmless for consumers that ignore extra _meta keys. Please confirm on the internal
side.

https://claude.ai/code/session_01SF9P6g91UrVMahn4bLsUNf