Draft
Conversation
Define 9 new commands under `temporal activity` for standalone (top-level) Activity Executions: start, execute, describe, list, count, cancel, terminate, delete, result. Each mirrors the corresponding `temporal workflow` command pattern. Modify `complete` and `fail` to make --workflow-id optional so they work for both workflow-scoped and standalone Activities. Add two new reusable option sets: `activity-execution-reference` (activity-id + run-id) and `activity-start` (full set of start options including timeouts, retry policy, ID policies, search attributes, headers, metadata, and priority). All new commands are marked Experimental. Existing workflow-only commands (pause, unpause, reset, update-options) are unchanged. Co-authored-by: Cursor <cursoragent@cursor.com>
- cancel: Rewrite description following Python SDK style, explaining that cancellation is a request delivered via heartbeat response - complete/fail: Use activity-reference option set instead of inlining activity-id/run-id, fixing missing short flag and missing "latest run" description - fail: Clarify detail vs reason option descriptions (detail is the failure details payload; reason is the failure message) - count/list: Add example queries, improve query option descriptions, add visibility docs links - delete: Add note about async deletion and running activity termination (from proto docs) - execute: Use "output" instead of "printed" - update-options/pause/unpause/reset: Add "Not supported for standalone Activities" sentence - Remove resolved TODO comments Co-authored-by: Cursor <cursoragent@cursor.com>
Phase 2: Run code generation producing command structs for all 9 new commands and 2 new option sets (ActivityReferenceOptions, ActivityStartOptions). Phase 3: Implement run() methods for all new commands: - start: calls StartActivityExecution, outputs activity ID and run ID - execute: calls StartActivityExecution + PollActivityExecution, outputs the activity result - describe: calls DescribeActivityExecution with include_input and include_outcome - list: calls ListActivityExecutions with pagination, table output - count: calls CountActivityExecutions with group support - cancel: calls RequestCancelActivityExecution - terminate: calls TerminateActivityExecution with default reason - delete: calls DeleteActivityExecution - result: calls PollActivityExecution, outputs the activity result Shared helper buildStartActivityRequest() constructs the gRPC request from ActivityStartOptions, handling retry policy, ID policies, search attributes, headers, user metadata, and priority. Shared helper printActivityOutcome() formats activity results for both text and JSON output modes. Also adds description-header to temporal activity docs (required by code generator) and fixes import aliasing (common/v1 -> commonpb). Co-authored-by: Cursor <cursoragent@cursor.com>
Verify all 11 activity subcommands appear in help output (cancel, complete, count, delete, describe, execute, fail, list, result, start, terminate). Verify start command exposes expected flags (activity-id, type, task-queue, timeouts, input). Verify complete and fail commands expose both activity-reference options (activity-id, run-id) and the optional workflow-id flag. Integration tests for the new RPCs are deferred until a standalone-activity-enabled test server is available. Co-authored-by: Cursor <cursoragent@cursor.com>
- Use 'activity complete' as the primary example instead of experimental 'activity start' command - Restore original description-header text for docs - Revert unnecessary commonpb import alias (use default 'common' since no conflict exists in this file) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Activity count/list/result: use Standalone Activity Execution wording and 'only supported for Standalone Activity Execution' - Activity complete/fail: restore --workflow-id YourWorkflowId in examples - Keywords: restore 'activity execution' - Activity count/list: Search Attributes and queries; filter/to be counted - Workflow execute: add backslash after execute in example - Workflow start: revert to main (Initiate, Returns Workflow- and Run-IDs) - Workflow delete: revert to main (Remove, Executions typo); remove TODO - Workflow result: remove TODO (output verb already used) - Workflow count/list: example query and remove TODOs; queries. wording - Restore trailing spaces in worker deployment and task-queue docs to avoid whitespace-only diff noise Co-authored-by: Cursor <cursoragent@cursor.com>
This reverts commit 2ec455d.
- Activity complete/fail: restore --workflow-id in examples - Activity count/list: Standalone Activity Execution wording, filter/sentences, Search Attributes and queries - All standalone-only activity commands: summary + only supported sentence - Restore activity execution keyword - Workflow describe: revert summary to Show Workflow Execution info - Workflow delete: remove TODO - Workflow terminate: revert summary to Forcefully end a Workflow Execution - Workflow execute: add backslash after execute in example - Workflow count/list: remove TODO show an example query - Workflow result: remove TODO Co-authored-by: Cursor <cursoragent@cursor.com>
- Revert all trailing-whitespace-only changes in deployment/worker sections - Restore trailing whitespace on workflow headers line to match main - Apply workflow start description suggestion (mention workflow execute) - Apply id-reuse-policy description suggestion - Apply id-conflict-policy description suggestion - Add visibility docs link to search-attribute description Co-authored-by: Cursor <cursoragent@cursor.com>
Individual verb subcommands already have examples. Co-authored-by: Cursor <cursoragent@cursor.com>
The summaries already say "Standalone", making this sentence redundant in the descriptions. Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
…ityExecution) Neither the Go nor Python SDK exposes this RPC, and the server does not support it yet.
The examples were missing the required timeout, which is confusing since either schedule-to-close-timeout or start-to-close-timeout must be provided. Use different timeouts in each example to illustrate both options.
The server returns an empty non-error PollActivityExecution response when the long-poll timeout (default 20s) expires before the activity completes. This is the server's signal to re-issue the poll. Both execute and result were making a single call and treating the nil outcome as a terminal error. Extract shared pollActivityOutcome that loops until an outcome arrives.
Verifies that pollActivityOutcome retries when the server returns an empty PollActivityExecution response (nil outcome), rather than treating it as a terminal error. Uses a gRPC interceptor to simulate the long-poll timeout on the first poll, then return a result on the second. Without the fix in 384741e, this test fails with "activity outcome not available".
- pollActivityOutcome: use `for resp.GetOutcome() == nil` loop matching the SDK-Go's PollActivityResult pattern - printActivityOutcome: use type switch on GetValue() matching SDK-Go style, with informative default case - Enable standalone activities in dev server (history.enableChasm, activity.enableStandalone) with short long-poll timeout (2s) - Rewrite long-poll retry test as proper integration test: activity sleeps 3s, exceeding the 2s long-poll timeout, forcing a retry
…mands Workflow command tests are 100% integration tests (SharedServerSuite), with no TestHelp_* unit tests. Conform to that precedent: - Remove TestHelp_ActivitySubcommands, TestHelp_ActivityStartFlags, TestHelp_ActivityCompleteFlags, TestHelp_ActivityFailFlags - Add integration tests: Start, Execute (success, failure, poll retry), Result, Describe, List, Count, Cancel, Terminate - Add startStandaloneActivity helper for tests that need a running standalone activity
… count/delete wording - Revert whitespace-only reformatting of `activity complete` description - Apply "Output a count" for `workflow count` per review suggestion - Apply "queries" for `workflow delete` per review suggestion
- Apply suggestion: parent description → "Perform operations on Activity Executions." - Replace "Temporal Markdown" with "standard Markdown excluding images, HTML, and script tags"
The test was asserting map[foo:bar] which is Go's internal format.
The expected output is JSON: {"foo":"bar"}.
printActivityOutcome now JSON-marshals values so complex types (maps, slices) render as JSON rather than Go's fmt representation.
Tests verify that `activity complete` and `activity fail` work for standalone activities (without --workflow-id, using --run-id).
Replace hand-rolled PollActivityExecution long poll loop with the SDK's client.GetActivityHandle().Get(), which provides proper gRPC long-poll handling and retry semantics. This is analogous to how workflow update uses UpdateWorkflow() + updateHandle.Get().
Move workflow command text improvements (summaries, descriptions) out of this PR to keep it focused on standalone activity client functionality.
- cancel: direct verb instead of verbose "Request cancellation of" - complete/fail: add "with a result" / "with an error" for specificity - describe: "Show ... info" instead of parroting command name - execute: "Start ... and wait for its result" to distinguish from start - result: "Get the result" instead of verbose "Wait for and output" - start: drop redundant "a new" - terminate: "Forcefully end" to convey what terminate means
- Start output: add Type, Namespace, TaskQueue for parity with workflow start - Describe: switch from raw proto to SDK ActivityHandle.Describe() - Cancel: switch from raw proto to SDK ActivityHandle.Cancel() - Terminate: switch from raw proto to SDK ActivityHandle.Terminate() - Count: switch from raw proto to SDK cl.CountActivities() - List: add page size normalization matching workflow list - Add failing tests for execute JSON output (success + failure)
getActivityResult now produces structured JSON with activityId, runId, status (COMPLETED/FAILED), and result or failure details, matching the workflow execute JSON output pattern.
…tion proto Replace buildStartActivityRequest + raw proto call with cl.ExecuteActivity(ctx, opts, type, args...), mirroring the workflow pattern (buildStartOptions + cl.ExecuteWorkflow). The SDK now handles identity, request ID, input encoding, header propagation, user metadata serialization, and priority conversion. Removes the `started` field from start output since the SDK's ActivityHandle doesn't expose it (non-error return implies started).
The failure field should be a structured object with message, cause, etc. matching the workflow execute output, not a flat error string.
Use temporal.GetDefaultFailureConverter().ErrorToFailure() to convert the SDK error back to a proto Failure, then marshal it as JSON. This gives the same structured failure info (message, source, cause, applicationFailureInfo, activityFailureInfo) that workflow execute provides via its closeEvent.
Matches workflow count test coverage by verifying JSON output structure.
Text failure output should show Status and Failure message on stdout, matching the workflow execute pattern, not just log an error.
Use ErrorToFailure + MarshalFriendlyFailureBodyText to print a structured failure card (Status, Failure with Message/StackTrace/Cause) matching the workflow execute text output pattern.
Bring TestStandaloneActivity_Complete and _Fail into parity with the pre-existing workflow-bound tests by verifying results via handle.Get() and passing --identity.
Describe: add JSON output, --raw flag, and status/task-queue assertions. Count: already had JSON coverage from prior commit.
Cancel test now verifies RunState transitions to CancelRequested. Terminate test now verifies handle.Get() returns a termination error. Fix cancel YAML: use "Request cancellation" in summary; correct the claim that cancel has no effect on non-heartbeating activities (it does transition RunState to CancelRequested).
Match the workflow text output structure: start and execute now print a "Running execution:" section with ActivityId, RunId, Type, Namespace, TaskQueue. Execute additionally prints a "Results:" section with Status (COMPLETED/FAILED) and Result/Failure.
Merge JSON test into the success test (matching workflow pattern), verify activityId in JSON output, verify input was received by the activity.
The dev server supports GROUP BY for activity counts; the earlier attempt used the wrong column name (ActivityType).
Tests reproduce: - describe --raw producing identical output to non-raw - describe text showing ActivityType as raw proto JSON - describe text showing LastFailure as raw JSON blob - result on nonexistent activity returning FAILED instead of error - result -o json showing empty runId
- describe: non-raw text output now formats ActivityType as name, LastFailure as human-readable text, durations as Go durations. --raw preserves the raw proto output. - result: nonexistent activity returns a CLI error instead of misleadingly rendering as a FAILED result. - result: JSON output populates runId from describe when --run-id is not specified. - execute/result: --no-json-shorthand-payloads now works, showing raw payload format with metadata/encoding/data fields.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Test plan