Part of the runner protocol. docs/protocol.md has the rules for all of it and which file each section is in.
// cursor, opencode, grok and antigravity (Gemini on a Google plan): ACP
// agents, where their CLIs are installed and logged in (see "ACP agents")
type Provider = "claude" | "codex" | "cursor" | "opencode" | "grok" | "antigravity"
// What a provider is called and can do, from `hello`. A client asks this
// rather than comparing provider names, so a provider it has never heard of
// still gets the right menus.
type ProviderInfo = {
id: Provider
name: string // "Claude": in notes and menus
cliName: string // "Claude Code": the program, in notes about its versions
loginCommand: string // run in a Terminal to sign a login in ("claude auth login")
effort: "claude" | "codex" | "none" // which effort levels it offers: Claude's,
// those plus Codex's ultra, or none of Threadbear's own
// (Grok: "codex", each model's effortLevels narrowing it)
autoMode: "classifier" | "asks" // Auto: a classifier judges each action, or
// it behaves like Ask (Codex)
rewind: boolean // can go back to an earlier message
smallJobs: boolean // can run small jobs (titles, summaries)
usageReadings: boolean // reports how much room a login has
}
type Account = {
id: string // "claude-main", "claude-1", "codex-main", "codex-1", ...
provider: Provider
title: string // Claude: the email when known, else the id. Codex:
// "Codex · <email>", so an app that only reads title
// can tell it from a Claude login with the same address
configDir: string
defaultModel?: string // full id of the model a thread with no model runs on
// ("claude-fable-5-1"): the account's own setting
// (Codex: config.toml's model, else the model list's
// default), corrected by the first turn the runner
// sees. Absent until the runner knows
models?: ModelChoice[] // what the account's CLI offers, in its own order,
// once the runner has asked it (a few seconds after
// it starts). Codex: its model list without hidden models
defaultEffort?: EffortLevel // the account's own level (Codex: config.toml's
// model_reasoning_effort). Absent: each model's own
email?: string // the bare address, when known
plan?: string // "Max", "Team", "Pro Lite"
note?: string // Mike's own note for the account ("Convex work only")
usage?: AccountUsage // absent when nothing is known (and from older runners)
signedOut?: boolean // Claude: no turn can run on it until someone signs it
// in again (see "Signed out" under Pools). Pools skip it
loginEndsAt?: string // Claude: when this sign-in ends and can't be renewed
// (28 days after signing in, from Claude Code 2.1.325).
// Clients warn a few days ahead
yearToken?: { madeAt?: string } // Claude: runs on a year-long token
// Mike made for it, not its 28-day sign-in ("Year-long
// tokens", below). madeAt is when; loginEndsAt is a
// year on. The token itself is never sent
planEnded?: boolean // Claude: its paid plan has lapsed. The CLI's cached
// claude.ai profile (oauthAccount in the login's
// .claude.json, fetched again at most daily while the
// CLI runs on it) says organizationType claude_free,
// or a Pro or Max plan with billingType none (a lapsed
// Max still cached as claude_max). The free plan has
// no Claude Code. Its plan and usage are
// left out (a stale reset would promise room that
// isn't coming). Pools and the default account skip
// it; clients say "Plan ended", and offer no sign-in
// or reset for it
}
// "ultra" is Codex's multi-agent level. Claude never offers it.
type EffortLevel = "low" | "medium" | "high" | "xhigh" | "max" | "ultra"
type ModelChoice = {
id: string // what to send as `model` ("opus", "claude-fable-5-1[1m]", "gpt-6-luna")
model: string // the full id it runs as ("claude-opus-5-5")
title: string // "Opus 5.5"
description?: string
effortLevels?: EffortLevel[] // absent when the model takes no effort level
defaultEffort?: EffortLevel // the model's own level, when the CLI says (Codex)
}
type UsageWindow = {
kind: "five_hour" | "weekly" | "weekly_model" | "daily" | "monthly" | "allowance" | "other"
title: string // "5-hour", "Weekly", "Weekly Fable", "$250 allowance"
remainingPercent: number // 0 to 100, may be fractional
resetsAt?: string
detail?: string // "$132.79 left"
}
type AccountUsage = {
windows: UsageWindow[]
readAt: string // when the newest reading in it was taken
source: "tokenStats" | "live" // where the newest reading came from: Token
// Stats' limits.json, or the account's own turns
stale?: boolean // Token Stats hasn't written for 15 minutes and
// there's no live reading since
blocked?: boolean // the provider says this login is at its limit
notice?: string // Token Stats' own note ("64,390 credits · 2 limit resets available")
resets?: { available: number, nextExpiresAt?: string } // Codex: the usage
// resets it has left, from its last read (Pools,
// "Usage resets"); left out once the soonest has expired
}
type CliStatus = {
provider: Provider
path: string // the binary new sessions start
managedBy: "threadbear" | "cli" | "none" // Codex: Threadbear's own copies;
// Claude: its own installer; "none": codexPath set by
// hand, never updated
installedVersion?: string // what new sessions start on
latestVersion?: string
canUpdateNow?: boolean // an ACP agent: no version feed, so the row offers an
// update on demand (`clis.update`) and never updates by itself
status: "current" | "behind" | "held" | "unknown" | "missing"
policy: "auto" | "notify" | "off"
inUse: { version: string, threadIds: string[] }[] // versions live sessions run
previousVersion?: string // Codex: the kept version "Go back" returns to
checkedAt?: string
hold?: { version: string, reason: string, missing?: string[],
threadId?: string, investigating?: boolean } // why an
// update wasn't installed by itself ("the app-server
// protocol changed", with what it lost). A protocol
// hold starts a thread that looks into it (threadId;
// investigating while it's open), and is checked
// again once per runner start, so the landing that
// fixes it installs the version by itself
update?: { // the latest update, while it runs and after
state: "waiting" | "running" | "succeeded" | "unchanged" | "failed"
targetVersion?: string
waitingFor?: string[]
finishedAt?: string
message?: string
}
}
// A named, ordered list of logins (see Pools).
type Pool = {
id: string // "claude", "codex", "convex", or a slug Mike made
title: string // "Claude"
accountIds: string[] // in order; may mix providers
folders?: string[] // ~ allowed; a new thread under one starts on this pool
icon?: string // an SF Symbol name Mike picked ("leaf"); absent, the app picks one
builtIn?: boolean // from the code default, not runner.json
}
type ThreadStatus =
| "idle" // no turn running (CLI may or may not be live)
| "starting" // CLI spawning or resuming
| "running" // a turn is in progress
| "waiting" // blocked on an approval or a question
| "error" // last turn failed; can still send
| "stopped" // runner restarted mid-turn
type ThreadSummary = {
id: string
title: string
cwd: string
accountId: string // the login it runs on now (a pool thread's can change; see Pools)
poolId?: string // the pool that picks its login. Absent: pinned to accountId
waitingForRoom?: { until: string, accountId?: string } // every login in its
// pool is out of room; it carries on by itself at
// `until`. accountId: the login it's waiting on
carryOnAtReset?: false // Mike turned off carrying on by itself after a
// limit (Pools, "Waiting"). Absent: on
waitingForNetwork?: { since: string } // its last turn couldn't reach the
// API; it carries on by itself once the runner
// reaches it again (Pools, "A turn that lost the
// network"). since: when the line first went
provider: Provider // always the account's provider
model?: string // undefined means the account's default
effort?: EffortLevel // undefined means the model's own level
modelInUse?: string // full id the CLI ran the last turn on, once one has run
effortInUse?: EffortLevel // the level the CLI reported for the last turn
permissionMode: "full" | "ask" | "auto" | "plan" // "plan": Plan first
status: ThreadStatus
live: boolean // a CLI process is attached right now
needsYou: boolean // waiting, or a turn finished after lastSeenSeq
// that didn't end with needs "nothing", with no
// sub-agents still working (Needs you)
needs?: "you" | "nothing" // what the last completed turn said; absent
// when it said neither (see Needs you)
asks?: OpenAsk[] // that turn's asks, when needs is "you"
asksSeq?: number // seq of the turn.completed they came with
createdAt: string
updatedAt: string
lastActivityAt: string
snoozedUntil?: string
snoozedUntilRestart?: true // hibernating until the runner next starts;
// snoozedUntil is then 9999-12-31T00:00:00.000Z
snoozedUntilRelease?: true // with snoozedUntilRestart: only a start on
// another release than the one it went to sleep on
wakeWhen?: { said: string, topic?: string, pending?: true, agent?: true }
// hibernated in Mike's words (Hibernate in words);
// only while snoozedUntil is set. `agent`: its own
// agent set it (end_turn's snooze); with an
// "unlanded" loose end it's waiting to land, and
// the sidebar puts it under Running
waitingOn?: { threadId, title, until?, done?: true }[] // hibernating until these
// threads finish (end_turn's waitFor); only
// while snoozedUntil is set
awaitingAppRestart?: true // hibernating until the Mac app restarts onto
// what this thread landed (wait_for_app_restart);
// only while snoozedUntil is set. With an unfinished
// waitingOn, the sidebar puts it under Running.
startedBy?: { kind, label, icon?, threadId?, threadTitle?, why? } // who
// started it when Mike didn't (Who started a thread)
detached?: true // a thread another thread started that doesn't
// nest under it in the sidebar (Nested threads)
asked?: string // Mike's last message to it, one line, <= 140 chars
// (What Mike last asked)
request?: string // Mike's first message to it, one line, <= 200
// chars (What Mike first asked)
keywords?: string // the librarian's search words, lowercase and
// space-separated, <= 200 chars (Search)
woke?: { at: string, since?: string } // came back from hibernating by
// itself (its time, a restart, a topic) at `at`,
// put away at `since` when known; only until Mike
// looks (threads.markSeen) or sends to it. The wake
// also adds a system.note ("Woke up after
// hibernating for a day.") Mirrored to the phone's
// row from backend API 13
archivedAt?: string
archivedBy?: "mike" | "agent" | "threadbear" // who archived it; only
// while archivedAt is set (Who archived a thread)
archiveVerdict?: "worked" | "didntWork" | "notNeeded" | "didntNeedToSee" | "gladISaw" | "notSure" // how it went, Mike's
// pick from the done card's Archive menu
starredAt?: string // Mike starred it, at this time: it stays in the
// Starred section above the Inbox, hibernating or
// not, oldest star first. Kept while archived, when
// it's under Archived, so bringing it back stars it
onOldRunner?: true // finishing a turn on the runner that handed over
// (Handovers); moves across when the turn ends
preview: string // last assistant text, one line, <= 140 chars
lastSeq: number // seq of the newest persisted event
lastSeenSeq: number
nativeSessionId?: string
contextTokens?: number
contextWindow?: number // the model's context window, when the CLI reports it
// (Claude: its result's modelUsage, for the session's model)
costUsd?: number // total for the thread so far, if known (Codex reports none)
panels?: Panel[] // from the folder's patches (see Patches); absent when there are none
actions?: Action[] // likewise
hooks?: Hook[] // likewise
patches?: PatchInfo[] // the patches that apply to the folder; absent when there are none
background?: BackgroundTask[] // what the live CLI is still running in
// the background: sub-agents and shell jobs
// started with run_in_background, Monitor and the
// like, and ones just finished whose result the
// agent hasn't read yet. Absent when there's none.
// Set during a turn too; between turns it's the
// sign the thread is still being worked on
subagents?: Subagent[] // the sub-agents the agent has started, foreground
// and background: the newest 20, oldest first.
// Absent when it has started none
projects?: ThreadProject[] // the projects the thread is in (see Projects),
// oldest first. Absent when it's in none
highlightsAt?: string // when its highlights last changed other than by a
// new event: a pin, a removal, the librarian's
// brief (see Highlights). A client fetches
// threads.highlights again when this or lastSeq moves
sample?: true // one of the tour's sample threads (threads.samples):
// made up, and threads.send refuses it
worktree?: ThreadWorktree // the thread has a git worktree of its own
// (see Worktrees). Absent when it doesn't, or once
// it was removed
schedule?: { id: string, title: string } // the schedule that started the
// thread (see Schedules), with its title as it was
// then. Absent for one a person or agent started
panelRequest?: PanelRequest // a panel the agent asked to show Mike,
// waiting for him to look at the thread (see
// Showing panels). Absent when there's none
share?: ThreadShare // who else can read it on the website (see
// Sharing). Absent until it's first shared
}
// A thread's own worktree, as its summary shows it (see Worktrees).
type ThreadWorktree = {
branch: string // "thread/ab12cd34"
mainCheckout: string // the checkout with main checked out, where it lands
path: string // the worktree's root folder
}
// A project a thread is in, as its summary shows it.
type ThreadProject = {
id: string
title: string
by: "mike" | "agent" | "librarian" // who put it there
pinned?: boolean // Mike put it there (or an agent was told to): the
// librarian won't take it out
at: string // when it was put there
why?: string // why it's there, a short line: the librarian's
// reason ("Shortlists photos for the calendar
// entry"), newest look's wins. Highlights shows it
// behind the project's ⓘ
}
type Action = {
id: string // "<patch>.<slug of the title>": "reseed.reseed-dev-db"
title: string
kind: "command" | "prompt" | "url"
command?: string // kind "command": run by `actions.run`, in `folder`
prompt?: string // kind "prompt": sent to the thread as a message by `actions.run`
url?: string // kind "url": an http or https page (normalised). The
// client opens it itself, on the device it was pressed
// on: no RPC, nothing in the transcript. The phone
// gets these through Sync (`links`) An older
// client reads the unknown kind as a command and
// calls `actions.run`, which opens it on the runner's
// Mac and answers `{ ok: true, durationMs }`
patch: string
folder?: string // where the command runs: the project folder the
// patch came from. Absent: the thread's own folder
projectId?: string // the project whose folder gave it (see Projects)
note?: string
icon?: string // an SF Symbol for the chip: the action's own `icon`,
// else its patch file's; absent: the client's default
badge?: number // see Patches, "Live state"
}
type Hook = {
id: string // "<patch>.<slug of the title>"
title: string
on: "turn.end" // when it runs: after a turn the agent completed (not one it was interrupted in, or failed)
command: string // run in `folder`, as an action's command is
exec?: string // for a patch trusted by its hash: what the runner
// really runs, `command`'s script by absolute path
// (see "Trusting a folder's patches"); show `command`
edited?: string // only after a turn that edited a file matching this glob, relative to `folder` ("**/*.ts")
tell: "failures" | "always" | "never" // when its result is sent to the agent as a message (see Patches)
patch: string
folder?: string // as Action's; a hook from a project folder only
// sees edits inside that folder
projectId?: string
note?: string
}
type PatchInfo = {
id: string // "convex", "xcode", or a patch file's name without its extension
source: "builtin" | "home" | "project" | "claude" // claude: the thread
// folder's Claude Code settings, listed only while
// they're waiting (see "Trusting a folder's Claude
// Code hooks"); a client that doesn't know it shows
// it as a project's
file?: string // the module, for home and project patches
folder?: string // set (with projectId) when it came from one of
// the thread's projects' folders rather than its
// own: the folder holding `.threadbear/`, or a
// built-in's project folder
projectId?: string
error?: string // the file couldn't be loaded, and gives nothing until it's fixed
untrusted?: "new" | "changed" // a project's patch file that isn't trusted yet, so
// wasn't loaded and gives nothing: "new" when nothing
// from its folder is trusted, "changed" when an earlier
// version was (see "Trusting a folder's patches")
hash?: string // with untrusted: the version patches.trust would trust
helpers?: string[] // with untrusted: the local files it imports or names
// (absolute), whose text the hash covers too
changes?: { // with untrusted "changed": what differs from the version
// last trusted there (see "What changed"). Says only
since?: string // ISO time that version was trusted
recheck?: true // only hashes from before 6 Nov's version 3 there
files?: { path: string; was: "changed" | "added" | "removed";
commits?: { sha: string; subject: string }[]; moreCommits?: number;
uncommitted?: true; diff?: string }[] // path from the folder holding
// .threadbear/; diff: "- ", "+ ", " " lines, "…" between hunks
}
editsAsk?: string // a patch that loads without a hash runs something
// Threadbear can't follow, so threads in Ask and Auto
// ask before every file edit: which, why, and what to
// change (see "Agent writes that run as code")
}
type Panel = {
id: string // unique within the thread: "convex.dashboard", "xcode.simulator"
title: string // the tab's label
kind: "url" | "image" | "list" // a page in a web view, a picture the runner
// draws on request, or rows the runner gets from the
// patch on request (see Patches)
url?: string // kind "url": the page; also what Open in browser opens
icon?: string // an SF Symbol name for its button on the right-hand
// rail; absent: the client picks one by kind
patch: string // the patch it came from: "convex", "xcode"
projectId?: string // as Action's
note?: string // one line about it: the deployment, the project
convex?: { // the built-in Convex panel for a cloud deployment:
deployment: string // its name, "happy-otter-123"
deploymentUrl: string // "https://happy-otter-123.convex.cloud": only
// ever the deployment's own <name>[.<region>].convex.cloud,
// as it's handed a deploy key and comes from an env
// file a cloned repo writes; any other URL, a custom
// domain included, gets no `convex`
team?: string // "mike" and "walkies": what `convex dev` notes
project?: string // after CONVEX_DEPLOYMENT in .env.local, if it did
} // a client that knows it shows Convex's embedded
// dashboard with panels.convexKey (see "The Convex
// panel"); one that doesn't shows `url`
from?: string // a panel button's (see Reply buttons): the folder
// whose patch it is, as the thread isn't there
}
// One row of a `list` panel (panels.render).
type PanelItem = {
title: string
detail?: string // grey, under the title, up to two lines
url?: string // a click opens it in the browser, or the panel if Mike set "Default"
path?: string // a click previews the file in the pane
icon?: string // an SF Symbol name
tone?: "attention" | "failed" | "warning" | "working" | "done"
// each its own shape and a colour a red-green colour-blind
// eye tells apart (issue #67): an orange circle, a rose
// diamond, a yellow triangle, a turning blue arc, a blue
// tick; absent: plain. A client that doesn't know a tone
// draws the row plain
section?: string // a heading over this row and the ones after it with the same
// section, drawn where it changes ("Waiting · 1"); at most 80 characters
trailing?: string // short and faint at the end of the title's line, like a date
// ("5d"); at most 24 characters
toggle?: { // a switch drawn as an icon at the end of the title's line, lit
// when on and faint when off; a press sends panels.toggle. Only
// on rows of a panel whose patch has a `toggle` function (see
// Patches, "Row toggles"); dropped from any other panel's rows
id: string // what panels.toggle hands back; at most 200 characters
on: boolean
icon?: string // an SF Symbol name; absent: "power"
title?: string // its tooltip ("Auto-fix #812"); at most 80 characters
}
}
// A grouping above folders that carries goals, state and notes forward
// (see Projects).
type Project = {
id: string // "p_" and 8 hex characters
title: string
folders: string[] // absolute paths, in the order patches load from them
goals: string // a few lines: what it's for, what done looks like
state: string // a few lines: where it's up to, what's next
notes: string // markdown: decisions, gotchas, commands, links
links: ProjectLink[] // the places Mike goes for it, at most 8 (see
// Projects, "Links"); [] from a runner before them
createdBy: "mike" | "agent" | "librarian"
createdByThread?: string // the thread whose agent or look made it
titleBy?: "mike" | "agent" | "librarian" // who last named it; absent
// on older projects, where createdBy stands in
createdAt: string
updatedAt: string
stateUpdatedAt?: string
archived?: boolean
icon?: ProjectIcon // absent until the librarian has found or picked one
parentId?: string // the project it's a part of (see Projects,
// "Parts"); absent for a project of its own, and
// from a runner before parts
threadCount: number // threads in it, put away ones included
lastActivityAt?: string // its newest thread's lastActivityAt
}
// A place Mike keeps going back to for a project: its live site, admin
// page, dashboard, store listing or repo.
type ProjectLink = {
title: string // short: "Live site", "Admin"; the host when not given
url: string // http or https
}
// A project's icon: a picture, else an SF Symbol (see Projects, "Icons").
// A client that can't draw either shows the title's first letter.
type ProjectIcon = {
image?: ImageRef // a copy in the runner's data dir (project-icons/),
// PNG at most 256 px, or SVG ("image/svg+xml")
symbol?: string // an SF Symbol name, when there's no picture
from?: string // the file the picture was copied from
by: "mike" | "agent" | "librarian" // librarian: found by itself and kept
// up to date; mike or agent: chosen, and left alone
// until set back to automatic
updatedAt: string
}
// What the librarian (see Projects) is doing, has done and will do next.
type LibrarianStatus = {
state: "idle" | "working" | "paused" | "off"
reason?: string // state "off": why ("Needs a Claude pool to run
// on", "Every login in Claude is out of room",
// "Model calls are off")
paused: boolean // Mike paused it; looks wait in the queue
current?: LibrarianJob & { startedAt: string } // the look under way
queue: LibrarianJob[] // what it will look at next, soonest first
recent: LibrarianEntry[] // what it did, newest first, the last 50
looksToday: number
spentTodayUsd: number // always 0 (it runs on the pool); kept for older apps
skippedToday?: number // quiet catch-ups skipped without a model call
tokensToday?: number // tokens in and out, every look and icon pick
notionalTodayUsd?: number // what the pool's calls would have cost on
// the API; they use logins' room, not money
}
type LibrarianReason =
| "first-message" // a new thread's first message came in
| "first-turn" // a thread's first turn ended
| "new-folder" // a turn edited files outside the thread's projects' folders
| "moved" // the thread changed folder
| "catch-up" // more turns since its last look (at most hourly)
| "asked" // librarian.run, or a backfill
| "notes" // a project's notes went past 12,000 characters and
// were rewritten shorter (an entry only: threadId is
// "", projectIds has the project; the old notes are
// kept in <data dir>/project-notes, the last 5 each)
type LibrarianJob = {
threadId: string
threadTitle: string
reason: LibrarianReason
why: string // the reason in words: "Edited files in ~/dev/me/poddle"
dueAt: string
}
type LibrarianEntry = {
id: string
at: string
threadId: string
threadTitle: string
reason: LibrarianReason
outcome: "joined" | "created" | "updated" | "left" | "nothing" | "skipped" | "failed"
text: string // "Put it in Threadbear", "Made Poddle and put it there",
// "Threadbear's state", "No key", the model's error
projectIds?: string[]
reasons?: Record<string, string> // why it joined each project, by id; only
// on a look that filed the thread somewhere
why?: string // that look's line overall
costUsd?: number
}
// A sub-agent the thread's agent started (Claude's Agent tool). The runner
// follows it from the CLI's task events, so it changes while it runs: each
// change sends thread.updated. `threads.subagent` reads what it did.
type Subagent = {
id: string // the CLI's id for it (its task id)
itemId?: string // the tool.call that started it, in the thread
parentId?: string // the sub-agent that started this one, when it was
// started by a sub-agent rather than the thread's agent
description: string // its brief's title: "Review the runner changes"
agentType?: string // "general-purpose", "Explore", "fork"
model?: string // the model it runs on, from its own replies
// ("claude-opus-5-5"); absent before its first one.
// The latest reply's, as a fallback can take over
effort?: string // its effort level ("high"), filled in once
// threads.subagent has read its transcript
status: "running" | "completed" | "failed" | "stopped"
// clients treat a status they don't know as stopped
background: boolean // the agent carried on while it ran
activity?: string // while running, what it's doing in the CLI's own
// words ("Running npm test")
summary?: string // once finished, what it reported, one line, <= 200 chars
toolUses?: number // tool calls so far
startedAt: string
endedAt?: string // set once it's no longer running
}
type BackgroundTask = {
kind: "agent" | "shell" | "monitor" | "other" // a sub-agent, a shell
// command, a Monitor, or anything else the CLI
// runs in the background (a workflow). Clients
// treat a kind they don't know as "other"
description: string // the CLI's own words: the sub-agent's brief, the
// command. May be empty
finished?: boolean // true once it has finished and the agent is about
// to start a turn of its own to read its result
// (the runner counts it for up to 15 s, until that
// turn starts)
}
type ImageRef = {
path: string // absolute path on this Mac
mediaType: string // "image/png", "image/jpeg", "image/gif", "image/webp"
width?: number
height?: number
}
type Schedule = {
id: string
title: string // for lists; default the first line of text
text: string // the message it sends each time
at?: string // a one-off: when it runs
cron?: string // or repeating: a 5-field cron ("0 9 * * 1-5"), or
// @hourly, @daily, @weekly, @monthly, @yearly
timezone?: string // IANA zone the cron is read in; absent means the
// Mac's own zone, whatever it is at the time
whenText: string // "Weekdays at 9:00", "Once, Tue 28 Oct at 15:30":
// the runner's words for at/cron, for every client
threadId?: string // sends to this thread. Absent: starts a new thread
// each time, with the settings below
cwd?: string // new-thread settings, as in threads.create
accountId?: string // pins each thread to this login
poolId?: string // or this pool picks the login each run (see
// Pools); never both. Neither: the folder's pool,
// as threads.create picks it
model?: string
effort?: EffortLevel
permissionMode?: "full" | "ask" | "auto" // absent: the runner's
// defaults.permissionMode when it runs, else full
defaultMode?: "full" | "ask" | "auto" | "plan" // set by the runner on a
// new-thread one with no permissionMode that runs
// here: the mode it inherits. Absent for another
// runner's, whose default isn't known here. An Ask or
// Auto thread raising a schedule's mode is checked
// against this; one not known counts as Ask for
// raising it and Full for what its runs reach.
// Never stored.
paused: boolean
createdAt: string
updatedAt: string
createdBy?: string // the thread whose agent made it; absent for a person
nextRunAt?: string // absent while paused, or once a one-off has run
finishedAt?: string // a one-off that has run (kept for 7 days, then dropped)
runs: number // how many times it has sent its message
lastRun?: {
at: string
outcome: "sent" | "skipped" | "failed"
threadId?: string // the thread it sent to or started
note?: string // why it was skipped or failed
}
runnerId?: string // the runner it runs on (see Schedules, "Runners").
// Absent from a runner whose schedules are its own
// file: then it's that runner
runnerName?: string // that runner's name, as runners.list has it
runnerIcon?: string // and its icon (RunnerInfo.icon)
runRequestedAt?: string // a schedules.run for it waits for its runner
}
// A runner Threadbear knows of, from the backend (runners.list).
type RunnerInfo = {
id: string
name: string // "m5", "bruce": the Mac's hostname by default
icon?: string // an SF Symbol for its Mac: "laptopcomputer",
// "macmini", "macstudio", "macpro.gen3" or
// "desktopcomputer", from the model macOS names
// (runner/src/machine.ts), or sync.icon in
// runner.json. Absent from a runner before icons;
// a client draws a symbol it lacks as the desktop
online: boolean // heard from in the last 3 minutes
lastSeenAt?: string
self: boolean // the runner answering
// What its last heartbeat said, for the app's Runners panel. Absent from
// an older runner.
version?: string // RUNNER_VERSION
release?: string // the release it runs (release.ts), when it runs one
startedAt?: string // when that runner process started
draining?: boolean // an old release finishing its threads in a handover
}
// The runner's settings, as the Settings window shows them. Everything here
// is kept in runner.json except the key, which only the runner ever reads.
type Settings = {
defaultCwd: string // where a new thread starts when it names no folder
idleMinutes: number // a CLI with no turn for this long is released
maxLiveCLIs: number // most CLIs kept live at once
followMain: boolean // build and restart onto main by itself; a change
// takes effect when the runner next restarts
bulletReplies: boolean // a turn's reply is end_turn's bullets; false: the
// agent's own message (see "The summary")
oneReply: boolean // end_turn first, then the agent's message as the
// reply (see "Needs you", One reply); on by default
labReview?: boolean // review a code change on the other provider
// before the thread is done (Review by another
// lab); on unless runner.json has labReview: false.
// Absent from an older runner, where it was an
// experiment, so a client shows no switch
labReviewers?: { provider: Provider, model?: string, effort?: EffortLevel }[]
// who reviews, in order (Settings > General > Code
// review > Every change): the first of another lab
// with a login that has room, on its model and
// effort when it names them. A provider may come
// more than once on different models.
// runner.json's labReviewers, else Codex then Claude.
// Absent from an older runner: no list to show
labPanel?: { provider: Provider, model?: string, effort?: EffortLevel }[]
// the review panel (Code review > Big or risky
// changes), which reviews a big or risky change all
// at once (Review by another lab); [] for none.
// runner.json's labPanel, else the entries of an
// older runner.json's labReviewers ticked
// panel: true. Absent from an older runner, which
// sent those ticks in labReviewers instead
labPanelLines?: number // lines of code that make a change big (150)
keepAwake?: boolean // keep the Mac out of idle sleep while threads
// work (keep-awake.ts); on by default, sent only by
// a runner on a Mac, so clients show no switch
// without it
bringIn: number | "important" | "off" // a fork: how often a thread starts
// to bring in Mike's releases, in days (1 to 365;
// 5 by default), only for important ones, or never
// (runner.json releases.bringIn; "Mike's releases")
spareWeek?: boolean // a thread suggesting work when a login's week is
// about to go unused (runner/src/spare-week.ts);
// runner.json spareWeek, on unless false. Absent
// from an older runner: clients show no switch
fullSync: boolean // full sync, as runner.json's sync.full says; it
// takes effect when the runner next starts
// (docs/convex-backend.md, "Full sync"; `tb settings full on|off`)
models: {
pool: string | null // the pool whose Claude logins answer small
// jobs; "claude" by default, null: none, so
// no titles or librarian
privateFolders: string[] // folders (and everything under them) whose
// text is never sent; "~/" paths as written
}
}