improvement(api): replace workflow jobs with execution resources

[TheodoreSpeaks]

Summary

• replace public async workflow job receipts with execution IDs and canonical execution status resources
• project queued initial and resumed runs through the execution endpoint until durable logs exist
• remove the generic job route and update SDKs, OpenAPI, deployment examples, and localized references

Type of Change

• Improvement
• Breaking API cleanup

Testing

• 100 focused API tests
• 29 TypeScript SDK tests and SDK typecheck
• 28 Python SDK tests
• OpenAPI validation, strict API validation, lint, and all repository audits
• Full app typecheck still reports the existing Azure OpenAI and Gemini SDK type drift in untouched provider files

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
docs	Skipped		Aug 5, 2026 10:34pm

[cursor]

PR Summary

High Risk
Breaking changes to the public execute/async contract and polling model affect all API and SDK integrations, though legacy endpoints are retained. Core execution, resume, and queue projection logic in shared paths increases regression risk.

Overview
Public workflow execution moves to v2: execute URLs become /api/v2/workflows/{id}/execute, bodies use input (not inputs) and async: true instead of X-Execution-Mode: async, and successful responses are wrapped in data. Async dispatch returns an execution ID and a v2 status URL rather than a separate job ID and /api/jobs/... polling.

Polling is unified on the execution resource: getWorkflowExecutionStatus now projects queued/running state from the async job queue (and resume queue) until durable logs exist, so v2 status routes no longer duplicate queue lookups. Trigger.dev enqueue tags runs with jobId: for deterministic lookup.

HITL resume adds POST /api/v2/workflows/{id}/executions/{executionId}/resume (body includes contextId), implemented via shared handleResumeExecution with surface-specific async receipts—legacy resume still exposes jobId and /api/jobs/.... Docs, OpenAPI, deploy-modal examples, copilot deploy helpers, and Python/TypeScript SDKs are aligned to v2 execute + getWorkflowExecution polling; legacy job status APIs remain documented as deprecated paths.

^{Reviewed by Cursor Bugbot for commit 94e28e7. Bugbot is set up for automated code reviews on this repo. Configure here.}

[greptile-apps]

Greptile Summary

The PR replaces public asynchronous workflow-job receipts with canonical execution resources while preserving legacy polling compatibility.

• Adds execution-resource polling and a v2 human-in-the-loop resume endpoint.
• Projects queued initial and resumed runs until durable execution logs become available.
• Updates SDKs, contracts, OpenAPI specifications, deployment UI, examples, and documentation.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains; the previous resume-status issue is fixed by resolving active resume queue entries before the existing paused log, and the documentation convention thread was correctly resolved as inapplicable to external-consumer examples.

Important Files Changed

Filename	Overview
apps/sim/lib/workflows/executor/execution-status.ts	Projects claimed and pending resume attempts ahead of stale paused logs, with terminal durable logs retaining precedence.
apps/sim/app/api/resume/resume-handler.ts	Dispatches v2 async resumes with deterministic queue identities and returns canonical execution polling URLs while preserving legacy job receipts.
apps/sim/app/api/v2/workflows/[id]/executions/[executionId]/resume/route.ts	Adds the contract-bound v2 endpoint for resuming a paused workflow execution.
packages/ts-sdk/src/index.ts	Migrates SDK execution and polling behavior from generic jobs to canonical workflow execution resources.
packages/python-sdk/simstudio/init.py	Updates Python SDK async receipts and execution-status polling to use execution IDs.
apps/docs/openapi-v2-workflows.json	Documents the v2 resume endpoint and its synchronous, asynchronous, validation, and error responses.

Sequence Diagram

sequenceDiagram
  participant Client
  participant API as Workflow API
  participant Queue as Execution Queue
  participant Worker
  participant Logs as Durable Execution Logs
  Client->>API: POST execute/resume (async)
  API->>Queue: Enqueue using execution identity
  API-->>Client: 202 executionId + statusUrl
  Client->>API: GET execution resource
  API->>Queue: Resolve active queued attempt
  Queue-->>API: queued/running state
  API-->>Client: Execution resource
  Worker->>Logs: Persist execution state/output
  Client->>API: GET execution resource
  API->>Logs: Read durable state
  API-->>Client: completed/failed/paused resource

Loading

_{Reviews (6): Last reviewed commit: "fix(api): prefer terminal logs over stal..." | Re-trigger Greptile}

[TheodoreSpeaks]

@cursor review

[TheodoreSpeaks]

@greptile

[TheodoreSpeaks]

@greptile

[TheodoreSpeaks]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 5698672. Configure here.}

[TheodoreSpeaks]

@greptile

[TheodoreSpeaks]

@cursor review

[TheodoreSpeaks]

@greptile

[TheodoreSpeaks]

@cursor review

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit c903ba1. Configure here.}

[TheodoreSpeaks]

@greptile