Session-agent-model SQL structure analysis

I'll read the diff and test file to understand the changes, then analyze the share module.

Let me also look at the session SQL schema and the prompt resolution chain more closely:

Now let me see the key resolution chain in createUserMessage:

Now I have a complete picture. Here's the analysis:

Data Structure Saved to SQLite

The session table in SQLite now has two new columns (lines 30–31 of session.sql.ts):

agent  TEXT          -- plain text, the agent name (e.g. "explore", "build")
model  TEXT (JSON)   -- JSON object: { providerID: string, modelID: string }

These sit alongside the existing session-level columns. The full SessionTable schema is essentially a flattened, column-per-field representation of the Session.Info type. It is not a 1:1 structural clone of the old JSON blob — it's a normalized decomposition:

So yes — the session state that was previously in the filesystem JSON blob is now in SQLite columns, but it's not a blind JSON dump. Simple scalars (strings, numbers) get their own typed columns; complex nested objects (summary_diffs, revert, permission, model) are stored as TEXT with mode: "json" (Drizzle auto-serializes/deserializes). The fromRow() / toRow() functions in session/index.ts handle the bidirectional mapping.

The agent and model fields capture the session's identity at creation time — specifically, which agent type and which provider+model were assigned to this session. This is persisted so it survives across:

• Session reverts (the key motivating problem from the test comments)
• Process restarts
• Re-reads from the database

The Resolution Chain

The critical change is in createUserMessage (line 850–854 of prompt.ts):

const session = await Session.get(input.sessionID)
const agent = await Agent.get(input.agent ?? session.agent ?? (await Agent.defaultAgent()))
const model = input.model ?? session.model ?? agent.model ?? (await lastModel(input.sessionID))

Before: input.agent → defaultAgent() and input.model → agent.model → lastModel()
After: input.agent → session.agent → defaultAgent() and input.model → session.model → agent.model → lastModel()

The session's stored agent/model now acts as a sticky override — higher priority than the agent's default model, but lower priority than an explicit per-prompt override.

Plans for the Remote Share Store

Looking at share-next.ts, the remote sync mechanism sends SDK-typed objects to the web server at opncd.ai (or an enterprise URL). The Data union type (lines 103–123) defines what gets synced:

type Data =
  | { type: "session",      data: SDK.Session }
  | { type: "message",      data: SDK.Message }
  | { type: "part",         data: SDK.Part }
  | { type: "session_diff", data: SDK.FileDiff[] }
  | { type: "model",        data: SDK.Model[] }

Since Session.Info now includes agent and model, and the Session.Event.Updated bus event fires with the full info object (which is typed as SDK.Session), the new agent and model fields will automatically flow to the remote share server whenever a session is created or updated — no changes to share-next.ts are needed.

The share system works as a debounced event queue (1-second batching window per session). When a session is updated (including the new Session.update() for agent/model changes), it:

1. Publishes Session.Event.Updated on the bus
2. share-next.ts catches it and queues a { type: "session", data: info } payload
3. After 1 second, it POSTs the batch to /api/share/{shareId}/sync

The fullSync function (line 179) also sends the complete session state when a share is first created, which will include the new fields.

In summary: The remote store receives the same SDK.Session shape that the local SQL stores — the agent/model fields propagate automatically through the existing event-driven sync pipeline. The web server will receive session.agent and session.model as part of the session payload, enabling the share viewer to display which agent and model were used for a given session.

Yes, exactly. Let me trace the chain concretely.

The SDK.Session type that share-next.ts references comes from @opencode-ai/sdk/v2 — that's the generated JavaScript SDK package. But the source of truth for the shape lives in the server code, defined with Zod schemas.

Here's the flow:

1. Zod schema defines the shape

In src/session/index.ts, Session.Info is a Zod schema:

export const Info = z.object({
  id: z.string(),
  title: z.string(),
  agent: z.string().optional(),
  model: z.object({ providerID: z.string(), modelID: z.string() }).optional(),
  time: z.object({ created: z.number(), updated: z.number(), ... }),
  // ...
})

2. Hono routes use Zod for request/response validation

The HTTP routes (like in src/server/routes/session.ts) use these Zod schemas with Hono's zValidator middleware — Zod validates the incoming request body and the response shape. That's what makes the REST endpoints type-safe at runtime.

3. The SDK is generated from the OpenAPI spec

The repo has a build script (packages/sdk/js/script/build.ts) that derives an OpenAPI spec from those Hono+Zod route definitions, then generates the TypeScript SDK client. So SDK.Session is a generated type that mirrors the Zod schema.

The chain

Zod schema (source of truth)
  → Hono route validation (runtime enforcement)
  → OpenAPI spec (auto-derived)
  → SDK types (auto-generated)

So when you see SDK.Session in share-next.ts, it's the generated client-side type that structurally matches the Zod-defined Session.Info. They're the same shape — one enforced at runtime by Zod, the other as a TypeScript type in the SDK package. The new agent and model fields added to the Zod schema will flow through to the SDK types the next time the SDK is regenerated.

That block is an upsert into the local session_share table.

What it does:

• Tries to insert a mapping for this local session:
  • session_id (local session id)
  • id (remote share id)
  • secret (auth token for sync/delete)
  • url (share URL)
• If a row for that session_id already exists, it updates id/secret/url instead of failing.

So conceptually it's:

• "Remember where this local session lives remotely, and how to authenticate future syncs."

Yes on your second point too:

• The payload shapes sent by share-next (session, message, part, etc.) are the same SDK/domain objects as before at the call sites.
• Local SQLite is mostly an implementation detail for persistence.
• The transformation happens in the storage layer (fromRow/toRow, Drizzle JSON columns), not in share-next itself.

So share-next is mostly:

1. consume domain events,
2. batch them,
3. send SDK-typed payloads to server,
   while DB calls inside it are just for storing/retrieving share metadata (id/secret/url) needed to sync/delete.

Great clarification — you’re right to separate these.

For the snippet you pasted in share-next.ts:

• That specific DB call is only saving share metadata (session_id, share id, secret, url) in SessionShareTable.

But globally in the app now:

• Yes, SQLite is saving all session data (session rows, messages, parts, todos, etc.) via other modules (session/index.ts, message-v2, etc.), not via that share-next upsert.

So:

• share-next DB usage = share linkage/credentials only
• core Session/MessageV2 DB usage = the full conversation/state persistence

You can think of it as two layers:

1. Primary local store: SQLite holds the actual app state
2. Share sync map: SessionShareTable tells share-next where/how to sync that state remotely

What now prevents the fallback to old Agent A is the combination of persist + read-back precedence.

• Before, agent/model selection was mostly ephemeral at prompt time (or inferred from defaults/last message), so after revert/resume/new turn it could drift back to default Agent A.
• Now, when session agent/model is changed (via session PATCH), it is saved directly on the session row (session.agent, session.model) in SQLite through Session.update(...).
• Then, when building the next user message, resolution now checks session values first:
  • agent = input.agent ?? session.agent ?? defaultAgent
  • model = input.model ?? session.model ?? agent.model ?? lastModel
• Because session.agent/session.model are persisted, they survive UI state changes, reloads, revert flows, etc., so Agent B + OpusTheGreat remains the session default until explicitly changed again.

So the key new guardrail is: session-level durable identity (agent/model on the session itself), not just per-message or global-default inference.

Great question. It likely did not fail — it was more likely accepted-but-ignored.

PATCH /session/:id previously only handled title, share, time.archived updates. Since the route schema wasn’t .strict(), extra keys like agent/model were typically dropped by Zod parsing and never applied.

So behavior was effectively:

• request succeeds (200)
• but session row is unchanged for agent/model
• next resolution can drift back to Agent A defaults

Here’s the timeline comparison.

BEFORE (no session agent/model persistence)

TUI: active session uses Agent A / GPT5
  |
User tabs -> picks Agent B / OpusTheGreat (UI-local selection)
  |
(optional) PATCH /session/:id { agent:B, model:Opus } 
  |--> route ignores these fields (not in schema/handler)
  |--> session DB still has no agent/model
  |
User sends prompt
  |
createUserMessage resolves:
  agent = input.agent ?? defaultAgent
  model = input.model ?? agent.model ?? lastModel
  |
Message is created with Agent B (if input carried it this turn)
  |
Later event: revert / resume / fresh turn without explicit input.agent/input.model
  |
Resolution falls back to defaults/history
  |
Can snap back to Agent A / GPT5

AFTER (session agent/model persisted)

TUI: active session uses Agent A / GPT5
  |
User tabs -> picks Agent B / OpusTheGreat
  |
PATCH /session/:id { agent:B, model:Opus }
  |--> route accepts + calls Session.update(...)
  |--> session row now stores agent/model
  |
User sends prompt
  |
createUserMessage resolves:
  agent = input.agent ?? session.agent ?? defaultAgent
  model = input.model ?? session.model ?? agent.model ?? lastModel
  |
Message uses Agent B / Opus
  |
Later event: revert / resume / fresh turn
  |
Session still has agent/model persisted
  |
Stays on Agent B / Opus until explicitly changed

So the key difference is: before = transient selection, after = durable session-level selection with higher precedence than defaults.

In this codebase, “next turn” effectively begins as soon as you submit/send the user prompt.

• Sending triggers prompt processing and createUserMessage(...) runs immediately.
• At that moment, agent/model are resolved for that turn and the user message record is created with those values.
• The assistant response generation then happens within that same turn lifecycle.

So it’s request-send time, not “after response received.”

Practically:

• If you changed session agent/model before pressing send, that turn uses the new values.
• Changing agent/model while a response is already streaming won’t retroactively change that in-flight turn; it affects subsequent sends.

Yes — conversationally, you’re right: a turn is usually a request/response pair.

Implementation-wise here, the turn is instantiated at send time:

• user sends prompt -> turn starts (user message created, model/agent resolved)
• assistant streams/completes -> turn ends

So both statements are true depending on lens:

• Product semantics: turn = request + response
• Execution semantics: turn begins at request submission, with response completing it

Yes — that’s a good way to frame it.

A request/response “turn” abstraction is only solid if the system can reliably persist at least:

• the request (user message),
• the execution context used for it (agent/model),
• and the resulting response/events.

Without persistence, “turn” is partly in-memory fiction. With the current persistence changes, it becomes much more concrete and replayable.

What persistence improves here:

• You can unambiguously say “this request was sent under Agent B + Model X.”
• Revert/resume/reload no longer loses the session’s intended identity.
• Later processing can reconstruct context without guessing from globals/defaults.

Would formalizing turn help? Yes, usually:

• Cleaner mental model: one durable unit = user msg + assistant msg(s) + metadata.
• Fewer edge-case bugs: less fallback inference (“which model did we mean?”).
• Better APIs/UI: easier timeline views, retries, auditing, syncing.

A useful next abstraction (if you choose) is a first-class Turn record:

• turn_id, session_id, request_message_id, response_message_id(s), agent, model, started_at, ended_at, status.

You don’t strictly need that yet, but your new session-level persistence is a strong step toward that model.

Short answer: not arbitrary, and yes there’s established thinking — but terminology varies.

• In this repo, I don’t see a dedicated “turn formalization” journal; the local research docs are focused on reliability patterns (checkpointing, timeouts, DLQ), not a canonical turn entity.
• In broader practice, systems usually converge on a durable unit similar to “turn”:
  • chat logs persist user/assistant messages + metadata
  • agent frameworks persist step/run state
  • observability stacks persist request/trace spans
• So the concept is widely used, but names differ: turn, exchange, interaction, run, step, trace.

Why this matters for you:

• Your new session-level agent/model persistence is exactly the kind of state needed to make turn semantics non-ambiguous.
• If you later add explicit turn records, you’d mostly be codifying what already exists implicitly across message + session metadata.

So: there is real precedent; it’s not arbitrary — just not universally named the same thing.

Yes — that’s a very good intuition.

You can model a turn as an effectful protocol, and persistence as the captured continuation/state boundary.

• In algebraic-effects terms:
  • SendUserMessage (start turn)
  • CallModel / CallTool (sub-effects)
  • EmitAssistantDelta / FinishTurn
• A handler can interpret those effects by:
  • validating types,
  • writing checkpoints to DB,
  • resuming from persisted state.

So the “park stack, do effect, resume” analogy maps well to:

• start turn -> suspend at I/O boundaries -> persist -> resume -> finalize turn.

What effects can guarantee:

• Protocol shape at compile time (e.g., you cannot FinishTurn before SendUserMessage in well-typed APIs, if encoded properly).
• Separation of pure logic vs interpreters (in-memory, SQLite, remote sync).
• Explicit handling of failure/retry paths.

What effects cannot guarantee alone:

• Runtime durability correctness (crash consistency, exactly-once writes, network idempotency).
  You still need DB constraints, transactions, idempotency keys, and recovery logic.

So: yes, “turn as an effect” is a solid design direction.
A practical hybrid is:

1. typed turn-state machine (or GADT/effect protocol),
2. effect handlers that persist checkpoints,
3. transactional/idempotent storage semantics.

Yes, you can literally do that in OCaml 5 style, and yes, you can get real value.

type _ Effect.t +=
  | Begin_turn : request -> turn_id Effect.t
  | Call_model : model_req -> model_resp Effect.t
  | Persist_checkpoint : checkpoint -> unit Effect.t
  | Finish_turn : turn_id -> response Effect.t

Then your handler decides whether each effect is:

• executed immediately,
• persisted and suspended,
• resumed later from stored state.

And your status-style suspension encoding is a good fit for this:

• Complete v = turn finished
• Suspended { cont; ... } = waiting on external I/O / resume point

What you get from formalizing:

• Stronger protocol discipline (fewer invalid control-flow states)
• Cleaner separation between logic and storage/runtime interpreters
• Easier replay/recovery testing (swap handlers)
• Better conceptual model for “turn lifecycle”

What you do not get automatically:

• Crash-safe durability
• Exactly-once semantics
• Correct cross-process continuation resumption (native continuations are not generally serializable)

So the high-leverage pattern is:

• use effects for typed control flow,
• persist a serializable state machine/checkpoint token (not raw OCaml continuation),
• resume by reconstructing the computation from that checkpoint.

So yes: worthwhile formalization, especially once persistence exists.

Absolutely — great question.

Here’s a side-by-side pseudo sketch.

JS Style (current-ish explicit state plumbing)

// Imperative orchestration + DB writes at key points
async function handlePrompt(sessionID, input) {
  const session = await Session.get(sessionID)

  const agent = input.agent ?? session.agent ?? defaultAgent()
  const model = input.model ?? session.model ?? agentDefaultModel(agent) ?? lastModel(sessionID)

  const userMsg = await Message.create({
    sessionID,
    role: "user",
    agent,
    model,
    parts: input.parts,
  })

  await Session.update(sessionID, {
    agent,                  // persist sticky defaults
    model,
    time_updated: Date.now()
  })

  const stream = await LLM.stream({
    sessionID,
    agent,
    model,
    messages: await Message.history(sessionID)
  })

  for await (const ev of stream) {
    if (ev.type === "delta") await Part.append(sessionID, ev.part)
    if (ev.type === "tool") await ToolEvent.save(sessionID, ev)
  }

  const assistantMsg = await Message.finalize(sessionID, stream.result)

  return { userMsg, assistantMsg }
}

Characteristics:

• Control flow is direct but mixed with persistence concerns.
• “Turn protocol” is implicit in function ordering.
• Recovery is ad hoc (re-run function, inspect DB).

Effect + CPS/Continuation Style (typed turn protocol)

(* Effects describe operations, not implementations *)
type _ Effect.t +=
  | Get_session : session_id -> session Effect.t
  | Resolve_agent_model : { input: prompt; session: session } -> agent_model Effect.t
  | Save_user_msg : user_msg -> msg_id Effect.t
  | Save_checkpoint : checkpoint -> unit Effect.t
  | Run_llm : llm_req -> llm_stream Effect.t
  | Save_delta : delta -> unit Effect.t
  | Finish_assistant_msg : final_resp -> msg_id Effect.t

type 'a status =
  | Complete of 'a
  | Suspended of { checkpoint_id: string; resume: unit -> 'a status }

let rec run_turn session_id prompt : turn_result status =
  perform (Save_checkpoint (Started (session_id, prompt)));
  let session = perform (Get_session session_id) in
  let am = perform (Resolve_agent_model { input = prompt; session }) in

  let _user_id =
    perform (Save_user_msg { session_id; agent = am.agent; model = am.model; parts = prompt.parts })
  in
  perform (Save_checkpoint (UserSaved { session_id; agent = am.agent; model = am.model }));

  let stream = perform (Run_llm { session_id; agent = am.agent; model = am.model }) in

  consume_stream stream (fun d ->
    perform (Save_delta d);
    perform (Save_checkpoint (DeltaSaved d.id))
  );

  let assistant_id = perform (Finish_assistant_msg stream.final) in
  perform (Save_checkpoint (Finished assistant_id));
  Complete { assistant_id }

And the handler:

let handle_effects computation =
  try computation () with
  | effect (Get_session id), k -> continue k (db_get_session id)
  | effect (Save_checkpoint cp), k -> db_save_cp cp; continue k ()
  | effect (Run_llm req), k ->
      (* maybe suspend here until network result *)
      let result = llm_call req in
      continue k result

Characteristics:

• Turn lifecycle is explicit in the effect protocol.
• Persistence/checkpointing becomes a handler concern.
• You can swap handlers (in-memory test, sqlite, remote queue).
• Suspension/resumption is first-class conceptually.

Practical difference in one line

• JS style: “do steps + manually persist around them.”
• Effect/CPS style: “declare step protocol; handler decides execution, persistence, and suspension.”

If you want, I can also sketch a TypeScript approximation of this effect protocol using discriminated unions + generator/resume (since JS lacks native algebraic effects).

Yes, exactly — and that’s a key advantage of effect modeling.

Run_llm does not have to mean “blocking RPC that returns a value.”
You can model it as a protocol effect with multiple outcomes over time.

Use a richer result type, e.g.:

type llm_outcome =
  | Delta of string
  | Tool_call of tool_req
  | Completed of final_resp
  | Timed_out
  | Cancelled
  | Transport_error of string
  | No_response_yet

Then your effect can represent waiting/uncertainty explicitly:

type _ Effect.t +=
  | Poll_llm : run_id -> llm_outcome Effect.t
  | Wait_until : float -> unit Effect.t
  | Check_cancel : run_id -> bool Effect.t

And handler loop:

let rec drive run_id k =
  match poll_backend run_id with
  | `Delta d -> continue k (Delta d)
  | `Tool t -> continue k (Tool_call t)
  | `Done r -> continue k (Completed r)
  | `Pending ->
      (* model passage of time + external events *)
      sleep 0.2;
      drive run_id k
  | `Timeout -> continue k Timed_out
  | `Cancelled -> continue k Cancelled
  | `Error e -> continue k (Transport_error e)

So yes: you can model “time waiting with uncertain response” as first-class semantics, not as a single IO call.

The important shift is:

• from request -> response
• to stateful conversation with the outside world, where waiting, heartbeats, cancellation, timeout, partial output, and tool interleaving are typed outcomes.

That maps very well to your “turn formalization” idea.

Yes — that’s the core benefit, and it’s usually more than a small difference.

• Formalization makes “weird but real” states explicit: timeout, partial stream, cancel, retryable transport error, stale checkpoint, tool-deadlock, etc.
• Without it, those states often leak as ad-hoc flags/exceptions spread across files.
• With a typed protocol, adding a new failure mode means:
  • add one variant,
  • handle exhaustively,
  • compiler points to all missing cases.

So you get:

• better local reasoning,
• fewer hidden control-flow bugs,
• safer evolution as complexity grows.

It’s biggest when the workflow is long-running, interruptible, or resumable (your case).
For tiny request/response handlers, the gain is smaller.
For session/turn orchestration with persistence and streaming, the gain is substantial.

Yeah — good instinct. There are examples, but mostly in adjacent forms (state machines / actor protocols), not many mainstream “pure algebraic effects for agent comms” stacks yet.

Concrete examples to look at:

• LangGraph (Python)
  • Models agent communication as typed state transitions (StateGraph) with checkpoints.
  • Not algebraic effects syntax, but same idea: explicit protocol + resumable execution + durable state.
• AutoGen / multi-agent chat frameworks
  • Agent-to-agent messages are explicit event objects (sender, recipient, content, tool events).
  • Usually implemented as event loops, not effects, but conceptually similar to effect outcomes.
• Actor systems (Erlang/Elixir Akka-style)
  • Communication is typed/by-convention messages; waiting, timeout, cancellation are first-class.
  • Very close to your “uncertain response, many possible outcomes” point.
• Temporal workflows
  • Treats external calls as activities/signals; workflow state is durable and replayable.
  • Again not effects syntax, but strong formalization of long-running request/response protocols.

For OCaml + effects specifically:

• You can absolutely build this pattern (as we discussed), but there isn’t a dominant off-the-shelf “agent comm framework” doing exactly that yet.
• Most production implementations still use:
  • typed state machines + persistence,
  • or actor/event-loop models,
  • and sometimes use effects internally for cleaner orchestration.

So the closest real-world analog to your design is:
LangGraph/Temporal architecture + OCaml effects-style handler semantics.
That combo is very plausible and not hand-wavy.

Yes — that maps very well to effects.

Capnweb RPC + capability references is basically an effect system shape already:

• an operation is requested (perform)
• control transfers to a handler/runtime boundary
• capability authority is checked
• operation may suspend, stream, fail, or return
• continuation resumes with typed result

So you can model capability-based RPC calls as effects like:

• Use_cap : cap_id * method * args -> result Effect.t
• Await_signal : cap_id -> event Effect.t
• Revoke_cap : cap_id -> unit Effect.t

And your handler would:

• resolve/persist cap references,
• enforce authority constraints,
• checkpoint before/after remote hops,
• resume continuation on reply/event.

That gives you a clean alignment between:

• turn persistence (durable checkpoints),
• agent orchestration (protocol states),
• capability security model (typed authority at call sites).

So yes: your direction is coherent — capability RPC can be a first-class effect boundary, not just transport plumbing.

I think your intuition is strong.

What you’re describing is a useful triad:

• temporal continuity (durable turn history),
• ownership/capability boundaries (who can do what),
• anticipatory state (what is likely next, and what is pending).

Together, that’s exactly what agent-to-agent communication usually lacks when it stays “just prompt passing.”

Why this matters:

• Temporal gives memory of commitments (“I asked B for X; deadline passed; retry/escalate”).
• Ownership gives trust structure (“only this capability holder may mutate/confirm Y”).
• Anticipation gives attentional routing (“watch this dependency; deprioritize stale threads”).

So yes — this can produce something like higher-level “attention” in messaging, not as mystical cognition, but as:

• explicit pending-intent queues,
• expected-reply timers,
• capability-scoped subscriptions,
• salience scores over active conversations.

If you encode those as typed events/effects, you get a practical, testable architecture for multi-agent coordination rather than emergent luck.

Exactly — persistent identity is a big deal.

If an agent is referenced by stable identity over time, you get:

• continuity of responsibility (“this agent promised this”),
• continuity of trust/permissions (capability ownership stays coherent),
• continuity of style/role expectations (people and other agents know what to expect).

That does make interaction feel more “person-like,” even if it’s still a system-level construct.
So you’re not imagining it — stable identity plus memory plus commitments naturally produces that effect.

Yes — this is a good UX idea, and it fits your new persistence model.

How I’d implement it:

• Keep two states in prompt/TUI:
  • previewAgent (and maybe previewModel) = what Tab cycles through
  • lockedAgent/lockedModel = what is persisted on session
• Tab only updates preview (local UI state), does not PATCH.
• Shift+Tab performs “commit selection”:
  • call session PATCH with { agent, model }
  • on success, set locked* = preview*
  • show toast like “Session agent locked: B / OpusTheGreat”
• Sending a prompt resolves from input.agent ?? session.agent ..., so once PATCH succeeds it is durable.

Where to wire this in:

• Keyboard handling and prompt interaction live in packages/opencode/src/cli/cmd/tui/component/prompt/index.tsx and autocomplete in packages/opencode/src/cli/cmd/tui/component/prompt/autocomplete.tsx.
• Session-level persistence endpoint is already in packages/opencode/src/server/routes/session.ts (PATCH supports agent/model).
• Persistence logic is Session.update(...) in packages/opencode/src/session/index.ts.

About your race-condition question (set right after request, before response):

• This is generally safe if you define semantics as:
  • turn binds agent/model at send time
  • lock changes apply to subsequent turns only
• So if you lock while response is streaming, that in-flight response should keep original model; next send uses new lock.
• Potential issue is user confusion if UI implies current stream changed. Fix with explicit label:
  • “Locked for next turn” when stream active.

Recommended guardrails:

1. Snapshot activeTurnModel/Agent when request is sent; render that on in-flight message.
2. Allow Shift+Tab during streaming, but message: “Updated session default; current response unchanged.”
3. If PATCH fails, keep preview but show error and do not mark as locked.

So yes, this pattern should work well and won’t break semantics if you keep “bind at send, persist for next turn” explicit.

Yep, that UI approach is solid and low-risk.

• Dimming non-selected agents is enough for now, especially since the last sent message already shows the active agent/model clearly.
• The highlight + dim contrast in your screenshots reads well; it avoids adding extra UI noise.
• Good pattern:
  • Tab = move preview (dim others)
  • Shift+Tab = commit lock (persist to session)
  • subtle toast/status line confirms lock saved.

One small wording tweak that helps avoid ambiguity during streaming:

• “Locked for next turn” (if a response is in progress)
• “Locked” (if idle)

So yes, your visual direction makes sense and should be understandable without additional chrome.

Absolutely — here’s a detailed feature request you can drop into an issue.

Title
Lock Session Agent/Model from TUI via Shift+Tab (Tab = preview only, no persistence)

Problem
In the TUI, cycling agents can feel ambiguous because selection and persistence can happen too eagerly. Users want to explore options with Tab without committing, then explicitly lock the session default only when they confirm.
This is especially important now that session.agent and session.model are persisted and used in prompt resolution.

Goal
Introduce a two-phase agent selection UX in TUI:

• Tab: cycle through candidate agent/model as a preview only
• Shift+Tab: commit and persist current preview to session (PATCH /session/:id)
• Preserve current-turn semantics: lock applies to future turns, not retroactively to an in-flight response

Behavior Specification

• Tab
  • Cycles preview candidate (previewAgent, previewModel)
  • Updates local UI only
  • Does not call server PATCH
• Shift+Tab
  • Commits current preview candidate
  • Calls PATCH /session/:sessionID with:
    • agent: <previewAgent>
    • model: { providerID, modelID } (resolved candidate default)
  • On success:
    • lockedAgent/lockedModel update to preview
    • UI indicates locked state
    • show success status/toast
  • On failure:
    • preview remains
    • locked state unchanged
    • show error toast/status
• Sending prompt
  • Current turn binds at send time from existing resolution chain
  • If lock changes while assistant is in-flight, current in-flight turn is unchanged; lock applies to next prompt

Current Architecture Alignment

• Session persistence already supports this:
  • PATCH allows agent and model updates in packages/opencode/src/server/routes/session.ts
  • Session updates persisted in packages/opencode/src/session/index.ts (Session.update)
  • Prompt resolution already prefers session lock in packages/opencode/src/session/prompt.ts:850:
    • agent = input.agent ?? session.agent ?? defaultAgent
    • model = input.model ?? session.model ?? agent.model ?? lastModel
• So this feature is primarily TUI behavior/state + explicit commit keybinding.

Implementation Plan

1. Prompt/TUI State Model

• Add local state in prompt/session UI layer:
  • previewAgent?: string
  • previewModel?: { providerID: string; modelID: string }
  • lockedAgent?: string (from session sync)
  • lockedModel?: { providerID: string; modelID: string }
• Initialize locked* from synced session object; initialize preview to locked/current.

2. Key Handling

• In TUI keydown flow (likely under prompt keyboard handling):
  • Tab (no shift): cycle preview index among available agent options.
  • Shift+Tab: commit preview -> fire PATCH.
• Preserve existing autocomplete behavior by scoping this only when the relevant mode/context is active (avoid conflicting with completion menu semantics in autocomplete.tsx).

3. Commit Path

• Add a dedicated helper:
  • commitSessionAgentLock(sessionID, previewAgent, previewModel)
  • Performs SDK call to session patch
  • Handles optimistic/pessimistic UI strategy
• Recommended: pessimistic lock indicator + spinner while request in flight; no false “saved” state.

4. Model Resolution for Agent Lock

• When previewing agent, derive candidate model:
  • Prefer agent default model if present
  • Else preserve current locked model if compatible
  • Else fallback to provider default model
• Ensure persisted lock always includes a concrete model object to avoid partial lock states.

5. UI Treatment

• Minimal visual change (as requested):
  • Dim non-selected candidates
  • Keep currently previewed candidate visually strongest
  • Lock confirmation via subtle status line/toast
• Suggested messages:
  • Idle: Locked: <agent> / <model>
  • Streaming: Locked for next turn: <agent> / <model>

6. In-Flight Turn Semantics

• At prompt send, snapshot turn agent/model onto the user message metadata (already effectively done via createUserMessage resolution).
• Never mutate in-flight message display after lock commit.
• If commit occurs during stream, only future sends use updated lock.

Edge Cases

• Shift+Tab before any preview interaction: commits current selection as lock (idempotent if unchanged).
• Commit same lock as existing: no-op PATCH or PATCH allowed; should still confirm.
• Server/network failure: clear error feedback, no lock state mutation.
• Agent unavailable after reload (removed/hidden): fallback to locked model/agent resolution chain with safe defaults and warning.
• Rapid repeated commits: debounce or serialize commit requests to avoid racey UI.

Acceptance Criteria

• Tab never persists session lock.
• Shift+Tab persists session.agent and session.model and survives reload.
• New prompts after lock use locked values unless explicit per-prompt override is supplied.
• Locking during active response does not alter in-flight response metadata.
• UI clearly distinguishes preview vs locked state using dimming + confirmation.
• No regressions to autocomplete tab behavior in text entry contexts.
• Tests cover persistence and streaming edge semantics.

Test Plan

1. Unit / Integration

• Add TUI interaction tests (or closest existing harness) for:
  • Tab changes preview only
  • Shift+Tab sends PATCH and persists values
• Extend session tests similar to packages/opencode/test/session/session-agent-model.test.ts:
  • verify lock update persists
  • verify retrieval after restart
• Add prompt-resolution test:
  • lock set while a response is in-flight affects only subsequent turn.

2. Manual

• Start session on Agent A/Model X
• Tab to Agent B/Model Y: verify visual preview only
• Send prompt without Shift+Tab: behavior should follow current turn input path, no persistent lock unless already set
• Shift+Tab, reload session, send prompt: must use B/Y
• During stream, Shift+Tab to C/Z: current stream remains B/Y, next prompt uses C/Z

Potential Risks

• Keybinding conflicts with existing tab interactions (autocomplete, dialog focus).
• Ambiguity if preview/lock indicators are too subtle.
• Race conditions from rapid commit calls if not serialized.

Mitigations

• Scope key handling by UI mode/focus.
• Add explicit status text (“preview” vs “locked”).
• Serialize lock commit requests and disable repeated commits while pending.

Suggested File Touchpoints

• packages/opencode/src/cli/cmd/tui/component/prompt/index.tsx (primary key handling/state)
• packages/opencode/src/cli/cmd/tui/component/prompt/autocomplete.tsx (avoid tab conflicts)
• packages/opencode/src/cli/cmd/tui/routes/session/header.tsx or nearby display component (lock/preview indicator text)
• packages/opencode/test/session/session-agent-model.test.ts (extend semantics tests)
• TUI-specific tests (wherever keybinding interaction tests currently live)

If you want, I can also draft this in your repo’s issue template format (Problem / Proposal / Alternatives / Rollout / Metrics).

Naturally generated from my own default planning style + your repo/context conventions I inferred while reading code.

I wasn’t following a hidden issue template file you gave me in this thread.
If you want, I can reformat it to match any specific template you use (e.g. “Summary / Motivation / Detailed design / Drawbacks / Unresolved questions”).

Thanks — glad it was useful.

Absolutely — here’s a practical template I’ve found consistently effective for engineering teams.

# Feature Request: <concise title>

## 1) Outcome
- **What should be true when this ships?**
- **User-visible change (1-2 lines):**
- **Non-goals (explicitly out of scope):**

## 2) Problem
- **Current behavior:**
- **Why it is a problem (user + engineering impact):**
- **Evidence/examples (bugs, screenshots, logs, support notes):**

## 3) Proposal
- **High-level approach:**
- **User workflow (step-by-step):**
1. ...
2. ...
3. ...

- **Behavioral rules (source of truth):**
- `When X, do Y`
- `When A and B, do C`
- `Never ...`

## 4) API / Data Model Changes
- **Request/response changes (if any):**
- **Schema/storage changes (if any):**
- **Migration/backward compatibility:**
- **Versioning implications:**

## 5) UX / Interaction Details
- **Entry points (where user triggers it):**
- **States:** idle, loading, success, error, disabled, conflict
- **Copy/messaging examples:**
  - Success: `...`
  - Error: `...`
  - In-progress: `...`
- **Accessibility/keyboard behavior:**

## 6) Technical Design
- **Core components/modules to modify:**
- `path/to/fileA`
- `path/to/fileB`

- **Control flow (brief sequence):**
1. Client action
2. Validation
3. Persistence/update
4. Event propagation
5. UI reconciliation

- **Concurrency/idempotency strategy:**
- **Observability (logs/metrics/traces):**

## 7) Edge Cases & Failure Modes
- **Edge cases:**
- ...
- **Failure handling:**
- ...
- **Security/privacy considerations:**
- ...

## 8) Acceptance Criteria
- [ ] Criterion 1 (user-facing)
- [ ] Criterion 2 (data correctness)
- [ ] Criterion 3 (error handling)
- [ ] Criterion 4 (no regression)

## 9) Test Plan
- **Unit tests:**
- **Integration tests:**
- **Manual test script (copy-paste steps):**
1. ...
2. ...
3. ...

- **Regression checks:**
- **Performance checks (if relevant):**

## 10) Rollout Plan
- **Feature flag needed?** yes/no
- **Phased rollout steps:**
- **Rollback plan:**
- **Migration/cleanup follow-ups:**

## 11) Risks & Tradeoffs
- **Top risks:**
- **Mitigations:**
- **Alternatives considered (and why rejected):**

## 12) Open Questions
- 1)
- 2)
- 3)

## 13) Definition of Done
- [ ] Code merged
- [ ] Tests passing in CI
- [ ] Docs/changelog updated
- [ ] Telemetry/alerts in place (if needed)
- [ ] Post-ship verification complete

If you want, I can also give you:

1. a short version for lightweight features, and
2. an RFC version for bigger architectural changes.

Great ask.
Short answer: numbering is helpful for models, but not required. Clear section headers + consistent labels are enough.

Here are unnumbered templates in the styles you asked for.

# Feature Request: <title>

## Snapshot
**What this improves:** <one line>
**Why now:** <one line>
**User impact:** <one line>

## Implementation hints
- <where to put logic>
- <what existing module/pattern to reuse>
- <one caution about edge cases>
- <how to instrument/log this>

## Proposed behavior
- <rule 1>
- <rule 2>
- <rule 3>

## Test definitions (source of truth)
- [ ] **Given** <state>, **when** <action>, **then** <result>
- [ ] **Given** <state>, **when** <action>, **then** <result>
- [ ] **Given** <failure condition>, **when** <action>, **then** <error behavior>
- [ ] **Given** <concurrency/race case>, **when** <action>, **then** <deterministic outcome>
- [ ] **Given** <backward compatibility condition>, **when** <action>, **then** <no regression>

## Minimal implementation plan
- [ ] Add/adjust data model fields: `<path>`
- [ ] Add/adjust API behavior: `<path>`
- [ ] Wire UI/control flow: `<path>`
- [ ] Add tests: `<path>`
- [ ] Add observability: `<path>`

## Acceptance
- [ ] All test definitions pass
- [ ] No existing tests regress
- [ ] Behavior matches proposed rules

# RFC (Human-Centered): <title>

## The story
We keep running into <problem>. It feels like <pain in real usage>, especially when <specific scenario>.
People expect <expected behavior>, but today they get <actual behavior>.

## What we want instead
We want the system to feel like <desired UX/property>.
In practice, that means:
- <behavior idea>
- <behavior idea>
- <behavior idea>

## Why this is the right direction
- It matches how users already think about <concept>.
- It reduces confusion around <state transition/ownership/timing>.
- It gives us a cleaner foundation for <future capability>.

## How it could work
At a high level:
- <state introduced/persisted>
- <trigger/action>
- <what gets committed>
- <how future actions read that state>

Likely touchpoints:
- `<path>`
- `<path>`
- `<path>`

## Tradeoffs we accept
- <tradeoff>
- <tradeoff>

## What could go wrong
- <risk>
- <risk>

Mitigations:
- <mitigation>
- <mitigation>

## How we know it worked
- Users can now <observable outcome>.
- Support/debug confusion around <topic> drops.
- Tests cover <key edge cases> and stay green.

## Open questions
- <question>
- <question>

# RFC (Agent Committee Spec): <title>

## Intent
Define machine-actionable behavior for <feature> with deterministic semantics across UI, API, storage, and runtime orchestration.

## Scope
**In scope**
- <item>
- <item>

**Out of scope**
- <item>
- <item>

## Normative rules
- `MUST`: <hard requirement>
- `MUST`: <hard requirement>
- `SHOULD`: <recommended behavior>
- `MAY`: <optional behavior>
- `MUST NOT`: <forbidden behavior>

## State model
**Entities**
- `<entity>`: <fields>
- `<entity>`: <fields>

**Invariants**
- `INV-1`: <invariant>
- `INV-2`: <invariant>

## Event protocol
**Inputs**
- `<event/action>` with payload `<shape>`

**Transitions**
- From `<state>` + `<input>` -> `<state>` with side effects `<effects>`

**Failure outcomes**
- `<error_code>` => <handling rule>
- `<error_code>` => <handling rule>

## Persistence contract
- Storage location: `<table/collection/path>`
- Serialization: `<format>`
- Idempotency key: `<field>`
- Concurrency rule: `<last-write-wins / compare-and-swap / transaction>`

## API contract
- Endpoint/command: `<name>`
- Request schema: `<shape>`
- Response schema: `<shape>`
- Backward compatibility: <rule>

## Implementation plan (agent-executable)
- [ ] Update schema/storage in `<path>`
- [ ] Implement domain logic in `<path>`
- [ ] Implement transport/API in `<path>`
- [ ] Implement UI/controller in `<path>`
- [ ] Add tests in `<path>`
- [ ] Add telemetry in `<path>`

## Test matrix
- [ ] `T-HAPPY-1`: <happy path>
- [ ] `T-HAPPY-2`: <happy path>
- [ ] `T-FAIL-1`: <error path>
- [ ] `T-RACE-1`: <concurrency path>
- [ ] `T-BWC-1`: <compatibility path>

## Rollout and rollback
- Rollout gate: <flag/check>
- Success metrics: <metric list>
- Rollback trigger: <conditions>
- Rollback action: <steps>

## Agent handoff notes
- Preferred order of operations: <sequence>
- Forbidden shortcuts: <list>
- Validation commands: <commands>

If you want, I can now generate a filled example of each template using your exact “Tab preview / Shift+Tab commit” feature so you can compare tone and usefulness side-by-side.