The names that only the agent or only the config uses start with agent
or config: the instructions file of the agent and the endpoint values of
config.json. Config and ModelConfig stay generic, because the daemon,
the probe, the model client, and the compactor read them.
The data directory is in datadir.go, with its tests in datadir_test.go,
because the login, the terminal client, the daemon, and the probe use
it, and it is not a part of config.json. The declarations of these files
follow the order of the go-code skill. The behavior does not change.
Every package-level name that only the compactor uses starts with
compactor: its limit of tries, the ruler, the task text, the note on a
long line, and the helpers that cut a line and pick the shortest one.
Names such as ruler and shortest read as helpers of the whole program,
but only the compactor uses them.
The declarations of the compactor files follow the order of the go-code
skill. The behavior does not change.
Every package-level name of the tools starts with tool: the Toolbox, its
interfaces ToolLog and ToolChat, the argument types, the head and tail
buffer, and the clip helpers. The interfaces chatLog and chatReader read
as parts of the chat, but only the tools use them.
The declarations of tools.go follow the order of the go-code skill. The
behavior does not change.
The function tools that every model call sends are promptTools, and
their schema helpers start with prompt too. The turns and the
compactions send the same prompt and tools, so the tools are a part of
the prompt, and agentTools read as the tools of an agent next to the
agent config. The parts of the prompt text, such as the task sentence
and the clause on the instructions, start with prompt as well.
The declarations of prompt.go already follow the order of the go-code
skill. The behavior does not change.
Every package-level name of the probe starts with probe: its run
ProbeRun, the summarizer ProbeSlotSummarizer that limits the builds at
once, the reader of its log and of the usage file, and the parts of its
report. Names such as ratio, timeText, and modelLines read as helpers of
the whole program, but only the probe uses them.
The declarations of the probe files follow the order of the go-code
skill. The behavior does not change.
The queue of the node builds is BuildQueue in build_queue.go, and its
other names start with build: buildMax and buildLeafWindow are its
limits, and BuildMergeHeap holds its merges. The Telegram bot has a
queue of events too, so a bare queue does not tell which one it is.
The declarations of the queue file follow the order of the go-code
skill. The behavior does not change.
Every package-level name of the view starts with view: its size limits,
the pending mark, the saved state ViewState, and the interface
ViewNodeReader. The layout of the view messages in the turn requests is
in view_layout.go, as ViewLayout. The limits chatHigh and compactionHigh
read as limits of the chat and of the compactor, but they are limits of
the two views.
The declarations of the view files follow the order of the go-code
skill. The behavior does not change.
Every package-level name that only the turn loop uses starts with turn:
the loop is TurnLoop, its function call items are TurnFunctionCall and
TurnFunctionCallOutput, and its error of a log write is errTurnLogWrite.
Event stays generic, because the daemon, the terminal client, and the
Telegram bot read the events too.
The declarations of the turn files follow the order of the go-code
skill. The behavior does not change.
Every package-level name that only the daemon uses starts with daemon:
its hub of socket clients is DaemonHub, a connected client is
DaemonClient, and the loop that serves the agent is daemonServe. So a
client of the socket does not read as the model client or the Bot API
client.
What the daemon and the terminal client share is in socket.go: the
socket file, the size limits, the request type SocketRequest, and the
check of the socket path. The file locks that the log, the daemon, the
login, and the probe share are in lock.go, with their test in
lock_test.go. The declarations of these files follow the order of the
go-code skill. The behavior does not change.
Every package-level name of the terminal client starts with terminal,
and its file is terminal.go, with its tests in terminal_test.go. The
client runs the command "onechat chat", but in the code the chat is the
chat of the agent, with its log, tree, and views, so the prefix names
the client by its kind.
The stop command is in stop.go and the test buffer in buffer_test.go,
because the terminal client and the Telegram bot use them both. The
declarations of the terminal files follow the order of the go-code
skill. The behavior does not change.
Every package-level name of the ChatGPT login starts with chatgpt, and
its file is chatgpt.go. The login has an issuer, a client ID, a token
file, and a poll interval, and the prefix keeps these names apart from
the names of the Telegram bot and the model client. The client ID
constant does not name another program.
The declarations of the login files follow the order of the go-code
skill. The behavior does not change.
Every package-level name of the client that sends the model calls starts
with model, and its file is model.go. The client talks to the ChatGPT
backend or to the OpenAI API, so the name tells its role and not one of
the endpoints. The interface of the turn loop that the client satisfies
is TurnClient, so it does not take the name of the client. The fake
output items of the tests are in model_test.go, next to the other fakes
of the endpoint.
The declarations of the model files follow the order of the go-code
skill. The behavior does not change.
Every package-level name of the Telegram bot starts with telegram, and
its files start with the same name: the Bot API client is in
telegram_api.go and the Markdown conversion in telegram_markdown.go. So
the names of the bot do not read as names of the model client or of the
login, which also have a client, an API, and a poll. Type names start
with a capital letter, so that a variable can have the name of its type.
The declarations of the Telegram files follow the order of the go-code
skill: entry points, then each type with its methods, then the utility
functions, each group in the order of first use. The behavior does not
change.
The go-code skill now asks for type names with a capital letter and for
all other package-level names in lower case. A lower-case type name
clashes with an import, such as a log type with the log package, and
with local variables that have the name of their type, such as a memory
variable of a memory type. A capital letter keeps both names free.
The bot sends each model reply with sendRichMessage and the Markdown of
the reply unchanged, so Telegram renders the tables and the other blocks
itself. Message entities have no tables, so a table showed as lines of
pipes. A reply over the limit of a rich message goes as more than one
rich message, split between blocks with splitRich.
When the Bot API answers ok false with HTTP 400 or 404, the reply was
not sent, so the bot sends the same Markdown once with the entity path:
markdownEntities, splitEntities, and sendMessage. The fallback logs one
line with no text of the reply. Every other failure gives no fallback: a
network error, HTTP 429, and HTTP 5xx wait and try the rich message
again, and any other failure drops the reply with one log line. The send
timeout applies to each sendRichMessage call.
The notices of the bot, the errors, and the messages from the terminal
stay plain text with sendMessage. The log and the terminal client do not
change.
The go-code skill now asks for a feature prefix on each package-level
name that belongs to one feature or integration, and on the names of its
files. A name stays generic only when more than one feature uses it. All
the code is in one main package, so every name is visible in every file,
and generic names such as a client, a request, or a poll interval of one
service read as if they belong to all of them.
The skill also asks for unexported names, because an exported name has
no effect in a main package, and for initialisms in one case.
splitRich cuts the Markdown of a reply into parts of at most 32768
bytes, the limit of the Markdown of one rich message. It cuts after a
blank line outside a code block, so a table, a code block, and a
paragraph stay whole, and each part renders as the reply would. When no
such cut fits, it cuts after a line break outside a code block, and then
inside a code block, which it closes at the end of the part and opens
again with the same fence line in the next part. A single line over the
limit is cut at the limit, never inside a character.
The Bot API allows 32768 characters of rendered text and does not say if
a character is a byte. The bytes of the Markdown are at least the
characters of the text, so a part is never over the limit. The bot does
not use splitRich yet.
The Bot API client sends Markdown as a rich message with
sendRichMessage, which Telegram renders itself, tables included. The
call has the same send timeout as sendMessage, so a stalled connection
fails with a network error that the sender can try again.
A botError now tells if the answer is a Bot API answer with ok false,
and rejected tells if such an answer has HTTP 400 or 404. Then the call
did nothing, so the sender can send the same content another way with no
risk to repeat it. An error page of a proxy with HTTP 404 is not a Bot
API answer, so it is not a refusal.
The bot converts the Markdown of each model reply to text and message
entities, and sends them with the entities field of sendMessage, with no
parse mode. The phone then shows bold text, code and code blocks
formatted, not their marks. A reply longer than 4096 UTF-16 units is
split as before, and an entity that crosses a cut becomes one entity in
each part, with offsets from the start of its part.
When Telegram refuses a part with entities with HTTP 400, the bot sends
the same text again once with no entities and logs one line without the
text, so a bad entity does not lose a reply. Other failures wait and try
again as before.
Only the replies get entities. The notices of the bot get their own
event kind, so they stay plain text with the errors and the messages
typed in the terminal. A reply with no text left after the conversion
goes as its Markdown. The log and the terminal client do not change.
A converter on the standard library turns the Markdown of a model reply
into plain text and Telegram message entities. It knows bold, italic,
strikethrough, inline code, fenced code blocks with an optional
language, links, and ATX headings, which become bold. Lists, quotes and
tables stay as their text. With entities, the text needs no escaping, so
a mark that does not close only stays as text, and it cannot make
Telegram refuse the message.
Inline marks do not cross a line break, so one open mark cannot change
the rest of a reply. Underscores inside a word stay as text, so
snake_case names do not turn italic, and an asterisk that a space
follows, as in a list item, opens nothing. Code holds no entity. The
offsets and lengths count UTF-16 code units, as Telegram does.
Each sendMessage and sendChatAction call gets its own limit of 30 s,
through a child context of the call. Before, only getUpdates had a
limit, so a connection that stopped without a close, such as after a
network change, held the sender until TCP gave up, and no reply, error
or typing action reached the chat in that time.
A call that times out fails with the same network error as the other
network failures, so the sender waits and tries again, and the error
text holds no token and no URL. The HTTP client keeps no timeout of its
own, because the long poll of getUpdates needs a longer limit. A stop of
the daemon still ends a call in progress at once, because the limit is a
child of the daemon context.
When telegram.json exists in the data directory, the daemon runs a
Telegram bot next to the socket clients. The file holds the bot token
and the user ID of the owner, and the daemon refuses it unless its mode
is 0600, because the token is a secret. The bot uses getUpdates long
polling only, so it needs no webhook and no open port.
The bot reads only the text messages of the owner in the private chat
and ignores every other update without a log of its content. Each text
goes to the agent as a user message from the source telegram, and /stop
interrupts the turn. A message that is not text gets the answer that
only text is supported. The chat gets the replies as plain text in parts
of at most 4096 UTF-16 units, the errors as short messages, and the
messages typed in the terminal with a mark. It shows the typing action
while a turn runs. Tool calls stay out of the chat, so the phone stays
readable and the bot stays far from the rate limit.
agent/telegram-offset.json holds the next update ID. It moves past an
update only after the message is flushed to the log, so a restart loses
no message. A crash between the flush and the offset write repeats that
message once, which the user accepts. A failed Bot API call waits and
tries again, as long as HTTP 429 asks or from one second up to a minute,
and never stops the agent. A failed write of a message or of the offset
stops the daemon, because the bot could then lose or repeat messages.
A small client of the Bot API, on the standard library only, waits for
new messages with getUpdates long polling, sends plain text with no
parse mode, and shows the typing action. It tells a failure that a later
try can fix, such as a network error, HTTP 429 with its wait, or a
server error, from one that it cannot.
The bot token is a part of each URL, and a net/http error holds the URL.
So no error of the client wraps a net/http error: it keeps only the text
of the cause, with the token removed. A test checks the error text of
each kind of failure for the token.
Each user message event names its source client. The socket clients
submit as terminal, and the terminal client shows a user message from
any other source with the source as a mark, such as "[telegram] text".
With more than one client on one agent, each client then shows the full
conversation, so a reply always comes with its question. The log does
not keep the source.
A signal is the normal stop of the daemon and of the terminal client, so
both exit with status 0 and print no error after Ctrl-C or SIGTERM. The
other commands still report a canceled context, because a signal there
stops an operation before it is done.
The daemon checks the length of the socket path first, before it reads
the config, takes the token lock, or opens the agent. With a data
directory whose path is too long, it gives the error and leaves the
directory empty, so a failed start leaves no agent or lock file behind.
onechat daemon owns the root agent in agent/ in the data directory: its
config, chat, compactor, and loop. It listens on the Unix socket
onechat.sock in the data directory, with mode 0600, and sends each event
to every client as a JSON line: ready with the agent's name on connect,
busy and idle around each turn, each logged message, and errors. A
client sends JSON lines too: send with a message, or interrupt. A slow
client is dropped, so it never stops the agent.
onechat chat is a line-based client without a terminal library. Each
input line is a message, the line /stop interrupts the turn, and the end
of the input ends the client. It shows the replies, the tool calls, and
the first 10 lines of each result as they happen.
The daemon, login, and probe each hold a lock on auth.lock in the data
directory while they run, so only one process reads and refreshes the
tokens. Two processes that refresh one token file rotate the refresh
token of each other and log each other out. The client never reads the
token file.
The first request of a turn reads the view of the turn before from the
prompt cache without a warm-up. In two live runs of 6 turns on a view of
about 31,000 tokens, turns 2 to 6 read 99.1% to 99.4% of their input
from the cache without the warm-up, and 99.3% to 99.6% with it. One call
per turn for about 0.1 points is not worth it, so the loop sends no
warm-up and the client does not stop a stream early.
The view messages that only grow stay. With the whole view in one user
message, turn 2 of a third run read nothing from the cache, and turns 3
to 6 read 99.2% to 99.5%. With the grow-only messages, each of the 10
later turns hit.
The ChatGPT backend writes a cache entry only at the end of the latest
message of a request, and a later request reads it only at one of its
own message ends. The first request of a turn now puts the stable parts
first and the per-turn state last: the prompt and the tools, then the
view as user messages, then a message with the end of the view and the
date, then each new message.
The view messages only grow between batches. layout.json in the agent's
directory keeps the line count and a hash of each view message sent. The
next request sends the same messages while their lines give the same
text, and the new lines follow as one new message. At the first message
that differs, such as after a batch merge, the rest of the view becomes
one new message.
After the turns, when the builds are done and no message waits, a
warm-up request sends only the prompt, the tools, and the view messages.
It ends at the view, where the next turn has a message end, so that turn
can read the view from the cache. The warm-up stops reading at its first
output item, after the input is read, to save output tokens, and its
output is never logged or used. Each usage record names the request of a
turn: first, next, or warmup.
A user message goes to the log when it comes and wakes the loop. A turn
waits until every build is done, so the view holds the summaries of the
messages before it. Its first request holds the prompt, the six tools,
and one user message with the view, the date and time of the turn, and
each new message whole. The view leaves out the leaf lines of the new
messages, but it keeps every other line, also the replies that came
after a message that waited.
The loop runs the tool calls of each response and sends their results
back until a response has no tool call. Each later request begins with
the whole previous input, then the output items with the encrypted
reasoning and without their ids, because the calls do not store them,
then the tool results. So each request of a turn begins with all of the
one before it. User messages that come during a turn join the next
request after the tool results, and a message that comes during the
final request starts a new turn. Replies, tool calls, and results go to
the log as they happen, and the reasoning never does.
An interrupt cancels the turn and kills a running tool. A failed call
ends the turn without a retry, and its messages stay in the log, so a
lasting failure does not repeat. Only a failed log write stops the loop.
The prompt gets a paragraph on persistent mode: a reply with no tool
call ends the turn, a question in the middle of a task does not end the
task, and "continue" resumes the latest unfinished task.
The agent gets four more tools after zoom and date: shell, read, write,
and edit. Turns and compactions send all six, so they keep one cached
prefix. shell runs a command with bash as the user in the working
directory of the agent, with no input and no sandbox, in its own process
group, so an interrupt kills the command and its children. read, write,
and edit take a path relative to the working directory or an absolute
one, and edit replaces a text that occurs exactly once.
Each call goes to the log as a tool message, the log is flushed, and
only then does the tool run, so the log never misses an action outside
the agent. The result goes to the log as an echo message. An interrupt
before the flush logs that the tool did not run. A tool error is the
output, so the model sees it.
Each output keeps its first and last 15,000 characters, 30,000 in all,
with a mark of the cut bytes between them. shell and read keep only the
ends while they read, so a long output does not fill the memory.
Each agent has its own directory with a config.json: the name, a random
ID, the model, the effort, and the working directory of its commands.
The first open writes the file with the defaults (OneChat, gpt-6.1-sol
at medium effort, the home directory) and a new 128-bit ID, and no later
open changes the ID. The prompt cache key comes from the ID, so a rename
keeps the prompt cache and two agents with one name do not share a key.
An unknown field is an error, and the ID must be there.
The user's instructions are in instructions.md in the agent's directory.
The prompt puts them at its end and gets back the clause of the
reference design that points to them. Without instructions the prompt
has neither, so it describes only what exists. The agent reads the file
on each call, and the compactor takes the prompt from the agent at each
build, so turns and compactions keep one cached prompt.
Each write of a chat still goes to the operating system at once, so a
crash of the process loses nothing. After each write, a background
syncfs of the file system of the chat starts unless one runs already,
and the next one starts when it ends. One sync makes every earlier write
durable, so a power loss loses at most the writes after the start of the
last finished sync, and there is never more than one sync at a time.
Memory.Flush returns when the writes before it are durable, so a caller
can make a tool call durable before the tool runs. A failed sync stays
and fails each later flush, because the kernel can drop the data of a
failed write back.
A crash can stop a write in the middle of a line. The open now cuts a
part of a line at the end of the last day file, whose write never
returned, and still refuses one in an earlier file.
golang.org/x/sys gives syncfs on every Linux architecture. The frozen
syscall package has no syncfs number on amd64.
A test kills a writer child process three times during writes of small
and large messages and finds every acknowledged message after each open.
A chat opens again after a crash between the build of a free leaf and
the save of the view. The catch-up adds the messages that the view does
not cover, and it now keeps a leaf that the tree holds already instead
of a second build of it, which the tree refuses as a duplicate. The
parent of such a leaf is settled at the start, with the other built
nodes.
A process that is killed during writes then opens again, so the log
loses no message that it acknowledged.
This reverts commits 4b9b226 and 56129a5. A compaction sends its view
again as one input part, followed by the task and, on a retry, the note.
The ChatGPT backend writes a cache entry only at the end of the latest
message of a request, and a later request reads it only at one of its
own message ends. Parts inside a message are not lookup boundaries, so
the blocks gave no cache hit. The entry of a compaction ends after its
task, which no later compaction begins with, so first tries miss with
any split of the view. A warm-up call per prefix would write a usable
entry, but it costs more than the misses, so the first-try misses stay.
Send the end of the view in one part with the task
The first try of a compaction sends the opening tag and each whole block
of four view lines as parts of their own, and then one last part with
the rest of the lines, the closing tag, and the task. The note of a
retry is the part after that. Joined, the parts are the same bytes as
before.
A pair check showed that a compaction whose view shares whole blocks
with an earlier one, but has its own rest part, reads nothing from the
cache, and that an exact repeat does. A rule that fits all results so
far: the ChatGPT backend stores a cache entry for a request without its
last part, and a later request reads it only if it begins with that
whole entry. With the end of the view in the last part, the entry of a
compaction ends at its last whole block, and a later compaction with a
longer view begins with it.
A compaction sends its view as separate input parts of the user
message: the opening tag, one part for each whole block of four lines,
and the rest of the lines with the closing tag. The task and the note
of a retry follow as parts of their own. Joined, the parts are the same
bytes as the single view part before, so the model reads the same text.
The views of two compactions end at different lines when builds run at
once, so before this change no two first tries sent the same view part.
With blocks, they send the same parts up to the last whole block that
both views have. This tests the hypothesis that the ChatGPT backend
reuses a cache entry only up to the end of an input part that both
requests have. The explicit cache breakpoints of the reference
implementation are not used, because the ChatGPT endpoint rejects both
prompt_cache_breakpoint and prompt_cache_options with gpt-6.1-sol.
onechat probe takes an optional BUILDS argument from 1 to 8, which
limits the builds that call the model at once in that run. A summarizer
with that many slots wraps the compactor, so maxBuilds in the core stays
8. A lower limit lowers the rate of calls on one cache key, which tests
whether the rate is the cause of the low cached share. The report adds
the calls per minute.
The probe reads the usage records in the order of the start of their
calls. The file holds them in the order of their end, so with calls at
once the quota stop compared the first record written with the last one,
not the earliest call with the latest, and the report showed the same
records as the first and the last call.
The compactor uses gpt-6.1-sol at high effort unless config.json names
another model. In the probe run it needed 1.10 calls per model line, and
2 of 388 lines went over 512 bytes, where gpt-6-luna needed 3.3 calls
per line and kept half of its lines over the limit after five tries. It
also credited quoted tool text to the tool, where gpt-6-luna credited it
to the user. 425 calls for 300 messages moved the weekly quota window by
about one point.
A long quote in an issue goes in a blockquote below its paragraph or
list. mdformat cannot wrap inline code, so a long code span stays on one
line of more than 72 characters, and the terminal UI breaks it in the
middle of the text. A blockquote inside a list item makes the whole list
loose, so the quote goes after the list.
The probe waits for the builds only before a user message, as a turn
does, so up to eight builds run at once while the other messages come
in. During a wait it checks the stop rules each second, so a stop does
not wait for a long backlog. After a stop it waits for the calls in
flight, so no call that was sent is cancelled.
The client takes a call limit and refuses each call over it before it
sends anything, so the probe stops at 660 calls also with eight builds
at once. The report adds the calls per model line, the time per call,
and how many calls ran at once.
Issue bodies and comments go through mdformat with the repository
configuration, so they wrap and number lists as every other Markdown
file does. mdformat joins trailer lines into one line, so the text is
formatted first and the trailers are added after it.
A question to the user that is still open at the end of a session goes
on the issue as a comment, with the options and a recommendation, and
the answer follows as a comment. Otherwise the question is lost when the
session ends, and a new agent cannot see it. Each decision comment gives
its reason, so that a later agent does not undo the decision.
Record the node, reply size, and time of each call
Each line of usage.jsonl also gives the length of the call in seconds,
the size of the text of the reply in bytes, and, for a compaction, the
node [l, i] that it builds. With these fields the records show the size
of each try of a node, the time per call, and how many calls ran at
once, also when eight builds run in parallel and the order of the calls
no longer tells which node a call belongs to.
The compactor names the node on its requests. The node goes only to the
usage file and never to the endpoint.
Each call to the ChatGPT backend sends the cache key of the agent in the
session_id header too, and keeps prompt_cache_key in the body. With the
key in the body only, the probe got no cached token, also on five tries
of one node with the same prefix. The same request sent twice with the
header got 1,664 of 1,756 input tokens from the cache on the second
call. Calls to the OpenAI API do not send the header.
The ChatGPT backend sends x-codex-turn-state on each response: an opaque
state of the backend of about 1 KB, not quota. The usage records keep
every other x-codex-* header, so each line holds the plan and the
windows without the noise.
onechat probe LOG COUNT appends the first COUNT messages of a log to a
new chat in probe/ in the data directory and builds its tree with real
model calls, as the live check of the compactor. After each message it
waits for the builds, as a turn does. It reports the calls per message,
the cached share of the input tokens, the retries, the sizes of the
model lines, and the quota at the first and the last call.
The run guards the quota of the account: it stops at the first failed
call, so a wrong setting cannot repeat a failing call at each message,
and it stops when the used percent of any quota window grows by more
than 15 points since the first call.
A test generates the probe log: 1,000 readable made-up messages about a
small bakery order system, with the mix of kinds and sizes of the
synthetic log of the core. It writes the log to a file when
ONECHAT_PROBE_LOG names one, and needs no network.
The note for a line that is too long ends its cut with "| <- LIMIT"
instead of a Unicode arrow, as the guide requires ASCII in every file
except Unicode test data.
Files, commit messages, and issues use only ASCII characters, with <-
and -> for arrows and plain dashes and quotes. Decorative characters
such as a Unicode arrow in a model task text are hard to type and search
for, and they add nothing that ASCII cannot say. Test data that checks
Unicode handling is the only exception.
The compactor is the Summarizer of the memory core. Each build is a call
like a turn, with the same system prompt, tools, and cache key, so it
reads the prompt cache of the turns and never calls a tool. The input is
one user message with the compaction view up to the node and the task:
the leaf or merge text of the reference design with the 512-dash ruler.
A line over 512 bytes gets another try with the same view and task plus
only the newest note, which gives its size and its cut at the limit. The
model's earlier reply and reasoning never go back, so each try has the
same cached prefix and about the same size. After at most five tries the
shortest line is the node. A call that fails before any line fails the
build, and the core tries it again at the next message. The model and
effort come from the compactor settings of config.json.
Code, comments, and tests refer to the reference design and its rollback
push list by their function, not by the names of their author or their
system. The view comment, the push-order test, and the prompt comment
use "the reference design".
The prompt test keeps its check that the prompt holds no old agent name.
It builds the word from parts, so the source does not spell it.
The system prompt of the UniiChat design and the zoom and date tools
live in prompt.go, so the turns and the compactions send the same bytes
and share one prompt cache. The prompt is the spec text with the agent's
name in place of Unii and the kind reply in place of unii. It holds no
date and no state.
The prompt describes only what OneChat can do, so it leaves out the spec
text on images, the name form of zoom, subagents, background tasks, the
user's computers, and the user's instructions. Each part returns with
the issue that adds its feature. The tool schemas are strict, with every
property required, and encode to the same bytes on each call.
The model client and the ChatGPT authorizer read the time with time.Now
instead of a clock field. No caller set the field, so it was an
injection with no user. A test that needs fake time can run in a
testing/synctest bubble, where the time package uses a fake clock.
writeFileAtomic moves from memory.go to file.go with no change, because
the token file of the login uses it too, and a helper in the file of its
first user hides the dependency of the other. The test clock moves from
log_test.go to clock_test.go for the same reason: the memory, tree, and
replay tests use it only as a clock.
A search of every cross-file use finds no other helper with an unrelated
user. The other shared declarations are parts of the memory core or of
the model client that compose for one purpose.
Code that gets a user in another file for an unrelated purpose moves to
a file named for its function in the same change. The file rules covered
only new code, and the rule against unrelated changes made an agent
leave a shared helper in the file of its first user, where it hid a
dependency of the new caller.
onechat login runs the device code login of the Codex client. It shows
the link and the code, polls until the user approves the code on any
device, trades the grant for tokens, reads the account ID from the auth
claim of the token, and writes auth.json in the data directory with mode
0600. The command needs no browser on the machine.
Before each call to the ChatGPT backend, the authorizer reads the expiry
from the access token. Within 60 seconds of the expiry it refreshes the
tokens, keeps a new refresh token when one comes, and replaces the file
atomically. A mutex lets one refresh run at a time. A missing file or a
failed refresh gives errLoginNeeded and leaves the file as it is. Errors
hold the HTTP status but never an answer body, so no token reaches a
log.
The endpoint in config.json selects the ChatGPT backend with this
authorizer or the OpenAI API with OPENAI_API_KEY, with no fallback from
one to the other. OneChat keeps its own token file, because the Codex
CLI rotates the same refresh token and two programs with one file log
each other out.
The test cases of the configuration and the data directory set their
fields by name, with one field on each line, as the go-code skill
requires. A case then shows which value is the XDG directory and which
is the home directory without a look at the struct.
A search of the rest of the code finds no other positional struct
literal. The node keys stay positional, because the skill allows a small
two-field type that acts as one value.
One client sends every model call of an agent. The ChatGPT backend and
the OpenAI API take the same request body, so the client differs between
them only in its URL and its credentials. Each request sets store to
false and stream to true, sends the input as a list, asks for the
encrypted reasoning, and carries the fixed cache key of the agent, so
the turns and the compactions share one prompt cache. It never sends
max_output_tokens or metadata, which the ChatGPT backend refuses.
The client reads the event stream until the response completes and fails
on a failed, incomplete, or cut stream. Each call, also a failed one,
adds a line to usage.jsonl with the model, the input, cached, and output
tokens, the HTTP status, and the x-codex-* quota headers.
Struct literals use field names, with one field on each line when more
than one field is set, and table-driven test cases follow the same rule.
The old rule applied only to keyed literals, so positional test cases
with many fields on one line passed it. A small two-field type that acts
as one value, such as a node key, can still use a positional literal.
OneChat finds its data directory in ONECHAT_DIR, then in an absolute
XDG_DATA_HOME, then in ~/.local/share/onechat, and creates it with mode
0700. config.json in that directory selects the model endpoint and the
compactor model and effort. A missing file or field takes the default,
and an unknown field or an invalid value is an error, so a typo never
becomes a silent default.
The endpoint is a name, chatgpt or api, not a URL, so the configuration
cannot send a token to another host.
The memory core no longer holds the whole log, which grows by about 200
MB a month. The log and the tree read each message and node from its day
file at the position in an index. index/main.idx holds the position of
message i in record i. index/tree.idx lists the node lines in file
order, and index/tree-L.idx holds the position of node (L, i) in record
i, with a zero record for a node that is not built. A read is one read
of the index and one of the day file.
At open the log and the tree index the lines after their last indexed
line, so a missing index is built again from the day files, and the
lines that a crash left out of an index join it. A partial record at the
end of an index is cut. The last node of the tree gets its level record
again, because a crash can stop an add between the two index writes.
The views keep the nodes of their own lines, and a running build keeps
its task. Nothing else stays in memory: after the 100,000-message
synthetic log the heap in use is about 3.4 MB.
The queue starts the node whose context ends first: a leaf ends before
its message and a merge after its last message, and at a tie the merge
starts first. With leaves before all merges, a backlog of long messages
kept back the merges that a batch needs, so the view could not shrink.
The merges wait in a heap by the end of their context, so the next build
is found without a scan. The leaf window of 8 unbuilt leaves and the
limit of 8 builds stay as they are.
The build limit test opens the gate of the fake summarizer only after
all 8 builds run, so its peak count no longer depends on goroutine
timing. The synthetic log test measures each view as the append did,
with the newest line as the pending mark, because the leaf of the new
message can be built before the check reads the view.
The exit check of the memory core runs a synthetic log of 100,000
messages through the core with the fake summarizer. The log mixes short
user lines, replies, notes, reports, tool calls, and tool output, and
one output in a hundred is over 30 KB. The core has no reader of the
optchat log, because that belongs to the history import.
After each message the test checks that the chat view is at most 128,000
bytes and the compaction view at most 32,000, and that a batch merges
the chat view to 64,000 bytes or less. It checks each rendered line: a
built line holds its node, a long message has a summary and not its
text, and an unbuilt line holds only the pending mark. A restart in the
middle and at the end loads the same views and view.json byte for byte.
Each log line and each node goes to the operating system with one write
and no buffer before the call returns, so a crash of the process loses
nothing. view.json stays atomic through a temporary file and a rename.
An fsync on each write cost about 96 ms per message on a typical disk,
which made a long replay take hours. Durability against a power loss is
a later group commit, with one background sync that makes all earlier
writes durable.
The core keeps the nodes that are ready for a model build in a queue and
never scans the tree for work. A leaf joins the queue when its message
is too long to be its own node. A merge joins when both of its children
are built and their texts do not fit in one node. A parent that fits is
built at once, up the tree.
At most 8 builds run at once. A leaf starts once fewer than 8 leaves
before it are unbuilt. Leaves start before merges, oldest first, because
a turn waits for the leaves of all earlier messages. A failed build
starts again at the next message. Each build gets its compaction view
and its input, the source of a leaf or the two child lines of a merge.
The model stays behind a small Summarizer interface, and the tests use a
fake one. The start reads the log and the tree once to fill the queue
again, and builds the free nodes that a crash left out.
A compaction reads the chat view merged further, at the limits of 16 to
32 KB, so that it has context to resolve references without the whole
chat. The compaction view takes each new line of the chat. It merges in
one batch from above 32 KB down to 16 KB, and again when the chat view
merges: then it first takes each merge of the chat view, so it stays the
chat view merged further. Compactions share its prefix and so read each
other's view from the prompt cache. view.json saves it with the chat
view, and a restart loads both as they are.
The context of a build ends at its node: before the message of a leaf,
or after the last message of a merge. It stops at the first line that is
not built, so a compaction never sees a pending mark or a part of a
message.
The view is a list of tree nodes that covers the whole chat, oldest
first. Each new message appends its leaf as a line. Once the node text
of the view goes above 128,000 bytes, one batch merges the most due
sibling pairs until it is at most 64,000 bytes. Due is (T - last) / 2^l,
measured from the last message of the pair, and the oldest pair wins a
tie. A batch merges only pairs whose parent is built, and it continues
at each new message until it gets to 64,000 bytes. With the length of
Taelin's push list as the budget, the merges match the push for t = 0 to
20,000.
The memory core logs each message, builds the nodes that need no model
call, appends to the view, and writes view.json atomically after each
change. view.json holds the lines and the batch state, and the start
loads it as it is. The core never builds the view again from the log: a
chat with messages and no view.json does not open. The start only
appends the messages that a crash left out of the view.
A line whose node is not built renders as a pending mark, so the view
never holds a part of an unsummarized message.
The tree stores each built node (l, i) as one JSON line, {l, i, text,
size}, in tree/YYYY-MM-DD.jsonl, and loads all lines again at start.
Node (l, i) covers the 2^l messages from i*2^l on. The tree refuses a
node that is already built and a parent without both children, so each
node is built once and the tree never holds a gap.
A source that fits in 512 bytes is its own node with no model call. A
short message becomes the leaf "kind: text" word for word, and two short
siblings join with a newline into their parent.
The log of one chat stores each message as one JSON line, {i, kind,
text, size, date}, in main/YYYY-MM-DD.jsonl for the local day of the
write. Each append goes to the disk before it returns, and the log loads
all lines again at start. An exclusive lock on the chat makes sure that
only one process writes it. After a failed write the log refuses more
writes, because the end of the file is not known.
The kinds are user, unii, tool, echo, work, and note. Size is the UTF-8
byte length of the text. Tests use testify, so the Nix package gets a
vendor hash.
The development shell sets ONECHAT_DIR to .devenv/onechat at the root of
the checkout, unless the variable is already set. Development data, such
as a copy of an old chat log for a replay, stays inside the checkout,
away from a running service, and Git ignores it. Each worktree has its
own .devenv, so parallel work does not share data.
Issues live in git-bug, inside the Git repository, so they work offline
and travel with the code through git bug push and pull. They are not
files in the checkout, so they stay out of diffs, formatters, and the
rule that files describe only the current state.
The development shell supplies git-bug. The issues skill tells agents
how to read and write issues, and warns that the -F option drops every
line that starts with "#". Commit messages now refer to an issue with an
Issue trailer that holds its git-bug ID, because there are no issue URLs
to link.
git-bug has no links between issues, so relations are Parent and
Depends-on trailers at the end of the body, as in a commit message. git
interpret-trailers can read them, and a search for an issue ID finds the
issues that refer to it.
OneChat is a Go program that prints its name. A Nix flake pins the Go
toolchain and every tool, builds the program with nix build, and runs
the binary in an install check. The development shell supplies the
formatters, the linters, and a pinned Vim, and it turns on the commit
message hook.
AGENTS.md holds the rules that apply to every task, such as the Nix
environment, the current-state-only rule, and the rule against revealing
infrastructure. The skills in .agents/skills hold the procedures for Go
code, documentation and comments, checks, and commits, so an agent loads
each one only for the task that needs it.
bin/format and bin/check cover every Go, Nix, RST, and Markdown file
that Git knows about. bin/reflow wraps comment paragraphs the same way
on every machine because it does not use a personal Vim configuration.
CLAUDE.md and .claude/skills are links to the same files, so Claude Code
reads one copy of the rules and skills.
projects / onechat / log