Relationships
#3722 Expose run provenance (definitionHash, modelVersion, triggeredBy) in method-summary reports or the extension context
Opened by sntxrr · 10/21/2026· Shipped 10/22/2026
Problem
An extension that diagnoses failed runs (read-only triage over @swamp/method-summary / @swamp/workflow-summary data) cannot answer the two most useful questions about a failure:
- Did anything change between the last success and the first failure?
swamp model method history get <id> --jsonalready recordsprovenance.definitionHash,provenance.modelVersion,triggeredByandinitiatedByper run. None of it is in the method-summary report, and nocontextAPI (dataRepository,queryData,readModelData) reaches run history. ComparingdefinitionHash/modelVersionacross that boundary would turn "it broke at 06:53" into "the definition changed" or "the extension was upgraded". - What did the failing call pass? The summary lists argument names (
methodArgs,globalArgs), never values. When a run fails on an input (e.g. a path that is a file, not a directory), a diagnoser cannot tell a bad per-call value from a bad definition, and an LLM agent reading the finding tends to invent a definition fix.
Proposed solution
Either of:
- Add
provenance(definitionHash,modelVersion,triggeredBy,initiatedBy, plus the enclosing workflow run id when there is one) to the@swamp/method-summaryJSON, and the method-argument values with any schema-sensitive argument redacted as global arguments already are. - Or expose read-only run history to extensions, e.g.
context.readRunHistory({ modelName, limit })returning whatswamp model method history getreturns.
Alternatives considered
- Reading swamp's internal files under
.swamp/from an extension: fragile across releases and differs per datastore. - Shelling out to
swamp model method historyfrom a method: needs--allow-run, and bypasses swamp's own interfaces.
Also noticed
Locally run methods — including ones launched by a scheduled swamp workflow run — all record triggeredBy: manual with the same initiatedBy, so the field cannot yet tell a scheduled run from an interactive one.
Shipped
Click a lifecycle step above to view its details.
stack72 commented 10/22/2026, 9:05:40 PM
@sntxrr thanks for such a detailed report. Here's what's shipping, and why we went only partway down your list.
What changes
The @swamp/method-summary report now has a provenance block, in its JSON and as a Provenance section in its markdown. It holds:
definitionHashmodelVersiontriggeredByinitiatedBy- for a workflow step, the workflow id, run id and step name
An extension that reads summaries can now compare the last success with the first failure.
- Different
definitionHash: the definition was edited. - Different
modelVersion: the extension was upgraded. - Neither changed: look at the inputs.
Report extensions also get the same data as context.provenance.
While building this we found that definitionHash was taken after the call's inputs had been written into the definition. So a different --input value, or a workflow input like your path, produced a new hash on every run. That would have pointed your diagnoser at "the definition changed" for exactly the bad-input failures you described. The hash now covers only the stored definition, so it changes only when someone edits it. Summaries from earlier versions have no provenance block, so compare only summaries that both have one.
Workflow steps also now record initiatedBy. Before, it was only set for direct runs.
What we left out, and why
- Argument values. The summary lists names only on purpose. We took values out after a secret leaked through it, and keeping them safe depends on every sensitive argument being marked in its schema. Even with masking, values come in from too many places, such as
--input, workflow inputs, data reads and vault references. A summary that thousands of runs write, and anyone with data read access can see, is the wrong place to depend on that being complete. If you need the failing call's values, could you tell us what your diagnoser would do with them? There may be a narrower way to give you that signal, for example a flag saying whether the value came from the definition or from the call. - A run-history API for extensions. With provenance in every summary, an extension can already find what changed from the data it can read. A history API would be new public surface for extension authors, so we'd rather add it once there's a question the summaries can't answer.
"triggeredBy: manual for scheduled runs"
We couldn't reproduce this. A step run by swamp workflow run records triggeredBy: workflow, with the workflow run id and step name. Only a direct swamp behavior run (or swamp model method run) records manual. How does your schedule start its runs: cron calling swamp workflow run, swamp serve schedules, or a workflow step that shells out to swamp model method run? Also, swamp has no separate trigger type for scheduled runs today. A cron-started swamp workflow run looks the same as one you start by hand. If you need to tell them apart, that's worth its own issue.
Sign in to post a ripple.