threecode/ui

REPL command dispatch and provider/model wizards.

Handles all :cmd input that is not a prompt to the model. The command set is narrow by design: introspection (:show, :log, :tokens), context management (:clear, :summarize), provider/model switching (:provider, :model, :reasoning).

Tab-completion in tabComplete walks KnownGoodCombos and the live provider list to offer only valid model names. The provider-add wizard in runProviderAdd validates the API key with a one-token probe before saving.

Types

CommandDisposition = enum
  cdTranscriptResult, cdHarnessOnly, cdModal
CommandKind = enum
  ckUnknown, ckSafeImmediate, ckMutating, ckModal, ckQuit
CommandResult = object
  recognized*: bool
  ok*: bool
  name*: string
  body*: string
  plainBody*: bool
  clearFooter*: bool
  disposition*: CommandDisposition
WizardReadLineHook = proc (prompt: string; hidden, noHistory: bool): string {.
    closure.}

Consts

CommandNames = [":help", ":tokens", ":clear", ":model", ":provider",
                ":reasoning", ":streaming", ":prompt", ":show", ":log",
                ":sessions", ":summarize", ":q", ":quit", ":exit"]

Procs

proc bootstrapProvider(editor: var minline.LineEditor): Profile {.
    ...raises: [IOError, IOError, Exception, KeyError, OSError], tags: [
    WriteIOEffect, RootEffect, WriteDirEffect, ReadDirEffect, ReadEnvEffect,
    ReadIOEffect, TimeEffect], forbids: [].}
proc buildUserMessage(messages: JsonNode; raw: string): string {.
    ...raises: [OSError, IOError], tags: [ReadEnvEffect, ReadIOEffect,
                                       ReadDirEffect, RootEffect, TimeEffect,
                                       WriteDirEffect, ExecIOEffect],
    forbids: [].}
Apply @file inlining always; prepend the session preamble (cwd, git state, AGENTS.md, ls) only on the first user message of a session so resumed conversations don't re-inject stale context.
proc classifyCommand(cmd: string): CommandKind {....raises: [], tags: [],
    forbids: [].}
proc completionFor(line: string): seq[string] {....raises: [], tags: [],
    forbids: [].}
proc handleCommand(cmd: string; messages: var JsonNode; session: var Session;
                   prof: var Profile; editor: var minline.LineEditor): bool {.
    ...raises: [Exception, IOError], tags: [RootEffect, WriteIOEffect], forbids: [].}
returns true if the input was a recognised command
proc handleCommandResult(cmd: string; messages: var JsonNode;
                         session: var Session; prof: var Profile;
                         editor: var minline.LineEditor): CommandResult {....raises: [
    IOError, Exception, KeyError, OSError, SessionLocked, IOError, OSError,
    SessionLocked, Exception, KeyError, IOError], tags: [WriteIOEffect,
    RootEffect, WriteDirEffect, ReadDirEffect, ReadEnvEffect, ReadIOEffect,
    TimeEffect], forbids: [].}
proc inlineAtFiles(msg: string): string {....raises: [],
    tags: [ReadEnvEffect, ReadIOEffect, ReadDirEffect], forbids: [].}
Find @path tokens (whitespace-delimited, must follow whitespace or start of input). For each that resolves to an existing regular file under cwd, append \n\n=== {path} ===\n<content> (capped) to the message. Leave the @token visible so the model sees the user's intent.
proc isFirstUserMessage(messages: JsonNode): bool {....raises: [],
    tags: [RootEffect], forbids: [].}
proc promptEditProvider(editor: var minline.LineEditor; existing: ProviderRec): ProviderRec {.
    ...raises: [IOError, Exception, KeyError, OSError, InputCancelled], tags: [
    WriteIOEffect, RootEffect, WriteDirEffect, ReadDirEffect, ReadEnvEffect,
    ReadIOEffect, TimeEffect], forbids: [].}
proc promptNewProvider(editor: var minline.LineEditor): ProviderRec {.
    ...raises: [IOError, Exception, KeyError, OSError, InputCancelled], tags: [
    WriteIOEffect, RootEffect, WriteDirEffect, ReadDirEffect, ReadEnvEffect,
    ReadIOEffect, TimeEffect], forbids: [].}
proc readInput(editor: var minline.LineEditor; done: var bool): string {.
    ...raises: [ResourceExhaustedError, IOError],
    tags: [TimeEffect, WriteIOEffect, ReadEnvEffect], forbids: [].}
Read a line submitted by the persistent input thread. The same minline.readLineWith path owns idle prompt input and active-turn buffered input; the controller only consumes completed lines here.
proc readOptional(editor: var minline.LineEditor; prompt: string;
                  hidden = false; noHistory = true): string {.
    ...raises: [Exception, Exception, IOError, KeyError, OSError, InputCancelled],
    tags: [RootEffect, WriteDirEffect, ReadDirEffect, WriteIOEffect],
    forbids: [].}
ctrl+c raises minline.InputCancelled to the caller; ctrl+d aborts the program. Empty input is returned as "".
proc readRequired(editor: var minline.LineEditor; prompt: string;
                  hidden = false; noHistory = true): string {.
    ...raises: [Exception, Exception, IOError, KeyError, OSError, InputCancelled],
    tags: [RootEffect, WriteDirEffect, ReadDirEffect, WriteIOEffect],
    forbids: [].}
ctrl+c raises minline.InputCancelled to the caller; ctrl+d aborts the program. Empty input keeps re-prompting.
proc sessionPreamble(cwd: string): string {....raises: [OSError, IOError], tags: [
    ReadEnvEffect, ReadIOEffect, TimeEffect, WriteDirEffect, ReadDirEffect,
    ExecIOEffect], forbids: [].}
Build a one-shot context block to prepend to the first user message of a fresh session: cwd, git state, top-level listing, AGENTS.md content.