Skip to content

refactor: Extract shared run helpers and run output schema #762

@jirispilka

Description

@jirispilka

Base branch: claude/implement-get-actor-run-MUTXI (or master once merged).

Sub-issue of #582. No behavior change.

Context

#582 wants call-actor to return immediately and get-actor-run to gain waitSecs. Both feature handlers will share helpers that today live inline in actor_execution.ts:callActorGetDataset (the abort-race) and aren't yet factored out for use by the always-async path. Land the extraction first so the feature PR is a small, readable diff.

Scope

Pure mechanical extraction. No public schema change.

  • src/tools/core/call_actor_common.ts:
    • Extract waitForRunWithAbort({ runId, apifyClient, abortSignal }) from the inline Promise.race against CLIENT_ABORT in src/tools/core/actor_execution.ts:callActorGetDataset (~lines 80-130). On abort, call apifyClient.run(runId).abort({ gracefully: false }) and return null. Caller decides what to return on null.
    • Add buildActorRunStructuredContent({ run, actorName }) returning { runId, actorName?, status, startedAt, finishedAt?, stats?, storages, hint } — uniform shape consumed by both call-actor and get-actor-run. No inline preview, no input echo.
    • Add getRunStatusHint(status) — maps statuses to the strings finalized in #C.
  • src/const.ts: add ACTOR_RUN_STATUS const object mirroring ACTOR_JOB_STATUSES from @apify/consts. Used by getRunStatusHint.
  • src/tools/structured_output_schemas.ts: add actorRunOutputSchema (uniform shape; actorName, finishedAt, stats optional). Existing callActorOutputSchema, buildEnrichedCallActorOutputSchema, and getActorRunOutputSchema stay untouched — repointed in #C.
  • src/types.ts: add mcpTaskExecution?: boolean to InternalToolArgs. Unused in this PR.
  • src/tools/core/actor_execution.ts:callActorGetDataset: replace the inline abort race with a call to the new waitForRunWithAbort. Behavior identical.

Plan

  • Extract waitForRunWithAbort; swap callActorGetDataset to use it
  • Add buildActorRunStructuredContent + getRunStatusHint
  • Add ACTOR_RUN_STATUS and actorRunOutputSchema
  • Add mcpTaskExecution? to InternalToolArgs
  • Unit tests for the new helpers

Files touched

  • src/const.ts
  • src/types.ts
  • src/tools/core/call_actor_common.ts
  • src/tools/core/actor_execution.ts
  • src/tools/structured_output_schemas.ts
  • tests/unit/...

Acceptance

  • npm run type-check, npm run lint, npm run test:unit clean
  • No public tool input or output schema change
  • Existing integration suite passes unchanged
  • mcpc smoke after npm run build: tools-call get-actor-run runId:=<existing> returns the same shape pre/post; tools-call call-actor actor:="apify/python-example" input:='{"first_number":1,"second_number":2}' still completes end-to-end
  • apify-mcp-server-internal unaffected (no exported surface change)

Independence

Blocks #C (feat). Independent of #B (cancel fix).

Estimate

~2 h.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request.t-aiIssues owned by the AI team.

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions