Feature discussion: first-class Pursue Goal mode for long-running agent work

[jongan69]

Summary

Odysseus already has several pieces that make longer agent work possible: stream_agent_loop can run multi-round tool use, detached runs can survive a tab disconnect, background shell jobs can auto-continue after completion, and scheduled tasks can run prompts in the background.

What it does not appear to have as a first-class product/API concept is a durable Pursue Goal mode: start with an objective, keep working through bounded continuations, and only stop when the goal is complete, blocked, cancelled, or out of budget.

This discussion is meant to align on the shape of that feature before it becomes a large implementation.

Related work

• Draft PR: [codex] Add persistent agent goals #2457 ([codex] Add persistent agent goals)
• HITL / loop-safety concern: Need HITL (Human-in-the-loop) in stream_agent_loop to prevent infinite error loops with fast models #3436
• Mobile companion context: Odysseus mobile companion app: React Native, private pairing, and App Store path #3403
• Companion backend PR: feat(companion): implement backend-only chat scope and command contract #3400

The intent here is not to expand #3400. The companion/mobile work can consume a future goal API, but the goal runner should be designed as a core Odysseus capability first.

Proposed capability

Add an opt-in Pursue Goal layer around the existing agent loop.

A goal would have a persisted lifecycle, for example:

• active: the agent is allowed to keep working within configured limits
• waiting_for_user: the agent needs a human decision or approval
• blocked: the same blocker repeated and the agent cannot make useful progress
• complete: success criteria were satisfied
• cancelled: stopped by the user
• exhausted: budget, round, wall-clock, or tool-call cap reached

The key distinction from a normal agent turn is that completion is not just “the model stopped streaming.” The runner should explicitly decide whether the objective is complete, still needs another continuation, or is blocked.

Possible implementation outline

• Persist a goal record per owner/session: objective, status, budget, timestamps, latest blocker, usage, and current run id.
• Reuse existing primitives where possible:
  • stream_agent_loop for actual tool-using work
  • agent_runs for detached stream/reconnect behavior
  • bg_jobs for long shell jobs that should resume the objective after completion
  • existing verifier / loop-breaker logic for completion checks and runaway protection
• Add a small supervisor that starts a normal agent turn, inspects the result/events, and decides whether to continue, pause for HITL, or mark terminal.
• Surface status and control endpoints: start, status, pause, resume, cancel, and maybe “continue once.”
• Add UI affordances separate from regular chat send: “Pursue goal,” status timeline, stop/pause controls, and reason for blocked/exhausted states.
• Eventually expose the capability in the companion manifest so mobile clients can start/resume/stop goals without inventing a second workflow.

Safety boundaries

This should not be an infinite loop or a raw remote-control surface.

Suggested guardrails:

• Default off / explicit opt-in per goal.
• Per-goal max continuations, max tool calls, max wall-clock time, and token budget.
• Clear HITL gates for destructive operations, auth-sensitive actions, or repeated failures.
• Preserve existing owner scoping and tool policy gates.
• Do not expand raw shell authority as part of this feature.
• If the agent hits the same blocker repeatedly, mark blocked instead of continuing forever.

Acceptance criteria

A minimal acceptable version might be:

1. User can create a goal from the UI or API with an objective and optional budget.
2. The server persists the goal and exposes current status.
3. The runner can continue across at least one bounded follow-up without requiring the user to manually click Continue.
4. A browser disconnect does not kill the goal run.
5. The goal enters a terminal state (complete, blocked, cancelled, or exhausted) with a human-readable reason.
6. Existing chat/agent behavior remains unchanged unless Pursue Goal is explicitly selected.
7. Tests cover owner scoping, round/budget exhaustion, cancellation, repeated blocker handling, and background-job follow-up.

Open questions

• Should [codex] Add persistent agent goals #2457 be revived as the base, or is it better to split the work into a smaller core runner first?
• Should goals be session-scoped only, or can a goal span child sessions / background sessions?
• What is the right default cap: continuations, time, tool calls, or all three?
• Should completion verification be model-based, rule/event-based, or both?
• How much should the mobile companion API expose in the first pass: status only, or full start/resume/cancel?
• What should require human confirmation before the runner continues?

[jongan69]

Scope/alignment note with #3163: this is feature-planning for a future core capability, not my proposed Stabilization v1 item.

I do not want this discussion used to widen #3400 or to turn the current stabilization lane into a broad mobile/agent feature epic. If this moves forward, it should be after stabilization as a narrow accepted plan for a core goal runner, with companion/mobile consumption following that core design.