Session and conversation product model
Status: current implementation. This model defines conversation identity, Feishu bindings and input lifetime. It complements the Agent contract, Bridge contract and Task model.
Objects and identity
A Session is the Runtime-owned managed conversation, addressed by target and Session identity. It retains launch settings, workspace, execution identity and resumable provider history. An Agent Profile is its launch definition, not its identity. The native provider's conversation ID is a resume handle, not the amux Session ID. A restart can change the process without changing the Session.
Restart and automatic wake retain recorded execution settings. Missing profile or engine identity is first recovered from the saved launch snapshot. If no profile identity remains, recovery uses builtin/default when registered, otherwise the distribution's default builtin profile. A missing engine uses the distribution's default launch runtime. These fallbacks do not inherit shortcut permission bypass. Saved model, reasoning, permission settings and workspace remain authoritative. A deleted source Pack does not invalidate an existing execution snapshot; an unavailable recorded engine is an error, never an automatic engine switch. If no engine identity survives, native provider history cannot safely be resumed; recovery starts a fresh provider conversation with the amux history handoff.
New Sessions default to native bypass unless native permission arguments were explicitly supplied. This applies to CLI, MCP and Feishu launches, independently of the expert. The resolved default is recorded for restart and resume; existing Sessions retain their saved execution settings.
A Turn is one dispatched submission accepted by the Session queue. Several Feishu messages may be coalesced into one submission; one message can also trigger a control action or add context without starting a Turn. The canonical Timeline owns TurnID/TurnSeq and exactly one TurnFinished. Result text alone is not a completion signal. A Session can contain many Turns.
Feishu ordinary follow-ups do not preempt active work by default. A text-only input that arrives during an active Turn is coalesced with the burst in a default two-second window and then either steered or queued:
- Steered when its sender is the one person who sent the running Turn's input. The input is pinned to that TurnID and added to the running Turn; it does not create a new Turn, and the Turn still ends with exactly one TurnFinished, after the provider has handled its last steered input.
- Queued as ordinary input for the next Turn in every other case: input from another group member, group-watch alerts, Bot input or other input without a sender, no known running Turn, earlier input already waiting in the queue, a Turn that is being interrupted, differing Turn authorization, or a provider without steering. Queued follow-ups never preempt.
- Not delivered when the provider may already have taken the input but did not confirm it (a timeout or broken transport). The submission fails instead of queueing a second copy that could run twice.
Interrupting a Turn also cancels the input steered into it. Claude stops a steered input that the CLI still has queued as soon as it starts running, and the next Turn starts with a note naming the cancelled input. AMUX_FEISHU_BUSY_INPUT=interrupt restores the previous contract: Bridge requests interruption immediately and submits the coalesced input with preemption. Material-bearing inputs bypass text coalescing. This is separate from queued compact / clear controls, which do not preempt preceding input. Neither interruption nor a context reset rolls back completed tool side effects.
A TaskRun is created through Task admission for a bounded child execution. An ordinary Feishu request can drive a Session Turn without any TaskRun. The product UI's use of “task” for ongoing work does not establish a TaskRun record. A TaskRun records its child Session and exact accepted child Turn; an Agent Instance can span multiple TaskRuns with distinct task IDs.
Feishu binding scopes
| Binding | Reuse rule | Boundary |
|---|---|---|
| Topic | Accepted input in an active bound topic reaches its Session | A new independent topic has a separate binding |
| Bot singleton | Eligible private/group input reuses the Bot Profile's bound Session | Not automatically per-chat or per-user |
| Group singleton | An opted-in group's eligible input reaches its current group Session | Scoped by Bot and group; distinct from the bot singleton |
Per-group settings are default-off. When enabled for a group they override bot message-handling defaults. Existing ordinary topic bindings remain addressable; an explicit launch/bind does not replace the group's current continuous conversation. Retiring a group singleton stops new input to that conversation but lets accepted work complete, including output recovery after a Bridge restart.
In shared active topics, ordinary unmentioned human discussion is recorded as bounded context; an explicit mention triggers work. Owner-only admission and binding-control authorization are independent checks. A visible card or topic does not authorize all readers to drive its Session.
Lifecycle and user actions
Session state uses created, running, idle, sleeping, archived. Turn state and TaskRun status must not be inferred from these labels. Process liveness alone does not say whether a turn is awaiting a tool, permission or completion.
| Action | Meaning |
|---|---|
| Submit/reply | Queue new input for the existing conversation |
| Detach | Close a viewer; preserve Session and execution |
| Interrupt | Request interruption of the active work; preserve Session identity |
| Sleep/resume | Stop/relaunch the process with resumable state |
| Restart | Relaunch using the existing Session's settings and available history |
| Compact | Ask a supporting Agent to summarize its current context |
| Clear | Start fresh native context while retaining the Session binding, where supported |
| Stop a topic | Kill its Session and terminate the topic binding |
| New group continuous conversation | Retire the old input pointer; do not cancel already accepted work |
Bot-wide singleton mode rejects topic-style run/bind/stop operations and directs the user to management. Agent-specific controls may be unavailable. Clearing context or changing a binding is not deletion of workspace files, stored Hub memory or all historical records. An ended topic is not silently reused as a new conversation. Default expert changes apply to new launches; existing topic Sessions keep their selected expert. Singleton expert replacement follows its confirmed management transition.
Context boundaries
Native conversation history, Feishu context packages, workspaces, explicit Task inputs and Hub memory are separate resources. They do not merge merely because a bot, Profile or human user is shared. Topic context is bounded, not an export of the whole chat. Children receive their explicit task inputs and allowed resources, not automatic copies of the parent's complete conversation.
See thread context for selection and truncation, and memory for principal-derived scope.
Implementation evidence
- Event timeline design record preserves the historical rationale and alternatives behind Turn ownership and replay.
- Session state and queue, Timeline.
- Topic decisions, routing, bot singleton, group singleton.
- Control dispatch, command policies.
- TaskRun fields, persistent instance store.
Native goals
Source implementation; live Feishu end-to-end acceptance is pending.
Only a leading bare goal is a formal command; /goal is not an alias. The commands are goal <objective> (create/start), goal (query), goal pause, goal resume, goal clear, goal set <objective> (explicit replacement), and goal budget <positive tokens>. An unfinished goal rejects implicit replacement. No budget is invented. Native state, token usage and runtime seconds remain authoritative. Resume preserves native accounting; changing an objective follows the provider's accounting semantics. Clearing a goal preserves the conversation.
Capability is discovered on the live provider. Codex-compatible app servers are probed with thread/goal/get; unsupported methods, disabled features and invalid responses fail closed. Other registered structured providers opt in through GoalController and NativeGoalTurnProvider, exported by pkg/extensions. Claude SDK and Pi currently have no native goal adapter and expose no goal help or actions. Agent names alone never establish support. No native /goal slash menu is registered.
In topic mode, controls resolve the bound Session. Only creation can launch and bind an unbound topic through normal admission. In bot singleton mode, the goal belongs to the shared bot Session across chats. Output stays pinned to the creation destination; querying elsewhere does not relocate it. Replacing the goal establishes a new destination and invalidates earlier card buttons. Creation/replacement accepts a text objective; send attachments and explicit quoted material as separate ordinary follow-ups. Existing native conversation history remains available; goal controls do not hydrate Feishu topic history. Existing mention, ownership and group-access rules still apply.
Each native continuation needs an enabled durable grant matching its native conversation and objective, and a single runtime owner. It receives a fresh canonical Turn and ordinary terminal, transport replay and watchdog handling, without local-expert authoring privileges. Pending user inputs take priority. Only matching persisted destinations authorize Feishu goal output; unrelated native turns retain quarantine. Startup notifications wait for owner handover. Pause revokes admission before native cancellation; clear also removes grants and destinations. Ordinary input preemption preserves the grant and can resume an otherwise paused goal after the input queue drains. Explicit interrupts and goal pause revoke it. Native blocked, usage-limited, budget-limited and complete states do not auto-resume. A disconnected owner cannot admit new continuations; if quarantine pauses the native goal, use goal resume after reconnecting.
Goal observations are sticky session-scoped canonical events and are restored at Attach catch-up. State cards include native usage, budget and time, with English and Simplified Chinese copy. Mutating card callbacks recheck permissions, current Session identity, destination generation and native goal identity; stale cards cannot control a replacement Session or goal.
Goal permission requests use the same frozen binding as the turn's replies. An accepted ordinary submission cancels a pending goal admission offer atomically; ordinary input in progress rejects goal offers without waiting for that input to finish. TAIL Attach includes the active canonical turn's start snapshot from the atomic read head. Bridge restores only a goal turn matching its persisted destination and current binding, authorizing subsequent replies and permission requests without replaying earlier output.