chatshell

func (*Model) AppendAssistant ¶

func (m *Model) AppendAssistant(text string)

AppendAssistant appends a (non-streamed) assistant message.

func (*Model) AppendAssistantMarkdown ¶ added in v0.0.3

func (m *Model) AppendAssistantMarkdown(text string)

AppendAssistantMarkdown appends a non-streamed assistant message rendered through the configured MarkdownRenderer (WithMarkdownRenderer), e.g. agent or HTTP-response markdown via glamour. With no renderer configured it behaves like AppendAssistant (transcript.Entry.Markdown is inert then).

func (*Model) AppendBlock ¶

func (m *Model) AppendBlock(block transcript.Block)

AppendBlock appends a rich transcript.Block (e.g. a tui/grid result).

func (*Model) AppendBlockWithID ¶ added in v0.0.3

func (m *Model) AppendBlockWithID(id string, block transcript.Block) bool

AppendBlockWithID appends a rich transcript.Block under a caller-chosen, stable id, so a product can later FocusEntry(id) (e.g. DataTug's Ctrl+G "jump to latest grid") or ReplaceBlock(id, ...) it. id must be non-empty and unique among live entries (and must not clash with an in-flight StartStream id, since both identify a transcript entry the same way); AppendBlockWithID reports false and does not append on any such collision, so a caller can generate a fresh id and retry instead of silently corrupting FocusEntry/ReplaceBlock addressing.

func (*Model) AppendSystem ¶

func (m *Model) AppendSystem(text string)

AppendSystem appends a system/status message (e.g. an error).

func (*Model) AppendUser ¶

func (m *Model) AppendUser(text string)

AppendUser appends a user message to the transcript.

func (*Model) Busy ¶

func (m *Model) Busy() bool

Busy reports whether a stream, or a product SetBusy(true) phase, is in flight.

func (*Model) Chips ¶ added in v0.2.0

func (m *Model) Chips() []Chip

Chips returns a defensive copy of the composer's current attachment chips.

func (*Model) ClearChips ¶ added in v0.2.0

func (m *Model) ClearChips() tea.Cmd

ClearChips detaches every chip -- a product-facing equivalent of Esc's second step (clearComposerStep) -- e.g. a toolbar "clear attachments" button. It snapshots the pre-clear draft first (so Shift+Esc/Ctrl+Y can undo it) and is a no-op (returns nil) when there are no chips to clear.

func (*Model) ClearTranscript ¶ added in v0.0.3

func (m *Model) ClearTranscript()

ClearTranscript cancels any in-flight stream, empties the transcript and returns focus to the composer, e.g. /clear or a session switch. Cancelling first (rather than leaving the stream running against a now-empty transcript) matters because handleStreamEvent only applies an EventMsg whose ID still matches the current stream — a stray delta for the cancelled stream is otherwise silently dropped instead of resurrecting a transcript entry the clear just removed. A product's own SetBusy(true) phase (no stream, e.g. a decision chain) has no DoneMsg to cancel it asynchronously, so ClearTranscript also invokes the registered SetBusyCancel callback directly, same as cancelBusy does for Esc/Ctrl+C.

ClearTranscript also drops any pending Shift+Esc/Ctrl+Y composer-draft snapshot and clears chip focus (M1, r1 review) -- e.g. a session switch, where the OLD session's "undo my last chip removal" and chip-row cursor position no longer mean anything against the NEW session's own chips (which a product typically installs right after via SetChips). It does NOT itself clear m.chips: which chips belong to the new session is the product's call, made via SetChips, not ClearTranscript's.

func (*Model) CloseOverlay ¶ added in v0.1.0

func (m *Model) CloseOverlay(o Overlay) bool

CloseOverlay removes o from the overlay stack WHEREVER IT IS -- not only if it's on top -- matching by POINTER IDENTITY (see Overlay's doc: an Overlay MUST be a pointer type for this to ever find it). It reports whether o was found and removed; false is a no-op. This is the identity-safe replacement for PopOverlay in the async-safe overlay pattern once a second overlay might be stacked on top of the one an async result is meant to close (r3 review, MAJOR -- see PopOverlay's doc).

A non-pointer Overlay (or a nil pointer) can never be matched -- o's pointer identity is extracted via reflection rather than Go's `==` specifically to avoid a runtime panic comparing two interface values whose dynamic type is non-comparable (e.g. one holding a slice or map field); CloseOverlay simply reports false for such an Overlay instead of crashing.

func (*Model) FocusEntry ¶ added in v0.0.3

func (m *Model) FocusEntry(id string) bool

FocusEntry moves focus to the transcript entry identified by id (e.g. DataTug's Ctrl+G "jump to latest grid"), scrolling it into view. It reports whether such a focusable entry exists; when it doesn't, focus is left unchanged.

func (*Model) FocusedEntryID ¶ added in v0.1.0

func (m *Model) FocusedEntryID() string

FocusedEntryID reports the transcript entry id currently under focus (Zone() == focus.ZoneTranscript), or "" when the transcript isn't focused, no entry is focused, or the focused entry was never given an id (AppendBlockWithID/StartStream's id; a plain AppendUser/AppendAssistant/ AppendBlock entry has none).

func (*Model) FocusedRef ¶

func (m *Model) FocusedRef() *session.EntityRef

FocusedRef returns the entity ref under focus: the transcript's focused block's Current() when the transcript zone has focus, or the sidebar cursor's ref when the sidebar zone has focus (the default sidebar only — a SidePanel exposes no cursor in its pinned contract, so this is nil while one is active). It is nil when the composer has focus, or nothing is under the cursor.

func (*Model) Init ¶

func (m *Model) Init() tea.Cmd

func (*Model) MouseEnabled ¶ added in v0.1.0

func (m *Model) MouseEnabled() bool

MouseEnabled reports whether mouse reporting is currently requested (see SetMouseEnabled).

func (*Model) PinToSidebar ¶

func (m *Model) PinToSidebar(ref session.EntityRef)

PinToSidebar adds ref to the sidebar (or, with a SidePanel implementing SidePanelPinner, to it instead) and notifies an OnSidebarChange Handler, if any.

func (*Model) PopOverlay ¶ added in v0.1.0

func (m *Model) PopOverlay() tea.Cmd

PopOverlay closes the TOP overlay PROGRAMMATICALLY -- without waiting for its own Update to report done. It is a no-op (returns nil) when no overlay is open.

PopOverlay is TOP-ONLY: it closes whatever happens to be on top at the moment it is called, regardless of which overlay a caller "meant". That is exactly right for the common case (at most one overlay is ever open at a time), but WRONG for the async-safe pattern below once a SECOND overlay can be stacked on top of the first before its async result arrives (r3 review, MAJOR) -- e.g. dialog A's submit is in flight, the user opens dialog B on top of it, and A's result lands: PopOverlay would close B, not A. Use CloseOverlay(o) instead whenever more than one overlay might ever be on the stack at once; PopOverlay remains for the simpler single-overlay case (or for closing "whatever's on top" on purpose, e.g. an Esc-equivalent product action).

Async-safe overlay pattern: an Overlay may need to stay open ACROSS an async round trip (e.g. a form whose Enter submits to a server before it can close). Its own Update returns done: false plus a product tea.Cmd on submit -- exactly like any other command chatshell dispatches. The product's own result message, once it arrives, is NOT itself overlay input (isOverlayInputMsg only classifies key/paste/mouse messages), so it takes the normal Update path and reaches an optional MsgHandler.OnMsg (dispatchUnhandled's default routing) EVEN WHILE THE OVERLAY IS STILL OPEN -- an open overlay only captures key/paste/mouse input, never this. From there the product calls CloseOverlay(o) with the SAME *T it passed to PushOverlay on success (see Overlay's doc: it MUST be a pointer type), or -- to show an error while keeping the user's draft -- updates the overlay in place (e.g. via an optional `interface{ OnResult(any) }` capability the product's own Overlay implements, or simply because the product holds that same pointer and can mutate it directly).

func (*Model) PushOverlay ¶ added in v0.0.3

func (m *Model) PushOverlay(o Overlay) tea.Cmd

PushOverlay pushes a modal dialog onto the overlay stack. The top overlay captures every key event (and every other message chatshell would otherwise handle itself) until its Update returns done, and is rendered centred over the screen.

func (*Model) RemoveChip ¶ added in v0.2.0

func (m *Model) RemoveChip(id string) (cmd tea.Cmd, found bool)

RemoveChip removes the chip with the given ID -- a product-facing equivalent of Backspace/Delete on a focused chip or a mouse click on its ×, e.g. a "remove attachment" control the product renders elsewhere in its own UI. It snapshots the pre-removal draft first, same as any other removal (so Shift+Esc/Ctrl+Y can undo it), and reports (r2 review, m3) via the second return value whether a chip with that ID was found and removed; found is false (cmd is nil) for an unknown ID, a documented no-op.

func (*Model) ReplaceBlock ¶ added in v0.0.3

func (m *Model) ReplaceBlock(entryID string, b transcript.Block)

ReplaceBlock refreshes/re-runs a grid (or any other transcript.Block) in place: the entry identified by entryID keeps its position and ID, but renders b from now on. If that entry currently holds transcript focus, it keeps it (the focus ring stop is recomputed for the entry, not left pointing at whatever raw index it used to occupy — necessary because replacing a Block can change its own Focusable() answer).

The previously-focused entry is tracked by its RAW POSITION in m.transcript.Entries(), not by transcript.StopForID(fe.ID): that ID-keyed lookup always reports -1 for an entry with an empty ID (which AppendUser/AppendAssistant/plain AppendBlock all leave empty — only AppendBlockWithID sets one), and transcript.ReplaceBlock's own internal focus cursor likewise only re-resolves itself by ID when the focused entry has one. So a no-ID focused entry would otherwise silently look unfocused (or land on the wrong stop) the moment an EARLIER entry's swap shifts stop numbers — even though that entry's own Block never changed. Raw position is safe to track across the call because transcript.ReplaceBlock only mutates one entry's Block in place; it never reorders, inserts or removes entries.

m.focusRing (chatshell's own zone/stop tracker) is resynced to whatever was decided too: syncFocus later reapplies focusRing.Stop() into the transcript on the next zone change or resize, so leaving it stale would silently undo the recomputed focus the next time that happens.

func (*Model) SelectionRefs ¶

func (m *Model) SelectionRefs() []session.EntityRef

SelectionRefs returns the transcript's current selection: the focused block's entity, when any (a Block may later report more than one, e.g. a grid's multi-selected rows; today this is FocusedRef's single entity). It is distinct from the sidebar's pins — see SidebarRefs.

func (*Model) SetBusy ¶

func (m *Model) SetBusy(busy bool) tea.Cmd

SetBusy marks a product-driven phase that precedes (or stands in for) a stream — e.g. a decision chain or a deterministic query — as in flight: the composer stops accepting input and the spinner runs, exactly as while a stream is in flight. The returned tea.Cmd starts the spinner and must be returned from Update/a command chain when busy is true; it is nil when busy is false. SetBusy(false) clears any SetBusyCancel func registered for the phase that just ended.

func (*Model) SetBusyCancel ¶

func (m *Model) SetBusyCancel(cancel func())

SetBusyCancel registers the cancel func for the current SetBusy(true) phase (e.g. a context.CancelFunc for the ctx a decision chain runs under). Esc/Ctrl+C while busy and no stream is active calls it — see cancelBusy. Products that call SetBusy(true) but have nothing cancellable may leave this unset.

func (*Model) SetChips ¶ added in v0.2.0

func (m *Model) SetChips(chips []Chip)

SetChips replaces the composer's attachment chips wholesale, e.g. when the product attaches a new entity from its own workspace/sidebar UI. The focused chip index is preserved when it still falls within the new list, and reset to "no chip focused" (returning keyboard focus to the input) when it doesn't -- e.g. the list shrank.

SetChips does NOT clear a pending Shift+Esc/Ctrl+Y undo snapshot (see snapshotComposerUndo): the snapshot exists to let the user recover from a change THEY just made, and a product-driven SetChips call (adding or syncing chips for an unrelated reason) shouldn't silently discard that recovery option out from under them. When a restore does eventually happen, any chip present now that wasn't part of the snapshot is kept, not discarded -- see mergeRestoredChips.

func (*Model) SetComposerText ¶ added in v0.0.3

func (m *Model) SetComposerText(s string)

SetComposerText sets the composer's text and moves the cursor to the end, e.g. an edit-previous-message flow.

func (*Model) SetMouseEnabled ¶ added in v0.1.0

func (m *Model) SetMouseEnabled(enabled bool)

SetMouseEnabled toggles mouse reporting at runtime, e.g. DataTug's F2 capture toggle (a terminal's own native text-selection/copy is unusable while mouse reporting is on, so a product that wants both needs a key to flip between them). enabled true requests the mode configured via WithMouse (MouseCellMotion by default if WithMouse was never called); enabled false requests no mouse reporting at all. The new mode takes effect on the next View() -- chatshell has no way to push it to the terminal outside the normal render cycle.

func (*Model) SetStatus ¶

func (m *Model) SetStatus(text string)

SetStatus sets the status line text (provider/model/path/usage, etc.).

func (*Model) SidebarRefs ¶

func (m *Model) SidebarRefs() []session.EntityRef

SidebarRefs returns the sidebar's pinned refs: the default sidebar's, or a SidePanelPinner SidePanel's, or nil when a SidePanel is active but doesn't implement SidePanelPinner (see PinToSidebar).

func (*Model) StartStream ¶

func (m *Model) StartStream(id string, open func(ctx context.Context) iter.Seq2[ai.Event, error]) tea.Cmd

StartStream starts a streamed assistant entry. id must be unique per turn; deltas render progressively into the transcript, and a spinner runs until the first delta (or completion) arrives.

The Model owns the per-stream context: it creates a cancellable child of its own context (WithContext) and passes it to open, which must use it to build the actual provider call (e.g. `return provider.Stream(ctx, req)`) so a cancellation reaches the live request, not just this local pump — an adapter observing ctx.Done() aborts its call and yields ai.ErrCodeCanceled. The context is cancelled automatically when a new StartStream call supersedes this one, or explicitly by the user (Esc or Ctrl+C while busy). A cancelled stream ends with a "(stopped)" transcript entry, not an error, and StreamObserver.OnStreamDone (if implemented) always fires once the stream ends, however it ended.

func (*Model) StartStreamMarkdown ¶ added in v0.0.3

func (m *Model) StartStreamMarkdown(id string, open func(ctx context.Context) iter.Seq2[ai.Event, error]) tea.Cmd

StartStreamMarkdown is StartStream, but the streaming entry is rendered through the configured MarkdownRenderer (WithMarkdownRenderer) as it accumulates, same as AppendAssistantMarkdown for a non-streamed message — e.g. DataTug's agent/HTTP markdown responses. With no renderer configured it behaves like StartStream (transcript.Entry.Markdown is inert then).

func (*Model) UnpinFromSidebar ¶

func (m *Model) UnpinFromSidebar(ref session.EntityRef)

UnpinFromSidebar removes ref from the sidebar (or SidePanelPinner) and notifies an OnSidebarChange Handler, if any.

func (*Model) Update ¶

func (m *Model) Update(msg tea.Msg) (tea.Model, tea.Cmd)

func (*Model) View ¶

func (m *Model) View() tea.View

View renders the chat screen. It re-applies resize() FIRST, on every call (r2 review, B1) -- not only in response to WindowSizeMsg/F6/Ctrl+ Left/Right/a chip-list change, the only events that previously called it -- because historyHeight() (and therefore how tall the transcript SHOULD be) also depends on state that changes without going through any of those: typing "/" opens the slash-command menu, SetStatus changes the status segment's height, and SetBusy(true)/StartStream reserves the spinner line. Without this, m.transcript's ACTUAL viewport size (set via SetSize, and otherwise sticky) drifts from the CURRENT historyHeight() value between renders -- both the total rendered line count (over- or under-filling the screen) and chipsTopY's click math (computed fresh from the CURRENT historyHeight() at click time, but answering for whatever was ACTUALLY drawn by the last, possibly stale, render) go wrong. Calling resize() here is cheap (it only sets sizes) and idempotent, so doing it unconditionally on every render is simpler and more robust than hunting down every call site that can change chrome height.

func (*Model) Zone ¶ added in v0.1.0

func (m *Model) Zone() focus.Zone

Zone reports which focus zone currently has focus: the composer (focus.ZoneInput), a transcript stop (focus.ZoneTranscript), or the sidebar/SidePanel (focus.ZoneSidebar) -- e.g. for a product's context-specific status hint.