ghost-dragon 4.2.1

package/src/agent/tools.ts

@@ -0,0 +1,255 @@
+/**
+ * Local coding tools — the agent's hands. These run on THIS machine (that's the
+ * whole point of a CLI coding agent vs the hosted Worker assistant): read/write/
+ * edit files, list/glob/grep the tree, run shell commands.
+ *
+ * Mutating tools (write_file, edit_file, bash) pass through an approval gate so
+ * nothing touches the disk or runs a command without a yes — unless the session
+ * is in auto-approve. Read-only tools (read_file, list_dir, glob, grep) run free.
+ *
+ * grep/glob shell out to ripgrep (present on this box) for speed + .gitignore
+ * awareness; output is capped so a huge result can't blow the context window.
+ *
+ * Copyright 2026 Ghost Protocol (Pvt) Ltd. All Rights Reserved.
+ */
+
+import { spawn } from 'node:child_process'
+import { readFileSync, writeFileSync, mkdirSync, statSync, readdirSync, existsSync, realpathSync } from 'node:fs'
+import { resolve, dirname, isAbsolute, join, relative } from 'node:path'
+import type { ToolSpec } from '../brain/types.js'
+
+const MAX_OUTPUT = 30_000 // chars fed back to the model per tool result
+const MAX_READ_BYTES = 200_000
+
+export interface ToolContext {
+  cwd: string
+  /** Returns true to proceed. `dangerous` actions (bash, anything outside the
+   *  working dir) are NEVER covered by --auto — they always prompt. */
+  approve: (summary: string, opts?: { detail?: string; dangerous?: boolean }) => Promise<boolean>
+  /** When true, run bash inside a bwrap sandbox (cwd writable, rest read-only,
+   *  credential dirs masked). Filesystem confinement only — network is shared. */
+  sandbox?: boolean
+}
+
+export const BWRAP = ['/usr/bin/bwrap', '/usr/local/bin/bwrap'].find((p) => existsSync(p)) ?? null
+
+/** Build the argv for a shell command, optionally wrapped in a bwrap jail. */
+function bashArgv(command: string, cwd: string, sandbox: boolean): { cmd: string; args: string[] } {
+  if (sandbox && BWRAP) {
+    const home = process.env.HOME || ''
+    const mask = ['.ssh', '.aws', '.gnupg', '.dragon', '.config/gh', '.npmrc'].flatMap((d) => ['--tmpfs', `${home}/${d}`])
+    return {
+      cmd: BWRAP,
+      args: ['--ro-bind', '/', '/', '--bind', cwd, cwd, '--tmpfs', '/tmp', '--dev', '/dev', '--proc', '/proc', '--unshare-pid', ...mask, '--chdir', cwd, '--', 'bash', '-c', command],
+    }
+  }
+  return { cmd: 'bash', args: ['-c', command] }
+}
+
+// Paths the agent must never touch — credentials/keys — even with approval.
+const PROTECTED = [/(^|\/)\.ssh(\/|$)/, /(^|\/)\.aws(\/|$)/, /(^|\/)\.gnupg(\/|$)/, /(^|\/)\.dragon(\/|$)/, /(^|\/)\.git\/config$/, /\.env(\.[\w-]+)?$/, /id_(rsa|ed25519|ecdsa)/, /\.(pem|key|p12|keystore)$/, /(^|\/)\.(npmrc|netrc|pgpass)$/];
+
+// Obviously-catastrophic shell — flagged for a louder confirm (never auto-run).
+const CATASTROPHIC = /\brm\s+-[rf]{1,2}\b[^|]*[\s/~*]|\bmkfs\b|\bdd\s+if=|>\s*\/dev\/(sd|nvme|disk)|:\(\)\s*\{\s*:\s*\|\s*:|(curl|wget)\b[^|]*\|\s*(sudo\s+)?(ba)?sh\b|\bchmod\s+-R?\s*777\s+\//i;
+
+/** Resolve a path and classify it: inside cwd, outside, or protected (symlink-aware). */
+export function guardPath(cwd: string, p: string): { abs: string; outside: boolean; protectedPath: boolean } {
+  const absPath = isAbsolute(p) ? resolve(p) : resolve(cwd, p)
+  const protectedPath = PROTECTED.some((re) => re.test(absPath))
+  let real = absPath
+  try { real = realpathSync(absPath) } catch { /* may not exist yet (new file) */ }
+  let root = resolve(cwd)
+  try { root = realpathSync(cwd) } catch { /* keep resolved */ }
+  const within = (x: string) => x === root || x.startsWith(root + '/')
+  const outside = !(within(real) || within(absPath))
+  return { abs: absPath, outside, protectedPath }
+}
+
+export interface LocalTool {
+  spec: ToolSpec
+  mutating: boolean
+  summary(args: Record<string, unknown>): string
+  run(args: Record<string, unknown>, ctx: ToolContext): Promise<string>
+}
+
+function clamp(s: string): string {
+  return s.length > MAX_OUTPUT ? s.slice(0, MAX_OUTPUT) + `\n… [truncated ${s.length - MAX_OUTPUT} chars]` : s
+}
+
+function capture(cmd: string, args: string[], opts: { cwd: string; input?: string; timeout?: number }): Promise<{ stdout: string; stderr: string; code: number }> {
+  return new Promise((res) => {
+    const child = spawn(cmd, args, { cwd: opts.cwd })
+    let stdout = ''
+    let stderr = ''
+    const timer = setTimeout(() => { try { child.kill('SIGKILL') } catch {} }, opts.timeout ?? 120_000)
+    child.stdout.on('data', (d) => { if (stdout.length < MAX_OUTPUT * 2) stdout += d })
+    child.stderr.on('data', (d) => { if (stderr.length < MAX_OUTPUT) stderr += d })
+    child.on('error', (e) => { clearTimeout(timer); res({ stdout, stderr: stderr + String(e), code: 127 }) })
+    child.on('close', (code) => { clearTimeout(timer); res({ stdout, stderr, code: code ?? 0 }) })
+    if (opts.input !== undefined) { child.stdin.write(opts.input); child.stdin.end() }
+  })
+}
+
+const read_file: LocalTool = {
+  mutating: false,
+  summary: (a) => `read ${a.path}`,
+  spec: {
+    name: 'read_file',
+    description: 'Read a UTF-8 text file. Returns the content with 1-based line numbers. Use offset/limit for large files.',
+    parameters: { type: 'object', properties: { path: { type: 'string' }, offset: { type: 'number', description: '1-based start line' }, limit: { type: 'number', description: 'max lines' } }, required: ['path'] },
+  },
+  async run(a, ctx) {
+    const g = guardPath(ctx.cwd, String(a.path))
+    if (g.protectedPath) return `error: ${a.path} is a protected path (credentials/keys) — refused`
+    if (g.outside && !(await ctx.approve(`read OUTSIDE the working dir: ${a.path}`, { dangerous: true }))) return 'error: read declined (outside working directory)'
+    const p = g.abs
+    if (!existsSync(p)) return `error: no such file: ${a.path}`
+    const st = statSync(p)
+    if (st.isDirectory()) return `error: ${a.path} is a directory (use list_dir)`
+    if (st.size > MAX_READ_BYTES) return `error: file too large (${st.size} bytes). Use grep or offset/limit.`
+    const lines = readFileSync(p, 'utf-8').split('\n')
+    const start = a.offset ? Math.max(1, Number(a.offset)) : 1
+    const end = a.limit ? start + Number(a.limit) - 1 : lines.length
+    const slice = lines.slice(start - 1, end).map((l, i) => `${String(start + i).padStart(5)}\t${l}`).join('\n')
+    return clamp(slice || '(empty file)')
+  },
+}
+
+const write_file: LocalTool = {
+  mutating: true,
+  summary: (a) => `write ${a.path} (${String(a.content ?? '').length} bytes)`,
+  spec: {
+    name: 'write_file',
+    description: 'Create or overwrite a file with the given content. Creates parent directories. Prefer edit_file for changes to existing files.',
+    parameters: { type: 'object', properties: { path: { type: 'string' }, content: { type: 'string' } }, required: ['path', 'content'] },
+  },
+  async run(a, ctx) {
+    const g = guardPath(ctx.cwd, String(a.path))
+    if (g.protectedPath) return `error: ${a.path} is a protected path — refused`
+    const p = g.abs
+    const content = String(a.content ?? '')
+    const existed = existsSync(p)
+    if (!(await ctx.approve(`${existed ? 'overwrite' : 'create'} ${relative(ctx.cwd, p) || a.path}${g.outside ? ' (OUTSIDE working dir)' : ''}`, { detail: content.slice(0, 800), dangerous: g.outside }))) return 'error: write declined by user'
+    mkdirSync(dirname(p), { recursive: true })
+    writeFileSync(p, content)
+    return `wrote ${content.length} bytes to ${a.path}`
+  },
+}
+
+const edit_file: LocalTool = {
+  mutating: true,
+  summary: (a) => `edit ${a.path}`,
+  spec: {
+    name: 'edit_file',
+    description: 'Replace an exact string in a file. old_string must match verbatim and be unique unless replace_all is true.',
+    parameters: { type: 'object', properties: { path: { type: 'string' }, old_string: { type: 'string' }, new_string: { type: 'string' }, replace_all: { type: 'boolean' } }, required: ['path', 'old_string', 'new_string'] },
+  },
+  async run(a, ctx) {
+    const g = guardPath(ctx.cwd, String(a.path))
+    if (g.protectedPath) return `error: ${a.path} is a protected path — refused`
+    const p = g.abs
+    if (!existsSync(p)) return `error: no such file: ${a.path}`
+    const src = readFileSync(p, 'utf-8')
+    const oldS = String(a.old_string)
+    const count = src.split(oldS).length - 1
+    if (count === 0) return `error: old_string not found in ${a.path}`
+    if (count > 1 && !a.replace_all) return `error: old_string appears ${count}× — pass replace_all:true or add context to make it unique`
+    if (!(await ctx.approve(`edit ${relative(ctx.cwd, p) || a.path}${g.outside ? ' (OUTSIDE working dir)' : ''}`, { detail: `- ${oldS.slice(0, 300)}\n+ ${String(a.new_string).slice(0, 300)}`, dangerous: g.outside }))) return 'error: edit declined by user'
+    const next = a.replace_all ? src.split(oldS).join(String(a.new_string)) : src.replace(oldS, String(a.new_string))
+    writeFileSync(p, next)
+    return `edited ${a.path} (${count} replacement${count > 1 ? 's' : ''})`
+  },
+}
+
+const list_dir: LocalTool = {
+  mutating: false,
+  summary: (a) => `ls ${a.path ?? '.'}`,
+  spec: { name: 'list_dir', description: 'List directory entries with type + size.', parameters: { type: 'object', properties: { path: { type: 'string' } }, required: [] } },
+  async run(a, ctx) {
+    const g = guardPath(ctx.cwd, String(a.path ?? '.'))
+    if (g.protectedPath) return `error: protected path — refused`
+    if (g.outside && !(await ctx.approve(`list OUTSIDE the working dir: ${a.path}`, { dangerous: true }))) return 'error: declined (outside working directory)'
+    const p = g.abs
+    if (!existsSync(p)) return `error: no such directory: ${a.path}`
+    const entries = readdirSync(p, { withFileTypes: true })
+      .map((e) => {
+        const full = join(p, e.name)
+        let size = ''
+        try { if (e.isFile()) size = `  ${statSync(full).size}b` } catch {}
+        return `${e.isDirectory() ? 'd' : '-'} ${e.name}${e.isDirectory() ? '/' : ''}${size}`
+      })
+      .sort()
+    return clamp(entries.join('\n') || '(empty)')
+  },
+}
+
+const glob: LocalTool = {
+  mutating: false,
+  summary: (a) => `glob ${a.pattern}`,
+  spec: { name: 'glob', description: 'Find files matching a glob (ripgrep, .gitignore-aware). e.g. "src/**/*.ts".', parameters: { type: 'object', properties: { pattern: { type: 'string' }, path: { type: 'string' } }, required: ['pattern'] } },
+  async run(a, ctx) {
+    const g = guardPath(ctx.cwd, String(a.path ?? '.'))
+    if (g.protectedPath) return `error: protected path — refused`
+    if (g.outside && !(await ctx.approve(`glob OUTSIDE the working dir: ${a.path}`, { dangerous: true }))) return 'error: declined (outside working directory)'
+    const dir = g.abs
+    const { stdout, stderr, code } = await capture('rg', ['--files', '-g', String(a.pattern), dir], { cwd: ctx.cwd })
+    if (code !== 0 && !stdout) return stderr.trim() ? `no matches (${stderr.trim().slice(0, 200)})` : 'no matches'
+    return clamp(stdout.split('\n').filter(Boolean).map((f) => relative(ctx.cwd, f) || f).join('\n') || 'no matches')
+  },
+}
+
+const grep: LocalTool = {
+  mutating: false,
+  summary: (a) => `grep "${a.pattern}"`,
+  spec: {
+    name: 'grep',
+    description: 'Search file contents with a regex (ripgrep). Returns file:line:match. Use glob to scope by file type.',
+    parameters: { type: 'object', properties: { pattern: { type: 'string' }, path: { type: 'string' }, glob: { type: 'string' }, ignore_case: { type: 'boolean' } }, required: ['pattern'] },
+  },
+  async run(a, ctx) {
+    const g = guardPath(ctx.cwd, String(a.path ?? '.'))
+    if (g.protectedPath) return `error: protected path — refused`
+    if (g.outside && !(await ctx.approve(`grep OUTSIDE the working dir: ${a.path}`, { dangerous: true }))) return 'error: declined (outside working directory)'
+    const args = ['--line-number', '--no-heading', '--color', 'never']
+    if (a.ignore_case) args.push('-i')
+    if (a.glob) args.push('-g', String(a.glob))
+    args.push('--', String(a.pattern), g.abs)
+    const { stdout, stderr, code } = await capture('rg', args, { cwd: ctx.cwd })
+    if (code === 1) return 'no matches'
+    if (code > 1) return `error: ${stderr.trim().slice(0, 300)}`
+    return clamp(stdout || 'no matches')
+  },
+}
+
+const bash: LocalTool = {
+  mutating: true,
+  summary: (a) => `bash: ${String(a.command).slice(0, 70)}`,
+  spec: {
+    name: 'bash',
+    description: 'Run a shell command in the working directory and return stdout+stderr+exit code. Use for builds, tests, git, installs. Avoid destructive commands.',
+    parameters: { type: 'object', properties: { command: { type: 'string' }, timeout_ms: { type: 'number' } }, required: ['command'] },
+  },
+  async run(a, ctx) {
+    const command = String(a.command)
+    const danger = CATASTROPHIC.test(command)
+    const summary = danger ? `⚠ DANGEROUS shell — ${command.slice(0, 80)}` : `run: ${command.slice(0, 80)}`
+    // bash is ALWAYS dangerous → never covered by --auto; the full command is shown.
+    if (!(await ctx.approve(`${ctx.sandbox && BWRAP ? '[sandboxed] ' : ''}${summary}`, { detail: command, dangerous: true }))) return 'error: command declined by user'
+    const { cmd, args } = bashArgv(command, ctx.cwd, !!ctx.sandbox)
+    const { stdout, stderr, code } = await capture(cmd, args, { cwd: ctx.cwd, timeout: a.timeout_ms ? Number(a.timeout_ms) : 120_000 })
+    const tag = ctx.sandbox ? (BWRAP ? '[sandboxed] ' : '[sandbox unavailable — bwrap not found] ') : ''
+    const body = [stdout && `stdout:\n${stdout}`, stderr && `stderr:\n${stderr}`].filter(Boolean).join('\n')
+    return clamp(`${tag}exit ${code}\n${body || '(no output)'}`)
+  },
+}
+
+export const LOCAL_TOOLS: LocalTool[] = [read_file, write_file, edit_file, list_dir, glob, grep, bash]
+const BY_NAME = new Map(LOCAL_TOOLS.map((t) => [t.spec.name, t]))
+
+export function localToolSpecs(): ToolSpec[] {
+  return LOCAL_TOOLS.map((t) => t.spec)
+}
+
+export function getLocalTool(name: string): LocalTool | undefined {
+  return BY_NAME.get(name)
+}

package/src/agent/trace.ts

@@ -0,0 +1,76 @@
+/**
+ * Flywheel — emit a tool-use trace per completed agent turn to ~/.dragon/traces/.
+ *
+ * These traces are the training data for DragonSpark (our own nano brain): the agent's
+ * real work becomes the dataset that makes its next model better. DragonSpark's data
+ * pipeline does a mandatory secret/customer scrub before any training; we also do a
+ * light redaction here at emit time as defense-in-depth.
+ *
+ * On by default; disable with `--no-trace` or DRAGON_NO_TRACE=1. Local-only — nothing
+ * is uploaded; the file just sits on the operator's machine for the DragonSpark repo
+ * to ingest (src/dragonspark/traces.py).
+ *
+ * Copyright 2026 Ghost Protocol (Pvt) Ltd. All Rights Reserved.
+ */
+
+import { appendFileSync, mkdirSync, chmodSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import type { BrainMessage } from '../brain/types.js'
+
+export const TRACE_DIR = join(homedir(), '.dragon', 'traces')
+
+/**
+ * Strip secrets before anything touches disk. Covers known key prefixes
+ * (sk-, sk-ant-, ghp_, xoxb-, AKIA, dgn_, JWT), cookie + authorization values,
+ * and any long opaque blob. Defense-in-depth for traces that may carry tool output.
+ */
+export function redact(s: string): string {
+  if (!s) return s
+  return s
+    .replace(/\b(?:sk-ant-[A-Za-z0-9_-]+|sk-[A-Za-z0-9_-]{20,}|ghp_[A-Za-z0-9]+|gho_[A-Za-z0-9]+|xox[baprs]-[A-Za-z0-9-]+|AKIA[A-Z0-9]{16}|dgn_[A-Za-z0-9_-]+|eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+)\b/g, '[redacted]')
+    .replace(/(gp_session=)[^;\s"']+/gi, '$1[redacted]')
+    .replace(/(authorization["']?\s*[:=]\s*["']?(?:bearer\s+)?)[^\s"',}]+/gi, '$1[redacted]')
+    .replace(/\b[A-Za-z0-9_-]{40,}\b/g, '[redacted]')
+    .replace(/[A-Za-z0-9+/_-]{40,}={0,2}/g, '[redacted]')
+}
+
+export function traceEnabled(disabledFlag?: boolean): boolean {
+  return !disabledFlag && !process.env.DRAGON_NO_TRACE
+}
+
+/**
+ * Record one settled turn. `added` is the slice of messages appended during the turn
+ * (user → [assistant/tool]* → final assistant). Never throws — a trace failure must
+ * not break the session.
+ */
+export function recordTurn(added: BrainMessage[], meta: { cwd: string; brain: string; context?: string | null }): void {
+  try {
+    const user = added.find((m) => m.role === 'user')?.content ?? ''
+    const tool_calls = added
+      .filter((m) => m.role === 'assistant')
+      .flatMap((m) => (m.toolCalls ?? []).map((t) => ({ name: t.name, arguments: redact(JSON.stringify(t.arguments ?? {})).slice(0, 2000) })))
+    const tool_results = added
+      .filter((m) => m.role === 'tool')
+      .map((m) => ({ name: m.toolName ?? '', result: redact(m.content).slice(0, 4000) }))
+    const finals = added.filter((m) => m.role === 'assistant' && m.content)
+    const final_answer = finals.length ? finals[finals.length - 1].content : ''
+
+    const rec = {
+      ts: new Date().toISOString(),
+      cwd: meta.cwd,
+      brain: meta.brain,
+      prompt: redact(user).slice(0, 8000),
+      retrieved_wyrm_context: meta.context ? redact(meta.context).slice(0, 4000) : undefined,
+      tool_calls,
+      tool_results,
+      final_answer: redact(final_answer).slice(0, 8000),
+    }
+    mkdirSync(TRACE_DIR, { recursive: true, mode: 0o700 })
+    const file = join(TRACE_DIR, `${rec.ts.slice(0, 10)}.jsonl`)
+    appendFileSync(file, JSON.stringify(rec) + '\n', { mode: 0o600 })
+    chmodSync(file, 0o600) // appendFileSync mode only applies on create — enforce on existing too
+  } catch {
+    /* never break a session over a trace write */
+  }
+}

package/src/agent.ts

@@ -0,0 +1,114 @@
+/**
+ * Client for the Dragon assistant — account.ghosts.lk `POST /api/v1/agent`.
+ *
+ * The endpoint runs a server-side tool-calling loop, then streams the answer as
+ * SSE. Two frame kinds arrive on the `data:` channel:
+ *   - `{"tools":[{"name","ok"}]}`  — once, up front, if tools ran (→ onTools)
+ *   - `{"response":"…"}`           — token deltas of the natural-language answer
+ *   - `[DONE]`                     — terminator
+ *
+ * Tools execute server-side and role-gated; the client only DISPLAYS which ran.
+ * Request body is `{ messages:[{role,content}], surface }` — the server keeps
+ * only user/assistant turns and prepends its own system prompt + memory.
+ *
+ * Copyright 2026 Ghost Protocol (Pvt) Ltd. All Rights Reserved.
+ */
+
+import { resolveAuth } from './auth.js'
+
+export interface AgentMsg { role: 'user' | 'assistant'; content: string }
+export interface ToolChip { name: string; ok: boolean }
+
+/** Surfaces the server understands — they scope the tool set + system context. */
+export const SURFACES = ['dashboard', 'admin', 'chat', 'activity', 'marketing'] as const
+export type Surface = (typeof SURFACES)[number]
+
+export type AgentErrorKind = 'unauthenticated' | 'quota' | 'unavailable' | 'http' | 'network'
+
+export class AgentError extends Error {
+  constructor(public kind: AgentErrorKind, message: string, public detail?: unknown) {
+    super(message)
+    this.name = 'AgentError'
+  }
+}
+
+export interface StreamAgentOpts {
+  messages: AgentMsg[]
+  surface: string
+  onDelta: (s: string) => void
+  onTools?: (tools: ToolChip[]) => void
+  signal?: AbortSignal
+}
+
+/**
+ * Stream one assistant turn. Emits tool chips (if any) then token deltas, and
+ * returns the assembled answer when `[DONE]` arrives. Throws AgentError on
+ * 401 (unauthenticated), 429 (quota), 502 (model down), or transport failure.
+ */
+export async function streamAgent(opts: StreamAgentOpts): Promise<string> {
+  const { apiBase, headers, mode } = resolveAuth()
+
+  let res: Response
+  try {
+    res = await fetch(`${apiBase}/api/v1/agent`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', ...headers },
+      body: JSON.stringify({ messages: opts.messages, surface: opts.surface }),
+      signal: opts.signal,
+    })
+  } catch (e) {
+    if ((e as { name?: string })?.name === 'AbortError') throw e
+    throw new AgentError('network', `cannot reach ${apiBase}: ${String(e instanceof Error ? e.message : e)}`)
+  }
+
+  if (res.status === 401) {
+    const b = (await res.json().catch(() => ({}))) as { login_url?: string }
+    const hint = mode === 'none'
+      ? 'no credentials configured — run `dragon login`'
+      : 'your session is invalid or expired — run `dragon login` again'
+    throw new AgentError('unauthenticated', hint, b)
+  }
+  if (res.status === 429) {
+    const b = (await res.json().catch(() => ({}))) as { used?: number; cap?: number; reset_at?: number }
+    const reset = b.reset_at ? new Date(b.reset_at).toLocaleString() : '—'
+    throw new AgentError('quota', `daily quota reached (${b.used ?? '?'} / ${b.cap ?? '?'} tokens). Resets ${reset}.`, b)
+  }
+  if (res.status === 502) {
+    throw new AgentError('unavailable', 'the model is momentarily unavailable — try again in a moment.')
+  }
+  if (!res.ok || !res.body) {
+    const t = await res.text().catch(() => res.statusText)
+    throw new AgentError('http', `HTTP ${res.status}: ${t}`)
+  }
+
+  const reader = res.body.getReader()
+  const decoder = new TextDecoder()
+  let buffer = ''
+  let assembled = ''
+
+  for (;;) {
+    const { value, done } = await reader.read()
+    if (done) break
+    buffer += decoder.decode(value, { stream: true })
+    const lines = buffer.split('\n')
+    buffer = lines.pop() ?? '' // hold the partial trailing line
+
+    for (const line of lines) {
+      if (!line.startsWith('data: ')) continue
+      const data = line.slice(6)
+      if (data === '[DONE]') return assembled
+      try {
+        const obj = JSON.parse(data) as { response?: string; tools?: { name: string; ok?: boolean }[] }
+        if (Array.isArray(obj.tools)) {
+          opts.onTools?.(obj.tools.map((t) => ({ name: String(t.name), ok: t.ok !== false })))
+        } else if (typeof obj.response === 'string' && obj.response) {
+          assembled += obj.response
+          opts.onDelta(obj.response)
+        }
+      } catch {
+        /* skip a malformed frame */
+      }
+    }
+  }
+  return assembled
+}

package/src/auth.ts

@@ -0,0 +1,133 @@
+/**
+ * Auth for the Dragon assistant (account.ghosts.lk /api/v1/agent).
+ *
+ * The assistant is account-scoped: it answers AS the signed-in user and gates
+ * its tools by role. The browser authenticates with the `gp_session` HttpOnly
+ * cookie minted by Google/GitHub OAuth. A CLI has no browser, so we support two
+ * credential carriers, in priority order:
+ *
+ *   1. Bearer token  — `DRAGON_TOKEN` env or `auth.token` in config. The primary
+ *      path: a 90-day personal access token (`dgn_…`) minted by `dragon login`'s
+ *      browser device-code flow. Backend is live on account.ghosts.lk.
+ *   2. Session cookie — `DRAGON_SESSION` env or `auth.session` in config. The
+ *      `gp_session` value copied from a signed-in browser. The `--paste` fallback
+ *      for headless boxes where the device flow can't open a browser.
+ *
+ * Resolution is env-first so a shell can override the stored credential without
+ * touching the config file.
+ *
+ * Copyright 2026 Ghost Protocol (Pvt) Ltd. All Rights Reserved.
+ */
+
+import { loadConfig, saveConfig, type DragonConfig } from './config.js'
+
+export const DEFAULT_API = 'https://account.ghosts.lk'
+
+// Ports browsers refuse to open (ERR_UNSAFE_PORT / "this address is restricted").
+// We guard against ever handing one of these to a browser or using it as an origin.
+const RESTRICTED_PORTS = new Set([
+  1, 7, 9, 11, 13, 15, 17, 19, 20, 21, 22, 23, 25, 37, 42, 43, 53, 69, 77, 79, 87, 95,
+  101, 102, 103, 104, 109, 110, 111, 113, 115, 117, 119, 123, 135, 137, 139, 143, 161,
+  179, 389, 427, 465, 512, 513, 514, 515, 526, 530, 531, 532, 540, 548, 554, 556, 563,
+  587, 601, 636, 989, 990, 993, 995, 1719, 1720, 1723, 2049, 3659, 4045, 5060, 5061,
+  6000, 6566, 6665, 6666, 6667, 6668, 6669, 6697, 10080,
+])
+
+/** True if `raw` is a URL a browser will actually open: http(s), a sane port, and
+ *  https for any non-loopback host (no plaintext auth over the network). */
+export function isBrowsableHttpUrl(raw: string): boolean {
+  let u: URL
+  try { u = new URL(raw) } catch { return false }
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') return false
+  const isLocal = u.hostname === 'localhost' || u.hostname === '127.0.0.1' || u.hostname === '::1'
+  if (!isLocal && u.protocol !== 'https:') return false
+  const port = u.port ? Number(u.port) : u.protocol === 'https:' ? 443 : 80
+  return !RESTRICTED_PORTS.has(port)
+}
+
+/** A trustworthy assistant origin, self-healing: a malformed/restricted-port value
+ *  (e.g. a stale config) silently falls back to the default instead of breaking login. */
+export function sanitizeApiBase(raw?: string): string {
+  const trimmed = (raw ?? '').replace(/\/+$/, '')
+  return trimmed && isBrowsableHttpUrl(trimmed) ? trimmed : DEFAULT_API
+}
+
+export type AuthMode = 'token' | 'session' | 'none'
+
+export interface ResolvedAuth {
+  apiBase: string
+  headers: Record<string, string>
+  mode: AuthMode
+  email?: string
+}
+
+/** Credential values become HTTP header content — accept only printable, space-free
+ *  ASCII so a CR/LF or control char can't smuggle extra headers. */
+export function validCred(v?: string): string | undefined {
+  return v && /^[\x21-\x7e]+$/.test(v) ? v : undefined
+}
+
+/** The credential-bearing env vars auth reads — extracted so the precedence
+ *  logic is unit-testable without a real shell, config file, or second machine. */
+export interface AuthEnv {
+  DRAGON_API?: string
+  DRAGON_TOKEN?: string
+  DRAGON_SESSION?: string
+}
+
+/**
+ * Pure auth resolution: env-first, then config, behind the cred-injection
+ * (`validCred`) and restricted-origin (`sanitizeApiBase`) guards. Token beats
+ * session beats none. `resolveAuth()` is just this fed the real env + config —
+ * keeping the decision logic deterministic and machine-independent for tests.
+ */
+export function resolveAuthFrom(env: AuthEnv, cfg: DragonConfig): ResolvedAuth {
+  const apiBase = sanitizeApiBase(env.DRAGON_API || cfg.auth?.apiBase)
+  const token = validCred(env.DRAGON_TOKEN || cfg.auth?.token)
+  const session = validCred(env.DRAGON_SESSION || cfg.auth?.session)
+  const email = cfg.auth?.email
+  if (token) return { apiBase, headers: { authorization: `Bearer ${token}` }, mode: 'token', email }
+  if (session) return { apiBase, headers: { cookie: `gp_session=${session}` }, mode: 'session', email }
+  return { apiBase, headers: {}, mode: 'none', email }
+}
+
+/** Resolve the assistant origin + credential headers from env then config. */
+export function resolveAuth(): ResolvedAuth {
+  return resolveAuthFrom(process.env, loadConfig())
+}
+
+/** Merge a patch into config.auth and persist. */
+export function saveAuth(patch: Partial<NonNullable<DragonConfig['auth']>>): void {
+  const cfg = loadConfig()
+  cfg.auth = { ...(cfg.auth ?? {}), ...patch }
+  saveConfig(cfg)
+}
+
+/** Forget all stored credentials (keeps a custom apiBase if set). */
+export function clearAuth(): void {
+  const cfg = loadConfig()
+  const apiBase = cfg.auth?.apiBase
+  cfg.auth = apiBase ? { apiBase } : {}
+  saveConfig(cfg)
+}
+
+export interface WhoAmI { ok: boolean; status: number; email?: string; error?: string }
+
+/**
+ * Validate the current (or a supplied) credential against the cheap authed
+ * endpoint `GET /api/v1/me/licenses` — no LLM cost. Returns the identity email
+ * on success so the caller can confirm + store who we signed in as.
+ */
+export async function whoami(override?: { headers?: Record<string, string>; apiBase?: string }): Promise<WhoAmI> {
+  const base = override?.apiBase ?? resolveAuth().apiBase
+  const headers = override?.headers ?? resolveAuth().headers
+  try {
+    const res = await fetch(`${base}/api/v1/me/licenses`, { headers })
+    if (res.status === 401) return { ok: false, status: 401, error: 'not signed in' }
+    if (!res.ok) return { ok: false, status: res.status, error: `HTTP ${res.status}` }
+    const body = (await res.json().catch(() => ({}))) as { account?: { email?: string } }
+    return { ok: true, status: 200, email: body.account?.email }
+  } catch (e) {
+    return { ok: false, status: 0, error: String(e instanceof Error ? e.message : e) }
+  }
+}

package/src/brain/anthropic.ts

@@ -0,0 +1,83 @@
+/**
+ * Claude brain — Anthropic Messages API via the official SDK. The default,
+ * "amazing at programming" path.
+ *
+ * Maps our normalized BrainMessage[] onto Anthropic's content-block format:
+ *   - assistant tool calls  → `tool_use`  blocks
+ *   - tool results          → `tool_result` blocks (folded into a user message;
+ *     consecutive tool messages are batched into one user turn, as the API wants)
+ * Streams `text` deltas and collects `tool_use` blocks from the final message.
+ *
+ * Copyright 2026 Ghost Protocol (Pvt) Ltd. All Rights Reserved.
+ */
+
+import Anthropic from '@anthropic-ai/sdk'
+import type { Brain, BrainMessage, BrainTurn, ToolSpec, TurnOpts } from './types.js'
+
+export const DEFAULT_CLAUDE_MODEL = 'claude-sonnet-4-6'
+
+type ABlock =
+  | { type: 'text'; text: string }
+  | { type: 'tool_use'; id: string; name: string; input: unknown }
+  | { type: 'tool_result'; tool_use_id: string; content: string }
+
+interface AMessage { role: 'user' | 'assistant'; content: ABlock[] }
+
+/** Fold our flat BrainMessage[] into Anthropic's role-batched content blocks. */
+function toAnthropic(messages: BrainMessage[]): AMessage[] {
+  const out: AMessage[] = []
+  for (const m of messages) {
+    if (m.role === 'tool') {
+      const block: ABlock = { type: 'tool_result', tool_use_id: m.toolCallId ?? '', content: m.content }
+      const last = out[out.length - 1]
+      if (last && last.role === 'user' && last.content.every((b) => b.type === 'tool_result')) last.content.push(block)
+      else out.push({ role: 'user', content: [block] })
+      continue
+    }
+    if (m.role === 'assistant') {
+      const blocks: ABlock[] = []
+      if (m.content) blocks.push({ type: 'text', text: m.content })
+      for (const tc of m.toolCalls ?? []) blocks.push({ type: 'tool_use', id: tc.id, name: tc.name, input: tc.arguments })
+      out.push({ role: 'assistant', content: blocks.length ? blocks : [{ type: 'text', text: '' }] })
+      continue
+    }
+    // user
+    out.push({ role: 'user', content: [{ type: 'text', text: m.content }] })
+  }
+  return out
+}
+
+function toAnthropicTools(tools: ToolSpec[]) {
+  return tools.map((t) => ({ name: t.name, description: t.description, input_schema: t.parameters as Anthropic.Tool.InputSchema }))
+}
+
+export function makeClaudeBrain(opts: { apiKey: string; model?: string }): Brain {
+  const client = new Anthropic({ apiKey: opts.apiKey })
+  const model = opts.model || DEFAULT_CLAUDE_MODEL
+  return {
+    id: 'claude',
+    model,
+    async turn(t: TurnOpts): Promise<BrainTurn> {
+      const stream = client.messages.stream(
+        {
+          model,
+          max_tokens: t.maxTokens ?? 8192,
+          system: t.system,
+          messages: toAnthropic(t.messages) as Anthropic.MessageParam[],
+          tools: t.tools.length ? toAnthropicTools(t.tools) : undefined,
+        },
+        { signal: t.signal },
+      )
+      if (t.onDelta) stream.on('text', (delta) => t.onDelta!(delta))
+      const final = await stream.finalMessage()
+
+      let text = ''
+      const toolCalls: BrainTurn['toolCalls'] = []
+      for (const block of final.content) {
+        if (block.type === 'text') text += block.text
+        else if (block.type === 'tool_use') toolCalls.push({ id: block.id, name: block.name, arguments: (block.input ?? {}) as Record<string, unknown> })
+      }
+      return { text, toolCalls }
+    },
+  }
+}