mirab 0.0.0-stage → 0.2.0

package/src/api/events-contract.ts

@@ -0,0 +1,103 @@
+// Generated by gild-site/scripts/generate-api-client.mjs. Edit the site source.
+import { z } from 'zod'
+export const EVENT_NAMES = [
+  'channel.mention',
+  'session',
+  'runner',
+  'push',
+  'pull_request',
+  'pull_request_review',
+  'pull_request_review_comment',
+  'issues',
+  'issue_comment',
+  'workflow_run',
+  'workflow_job',
+  'ping',
+  'merge_queue',
+  'agent_request',
+  'health_changed',
+  'webhook_disabled',
+] as const
+export const eventName = z.enum(EVENT_NAMES)
+export const hookInput = z.object({
+  name: z.literal('web').default('web'),
+  config: z.object({
+    url: z.string().url(),
+    content_type: z.enum(['json', 'form']).default('json'),
+    secret: z.string().min(1).max(256),
+    insecure_ssl: z.enum(['0']).default('0'),
+  }),
+  events: z.array(eventName).min(1).max(20).default(['push']),
+  active: z.boolean().default(true),
+})
+export const hookPatch = z.object({
+  config: hookInput.shape.config.partial().optional(),
+  events: z.array(eventName).min(1).max(20).optional(),
+  active: z.boolean().optional(),
+})
+export const hookSchema = z.object({
+  id: z.number().int(),
+  name: z.literal('web'),
+  type: z.enum(['Repository', 'Organization']),
+  active: z.boolean(),
+  events: z.array(eventName),
+  config: z.object({
+    url: z.string(),
+    content_type: z.enum(['json', 'form']),
+    insecure_ssl: z.literal('0'),
+  }),
+  created_at: z.string(),
+  updated_at: z.string(),
+  url: z.string(),
+  ping_url: z.string(),
+  deliveries_url: z.string(),
+  disabled_reason: z.string().nullable(),
+})
+export const streamEvent = z.object({
+  id: z.string(),
+  cursor: z.string(),
+  event: eventName,
+  repository: z.string().nullable(),
+  created_at: z.string(),
+  payload: z.record(z.string(), z.unknown()),
+})
+export const eventPage = z.object({
+  events: z.array(streamEvent),
+  cursor: z.string(),
+})
+export const deliverySchema = z.object({
+  id: z.number().int().positive(),
+  guid: z.string(),
+  delivered_at: z.string().nullable(),
+  redelivery: z.boolean(),
+  duration: z.number(),
+  status: z.string(),
+  status_code: z.number().nullable(),
+  event: eventName,
+  action: z.string().nullable(),
+  attempts: z.number().int(),
+  request: z.object({
+    headers: z.record(z.string(), z.string()),
+    payload: z.record(z.string(), z.unknown()),
+    wire: z.string(),
+  }),
+  response: z.object({
+    headers: z.record(z.string(), z.string()),
+    payload: z.string(),
+    truncated: z.boolean(),
+  }),
+  error: z.string().nullable(),
+})
+export type HookInput = z.output<typeof hookInput>
+export type HookPatch = z.output<typeof hookPatch>
+export type Hook = z.output<typeof hookSchema>
+export type StreamEvent = z.output<typeof streamEvent>
+export type Delivery = z.output<typeof deliverySchema>
+export interface Emission {
+  created_at?: string
+  id: string
+  event: (typeof EVENT_NAMES)[number]
+  repository: string | null
+  audience?: string
+  payload: Record<string, unknown>
+}

package/src/api/import-contract.ts

@@ -0,0 +1,22 @@
+// Generated by gild-site/scripts/generate-api-client.mjs. Edit the site source.
+import { z } from 'zod'
+const text = z.string().max(65536), id = z.string().regex(/^[A-Za-z0-9_.:-]{1,160}$/)
+const at = z.string().datetime(), number = z.number().int().positive().max(1_000_000_000)
+export const provenance = z.object({ forge: z.enum(['github','gitlab']), url: z.string().url(), author: z.string().max(200), id, updatedAt: at, state:z.string().optional(),closedAt:at.nullable().optional(),mergedAt:at.nullable().optional() })
+const base = { number, title: text, body: text, bodyParts:z.number().int().positive().max(128).optional(), createdAt: at, imported: provenance }
+export const importRecord = z.discriminatedUnion('kind', [
+  z.object({ kind:z.literal('issue'), ...base, state:z.enum(['open','closed']), labels:z.array(z.string().max(200)).max(100) }),
+  z.object({ kind:z.literal('pull'), ...base, state:z.enum(['open','closed','merged']), head:z.string().max(300), base:z.string().max(300), sourceRef:z.string().max(300), labels:z.array(z.string().max(200)).max(100).optional(),sourceHead:z.object({ref:z.string(),sha:z.string().nullable(),repository:z.string().nullable()}).optional(), patchParts:z.number().int().nonnegative().optional(), merged:z.object({ by:text, at, commit:z.string().regex(/^[a-f0-9]{40}$/) }).optional() }),
+  z.object({ kind:z.enum(['comment','review']), number, target:z.enum(['issue','pr']), id, body:text, bodyParts:z.number().int().positive().max(128).optional(), createdAt:at, imported:provenance, verdict:z.enum(['approve','changes','comment']).optional(), headOid:z.string().nullable().optional(), path:text.optional(), line:z.number().int().optional(), side:z.enum(['LEFT','RIGHT']).optional() }),
+  z.object({ kind:z.literal('label'), id, name:z.string().max(200), color:z.string().max(10), description:text }),
+  z.object({kind:z.literal('body'),number,target:z.enum(['issue','pr']),record:z.enum(['issue','pull','comment','review']),id:id.optional(),createdAt:at,version:at,part:z.number().int().nonnegative().max(127),parts:z.number().int().positive().max(128),text:z.string().max(8192)}),
+  z.object({ kind:z.literal('patch'), number, part:z.number().int().nonnegative().max(100000), text:z.string().max(16384) }),
+])
+export type ImportRecord = z.infer<typeof importRecord>
+export const importInput = z.object({ url:z.string().min(1).max(2048), name:z.string().regex(/^[a-z0-9][a-z0-9._-]{0,62}$/i).optional(), private:z.boolean().optional(), mirror:z.boolean().default(false), source_token:z.string().max(16384).optional(), forge:z.enum(['github','gitlab','git']).optional() })
+export const importProgress = z.object({ phase:z.enum(['git','metadata','workflows']), completed:z.number().int().nonnegative(), message:z.string().max(200), checkpoint:z.string().max(2048).optional(),default_branch:z.string().max(300).optional(),internal_prefix:z.string().regex(/^import_*\/pr$/).optional() })
+export const importSummary=z.object({branches:z.number().int().nonnegative(),tags:z.number().int().nonnegative(),commits:z.number().int().nonnegative(),records:z.number().int().nonnegative(),elapsed_ms:z.number().nonnegative()})
+export const importStatus = z.object({ repository:z.string(), source:z.string(), mirror:z.boolean(), state:z.enum(['queued','running','complete','mirroring','failed','cutover']), progress:importProgress, warnings:z.array(z.string()), error:z.string().nullable(), updated_at:z.string(), next_sync:z.string().nullable(),summary:importSummary.optional(),/** Too large for gild's servers: `gild clone` imports it locally. */local:z.boolean().optional() })
+export const importAssignment = z.object({ repository:z.string(), source:z.string(), forge:z.enum(['github','gitlab','git']), token:z.string(), source_token:z.string().optional(), mirror:z.boolean(), checkpoint:z.string() })
+export const importCredentials = z.object({ url:z.string(), token:z.string() })
+export const importBatch = z.object({ records:z.array(importRecord).max(40), progress:importProgress })

package/src/api/orchestrator-contract.ts

@@ -0,0 +1,73 @@
+// Generated by gild-site/scripts/generate-api-client.mjs. Edit the site source.
+import { z } from 'zod'
+// Orchestrator agents: a grant on a repo or org lets an agent spawn child
+// agents there, suspend and resume them, and read every agent's mentions.
+const text = z.string()
+export const agentGrant = z.enum(['pr', 'review', 'merge', 'coordinate', 'queue'])
+export const orchestratorGrant = z.object({
+  agent: text,
+  /** Where the grant lives: this repo, or the org that owns it. */
+  scope: z.enum(['repo', 'org']),
+  child_limit: z.number().int(),
+  /** Live (not revoked) children it holds, across every repo. */
+  children: z.number().int(),
+  granted_by: text,
+  granted_at: text,
+})
+export const orchestratorList = z.object({
+  orchestrators: z.array(orchestratorGrant),
+})
+export const orchestratorInput = z.object({
+  /** sponsor/label of an existing agent (an unknown one answers 404). */
+  agent: text.min(1).max(80),
+  child_limit: z.number().int().min(1).max(100).default(10),
+})
+export const orchestratorRevoked = z.object({
+  ok: z.literal(true),
+  agent: text,
+  /** Every descendant revoked with it. */
+  revoked: z.array(text),
+})
+export const childInput = z.object({
+  label: text.regex(/^[a-z0-9][a-z0-9-]{0,30}$/),
+  publicKey: text.regex(/^ed25519:[A-Za-z0-9+/=]{1,200}$/),
+  grants: z.array(agentGrant).max(3).default([]),
+  note: text.max(280).optional(),
+})
+export const childAgent = z.object({
+  name: text,
+  label: text,
+  /** The orchestrator that spawned it. */
+  sponsor: text,
+  /** The person behind the orchestrator, and so behind the child. */
+  human: text,
+  repo: text,
+  grants: z.array(agentGrant),
+  suspended: z.boolean(),
+  suspended_at: text.nullable(),
+  suspended_by: text.nullable(),
+  created_at: text,
+  revoked_at: text.nullable(),
+})
+export const spawnedChild = childAgent.extend({
+  request_id: text,
+  scopes: z.array(text),
+  /** Returned once; the server keeps only its hash. */
+  token: text,
+})
+export const suspension = z.object({
+  agent: text,
+  suspended: z.boolean(),
+  suspended_at: text.nullable(),
+  suspended_by: text.nullable(),
+})
+export type ChildAgent = z.output<typeof childAgent>
+/** Agent-facing operations: no token scope, the orchestrator grant (or a
+ *  person's repo admin) is checked by the orchestrator service itself. */
+export const ORCHESTRATED_OPERATIONS = ['childAgents', 'createChildAgent', 'suspendAgent', 'resumeAgent'] as const
+/** Every operation the orchestrator service executes. */
+export const ORCHESTRATOR_OPERATIONS = [
+  ...ORCHESTRATED_OPERATIONS,
+  'repoOrchestrators', 'setRepoOrchestrator', 'deleteRepoOrchestrator',
+  'orgOrchestrators', 'setOrgOrchestrator', 'deleteOrgOrchestrator',
+] as const

package/src/api/runner-contract.ts

@@ -0,0 +1,25 @@
+// Generated by gild-site/scripts/generate-api-client.mjs. Edit the site source.
+import { z } from 'zod'
+export const runnerRegistration = z.object({
+  name: z.string().regex(/^[a-zA-Z0-9][\w.-]{0,63}$/),
+  os: z.enum(['darwin', 'macos', 'linux', 'windows', 'win32']),
+  arch: z.enum(['x64', 'arm64', 'aarch64', 'amd64']),
+  labels: z
+    .array(z.string().regex(/^[\w.-]{1,64}$/))
+    .max(32)
+    .default([]),
+  group: z.string().min(1).default('default'),
+})
+export const runnerGroup = z.object({
+  id: z.string().min(1),
+  name: z.string().trim().min(1).max(64),
+  visibility: z.enum(['all', 'selected']),
+  allow_public_repositories: z.boolean(),
+  repositories: z
+    .array(z.string().regex(/^[a-zA-Z0-9][\w.-]*\/[a-zA-Z0-9][\w.-]*$/))
+    .max(1000),
+})
+export const groupInput = runnerGroup
+  .omit({ id: true })
+  .partial()
+  .extend({ name: runnerGroup.shape.name })

package/src/api/scopes.ts

@@ -0,0 +1,41 @@
+// Generated by gild-site/scripts/generate-api-client.mjs. Edit the site source.
+export const SCOPES = [
+  'repo:read',
+  'repo:write',
+  'channel:write',
+  'issues:write',
+  'pulls:write',
+  'actions',
+  'hooks',
+  'agents',
+  'admin',
+] as const
+export type Scope = (typeof SCOPES)[number]
+export interface Principal {
+  anonymous?: boolean
+  id: string
+  name: string
+  publicKey: string
+  scopes: readonly string[] | null
+  repos: readonly string[] | null
+}
+export function hasScope(p: Principal, scope: Scope) {
+  return p.scopes === null || p.scopes.includes(scope)
+}
+export function permitsRepo(p: Principal, owner: string, repo: string) {
+  return (
+    p.repos === null ||
+    p.repos.some((r) => r.toLowerCase() === `${owner}/${repo}`.toLowerCase())
+  )
+}
+export function grantScopes(grants: readonly string[]): Scope[] {
+  return [
+    'repo:read',
+    ...(grants.includes('pr')
+      ? (['repo:write', 'issues:write', 'pulls:write'] as const)
+      : []),
+    ...(grants.includes('review') || grants.includes('queue')
+      ? (['pulls:write'] as const)
+      : []),
+  ]
+}

package/src/api/sessions-contract.ts

@@ -0,0 +1,71 @@
+// Generated by gild-site/scripts/generate-api-client.mjs. Edit the site source.
+import { z } from 'zod'
+const path = z
+  .string()
+  .min(1)
+  .max(1024)
+  .refine(
+    (p) =>
+      !p.startsWith('/') &&
+      !p.split('/').includes('..') &&
+      !/[\x00-\x1f]/.test(p),
+    'Use a repository-relative path',
+  )
+/** Optional live state; no prompts, tool arguments or hook payloads. */
+export const sessionState = z.object({
+  status: z.enum(['unknown', 'busy', 'idle', 'waiting', 'tool_start', 'tool_end', 'ended']),
+  tool: z.string().regex(/^[a-zA-Z0-9_.:/-]{1,160}$/).optional(),
+  last_activity: z.iso.datetime(),
+}).strict()
+export const sessionInput = z
+  .object({
+    id: z.string().uuid().optional(),
+    agent: z.string().max(100).optional(),
+    started_at: z.iso.datetime(),
+    ended_at: z.iso.datetime().nullable().default(null),
+    state: sessionState.optional(),
+    model: z.string().min(1).max(120),
+    tokens_in: z.number().int().nonnegative().default(0),
+    tokens_out: z.number().int().nonnegative().default(0),
+    cost: z.number().nonnegative().optional(),
+    currency: z
+      .string()
+      .regex(/^[A-Z]{3}$/)
+      .default('USD'),
+    commands: z
+      .array(
+        z.object({
+          name: z.string().min(1).max(4096),
+          exit_code: z.number().int().nullable(),
+          duration_ms: z.number().nonnegative(),
+        }),
+      )
+      .max(200)
+      .default([]),
+    files: z
+      .object({
+        read: z.array(path).max(1000).default([]),
+        written: z.array(path).max(1000).default([]),
+      })
+      .default({ read: [], written: [] }),
+    notes: z.string().max(16000).default(''),
+  })
+  .refine(
+    (s) => !s.ended_at || Date.parse(s.ended_at) >= Date.parse(s.started_at),
+    'ended_at must follow started_at',
+  )
+export const receiptPayload = sessionInput.safeExtend({
+  id: z.string().uuid(),
+  agent: z.string(),
+  repository: z.string(),
+  target: z.string(),
+  created_at: z.iso.datetime(),
+  updated_at: z.iso.datetime(),
+  version: z.number().int().positive(),
+  closed: z.boolean(),
+})
+export const receiptSchema = receiptPayload.safeExtend({
+  reported_by: z.literal('agent').default('agent'),
+})
+export type SessionInput = z.output<typeof sessionInput>
+export type Receipt = z.output<typeof receiptSchema>

package/src/api/settings-contract.ts

@@ -0,0 +1,50 @@
+// Generated by gild-site/scripts/generate-api-client.mjs. Edit the site source.
+import { z } from 'zod'
+const link = z.union([
+  z.literal(''),
+  z
+    .url()
+    .max(2048)
+    .refine((s) => /^https?:\/\//.test(s), 'Use an http or https URL'),
+])
+const email = z.union([z.literal(''), z.email().max(254)])
+export const profileSchema = z.object({
+  displayName: z.string().max(100),
+  publicEmail: email,
+  description: z.string().max(1000),
+  url: link,
+  socialLinks: z.array(link).max(4),
+  location: z.string().max(100),
+  picture: z.string().nullable(),
+})
+export const profileInput = profileSchema
+  .omit({ picture: true })
+  .partial()
+  .strict()
+
+export const renameStatus = z.object({
+  job: z
+    .object({
+      id: z.string(),
+      from: z.string(),
+      to: z.string(),
+      org: z.boolean(),
+      orgOwner: z.boolean(),
+      phase: z.enum([
+        'waiting',
+        'copying',
+        'publishing',
+        'rebinding',
+        'rollback',
+        'complete',
+        'failed',
+      ]),
+      repos: z.array(
+        z.object({ from: z.string(), to: z.string(), id: z.string() }),
+      ),
+      copied: z.number(),
+      rebound: z.number(),
+      error: z.string().nullable(),
+    })
+    .nullable(),
+})

package/src/channel/bridge.ts

@@ -0,0 +1,97 @@
+// The station's end of an agent's channel: what other members say goes into
+// the agent's VM over its pty, and what the agent says there comes back as
+// the agent's messages (wire.ts). The VM is untrusted: only well-formed say
+// lines count, they are posted as the agent and nobody else, and an answer
+// may only point at a message the agent was given.
+import type { PtyHandle } from '../isolation/session'
+import type { LocalChannel } from './local'
+import {
+  decodeFromAgent,
+  decodeToAgent,
+  encodeToAgent,
+  lineSplitter,
+  printable,
+} from './wire'
+
+/** Lines of the VM's other output shown per chat. */
+const VM_LINES = 200
+
+export function bridgeAgent(o: {
+  channel: LocalChannel
+  /** The agent's member name. */
+  agent: string
+  pty: Pick<PtyHandle, 'write' | 'onData'>
+  /** Whatever else the VM printed (its errors), for the person's log. */
+  log?: (line: string) => void
+}): () => void {
+  const given = new Set<string>()
+  let off = false
+  // Nothing goes in until the guest says it is here: by then its pty is raw,
+  // so a message is neither echoed nor cut at the line-editing limit.
+  let ready = false
+  const queued: string[] = []
+  let refused = 0
+  let shown = 0
+  const post = (
+    text: string,
+    options: { note?: boolean; answers?: string },
+  ) => {
+    try {
+      o.channel.post(o.agent, text, options)
+      if (options.answers) given.delete(options.answers)
+      return true
+    } catch (e) {
+      // Said once, not once per message a flooding VM sends.
+      if (refused++ === 0)
+        o.log?.(`the agent's messages aren't taken: ${(e as Error).message}`)
+      return false
+    }
+  }
+  o.pty.onData(
+    lineSplitter((line) => {
+      if (off) return
+      const said = decodeFromAgent(line)
+      if (!said) {
+        // The pty echoing a message is neither the agent speaking nor worth
+        // showing; anything else is, made safe for a terminal.
+        if (line.trim() && !decodeToAgent(line)) {
+          // Enough to see what went wrong; never a firehose.
+          shown++
+          if (shown <= VM_LINES)
+            o.log?.(`(vm) ${printable(line.slice(0, 500))}`)
+          else if (shown === VM_LINES + 1)
+            o.log?.('(vm) … more output from the VM is not shown')
+        }
+        return
+      }
+      const answers =
+        said.answers && given.has(said.answers) ? said.answers : undefined
+      if (!post(said.text, { note: said.note, answers }) && answers)
+        // An answer that couldn't be kept still finishes its message, so the
+        // chat can end; the station says why, not the VM.
+        try {
+          o.channel.post(o.agent, "the agent's answer couldn't be kept", {
+            note: true,
+            answers,
+            reserved: true,
+          })
+          given.delete(answers)
+        } catch {}
+      if (!ready && said.note) {
+        ready = true
+        for (const line of queued.splice(0)) o.pty.write(line)
+      }
+    }),
+  )
+  const stop = o.channel.onMessage((m) => {
+    if (m.from === o.agent || m.note) return
+    given.add(m.id)
+    const line = encodeToAgent({ id: m.id, from: m.from, text: m.text })
+    if (ready) o.pty.write(line)
+    else queued.push(line)
+  })
+  return () => {
+    off = true
+    stop()
+  }
+}

package/src/channel/local.ts

@@ -0,0 +1,154 @@
+// A channel the station hosts (docs/architecture.md section 4; harar section
+// 3b): the chat in `mirab dev` between the person at this terminal and the
+// agent in its VM. The station is the app here: it holds the messages, one
+// JSON line each, in a file only this machine's user can read, and never lets
+// them leave the machine. Membership is fixed when the channel opens; a
+// message is untrusted input from whoever wrote it, and being a member grants
+// nothing else. A channel id is never reused, so a new chat never shows an
+// old one's messages.
+import { randomBytes } from 'node:crypto'
+import { appendFileSync, mkdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** The longest message a channel takes; a longer one is refused, never cut. */
+export const MAX_MESSAGE = 64 * 1024
+/** The most a station keeps for one channel, so a VM that floods it can't
+ *  fill the disk. */
+export const MAX_CHANNEL = 64 * 1024 * 1024
+
+export interface Member {
+  /** An actor's harar name, e.g. `gg.addis.human.sami`, `gg.addis.agent.ops`. */
+  name: string
+  can: 'speak' | 'listen'
+  /** Named by this machine alone: nothing (no harar token) vouched for it. */
+  unverified?: true
+}
+
+export interface Message {
+  /** Never reused, and ordered by the millisecond: a ULID. */
+  id: string
+  from: string
+  at: string
+  text: string
+  /** Said about the chat (the agent reloaded, a turn failed), not in it. */
+  note?: true
+  /** The message this finishes: its reply, or why there is none. */
+  answers?: string
+}
+
+export interface LocalChannel {
+  /** `<org>.channel.ch-<ulid>` */
+  readonly id: string
+  readonly members: readonly Member[]
+  /** Where the messages are kept. */
+  readonly path: string
+  post(
+    from: string,
+    text: string,
+    options?: {
+      note?: boolean
+      answers?: string
+      /** The station's own note: it may use the room kept back for it, so
+       *  whatever fills the channel, a message can still be answered. */
+      reserved?: boolean
+    },
+  ): Message
+  messages(): Message[]
+  /** Every message posted from now on, in order. */
+  onMessage(listener: (message: Message) => void): () => void
+}
+
+const CROCKFORD = '0123456789ABCDEFGHJKMNPQRSTVWXYZ'
+
+/** 48 bits of milliseconds and 80 random bits, in Crockford base32. */
+export function ulid(now = Date.now()): string {
+  let time = ''
+  for (let t = now, i = 0; i < 10; i++, t = Math.floor(t / 32))
+    time = CROCKFORD[t % 32] + time
+  let random = ''
+  const bytes = randomBytes(10)
+  let bits = 0
+  let value = 0
+  for (const byte of bytes) {
+    value = (value << 8) | byte
+    bits += 8
+    while (bits >= 5) {
+      bits -= 5
+      random += CROCKFORD[(value >> bits) & 31]
+    }
+    value &= (1 << bits) - 1
+  }
+  return time + random
+}
+
+export function openChannel(o: {
+  /** The directory the station keeps channels in (private to this user). */
+  dir: string
+  /** The org whose channel it is: the hosting agent's. */
+  org: string
+  members: Member[]
+  now?: () => Date
+  /** Tests make it small. */
+  maxBytes?: number
+}): LocalChannel {
+  const now = o.now ?? (() => new Date())
+  const id = `${o.org}.channel.ch-${ulid(now().getTime()).toLowerCase()}`
+  const path = join(o.dir, `${id}.jsonl`)
+  const members = o.members.map((m) => ({ ...m }))
+  const byName = new Map(members.map((m) => [m.name, m]))
+  if (byName.size !== members.length)
+    throw new Error('a channel lists each member once')
+  mkdirSync(o.dir, { recursive: true, mode: 0o700 })
+  // The first line says what the channel is; `flag: 'wx'` because an id is
+  // never reused.
+  appendFileSync(
+    path,
+    JSON.stringify({ channel: id, members, opened: now().toISOString() }) +
+      '\n',
+    { mode: 0o600, flag: 'wx' },
+  )
+  const listeners = new Set<(message: Message) => void>()
+  let kept = 0
+  return {
+    id,
+    members,
+    path,
+    post(from, text, options) {
+      const member = byName.get(from)
+      if (!member) throw new Error(`${from} isn't a member of ${id}`)
+      if (member.can !== 'speak')
+        throw new Error(`${from} only listens in ${id}`)
+      if (Buffer.byteLength(text) > MAX_MESSAGE)
+        throw new Error(`a message is at most ${MAX_MESSAGE} bytes`)
+      const at = now()
+      const message: Message = {
+        id: ulid(at.getTime()),
+        from,
+        at: at.toISOString(),
+        text,
+        ...(options?.note ? { note: true as const } : {}),
+        ...(options?.answers ? { answers: options.answers } : {}),
+      }
+      const line = JSON.stringify(message) + '\n'
+      const max = o.maxBytes ?? MAX_CHANNEL
+      const room = options?.reserved ? max : max - Math.min(max / 8, 1 << 20)
+      if (kept + Buffer.byteLength(line) > room)
+        throw new Error(`${id} is full; open a new chat`)
+      appendFileSync(path, line)
+      kept += Buffer.byteLength(line)
+      for (const listener of listeners) listener(message)
+      return message
+    },
+    messages() {
+      return readFileSync(path, 'utf8')
+        .split('\n')
+        .slice(1)
+        .filter(Boolean)
+        .map((line) => JSON.parse(line) as Message)
+    },
+    onMessage(listener) {
+      listeners.add(listener)
+      return () => void listeners.delete(listener)
+    },
+  }
+}

package/src/channel/state.ts

@@ -0,0 +1,11 @@
+// Generated by gild-site/scripts/generate-api-client.mjs. Edit the site source.
+import { z } from 'zod'
+import { sessionState } from '../api/sessions-contract.ts'
+export const channelState = sessionState
+export type ChannelState = z.output<typeof channelState>
+export function stateLabel(state: ChannelState) {
+  if (state.status === 'waiting') return '◐ waiting'
+  if (state.status === 'busy' || state.status === 'tool_start') return '● busy' + (state.tool ? ` · ${state.tool}` : '')
+  if (['idle', 'tool_end', 'ended'].includes(state.status)) return '○ idle'
+  return '○ unknown'
+}