@lef237/hagumi 0.0.0-stage → 0.1.1

package/src/chat.ts

@@ -0,0 +1,212 @@
+// A chat: how it starts, the commands in it, each message and its reply, and what is remembered after a reply.
+import { readdir } from "node:fs/promises"
+import { basename } from "node:path"
+import { createInterface } from "node:readline"
+import { parseArgs } from "node:util"
+import { paths } from "./app"
+import { columnsText, isEmptyBoard, readBoard, writeBoard } from "./board"
+import { type Config, type Language, languages, nameOf } from "./config"
+import { messagesFrom, turn } from "./conversation"
+import { faceSets, withFace } from "./faces"
+import { languageName, Problem, t, useLanguage } from "./i18n"
+import { openSessionLog, type SessionLog } from "./log"
+import { addMemory, fits, placeFor, proposals, readMemory, seedPersona } from "./memory"
+import { systemPrompt } from "./prompt"
+import { chooseModel, isSignedIn, type ModelChoice, modelIds, type Provider, providers } from "./providers"
+import { approver, boardView, chatInput, dim, notice, report, show, tilde } from "./terminal"
+import type { ToolContext } from "./tools"
+
+export const conversationOptions = {
+  model: { type: "string" },
+  session: { type: "string" },
+} as const
+
+type Question = (prompt: string) => Promise<string>
+
+// A chat, or a single question: where it is logged, which model answers, how the user is asked,
+// what its tools may do, how hagumi presents itself, and what it remembers as the session starts.
+type Session = {
+  log: SessionLog
+  choice: ModelChoice
+  question: Question
+  context: ToolContext
+  config: Config
+  persona: string
+  memory: string
+  // This project's board as the session starts, as the model reads it.
+  board: string
+}
+
+// A chat in the working directory, which its prompt names. Coming from the list, hagumi has already said hello.
+export async function chat(args: string[], config: Config, greeted = false): Promise<void> {
+  const { values } = parseArgs({ args, options: conversationOptions })
+  const choice = chooseModel(values.model ?? config.model)
+  const log = await openSession(values.session)
+  const faces = faceSets[config.faces]
+  const workspace = process.cwd()
+  const hello = values.session ? t.welcomeBack(nameOf(config)) : t.greeting(nameOf(config), new Date().getHours())
+  if (!greeted) console.log(withFace(faces.greeting, hello))
+  console.log(`${dim(t.chatInfo(tilde(workspace), choice.ref, tilde(log.path)))}\n`)
+
+  // readline gives line editing and history; a resumed session recalls its own earlier inputs.
+  const history = messagesFrom(await log.read())
+    .flatMap((message) => (message.role === "user" ? [message.text] : []))
+    .reverse()
+  const prompt = `${basename(workspace)}> `
+  const input = chatInput(createInterface({ input: process.stdin, output: process.stdout, prompt, history }))
+  const session = await startSession(log, choice, input.question, config)
+  await input.each(async (line) => {
+    try {
+      await chatLine(line.trim(), session)
+    } catch (error) {
+      report(error)
+    }
+  })
+  process.stdout.write("\n")
+  await boardIfWorked(workspace, log, session.context.boards)
+}
+
+// A place worked in, with files in it or a long conversation behind it, gets a board as the chat ends, so that it
+// shows in the list to start from; the model fills it in as the work moves.
+async function boardIfWorked(workspace: string, log: SessionLog, dir: string): Promise<void> {
+  if (await readBoard(workspace, dir)) return
+  const turns = messagesFrom(await log.read()).filter((message) => message.role === "user").length
+  if (turns < 10 && !(await readdir(workspace)).some((name) => name !== ".git")) return
+  await writeBoard(workspace, { doing: [], todo: [], done: [] }, dir)
+  console.log(t.boardMade)
+}
+
+// The chat's commands, by name. They may change the session for the rest of the chat.
+export const chatCommands: Record<string, (argument: string, session: Session) => void | Promise<void>> = {
+  "/help": () => console.log(t.chatHelp),
+  "/models": (argument, session) => printModels(argument || undefined, session.choice.ref),
+  "/model": (argument, session) => {
+    if (argument) session.choice = chooseModel(argument)
+    console.log(t.model(session.choice.ref))
+  },
+  // This project's board as it stands now.
+  "/board": async (_, session) => {
+    const board = await readBoard(session.context.workspace, session.context.boards)
+    console.log(board && !isEmptyBoard(board) ? boardView(board) : t.boardEmpty)
+  },
+  // The screen changes at once; the partner speaks the new language from the next message,
+  // which changes the system prompt and so starts its cache afresh.
+  "/language": (argument, session) => {
+    if (argument) {
+      if (!languages.includes(argument as Language)) throw new Problem("unknownLanguage", languages.join(" / "))
+      session.config = { ...session.config, language: argument as Language }
+      useLanguage(session.config.language)
+    }
+    console.log(t.language(languageName(session.config.language)))
+  },
+}
+
+// One line of chat: a command, or a message for the model.
+async function chatLine(line: string, session: Session): Promise<void> {
+  const [name = "", ...rest] = line.split(/\s+/)
+  const command = chatCommands[name]
+  if (command) return command(rest.join(" "), session)
+  if (!line) return
+  await converse(session, line)
+  process.stdout.write("\n")
+}
+
+export async function converse(session: Session, text: string): Promise<void> {
+  const { log, choice, context, config, persona, memory, board } = session
+  const system = systemPrompt({
+    workspace: context.workspace,
+    name: nameOf(config),
+    language: config.language,
+    persona,
+    memory,
+    board,
+  })
+  await show(turn({ log, choice, text, system, context }), faceSets[config.faces])
+  process.stdout.write("\n")
+  await review(session)
+}
+
+// After the reply, each fact the partner proposed is kept or not. What came from the user's own words is kept
+// at once, with a word on the screen; what may come from a file or a command output waits for the user's "y".
+// Facts proposed together may not all fit, so each is measured again first. Every outcome is logged.
+async function review({ log, question, context, config }: Session): Promise<void> {
+  const faces = faceSets[config.faces]
+  const proposed = proposals(await log.read(), context.workspace)
+  if (proposed.length > 0) process.stdout.write("\n")
+  for (const { about, fact, origin } of proposed) {
+    const { path, limit } = placeFor(about, context)
+    const full = !(await fits(fact, path, limit))
+    if (full) console.log(withFace(faces.troubled, t.memoryFull(fact)))
+    const ask = about === "self" ? t.rememberSelf : t.rememberThis
+    const approved = !full && (origin === "user" || yes(await question(withFace(faces.waiting, ask(fact)))))
+    if (approved) {
+      await addMemory(fact, { about, session: log.id, origin, workspace: context.workspace }, path)
+      const kept = about === "self" ? t.keptSelf : t.kept
+      console.log(origin === "user" ? dim(kept(fact)) : withFace(faces.happy, t.remembered))
+    }
+    await log.append({ kind: "memory", about, fact, origin, approved, full })
+  }
+}
+
+// The persona and memory are read once, as the session starts, so that the system prompt stays the same
+// throughout. The persona is seeded first, in the language of the settings.
+export async function startSession(log: SessionLog, choice: ModelChoice, question: Question, config: Config): Promise<Session> {
+  const context = toolContext(question, config)
+  await seedPersona(t.personaSeed, context.persona)
+  const [persona, memory, board] = await Promise.all([
+    readMemory(context.persona),
+    readMemory(context.memory),
+    readBoard(context.workspace, context.boards),
+  ])
+  return { log, choice, question, context, config, persona, memory, board: board ? columnsText(board) : "" }
+}
+
+// File tools stay inside the working directory; bash has separate read and write limits. Every action waits for the user,
+// unless the user's rules already decide it.
+export function toolContext(question: Question, config: Config): ToolContext {
+  return {
+    workspace: process.cwd(),
+    memory: paths.memory,
+    persona: paths.persona,
+    boards: paths.boards,
+    seen: new Map(),
+    rules: config.commands,
+    approve: approver(question, faceSets[config.faces]),
+    notice,
+  }
+}
+
+export function yes(answer: string): boolean {
+  return answer.trim().toLowerCase() === "y"
+}
+
+export function providerOf(id: string): Provider {
+  const provider = providers[id]
+  if (!provider) throw new Problem("unknownProvider", id)
+  return provider
+}
+
+// A new session, or an existing one to continue.
+export async function openSession(id?: string): Promise<SessionLog> {
+  const log = await openSessionLog(id)
+  if (id && (await log.read()).length === 0) throw new Problem("sessionNotFound")
+  return log
+}
+
+// The models of one provider, or of every provider signed in to, named as `/model` expects them.
+export async function printModels(providerId?: string, current?: string): Promise<void> {
+  const targets = providerId ? [providerOf(providerId)] : await signedInProviders()
+  if (targets.length === 0) throw new Problem("notSignedIn", "chatgpt")
+  for (const provider of targets) {
+    for (const model of await modelIds(provider)) {
+      const ref = `${provider.id}/${model}`
+      console.log(current === undefined ? ref : `${ref === current ? "*" : " "} ${ref}`)
+    }
+  }
+}
+
+async function signedInProviders(): Promise<Provider[]> {
+  const all = Object.values(providers)
+  const signedIn = await Promise.all(all.map(isSignedIn))
+  return all.filter((_, index) => signedIn[index])
+}

package/src/chatgpt.ts

@@ -0,0 +1,181 @@
+// Sign in with ChatGPT: lets hagumi run requests on the user's ChatGPT plan through the public Responses API.
+// OpenAI allows this for personal projects that run locally:
+// https://developers.openai.com/cookbook/articles/sign-in-with-chatgpt
+import { createHash, randomBytes, type webcrypto } from "node:crypto"
+import { paths, userAgent } from "./app"
+import { Problem, t } from "./i18n"
+import { readJson, writeSecret } from "./store"
+
+const issuer = "https://auth.openai.com"
+export const resource = "https://api.openai.com/v1"
+const tokenSharing = "chatgpt.tokens.use.direct"
+
+export type ChatGPTAuth = {
+  hostId: string
+  clientId: string
+  accessToken: string
+  refreshToken: string
+  expiresAt: number
+}
+
+type TokenResponse = {
+  access_token: string
+  refresh_token?: string
+  id_token?: string
+  expires_in?: number
+  scope?: string
+}
+
+export type ChatGPTModel = { slug: string; display_name: string }
+
+export function authorizeUrl(options: {
+  redirect: string
+  challenge: string
+  state: string
+  nonce: string
+  hostId: string
+  clientId?: string
+}): string {
+  const params = new URLSearchParams({
+    // The first sign-in registers a client owned by this user; later sign-ins reuse it.
+    client_id: options.clientId ?? "dynamic_agent_client",
+    ...(options.clientId ? {} : { agent_name_hint: "hagumi" }),
+    ext_agent_host_id: options.hostId,
+    response_type: "code",
+    redirect_uri: options.redirect,
+    scope: `openid profile email offline_access resource.invoke ${tokenSharing}`,
+    resource,
+    state: options.state,
+    nonce: options.nonce,
+    code_challenge_method: "S256",
+    code_challenge: options.challenge,
+  })
+  return `${issuer}/api/accounts/authorize?${params}`
+}
+
+export async function signIn(showUrl: (url: string) => void): Promise<ChatGPTAuth> {
+  const saved = await readJson<ChatGPTAuth>(paths.auth("chatgpt"))
+  const hostId = saved?.hostId ?? `urn:uuid:${crypto.randomUUID()}`
+  const verifier = random(32)
+  const state = random(16)
+  const nonce = random(16)
+  const callback = Promise.withResolvers<URLSearchParams>()
+  const server = Bun.serve({
+    hostname: "127.0.0.1",
+    port: 0,
+    fetch(request) {
+      const url = new URL(request.url)
+      if (url.pathname !== "/auth/callback") return new Response("Not found", { status: 404 })
+      callback.resolve(url.searchParams)
+      return new Response(t.callbackPage, { headers: { "Content-Type": "text/plain; charset=utf-8" } })
+    },
+  })
+
+  try {
+    const redirect = `http://127.0.0.1:${server.port}/auth/callback`
+    const challenge = createHash("sha256").update(verifier).digest("base64url")
+    showUrl(authorizeUrl({ redirect, challenge, state, nonce, hostId, clientId: saved?.clientId }))
+
+    const params = await callback.promise
+    const error = params.get("error_description") ?? params.get("error")
+    if (error) throw new Error(`ChatGPT sign-in failed: ${error}`)
+    if (params.get("state") !== state) throw new Error("ChatGPT sign-in returned an unexpected state")
+
+    const code = params.get("code")
+    const returnedId = params.get("client_id")
+    if (saved && returnedId && returnedId !== saved.clientId) throw new Error("ChatGPT returned a different client")
+    const clientId = saved?.clientId ?? returnedId
+    if (!code || !clientId || clientId === "dynamic_agent_client") throw new Error("ChatGPT sign-in returned no code or issued client ID")
+
+    const tokens = await requestToken({
+      grant_type: "authorization_code",
+      client_id: clientId,
+      code,
+      code_verifier: verifier,
+      redirect_uri: redirect,
+    })
+    if (!tokens.scope?.split(" ").includes(tokenSharing)) throw new Problem("noTokenSharing")
+    await checkIdToken(tokens.id_token, clientId, nonce)
+
+    const auth = toAuth(tokens, { hostId, clientId })
+    await writeSecret(paths.auth("chatgpt"), auth)
+    return auth
+  } finally {
+    server.stop()
+  }
+}
+
+// Returns a usable access token, refreshing it shortly before it expires.
+export async function accessToken(): Promise<string> {
+  const auth = await readJson<ChatGPTAuth>(paths.auth("chatgpt"))
+  if (!auth) throw new Problem("notSignedIn", "chatgpt")
+  if (auth.expiresAt - Date.now() > 60_000) return auth.accessToken
+
+  const tokens = await requestToken({
+    grant_type: "refresh_token",
+    client_id: auth.clientId,
+    refresh_token: auth.refreshToken,
+  })
+  const refreshed = toAuth(tokens, auth)
+  await writeSecret(paths.auth("chatgpt"), refreshed)
+  return refreshed.accessToken
+}
+
+export async function listModels(token: string): Promise<ChatGPTModel[]> {
+  const response = await fetch(`${resource}/models`, {
+    headers: { Authorization: `Bearer ${token}`, "User-Agent": userAgent },
+  })
+  if (!response.ok) throw new Error(`GET /models failed: ${response.status} ${await response.text()}`)
+  const { models } = (await response.json()) as {
+    models: (ChatGPTModel & { visibility: string; supported_in_api: boolean })[]
+  }
+  return models.filter((model) => model.visibility === "list" && model.supported_in_api)
+}
+
+async function requestToken(params: Record<string, string>): Promise<TokenResponse> {
+  const response = await fetch(`${issuer}/api/accounts/oauth/token`, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded", "User-Agent": userAgent },
+    body: new URLSearchParams({ ...params, resource }),
+  })
+  if (!response.ok) throw new Error(`ChatGPT token request failed: ${response.status} ${await response.text()}`)
+  return (await response.json()) as TokenResponse
+}
+
+// Checked as OpenAI's guide for open-source apps asks: the signature against OpenAI's published keys, fetched
+// fresh at each sign-in so that no cache is needed, then who issued the token, for whom, for this sign-in, and when.
+// https://developers.openai.com/siwc/token-sharing-open-source/sign-in
+export async function checkIdToken(idToken: string | undefined, clientId: string, nonce: string): Promise<void> {
+  const [head = "", body = "", signature = ""] = (idToken ?? "").split(".")
+  const decode = (part: string) => { try { return JSON.parse(Buffer.from(part, "base64url").toString()) } catch { return {} } }
+  const header = decode(head)
+  const response = await fetch(`${issuer}/.well-known/jwks.json`, { signal: AbortSignal.timeout(10_000) })
+  if (!response.ok) throw new Error(`Could not get OpenAI's signing keys: ${response.status}`)
+  const { keys } = (await response.json()) as { keys: (webcrypto.JsonWebKey & { kid?: string })[] }
+  const jwk = keys.find((key) => key.kid === header.kid)
+  const rsa = { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" }
+  const key = header.alg === "RS256" && jwk && (await crypto.subtle.importKey("jwk", jwk, rsa, false, ["verify"]))
+  const signed = key && (await crypto.subtle.verify(rsa, key, Buffer.from(signature, "base64url"), Buffer.from(`${head}.${body}`)))
+  const claims = decode(body)
+  const now = Date.now() / 1000
+  if (!signed || claims.iss !== issuer || ![claims.aud].flat().includes(clientId) || claims.nonce !== nonce ||
+    !(claims.exp > now - 5) || !(claims.iat < now + 5) || !claims.sub) {
+    throw new Error("ChatGPT returned an invalid ID token")
+  }
+}
+
+function toAuth(tokens: TokenResponse, previous: Pick<ChatGPTAuth, "hostId" | "clientId"> & { refreshToken?: string }) {
+  const refreshToken = tokens.refresh_token ?? previous.refreshToken
+  if (!refreshToken) throw new Error("ChatGPT returned no refresh token")
+  return {
+    hostId: previous.hostId,
+    clientId: previous.clientId,
+    accessToken: tokens.access_token,
+    refreshToken,
+    expiresAt: Date.now() + (tokens.expires_in ?? 3600) * 1000,
+  } satisfies ChatGPTAuth
+}
+
+function random(bytes: number): string {
+  return randomBytes(bytes).toString("base64url")
+}

package/src/cli.ts

@@ -0,0 +1,177 @@
+#!/usr/bin/env bun
+import { existsSync } from "node:fs"
+import { parseArgs } from "node:util"
+import { paths, prepareStorage } from "./app"
+import { allBoards, type BoardEntry, columnsText } from "./board"
+import { chat, conversationOptions, converse, openSession, printModels, providerOf, startSession, toolContext, yes } from "./chat"
+import { signIn } from "./chatgpt"
+import { type Config, loadConfig, nameOf } from "./config"
+import { messagesFrom, turn } from "./conversation"
+import { faceSets, withFace } from "./faces"
+import { Problem, t, useLanguage } from "./i18n"
+import { openSessionLog } from "./log"
+import { memoryHistory, memoryLimit, personaLimit, readMemory, size } from "./memory"
+import { chooseModel, providers, saveApiKey } from "./providers"
+import { askOnce, dim, openBrowser, projectLine, readSecret, report, tilde } from "./terminal"
+import { emptyWorkspaces, isEmpty, newWorkspace, tidy } from "./workspaces"
+
+type Command = (args: string[], config: Config) => Promise<void>
+
+const commands: Record<string, Command> = {
+  async login([id = "chatgpt"]) {
+    const provider = providerOf(id)
+    if (provider.auth === "chatgpt") {
+      await signIn((url) => {
+        console.log(t.openUrl(url))
+        openBrowser(url)
+      })
+    } else {
+      const apiKey = await readSecret(t.askApiKey(provider.id))
+      if (!apiKey) throw new Problem("cancelled")
+      await saveApiKey(provider, apiKey)
+    }
+    console.log(t.signedIn(provider.id))
+  },
+
+  async models([id]) {
+    await printModels(id)
+  },
+
+  async ask(args, config) {
+    const { values, positionals } = parseArgs({ args, options: conversationOptions, allowPositionals: true })
+    const text = positionals.join(" ")
+    if (!text) throw usage()
+    const choice = chooseModel(values.model ?? config.model)
+    const log = await openSession(values.session)
+    await converse(await startSession(log, choice, askOnce, config), text)
+    console.log(`\n${t.footer(choice.ref, log.path)}`)
+  },
+
+  "": home,
+  ".": (args, config) => chat(args, config),
+  new: (args, config) => fresh(args, config),
+
+  // Tidies away the empty places hagumi new left, all at once after one question; never the one in use.
+  async prune(_args, config) {
+    const empty = (await emptyWorkspaces(config.workspaces)).filter((dir) => dir !== process.cwd())
+    if (empty.length === 0) return console.log(t.pruneNone)
+    console.log(t.pruneFound(empty.map((dir) => `  ${tilde(dir)}`)))
+    if (!yes(await askOnce(t.pruneAsk))) return
+    let count = 0
+    for (const dir of empty) if (await tidy(dir)) count++
+    console.log(t.pruned(count))
+  },
+
+  // Shows where the settings live, and every value in effect.
+  async config(_args, config) {
+    console.log(`${t.configShown(paths.config)}\n${JSON.stringify(config, null, 2)}`)
+  },
+
+  // Shows where the persona and memory are kept, what they hold, and how they changed lately.
+  async memory() {
+    for (const [shown, path, limit] of [
+      [t.personaShown, paths.persona, personaLimit],
+      [t.memoryShown, paths.memory, memoryLimit],
+    ] as const) {
+      const text = await readMemory(path)
+      console.log(`${shown(path, size(text), limit)}\n${text ? `\n${text}` : t.memoryEmpty}\n`)
+    }
+    const changes = await memoryHistory()
+    if (changes.length > 0) console.log(`${t.memoryChanges}\n${changes.map((change) => `  ${change}`).join("\n")}`)
+  },
+
+  // Prints the last request exactly as it was sent to the model, secrets aside.
+  async inspect([id]) {
+    if (!id) throw usage()
+    const request = (await (await openSession(id)).read()).findLast((entry) => entry.kind === "request")
+    if (!request) throw new Problem("sessionNotFound")
+    const { url, headers, body } = request
+    console.log(JSON.stringify({ url, headers, body }, null, 2))
+  },
+}
+
+// The way in: the projects that moved most recently, then where to begin. Older ones are not shown, which is
+// all their archive is, and are found by what the user remembers of them. A project is resumed in a new chat,
+// since its board and memory carry on from before. Without a terminal, the list is all.
+async function home(_args: string[], config: Config): Promise<void> {
+  const faces = faceSets[config.faces]
+  const all = (await allBoards()).filter(({ workspace }) => existsSync(workspace)).sort((a, b) => b.updated - a.updated)
+  const projects = all.slice(0, 9)
+  console.log(withFace(faces.greeting, t.greeting(nameOf(config), new Date().getHours())))
+  console.log(
+    [
+      "",
+      ...numbered(projects),
+      `  n. ${t.startNew}`,
+      `  .  ${t.startHere(tilde(process.cwd()))}`,
+      ...(all.length > 0 ? [dim(`  ${t.searchHint}`)] : []),
+      "",
+    ].join("\n"),
+  )
+  if (!process.stdin.isTTY) return
+  const answer = (await askOnce(withFace(faces.waiting, t.whereToStart))).trim()
+  console.log()
+  const chosen = /^\d+$/.test(answer) ? projects[Number(answer) - 1] : ["", "n", "."].includes(answer) ? undefined : await search(answer, all, config)
+  if (chosen) process.chdir(chosen.workspace)
+  if (chosen || answer === ".") return chat([], config, true)
+  if (answer === "n") return fresh([], config, true)
+}
+
+// Finds a project from what the user remembers of it: when it was, its name, or what it was about. The model
+// reads every board, with no tools to call, and the user picks from what it finds.
+async function search(description: string, boards: BoardEntry[], config: Config): Promise<BoardEntry | undefined> {
+  const faces = faceSets[config.faces]
+  console.log(withFace(faces.thinking, t.searching))
+  const log = await openSessionLog()
+  const listed = boards.map(({ workspace, board, updated }, index) =>
+    [`${index + 1}. ${workspace} (last moved ${new Date(updated).toLocaleDateString("sv-SE")})`, columnsText(board)].join("\n"),
+  )
+  const text = `${description}\n\n${listed.join("\n\n")}`
+  for await (const _ of turn({ log, choice: chooseModel(config.model), text, system: searchPrompt, context: toolContext(askOnce, config), tools: [] })) {
+  }
+  const reply = messagesFrom(await log.read()).findLast((message) => message.role === "assistant")
+  const found = [...new Set(reply?.text.match(/\d+/g) ?? [])].flatMap((n) => boards[Number(n) - 1] ?? []).slice(0, 9)
+  if (found.length === 0) return void console.log(t.searchNone)
+  console.log(["", ...numbered(found), ""].join("\n"))
+  const answer = (await askOnce(withFace(faces.waiting, t.whichOne))).trim()
+  console.log()
+  return found[Number(answer) - 1]
+}
+
+const searchPrompt =
+  "The user is looking for one of their projects and tells you what they remember of it: when it was, its name, or what it was about. " +
+  "Below it are the projects, each with its directory, the day its board last moved, and its board. " +
+  "Reply with only the numbers of the projects that match, best first, separated by spaces, or 0 if none does."
+
+function numbered(projects: BoardEntry[]): string[] {
+  return projects.map(({ workspace, board }, index) => `  ${index + 1}. ${projectLine(workspace, board)}`)
+}
+
+// A fresh place to work, and a chat in it.
+async function fresh(args: string[], config: Config, greeted = false): Promise<void> {
+  parseArgs({ args, options: { model: { type: "string" } } })
+  const workspace = await newWorkspace(config.workspaces)
+  process.chdir(workspace)
+  console.log(t.madeWorkspace(tilde(workspace)))
+  await chat(args, config, greeted)
+  // A place left empty is offered to be tidied away; otherwise the way there is shown.
+  const tidied = (await isEmpty(workspace)) && yes(await askOnce(t.tidyEmpty)) && (await tidy(workspace))
+  console.log(tidied ? t.tidied : t.goThere(tilde(workspace)))
+}
+
+function usage(): Problem {
+  return new Problem("usage", Object.keys(providers).join(", "))
+}
+
+const [name = "", ...args] = process.argv.slice(2)
+try {
+  await prepareStorage()
+  const config = await loadConfig()
+  useLanguage(config.language)
+  const command = commands[name]
+  if (!command) throw usage()
+  await command(args, config)
+} catch (error) {
+  report(error)
+  process.exit(1)
+}

package/src/compact.ts

@@ -0,0 +1,41 @@
+// Old tool output is most of what fills a conversation (docs/concept.md §6.2). Once the conversation grows
+// past a size, every long output from before the current turn is replaced with a short note, all at once,
+// so that the prompt cache breaks only then. The log keeps every output in full: this only shapes what is
+// sent, and the same log always gives the same request.
+import type { Message } from "./conversation"
+
+// In characters, as the conversation is sent: about 30,000 tokens.
+export const compactAt = 100_000
+// A shorter output says too much for its size to be worth leaving out.
+const longOutput = 1_000
+
+// The conversation to send, and how many outputs were left out as the current turn began.
+export function compact(messages: Message[]): { conversation: Message[]; omitted: number } {
+  const conversation = [...messages]
+  let size = 0
+  let omitted = 0
+  for (const [index, message] of messages.entries()) {
+    if (message.role === "user") omitted = 0
+    if (message.role === "user" && size > compactAt) {
+      for (const [earlier, old] of conversation.slice(0, index).entries()) {
+        if (old.role !== "tool" || old.output.length <= longOutput) continue
+        const output = note(old.output.length)
+        size -= old.output.length - output.length
+        conversation[earlier] = { ...old, output }
+        omitted++
+      }
+    }
+    size += sizeOf(message)
+  }
+  return { conversation, omitted }
+}
+
+function note(length: number): string {
+  return `[Omitted: ${length.toLocaleString("en-US")} characters of old output. Call the tool again if you need it.]`
+}
+
+function sizeOf(message: Message): number {
+  if (message.role === "user") return message.text.length
+  if (message.role === "tool") return message.output.length
+  return message.text.length + message.toolCalls.reduce((sum, call) => sum + call.arguments.length, 0)
+}