Skip to content

docs: dispatch-workflow default max disagrees between safe-outputs-specification.md (3) and actual implementation (1) #49600

Description

@blozano-tt

Summary

dispatch-workflow's documented default max disagrees with its actual implemented default. This surfaced while configuring dispatch-workflow for a real workflow (tenstorrent/tt-metal's silencer.md) and needing to reason precisely about how many dispatch calls a single agent turn could make without an explicit max.

The mismatch

  • docs/src/content/docs/specs/safe-outputs-specification.md states Default Max: 3 for dispatch_workflow.
  • docs/src/content/docs/reference/rate-limiting-controls.md states the default max for dispatch-workflow is 1.
  • pkg/workflow/safe_outputs_validation_config.go sets DefaultMax: 1 for dispatch_workflow.
  • pkg/workflow/dispatch_workflow.go's parseDispatchWorkflowConfig defaults to 1 when max is omitted, whether the config is given as a simple workflow-name list or a map.
  • The runtime handler in actions/setup/js/dispatch_workflow.cjs reads config.max, which is 1 unless explicitly configured — confirmed by the handler's own tests, which expect the n-th call beyond a configured max to fail with success: false / "Max count reached", tested against the 1-default path.

Three independent sources (Go validation config, Go parser, JS runtime + its tests) agree on 1. Only the older safe-outputs-specification.md page says 3. That page is almost certainly the stale one, but I haven't traced its history to confirm nothing upstream actually intended 3 and regressed.

Impact

Anyone reading only safe-outputs-specification.md (a reasonable place to look — it reads as the canonical spec) will configure a workflow assuming dispatch-workflow allows 3 calls per turn by default, and be surprised when the 2nd call in a turn is silently rejected with "Max count reached" (rejection is correct/by-design — dispatch-workflow explicitly does not truncate — but the surprise comes from the wrong assumed ceiling).

Suggested fix

Whichever number is actually correct, make all four sources agree:

  • If 1 is correct (my read, given 3-of-4 sources and the passing test suite agree): fix the Default Max: 3 line in safe-outputs-specification.md.
  • If 3 was actually intended: update DefaultMax in safe_outputs_validation_config.go, the parseDispatchWorkflowConfig default in dispatch_workflow.go, and rate-limiting-controls.md, plus whatever test coverage assumes 1 today.

Happy to open the doc-only PR myself if a maintainer confirms 1 is the intended behavior (my belief, from the code, but I'd rather not guess wrong on unowned docs).

Metadata

Metadata

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions