The all-in-one local AI studio for your desktop: chat, image and video generation and a coding agent in one free, open source app. Windows and Linux. No Docker, no terminal, no cloud required.
TypeScript agentai-chatai-studioall-in-onecoding-agentdesktop-appfluximage-generationlinuxllmlocal-ailocal-llmopen-sourceprivacyself-hostedstable-diffusionuncensoreduncensored-aivideo-generationwindows
import type { CustomParam } from '../lib/custom-params'
import type { AgentBlock } from './agent-mode'
import type { SamplingOverrides } from '../lib/sampling'
export type Role = 'user' | 'assistant' | 'system' | 'tool'
export interface ImageAttachment {
data: string // base64 while composing; lu-attachment:v1:<sha256> in saved chats
mimeType: string // e.g. 'image/png', 'image/jpeg'
name: string // filename
}
/** A clip or sound track attached for Create in chat. Only the facts live in
* the message; the bytes stay in the app session
* (lib/create/chat-attachments.ts) and never enter the chat store. */
export interface MediaAttachment {
kind: 'video' | 'audio'
mimeType: string
name: string
size: number
}
/**
* A file of any kind attached to a user message (3.0.5).
*
* A language model cannot read bytes, so the file itself is NOT in the chat:
* no base64, no reference to a stored copy. What is kept is what the model was
* given in its place (`summary`, a few kilobytes at most) and, in Agent and
* Code, where the file was put in the chat's working folder so the file tools
* can work on it. See lib/chat-files.ts.
*/
export interface FileAttachment {
name: string
/** Size of the file in bytes. */
size: number
/** The type read from the first bytes, e.g. "Game Boy Advance ROM". */
kind: string
/** Lowercase hex SHA-256 of the whole file. */
sha256: string
/** What the model reads instead of the bytes: a hex dump of the start and
* the readable strings, or the start of the text for a text file. */
summary: string
/** Set when the file is not text, so the model got a binary summary
* (3.0.7). Absent on attachments stored before; see isBinaryAttachment. */
binary?: boolean
/** Path inside the chat's working folder, set once the file was put there
* (Agent and Code only). */
workspacePath?: string
/** The same file as a full path on this computer (3.0.8). Tools that do not
* work in the chat's folder, such as the REA plugin, need it. Absent on
* attachments stored before. */
absolutePath?: string
/** A text file: how many characters its text has (GH #171). Absent on a
* binary, on a text too long to be read in whole, and on attachments
* stored before 3.0.7. */
textChars?: number
/** Set when less than the whole text went to the model: how many of the
* `textChars` characters it got. The chip shows it. */
includedChars?: number
}
/**
* A chat-tools "artifact": a file the model produced in PLAIN chat. In chat
* mode `file_write` does NOT touch disk (ChatGPT-style) — the content lands in
* the message and renders inline with a preview + Download button. (The Coding
* Agent still writes to its real working directory.)
*/
export interface ChatArtifact {
id: string
/** Filename the model chose, e.g. "report.md". */
name: string
/** The text content the model "wrote". */
content: string
/** MIME type, derived from the extension — drives the preview. */
mime: string
}
/** Why a run ended in an error, by kind. The chat hook writes it; a screen
* reads it instead of guessing from the text of the answer. */
export type MessageErrorKind = 'credits' | 'session' | 'limit' | 'network' | 'engine' | 'interrupted' | 'generic'
/**
* The error of an assistant turn, as a field (mobile round 2, audit L12).
*
* `content` still carries the sentence the desktop bubble shows, exactly as
* before, so nothing on the desktop changes. `at` is the length of the text
* that had arrived before the error sentence was appended: a reader that
* draws its own error box shows `content.slice(0, at)` and the box.
*/
export interface MessageError {
kind: MessageErrorKind
/** The reason in plain words, empty when the kind says it all. */
detail: string
/** Characters of `content` that are the answer itself. */
at: number
}
export interface Message {
id: string
role: Role
content: string
/** Written on the paired phone (shared chats, lib/remote-chats-bridge). */
fromPhone?: true
/** Set by the chat hook when the run failed. See MessageError. */
error?: MessageError
/** How long the model thought before its first word of answer, in
* milliseconds. Written once, when the answer starts or the run ends. */
thinkingMs?: number
/** When set, the UI renders THIS instead of `content` for a user message.
* Agent slash commands (v2.5.3): the user sees the short "/commit" they
* typed, while `content` holds the full expanded instruction the model
* actually receives. Display-only — never sent to the model. */
displayContent?: string
/** Clips and sound tracks attached for Create in chat. */
media?: MediaAttachment[]
/** Coding-Agent slash command that triggered this assistant turn (e.g.
* "review", "init"). When set, CodexView wraps the whole step transcript in a
* collapsible tool-call-style window — default collapsed, live-streams while
* running (2026-06-12). Undefined for normal coding instructions. */
slashCommand?: string
thinking?: string
/** Which model produced this assistant turn. Set in group chats so the
* bubble can label the speaker and the payload builder can tag the other
* models' lines. Absent on single-model chats. */
modelId?: string
/** Group chat: the persona this turn was written as, when its model played
* one (GH #169). The persona decides who spoke, so the turn stays its
* author's after the persona moves to another model. Absent on turns from
* before 3.0.7 and on turns of a model without a persona of its own. */
groupPersonaId?: string
/** The name that persona had then, for when it has been deleted since. */
groupSpeakerName?: string
/** GH #180: written outside group chat in a thread that has been a group,
* by its model without any persona. Such a turn is its model's and never
* gets a persona stamped on later, so turning group chat back on does not
* hand it to whichever persona that model plays then. */
noGroupPersona?: true
/** GH #201: the request behind this answer left out `dropped` older
* messages to fit `window` tokens. The chat says so next to the answer.
* Absent when the whole conversation went out. */
historyTrim?: { dropped: number; window: number; shortened?: number }
timestamp: number
images?: ImageAttachment[]
/** Files attached to this user message. `content` already carries their
* summaries for the model, `displayContent` holds what the user typed, and
* this list draws the chips and lets a resend rebuild the message. */
files?: FileAttachment[]
sources?: { documentName: string; chunkIndex: number; preview: string }[]
// Agent Mode fields
agentBlocks?: AgentBlock[]
toolCallSummary?: string
/** Chat-tools artifacts — files "written" in plain chat, rendered inline
* with preview + Download (never touch disk). See ChatArtifact. */
artifacts?: ChatArtifact[]
// Continue capability — tool-call history persisted between turns so
// the model sees what it did before (parity with original Codex CLI).
// Hidden messages are included in the API payload but not rendered.
hidden?: boolean
tool_calls?: { id?: string; function: { name: string; arguments: Record<string, unknown> } }[]
/** OpenAI tool-result linkage on role:'tool' messages. Persisted so id-based
* providers (lu-cloud, OpenAI) can match a tool result to its call
* ACROSS turns. Without it, once a tool call is in the history the upstream 422s
* "tool_call_id: Field required" on every follow-up turn (Bug 4, 2026-07-11). */
tool_call_id?: string
// Real token usage reported by the model (Ollama prompt_eval_count/eval_count,
// OpenAI/LM-Studio usage.*). promptTokens = the FULL consumed context for that
// turn (system prompt + tools + RAG + history + input), so it powers a
// 100%-real context readout instead of a char/4 estimate.
// promptTokens = the FULL consumed context (system prompt + tools + RAG +
// history + input). `estimated` is true for the provisional value the agent
// loop sets BEFORE the model replies (so the counter isn't a tiny char/4 guess
// of only the visible messages); it flips to false once the model reports the
// exact prompt_eval_count / usage.prompt_tokens.
usage?: { promptTokens: number; completionTokens: number; totalTokens: number; estimated?: boolean }
/** What this one request cost, for the line under the answer and `/usage`.
* `usage` above is the context anchor and keeps only the LAST model call;
* an agent answer makes several, so this is their sum. Real provider
* counts only, never an estimate: absent when the backend reported none.
* See lib/request-usage.ts. */
requestUsage?: RequestUsage
/** An app notice, not a model turn: the coding view renders it as a plain
* line instead of an assistant bubble, because putting it in a bubble would
* claim the model said it. 'warn' is for a notice the user has to act on,
* today the one that says the bytes on disk are NOT the diff they approved.
* Carried on role:'system' messages, which the payload builder drops, so a
* notice never reaches the model. */
notice?: 'info' | 'warn'
/** Why generation ended, when the model did NOT stop on its own terms:
* 'length' (token budget) or 'disconnect'. Drives the small cut-off badge so
* a truncated answer is not shown as if it were complete (parity with the
* benchmark screen). Absent or 'stop' on a clean finish. */
finishReason?: string
/** Phone only (round 10, lib/continue-answer.ts): this answer is the direct
* continuation of the answer before it. The engine wrote it inside that
* answer's open turn, so the two join without anything between them.
* Absent everywhere else. */
continuation?: 'exact'
/** Z36 finding 3: URLs in this agent answer that appear nowhere in what the
* model was shown this run (system prompt, history, tool results), so no
* tool returned them. Set only after the one corrective steer was ignored.
* Drives a labelled notice under the bubble instead of rewriting the
* model's text (G14-2). Absent when every link was backed. */
unbackedLinks?: string[]
/** The opening message of a character card chat (3.0.7): every greeting
* the card offers, `content` is the one at `greetingIndex`. Switching only
* happens before the user writes. */
greetings?: string[]
greetingIndex?: number
}
/**
* One compaction of this conversation (2.6.8).
*
* WHY THE ANCHOR IS AN ID AND NOT AN INDEX. The cut has to survive everything
* that happens to the array afterwards: new turns appended, a message deleted,
* the payload builders filtering stored `role:'system'` notices out. An index
* survives none of those — it would silently start covering the wrong turns,
* and a summary standing in front of material it does not describe is worse
* than no summary. An id that is gone means the record is stale, which is a
* state the reader can detect and ignore.
*
* The summary itself is stored RENDERED, exactly as it goes into the payload,
* so what the transcript block shows and what the model receives cannot drift.
*/
export interface CompactionRecord {
id: string
/** The rendered summary, byte-identical to what the payload carries. */
summary: string
/** Id of the LAST message this summary stands in for — the cut point. */
upToMessageId: string
/** How many messages it stands in for. Display only. */
replaced: number
/** Messages in the conversation when it ran. The auto-compact cooldown anchor. */
atMessageCount: number
/** Estimated tokens of the replaced turns, and of the summary. */
tokensBefore: number
tokensAfter: number
/** Who asked: the user typing /compact, or the threshold firing. */
trigger: 'manual' | 'auto'
at: number
/**
* True when `summary` is a merged state (3.0.7, issue #151): it stands for
* everything up to its anchor, the earlier records included, and the payload
* starts from it instead of sending the whole chain. Absent on older records
* and on a run whose merge failed and fell back to a plain link.
*/
merged?: boolean
/**
* The whole payload before and after, estimated, for the transcript line
* "Compacted, 28.9K → 17.9K" (3.0.9). `tokensBefore`/`tokensAfter` above
* only measure the replaced turns against their summary, which is not the
* number the context counter shows. Absent on records from before 3.0.9.
*/
contextBefore?: number
contextAfter?: number
/** Id of the newest message when it ran: where the view "before this
* compaction" ends (lib/compact-layers.ts). Absent on older records,
* which fall back to `atMessageCount`. */
endMessageId?: string
}
/**
* The kept versions of one point in a chat (GH #172, #174).
*
* A resend after an edit, and a regenerate, start a new continuation after
* one message. The old continuation is not deleted any more: it moves in here
* and stays one click away ("< 1/2 >"). `null` marks the version that is in
* `Conversation.messages` right now, so every message lives in exactly one
* place and a version costs no copy.
*/
export interface ChatFork {
/** Every continuation after the key message, oldest first. */
versions: (Message[] | null)[]
}
export interface Conversation {
id: string
/** Stable user-assigned project ID for memory retrieval and extraction. */
memoryScope?: string
title: string
messages: Message[]
model: string
systemPrompt: string
mode?: 'lu' | 'codex' | 'openclaw' | 'remote'
/** Shared with the paired phones ("Continue on phone", CHATS-V1.md): the
* phone lists it, reads it live and writes into it. */
remoteShared?: boolean
/** Per-chat persona toggle. Mirrors the mobile chat's `personaEnabled`
* flag so the user can flip the persona on/off for each chat
* individually without losing the selection in Settings. Undefined
* on legacy chats and treated as enabled. */
personaEnabled?: boolean
/** GH #170: the persona this chat speaks as, written when the chat is
* created with one and whenever a persona is picked in the Plugins menu
* of this chat. Read through lib/chat-persona.ts, which also covers chats
* from before this field (they keep `systemPrompt`). */
personaId?: string
/** Group chat v1: two to four models that answer in turn on every user
* message. Fewer than two entries means a normal single-model chat. */
groupModels?: string[]
/** Group chat: the persona each participant speaks as, model name to
* persona id (3.0.5, a user on Discord). A model without an entry
* follows the chat's own persona setting, which is how every group worked
* before this field existed. */
groupPersonas?: Record<string, string>
/** Group chat (GH #200): members set to sit out the NEXT round only. The
* round that starts takes it away again, so it never lingers. Absent:
* everyone answers, in the order of `groupModels`. */
groupSitOut?: string[]
/**
* Compactions that have happened in this chat, oldest first. The payload
* carries the newest merged state and any plain links after it; a chat from
* before 3.0.7 has no merged state and sends the whole chain, because each
* plain link only covers the turns since the one before it. The earlier
* records stay stored because the transcript shows them where they happened.
*
* Absent on every chat from before 2.6.8, and on every chat that has never
* been compacted. Both read as "no compaction", which is what they are.
*/
compactions?: CompactionRecord[]
/** R5-10/R5-11 (3.0.1-Liste): sampling this chat has chosen for itself.
* Additive and optional, so a chat persisted before this field existed
* loads unchanged and needs no store migration. Absent means "follow the
* Settings page", not "use the app default"; src/lib/sampling.ts has the
* full rule. Reset in the popup deletes this field rather than writing the
* defaults into it, so a reset chat keeps following the Settings page even
* if its sliders move again afterwards. */
sampling?: SamplingOverrides
/** GH #198: this chat's own custom sampling parameters. They win over the
* speaker's persona rows with the same key; in a group they hold for every
* member. Absent on every chat from before. */
customParams?: CustomParam[]
/**
* Kept versions (GH #172, #174), keyed by the id of the message they follow,
* or FORK_ROOT (lib/chat-forks.ts) for a change of the very first message.
* `messages` stays the one thread every reader works with: the payload,
* the search, the export. Absent on every chat from before 3.0.7 and on
* every chat that was never resent, which reads as "one version".
*/
forks?: Record<string, ChatFork>
/** D26 (3.0.8): set on a chat made from a chatbot export. `fingerprint`
* hashes the messages as imported; when the chat's messages no longer
* match it, the user went on in LU and a newer export must not replace
* the chat (see lib/chat-import.ts). `version` is the export's last
* change (epoch ms) at import. Absent on every other chat. */
importedFrom?: { fingerprint: string; version: number }
createdAt: number
updatedAt: number
}
/** The sum of every model call one answer made. `calls` counts the calls
* that reported numbers. `billing` is LU Cloud's own word for the request:
* 'flash' drew no credits, 'credits' did (one call on credits is enough). */
export interface RequestUsage {
inputTokens: number
outputTokens: number
calls: number
billing?: 'flash' | 'credits'
/** Of inputTokens, how many the backend served from its prompt cache (CA).
* Absent when no call reported it. */
cachedTokens?: number
}