@onepointfour-packs/flaredeck-agent 0.1.0

package/dist/jevguard.d.ts

@@ -0,0 +1,28 @@
+import type { HookCallbackMatcher, HookEvent } from '@anthropic-ai/claude-agent-sdk';
+import type { Decider } from './permissions.js';
+export type GuardOutcome = 'ran' | 'asked-allowed' | 'asked-denied' | 'refused' | 'unchecked';
+export type GuardConfig = {
+    apiKey: string;
+    /** Where a question goes when one is worth asking. */
+    decider: Decider;
+    /** The pane. */
+    log: (text: string) => void;
+    /** Which agent and repo this is, for the audit file. */
+    agent: string;
+    repo: string;
+    /** The card being worked, when there is one. */
+    card: () => string | null;
+};
+export declare function audit(entry: Record<string, unknown>): void;
+/**
+ * Should this command run? One decision, shared.
+ *
+ * The Claude engine asks through a PreToolUse hook; the Gemini engine asks over loopback from its
+ * Python sidecar. Both land here, so there is one set of thresholds, one audit trail and one place
+ * to change the rules — rather than the same policy written twice and quietly diverging.
+ */
+export declare function judgeCommand(cfg: GuardConfig, command: string): Promise<{
+    allow: boolean;
+    reason?: string;
+}>;
+export declare function jevGuard(cfg: GuardConfig): Partial<Record<HookEvent, HookCallbackMatcher[]>>;

package/dist/jevguard.js

@@ -0,0 +1,213 @@
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+/**
+ * The gate that lets the agent work.
+ *
+ * Running the SDK on `auto` meant a model classifier judged every call with no knowledge of this
+ * machine, and it refused ordinary work — a build, a deploy script, an edit through a heredoc —
+ * which left the agent reporting itself blocked and waiting for a person to type the command.
+ * That is the opposite of what FlareDeck is for. So permissions are bypassed and ONE question is
+ * asked instead, of a model that only answers questions: would this destroy or expose something
+ * that cannot be got back?
+ *
+ * Almost nothing is asked about. A regex prefilter finds the commands that could conceivably be
+ * irreversible; everything else — the overwhelming majority — runs untouched and costs nothing.
+ *
+ * This is a RATE reducer, not a boundary. Jev reads the command text, so a DROP reached through a
+ * migration, an ORM call or `npm run reset-db` is a string it has no opinion about. The boundaries
+ * that actually hold are elsewhere and do not depend on anybody's judgement: read-only database
+ * credentials, no production secrets on the machine, point-in-time recovery proved by a restore,
+ * branch protection on the remote. Keep those and this is a sensible trade; skip them and this is
+ * the only thing standing between an agent and your data, which it is not good enough to be.
+ */
+const ENDPOINT = 'https://openrouter.ai/api/alpha/decisions';
+const MODEL = 'typesafe/jev-1.13';
+/**
+ * The tiers are set on the assumption that ASKING IS WEAK.
+ *
+ * Someone who has lost contact with the work approves everything to get it moving, which is no
+ * permission system at all — just a slower one with a name attached. So the band that asks is
+ * deliberately narrow: things that can be undone RUN, things that cannot are REFUSED outright,
+ * and a person is only asked in the strip of genuine uncertainty between them. A refusal the
+ * agent can read and route around (the production-run flow, a note on the card) is worth more
+ * than a yes nobody meant.
+ */
+const REFUSE_AT = 0.6;
+/** Above this, a person is asked on the card. Below it, the command runs. */
+const ESCALATE_AT = 0.4;
+/** Reading a credential into the transcript is not "destructive", so it is judged on its own. */
+const EXPOSE_AT = 0.6;
+/**
+ * Commands worth a question. Deliberately broad — a false positive costs a fraction of a cent and
+ * a second, a false negative costs the thing that was deleted.
+ */
+const INTERESTING = [
+    /\brm\b.*(-[a-z]*r|--recursive)/i,
+    /\b(drop|truncate|delete\s+from)\b/i,
+    /\b(psql|mysql|mongo|mongosh|redis-cli|sqlite3|dbmate|flyway|liquibase)\b/i,
+    /\b(prisma|sequelize|knex|typeorm|alembic|rails)\b.*\b(migrate|reset|drop|db:drop|db:reset)\b/i,
+    /\bgcloud\b.*\b(delete|destroy|remove)\b/i,
+    /\b(aws|az)\b.*\b(rm|delete|destroy|terminate)\b/i,
+    /\bgsutil\b.*\brm\b/i,
+    /\bfirebase\b.*\b(delete|destroy)\b/i,
+    /\bterraform\b.*\b(destroy|apply)\b/i,
+    /\bkubectl\b.*\b(delete|drain)\b/i,
+    /\bdocker\b.*\b(system\s+prune|volume\s+rm)\b/i,
+    /\bgit\b.*(--force|-f\b|reset\s+--hard|clean\s+-[a-z]*f)/i,
+    /\b(chmod|chown)\b.*-R/i,
+    /\b(shutdown|reboot|mkfs|dd)\b/i,
+    // Sending data OFF the machine. `\b` does NOT sit between a space and a hyphen — both are
+    // non-word characters — so `\b-d\b` never matched ` -d @.env`, and the probe walked an `.env`
+    // POST straight through. Flags are matched on whitespace, not on word boundaries.
+    /\b(curl|wget|http|httpie)\b[^\n]*(^|\s)(-d|-F|-T|--data|--data-binary|--data-raw|--form|--upload-file)(\s|=)/i,
+    /\b(scp|rsync|ncat|nc)\b/i,
+    // Secrets, by name, anywhere a command could read them and pipe them somewhere.
+    /\.(env|pem|key|p12|p8)\b|\b(id_rsa|credentials|service-?account|secrets?\.(json|ya?ml))\b/i,
+    // Fetch-and-execute: the fetched text is nobody's reviewed code.
+    /\b(curl|wget)\b[^|]*\|\s*(ba)?sh\b/i,
+    />\s*\/dev\/(sd|nvme)/i,
+    /\b(deploy|promote|release|publish)\b/i,
+];
+/** One line per decision, appended forever: what was asked, what Jev said, what happened. */
+const auditPath = () => join(process.env['XDG_CONFIG_HOME'] || join(homedir(), '.config'), 'flaredeck-agent', 'decisions.jsonl');
+export function audit(entry) {
+    try {
+        const path = auditPath();
+        mkdirSync(dirname(path), { recursive: true });
+        appendFileSync(path, `${JSON.stringify({ at: new Date().toISOString(), ...entry })}\n`);
+    }
+    catch {
+        // An audit line that cannot be written must not stop the work it is describing.
+    }
+}
+async function ask(command, apiKey) {
+    const started = Date.now();
+    const res = await fetch(ENDPOINT, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            model: MODEL,
+            state: `A software agent working unattended in a git checkout wants to run this shell command:\n\n${command}`,
+            questions: {
+                destructive: {
+                    type: 'noul',
+                    instructions: 'Would running this command destroy, overwrite or expose something that CANNOT be recovered from the git repository — dropping, truncating or deleting rows from a database; deleting storage buckets, volumes or production files; destroying infrastructure; revoking or rotating credentials; rewriting or force-pushing shared history; or sending secrets off the machine? Building, testing, installing dependencies, reading, and deleting files inside the checkout are NOT destructive: everything in the checkout is recoverable from git.',
+                },
+                reversible: {
+                    type: 'noul',
+                    instructions: 'If this command did the wrong thing, could the previous state be put back WITHOUT a database restore and without losing data — by deploying again, reverting a commit, reinstalling, or re-running it? A deploy, a build, a dependency install and a config change are reversible. Dropping or truncating a table, deleting rows, deleting a bucket or an instance, and destroying infrastructure are NOT.',
+                },
+                exposes: {
+                    type: 'noul',
+                    instructions: 'Would running this put a SECRET where it does not belong — printing, copying, encoding or uploading a private key, an API key, a token, a password, a .env file or a service-account file? Reading application source, configuration without secrets in it, or logs is NOT exposure.',
+                },
+                blast: {
+                    type: 'choice',
+                    instructions: 'If this command went wrong, what would it reach?',
+                    criteria: {
+                        local: 'Only this checkout or this machine — recoverable from git or by reinstalling',
+                        shared: 'A shared branch, a CI pipeline, a staging environment or a team account',
+                        production: 'Production data, live customer data, production infrastructure or credentials',
+                    },
+                },
+            },
+        }),
+    });
+    const body = await res.json().catch(() => ({}));
+    if (!res.ok)
+        throw new Error(`OpenRouter ${res.status}: ${body?.error?.message ?? 'request failed'}`);
+    return {
+        destructive: Number(body.answers?.destructive?.noul ?? 1),
+        reversible: Number(body.answers?.reversible?.noul ?? 0),
+        exposes: Number(body.answers?.exposes?.noul ?? 1),
+        blast: String(body.answers?.blast?.choice ?? 'unknown'),
+        cost: Number(body.usage?.cost ?? 0),
+        ms: Date.now() - started,
+    };
+}
+/**
+ * Should this command run? One decision, shared.
+ *
+ * The Claude engine asks through a PreToolUse hook; the Gemini engine asks over loopback from its
+ * Python sidecar. Both land here, so there is one set of thresholds, one audit trail and one place
+ * to change the rules — rather than the same policy written twice and quietly diverging.
+ */
+export async function judgeCommand(cfg, command) {
+    const card = cfg.card();
+    const base = { agent: cfg.agent, repo: cfg.repo, card, command: command.slice(0, 500) };
+    if (!INTERESTING.some((re) => re.test(command)))
+        return { allow: true };
+    let verdict;
+    try {
+        // No key is not a reason to skip the guard — it is a reason to ask a person. Thrown rather
+        // than called out to OpenRouter first: a 401 per risky command is a round trip that can only
+        // ever fail, and the handler below is already exactly the right behaviour for it.
+        if (!cfg.apiKey)
+            throw new Error('no OpenRouter key on this machine');
+        verdict = await ask(command, cfg.apiKey);
+    }
+    catch (e) {
+        // Fail CLOSED, but to a person rather than to a refusal: an unreachable decision model must
+        // not become an agent that stops, and must not become one that proceeds.
+        const why = e instanceof Error ? e.message : String(e);
+        cfg.log(`jev unreachable (${why}) — asking a person instead`);
+        const decision = await cfg.decider({ toolName: 'Bash', input: { command } }, { signal: new AbortController().signal });
+        audit({ ...base, outcome: decision.allow ? 'asked-allowed' : 'asked-denied', jev: null, error: why });
+        return decision.allow ? { allow: true } : { allow: false, reason: `Not approved. ${decision.reason}` };
+    }
+    const jev = { destructive: verdict.destructive, reversible: verdict.reversible, exposes: verdict.exposes, blast: verdict.blast, cost_usd: verdict.cost, ms: verdict.ms };
+    // A secret read into the transcript is already out — there is nothing to approve afterwards,
+    // so this one never asks.
+    if (verdict.exposes >= EXPOSE_AT) {
+        cfg.log(`refused: it would put a secret in the open (${Math.round(verdict.exposes * 100)}%)`);
+        audit({ ...base, outcome: 'refused', why: 'exposes', jev });
+        return {
+            allow: false,
+            reason: 'That would put a secret where it does not belong — a key, a token, a .env or a service-account file — and once it is in this transcript it cannot be taken back.\n\n' +
+                'Read what you need from the application config instead, or say on the card which credential you need and why.',
+        };
+    }
+    // REVERSIBILITY is the line, not blast radius. A deploy reaches production and is meant to — it
+    // can be deployed again. A TRUNCATE reaches production and cannot be undone.
+    if (verdict.destructive >= REFUSE_AT && verdict.reversible < 0.5) {
+        cfg.log(`refused a ${verdict.blast} command (${Math.round(verdict.destructive * 100)}% destructive, no way back)`);
+        audit({ ...base, outcome: 'refused', why: 'irreversible', jev });
+        return {
+            allow: false,
+            reason: `This cannot be undone (${Math.round(verdict.destructive * 100)}% destructive, reaching ${verdict.blast}, no way back without a restore), so it was not run.\n\n` +
+                `If it genuinely needs doing, request it as a production run — a person approves that with the script in front of them — or say on the card what you need and why.`,
+        };
+    }
+    // Destructive but reversible: run it, and leave a line in the audit. Asking here is the rubber
+    // stamp — somebody out of touch with the work says yes to everything to get it moving.
+    if (verdict.destructive >= REFUSE_AT) {
+        cfg.log(`ran a ${verdict.blast} command that can be put back (${Math.round(verdict.reversible * 100)}% reversible)`);
+        audit({ ...base, outcome: 'ran', why: 'reversible', jev });
+        return { allow: true };
+    }
+    if (verdict.destructive >= ESCALATE_AT) {
+        cfg.log(`asking a person: ${command.slice(0, 60)} (${Math.round(verdict.destructive * 100)}% destructive, ${verdict.blast})`);
+        const decision = await cfg.decider({ toolName: 'Bash', input: { command } }, { signal: new AbortController().signal });
+        audit({ ...base, outcome: decision.allow ? 'asked-allowed' : 'asked-denied', jev });
+        return decision.allow ? { allow: true } : { allow: false, reason: `Not approved. ${decision.reason}` };
+    }
+    audit({ ...base, outcome: 'ran', jev });
+    return { allow: true };
+}
+export function jevGuard(cfg) {
+    return {
+        PreToolUse: [
+            {
+                matcher: 'Bash',
+                hooks: [
+                    async (input) => {
+                        const verdict = await judgeCommand(cfg, String(input?.tool_input?.command ?? ''));
+                        return verdict.allow ? { continue: true } : { decision: 'block', reason: verdict.reason };
+                    },
+                ],
+            },
+        ],
+    };
+}
+//# sourceMappingURL=jevguard.js.map

package/dist/jevguard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jevguard.js","sourceRoot":"","sources":["../src/jevguard.ts"],"names":[],"mappings":"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"}

package/dist/mailbox.d.ts

@@ -0,0 +1,22 @@
+import type { SDKUserMessage } from '@anthropic-ai/claude-agent-sdk';
+/**
+ * Everything the agent is told, in one queue: card events from FlareDeck and whatever you type.
+ *
+ * The SDK takes an async iterable as its prompt, so a session is not one question and one answer
+ * — it is a conversation the harness keeps feeding. That is what makes steering possible at all:
+ * a running turn can be given a new instruction rather than being interrupted and restarted.
+ */
+export declare class Mailbox {
+    private waiting;
+    private queued;
+    private closed;
+    /**
+     * `human` marks input that came from a person at the keyboard. It matters: the SDK treats an
+     * unstamped message as unattributed and fails closed at trust gates, and it SHOULD — a line you
+     * typed deserves more weight than a comment someone left on a card.
+     */
+    push(text: string, human?: boolean): void;
+    close(): void;
+    get pending(): number;
+    [Symbol.asyncIterator](): AsyncIterator<SDKUserMessage>;
+}

package/dist/mailbox.js

@@ -0,0 +1,51 @@
+/**
+ * Everything the agent is told, in one queue: card events from FlareDeck and whatever you type.
+ *
+ * The SDK takes an async iterable as its prompt, so a session is not one question and one answer
+ * — it is a conversation the harness keeps feeding. That is what makes steering possible at all:
+ * a running turn can be given a new instruction rather than being interrupted and restarted.
+ */
+export class Mailbox {
+    waiting = [];
+    queued = [];
+    closed = false;
+    /**
+     * `human` marks input that came from a person at the keyboard. It matters: the SDK treats an
+     * unstamped message as unattributed and fails closed at trust gates, and it SHOULD — a line you
+     * typed deserves more weight than a comment someone left on a card.
+     */
+    push(text, human = false) {
+        const message = {
+            type: 'user',
+            message: { role: 'user', content: text },
+            parent_tool_use_id: null,
+            ...(human ? { origin: { kind: 'human' }, priority: 'now' } : {}),
+        };
+        const next = this.waiting.shift();
+        if (next)
+            next({ value: message, done: false });
+        else
+            this.queued.push(message);
+    }
+    close() {
+        this.closed = true;
+        for (const w of this.waiting.splice(0))
+            w({ value: undefined, done: true });
+    }
+    get pending() {
+        return this.queued.length;
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => {
+                const queued = this.queued.shift();
+                if (queued)
+                    return Promise.resolve({ value: queued, done: false });
+                if (this.closed)
+                    return Promise.resolve({ value: undefined, done: true });
+                return new Promise((resolve) => this.waiting.push(resolve));
+            },
+        };
+    }
+}
+//# sourceMappingURL=mailbox.js.map

package/dist/mailbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mailbox.js","sourceRoot":"","sources":["../src/mailbox.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,OAAO,OAAO;IACV,OAAO,GAAoD,EAAE,CAAC;IAC9D,MAAM,GAAqB,EAAE,CAAC;IAC9B,MAAM,GAAG,KAAK,CAAC;IAEvB;;;;OAIG;IACH,IAAI,CAAC,IAAY,EAAE,KAAK,GAAG,KAAK;QAC9B,MAAM,OAAO,GAAmB;YAC9B,IAAI,EAAE,MAAM;YACZ,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE;YACxC,kBAAkB,EAAE,IAAI;YACxB,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,OAAgB,EAAE,EAAE,QAAQ,EAAE,KAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACnF,CAAC;QACF,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QAClC,IAAI,IAAI;YAAE,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;;YAC3C,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACjC,CAAC;IAED,KAAK;QACH,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;YAAE,CAAC,CAAC,EAAE,KAAK,EAAE,SAAkB,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IACvF,CAAC;IAED,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;IAC5B,CAAC;IAED,CAAC,MAAM,CAAC,aAAa,CAAC;QACpB,OAAO;YACL,IAAI,EAAE,GAAG,EAAE;gBACT,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;gBACnC,IAAI,MAAM;oBAAE,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;gBACnE,IAAI,IAAI,CAAC,MAAM;oBAAE,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,SAAkB,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;gBACnF,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;YAC9D,CAAC;SACF,CAAC;IACJ,CAAC;CACF"}

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import './env.js';