Standalone activity client

[dandavison]

What was changed

Why?

Checklist

1. Closes

2. How was this tested:

3. Any docs updates needed?

[dandavison]

Addressed in new commits.

[dandavison]

why delete this? The command still exists but only for workflow activities.

[dandavison]

Restored the original description-header in 1b728de.

[dandavison]

Since this is an experimental API, I don't think it should be the example.

[dandavison]

🤖 Agreed. Changed to use activity complete as the primary example and added activity update-options as the second example in 1b728de.

[dandavison]

But update-options isn't even implemented is it? I thought it wasn't in the grpc API.

[dandavison]

🤖 The update-options command is implemented and functional. It uses WorkflowService().UpdateActivityOptions() from the gRPC API. You can see the implementation at commands.activity.go:101-236 and the passing tests TestActivityOptionsUpdate_Accept and TestActivityOptionsUpdate_Partial in commands.activity_test.go.

Just ran the tests to confirm:

go test -run "TestSharedServerSuite/TestActivityOptionsUpdate" ./internal/temporalcli/ -v
--- PASS: TestSharedServerSuite (1.81s)
    --- PASS: TestSharedServerSuite/TestActivityOptionsUpdate_Accept (0.11s)
    --- PASS: TestSharedServerSuite/TestActivityOptionsUpdate_Partial (0.11s)

[dandavison]

I see. Yes, I was confusing this with the fact that it's not implemented for standalone activity. However, let's not just not add any example here; this is temporal activity after all, not any verb.

[dandavison]

🤖 Agreed — the temporal activity help now shows examples for activity complete and activity update-options (both workflow-activity commands). The standalone-only activity start example has been removed from this top-level help.

[dandavison]

🤖 Understood — the parent command is a grouping command, not a verb. Left as-is with the short description, no example.

[dandavison]

Why did you change this?

[dandavison]

🤖 Reverted in 1b728de. The commonpb alias was unnecessary since there's no import conflict in this file — the default package name common works fine.

[dandavison]

I see. Yes, I was confusing this with the fact that it's not implemented for standalone activity. However, let's not just not add any example here; this is temporal activity after all, not any verb.

[dandavison]

This change is pure whitespace and is just adding noise to the diff.

[dandavison]

🤖 No trailing-whitespace-only changes in current file; any prior diff noise was addressed in 2ec455d.

[dandavison]

The change here differs only in line-wrapping. Revert it please.

[dandavison]

🤖 Reverted in e899625. The complete description is back to the original line wrapping.

[dandavison]

🤖 Already reverted in e899625. The current description matches the original line-wrapping exactly:

Complete an Activity, marking it as successfully finished. Specify the
Activity ID and include a JSON result for the returned value:

[dandavison]

This was here before, so we shouldn't be getting rid of it. In general, standalone activity is a new feature; workflow activity is the more commonly used by a long way.

[dandavison]

🤖 Addressed in 2de6d1e: restored “activity execution” in keywords.

[dandavison]

🤖 The "activity execution" keyword is present at its current position. No content was lost.

[dandavison]

Suggested change

	description: |
	Return a count of Activity Executions. Use `--query` to count
	a subset:
	description: |
	Return a count of Activity Executions. Use `--query` to filter
	the activities to be counted.

[dandavison]

🤖 Addressed in 2de6d1e: activity count/list use “filter the activities to be counted”, “Search Attributes and queries.”, and “Standalone Activity Execution” / “only supported for Standalone Activity Execution” wording.

[dandavison]

🤖 Applied in 2ec455d. Now reads "Return a count of Standalone Activity Executions. Use `--query` to filter the activities to be counted."

[dandavison]

don't make changes in this PR that are merely trailing whitespace

[dandavison]

🤖 No trailing-whitespace-only changes in current file.

[dandavison]

🤖 Reverted all trailing-whitespace-only changes in c96bb91.

[dandavison]

🤖 Trailing whitespace changes removed in 2ec455d.

[dandavison]

Suggested change

	Re-use policy for the Activity ID when a previous
	Execution has completed.
	Policy for handling activity start when an Activity
	with the same ID exists and has completed.

[dandavison]

🤖 Applied suggestion in c96bb91.

[dandavison]

Suggested change

	Policy for handling a conflict when starting an
	Activity with a duplicate Activity ID of a running
	Execution.
	Policy for handling activity start when an
	Activity with the same ID is currently running.

[dandavison]

🤖 Applied suggestion in c96bb91.

[dandavison]

Can you find whether "Temporal Markdown" is documented somewhere? Use your temporal-docs MCP tool and/or the documentation repo.

[dandavison]

🤖 I searched the api proto repo, sdk-go, sdk-java, documentation repo, and UI repo. "Temporal Markdown" is used as a term in Go SDK and Java SDK doc comments (e.g. in single-line Temporal Markdown format) and in the generated CLI docs, but there is no dedicated documentation page or formal specification for it. The term appears to refer to standard Markdown as rendered by the Temporal UI.

[dandavison]

Please change "Temporal Markdown" to "standard Markdown excluding images, HTML, and script tags" everywhere.

[dandavison]

🤖 Applied in a661e6f. All 4 occurrences of "Temporal Markdown" changed to "standard Markdown excluding images, HTML, and script tags" (2 in workflow start options, 2 in activity start options).

[dandavison]

🤖 Addressed all review feedback in commit 2ec455d:

• Activity count/list/result: Use "Standalone Activity Execution" and "only supported for Standalone Activity Execution".
• Activity complete/fail: Restored --workflow-id YourWorkflowId in examples.
• Keywords: Restored "activity execution".
• Activity count/list: "Search Attributes and queries"; "filter the activities to be counted".
• Workflow execute: Added backslash after execute in example.
• Workflow start: Reverted to main (Initiate, Returns Workflow- and Run-IDs).
• Workflow delete: Reverted to main (Remove, Executions typo); removed TODO.
• Workflow result: Removed TODO (output verb already used).
• Workflow count/list: Example queries and "queries." wording; removed TODOs.
• Trailing whitespace: Restored in worker deployment and task-queue docs to avoid diff noise.

2810472090 (server repo test coverage): The server repo is not in this workspace; suggest verifying tests/standalone_activity_test.go in the server repo separately.

[dandavison]

Suggested change

Only supported for Standalone Activity Execution.

[dandavison]

🤖 Applied: removed redundant sentence from all 9 standalone activity command descriptions in ed5405a.

[dandavison]

Capitalization should be Standalone Activit{y,ies} throughout this file.

[dandavison]

🤖 Applied in 69f8335: capitalized "Standalone Activities" in all 6 remaining lowercase instances.

[dandavison]

🤖 Overall Review

This PR adds 8 new temporal activity subcommands (start, execute, describe, list, count, cancel, terminate, result) for standalone activities, and modifies complete/fail to make --workflow-id optional. The structure follows existing workflow command patterns well, and the code is clean and well-organized.

What it's trying to do is right. The mapping of gRPC RPCs to CLI commands mirrors the temporal workflow pattern closely, which is the correct approach.

Issues to address:

1. delete command is missing. The plan calls for 9 new commands; only 8 are implemented. The API has DeleteActivityExecution. Intentional deferral, or oversight?

2. Zero-duration timeouts sent for unset flags — see inline comment on buildStartActivityRequest.

3. No tests for modified complete/fail — These commands changed their option structure. There should be tests for both the standalone path (omitting --workflow-id) and regression tests for the workflow-scoped path.

4. Result formatting uses %v — see inline comment on printActivityOutcome.

5. Unrelated workflow command doc edits — The PR modifies descriptions for workflow cancel, count, delete, describe, execute, result, start, and terminate. These should be in a separate commit to keep the diff focused.

6. .task/, AGENTS.md, CLAUDE.md symlinks — Development scaffolding; remove before merge.

7. Missing --name alias for --type — see inline comment on activity-start option set.

[dandavison]

🤖 %v produces Go-native formatting (e.g. map[foo:bar]). For a CLI tool, users would expect JSON. Consider using json.Marshal(value) or the converter's string representation for consistency with how workflow execute prints results.

[dandavison]

Give me a CLI command or commands that will repro the problem you're describing.

[dandavison]

🤖 Fixed in 15c1f96. The issue: printActivityOutcome used %v which produces Go's internal format for complex types. Any activity execute or activity result where the activity returns a map will show map[foo:bar] instead of {"foo":"bar"}.

Repro (assuming a running activity that returns a map):

temporal activity execute --activity-id test --type MapReturner --task-queue q --start-to-close-timeout 30s
# Was: Result: map[foo:bar]
# Now: Result: {"foo":"bar"}

The test TestStandaloneActivity_Execute_Success was asserting map[foo:bar]. Fixed in 67942e7 to assert {"foo":"bar"}, then fixed the implementation in 15c1f96 to JSON-marshal the value.

[dandavison]

🤖 If the per-RPC rpcCtx deadline fires (e.g. network hiccup causing the 70s timeout), the code falls through to return the error permanently. The parent context (cctx) won't have an error, so the check on line 663 won't save it. Consider retrying on context.DeadlineExceeded when cctx.Err() == nil.

[dandavison]

Please compare the sdk-go long-poll loop implementation for update and activity handle.Get(). Does it have the problem your describing?

[dandavison]

🤖 sdk-go PollActivityResult (internal_activity_client.go:642) uses the same pattern:

for resp.GetOutcome() == nil {
    grpcCtx, cancel := newGRPCContext(ctx, grpcLongPoll(true), grpcTimeout(pollActivityTimeout), ...)
    resp, err = w.client.WorkflowService().PollActivityExecution(grpcCtx, request)
    cancel()
    if err != nil {
        return nil, err
    }
}

And PollWorkflowUpdate (internal_workflow_client.go:2546) does the same with an additional ctx.Err() check after errors.

The CLI's loop is structurally identical. One difference: the CLI checks cctx.Err() (parent context) before returning errors, which correctly distinguishes user cancellation from RPC errors. sdk-go's activity poller returns the raw error without this check. So the CLI's error handling is actually slightly more careful than sdk-go's activity polling.

Neither has the problem I described in my review comment — the per-RPC context timeout is independent of the parent context, and cancel() is called promptly.

[dandavison]

🤖 The analogous shared-workflow-start-options defines aliases: [name] for its --type flag (line 4653). For consistency, this type field should also have aliases: [name].

[dandavison]

🤖 The .task/ directory, AGENTS.md, and CLAUDE.md symlinks are development scaffolding and should be removed before merge.

[dandavison]

I was hoping that this would hide or fold the .task files in the PR, but it doesn't seem to. Do you know why my expectation wasn't met?

[dandavison]

🤖 The linguist-generated attribute makes GitHub collapse diffs in PR views, but the pattern .task/ matches the directory entry itself, not files within it. To match files, the pattern should be .task/** linguist-generated. However, even with the correct pattern, linguist-generated only affects the diff view (collapsing the file), not the file tree sidebar.

[dandavison]

Please compare the sdk-go long-poll loop implementation for update and activity handle.Get(). Does it have the problem your describing?

[dandavison]

Show me evidence that 2s is the relevant timeout here please.

[dandavison]

🤖 The comment claims "the server's activity.longPollTimeout (2s)" but the server default is 20 seconds, not 2. From chasm/lib/activity/config.go:

LongPollTimeout = dynamicconfig.NewNamespaceDurationSetting(
    "activity.longPollTimeout",
    20*time.Second,
    `Timeout for activity long-poll requests.`,
)

With 20s default, an activity sleeping 3s would complete well within the first poll — the test wouldn't actually exercise the retry path unless the dev server overrides this to a shorter value. I cannot find evidence that the dev server sets it to 2s. The comment appears to be incorrect.

[dandavison]

Suggested change

	Complete, fail, or update an Activity's state or options.
	Perform operations on Activity Executions.

[dandavison]

🤖 Applied in a661e6f. Description now reads "Perform operations on Activity Executions."

[dandavison]

The change here differs only in line-wrapping. Revert it please.

[dandavison]

The diff in this comment is making a suggestion; the GitHub UI makes it possible to accept them by clicking on a UI element. Please accept the suggestion, either by using an appropriate API (if GitHub offers such a thing) or manually by making a commit and pushing it.

[dandavison]

Please change "Temporal Markdown" to "standard Markdown excluding images, HTML, and script tags" everywhere.

[dandavison]

🤖 Review: Standalone Activity Commands vs Workflow Counterparts

I compared every new standalone activity function and test against its most similar workflow counterpart. The overarching finding is that the workflow implementation uses the Go SDK's high-level client API (cl.ExecuteWorkflow, cl.CancelWorkflow, cl.TerminateWorkflow, cl.ListWorkflow, etc.), while the standalone activity implementation bypasses the SDK almost entirely, going directly to cl.WorkflowService() proto calls for start, describe, list, count, cancel, and terminate. Only getActivityResult (via cl.GetActivityHandle().Get()) uses the SDK.

The Go SDK at this version provides a comprehensive standalone activity API:

• cl.ExecuteActivity(ctx, client.StartActivityOptions{...}, activityType, args...) → ActivityHandle
• ActivityHandle.Get(), .Describe(), .Cancel(), .Terminate()
• cl.ListActivities(ctx, options), cl.CountActivities(ctx, options)

Using the SDK would bring search attribute/header/payload serialization consistency, interceptor support, and reduced maintenance surface — mirroring how workflows are implemented in this CLI.

See inline comments for details.

[dandavison]

🤖 Review: Standalone Activity Commands vs Workflow Counterparts

I compared every new standalone activity function and test against its most similar workflow counterpart. The overarching finding is that the workflow implementation uses the Go SDK's high-level client API (cl.ExecuteWorkflow, cl.CancelWorkflow, cl.TerminateWorkflow, cl.ListWorkflow, etc.), while the standalone activity implementation bypasses the SDK almost entirely, going directly to cl.WorkflowService() proto calls for start, describe, list, count, cancel, and terminate. Only getActivityResult (via cl.GetActivityHandle().Get()) uses the SDK.

The Go SDK at this version provides a comprehensive standalone activity API:

• cl.ExecuteActivity(ctx, client.StartActivityOptions{...}, activityType, args...) → ActivityHandle
• ActivityHandle.Get(), .Describe(), .Cancel(), .Terminate()
• cl.ListActivities(ctx, options), cl.CountActivities(ctx, options)

Using the SDK would bring search attribute/header/payload serialization consistency, interceptor support, and reduced maintenance surface — mirroring how workflows are implemented in this CLI.

See inline comments for details.

[dandavison]

🤖 Major: hand-rolling proto request instead of using Go SDK

The workflow counterpart uses the SDK: buildStartOptions() builds client.StartWorkflowOptions, then cl.ExecuteWorkflow() handles the proto construction, including search attributes, headers, user metadata, priority, and retry policy serialization.

Here, the entire StartActivityExecutionRequest proto is hand-built (~110 lines). The Go SDK provides client.StartActivityOptions with fields for all of these (ID, TaskQueue, timeouts, policies, RetryPolicy, TypedSearchAttributes, Summary, Details, Priority), and cl.ExecuteActivity(ctx, opts, activityType, args...) returns an ActivityHandle.

Specific issues with the hand-rolled approach:

1. Search attributes (line 157): uses encodeMapToPayloads to build raw common.SearchAttributes. The workflow version passes map[string]any to the SDK's StartWorkflowOptions.SearchAttributes, letting the SDK serialize. Different code path, potential for subtle differences.

2. UserMetadata (line 181): manually creates payloads with json/plain encoding and %q formatting. The workflow version just sets StaticSummary/StaticDetails as strings on StartWorkflowOptions, letting the SDK handle serialization.

3. Headers (line 169): builds common.Header{Fields: ...} directly on the proto. The workflow version uses contextWithHeaders() + SDK interceptor pipeline. Since this call bypasses the SDK, headers won't flow through SDK interceptors.

One consideration: the SDK's ActivityHandle exposes GetID()/GetRunID() but not Started from the proto response. If Started is essential, you could call cl.ExecuteActivity() and always report started=true (since a non-error return implies start), or access it via the raw response if the SDK supports it.

See buildStartOptions in commands.workflow_exec.go:568 and startWorkflow at line 518 for the workflow pattern.

[dandavison]

🤖 Start output less informative than workflow counterpart

The workflow startWorkflow (commands.workflow_exec.go:518) prints:

Running execution:
  WorkflowId  my-id1
  RunId       <uuid>
  Type        DevWorkflow
  Namespace   default
  TaskQueue   my-queue

The activity start prints:

  ActivityId  start-test
  RunId       <uuid>
  Started     true

Missing: Type, TaskQueue, and Namespace. The Started field is unique to activities, which is good. But consider also printing the type, task queue, and namespace for parity with the workflow experience.

[dandavison]

🤖 Execute: appropriate simplification vs workflow counterpart

The workflow execute (commands.workflow_exec.go:42) is much more elaborate: it shows progress (streaming history events), handles continue-as-new, prints colored status, and has separate JSON/text result formatting.

The activity execute is simpler: start + get result. This is appropriate since standalone activities don't have event history in the same way. The simplicity is good.

However, if the activity fails, the error message "activity failed: " doesn't give the structured output that the workflow version does (e.g. status, failure message, etc.). Consider whether a failed activity should still produce structured output before returning an error, as the workflow version does.

[dandavison]

🤖 Result output less informative than workflow counterpart

Compare with the workflow's printTextResult (commands.workflow_exec.go:470) and workflowJSONResult (commands.workflow_exec.go:390):

• Workflow text output: colored Status (COMPLETED/FAILED/TIMEOUT/CANCELED), RunTime, Result with encoding, and Failure details — all via cctx.Printer.PrintStructured.

• Activity text output: just Result: %s with raw JSON bytes.

• Workflow JSON output: rich struct with workflowId, runId, type, namespace, status, closeEvent, result, and optional history.

• Activity JSON output: {"result": ...} — minimal.

For consistency with the workflow experience, consider printing a status and using PrintStructured for text output.

Also note: the workflow result commands handle non-completion by returning fmt.Errorf("workflow failed"), reporting both the print error and the status. The activity version returns the error from handle.Get(), which is fine semantically, but the user experience is different.

[dandavison]

🤖 Use SDK ActivityHandle.Describe() instead of raw proto

The SDK provides ActivityHandle.Describe(ctx, client.DescribeActivityOptions{}) which returns *client.ActivityExecutionDescription. This is consistent with how workflow describe uses the SDK's typed responses.

The raw proto approach here works, but it bypasses the SDK's response transformation layer (the SDK wraps the proto into ClientActivityExecutionDescription which includes typed search attributes, etc.).

[dandavison]

🤖 No JSON output test — compare with TestWorkflow_Execute_SimpleSuccess (commands.workflow_exec_test.go:134)

The workflow execute test checks both text and JSON output:

// JSON
res = s.Execute("workflow", "execute", "-o", "json", ...)
var jsonOut map[string]any
s.NoError(json.Unmarshal(res.Stdout.Bytes(), &jsonOut))
s.Equal("my-id2", jsonOut["workflowId"])
s.Equal("COMPLETED", jsonOut["status"])
s.NotNil(jsonOut["closeEvent"])
s.Equal(map[string]any{"foo": "bar"}, jsonOut["result"])

This test only checks text output. Consider adding a JSON variant.

Also, the workflow test verifies the input was received (s.Equal([]any{"val1", "val2"}, s.Worker().DevWorkflowLastInput())). Consider passing input and verifying the activity received it.

[dandavison]

🤖 Minimal describe test — compare with workflow describe tests

The workflow describe has extensive test coverage: TestWorkflow_Describe_ActivityFailing, TestWorkflow_Describe_Completed, TestWorkflow_Describe_Versioned, TestWorkflow_Describe_NotDecodable, TestWorkflow_Describe_ResetPoints, etc. (commands.workflow_view_test.go:28+).

This test only checks that ActivityId and type name appear in the output. Consider:

• Testing --raw flag (the describe command has a c.Raw code path)
• Testing JSON output (-o json)
• Verifying more fields (status, task queue, timeouts)

[dandavison]

🤖 No JSON output test — compare with TestWorkflow_Count (commands.workflow_view_test.go:465)

The workflow count test verifies both text and JSON output, including checking the response structure with group values. This test only checks that "Total:" appears in the text output.

Consider adding a JSON variant and potentially testing GROUP BY behavior to match the workflow count test's coverage.

[dandavison]

🤖 Cancel/terminate tests don't verify actual state change

Both TestStandaloneActivity_Cancel and TestStandaloneActivity_Terminate check that the command succeeds and prints the expected message, but don't verify the activity's state actually changed.

Compare with how the pre-existing TestActivityPauseUnpause (line 204) uses s.Eventually to confirm the activity is actually paused/unpaused by calling DescribeWorkflowExecution and checking PendingActivities[0].Paused.

For standalone activities, consider verifying via DescribeActivityExecution or handle.Get() that cancel/terminate took effect (e.g. handle.Get() returns a cancellation/termination error).

[dandavison]

🤖 Config additions look correct

The three dynamic config settings (frontend.activityAPIsEnabled, history.enableChasm, activity.enableStandalone) are required for standalone activity support. The activity.longPollTimeout of 2s is used by the TestStandaloneActivity_Execute_RetriesOnEmptyPollResponse test which sleeps 3s to force an empty poll.

Minor: the comment // Disable DescribeTaskQueue cache. from the previous line appears to have been displaced — it was likely for the DescribeTaskQueue TTL line below, not for these new config lines.