mirab 0.0.0 → 0.2.0

package/src/agent/approved.ts

@@ -0,0 +1,261 @@
+// What a person approved a project's agent to reach: its manifest's domains
+// (the station's whitelist) and packages (its image). The manifest is read
+// from the agent's own code in its VM, and that code can change: in the VM,
+// through a file it imports from outside agent/, through package.json. So
+// whatever the manifest asks for now is checked against what the person
+// approved; anything new waits (`mirab manifest approve`), never quietly in
+// effect. Its gateway section (rixse's rules and secrets) is approved as a
+// whole: the one in force is the one the person approved, and any change,
+// even one that looks narrower, waits. Tools need no approval: they run in the VM, and what they can reach
+// is still the whitelist and the station.
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { fileName, projectAgent, ruleProblem, writeJson } from 'rixse'
+import { UNSHOWABLE } from './define'
+import { manifestSchema, type Manifest } from './manifest'
+
+export type Gateway = Manifest['gateway']
+
+export interface Reach {
+  domains: string[]
+  packages: string[]
+  /** As approved; `{}` is no rules (rixse's defaults). */
+  gateway: Gateway
+}
+
+const reachPath = (configDir: string, project: string, kind: string) =>
+  join(
+    configDir,
+    'manifests',
+    `${fileName(projectAgent(project))}.${kind}.json`,
+  )
+
+/** One spelling for one gateway section: rules in a fixed order (rixse
+ *  decides by specificity, never by order), secrets by host. */
+function canonical(g: Gateway): Gateway {
+  const out: Gateway = {}
+  if (g.rules?.length)
+    out.rules = [
+      ...new Map(
+        g.rules.map((r) => {
+          const rule = {
+            host: r.host,
+            ...(r.method !== undefined && { method: r.method }),
+            ...(r.path !== undefined && { path: r.path }),
+            effect: r.effect,
+          }
+          return [JSON.stringify(rule), rule] as const
+        }),
+      ).entries(),
+    ]
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+      .map(([, r]) => r)
+  const hosts = Object.keys(g.secrets ?? {}).sort()
+  if (hosts.length)
+    out.secrets = Object.fromEntries(
+      hosts.map((h) => {
+        const { agent, approved } = g.secrets![h]
+        return [h, { agent, ...(approved !== undefined && { approved }) }]
+      }),
+    )
+  return out
+}
+
+/** Why rixse would refuse `g` when a session starts, or null: checked before
+ *  a section is recorded or waits, so one can never be approved and then stop
+ *  every session. */
+export function gatewayProblem(g: Gateway): string | null {
+  for (const r of g.rules ?? []) {
+    const problem = ruleProblem(r)
+    if (problem) return problem
+  }
+  return null
+}
+
+const same = (a: Gateway, b: Gateway) =>
+  JSON.stringify(canonical(a)) === JSON.stringify(canonical(b))
+
+const reachOf = (
+  m: Pick<Manifest, 'domains' | 'packages' | 'gateway'>,
+): Reach => ({
+  domains: [...new Set(m.domains)].sort(),
+  packages: [...new Set(m.packages)].sort(),
+  gateway: canonical(m.gateway),
+})
+
+/** A reach file: missing (nothing yet), or what it holds; a file that is
+ *  there but doesn't read as one is an error, never "nothing yet", so a
+ *  damaged or tampered file can't turn into a first run that approves all. */
+function read(path: string): Reach | undefined {
+  let text: string
+  try {
+    text = readFileSync(path, 'utf8')
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code === 'ENOENT') return undefined
+    throw e
+  }
+  let r: unknown
+  try {
+    r = JSON.parse(text)
+  } catch {
+    r = undefined
+  }
+  if (r === null) return undefined
+  const ok = (v: unknown): v is string[] =>
+    Array.isArray(v) && v.every((x) => typeof x === 'string')
+  const reach = r as Partial<Reach> | undefined
+  if (!reach || !ok(reach.domains) || !ok(reach.packages))
+    throw new Error(`${path} doesn't read as an approval; fix or remove it`)
+  // An approval from before gateway sections approved none.
+  const gateway = reach.gateway ?? {}
+  const parsed = manifestSchema.shape.gateway.safeParse(gateway)
+  if (!parsed.success || gatewayProblem(parsed.data))
+    throw new Error(`${path} doesn't read as an approval; fix or remove it`)
+  return {
+    domains: reach.domains,
+    packages: reach.packages,
+    gateway: canonical(parsed.data),
+  }
+}
+
+/** What the person approved for `project`'s agent, if anything yet. */
+export const approvedReach = (configDir: string, project: string) =>
+  read(reachPath(configDir, project, 'approved'))
+
+/** What the agent last asked for beyond its approval, waiting. */
+export const pendingReach = (configDir: string, project: string) =>
+  read(reachPath(configDir, project, 'pending'))
+
+export interface Beyond {
+  domains: string[]
+  packages: string[]
+  /** The gateway section asked for, when it isn't the approved one. */
+  gateway?: Gateway
+}
+
+/** What `asked` adds to `approved`. */
+export const beyond = (approved: Reach, asked: Reach): Beyond => ({
+  domains: asked.domains.filter((d) => !approved.domains.includes(d)),
+  packages: asked.packages.filter((p) => !approved.packages.includes(p)),
+  ...(!same(approved.gateway, asked.gateway) && { gateway: asked.gateway }),
+})
+
+const isEmpty = (r: Beyond) =>
+  !r.domains.length && !r.packages.length && !r.gateway
+
+/**
+ * The manifest as it may run: its domains and packages narrowed to what the
+ * person approved. Only a session the person starts (`record`, mirab dev)
+ * records a first approval, and says what it was; anything else (looking at
+ * the manifest, building its image) approves nothing. After that, anything
+ * new is left out, kept as pending, and said; what the agent no longer asks
+ * for is no longer approved, so dropping something and adding it back asks
+ * again.
+ */
+export function withinApproval(
+  configDir: string,
+  project: string,
+  manifest: Manifest,
+  o: { record: boolean; log?: (line: string) => void },
+): Manifest {
+  const asked = reachOf(manifest)
+  // A section rixse would refuse is never recorded nor waits: the one
+  // approved before, if any, stays, and the person is told why.
+  const problem = gatewayProblem(asked.gateway)
+  if (problem) {
+    asked.gateway = approvedReach(configDir, project)?.gateway ?? {}
+    o.log?.(`the agent's gateway section can't be used (${problem}): left out`)
+  }
+  const approvedPath = reachPath(configDir, project, 'approved')
+  const pendingPath = reachPath(configDir, project, 'pending')
+  let approved = approvedReach(configDir, project)
+  if (!approved) {
+    if (!o.record) {
+      approved = { domains: [], packages: [], gateway: {} }
+    } else {
+      writeJson(approvedPath, asked)
+      writeJson(pendingPath, null)
+      if (!isEmpty(asked))
+        o.log?.(
+          `first run here: approved ${describe(asked)} (later changes wait for mirab manifest approve)`,
+        )
+      return { ...manifest, gateway: asked.gateway }
+    }
+  } else {
+    // What it stopped asking for stops being approved.
+    const kept: Reach = {
+      domains: approved.domains.filter((d) => asked.domains.includes(d)),
+      packages: approved.packages.filter((p) => asked.packages.includes(p)),
+      // The approved section stays in force until a new one is approved.
+      gateway: approved.gateway,
+    }
+    if (
+      kept.domains.length !== approved.domains.length ||
+      kept.packages.length !== approved.packages.length
+    ) {
+      writeJson(approvedPath, kept)
+      approved = kept
+    }
+  }
+  const extra = beyond(approved, asked)
+  if (isEmpty(extra)) {
+    // Nothing waits any more: an old ask can't be approved later by mistake.
+    writeJson(pendingPath, null)
+  } else {
+    writeJson(pendingPath, asked)
+    o.log?.(
+      `the agent's definition asks for ${describe(extra)}, which you haven't approved: left out. If that was you, run mirab manifest approve here (never in the VM)`,
+    )
+  }
+  return {
+    ...manifest,
+    domains: manifest.domains.filter((d) => approved.domains.includes(d)),
+    packages: manifest.packages.filter((p) => approved.packages.includes(p)),
+    gateway: approved.gateway,
+  }
+}
+
+/** The person's yes to what waits, exactly as they were shown it: `shown`
+ *  must equal what is pending now, or nothing is approved. */
+export function approvePending(
+  configDir: string,
+  project: string,
+  shown: Reach,
+): Reach | undefined {
+  const pending = pendingReach(configDir, project)
+  if (!pending) return undefined
+  if (JSON.stringify(pending) !== JSON.stringify(shown))
+    throw new Error('what waits changed since it was shown; look again')
+  writeJson(reachPath(configDir, project, 'approved'), pending)
+  writeJson(reachPath(configDir, project, 'pending'), null)
+  return pending
+}
+
+export function describe(r: Beyond) {
+  const parts = [
+    r.domains.length && `domains ${r.domains.join(', ')}`,
+    r.packages.length && `packages ${r.packages.join(', ')}`,
+    r.gateway && `the gateway section ${describeGateway(r.gateway)}`,
+  ].filter(Boolean)
+  return parts.join(' and ')
+}
+
+/** A gateway section in full, as a person approves it: every rule and key. */
+export function describeGateway(g: Gateway) {
+  // The schema refuses these; an approval file is still escaped, never trusted.
+  const shown = (s: string) =>
+    s.replace(
+      new RegExp(UNSHOWABLE.source, 'g'),
+      (c) => `\\u{${c.codePointAt(0)!.toString(16)}}`,
+    )
+  const c = canonical(g)
+  const rules = (c.rules ?? []).map(
+    (r) => `${r.effect} ${r.method ?? '*'} ${r.host}${shown(r.path ?? '/*')}`,
+  )
+  const secrets = Object.entries(c.secrets ?? {}).map(
+    ([h, k]) =>
+      `${h} uses ${shown(k.agent)}${k.approved ? ` (approved sends: ${shown(k.approved)})` : ''}`,
+  )
+  const all = [...rules, ...secrets]
+  return all.length ? `(${all.join('; ')})` : '(no rules: rixse defaults)'
+}

package/src/agent/define.ts

@@ -0,0 +1,235 @@
+// What an agent folder declares: `agent/agent.ts` exports defineAgent(...),
+// and each file in `agent/tools/` exports defineTool(...). The shape follows
+// Vercel's eve, so its users know it; everything runs inside the agent's VM.
+import { z } from 'zod'
+
+/** One harar label: [a-z0-9-], 1–63 characters, not starting or ending with `-`. */
+const LABEL = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/
+
+/** The kinds harar reserves; none of them is ever an org label. These follow
+ *  harar's design (docs/architecture.md section 2, with app and channel from
+ *  section 3b), which harar's code (harar-client model.rs) is catching up to. */
+const KINDS = new Set([
+  'human',
+  'user',
+  'agent',
+  'service',
+  'broker',
+  'zone',
+  'role',
+  'profile',
+  'app',
+  'channel',
+])
+
+/** Why `name` isn't a harar name of `kind` (`<org>.<kind>.<local>`), or null. */
+export function nameProblem(
+  name: string,
+  kind: 'agent' | 'channel' | 'human',
+  example: string,
+): string | null {
+  if (name.length > 253) return 'is longer than 253 characters'
+  const labels = name.split('.')
+  const at = labels.findIndex((label) => KINDS.has(label))
+  if (at < 0 || labels[at] !== kind)
+    return `needs the form <org>.${kind}.<name>, like ${example}`
+  if (at < 2) return `needs an org of two or more labels, like ${example}`
+  if (at !== labels.length - 2)
+    return `has one label after .${kind}., like ${example}`
+  const bad = labels.find((label) => !LABEL.test(label))
+  if (bad !== undefined)
+    return `has a label that isn't [a-z0-9-] (1–63, no leading or trailing -): ${JSON.stringify(bad)}`
+  return null
+}
+
+/** Why `name` isn't an agent name (`<org>.agent.<local>`, harar's rules), or null. */
+export function agentNameProblem(name: string): string | null {
+  return nameProblem(name, 'agent', 'gg.addis.agent.ops')
+}
+
+/** Why `name` isn't a human's harar name (`<org>.human.<local>`), or null. */
+export function humanNameProblem(name: string): string | null {
+  return nameProblem(name, 'human', 'gg.addis.human.sami')
+}
+
+const agentName = z.string().superRefine((name, ctx) => {
+  const problem = agentNameProblem(name)
+  if (problem)
+    ctx.addIssue({ code: 'custom', message: `agent name ${problem}` })
+})
+
+/** `provider/model`, e.g. `anthropic/claude-sonnet-5-5`. */
+export const MODEL = /^[a-z0-9-]+\/[A-Za-z0-9._-]+$/
+const model = z
+  .string()
+  .regex(MODEL, 'model is provider/model, like anthropic/claude-sonnet-5-5')
+
+/** A tool's name is its file's name, or its key in `tools`; the model sees exactly that. */
+export const TOOL_NAME = /^[a-zA-Z0-9_-]{1,64}$/
+
+/** Why `name` can't be a tool's name, or null. `__proto__` is refused: as a
+ *  key in plain data it is dropped or changes the object, never a tool. */
+export function toolNameProblem(name: string): string | null {
+  if (!TOOL_NAME.test(name))
+    return "a tool's name is [a-zA-Z0-9_-] up to 64 characters"
+  if (name === '__proto__') return "__proto__ can't be a tool's name"
+  return null
+}
+
+/** A tool's input: a JSON Schema for an object, which is what models take. */
+export const toolInput = z
+  .record(z.string(), z.unknown())
+  .refine((schema) => schema.type === 'object', {
+    message: 'a tool input is a JSON Schema with type "object"',
+  })
+
+/** A tool that is an executable in the VM: the model's input as JSON on its
+ *  stdin (checked against `input` first), its answer as JSON on stdout. */
+export const commandToolSchema = z.strictObject({
+  description: z.string().trim().min(1, 'a tool needs a description'),
+  /** An executable: on the VM's PATH, absolute, or `./` from the project. */
+  command: z.string().min(1),
+  args: z.array(z.string()).optional(),
+  input: toolInput.superRefine((schema, ctx) => {
+    try {
+      z.fromJSONSchema(schema)
+    } catch (e) {
+      ctx.addIssue({
+        code: 'custom',
+        message: `the input schema can't be checked: ${(e as Error).message}`,
+      })
+    }
+  }),
+  /** How long one call may take; TOOL_TIMEOUT_MS if unset. */
+  timeoutMs: z.number().int().positive().optional(),
+})
+export type CommandTool = z.infer<typeof commandToolSchema>
+
+const toolName = z.string().superRefine((name, ctx) => {
+  const problem = toolNameProblem(name)
+  if (problem) ctx.addIssue({ code: 'custom', message: problem })
+})
+
+/** Tools by name. zod's record drops a `__proto__` key before checking it,
+ *  so the raw data is checked for one first. */
+export function toolRecord<T extends z.ZodType>(tool: T) {
+  return z
+    .unknown()
+    .superRefine((data, ctx) => {
+      if (data && typeof data === 'object' && Object.hasOwn(data, '__proto__'))
+        ctx.addIssue({ code: 'custom', message: toolNameProblem('__proto__')! })
+    })
+    .pipe(z.record(toolName, tool))
+}
+
+/** A package in the agent's VM image, by name (a nixpkgs attribute, later). */
+const packageName = z.string().regex(
+  // Never ending in -, which apt reads as "remove" (g++ is fine).
+  /^[a-zA-Z0-9](?:[a-zA-Z0-9._+-]{0,126}[a-zA-Z0-9+])?$/,
+  'a package is a name, like ripgrep',
+)
+
+/** A whitelist entry as the station matches it: `api.github.com`, or
+ *  `*.github.com` for every name under it. Names only, never an address. */
+export function domainProblem(domain: string): string | null {
+  const labels = (domain.startsWith('*.') ? domain.slice(2) : domain).split('.')
+  if (domain.length > 253) return 'is longer than 253 characters'
+  if (labels.length < 2) return 'needs two or more labels, like api.github.com'
+  if (labels.some((label) => !LABEL.test(label)))
+    return 'is lowercase labels of [a-z0-9-], with only a leading *. as a wildcard'
+  // A name's last label starts with a letter; 127.0.0x1 and 1.0x7f are addresses.
+  if (!/^[a-z]/.test(labels.at(-1)!)) return 'is a name, not an address'
+  return null
+}
+const domain = z.string().superRefine((d, ctx) => {
+  const problem = domainProblem(d)
+  if (problem) ctx.addIssue({ code: 'custom', message: `domain ${problem}` })
+})
+
+const channel = z.string().superRefine((name, ctx) => {
+  const problem = nameProblem(name, 'channel', 'gg.addis.channel.ops')
+  if (problem) ctx.addIssue({ code: 'custom', message: `channel ${problem}` })
+})
+
+/** Characters that can make a terminal show something other than the text:
+ *  controls, C1 controls, line separators and bidirectional overrides. A
+ *  person approves rules by reading them, so none may appear in one. */
+export const UNSHOWABLE =
+  /[\u0000-\u001f\u007f-\u009f\u200e\u200f\u2028\u2029\u202a-\u202e\u2066-\u2069]/
+
+const showable = (what: string) =>
+  z
+    .string()
+    .refine(
+      (s) => !UNSHOWABLE.test(s),
+      `${what} has a character a terminal can't show as itself`,
+    )
+
+/** A harar secret path: `/`-separated segments, none empty, `.` or `..`. */
+const secretPath = showable('a secret').refine(
+  (p) => p.split('/').every((s) => s !== '' && s !== '.' && s !== '..'),
+  'a secret is a harar path, like prod/shop/STRIPE_KEY',
+)
+
+/** One of rixse's gateway rules. Its shape is checked here, in the VM; the
+ *  gateway checks its meaning when a session starts, on the host. */
+const gatewayRule = z.strictObject({
+  host: domain,
+  method: z
+    .string()
+    .regex(/^(\*|[A-Za-z]+)$/, 'method is a method name or *')
+    .optional(),
+  path: showable('a path').startsWith('/', 'path starts with /').optional(),
+  effect: z.enum(['apply', 'request', 'forbidden']),
+})
+
+/** What agent/agent.ts declares. TypeScript tools are files in agent/tools/;
+ *  `tools` here holds command tools. */
+export const agentSchema = z.strictObject({
+  /** The agent's harar name: its identity everywhere it goes. */
+  name: agentName,
+  model,
+  tools: toolRecord(commandToolSchema).optional(),
+  /** What its VM image holds besides the base. */
+  packages: z.array(packageName).optional(),
+  /** Its zone's whitelist: the only names the station lets it reach. */
+  domains: z.array(domain).optional(),
+  /** The channels it joins. */
+  channels: z.array(channel).optional(),
+  /** What rixse's gateway lets its calls do: rules per host, method and path
+   *  (`apply`, `request` held for a person, `forbidden`), and per host the
+   *  secret its calls use, with an optional separate one for approved sends.
+   *  In force only as the person approved it (mirab manifest approve). */
+  gateway: z
+    .strictObject({
+      rules: z.array(gatewayRule).optional(),
+      secrets: z
+        .record(
+          domain,
+          z.strictObject({
+            agent: secretPath,
+            approved: secretPath.optional(),
+          }),
+        )
+        .optional(),
+    })
+    .optional(),
+})
+export type Agent = z.infer<typeof agentSchema>
+
+export function defineAgent(agent: Agent): Agent {
+  return agentSchema.parse(agent)
+}
+
+export interface Tool<Input extends z.ZodType> {
+  description: string
+  inputSchema: Input
+  execute(input: z.infer<Input>): unknown | Promise<unknown>
+}
+
+export function defineTool<Input extends z.ZodType>(
+  tool: Tool<Input>,
+): Tool<Input> {
+  if (!tool.description.trim()) throw new Error('a tool needs a description')
+  return tool
+}

package/src/agent/guest.ts

@@ -0,0 +1,138 @@
+// The agent loop as it runs in the VM: `bun loop.js <project>` on the guest
+// pty, speaking the channel `mirab dev` opens between the person and the
+// agent (src/channel). The model is the station's route on the guest's
+// loopback; the key is a placeholder the station replaces on the host, so
+// nothing in the VM ever holds it.
+import { lstatSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { createInterface } from 'node:readline'
+import type { ModelMessage } from 'ai'
+import {
+  decodeToAgent,
+  encodeFromAgent,
+  fitted,
+  type FromAgent,
+} from '../channel/wire'
+import { loadManifest } from './manifest'
+import { loadAgent, modelFor, runTurn, type ModelEndpoint } from './runtime'
+
+/** When anything under the agent's folder last changed. */
+export function agentStamp(project: string): string {
+  const dir = join(project, 'agent')
+  const parts: string[] = []
+  const walk = (path: string) => {
+    for (const name of readdirSync(path).sort()) {
+      const full = join(path, name)
+      // Links are part of the folder as they are; never followed.
+      const st = lstatSync(full)
+      parts.push(`${full}:${st.mtimeMs}:${st.size}`)
+      if (st.isDirectory()) walk(full)
+    }
+  }
+  try {
+    walk(dir)
+  } catch {
+    return ''
+  }
+  return parts.join('|')
+}
+
+/**
+ * The agent's side of the channel its station hosts (src/channel): a message
+ * in on `input`, one JSON line each; what the agent says out on `output`.
+ * Every message gets exactly one answer, its reply or why there is none. A
+ * message is untrusted input, and only ever the next thing said to the agent.
+ */
+export async function serve(
+  project: string,
+  input: NodeJS.ReadableStream,
+  output: NodeJS.WritableStream,
+  endpoint: ModelEndpoint,
+) {
+  // On the guest pty: no echo, no line editing, the bytes as the host sent them.
+  const tty = input as NodeJS.ReadableStream & {
+    isTTY?: boolean
+    setRawMode?: (raw: boolean) => void
+  }
+  if (tty.isTTY) tty.setRawMode?.(true)
+  const say = (m: FromAgent) => output.write(encodeFromAgent(m))
+  let loaded = await loadAgent(project)
+  let model = modelFor(loaded.agent, endpoint)
+  let stamp = agentStamp(project)
+  say({ text: `${loaded.agent.name} is here.`, note: true })
+  let history: ModelMessage[] = []
+  for await (const line of createInterface({ input, crlfDelay: Infinity })) {
+    const message = decodeToAgent(line)
+    if (!message) continue
+    // The person's edits reach the VM as they save (live sync): pick up
+    // agent.ts, instructions and tools before the next turn, keeping the
+    // conversation.
+    const now = agentStamp(project)
+    if (now !== stamp) {
+      // Only a load that worked counts: a half-saved agent is tried again
+      // next turn, and the one that loaded answers meanwhile.
+      try {
+        const next = await loadAgent(project)
+        model = modelFor(next.agent, endpoint)
+        loaded = next
+        stamp = now
+        say({ text: 'the agent changed; reloaded', note: true })
+      } catch (e) {
+        say({
+          text: fitted(
+            `the agent changed but didn't load: ${(e as Error).message}`,
+          ),
+          note: true,
+        })
+      }
+    }
+    try {
+      const turn = await runTurn({
+        loaded,
+        model,
+        history,
+        message: message.text,
+      })
+      history = turn.messages
+      say({
+        text: fitted(
+          `${turn.text}${turn.truncated ? ' [stopped: too many steps]' : ''}`,
+        ),
+        answers: message.id,
+      })
+    } catch (e) {
+      say({
+        text: fitted((e as Error).message),
+        note: true,
+        answers: message.id,
+      })
+    }
+  }
+}
+
+/** The line the guest prints the manifest on, for the host to read back. */
+export const MANIFEST_LINE = 'mirab-manifest '
+
+if (import.meta.main) {
+  const [first, second] = process.argv.slice(2)
+  // `--manifest <project>`: the agent's files run here, in the VM, never on
+  // the host, which only checks the JSON this prints.
+  if (first === '--manifest')
+    console.log(
+      MANIFEST_LINE +
+        JSON.stringify((await loadManifest(second ?? '/workspace')).manifest),
+    )
+  // `<project> <model URL> <placeholder key>`: the gateway's route, as the
+  // host (which runs the gateway) says it; the guest holds no key.
+  else {
+    const [, baseURL, key] = process.argv.slice(2)
+    if (!baseURL || !key)
+      throw new Error(
+        'usage: loop.js <project> <model base URL> <placeholder key>',
+      )
+    await serve(first ?? '/workspace', process.stdin, process.stdout, {
+      baseURL,
+      key,
+    })
+  }
+}