mirab 0.0.0-stage → 0.2.0

package/src/agent/init.ts

@@ -0,0 +1,150 @@
+// `mirab init`: make an agent folder. It never writes a .env and never
+// overwrites a file; model access comes from harar, not from the project.
+import { spawnSync } from 'node:child_process'
+import { existsSync, lstatSync, readdirSync, readFileSync } from 'node:fs'
+import { appendFile, mkdir, writeFile } from 'node:fs/promises'
+import { basename, join, resolve } from 'node:path'
+import { MODEL, agentNameProblem } from './define'
+
+export const DEFAULT_MODEL = 'anthropic/claude-sonnet-5-5'
+
+/** The folders an agent may fill, one capability each. */
+export const AGENT_FOLDERS = [
+  'tools',
+  'skills',
+  'subagents',
+  'schedules',
+  'channels',
+] as const
+
+export interface InitResult {
+  /** Files written, relative to the project. */
+  written: string[]
+  /** Something init skipped and the person should know about. */
+  notes: string[]
+}
+
+export interface InitOptions {
+  /** Where the project goes; made if missing. */
+  directory: string
+  /** The agent's harar name, `<org>.agent.<name>`. */
+  name: string
+  model?: string
+  /** Run `git init` (default true). */
+  git?: boolean
+}
+
+/** Whether `directory` can take a new agent: missing, empty, or only dotfiles like .git. */
+export function initProblem(directory: string): string | null {
+  if (!existsSync(directory)) return null
+  if (!lstatSync(directory).isDirectory()) return `${directory} isn't a folder`
+  // lstat, so a dangling symlink named agent counts as taken too.
+  if (lstatSync(join(directory, 'agent'), { throwIfNoEntry: false }))
+    return `${directory} already has an agent/ folder`
+  const taken = readdirSync(directory).filter(
+    (entry) => !entry.startsWith('.') && entry !== 'README.md',
+  )
+  return taken.length
+    ? `${directory} isn't empty (${taken.slice(0, 3).join(', ')}${taken.length > 3 ? ', …' : ''}); run it in an empty folder`
+    : null
+}
+
+/** The files an agent starts with, by path relative to the project. */
+export function agentFiles(name: string, model = DEFAULT_MODEL) {
+  const local = name.split('.').at(-1)!
+  return {
+    'package.json':
+      JSON.stringify(
+        {
+          name: local,
+          private: true,
+          type: 'module',
+          scripts: { dev: 'mirab dev' },
+          // mirab isn't on npm yet; its repository is public.
+          dependencies: { mirab: 'github:addiscorp/mirab', zod: '^4.1.12' },
+        },
+        null,
+        2,
+      ) + '\n',
+    // Never commit a key; mirab never reads one from here either.
+    '.gitignore': 'node_modules/\n.env\n.env.*\n',
+    'agent/agent.ts': `import { defineAgent } from 'mirab'
+
+export default defineAgent({
+  name: '${name}',
+  model: '${model}',
+})
+`,
+    'agent/instructions.md': `You are ${local}. Be concise, and use your tools when they help.
+`,
+    ...Object.fromEntries(
+      AGENT_FOLDERS.map((folder) => [`agent/${folder}/.gitkeep`, '']),
+    ),
+  }
+}
+
+/** Makes the project. Everything is checked before anything is written, so a
+ *  refusal leaves the folder as it was. */
+export async function initAgent(options: InitOptions): Promise<InitResult> {
+  const name = options.name.trim()
+  const problem = agentNameProblem(name)
+  if (problem) throw new Error(`The agent name ${problem}`)
+  const model = options.model ?? DEFAULT_MODEL
+  if (!MODEL.test(model))
+    throw new Error(
+      `The model is provider/model, like ${DEFAULT_MODEL}: ${JSON.stringify(model)}`,
+    )
+  const directory = resolve(options.directory)
+  const taken = initProblem(directory)
+  if (taken) throw new Error(taken)
+  const files: Record<string, string> = agentFiles(name, model)
+  // An existing .gitignore is kept and gets only the lines it lacks.
+  const gitignore = join(directory, '.gitignore')
+  let ignoreAdd: string | undefined
+  if (existsSync(gitignore)) {
+    const have = new Set(
+      readFileSync(gitignore, 'utf8')
+        .split('\n')
+        .map((l) => l.trim()),
+    )
+    const missing = files['.gitignore']
+      .split('\n')
+      .filter((l) => l && !have.has(l))
+    if (missing.length) ignoreAdd = missing.join('\n') + '\n'
+    delete files['.gitignore']
+  }
+  const clash = Object.keys(files).find((path) =>
+    lstatSync(join(directory, path), { throwIfNoEntry: false }),
+  )
+  if (clash)
+    throw new Error(
+      `${join(directory, clash)} already exists; nothing was written`,
+    )
+  await mkdir(directory, { recursive: true })
+  const result: InitResult = { written: [], notes: [] }
+  for (const [path, contents] of Object.entries(files)) {
+    const target = join(directory, path)
+    await mkdir(join(target, '..'), { recursive: true })
+    // `wx`: never overwrite, even a file that appeared since the check.
+    await writeFile(target, contents, { flag: 'wx' })
+    result.written.push(path)
+  }
+  if (ignoreAdd) {
+    await appendFile(gitignore, ignoreAdd)
+    result.written.push('.gitignore (added lines)')
+  }
+  if (options.git !== false) {
+    // Never a repository inside another one.
+    const inside = spawnSync('git', ['rev-parse', '--is-inside-work-tree'], {
+      cwd: directory,
+      encoding: 'utf8',
+    })
+    if (inside.status === 0 && inside.stdout.trim() === 'true')
+      result.notes.push('Already inside a git repository, so no git init.')
+    else if (spawnSync('git', ['init', '-q'], { cwd: directory }).status !== 0)
+      result.notes.push(
+        `git init didn't work in ${basename(directory)}; the agent is made, run it yourself.`,
+      )
+  }
+  return result
+}

package/src/agent/manifest.ts

@@ -0,0 +1,141 @@
+// The agent manifest (docs/architecture.md section 5a): plain data about an
+// agent, and the one thing mirab reads about it. agent/agent.ts is one way to
+// write it (a Nix flake will be the other); both end up checked by
+// manifestSchema, so there is one definition of what an agent is.
+import { existsSync, readdirSync, statSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { basename, join, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { z } from 'zod'
+import {
+  agentSchema,
+  commandToolSchema,
+  toolInput,
+  toolRecord,
+  toolNameProblem,
+  type Tool,
+} from './define'
+import { registerAgentModules } from './modules'
+
+/** A TypeScript tool, `agent/<file>`, run by the agent loop. */
+export const typescriptToolSchema = z.strictObject({
+  description: z.string().trim().min(1, 'a tool needs a description'),
+  /** Relative to agent/, e.g. `tools/add.ts`. */
+  file: z.string().regex(/^tools\/[a-zA-Z0-9_-]{1,64}\.ts$/),
+  input: toolInput,
+})
+
+export const manifestSchema = z.strictObject({
+  name: agentSchema.shape.name,
+  model: agentSchema.shape.model,
+  /** The system prompt. */
+  instructions: z.string(),
+  tools: toolRecord(z.union([typescriptToolSchema, commandToolSchema])),
+  packages: z.array(agentSchema.shape.packages.unwrap().element),
+  domains: z.array(agentSchema.shape.domains.unwrap().element),
+  channels: z.array(agentSchema.shape.channels.unwrap().element),
+  gateway: agentSchema.shape.gateway.unwrap().default({}),
+})
+export type Manifest = z.infer<typeof manifestSchema>
+
+/** The file as it is now: its URL carries its modification time, so a file
+ *  edited since the last load is imported again, not served from the cache. */
+function fresh(path: string) {
+  return `${pathToFileURL(path).href}?v=${statSync(path).mtimeMs}`
+}
+
+/** Checks manifest data from anywhere (agent.ts, `nix eval --json`). */
+export function parseManifest(data: unknown, from: string): Manifest {
+  const parsed = manifestSchema.safeParse(data)
+  if (!parsed.success)
+    throw new Error(
+      `${from}: ${parsed.error.issues.map((i) => `${i.path.join('.') || 'manifest'}: ${i.message}`).join('; ')}`,
+    )
+  return parsed.data
+}
+
+export interface LoadedManifest {
+  manifest: Manifest
+  /** The TypeScript tools as their files export them, by name. */
+  typescript: Record<string, Tool<z.ZodType>>
+}
+
+/** Reads `<project>/agent` (agent.ts, instructions.md, tools/*.ts) into a manifest. */
+export async function loadManifest(project: string): Promise<LoadedManifest> {
+  registerAgentModules()
+  const dir = join(resolve(project), 'agent')
+  const definition = join(dir, 'agent.ts')
+  if (!existsSync(definition))
+    throw new Error(`${definition} is missing; mirab init makes one`)
+  const parsed = agentSchema.safeParse(
+    (await import(fresh(definition))).default,
+  )
+  if (!parsed.success)
+    throw new Error(
+      `${definition}: ${parsed.error.issues.map((i) => i.message).join('; ')}`,
+    )
+  const agent = parsed.data
+  const instructionsPath = join(dir, 'instructions.md')
+  const instructions = existsSync(instructionsPath)
+    ? await readFile(instructionsPath, 'utf8')
+    : ''
+  // No prototype, so a tool named __proto__ is a tool like any other.
+  const tools: Manifest['tools'] = Object.create(null)
+  const typescript: LoadedManifest['typescript'] = Object.create(null)
+  for (const [name, tool] of Object.entries(agent.tools ?? {}))
+    tools[name] = tool
+  const toolsDir = join(dir, 'tools')
+  if (existsSync(toolsDir))
+    for (const file of readdirSync(toolsDir).sort()) {
+      if (
+        file.startsWith('.') ||
+        file.endsWith('.test.ts') ||
+        file.endsWith('.d.ts')
+      )
+        continue
+      if (!file.endsWith('.ts'))
+        throw new Error(
+          `tools/${file}: a tool is a TypeScript file (.ts); move anything else out of tools/`,
+        )
+      const name = basename(file, '.ts')
+      const problem = toolNameProblem(name)
+      if (problem) throw new Error(`tools/${file}: ${problem} (its file name)`)
+      if (Object.hasOwn(tools, name))
+        throw new Error(
+          `tools/${file}: agent.ts has a command tool named ${name} too; one name, one tool`,
+        )
+      const defined = (await import(fresh(join(toolsDir, file)))).default as
+        Tool<z.ZodType> | undefined
+      if (!defined?.description || !defined.inputSchema || !defined.execute)
+        throw new Error(
+          `tools/${file} must export default defineTool({ description, inputSchema, execute })`,
+        )
+      const input = z.toJSONSchema(defined.inputSchema, {
+        unrepresentable: 'any',
+      })
+      if (input.type !== 'object')
+        throw new Error(
+          `tools/${file}: inputSchema is a z.object({...}), so the model can call it (no transform or union at the top)`,
+        )
+      typescript[name] = defined
+      tools[name] = {
+        description: defined.description,
+        file: `tools/${file}`,
+        input,
+      }
+    }
+  const manifest = parseManifest(
+    {
+      name: agent.name,
+      model: agent.model,
+      instructions,
+      tools,
+      packages: agent.packages ?? [],
+      domains: agent.domains ?? [],
+      channels: agent.channels ?? [],
+      gateway: agent.gateway ?? {},
+    },
+    definition,
+  )
+  return { manifest, typescript }
+}

package/src/agent/modules.ts

@@ -0,0 +1,23 @@
+// The modules an agent's own files import ('mirab', 'mirab/tools', 'zod'),
+// given by mirab itself: in a VM there is no node_modules, and one zod means
+// a tool's schema is checked by the same zod that made it. They win over a
+// project's own node_modules (its pinned mirab or zod is not used), for the
+// whole process once registered.
+import * as zod from 'zod'
+import * as mirab from '../index'
+import * as tools from '../tools'
+
+let registered = false
+
+export function registerAgentModules() {
+  if (registered) return
+  registered = true
+  Bun.plugin({
+    name: 'mirab-agent-modules',
+    setup(build) {
+      build.module('mirab', () => ({ exports: mirab, loader: 'object' }))
+      build.module('mirab/tools', () => ({ exports: tools, loader: 'object' }))
+      build.module('zod', () => ({ exports: zod, loader: 'object' }))
+    },
+  })
+}

package/src/agent/runtime.ts

@@ -0,0 +1,239 @@
+// The loop that runs inside the agent's VM (docs/architecture.md section 3):
+// it loads the agent folder and runs turns, calling tools as the model asks.
+// Where the model is and what key to send are given by whoever starts it (in
+// the VM: the station's loopback route and a placeholder); the runtime never
+// reads an environment variable or a .env for them.
+import { spawn } from 'node:child_process'
+import { resolve } from 'node:path'
+import { createAnthropic } from '@ai-sdk/anthropic'
+import {
+  generateText,
+  stepCountIs,
+  dynamicTool,
+  type LanguageModel,
+  type ModelMessage,
+  type ToolSet,
+} from 'ai'
+import { z } from 'zod'
+import type { CommandTool } from './define'
+import { loadManifest, type Manifest } from './manifest'
+
+/** Turns stop after this many model calls, so a tool loop can't run forever. */
+export const MAX_STEPS = 20
+/** How long one tool call, and one whole turn, may take. */
+export const TOOL_TIMEOUT_MS = 5 * 60_000
+export const TURN_TIMEOUT_MS = 30 * 60_000
+/** The most a command tool may print, on stdout or stderr. */
+export const COMMAND_OUTPUT_MAX = 1024 * 1024
+
+export interface LoadedAgent {
+  agent: Manifest
+  tools: ToolSet
+}
+
+/** Loads `<project>/agent` and makes its manifest's tools callable. */
+export async function loadAgent(project: string): Promise<LoadedAgent> {
+  const root = resolve(project)
+  const { manifest, typescript } = await loadManifest(root)
+  // No prototype, so a tool named __proto__ is a tool like any other.
+  const tools: ToolSet = Object.create(null)
+  for (const [name, tool] of Object.entries(manifest.tools)) {
+    // The model's input is checked against the tool's own schema first.
+    tools[name] =
+      'file' in tool
+        ? dynamicTool({
+            description: tool.description,
+            inputSchema: typescript[name].inputSchema,
+            execute: async (input) => typescript[name].execute(input),
+          })
+        : commandTool(tool, root)
+  }
+  return { agent: manifest, tools }
+}
+
+/** A command tool for the model. The command gets the checked input, not
+ *  what the model sent: keys its schema doesn't list never reach it. */
+function commandTool(tool: CommandTool, root: string) {
+  const schema = z.fromJSONSchema(closedSchema(tool.input))
+  return dynamicTool({
+    description: tool.description,
+    inputSchema: schema,
+    execute: (input, { abortSignal }) =>
+      runCommand(tool, root, schema.parse(input), abortSignal),
+  })
+}
+
+/** A JSON Schema where every object that doesn't say otherwise takes only
+ *  the properties it lists, as a TypeScript tool's z.object does. */
+export function closedSchema<T>(schema: T, open = false): T {
+  if (Array.isArray(schema))
+    return schema.map((s) => closedSchema(s, open)) as T
+  if (!schema || typeof schema !== 'object') return schema
+  const node: Record<string, unknown> = Object.fromEntries(
+    Object.entries(schema).map(([k, v]) => [
+      k,
+      // Values, not schemas, are left as written; each allOf branch is one
+      // part of an object whose keys the other branches list.
+      VALUE_KEYWORDS.has(k) ? v : closedSchema(v, k === 'allOf'),
+    ]),
+  )
+  if (
+    !open &&
+    node.type === 'object' &&
+    !('additionalProperties' in node) &&
+    !('patternProperties' in node)
+  )
+    node.additionalProperties = false
+  return node as T
+}
+const VALUE_KEYWORDS = new Set(['const', 'enum', 'default', 'examples'])
+
+/** Runs a command tool: input as JSON on stdin, its JSON answer from stdout.
+ *  No shell, the project as its working directory, and only PATH and HOME
+ *  from the loop's environment, so a tool never sees what the loop was given.
+ *  It runs in its own process group: a timeout, the turn ending or too much
+ *  output stops everything it started, and so does its own exit. */
+export function runCommand(
+  tool: CommandTool,
+  cwd: string,
+  input: unknown,
+  signal?: AbortSignal,
+): Promise<unknown> {
+  return new Promise((done, fail) => {
+    if (signal?.aborted)
+      return fail(new Error(`${tool.command} was stopped: the turn ended`))
+    const child = spawn(tool.command, tool.args ?? [], {
+      cwd,
+      env: {
+        PATH: process.env.PATH ?? '/usr/bin:/bin',
+        HOME: process.env.HOME ?? cwd,
+      },
+      stdio: ['pipe', 'pipe', 'pipe'],
+      detached: true,
+    })
+    let stopped: string | undefined
+    const stopAll = (why?: string) => {
+      if (why && !stopped) stopped = why
+      try {
+        process.kill(-child.pid!, 'SIGKILL')
+      } catch {}
+    }
+    const ms = tool.timeoutMs ?? TOOL_TIMEOUT_MS
+    const timer = setTimeout(() => stopAll(`ran longer than ${ms} ms`), ms)
+    const onAbort = () => stopAll('the turn ended')
+    signal?.addEventListener('abort', onAbort, { once: true })
+    const finish = () => {
+      clearTimeout(timer)
+      signal?.removeEventListener('abort', onAbort)
+    }
+    const out: Buffer[] = []
+    const err: Buffer[] = []
+    let size = 0
+    const collect = (into: Buffer[]) => (chunk: Buffer) => {
+      size += chunk.length
+      if (size > COMMAND_OUTPUT_MAX)
+        stopAll(`printed more than ${COMMAND_OUTPUT_MAX} bytes`)
+      else into.push(chunk)
+    }
+    child.stdout!.on('data', collect(out))
+    child.stderr!.on('data', collect(err))
+    // A command that exits without reading its input is not an error here.
+    child.stdin!.on('error', () => {})
+    child.stdin!.end(JSON.stringify(input))
+    child.on('error', (e) => {
+      finish()
+      fail(new Error(`${tool.command} didn't run: ${e.message}`))
+    })
+    child.on('exit', () => {
+      // It answered in time: from here only the 1 s below governs the wait.
+      finish()
+      stopAll()
+      // Something that left the group can still hold the pipes open; the
+      // call ends anyway.
+      setTimeout(() => {
+        child.stdout!.destroy()
+        child.stderr!.destroy()
+      }, 1000).unref()
+    })
+    child.on('close', (code, killed) => {
+      finish()
+      const stderr = Buffer.concat(err).toString('utf8').trim().slice(-2000)
+      if (stopped)
+        return fail(new Error(`${tool.command} was stopped: ${stopped}`))
+      if (code !== 0)
+        return fail(
+          new Error(
+            `${tool.command} exited ${code ?? killed}${stderr ? `: ${stderr}` : ''}`,
+          ),
+        )
+      const stdout = Buffer.concat(out).toString('utf8')
+      try {
+        done(JSON.parse(stdout))
+      } catch {
+        fail(new Error(`${tool.command} didn't answer with JSON on stdout`))
+      }
+    })
+  })
+}
+
+export interface ModelEndpoint {
+  /** Base URL of the model API, e.g. the station's `http://127.0.0.1:8790/anthropic`. */
+  baseURL: string
+  /** What to send as the key: in a VM, a placeholder the station replaces. */
+  key: string
+}
+
+/** The model an agent names (`provider/model`), at the given endpoint. */
+export function modelFor(
+  agent: Pick<Manifest, 'model'>,
+  endpoint: ModelEndpoint,
+): LanguageModel {
+  // Always strings: the provider would fall back to ANTHROPIC_* variables otherwise.
+  if (!endpoint.key || !endpoint.baseURL)
+    throw new Error('the model endpoint needs a base URL and a key')
+  const [provider, id] = agent.model.split('/')
+  if (provider !== 'anthropic')
+    throw new Error(
+      `mirab talks to anthropic models for now; ${agent.model} isn't one`,
+    )
+  return createAnthropic({ baseURL: endpoint.baseURL, apiKey: endpoint.key })(
+    id,
+  )
+}
+
+export interface TurnResult {
+  text: string
+  /** The turn hit MAX_STEPS model calls before the model answered. */
+  truncated: boolean
+  /** The conversation after this turn, for the next one. */
+  messages: ModelMessage[]
+}
+
+/** One turn: the person's message in, the agent's answer out, with any tool calls between. */
+export async function runTurn(options: {
+  loaded: LoadedAgent
+  model: LanguageModel
+  history: ModelMessage[]
+  message: string
+  signal?: AbortSignal
+}): Promise<TurnResult> {
+  const messages: ModelMessage[] = [
+    ...options.history,
+    { role: 'user', content: options.message },
+  ]
+  const result = await generateText({
+    model: options.model,
+    instructions: options.loaded.agent.instructions,
+    messages,
+    tools: options.loaded.tools,
+    stopWhen: stepCountIs(MAX_STEPS),
+    timeout: { totalMs: TURN_TIMEOUT_MS, toolMs: TOOL_TIMEOUT_MS },
+    abortSignal: options.signal,
+  })
+  return {
+    text: result.text,
+    truncated: result.finishReason === 'tool-calls',
+    // Every step's messages (tool calls and results too), not just the last.
+    messages: [...messages, ...result.responseMessages],
+  }
+}