xcoder-jarvis-agent 0.0.0-stage → 1.4.0

package/dist/jarvis/tools/fs-tools.d.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import type { ToolDescriptor } from "./registry.js";
+export declare function isSecretPath(p: string): boolean;
+/** Convert a glob to a RegExp: `*`, `**`, `?`, `{a,b}` only. */
+export declare function globToRegExp(pattern: string): RegExp;
+declare const ReadFileArgs: z.ZodObject<{
+    path: z.ZodString;
+    maxBytes: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const readFileTool: ToolDescriptor<z.infer<typeof ReadFileArgs>>;
+declare const GlobArgs: z.ZodObject<{
+    pattern: z.ZodString;
+    maxResults: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const globTool: ToolDescriptor<z.infer<typeof GlobArgs>>;
+declare const GrepArgs: z.ZodObject<{
+    pattern: z.ZodString;
+    pathGlob: z.ZodOptional<z.ZodString>;
+    maxResults: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const grepTool: ToolDescriptor<z.infer<typeof GrepArgs>>;
+declare const SearchArgs: z.ZodObject<{
+    query: z.ZodString;
+    maxResults: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const searchWorkspaceTool: ToolDescriptor<z.infer<typeof SearchArgs>>;
+export declare const FS_TOOLS: readonly ToolDescriptor<any>[];
+export {};

package/dist/jarvis/tools/fs-tools.js

@@ -0,0 +1,292 @@
+// xcoder:version 1 | xcoder:task task-f1b5f6 | xcoder:updated 2026-11-05T02:46:50.359Z | xcoder:subtask code-st-53c7b5
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { byteLength, normalizeUntrusted, readBounded, redact, resolveInsideRoot, truncate, } from "../util/text.js";
+/**
+ * Read-only filesystem tools (design §2.6).
+ *
+ * Every one of these is confined to the workspace and bounded in both output
+ * size and result count. None of them can write, delete, spawn a process or
+ * reach the network — those capabilities simply do not exist in this module,
+ * so no prompt text can conjure them (PRM-04, LLM08).
+ */
+/** Paths whose contents must never enter the model context (PRM-03, LLM06). */
+const SECRET_PATH_PATTERNS = [
+    /(^|[\\/])\.env(\.[^.\\/]+)?$/i,
+    /(^|[\\/])\.npmrc$/i,
+    /(^|[\\/])\.netrc$/i,
+    /(^|[\\/])id_(rsa|dsa|ecdsa|ed25519)(\.pub)?$/i,
+    /(^|[\\/])[^\\/]*\.(pem|key|p12|pfx|jks)$/i,
+    /(^|[\\/])\.ssh([\\/]|$)/i,
+    /(^|[\\/])\.aws([\\/]|$)/i,
+    /(^|[\\/])\.docker[\\/]config\.json$/i,
+    /(^|[\\/])credentials(\.json)?$/i,
+];
+export function isSecretPath(p) {
+    return SECRET_PATH_PATTERNS.some((re) => re.test(p));
+}
+/** Directories never worth walking, and expensive if we did. */
+const SKIP_DIRS = new Set([
+    "node_modules",
+    ".git",
+    "dist",
+    "build",
+    "coverage",
+    ".next",
+    ".turbo",
+    ".venv",
+]);
+function aborted(ctx) {
+    if (ctx.signal?.aborted) {
+        return { ok: false, summary: "aborted by kill switch", bytes: 0, truncated: false };
+    }
+    return undefined;
+}
+/** Convert a glob to a RegExp: `*`, `**`, `?`, `{a,b}` only. */
+export function globToRegExp(pattern) {
+    let out = "";
+    let i = 0;
+    while (i < pattern.length) {
+        const ch = pattern[i];
+        if (ch === "*") {
+            if (pattern[i + 1] === "*") {
+                out += ".*";
+                i += 2;
+                if (pattern[i] === "/")
+                    i += 1;
+                continue;
+            }
+            out += "[^/]*";
+            i += 1;
+            continue;
+        }
+        if (ch === "?") {
+            out += "[^/]";
+            i += 1;
+            continue;
+        }
+        if (ch === "{") {
+            const close = pattern.indexOf("}", i);
+            if (close !== -1) {
+                const alts = pattern
+                    .slice(i + 1, close)
+                    .split(",")
+                    .map((a) => a.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+                out += `(?:${alts.join("|")})`;
+                i = close + 1;
+                continue;
+            }
+        }
+        out += ch.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        i += 1;
+    }
+    return new RegExp(`^${out}$`);
+}
+async function walk(root, maxFiles) {
+    const out = [];
+    const stack = [root];
+    while (stack.length > 0 && out.length < maxFiles) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = await fsp.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            if (out.length >= maxFiles)
+                break;
+            const full = path.join(dir, e.name);
+            if (e.isDirectory()) {
+                if (SKIP_DIRS.has(e.name))
+                    continue;
+                stack.push(full);
+            }
+            else if (e.isFile() && !isSecretPath(full)) {
+                out.push(full);
+            }
+        }
+    }
+    return out;
+}
+const ReadFileArgs = z.object({
+    path: z.string().min(1).max(1_000),
+    maxBytes: z.number().int().positive().max(1_048_576).optional(),
+});
+export const readFileTool = {
+    name: "read_file",
+    description: "Read a UTF-8 text file inside the workspace. Args: { path }. Secret-bearing paths (dotenv, keys, ssh, npmrc, credentials) are refused.",
+    risk: "read",
+    argsSchema: ReadFileArgs,
+    async execute(args, ctx) {
+        const stopped = aborted(ctx);
+        if (stopped)
+            return stopped;
+        if (isSecretPath(args.path)) {
+            return {
+                ok: false,
+                summary: `refused: ${args.path} is on the secret-path denylist`,
+                bytes: 0,
+                truncated: false,
+            };
+        }
+        const resolved = await resolveInsideRoot(ctx.workspaceRoot, args.path);
+        if (!resolved.ok) {
+            return { ok: false, summary: `refused: ${resolved.reason}`, bytes: 0, truncated: false };
+        }
+        if (isSecretPath(resolved.path)) {
+            return {
+                ok: false,
+                summary: "refused: resolved path is on the secret-path denylist",
+                bytes: 0,
+                truncated: false,
+            };
+        }
+        const cap = Math.min(args.maxBytes ?? ctx.limits.maxReadBytes, ctx.limits.maxReadBytes);
+        const read = await readBounded(resolved.path, cap);
+        if (!read.ok) {
+            return { ok: false, summary: `refused: ${read.reason}`, bytes: 0, truncated: false };
+        }
+        const cleaned = redact(normalizeUntrusted(read.text)).text;
+        const trimmed = truncate(cleaned, 20_000);
+        return {
+            ok: true,
+            summary: trimmed.text,
+            bytes: read.bytes,
+            truncated: read.truncated || trimmed.truncated,
+            data: { path: args.path, bytes: read.bytes },
+        };
+    },
+};
+const GlobArgs = z.object({
+    pattern: z.string().min(1).max(200),
+    maxResults: z.number().int().positive().max(200).optional(),
+});
+export const globTool = {
+    name: "glob",
+    description: "List workspace file paths matching a glob. Supports *, **, ? and {a,b} only. Args: { pattern, maxResults? }.",
+    risk: "read",
+    argsSchema: GlobArgs,
+    async execute(args, ctx) {
+        const stopped = aborted(ctx);
+        if (stopped)
+            return stopped;
+        const limit = Math.min(args.maxResults ?? 100, ctx.limits.maxResults);
+        const re = globToRegExp(args.pattern);
+        const files = await walk(ctx.workspaceRoot, 20_000);
+        const matches = [];
+        for (const f of files) {
+            const rel = path.relative(ctx.workspaceRoot, f).split(path.sep).join("/");
+            if (re.test(rel) || re.test(path.basename(rel))) {
+                matches.push(rel);
+                if (matches.length >= limit)
+                    break;
+            }
+        }
+        return {
+            ok: true,
+            summary: matches.length > 0 ? matches.join("\n") : "no files matched",
+            bytes: byteLength(matches.join("\n")),
+            truncated: matches.length >= limit,
+            data: { count: matches.length },
+        };
+    },
+};
+const GrepArgs = z.object({
+    pattern: z.string().min(1).max(200),
+    pathGlob: z.string().min(1).max(200).optional(),
+    maxResults: z.number().int().positive().max(500).optional(),
+});
+export const grepTool = {
+    name: "grep",
+    description: "Search workspace file contents for a regular expression. Binary files are skipped. Args: { pattern, pathGlob?, maxResults? }.",
+    risk: "read",
+    argsSchema: GrepArgs,
+    async execute(args, ctx) {
+        const stopped = aborted(ctx);
+        if (stopped)
+            return stopped;
+        let re;
+        try {
+            re = new RegExp(args.pattern, "i");
+        }
+        catch {
+            return { ok: false, summary: "refused: pattern is not a valid regex", bytes: 0, truncated: false };
+        }
+        const limit = Math.min(args.maxResults ?? 100, ctx.limits.maxResults);
+        const pathFilter = args.pathGlob ? globToRegExp(args.pathGlob) : undefined;
+        const files = await walk(ctx.workspaceRoot, 20_000);
+        const hits = [];
+        for (const file of files) {
+            if (ctx.signal?.aborted)
+                break;
+            if (hits.length >= limit)
+                break;
+            const rel = path.relative(ctx.workspaceRoot, file).split(path.sep).join("/");
+            if (pathFilter && !pathFilter.test(rel) && !pathFilter.test(path.basename(rel)))
+                continue;
+            const read = await readBounded(file, 256_000);
+            if (!read.ok)
+                continue;
+            if (read.text.includes("\u0000"))
+                continue; // binary
+            const lines = read.text.split(/\r?\n/);
+            for (let i = 0; i < lines.length; i += 1) {
+                if (!re.test(lines[i]))
+                    continue;
+                hits.push(`${rel}:${i + 1}: ${redact(lines[i]).text.slice(0, 300)}`);
+                if (hits.length >= limit)
+                    break;
+            }
+        }
+        return {
+            ok: true,
+            summary: hits.length > 0 ? hits.join("\n") : "no matches",
+            bytes: byteLength(hits.join("\n")),
+            truncated: hits.length >= limit,
+            data: { count: hits.length },
+        };
+    },
+};
+const SearchArgs = z.object({
+    query: z.string().min(1).max(200),
+    maxResults: z.number().int().positive().max(200).optional(),
+});
+export const searchWorkspaceTool = {
+    name: "search_workspace",
+    description: "Search workspace file PATHS for a substring (cheap path index lookup, not content). Args: { query, maxResults? }.",
+    risk: "read",
+    argsSchema: SearchArgs,
+    async execute(args, ctx) {
+        const stopped = aborted(ctx);
+        if (stopped)
+            return stopped;
+        const limit = Math.min(args.maxResults ?? 100, ctx.limits.maxResults);
+        const needle = args.query.toLowerCase();
+        const files = await walk(ctx.workspaceRoot, 20_000);
+        const matches = [];
+        for (const f of files) {
+            const rel = path.relative(ctx.workspaceRoot, f).split(path.sep).join("/");
+            if (rel.toLowerCase().includes(needle)) {
+                matches.push(rel);
+                if (matches.length >= limit)
+                    break;
+            }
+        }
+        return {
+            ok: true,
+            summary: matches.length > 0 ? matches.join("\n") : "no paths matched",
+            bytes: byteLength(matches.join("\n")),
+            truncated: matches.length >= limit,
+            data: { count: matches.length },
+        };
+    },
+};
+export const FS_TOOLS = [
+    readFileTool,
+    globTool,
+    grepTool,
+    searchWorkspaceTool,
+];

package/dist/jarvis/tools/memory-tools.d.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+import type { ToolDescriptor } from "./registry.js";
+/**
+ * Memory tools (design §2.6).
+ *
+ * `remember` is the only tool that mutates persistent state, so it is the one
+ * that respects the confirmation seam. It is also the only path by which the
+ * agent can carry something across sessions, and the value is redacted before
+ * it is written — so a key glimpsed in a file cannot be memorised verbatim.
+ */
+declare const RememberArgs: z.ZodObject<{
+    value: z.ZodString;
+    kind: z.ZodDefault<z.ZodEnum<{
+        fact: "fact";
+        preference: "preference";
+        task: "task";
+        observation: "observation";
+    }>>;
+    key: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const rememberTool: ToolDescriptor<z.infer<typeof RememberArgs>>;
+declare const RecallArgs: z.ZodObject<{
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const recallTool: ToolDescriptor<z.infer<typeof RecallArgs>>;
+export declare const MEMORY_TOOLS: readonly ToolDescriptor<any>[];
+export {};

package/dist/jarvis/tools/memory-tools.js

@@ -0,0 +1,83 @@
+// xcoder:version 1 | xcoder:task task-f1b5f6 | xcoder:updated 2026-11-05T02:46:55.784Z | xcoder:subtask code-st-53c7b5
+import { z } from "zod";
+import { requireConfirmation } from "../util/confirm.js";
+import { byteLength, truncate } from "../util/text.js";
+/**
+ * Memory tools (design §2.6).
+ *
+ * `remember` is the only tool that mutates persistent state, so it is the one
+ * that respects the confirmation seam. It is also the only path by which the
+ * agent can carry something across sessions, and the value is redacted before
+ * it is written — so a key glimpsed in a file cannot be memorised verbatim.
+ */
+const RememberArgs = z.object({
+    value: z.string().min(1).max(2_000),
+    kind: z.enum(["fact", "preference", "task", "observation"]).default("fact"),
+    key: z.string().min(1).max(128).optional(),
+});
+export const rememberTool = {
+    name: "remember",
+    description: "Save one short durable note for future sessions. Args: { value, kind?, key? }. Secrets are redacted before storage.",
+    risk: "write",
+    argsSchema: RememberArgs,
+    async execute(args, ctx) {
+        if (ctx.signal?.aborted) {
+            return { ok: false, summary: "aborted by kill switch", bytes: 0, truncated: false };
+        }
+        const allowed = await requireConfirmation(ctx.confirm, {
+            tool: "remember",
+            risk: "write",
+            summary: `${args.kind}: ${args.value.slice(0, 120)}`,
+        });
+        if (!allowed) {
+            return { ok: false, summary: "refused: memory write was not confirmed", bytes: 0, truncated: false };
+        }
+        const entry = await ctx.memory.append({
+            session: ctx.session,
+            kind: args.kind,
+            ...(args.key ? { key: args.key } : {}),
+            value: args.value,
+            source: "agent",
+        });
+        const preview = truncate(entry.value, 200).text;
+        return {
+            ok: true,
+            summary: `remembered ${args.kind}${args.key ? ` '${args.key}'` : ""}: ${preview}`,
+            bytes: byteLength(entry.value),
+            truncated: false,
+            data: { id: entry.id, kind: entry.kind, key: entry.key },
+        };
+    },
+};
+const RecallArgs = z.object({
+    limit: z.number().int().positive().max(100).optional(),
+});
+export const recallTool = {
+    name: "recall",
+    description: "Read back recent memory entries for this user and workspace. Args: { limit? }.",
+    risk: "read",
+    argsSchema: RecallArgs,
+    async execute(args, ctx) {
+        if (ctx.signal?.aborted) {
+            return { ok: false, summary: "aborted by kill switch", bytes: 0, truncated: false };
+        }
+        const limit = Math.min(args.limit ?? 20, ctx.limits.maxResults);
+        const entries = await ctx.memory.window(limit);
+        if (entries.length === 0) {
+            return { ok: true, summary: "no memory entries in scope", bytes: 0, truncated: false };
+        }
+        const lines = entries.map((e) => {
+            const key = e.key ? ` key=${e.key}` : "";
+            return `- ${e.ts} [${e.kind}${key}] ${truncate(e.value, 300).text}`;
+        });
+        const summary = lines.join("\n");
+        return {
+            ok: true,
+            summary,
+            bytes: byteLength(summary),
+            truncated: false,
+            data: { count: entries.length },
+        };
+    },
+};
+export const MEMORY_TOOLS = [rememberTool, recallTool];

package/dist/jarvis/tools/registry.d.ts

@@ -0,0 +1,54 @@
+import type { z } from "zod";
+import type { MemoryStore } from "../memory/store.js";
+import type { ConfirmFn, ToolRisk } from "../util/confirm.js";
+export type { ToolRisk, ConfirmFn };
+export interface ToolObservation {
+    ok: boolean;
+    summary: string;
+    data?: unknown;
+    bytes: number;
+    truncated: boolean;
+}
+export interface ToolLimits {
+    maxReadBytes: number;
+    maxResults: number;
+}
+export interface ToolContext {
+    workspaceRoot: string;
+    memory: MemoryStore;
+    session: string;
+    signal?: AbortSignal;
+    confirm: ConfirmFn;
+    limits: ToolLimits;
+}
+export interface ToolDescriptor<A = unknown> {
+    name: string;
+    description: string;
+    risk: ToolRisk;
+    argsSchema: z.ZodType<A>;
+    execute(args: A, ctx: ToolContext): Promise<ToolObservation>;
+}
+export interface ToolRegistry {
+    get(name: string): ToolDescriptor | undefined;
+    allowlist(): readonly string[];
+    describeForPrompt(): string;
+}
+export declare const DEFAULT_LIMITS: ToolLimits;
+/**
+ * Pass-1 allowlist. Six narrow, side-effect-free tools (PRM-04, design §2.6).
+ *
+ * Deliberately absent: shell/exec, file write or delete, network fetch, git
+ * push, SQL. There is no open-ended 'run any command' surface to smuggle a
+ * model instruction into, and no irreversible tool exists in this build.
+ */
+export declare const ALLOWED_TOOLS: readonly ["read_file", "glob", "grep", "search_workspace", "remember", "recall"];
+export type AllowedToolName = (typeof ALLOWED_TOOLS)[number];
+/**
+ * Static registry. The allowlist is enforced here, in code, not by prose in
+ * the prompt (PRM-09): `get()` returns undefined for any name not both
+ * registered and allowed, and the loop refuses rather than dispatching.
+ */
+export declare function createToolRegistry(o?: {
+    tools?: readonly ToolDescriptor<any>[];
+    allow?: readonly string[];
+}): ToolRegistry;

package/dist/jarvis/tools/registry.js

@@ -0,0 +1,49 @@
+export const DEFAULT_LIMITS = {
+    maxReadBytes: 262_144,
+    maxResults: 200,
+};
+/**
+ * Pass-1 allowlist. Six narrow, side-effect-free tools (PRM-04, design §2.6).
+ *
+ * Deliberately absent: shell/exec, file write or delete, network fetch, git
+ * push, SQL. There is no open-ended 'run any command' surface to smuggle a
+ * model instruction into, and no irreversible tool exists in this build.
+ */
+export const ALLOWED_TOOLS = [
+    "read_file",
+    "glob",
+    "grep",
+    "search_workspace",
+    "remember",
+    "recall",
+];
+/**
+ * Static registry. The allowlist is enforced here, in code, not by prose in
+ * the prompt (PRM-09): `get()` returns undefined for any name not both
+ * registered and allowed, and the loop refuses rather than dispatching.
+ */
+export function createToolRegistry(o = {}) {
+    const registered = new Map();
+    for (const t of o.tools ?? [])
+        registered.set(t.name, t);
+    const allowSet = new Set((o.allow && o.allow.length > 0 ? o.allow : ALLOWED_TOOLS).filter((n) => registered.has(n)));
+    return {
+        get(name) {
+            if (!allowSet.has(name))
+                return undefined;
+            return registered.get(name);
+        },
+        allowlist() {
+            return [...allowSet].sort();
+        },
+        describeForPrompt() {
+            return [...allowSet]
+                .sort()
+                .map((name) => {
+                const t = registered.get(name);
+                return t ? `- ${t.name}: ${t.description}` : `- ${name}`;
+            })
+                .join("\n");
+        },
+    };
+}

package/dist/jarvis/util/confirm.d.ts

@@ -0,0 +1,28 @@
+export type ToolRisk = "read" | "write" | "irreversible";
+export interface ConfirmRequest {
+    tool: string;
+    risk: ToolRisk;
+    summary: string;
+}
+export type ConfirmFn = (r: ConfirmRequest) => Promise<boolean>;
+/**
+ * Human-in-the-loop gate for high-impact actions (AI-03).
+ *
+ * Fails closed: when stdin is not a TTY (CI, piped input, an agent harness)
+ * there is nobody to ask, so the answer is `deny`. Pass-1 tools are all
+ * `read` or `write` and never reach this path; it exists so that adding an
+ * `irreversible` tool later cannot silently skip confirmation.
+ */
+export declare const denyWhenNotTty: ConfirmFn;
+export declare const alwaysDeny: ConfirmFn;
+export declare function createConfirm(opts?: {
+    stdin?: NodeJS.ReadableStream & {
+        isTTY?: boolean;
+    };
+    stdout?: NodeJS.WritableStream;
+}): ConfirmFn;
+/**
+ * Enforce the gate. Read/write tools with no confirmation callback still
+ * proceed only for `read`; anything above `read` requires an explicit allow.
+ */
+export declare function requireConfirmation(confirm: ConfirmFn, req: ConfirmRequest): Promise<boolean>;

package/dist/jarvis/util/confirm.js

@@ -0,0 +1,54 @@
+// xcoder:version 1 | xcoder:task task-f1b5f6 | xcoder:updated 2026-11-05T02:44:35.687Z | xcoder:subtask code-st-53c7b5
+import readline from "node:readline/promises";
+/**
+ * Human-in-the-loop gate for high-impact actions (AI-03).
+ *
+ * Fails closed: when stdin is not a TTY (CI, piped input, an agent harness)
+ * there is nobody to ask, so the answer is `deny`. Pass-1 tools are all
+ * `read` or `write` and never reach this path; it exists so that adding an
+ * `irreversible` tool later cannot silently skip confirmation.
+ */
+export const denyWhenNotTty = async () => false;
+export const alwaysDeny = async () => false;
+const RISK_LABEL = {
+    read: "reads data",
+    write: "modifies local state",
+    irreversible: "CANNOT BE UNDONE",
+};
+export function createConfirm(opts = {}) {
+    const stdin = opts.stdin ?? process.stdin;
+    const stdout = opts.stdout ?? process.stderr;
+    if (!stdin.isTTY)
+        return denyWhenNotTty;
+    return async (req) => {
+        const summary = req.summary.slice(0, 200).replace(/\s+/g, " ");
+        const rl = readline.createInterface({
+            input: stdin,
+            output: stdout,
+        });
+        try {
+            const answer = await rl.question(`jarvis: allow tool "${req.tool}" (${RISK_LABEL[req.risk]})? ${summary} [y/N] `);
+            return /^y(es)?$/i.test(answer.trim());
+        }
+        catch {
+            return false;
+        }
+        finally {
+            rl.close();
+        }
+    };
+}
+/**
+ * Enforce the gate. Read/write tools with no confirmation callback still
+ * proceed only for `read`; anything above `read` requires an explicit allow.
+ */
+export async function requireConfirmation(confirm, req) {
+    if (req.risk === "read")
+        return true;
+    try {
+        return await confirm(req);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/jarvis/util/kill.d.ts

@@ -0,0 +1,10 @@
+export interface KillState {
+    killed: boolean;
+    /** Which signal tripped, for provenance. Never contains file contents. */
+    reason?: "env" | "stop-file";
+}
+export declare function stopFilePath(workspaceRoot: string): string;
+/** Never throws: an unreadable STOP path is treated as "not killed". */
+export declare function readKillState(workspaceRoot: string): KillState;
+/** Convenience predicate for `ReactLoopInput.isKilled`. */
+export declare function createKillProbe(workspaceRoot: string): () => boolean;

package/dist/jarvis/util/kill.js

@@ -0,0 +1,39 @@
+// xcoder:version 1 | xcoder:task task-f1b5f6 | xcoder:updated 2026-11-05T02:44:31.387Z | xcoder:subtask code-st-53c7b5
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * Kill switch, fail-closed (design §4.3, AI-09).
+ *
+ * Jarvis aborts when either signal is present:
+ *  - `XCODER_JARVIS_KILL` is a truthy env value, or
+ *  - the workspace holds `.xcoder/jarvis/STOP`.
+ *
+ * The check runs before every LLM call, every tool dispatch and every memory
+ * write, so an operator can stop a runaway run without killing the process.
+ * It reads the filesystem on each call on purpose: the STOP file must take
+ * effect mid-run, which a value cached at startup could not do.
+ */
+const TRUTHY = new Set(["1", "true", "yes", "on"]);
+export function stopFilePath(workspaceRoot) {
+    return path.join(workspaceRoot, ".xcoder", "jarvis", "STOP");
+}
+/** Never throws: an unreadable STOP path is treated as "not killed". */
+export function readKillState(workspaceRoot) {
+    const env = process.env["XCODER_JARVIS_KILL"];
+    if (env && TRUTHY.has(env.trim().toLowerCase())) {
+        return { killed: true, reason: "env" };
+    }
+    try {
+        if (fs.existsSync(stopFilePath(workspaceRoot))) {
+            return { killed: true, reason: "stop-file" };
+        }
+    }
+    catch {
+        // An environment we cannot inspect must not be reported as a tripped switch.
+    }
+    return { killed: false };
+}
+/** Convenience predicate for `ReactLoopInput.isKilled`. */
+export function createKillProbe(workspaceRoot) {
+    return () => readKillState(workspaceRoot).killed;
+}