ghost-dragon 4.2.1

package/dist/agent/stack.js

@@ -0,0 +1,158 @@
+/**
+ * Stack-fused tools — the agent IS the operator console. It can read the live Ghost
+ * Protocol stack state and drive `dragon` subcommands (scale/wyrm/pentest/keep/net…)
+ * as first-class tools, not just guess at bash.
+ *
+ * Safety: read-only verbs run freely; everything else (pentest, deploy, install…) is
+ * `dangerous` → always prompts + shows the full command (never covered by --auto).
+ * Interactive/recursive/long-lived verbs (chat/ask/login/serve/up) are refused.
+ * Each invocation is a fresh subprocess of THIS CLI, time-bounded + output-capped.
+ *
+ * Copyright 2026 Ghost Protocol (Pvt) Ltd. All Rights Reserved.
+ */
+import { execFile } from 'node:child_process';
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { loadConfig } from '../config.js';
+const SELF = process.argv[1] ?? ''; // the dragon CLI entry (dist/index.js)
+const SAFE = new Set(['list', 'doctor', 'status', 'brains', 'whoami']); // read-only → no approval
+const BLOCKED = new Set(['chat', 'ask', 'login', 'logout', 'serve', 'up', 'down', 'init']); // interactive / recursive / long-lived
+const MAX_OUT = 20_000;
+function runDragon(args, cwd, timeout) {
+    return new Promise((res) => {
+        execFile(process.execPath, [SELF, ...args], { cwd, timeout, maxBuffer: 1 << 20 }, (err, stdout, stderr) => {
+            const out = ((stdout || '') + (stderr || '')).slice(0, MAX_OUT);
+            const code = err && typeof err.code === 'number' ? err.code : err ? 1 : 0;
+            res({ out, code });
+        });
+    });
+}
+/** Run an arbitrary external process (a stack product), bounded + capped.
+ *  Keeps stdout/stderr SEPARATE — products print progress to stderr and the
+ *  machine-readable JSON to stdout, so a parser must read stdout alone. */
+function runProc(cmd, args, cwd, timeout) {
+    return new Promise((res) => {
+        execFile(cmd, args, { cwd, timeout, maxBuffer: 8 << 20 }, (err, stdout, stderr) => {
+            const code = err && typeof err.code === 'number' ? err.code : err ? 1 : 0;
+            res({ stdout: stdout || '', stderr: stderr || '', code });
+        });
+    });
+}
+/** Newest reports/<dir>/findings.json under a PhantomDragon repo (the scan output). */
+function newestFindings(pentestRoot) {
+    const dir = join(pentestRoot, 'reports');
+    if (!existsSync(dir))
+        return null;
+    const subs = readdirSync(dir).map((d) => join(dir, d)).filter((p) => { try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    } });
+    if (!subs.length)
+        return null;
+    subs.sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs);
+    const f = join(subs[0], 'findings.json');
+    return existsSync(f) ? f : null;
+}
+export function makeStackTools() {
+    const specs = [
+        {
+            name: 'stack_status',
+            description: 'Live state of the Ghost Protocol dragon stack (each product: installed / running / version), as JSON. Read-only — call it to know what is deployed before acting.',
+            parameters: { type: 'object', properties: {}, required: [] },
+        },
+        {
+            name: 'stack_run',
+            description: 'Run a `dragon` stack command for an ops task — e.g. "list", "doctor", "pentest scan <url>", "wyrm <…>", "keep <…>". Read-only verbs run freely; actions require approval. NOT for chat/ask/login/serve.',
+            parameters: { type: 'object', properties: { command: { type: 'string', description: 'the dragon subcommand + args, e.g. "pentest scan https://example.com"' } }, required: ['command'] },
+        },
+        {
+            name: 'stack_pentest',
+            description: 'Run a PhantomDragon web security scan against a URL (AUTHORIZED targets only) and return STRUCTURED findings (severity, category, CVSS, confirmed, remediation) + a risk summary. Long-running; writes a report. Requires PhantomDragon configured.',
+            parameters: { type: 'object', properties: { url: { type: 'string' }, profile: { type: 'string', enum: ['quick', 'standard', 'full', 'api_only', 'auth_only'] }, mode: { type: 'string', enum: ['safe', 'standard', 'aggressive'] } }, required: ['url'] },
+        },
+        {
+            name: 'stack_keep',
+            description: 'Run a DragonKeep system-security scan (READ-ONLY local inspection) and return STRUCTURED findings (severity, CVSS, fix) + a summary. scan_type: full | quick | malware | ransomware | hunt | score.',
+            parameters: { type: 'object', properties: { scan_type: { type: 'string', enum: ['full', 'quick', 'malware', 'ransomware', 'hunt', 'score'] }, profile: { type: 'string' } }, required: [] },
+        },
+    ];
+    return {
+        specs,
+        handles: (name) => ['stack_status', 'stack_run', 'stack_pentest', 'stack_keep'].includes(name),
+        async call(name, args, ctx) {
+            if (name === 'stack_pentest')
+                return runPentest(args, ctx);
+            if (name === 'stack_keep')
+                return runKeep(args, ctx);
+            if (!SELF)
+                return 'error: stack tools unavailable (no CLI entry path)';
+            if (name === 'stack_status') {
+                const r = await runDragon(['list', '--json'], ctx.cwd, 30_000);
+                return r.out || '(no output)';
+            }
+            const command = String(args.command ?? '').trim();
+            if (!command)
+                return 'error: no command given';
+            const parts = command.split(/\s+/);
+            const verb = parts[0];
+            if (BLOCKED.has(verb))
+                return `error: "${verb}" can't be run as a tool (interactive / recursive / long-lived)`;
+            if (!SAFE.has(verb) && !(await ctx.approve(`dragon ${command.slice(0, 100)}`, { detail: `dragon ${command}`, dangerous: true }))) {
+                return 'error: declined by user';
+            }
+            const r = await runDragon(parts, ctx.cwd, 180_000);
+            return `exit ${r.code}\n${r.out || '(no output)'}`;
+        },
+    };
+}
+// ── Structured stack actions (typed results, not just passthrough) ──
+async function runPentest(args, ctx) {
+    const root = loadConfig().products?.pentest?.path;
+    if (!root || !existsSync(root))
+        return 'error: PhantomDragon not configured — set products.pentest.path (run `dragon init`).';
+    const script = ['phantom_dragon_ai.py', 'phantomdragon.py'].map((s) => join(root, s)).find(existsSync);
+    if (!script)
+        return `error: PhantomDragon entry script not found in ${root}`;
+    const url = String(args.url ?? '').trim();
+    if (!url)
+        return 'error: url is required';
+    const profile = String(args.profile ?? 'standard');
+    const mode = String(args.mode ?? 'safe');
+    if (!(await ctx.approve(`⚠ pentest scan ${url} (profile ${profile}, mode ${mode}) — authorized targets only`, { dangerous: true })))
+        return 'error: declined by user';
+    const r = await runProc('python3', [script, '-t', url, '--profile', profile, '--mode', mode], root, 600_000);
+    const fj = newestFindings(root);
+    if (!fj)
+        return `scan exited ${r.code}; no findings.json produced.\n${(r.stderr || r.stdout).slice(-1200)}`;
+    try {
+        const d = JSON.parse(readFileSync(fj, 'utf-8'));
+        const findings = (d.findings ?? []).slice(0, 15).map((f) => ({ id: f.id, title: f.title, severity: f.severity, category: f.category, url: f.url, confirmed: f.confirmed, cvss: f.cvss_score, remediation: (f.remediation ?? '').slice(0, 160) }));
+        return JSON.stringify({ report: fj, meta: d.meta, summary: d.summary, findings }).slice(0, MAX_OUT);
+    }
+    catch {
+        return `scan complete but findings.json could not be parsed at ${fj}`;
+    }
+}
+async function runKeep(args, ctx) {
+    const keepRoot = loadConfig().products?.keep?.path;
+    const bin = [keepRoot && join(keepRoot, 'target/release/dragonkeep'), keepRoot && join(keepRoot, 'target/debug/dragonkeep'), '/usr/local/bin/dragonkeep', '/usr/bin/dragonkeep'].filter(Boolean).find((p) => existsSync(p)) ?? 'dragonkeep';
+    const scanType = String(args.scan_type ?? 'quick');
+    const direct = ['malware', 'ransomware', 'hunt', 'score', 'ai', 'supply', 'anomaly'];
+    const cmd = ['--quiet', '--format', 'json'];
+    if (direct.includes(scanType))
+        cmd.push(scanType);
+    else
+        cmd.push('scan', '--profile', String(args.profile ?? (scanType === 'full' ? 'standard' : 'quick')));
+    const r = await runProc(bin, cmd, ctx.cwd, 300_000);
+    try {
+        const d = JSON.parse(r.stdout);
+        const sections = (d.sections ?? []).map((s) => ({ name: s.name, findings: (s.findings ?? []).filter((f) => f.severity !== 'Pass').slice(0, 8).map((f) => ({ title: f.title, severity: f.severity, cvss: f.cvss, fix: (f.fix ?? '').slice(0, 140) })) }));
+        return JSON.stringify({ hostname: d.hostname, summary: d.summary, sections }).slice(0, MAX_OUT);
+    }
+    catch {
+        return `dragonkeep exited ${r.code}${bin === 'dragonkeep' ? ' (binary not found — build it: cargo build --release in DragonKeep, or `dragon install keep`)' : ''}\n${(r.stderr || r.stdout).slice(0, 1500)}`;
+    }
+}
+//# sourceMappingURL=stack.js.map

package/dist/agent/task.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Sub-agents — the `task` tool. The agent can spawn a focused, READ-ONLY sub-agent
+ * to research/analyze a sub-problem (audit a file, summarize how something works,
+ * survey a codebase) without polluting the main thread. The sub-agent can read,
+ * grep, glob, list, and use skills — but cannot write, edit, or run shell, and
+ * cannot itself spawn tasks (no recursion / fork-bombs). It returns its findings.
+ *
+ * Copyright 2026 Ghost Protocol (Pvt) Ltd. All Rights Reserved.
+ */
+import type { Brain, ToolSpec } from '../brain/types.js';
+import type { SkillLibrary } from './skills.js';
+export interface TaskTool {
+    spec: ToolSpec;
+    call(args: Record<string, unknown>): Promise<string>;
+}
+export declare function makeTaskTool(parent: {
+    brain: Brain;
+    skills: SkillLibrary | null;
+    cwd: string;
+}): TaskTool;
+//# sourceMappingURL=task.d.ts.map

package/dist/agent/task.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../src/agent/task.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAI/C,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,QAAQ,CAAA;IACd,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;CACrD;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,QAAQ,CAkCzG"}

package/dist/agent/task.js

@@ -0,0 +1,45 @@
+/**
+ * Sub-agents — the `task` tool. The agent can spawn a focused, READ-ONLY sub-agent
+ * to research/analyze a sub-problem (audit a file, summarize how something works,
+ * survey a codebase) without polluting the main thread. The sub-agent can read,
+ * grep, glob, list, and use skills — but cannot write, edit, or run shell, and
+ * cannot itself spawn tasks (no recursion / fork-bombs). It returns its findings.
+ *
+ * Copyright 2026 Ghost Protocol (Pvt) Ltd. All Rights Reserved.
+ */
+import { runAgent, buildSystemPrompt } from './loop.js';
+export function makeTaskTool(parent) {
+    return {
+        spec: {
+            name: 'task',
+            description: 'Spawn a focused READ-ONLY sub-agent to research or analyze a sub-problem in isolation (e.g. "audit src/auth.ts for security bugs", "summarize how the brain adapter works"). It can read/grep/glob/list + use skills, but CANNOT write, edit, or run shell. Returns its findings. Use it to offload big read-heavy investigations and keep your own context clean.',
+            parameters: { type: 'object', properties: { task: { type: 'string', description: 'the self-contained subtask to investigate' } }, required: ['task'] },
+        },
+        async call(args) {
+            const prompt = String(args.task ?? '').trim();
+            if (!prompt)
+                return 'error: no task given';
+            const denyAll = { cwd: parent.cwd, approve: async () => false }; // read-only sub-agent
+            const subDeps = {
+                brain: parent.brain,
+                wyrm: null, portal: null, stack: null, mcp: null, task: null, // sub-agent: read + skills only, NO recursion
+                skills: parent.skills,
+                cwd: parent.cwd,
+                system: buildSystemPrompt({ cwd: parent.cwd, wyrm: false, portal: false, brainId: `${parent.brain.id}:${parent.brain.model}`, skills: parent.skills?.count || undefined }) +
+                    '\n\nYou are a FOCUSED SUB-AGENT spawned for ONE read-only investigation. Use read_file/grep/glob/list_dir/skill_* only — you CANNOT write, edit, or run shell (those are denied). Investigate thoroughly, then return a concise, complete, self-contained answer. Do not ask questions.',
+                toolCtx: denyAll,
+                messages: [],
+            };
+            let out = '';
+            const quiet = { onAssistantStart() { }, onDelta(s) { out += s; }, onToolStart() { }, onToolEnd() { } };
+            try {
+                await runAgent(subDeps, prompt, quiet, new AbortController().signal);
+                return out.trim() || '(sub-agent returned nothing)';
+            }
+            catch (e) {
+                return `sub-agent error: ${String(e instanceof Error ? e.message : e)}`;
+            }
+        },
+    };
+}
+//# sourceMappingURL=task.js.map

package/dist/agent/tools.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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 type { ToolSpec } from '../brain/types.js';
+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 declare const BWRAP: string | null;
+/** Resolve a path and classify it: inside cwd, outside, or protected (symlink-aware). */
+export declare function guardPath(cwd: string, p: string): {
+    abs: string;
+    outside: boolean;
+    protectedPath: boolean;
+};
+export interface LocalTool {
+    spec: ToolSpec;
+    mutating: boolean;
+    summary(args: Record<string, unknown>): string;
+    run(args: Record<string, unknown>, ctx: ToolContext): Promise<string>;
+}
+export declare const LOCAL_TOOLS: LocalTool[];
+export declare function localToolSpecs(): ToolSpec[];
+export declare function getLocalTool(name: string): LocalTool | undefined;
+//# sourceMappingURL=tools.d.ts.map

package/dist/agent/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/agent/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAKjD,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAA;IACX;yEACqE;IACrE,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IAC/F;oFACgF;IAChF,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,eAAO,MAAM,KAAK,eAAgF,CAAA;AAqBlG,yFAAyF;AACzF,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,aAAa,EAAE,OAAO,CAAA;CAAE,CAU3G;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,QAAQ,CAAA;IACd,QAAQ,EAAE,OAAO,CAAA;IACjB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAA;IAC9C,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;CACtE;AA6KD,eAAO,MAAM,WAAW,EAAE,SAAS,EAAmE,CAAA;AAGtG,wBAAgB,cAAc,IAAI,QAAQ,EAAE,CAE3C;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAEhE"}

package/dist/agent/tools.js

@@ -0,0 +1,262 @@
+/**
+ * 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';
+const MAX_OUTPUT = 30_000; // chars fed back to the model per tool result
+const MAX_READ_BYTES = 200_000;
+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, cwd, sandbox) {
+    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, p) {
+    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) => x === root || x.startsWith(root + '/');
+    const outside = !(within(real) || within(absPath));
+    return { abs: absPath, outside, protectedPath };
+}
+function clamp(s) {
+    return s.length > MAX_OUTPUT ? s.slice(0, MAX_OUTPUT) + `\n… [truncated ${s.length - MAX_OUTPUT} chars]` : s;
+}
+function capture(cmd, args, opts) {
+    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 = {
+    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 = {
+    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 = {
+    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 = {
+    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 = {
+    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 = {
+    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 = {
+    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 = [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() {
+    return LOCAL_TOOLS.map((t) => t.spec);
+}
+export function getLocalTool(name) {
+    return BY_NAME.get(name);
+}
+//# sourceMappingURL=tools.js.map

package/dist/agent/trace.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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 type { BrainMessage } from '../brain/types.js';
+export declare const TRACE_DIR: string;
+/**
+ * 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 declare function redact(s: string): string;
+export declare function traceEnabled(disabledFlag?: boolean): boolean;
+/**
+ * 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 declare function recordTurn(added: BrainMessage[], meta: {
+    cwd: string;
+    brain: string;
+    context?: string | null;
+}): void;
+//# sourceMappingURL=trace.d.ts.map

package/dist/agent/trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../../src/agent/trace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAErD,eAAO,MAAM,SAAS,QAAuC,CAAA;AAE7D;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAQxC;AAED,wBAAgB,YAAY,CAAC,YAAY,CAAC,EAAE,OAAO,GAAG,OAAO,CAE5D;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,YAAY,EAAE,EAAE,IAAI,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG,IAAI,CA6BrH"}

package/dist/agent/trace.js

@@ -0,0 +1,72 @@
+/**
+ * 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';
+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) {
+    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) {
+    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, meta) {
+    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 */
+    }
+}
+//# sourceMappingURL=trace.js.map