Skip to content

Bounded run reads: paged run list, run summaries, path reads, retention - #59

Merged
pallaoro merged 1 commit into
mainfrom
bounded-run-reads
Sep 25, 2026
Merged

pallaoro merged 1 commit into
mainfrom
bounded-run-reads

Conversation

@pallaoro

Copy link
Copy Markdown
Member

Every run is one JSON file in the state directory and none was ever deleted,
so the run list grows with every trigger that fires, and one record carries
each node's output more than once (state, completedNodes, trace). Returned
whole, either can overflow what an agent reads in one tool result; hosts cut
larger results and keep only the start.

  • core/runs.ts, exported for other hosts like manage.ts:
    • listRuns: newest first, a page at a time, on a (createdAt, instanceId)
      cursor so runs that start while a caller pages never shift a page and
      runs created in the same millisecond are neither skipped nor repeated.
      Loop/branch instance files are skipped by name, before parsing.
    • summarizeRun / runView: the run whole when it fits, else its status,
      error, each state key with its size, and the trace without outputs.
    • readRunValue: one value by dot path. Arrays are paged by item and a page
      shrinks until it fits, strings are paged by character, and an object too
      big to return comes back as its outline with paths to pass back.
    • pruneRuns: deletes finished runs (completed, failed, cancelled) with their
      sub-flow files after the retention period. Running, paused and waiting
      runs are never deleted; resume reads their record.
  • flow_status lists runs a page at a time (limit, cursor, flow, filter) and
    reads one value of a run with path/offset/limit. flow_run and flow_resume
    return the summary once a run passes 16,000 characters.
  • Retention runs daily in the serving process, first a minute after start.
    runRetentionDays in the plugin config, default 30; 0 keeps every run.

Every run is one JSON file in the state directory and none was ever deleted,
so the run list grows with every trigger that fires, and one record carries
each node's output more than once (state, completedNodes, trace). Returned
whole, either can overflow what an agent reads in one tool result; hosts cut
larger results and keep only the start.

- core/runs.ts, exported for other hosts like manage.ts:
  - listRuns: newest first, a page at a time, on a (createdAt, instanceId)
    cursor so runs that start while a caller pages never shift a page and
    runs created in the same millisecond are neither skipped nor repeated.
    Loop/branch instance files are skipped by name, before parsing.
  - summarizeRun / runView: the run whole when it fits, else its status,
    error, each state key with its size, and the trace without outputs.
  - readRunValue: one value by dot path. Arrays are paged by item and a page
    shrinks until it fits, strings are paged by character, and an object too
    big to return comes back as its outline with paths to pass back.
  - pruneRuns: deletes finished runs (completed, failed, cancelled) with their
    sub-flow files after the retention period. Running, paused and waiting
    runs are never deleted; resume reads their record.
- flow_status lists runs a page at a time (limit, cursor, flow, filter) and
  reads one value of a run with path/offset/limit. flow_run and flow_resume
  return the summary once a run passes 16,000 characters.
- Retention runs daily in the serving process, first a minute after start.
  runRetentionDays in the plugin config, default 30; 0 keeps every run.
@pallaoro
pallaoro merged commit 88f7de5 into main Sep 25, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant