Run-scoped control API after lifecycle v1

[stainlu]

opening the follow-up from #91 now that the v1 run lifecycle shipped.

imo the next control surface should stay run-scoped, not agent-scoped.

what exists now:

• every invocation has runId
• run_start / run_end + monotonic events
• durable run/event history on CF, in-memory on Node
• prompt / skill / task / shell have local CallHandle abort via AbortSignal
• flue logs can replay/tail a known run

missing bridge: once a webhook run is accepted, external code can observe it, but cannot ask the active run to stop.

rough v1 shape i would consider:

1. add an isolate-local active run registry: runId -> AbortController
2. expose the active run signal to the handler, maybe ctx.signal
3. compose that signal into prompt / skill / task / shell calls by default, while still respecting caller-provided options.signal
4. add POST /agents/:name/:id/runs/:runId/abort with optional { reason }
5. endpoint returns something like:
   • 202/200 when abort was requested
   • 404 when the run id does not belong to this agent/id
   • 409 when the run is already terminal
   • maybe 409/503 when the run is known active in the store but no live controller exists in this isolate

what i would not include yet:

• list-runs endpoint
• dashboard/admin API
• SIGTERM / pause / resume / agent state machine
• cross-agent orchestration

that keeps the model pretty clean:

• Session = durable conversation state
• Run = observable execution record
• AbortSignal = stop this active execution
• future admin API = can build on top once this primitive is real

this also seems like the right substrate for external managed-agent layers: they do not need Flue to become the managed-agent control plane, but they do need a reliable way to target and stop an active run.

question: does this feel like the right next v1 slice? or should the first PR only add ctx.signal + active run registry, and leave the HTTP abort endpoint for a second PR?

[stainlu]

after catching up with 0.6.x / #130, i think this can be narrower now.

run listing / lookup / admin inspection exists. the missing bridge is basically: does an active run have a live abort controller?

i’d probably split active abort into two layers:

• runtime-local: runId -> AbortController, expose ctx.signal, and compose that signal into prompt / skill / task / shell defaults
• HTTP/admin: later endpoint calls that local control path only if the run is actually live in this runtime

then endpoint semantics can stay honest:

• queued run: cancel from the scheduler / registry before it starts
• active run in this runtime: abort the controller
• terminal run: 409
• registry says active, but no live controller here: 409/503, not pretend success

one question: does abort introduce cancelled as a terminal run status? imo yes. otherwise user-requested stop and real failure both collapse into errored, which weakens run inspection.

i still would not put pause/resume/signal-state-machine in this first slice. just make “stop this run” real.