mirab 0.0.0 → 0.2.0

package/src/agent-profiles.ts

@@ -0,0 +1,327 @@
+import {
+  chmod,
+  lstat,
+  mkdir,
+  open,
+  readdir,
+  readFile,
+  rename,
+  unlink,
+} from 'node:fs/promises'
+import { constants } from 'node:fs'
+import { homedir } from 'node:os'
+import { isAbsolute, join, resolve } from 'node:path'
+import { randomBytes } from 'node:crypto'
+import { Command } from 'commander'
+import { z } from 'zod'
+import { nudgeSpec } from './spawn-nudge'
+
+// Runtime settings only. Scoped tokens stay in the existing identity store.
+const nameSchema = z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,23}$/)
+const text = z
+  .string()
+  .min(1)
+  .refine((s) => !s.includes('\0'))
+/** `<event>.<action>[:<label>]` against the forge event stream (gild-site#55). */
+export const triggerPattern = /^([a-z][a-z_]*)\.([a-z][a-z_]*)(?::([^\n]+))?$/
+const triggerSchema = z
+  .string()
+  .regex(
+    triggerPattern,
+    'Use <event>.<action>[:<label>], e.g. issues.labeled:triage',
+  )
+export type AgentTrigger = { event: string; action: string; label?: string }
+/** Split a validated trigger spec into its parts; null when the grammar fails. */
+export function parseTrigger(spec: string): AgentTrigger | null {
+  const match = spec.match(triggerPattern)
+  if (!match) return null
+  return {
+    event: match[1],
+    action: match[2],
+    ...(match[3] !== undefined ? { label: match[3] } : {}),
+  }
+}
+export const profileSchema = z.strictObject({
+  name: nameSchema,
+  runtime: text,
+  model: text.optional(),
+  effort: text.optional(),
+  directory: text.refine(isAbsolute),
+  args: z.array(z.string().refine((s) => !s.includes('\0'))).default([]),
+  env: z.array(z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/)).optional(),
+  channels: z
+    .array(z.string().regex(/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/))
+    .optional(),
+  nudges: z.array(nudgeSpec).optional(),
+  on: z.array(triggerSchema).optional(),
+})
+export type AgentProfile = z.infer<typeof profileSchema>
+export const profilesDirectory = () => join(homedir(), '.mirab', 'agents')
+function profilePath(name: string) {
+  if (!nameSchema.safeParse(name).success)
+    throw Error(
+      'Agent profile name must be 1–24 letters, digits, underscores or hyphens',
+    )
+  return join(profilesDirectory(), name + '.json')
+}
+async function privateDirectory() {
+  for (const path of [join(homedir(), '.mirab'), profilesDirectory()]) {
+    await mkdir(path, { mode: 0o700 }).catch((e: NodeJS.ErrnoException) => {
+      if (e.code !== 'EEXIST') throw e
+    })
+    const info = await lstat(path)
+    if (
+      !info.isDirectory() ||
+      info.isSymbolicLink() ||
+      info.uid !== process.getuid?.()
+    )
+      throw Error('Unsafe local agent profile directory')
+    await chmod(path, 0o700)
+  }
+}
+function nudgeError(issues: z.core.$ZodIssue[]) {
+  const issue = issues.find((i) => i.path[0] === 'nudges')
+  return issue && `Invalid nudge rule: ${issue.message}`
+}
+export function parseProfile(value: unknown): AgentProfile {
+  const result = profileSchema.safeParse(value)
+  if (!result.success)
+    throw Error(
+      nudgeError(result.error.issues) ??
+        'Invalid agent profile: only name, runtime, model, effort, directory, args, env, channels, on and nudges are allowed; credentials belong in the identity store' +
+          (result.error.issues[0]
+            ? ` (${result.error.issues[0].path.join('.') || 'profile'}: ${result.error.issues[0].message})`
+            : ''),
+    )
+  return result.data
+}
+export async function loadProfile(name: string): Promise<AgentProfile> {
+  const path = profilePath(name)
+  await privateDirectory()
+  const file = await open(
+    path,
+    constants.O_RDONLY | constants.O_NOFOLLOW,
+  ).catch((e: NodeJS.ErrnoException) => {
+    if (e.code === 'ENOENT')
+      throw Error(`No local agent profile ${name}; use mirab agent add ${name}`)
+    throw e
+  })
+  try {
+    const info = await file.stat()
+    if (
+      !info.isFile() ||
+      info.uid !== process.getuid?.() ||
+      info.size > 64 * 1024
+    )
+      throw Error('Unsafe local agent profile file')
+    await file.chmod(0o600)
+    let value: unknown
+    try {
+      value = JSON.parse(await file.readFile('utf8'))
+    } catch {
+      throw Error('Invalid agent profile JSON')
+    }
+    const profile = parseProfile(value)
+    if (profile.name !== name)
+      throw Error('Agent profile name differs from its filename')
+    return profile
+  } finally {
+    await file.close()
+  }
+}
+export async function saveProfile(value: unknown, create = false) {
+  const profile = parseProfile(value)
+  const path = profilePath(profile.name)
+  await privateDirectory()
+  const body = JSON.stringify(profile, null, 2) + '\n'
+  if (Buffer.byteLength(body) > 64 * 1024)
+    throw Error('Agent profile exceeds 64 KiB')
+  if (create) {
+    const file = await open(path, 'wx', 0o600).catch(
+      (e: NodeJS.ErrnoException) => {
+        if (e.code === 'EEXIST')
+          throw Error(
+            `Agent profile ${profile.name} already exists; use mirab agent edit`,
+          )
+        throw e
+      },
+    )
+    try {
+      await file.writeFile(body)
+    } finally {
+      await file.close()
+    }
+  } else {
+    await loadProfile(profile.name)
+    const temp = path + '.' + randomBytes(6).toString('hex') + '.tmp'
+    try {
+      const file = await open(temp, 'wx', 0o600)
+      try {
+        await file.writeFile(body)
+      } finally {
+        await file.close()
+      }
+      await rename(temp, path)
+    } finally {
+      await unlink(temp).catch(() => {})
+    }
+  }
+}
+export async function resolveProfile(name: string, extra: string[]) {
+  const profile = await loadProfile(name)
+  const { stat } = await import('node:fs/promises')
+  const directory = await stat(profile.directory).catch(() => null)
+  if (!directory?.isDirectory())
+    throw Error(
+      `Agent profile ${name} directory does not exist or is not a directory: ${profile.directory}`,
+    )
+  const { profileArguments } = await import('./spawn-adapters')
+  return {
+    profile,
+    args: [
+      ...profileArguments(profile.runtime, profile),
+      ...profile.args,
+      ...extra,
+    ],
+  }
+}
+const collect = (value: string, previous: string[] = []) => [...previous, value]
+export function profileCommands(agent: Command) {
+  for (const verb of ['add', 'edit'] as const) {
+    agent
+      .command(`${verb} <name>`)
+      .description(
+        `${verb} a local runtime profile (credentials are stored separately)`,
+      )
+      .option('--runtime <command>', 'native runtime or executable')
+      .option('--model <model>', 'native model ID; empty clears it')
+      .option('--effort <effort>', 'native reasoning effort; empty clears it')
+      .option(
+        '--dir <directory>',
+        'working directory, resolved to an absolute path',
+      )
+      .option(
+        '--arg <argument>',
+        'extra native argument; repeat to replace args',
+        collect,
+      )
+      .option(
+        '--env <name>',
+        'inherit only these environment variable names; repeat',
+        collect,
+      )
+      .option(
+        '--channel <owner/repo>',
+        'reserved channel mention subscription; repeat',
+        collect,
+      )
+      .option(
+        '--nudge <rule>',
+        'watchdog rule: idle:<duration>[:<limit>][:<message>], waiting:<duration>, ci:<owner/repo>, mention-unanswered:<duration>; repeat',
+        collect,
+      )
+      .option(
+        '--on <event.action[:label]>',
+        'wake this agent on a forge event, e.g. issues.labeled:triage; repeat',
+        collect,
+      )
+      .option('--clear-args', 'clear native arguments')
+      .option('--clear-env', 'restore normal environment inheritance')
+      .option('--clear-channels', 'clear reserved channels')
+      .option('--clear-nudges', 'clear watchdog rules')
+      .option('--clear-on', 'clear event triggers')
+      .option('--file <json>', 'read a complete, credential-free profile JSON')
+      .action(async (name: string, opts) => {
+        profilePath(name)
+        if (opts.file) {
+          if (Object.keys(opts).some((key) => key !== 'file'))
+            throw Error('--file cannot be combined with profile field options')
+          let value: unknown
+          try {
+            value = JSON.parse(await readFile(opts.file, 'utf8'))
+          } catch {
+            throw Error('Cannot read profile JSON')
+          }
+          const profile = parseProfile(value)
+          if (profile.name !== name)
+            throw Error('Agent profile name differs from the command name')
+          await saveProfile(profile, verb === 'add')
+          return
+        }
+        const previous =
+          verb === 'edit' ? await loadProfile(name) : { name, args: [] }
+        await saveProfile(
+          {
+            ...previous,
+            ...(opts.runtime !== undefined ? { runtime: opts.runtime } : {}),
+            ...(opts.dir !== undefined ? { directory: resolve(opts.dir) } : {}),
+            ...(opts.model !== undefined
+              ? { model: opts.model || undefined }
+              : {}),
+            ...(opts.effort !== undefined
+              ? { effort: opts.effort || undefined }
+              : {}),
+            ...(opts.arg
+              ? { args: opts.arg }
+              : opts.clearArgs
+                ? { args: [] }
+                : {}),
+            ...(opts.env
+              ? { env: opts.env }
+              : opts.clearEnv
+                ? { env: undefined }
+                : {}),
+            ...(opts.channel
+              ? { channels: opts.channel }
+              : opts.clearChannels
+                ? { channels: undefined }
+                : {}),
+            ...(opts.nudge
+              ? { nudges: opts.nudge }
+              : opts.clearNudges
+                ? { nudges: undefined }
+                : {}),
+            ...(opts.on
+              ? { on: opts.on }
+              : opts.clearOn
+                ? { on: undefined }
+                : {}),
+          },
+          verb === 'add',
+        )
+      })
+  }
+  agent
+    .command('rm <name>')
+    .description('remove a local runtime profile; keep approved credentials')
+    .action(async (name: string) => {
+      await loadProfile(name)
+      await unlink(profilePath(name))
+    })
+  agent
+    .command('ls')
+    .description('list local runtime profiles')
+    .option('--json', 'print profiles as JSON')
+    .action(async (opts) => {
+      await privateDirectory()
+      const profiles: AgentProfile[] = []
+      for (const entry of (await readdir(profilesDirectory())).sort()) {
+        if (entry.endsWith('.json'))
+          profiles.push(await loadProfile(entry.slice(0, -5)))
+      }
+      if (opts.json) console.log(JSON.stringify(profiles))
+      else {
+        console.log('NAME\tRUNTIME\tMODEL\tEFFORT\tDIRECTORY')
+        for (const p of profiles)
+          console.log(
+            [
+              p.name,
+              p.runtime,
+              p.model ?? '',
+              p.effort ?? '',
+              p.directory,
+            ].join('\t'),
+          )
+      }
+    })
+}

package/src/api/bootstrap-contract.ts

@@ -0,0 +1,95 @@
+// Generated by gild-site/scripts/generate-api-client.mjs. Edit the site source.
+// Identity establishment precedes a gf_ token. These legacy browser/terminal
+// routes keep their key-proof protocol and are deliberately outside API v1.
+import { z } from 'zod'
+import { ApiRequestError } from './client.ts'
+const proof = z.object({
+  challenge: z.string(),
+  publicKey: z.string(),
+  signature: z.string(),
+})
+export const bootstrapRoutes = {
+  challenge: {
+    path: '/api/auth/challenge',
+    input: z.object({}),
+    output: z.object({ challenge: z.string() }),
+  },
+  answer: {
+    path: '/api/auth/answer',
+    input: proof,
+    output: z.object({ ok: z.boolean() }),
+  },
+  claim: {
+    path: '/api/claim/answer',
+    input: proof,
+    output: z.object({ ok: z.boolean(), name: z.string() }),
+  },
+  token: {
+    path: '/api/tokens',
+    input: proof,
+    output: z.object({ token: z.string(), name: z.string().nullable() }),
+  },
+  join: {
+    path: '/api/agents/requests',
+    input: z.object({
+      sponsor: z.string(),
+      label: z.string(),
+      publicKey: z.string(),
+      repo: z.string().optional(),
+      grants: z.array(z.string()),
+      note: z.string().optional(),
+    }),
+    output: z.object({
+      id: z.string(),
+      status: z.string(),
+      agent: z.string(),
+      approveUrl: z.string(),
+      collect: z.string(),
+    }),
+  },
+  collect: {
+    path: '/api/agents/requests/{id}/token',
+    input: z.object({ signature: z.string() }),
+    output: z.object({
+      status: z.string(),
+      name: z.string().optional(),
+      token: z.string().optional(),
+      repo: z.string().nullable().optional(),
+      grants: z.array(z.string()).optional(),
+    }),
+  },
+} as const
+export class ProofClient {
+  constructor(
+    readonly origin: string,
+    readonly fetcher: typeof fetch = fetch,
+  ) {}
+  async request<I extends keyof typeof bootstrapRoutes>(
+    id: I,
+    input: z.input<(typeof bootstrapRoutes)[I]['input']>,
+    params: Record<string, string> = {},
+  ) {
+    const route = bootstrapRoutes[id],
+      path = route.path.replace(/\{(\w+)\}/g, (_, name) =>
+        encodeURIComponent(params[name]),
+      )
+    const response = await this.fetcher(this.origin.replace(/\/$/, '') + path, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(route.input.parse(input)),
+      redirect: 'error',
+      signal: AbortSignal.timeout(30000),
+    })
+    const data = await response
+      .json()
+      .catch(() => ({ error: `HTTP ${response.status}` }))
+    if (!response.ok)
+      throw new ApiRequestError(
+        response.status,
+        data.message ?? data.error ?? `HTTP ${response.status}`,
+      )
+    return route.output.parse(data) as z.output<
+      (typeof bootstrapRoutes)[I]['output']
+    >
+  }
+}

package/src/api/channel-contract.ts

@@ -0,0 +1,19 @@
+// Generated by gild-site/scripts/generate-api-client.mjs. Edit the site source.
+import { z } from 'zod'
+import { channelState } from '../channel/state.ts'
+export const channelCursor = z.string().regex(/^(0|[1-9][0-9]{0,14})$/)
+export const channelAuthor = z.object({ name: z.string(), kind: z.enum(['human', 'agent']) })
+export const channelMessage = z.object({
+  cursor: channelCursor, id: z.string(), created_at: z.string(),
+  reply_to: channelCursor.nullable(), author: channelAuthor, kind: z.enum(['message', 'system']), body: z.string(),
+  link: z.object({ href: z.string(), label: z.string() }).nullable(),
+})
+export const channelPage = z.object({ messages: z.array(channelMessage), cursor: channelCursor, before: channelCursor.nullable(), after: channelCursor.nullable() })
+export const channelQuery = z.object({ before: channelCursor.optional(), after: channelCursor.optional(), limit: z.coerce.number().int().min(1).max(200).default(50) }).refine(q => !(q.before && q.after), 'Use before or after, not both')
+export const channelInput = z.object({ body: z.string().trim().min(1).max(4000), reply_to: channelCursor.optional() })
+export const channelParticipant = channelAuthor.extend({ prefix: z.enum(['@', '%', '+', '']), sponsor: z.string().nullable(), scopes: z.array(z.string()), online: z.boolean(), state: channelState.nullable().optional() })
+export const channelParticipants = z.object({ participants: z.array(channelParticipant), can_post: z.boolean(), viewer: z.string().nullable() })
+export type ChannelMessage = z.output<typeof channelMessage>
+export type ChannelParticipant = z.output<typeof channelParticipant>
+export type ChannelPage = z.output<typeof channelPage>
+export type ChannelQuery = z.output<typeof channelQuery>

package/src/api/client.ts

@@ -0,0 +1,100 @@
+// Generated by gild-site/scripts/generate-api-client.mjs. Edit the site source.
+import {
+  routes,
+  type Operation,
+  type Input,
+  type Output,
+  type Query,
+} from './contract.ts'
+export class ApiRequestError extends Error {
+  readonly status: number
+  constructor(status: number, message: string) {
+    super(message)
+    this.status = status
+  }
+}
+export class GildClient {
+  constructor(
+    readonly baseURL: string,
+    readonly token: string,
+    readonly fetcher: (
+      input: RequestInfo | URL,
+      init?: RequestInit,
+    ) => Promise<Response> = fetch,
+  ) {}
+  async request<I extends Operation>(
+    operation: I,
+    params: Record<string, string | number> = {},
+    body?: Input<I>,
+    query?: Query<I>,
+    options?: { idempotencyKey?: string; signal?: AbortSignal },
+  ): Promise<Output<I>> {
+    const route = routes.find((r) => r.id === operation)!
+    const path = route.path.replace(/\{(\w+)\}/g, (_, name: string) => {
+      if (params[name] === undefined)
+        throw new Error(`Missing path parameter: ${name}`)
+      const value = String(params[name])
+      return name === 'path' || name === 'ref'
+        ? value.split('/').map(encodeURIComponent).join('/')
+        : encodeURIComponent(value)
+    })
+    const url = new URL(this.baseURL.replace(/\/$/, '') + path)
+    if (query)
+      for (const [name, value] of Object.entries(query))
+        if (value !== undefined) url.searchParams.set(name, String(value))
+    const res = await this.fetcher(url, {
+      method: route.method,
+      headers: {
+        authorization: `Bearer ${this.token}`,
+        'content-type': 'application/json',
+        ...(options?.idempotencyKey
+          ? { 'idempotency-key': options.idempotencyKey }
+          : {}),
+      },
+      body: ['GET', 'DELETE'].includes(route.method)
+        ? undefined
+        : JSON.stringify(route.input.parse(body ?? {})),
+      signal: options?.signal ?? AbortSignal.timeout(30000),
+      redirect: 'error',
+    })
+    const data = res.status === 204 ? null : await res
+      .json()
+      .catch(() => ({ message: `HTTP ${res.status}` }))
+    if (!res.ok)
+      throw new ApiRequestError(
+        res.status,
+        data.message ?? `HTTP ${res.status}`,
+      )
+    return route.output.parse(data) as Output<I>
+  }
+}
+// Protocol adapters still resolve through canonical definitions.
+export async function requestPath(
+  client: GildClient,
+  method: string,
+  path: string,
+  body?: unknown,
+) {
+  for (const route of routes) {
+    if (route.method !== method) continue
+    const names = [...route.path.matchAll(/\{(\w+)\}/g)].map((m) => m[1]),
+      pattern = new RegExp(
+        '^' +
+          route.path
+            .split(/\{\w+\}/)
+            .map((s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+            .join('([^/]+)') +
+          '$',
+      ),
+      matched = pattern.exec(path)
+    if (matched)
+      return client.request(
+        route.id,
+        Object.fromEntries(
+          names.map((n, i) => [n, decodeURIComponent(matched[i + 1])]),
+        ),
+        body as Input<Operation>,
+      )
+  }
+  throw new Error(`Unknown API operation: ${method} ${path}`)
+}