feat: Post-#582 roadmap — direct actor tools, resource links, dynamic resources, get-actor-output(runId), elicitation, completion

[jirispilka]

Context

This is a tracking issue for follow-up work after #582 (async call-actor + waitSecs on get-actor-run). These features build on the infrastructure introduced in #582 and form a natural progression toward a cleaner, more MCP-native Actor execution experience.

Ideas sourced from #582 design sessions and team meeting notes.

Roadmap

Phase 2: Direct actor tools → non-blocking uniform response

Value: High | Effort: Low | Depends on: #582

Make direct actor tools (RAG web browser, etc.) also non-blocking with the uniform response shape. #582 builds all the infrastructure needed (buildCallActorStructuredContent, waitForRunWithAbort, mcpTaskExecution flag, actorRunOutputSchema). Direct actor tools just need to be wired to use it.

• Update src/tools/default/actor_executor.ts and src/tools/openai/actor_executor.ts
• In task mode: wait for completion. In non-task mode: start and return immediately.
• Remove old code: callActorGetDataset, buildActorResponseContent, callActorOutputSchema, buildEnrichedCallActorOutputSchema, ActorStore enrichment pipeline

Phase 3: Enhanced dataset tools — download URLs, schema, resource links

Value: High | Effort: Medium | Depends on: #582

Significant upgrade to get-dataset-items / get-actor-output:

• Resource links to download URLs in content array:

  content: [
      { type: 'resource_link', uri: 'https://api.apify.com/...format=csv', name: '[dataset_ID].csv', mimeType: 'text/csv' },
      { type: 'resource_link', uri: 'https://api.apify.com/...format=json', name: '[dataset_ID].json', mimeType: 'application/json' },
      // csv, json, xml, xlsx
  ]

• downloadUrls in structured content (xlsx, csv, json, xml links)
• schema in structured content (auto-generated from items)
• Default limit: 10 instead of 100 (avoid wasting LLM context)
• Flexible datasetUrlOrId input — accept dataset ID, URL, or username~dataset-name format

Phase 4: get-key-value-store-files — new tool

Value: Medium | Effort: Medium | Depends on: #582

New tool for browsing KV store records as resource links. Every Actor run produces a KV store (logs, screenshots, etc.) that's currently invisible.

• Input: keyValueStoreUrlOrId, prefix, limit
• Output: resource links to individual records with correct MIME types

  content: [
      { type: 'resource_link', name: 'screenshot.png', mimeType: 'image/png', uri: 'https://api.apify.com/...record/screenshot.png' },
  ]

• Include by default alongside get-dataset-items

Phase 5: Resource links in call-actor / get-actor-run results

Value: High | Effort: Medium | Depends on: Phase 3

call-actor and get-actor-run include resource links to the run's dataset/KV store in the content array (when run has completed):

content: [
    { type: 'text', text: 'Actor finished...' },
    { type: 'resource_link', uri: 'apify://dataset/xyz789', name: 'Actor run output', mimeType: 'application/json' }
]

Resource-aware clients can fetch data automatically — reduces tool calls. Requires implementing resources/read handler for apify://dataset/{id} URIs.

Phase 6: Dynamic resources + resource/list_changed

Value: Medium | Effort: Medium | Depends on: Phase 5

When an Actor run completes, register its dataset and KV store as dynamic server resources and send notifications/resources/list_changed. Clients with resource panels can browse Actor outputs natively.

• Resource templates: apify://run/{runId}/dataset, apify://run/{runId}/key-value-store
• sendResourceListChanged() on run completion
• Track active run resources per session with TTL cleanup
• Add basic schema info and creation context to resource descriptions

Phase 7: get-actor-output accepting runId

Value: Medium | Effort: Tiny | Depends on: #582

Add optional runId parameter to get-actor-output. When provided, resolve defaultDatasetId internally via client.run(runId).get(). Simpler for the LLM — runId is always prominent in responses.

Phase 8: Elicitation for expensive operations

Value: Medium | Effort: Medium | Depends on: Client support

Before running expensive Actors, confirm via MCP elicitation:

elicitation/create {
    mode: "form",
    message: "Run web-scraper with 50 URLs? Estimated cost: $0.15",
    requestedSchema: { properties: { confirm: { type: "boolean" } } }
}

Phase 9: Completion for Actor names & parameters

Value: Low | Effort: Low | Depends on: None

Autocomplete Actor names as user types (apify/web- → suggestions). Could also suggest valid enum values from Actor input schemas. Uses completion/complete handler.

Future: Auto-wait for certain clients

For clients known to handle longer tool calls well, the server could auto-wait a short period (e.g., 30s) in call-actor before returning, to see if the Actor finishes quickly — avoiding the get-actor-run round trip for fast Actors. Client-specific behavior, needs careful design.

Priority matrix

Phase	Feature	Value	Effort	Depends on
2	Direct actor tools migration	High	Low	#582
3	Enhanced dataset tools (download URLs, schema, links)	High	Medium	#582
4	get-key-value-store-files	Medium	Medium	#582
5	Resource links in call-actor/get-actor-run	High	Medium	Phase 3
6	Dynamic resources + list_changed	Medium	Medium	Phase 5
7	get-actor-output(runId)	Medium	Tiny	#582
8	Elicitation	Medium	Medium	Client support
9	Completion	Low	Low	None