Proposal: first-class run display names, labels, links, and external status

[PhreeMason]

Use case

Local tools can dispatch a durable AgentField run with a stable X-Run-ID, signed completion webhook, input, output, and structured notes. The stock run dashboard still requires users to decode a technical run identifier or open the input/notes to learn which external task the run represents.

A pull-request reviewer, for example, should be identifiable at a glance as PR #472 — Fix hiding posted review platforms, link directly to the pull request, and show an external lifecycle such as review complete / publish pending, published, or publication failed / retryable. That status may change after the AgentField execution itself is complete.

Proposed contract

Add optional, provider-neutral run metadata:

• display_name: mutable human-readable run name
• labels: searchable string labels or a bounded key/value map
• links: bounded {label, url} entries rendered as safe clickable links
• external_status: mutable {state, label, url?, detail?} owned by the integrating application

The asynchronous execute endpoint could accept initial metadata, and a narrow authenticated run-metadata endpoint could update mutable fields after execution. The run list and detail dashboard should render the display name, labels, links, and external status while retaining the stable run identifier as technical identity.

Safety and compatibility

• Keep every field optional and backwards compatible
• Apply strict size/count limits and URL scheme validation
• Do not treat labels or links as trusted HTML
• Keep execution status separate from integration-owned external status
• Include metadata in the agentic run summary/query surface so non-dashboard clients can discover it without loading execution payloads
• Avoid placing credentials or webhook secrets in these fields

Structured notes are useful for progress, but they do not replace a concise list-row identity, clickable external target, or post-execution publication state.

[AbirAbbas]

Triage

Classification: feature ✓
Suggested labels: enhancement

Likely affected files:

• ./reasoners/webhook_router.py (matched: webhook, webhook)
• ./.env.example (matched: example)

---

Triage by github-buddy

[AbirAbbas]

Good proposal, and most of the plumbing for it already exists — this is smaller than it looks.

What's there today: workflow_runs.metadata is already a JSONB column (migrations/011_create_workflow_runs_and_steps.sql:12, AutoMigrated so it exists in local SQLite mode too) carrying two namespaces — lineage (internal/handlers/execute_restart.go:275) and golden (internal/handlers/ui/workflow_runs.go:272). There's already a mutable authenticated endpoint that read-modify-writes it (POST /api/ui/v2/workflow-runs/:run_id/golden → SaveGoldenRunHandler), the run list/detail already fan that metadata into the summary, and the UI already renders a golden badge and a clickable lineage link in exactly the badge lane your labels/links would live in (web/client/src/pages/RunsPage.tsx:1851-1875). display_name is already on the wire — it's just derived, never client-settable.

What's genuinely missing, i.e. your ask: the unified async execute path accepts none of it (readExecutionHeaders reads only X-Run-ID / X-Parent-Execution-ID / X-Session-ID / X-Actor-ID; X-Workflow-Name/X-Workflow-Tags exist only on the legacy sync endpoints and no SDK sends them), and /api/v1/agentic/run/:run_id returns nothing about run identity — since af wait polls exactly that endpoint, your point about the agentic surface is the sharpest one here. (#711 doesn't cover this — that was the af share HTML export.)

So: happy to take this, with a reduced v1 — display_name + labels + links, as one more namespace in workflow_runs.metadata. Let's hold external_status for a follow-up; it's the piece most likely to need iteration and I'd rather not bake a lifecycle vocabulary in on the first pass.

If you want to open a PR, the shape I'd want:

• Copy the SaveGoldenRunHandler read-modify-write pattern, but register the endpoint under /api/v1/runs/:run_id/metadata, not /api/ui/v2 — integrating apps shouldn't have to call a UI-private route. Auth comes free from the global API-key middleware.
• Don't reuse the full-row StoreWorkflowRun UPSERT (internal/storage/local.go:222-238) for updates; it overwrites status/step counts from the caller. A metadata-only column update avoids clobbering the restart-lineage seed fields — see the sole-writer note at execute_restart.go:269-274, which this change makes stale.
• Limits: sanitizeStringList (ui/workflow_runs.go:648) has no count or length cap today. Add caps there (that also fixes unbounded golden tags) — suggest display_name ≤ 200, labels ≤ 20 × ≤ 64, links ≤ 10 with url ≤ 2048.
• URL validation: scheme+host required, http/https only, reject embedded credentials. Don't pull in services.ValidateWebhookURL — its SSRF/private-address blocking would reject legitimate internal PR links. Scheme-check again at render and use rel="noopener noreferrer".
• external_status, when it lands, must never feed deriveOverallStatusForUI or the status filter.

Please include a validation contract in the PR description. internal/handlers/ui/coverage_execution_workflow_handlers_test.go:416 is a good template for the round-trip/namespace-coexistence test; I'd also want negative tests for a javascript: link, oversize labels, and "metadata update does not clobber lineage".