[subnetmarco]

Adds volcano durable callbacks succeed|fail|heartbeat <token>, the token holder's side of ctx.waitForCallback (hosting#1966).

• The token is the only credential these commands send, so they need no login or project. Pass - instead of the token to read it from stdin.
• The token is checked locally against the API's shape before anything is sent, and never appears in output or errors. The <token> placeholder isn't on telemetry's resource list.
• succeed takes --result or --result-file and refuses null before sending. fail takes --type and --message.
• A 202 reports that the answer is still being delivered and shouldn't be resent. callback_completed, callback_expired, execution_ended, callback_not_found and a heartbeat 503 each say what became of the wait.
• The three callback routes are synced into openapi/openapi.yaml, and the client is regenerated.
• Telemetry redaction also matches vcb_ tokens, in case an error ever quotes one. Hosting#1966 makes the same change to its copy of the rules.

Tests

• Unit tests cover the API wire shape, no Authorization header, stdin tokens, refusals made before any request, and refusal mapping.
• TestAPIE2ECloudDurableCallbacks runs in hosting's cloud-e2e durable CLI suite. hosting#1966 adds it to durable_regex. The workflow logs each token, and the test reads it from durable logs --type runtime. It then heartbeats and succeeds one token and fails the next, using a fresh HOME with no login, and follows both outcomes into the execution's result.
• TestLocalModeE2EDurableCallbacks runs the same round trip on the local stack. It is added to make localmode-e2e, which this repo's localmode-e2e job and hosting's local-mode workflow both run. Local mode supports callbacks (hosting#1966), so there is no refusal path.

Merge order

This PR stays a draft until its dependencies exist. The cloud test pins @volcano.dev/sdk ^2.2.0, the first release with waitForCallback, and runs only from CLI main after that release. The local-mode test deploys a Python workflow that builds volcano-sdk-python from a source archive of a fixed commit (the head of Kong/volcano-sdk-python#400, then its merge commit), so it doesn't wait for a release. It switches to volcano-sdk-python~=0.16.0 once that's published. Both tests need a server and a local-nightly image with the callback routes, so localmode-e2e stays red until hosting#1966 merges and the nightly image rebuilds.

1. Release sdk-js#332 and sdk-python#400.
2. Merge hosting#1966 and deploy it to staging.
3. Merge this PR.
4. Release the CLI, then merge hosting#2077 (the hosting CLI smoke refusals) and volcano-skills#67.

[github-actions]

AI review: no P0-P2 findings

Reviewed 29311b8. Run log

Adds volcano [cloud] durable callbacks succeed|fail|heartbeat <token>. The commands send only the vcb_ token, with no Authorization header, check it locally before any request, and can read it from stdin with -. The PR also adds the three callback routes to the vendored OpenAPI spec and regenerated client, adds vcb_ to telemetry redaction, adds cloud and local-mode E2E tests, and updates the docs. All three P2 findings from the last review are fixed at this head: refusals keep the API error via api.WithCause, so an unknown token exits 4; the callbacks group skips the project link; and both E2E tests accept a delivering answer. Risk is low and the change is additive; the only remaining finding is a P3 stale line in docs/connect.md.

⚪ P3

• docs/connect.md:189 connect.md still says every non-local command fails on a broken project link

Not checked: The AI review read the diff, the code, and the PR's text; it ran no tests or builds and read nothing outside this repository.

• Whether hosting#1966's deployed callback routes match the vendored contract (paths, 200/202, refusal codes, heartbeat 503) and answer within the CLI's HTTP timeout.
• Whether @​volcano.dev/sdk ^2.2.0 ships waitForCallback, and volcano-sdk-python~=0.16.0 on PyPI has CallbackFailedError and wait_for_callback.
• Whether local-nightly serves the callback routes and local durable logs --type runtime shows Python prints; localmode-e2e now depends on both.
• Whether the docs-site page /platform/functions/durable-callbacks linked from docs/durable-functions.md exists.
• Verify hosting#1966 is deployed and included in local-nightly, matching the vendored callback contract and responding within the client's 60-second timeout.

Human review: needed

• Should possession of a callback token alone authorize completing, failing, or heartbeating a workflow wait without login or project configuration (internal/durable/callbacks.go and openapi/openapi.ya…

The AI review found no P0-P2 problems at 29311b8, so the code needs no second review for bugs. Decide the points above: approve to accept them, or request changes.

Suggested reviewer: swkeever (maintains docs/durable-functions.md and the vendored OpenAPI/client for durable routes). Any collaborator with write access other than the author can approve.

[Copilot]

🟡 Changes recommended

HTML escaping can push valid callback results over the request limit, API error translation loses documented exit codes and telemetry metadata, and unrelated project-link errors can block token-only commands.

3 open issues

• Disable HTML escaping to prevent valid bodies exceeding size limit · New
• Avoid project link validation for token-only cloud callbacks · New
• Preserve API error metadata and documented not-found exit code · New

What changed in this PR

Adds token-based callback commands so external systems can resume or heartbeat durable workflows without a login or project.

Changes:

• Adds callbacks succeed, fail, and heartbeat, including stdin tokens, JSON output, and refusal messages.
• Extends the OpenAPI specification and generated client, and adds callback-token telemetry redaction.
• Documents callback usage and adds unit and cloud/local end-to-end coverage.

File	Description
tests/​e2e/​localmode/​durable_callbacks_test.go	Tests callback round trips on the local stack.
tests/​e2e/​api/​durable_callbacks_test.go	Tests cloud callbacks without holder login.
openapi/​openapi.yaml	Defines callback routes and schemas.
Makefile	Includes callbacks in local acceptance tests.
internal/​telemetry/​fields.go	Adds callback-token redaction.
internal/​telemetry/​fields_test.go	Tests callback-token redaction.
internal/​durable/​callbacks.go	Adds token validation, service calls, and refusal mapping.
internal/​cmd/​durable/​durable.go	Registers the callbacks command group.
internal/​cmd/​durable/​callbacks/​succeed.go	Adds JSON-result submission and null rejection.
internal/​cmd/​durable/​callbacks/​heartbeat.go	Adds heartbeat submission.
internal/​cmd/​durable/​callbacks/​fail.go	Adds callback failure submission.
internal/​cmd/​durable/​callbacks/​callbacks.go	Provides token input and shared output helpers.
internal/​cmd/​durable/​callbacks/​callbacks_test.go	Tests command input, authentication behavior, and outcomes.
internal/​apiclient/​client.gen.go	Generates callback models and request methods.
internal/​api/​durable_callbacks.go	Wraps callback API operations.
internal/​api/​durable_callbacks_test.go	Tests request bodies and refusal codes.
docs/​telemetry.md	Documents callback-token redaction.
docs/​README.md	Lists callback support.
docs/​durable-functions.md	Documents callback commands and retry behavior.

_{Review effort: Balanced}