feat: agent execution observability — run tools, provenance, and lifecycle history#411
Merged
Merged
Conversation
Make execution history lifecycle- and provenance-aware, and let flow run ad-hoc/transient commands as first-class, recorded executions. - ExecutionRecord gains Status (running/completed/failed), CompletedAt, PID, Source/ClientName/SessionID, and Command/Label; RecordExecution upserts by run ID so a run transitions running -> terminal in place. - exec writes a "running" record at start and finalizes at completion; stale running records (dead PID) are reconciled on read, reusing a shared process.Alive helper. - `flow exec --cmd` runs one or more ad-hoc commands (serial/parallel via --mode) as a transient executable; `--spec` runs an inline executable of any type. Runs resolve a workspace (--workspace, then the run dir, then current) without mutating the global current workspace. - `flow logs` surfaces status, command/label, and provenance. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Add run_command (single or batched shell commands) and run_executable (transient executable of any type from an inline spec); both propagate the MCP client name and session id as run provenance to the flow subprocess so runs are attributable in history. - Return structuredContent from the data tools and drop the large advertised output schemas on the read/list tools, roughly halving the always-loaded tool surface (~5.4k -> ~2.7k tokens) with no capability loss. Also drop the verb enum from execute/get_executable. - Trim server instructions to essentials and update the flow-context skill to prefer flow's run tools over raw shell. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add --source/--session/--client filters to `flow logs` and make the status filter lifecycle-aware (running/completed/failed, with success/failure aliases). Surface run origin in both the TUI list view (new Origin column) and the plain-text list, alongside the existing provenance in detail views. Expose the same through the MCP get_execution_logs tool: source/session/ status params plus a `mine` shortcut that scopes results to the calling session's own runs. Drop the remaining output schemas from switch_workspace and sync_executables to keep the tool surface lean. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Update the AI Tools guide with run_command/run_executable and a new Observability section covering lifecycle-aware history, provenance (source/client/session), and the get_execution_logs `mine` filter; sync the Claude Code skill example to the pick-the-closest-tool ladder. Add source/session/client filtering and lifecycle status to the Execution History guide, and refresh the llms.txt descriptions so agents pulling the index know the observability surface exists. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Codecov Report❌ Patch coverage is 📢 Thoughts on this report? Let us know! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Makes flow usable as an agent's primary execution engine and turns its history into an observability surface. Three layers:
runningand updated tocompleted/failedat finish, so in-progress foreground runs are visible from any terminal (not just after they exit). Runs whose process dies are reconciled tofailedon next view.cli, ormcpwith the calling client name (claude,cursor, …) and session ID.flow logsgains--source/--session/--clientfilters and a lifecycle-aware--status(running/completed/failed, withsuccess/failurealiases). Origin is surfaced in the TUI list (new Origin column), the plain-text list, and detail views.run_command(arbitrary shell command(s), single or serial/parallel batch) andrun_executable(transient executable of any type from an inlinespec) tools, so agents run everything through flow with workspace env/secrets and a durable, attributable history entry.get_execution_logsexposes the same provenance filters plusmine: true(this session's own runs). The always-loaded tool surface was trimmed ~50% (output schemas pruned to the execution tools; server instructions slimmed) to lower context cost.All three run tools (
execute,run_command,run_executable) stamp provenance via a shared transient path. Per-runworkspacescoping never mutates the global current workspace.Docs
integrations.mdtool list andllms.txtdescriptions updated; generated CLI docs regenerated.Testing
flow validategreen (generate → lint → unit → e2e → schemas), no generated drift.Notes
omitemptyrecord fields keep legacy history unmarshalling;RecordExecutionupserts by run ID.main; independent of the container-detail work onjdoc/feat-container-exec-view.🤖 Generated with Claude Code