@lef237/hagumi 0.0.0-stage → 0.1.0

package/src/memory.ts

@@ -0,0 +1,132 @@
+// What hagumi remembers (docs/design/memory.md): facts about the user and their projects in
+// ~/.hagumi/memory/memory.md, and how hagumi itself speaks in persona.md beside it. A line comes from the user's
+// own words, or, when it may come from a file or a command output, from the user's approval. The directory is
+// a git repository, and each line is one commit whose trailers say where it came from. The user may edit the
+// files by hand.
+import { appendFile, mkdir, writeFile } from "node:fs/promises"
+import { basename, dirname, join } from "node:path"
+import { paths } from "./app"
+import type { ToolCall } from "./conversation"
+import type { LogEntry } from "./log"
+
+// "tools" when tool output had come into the conversation before the fact was proposed:
+// the fact may then come from a file or a command rather than from the user.
+export type Origin = "user" | "tools"
+// Whom or what a fact is about: "self" is how hagumi speaks, and goes to the persona.
+export type About = "user" | "project" | "self"
+export type Proposal = { about: About; fact: string; origin: Origin }
+export type Provenance = { about: About; session: string; origin: Origin; workspace: string }
+
+// Facts are kept only where their history can be kept too.
+export const gitAvailable = Bun.which("git") !== null
+
+// Memory goes into the prompt of every session, so it is kept small; the persona, which rarely changes,
+// smaller still.
+export const memoryLimit = 2000
+export const personaLimit = 500
+
+// The persona starts from a small seed, written on first use so that it can be read and changed,
+// and recorded as the first step of its growth.
+export async function seedPersona(seed: string, path = paths.persona): Promise<void> {
+  if (await Bun.file(path).exists()) return
+  const dir = dirname(path)
+  await mkdir(dir, { recursive: true })
+  await writeFile(path, seed)
+  if (!gitAvailable) return
+  await git(dir, "init", "--quiet")
+  await git(dir, "add", basename(path))
+  await git(dir, "commit", "--quiet", "--message", "persona: seed")
+}
+
+// Read once when a session starts, so that the system prompt stays the same throughout the session.
+export async function readMemory(path = paths.memory): Promise<string> {
+  const file = Bun.file(path)
+  return (await file.exists()) ? (await file.text()).trim() : ""
+}
+
+// Characters as people count them, rather than UTF-16 code units.
+export function size(text: string): number {
+  return [...text].length
+}
+
+// Where a fact is kept, and how much that file may hold.
+export function placeFor(about: About, files: { memory: string; persona: string }): { path: string; limit: number } {
+  return about === "self" ? { path: files.persona, limit: personaLimit } : { path: files.memory, limit: memoryLimit }
+}
+
+// Whether one more fact fits within the limit. What the user wrote by hand is kept even past it;
+// only new facts are refused.
+export async function fits(fact: string, path = paths.memory, limit = memoryLimit): Promise<boolean> {
+  return size(await readMemory(path)) + size(`\n- ${fact}`) <= limit
+}
+
+// The latest changes, newest first, as "date  subject".
+export async function memoryHistory(path = paths.memory, count = 5): Promise<string[]> {
+  const dir = dirname(path)
+  if (!(await Bun.file(join(dir, ".git", "HEAD")).exists())) return []
+  const log = await git(dir, "log", `-${count}`, "--date=format:%Y-%m-%d %H:%M", "--format=%ad  %s")
+  return log ? log.split("\n") : []
+}
+
+// The line a proposal adds to memory.md. Memory is shared by every project, so a fact about the project
+// is marked with the name of the working directory, unless the model already named it there.
+export function factFrom(input: Record<string, unknown>, workspace: string): string {
+  const fact = String(input.fact ?? "").replace(/\s+/g, " ").trim()
+  const project = basename(workspace)
+  return fact && input.about === "project" && !fact.includes(project) ? `${project}: ${fact}` : fact
+}
+
+// The facts proposed during the last turn, read back from the session log.
+// A fact the user has already decided on in this session is not asked again.
+export function proposals(entries: LogEntry[], workspace: string): Proposal[] {
+  const turnStart = entries.findLastIndex((entry) => entry.kind === "user")
+  const accepted = new Set(entries.flatMap((entry) => (entry.kind === "tool_result" && entry.ok ? [entry.callId] : [])))
+  const asked = new Set(entries.flatMap((entry) => (entry.kind === "memory" ? [entry.fact] : [])))
+  const found: Proposal[] = []
+  let origin: Origin = "user"
+  entries.forEach((entry, index) => {
+    if (entry.kind === "tool_result" && entry.name !== "remember") origin = "tools"
+    if (index < turnStart || entry.kind !== "assistant") return
+    for (const call of entry.toolCalls as ToolCall[]) {
+      if (call.name !== "remember" || !accepted.has(call.id)) continue
+      const input = JSON.parse(call.arguments)
+      const fact = factFrom(input, workspace)
+      if (asked.has(fact)) continue
+      asked.add(fact)
+      found.push({ about: input.about, fact, origin })
+    }
+  })
+  return found
+}
+
+// Adds one fact as one commit. Edits made by hand since the last commit are committed first,
+// so that each commit says who made the change.
+export async function addMemory(fact: string, provenance: Provenance, path = paths.memory): Promise<void> {
+  const dir = dirname(path)
+  await mkdir(dir, { recursive: true })
+  await git(dir, "init", "--quiet")
+  if (await git(dir, "status", "--porcelain")) {
+    await git(dir, "add", "--all")
+    await git(dir, "commit", "--quiet", "--message", "edit: by hand")
+  }
+  const file = Bun.file(path)
+  const text = (await file.exists()) ? await file.text() : ""
+  await appendFile(path, `${text && !text.endsWith("\n") ? "\n" : ""}- ${fact}\n`)
+  await git(dir, "add", basename(path))
+  const trailers = [`Session: ${provenance.session}`, `Origin: ${provenance.origin}`, `Workspace: ${provenance.workspace}`]
+  const subject = `${provenance.about === "self" ? "persona" : "remember"}: ${fact}`
+  await git(dir, "commit", "--quiet", "--message", subject, "--message", trailers.join("\n"))
+}
+
+// hagumi commits as itself, whatever the user's git settings say about names and signing.
+async function git(dir: string, ...args: string[]): Promise<string> {
+  const identity = ["-c", "user.name=hagumi", "-c", "user.email=hagumi@localhost", "-c", "commit.gpgsign=false"]
+  const child = Bun.spawn(["git", "-C", dir, ...identity, ...args], { stdin: "ignore", stdout: "pipe", stderr: "pipe" })
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+    child.exited,
+  ])
+  if (exitCode !== 0) throw new Error(`git ${args[0]}: ${stderr.trim()}`)
+  return stdout.trim()
+}

package/src/policy.ts

@@ -0,0 +1,45 @@
+// The user's rules for commands. A denied command never runs; an allowed one runs without asking;
+// anything else is asked about. Deny wins over allow.
+import { basename } from "node:path"
+import { analyze } from "./shell"
+
+export type CommandRules = { allow: string[]; deny: string[] }
+
+export type Verdict = { kind: "ask" } | { kind: "allow"; rules: string[] } | { kind: "deny"; rule: string }
+
+// A command line is allowed only when every program it runs is allowed and nothing in it is opaque;
+// it is denied when any program it runs, however deeply nested, is denied.
+export function judge(line: string, rules: CommandRules): Verdict {
+  const { commands, opaque } = analyze(line)
+  for (const argv of commands) {
+    const rule = rules.deny.find((candidate) => denies(wordsOf(candidate), argv))
+    if (rule) return { kind: "deny", rule }
+  }
+  if (opaque || commands.length === 0) return { kind: "ask" }
+
+  const matched = commands.map((argv) => rules.allow.find((candidate) => allows(wordsOf(candidate), argv)))
+  if (matched.some((rule) => rule === undefined)) return { kind: "ask" }
+  return { kind: "allow", rules: [...new Set(matched as string[])] }
+}
+
+function wordsOf(rule: string): string[] {
+  return rule.trim().split(/\s+/)
+}
+
+// An allow rule is a prefix of the arguments: `git status` allows `git status -s`, but not `git -C x status`.
+function allows([program, ...args]: string[], argv: string[]): boolean {
+  return argv[0] === program && args.every((word, index) => argv[index + 1] === word)
+}
+
+// A deny rule is generous: its words after the program may appear anywhere, in order.
+// `git push` denies `git -C x push origin` too.
+function denies([program, ...args]: string[], argv: string[]): boolean {
+  if (basename(argv[0] ?? "") !== basename(program ?? "")) return false
+  let from = 1
+  for (const word of args) {
+    const at = argv.indexOf(word, from)
+    if (at < 0) return false
+    from = at + 1
+  }
+  return true
+}

package/src/prompt.ts

@@ -0,0 +1,43 @@
+// The system prompt, in named sections. It holds nothing that changes within a session,
+// so providers can keep it cached.
+import type { Language } from "./config"
+
+const speech: Record<Language, string> = {
+  auto: "Reply in the language the user writes in.",
+  ja: "Speak Japanese, unless the user writes in another language.",
+  en: "Speak English, unless the user writes in another language.",
+}
+
+// When the board is kept: told in the prompt and in the tool, since some models keep it only when told when.
+export const boardRule =
+  "Whenever the work moves, as you start or finish something or a new task comes up, update the board with the board tool in the same turn."
+
+// The persona follows the identity, since it rarely changes; memory and the board come last, since they change
+// most.
+export function systemPrompt(options: {
+  workspace: string
+  name: string
+  language: Language
+  persona: string
+  memory: string
+  board: string
+}): string {
+  return [
+    `<identity>You are ${options.name}, a coding partner working with the user in their terminal.</identity>`,
+    ...(options.persona
+      ? [`<persona>\nHow you speak. It grows through your conversations with the user:\n${options.persona}\n</persona>`]
+      : []),
+    `<workspace>The working directory is ${options.workspace}. ` +
+      "The read, write, and edit tools can access only files inside it. " +
+      "Bash can also read files outside it, except blocked credential locations; it can write to the workspace and temporary directories. " +
+      "Keep file reads within the working directory unless the user explicitly requests an outside path. " +
+      "Credential blocking does not cover every sensitive file.</workspace>",
+    `<language>${speech[options.language]}</language>`,
+    ...(options.memory
+      ? [`<memory>\nFacts about the user and your work together, kept from earlier conversations:\n${options.memory}\n</memory>`]
+      : []),
+    ...(options.board
+      ? [`<board>\nThe board of this project as this session began; the first item under To do comes next. ${boardRule}\n${options.board}\n</board>`]
+      : []),
+  ].join("\n")
+}

package/src/providers.ts

@@ -0,0 +1,85 @@
+// Providers are data. One that speaks a known wire needs no new code.
+import { paths, userAgent } from "./app"
+import { accessToken, listModels } from "./chatgpt"
+import { Problem } from "./i18n"
+import { readJson, writeSecret } from "./store"
+import { type Wire, type WireName, wires } from "./wire"
+
+export type Provider = {
+  id: string
+  baseUrl: string
+  auth: "chatgpt" | "api-key"
+  // The wire its models speak, and the models that speak another one.
+  wire: WireName
+  models?: Record<string, WireName>
+  // The header carrying hagumi's session id, which providers use for routing and prompt caching.
+  sessionHeader: string
+}
+
+export const providers: Record<string, Provider> = {
+  chatgpt: {
+    id: "chatgpt",
+    baseUrl: "https://api.openai.com/v1",
+    auth: "chatgpt",
+    wire: "openai-responses",
+    sessionHeader: "session-id",
+  },
+  // Open to coding agents that send their own User-Agent and a stable session id: https://dev.opencode.ai/v2/docs/console/go/
+  "opencode-go": {
+    id: "opencode-go",
+    baseUrl: "https://opencode.ai/zen/go/v1",
+    auth: "api-key",
+    wire: "openai-chat",
+    models: {
+      "grok-4.7": "openai-responses",
+      "grok-4.6": "openai-responses",
+      "gpt-6-luna": "openai-responses",
+      "gpt-5.6-luna": "openai-responses",
+      "muse-spark-1.3-contributor": "openai-responses",
+      "muse-spark-1.2-contributor": "openai-responses",
+      "claude-haiku-5-5": "anthropic-messages",
+      "minimax-m3": "anthropic-messages",
+      "minimax-m2.7": "anthropic-messages",
+      "qwen3.8-max": "anthropic-messages",
+      "qwen3.8-flash": "anthropic-messages",
+      "qwen3.7-plus": "anthropic-messages",
+    },
+    sessionHeader: "x-opencode-session",
+  },
+}
+
+export type ModelChoice = { ref: string; provider: Provider; model: string; wire: Wire }
+
+// Models are named `<provider>/<model>`, such as `opencode-go/kimi-k3`.
+export function chooseModel(ref: string): ModelChoice {
+  const slash = ref.indexOf("/")
+  const provider = slash > 0 ? providers[ref.slice(0, slash)] : undefined
+  const model = ref.slice(slash + 1)
+  if (!provider || !model) throw new Problem("unknownModel", ref)
+  return { ref, provider, model, wire: wires[provider.models?.[model] ?? provider.wire] }
+}
+
+export async function credential(provider: Provider): Promise<string> {
+  if (provider.auth === "chatgpt") return accessToken()
+  const saved = await readJson<{ apiKey: string }>(paths.auth(provider.id))
+  if (!saved) throw new Problem("notSignedIn", provider.id)
+  return saved.apiKey
+}
+
+export function isSignedIn(provider: Provider): Promise<boolean> {
+  return Bun.file(paths.auth(provider.id)).exists()
+}
+
+export function saveApiKey(provider: Provider, apiKey: string): Promise<void> {
+  return writeSecret(paths.auth(provider.id), { apiKey })
+}
+
+export async function modelIds(provider: Provider): Promise<string[]> {
+  if (provider.auth === "chatgpt") return (await listModels(await accessToken())).map((model) => model.slug)
+  const response = await fetch(`${provider.baseUrl}/models`, {
+    headers: { "User-Agent": userAgent, Authorization: `Bearer ${await credential(provider)}` },
+  })
+  if (!response.ok) throw new Error(`GET /models failed: ${response.status} ${await response.text()}`)
+  const { data } = (await response.json()) as { data: { id: string }[] }
+  return data.map((model) => model.id)
+}

package/src/sandbox.ts

@@ -0,0 +1,170 @@
+// Commands run inside the operating system's sandbox: Seatbelt on macOS, bubblewrap on Linux.
+// They may write only to the workspace and temporary directories, cannot reach the network,
+// cannot access known credential locations, and see few environment variables. Other OS-readable files,
+// including ones outside the workspace, remain readable.
+import { existsSync, lstatSync } from "node:fs"
+import { realpath } from "node:fs/promises"
+import { homedir, tmpdir } from "node:os"
+import { delimiter, isAbsolute, join, relative, sep } from "node:path"
+import { storageHome } from "./app"
+import { analyze } from "./shell"
+
+// What a command may touch, decided once for every platform.
+export type Limits = {
+  workspace: string
+  writable: string[]
+  // Inside the writable places, yet kept read-only: git runs hooks and reads its config from here.
+  protected: string[]
+  secrets: string[]
+}
+
+// How one platform's sandbox turns the limits into a command line.
+type Backend = { available(): boolean; wrap(command: string, limits: Limits): string[] }
+
+const seatbelt: Backend = {
+  available: () => existsSync("/usr/bin/sandbox-exec"),
+  wrap: (command, limits) => ["/usr/bin/sandbox-exec", "-p", seatbeltProfile(limits), "/bin/bash", "-c", command],
+}
+
+const bubblewrap: Backend = {
+  // bwrap needs unprivileged user namespaces, which some systems turn off; trying it once tells.
+  available: () => Bun.which("bwrap") !== null && Bun.spawnSync(["bwrap", "--ro-bind", "/", "/", "true"]).exitCode === 0,
+  wrap: (command, limits) => [...bubblewrapArgs(limits), "/bin/bash", "-c", command],
+}
+
+const backend = { darwin: seatbelt, linux: bubblewrap }[process.platform as string]
+
+// Where no sandbox is available, commands do not run at all.
+export const sandboxAvailable = backend?.available() ?? false
+
+// Known homes of credentials, hagumi's own included. A guard against accidents, not a complete list.
+export const secretPaths = [
+  ".hagumi",
+  ".ssh",
+  ".aws",
+  ".gnupg",
+  ".kube",
+  ".docker",
+  ".azure",
+  ".config/gh",
+  ".config/gcloud",
+  ".netrc",
+  ".npmrc",
+  ".codex",
+  ".claude",
+].map((path) => join(homedir(), path)).concat(storageHome)
+
+// Enough for tools to work; API keys and tokens in the environment stay behind.
+const passedEnvironment = ["PATH", "HOME", "USER", "LOGNAME", "SHELL", "TERM", "LANG", "LC_ALL", "LC_CTYPE", "TMPDIR"]
+
+export type CommandResult = { exitCode: number | null; stdout: string; stderr: string; timedOut: boolean }
+
+export async function runSandboxed(options: {
+  command: string
+  workspace: string
+  timeoutSeconds: number
+  secrets?: string[]
+}): Promise<CommandResult> {
+  if (!backend || !sandboxAvailable) throw new Error("No sandbox is available on this system")
+  // Sandboxes match real paths, so symbolic links such as /tmp -> /private/tmp are resolved first.
+  const workspace = await realpath(options.workspace)
+  const limits: Limits = {
+    workspace,
+    writable: [...new Set([workspace, await realpath(tmpdir())])],
+    protected: [join(workspace, ".git", "hooks"), join(workspace, ".git", "config")],
+    secrets: await Promise.all([...new Set([...secretPaths, ...(options.secrets ?? [])])].map(real)),
+  }
+  const child = Bun.spawn(backend.wrap(options.command, limits), {
+    cwd: workspace,
+    env: {
+      ...Object.fromEntries(passedEnvironment.flatMap((name) => (process.env[name] ? [[name, process.env[name]]] : []))),
+      PATH: await searchPath([...limits.writable, "/private/tmp", "/dev"], options.command),
+    },
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "pipe",
+    timeout: options.timeoutSeconds * 1000,
+  })
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+    child.exited,
+  ])
+  return { exitCode, stdout, stderr, timedOut: child.signalCode !== null }
+}
+
+// Bare command names must not select executables the model can replace. Check directories and executable links;
+// relative entries would also change their meaning after cd. Local tools can still run by an explicit path.
+async function searchPath(writable: string[], command: string): Promise<string> {
+  const outside = (target: string) => writable.every((root) => {
+    const fromRoot = relative(root, target)
+    return fromRoot === ".." || fromRoot.startsWith(`..${sep}`) || isAbsolute(fromRoot)
+  })
+  const programs = [...new Set(analyze(command).commands.flatMap(([program]) => program && !program.includes("/") ? [program] : []))]
+  const entries = await Promise.all((process.env.PATH ?? "/usr/bin:/bin").split(delimiter).map(async (entry) => {
+    if (!isAbsolute(entry)) return undefined
+    const target = await realpath(entry).catch(() => undefined)
+    if (!target || !outside(target)) return undefined
+    const executables = await Promise.all(programs.map((program) => existingPath(join(target, program)))).catch(() => undefined)
+    return executables?.every((executable) => executable === undefined || outside(executable)) ? target : undefined
+  }))
+  const path = [...new Set(entries.filter((entry) => entry !== undefined))].join(delimiter)
+  if (!path) throw new Error("PATH has no command directories outside the writable locations")
+  return path
+}
+
+// A dangling executable link is unsafe too: its target could be created inside the workspace before execution.
+async function existingPath(path: string): Promise<string | undefined> {
+  try { lstatSync(path) } catch { return undefined }
+  return realpath(path)
+}
+
+// The real path where it exists; a path that does not exist yet has nothing to resolve.
+function real(path: string): Promise<string> {
+  return realpath(path).catch(() => path)
+}
+
+// Later rules win: everything is allowed, then network and writes are taken away, then a few writes come back.
+// macOS keeps temporary files under /private/tmp too, and /dev must stay writable for /dev/null.
+export function seatbeltProfile(limits: Omit<Limits, "workspace">): string {
+  const rule = (verdict: string, operation: string, targets: string[]) =>
+    targets.length > 0 ? [`(${verdict} ${operation} ${targets.map((p) => `(subpath ${JSON.stringify(p)})`).join(" ")})`] : []
+  return [
+    "(version 1)",
+    "(allow default)",
+    "(deny network*)",
+    "(deny file-write*)",
+    ...rule("allow", "file-write*", [...limits.writable, "/private/tmp", "/dev"]),
+    ...rule("deny", "file-write*", limits.protected),
+    ...rule("deny", "file-read*", limits.secrets),
+    ...rule("deny", "file-write*", limits.secrets),
+  ].join("\n")
+}
+
+// Later mounts cover earlier ones: the whole system read-only, then the writable places, then the protected
+// ones read-only again, then the secrets covered by emptiness. The network is a fresh one with nothing in it.
+export function bubblewrapArgs(limits: Limits): string[] {
+  return [
+    "bwrap",
+    "--ro-bind", "/", "/",
+    "--dev", "/dev",
+    "--proc", "/proc",
+    ...limits.writable.flatMap((path) => ["--bind", path, path]),
+    ...limits.protected.flatMap((path) => ["--ro-bind-try", path, path]),
+    ...limits.secrets.flatMap(hidden),
+    "--unshare-net",
+    "--unshare-pid",
+    "--new-session",
+    "--die-with-parent",
+    "--chdir", limits.workspace,
+  ]
+}
+
+// A secret directory becomes an empty one and a secret file an empty file; what does not exist needs no cover.
+function hidden(path: string): string[] {
+  try {
+    return lstatSync(path).isDirectory() ? ["--tmpfs", path] : ["--ro-bind", "/dev/null", path]
+  } catch {
+    return []
+  }
+}