xcoder-jarvis-agent 0.0.0-stage → 1.3.0

package/dist/jarvis/chat/session.js

@@ -0,0 +1,122 @@
+// xcoder:version 2 | xcoder:task task-482677 | xcoder:updated 2026-11-05T03:48:55.859Z | xcoder:subtask code-st-729fd8
+import { EXIT, runJarvisAgent } from "../agent.js";
+import { readKillState } from "../util/kill.js";
+import { createChatConfirm } from "./confirm.js";
+import { createStdinLineSource } from "./lines.js";
+import { CHAT_DIRECTIVE } from "./prompt.js";
+import { isIgnorable, isTerminator } from "./terminator.js";
+/**
+ * Build a per-turn argv from the already-validated request. It is re-parsed by
+ * `runJarvisAgent`, so every turn passes through the same single validation
+ * gate instead of a second, divergent parser.
+ */
+export function turnArgv(request, session, text) {
+    const argv = [];
+    for (const skill of request.skills) {
+        argv.push("--skill", skill);
+    }
+    argv.push("--max-iterations", String(request.maxIterations));
+    argv.push("--session", session);
+    if (request.user !== undefined)
+        argv.push("--user", request.user);
+    if (!request.memory)
+        argv.push("--no-memory");
+    if (request.json)
+        argv.push("--json");
+    // `--` keeps a message that happens to start with `--` a positional word.
+    argv.push("--", text);
+    return argv;
+}
+export async function runChatSession(request, deps = {}) {
+    const stderr = deps.stderr ?? process.stderr;
+    const workspaceRoot = deps.workspaceRoot ?? process.cwd();
+    const result = await driveChat(request, deps, workspaceRoot, stderr);
+    return result.exitCode;
+}
+export async function runChatSessionDetailed(request, deps = {}) {
+    const stderr = deps.stderr ?? process.stderr;
+    const workspaceRoot = deps.workspaceRoot ?? process.cwd();
+    return await driveChat(request, deps, workspaceRoot, stderr);
+}
+async function driveChat(request, deps, workspaceRoot, stderr) {
+    // A stable session label is what makes the turns one conversation.
+    const session = request.session ?? `jarvis-chat-${Date.now().toString(36)}`;
+    const lines = deps.lines ?? createStdinLineSource({ stdin: deps.stdin });
+    const isInteractive = deps.isInteractive ?? Boolean((deps.stdin ?? process.stdin).isTTY);
+    const chatConfirm = createChatConfirm({ lines, stdout: stderr, isInteractive });
+    const turnDeps = {
+        ...deps,
+        stderr,
+        // Only this gate answers confirmation prompts in chat, so the agent's own
+        // readline-based createConfirm is unreachable here (AC20).
+        confirm: deps.confirm ?? chatConfirm,
+        // Marks the turn: constant trusted directive + user line appended to
+        // memory before the run (T4/AC15).
+        chatTurn: true,
+    };
+    let turns = 0;
+    if (!request.json) {
+        // --json must stay machine-readable, so the banner is never on stdout.
+        tryWrite(stderr, `jarvis: chat session ${session} - type exit, quit or bye to leave\n`);
+    }
+    try {
+        for (;;) {
+            // Kill switch at each turn boundary (K7/AC18/AC19).
+            if (readKillState(workspaceRoot).killed) {
+                tryWrite(stderr, "jarvis: aborted - kill switch tripped\n");
+                return { exitCode: EXIT.aborted, stopReason: "killed", turns };
+            }
+            // A terminator typed at a confirmation prompt denies that tool and ends
+            // the session here, at a turn boundary, not mid-turn (T5).
+            if (chatConfirm.pendingExit) {
+                return { exitCode: EXIT.answered, stopReason: "terminator", turns };
+            }
+            if (turns >= request.maxTurns) {
+                tryWrite(stderr, `jarvis: --max-turns ${request.maxTurns} reached\n`);
+                return { exitCode: EXIT.budget_exceeded, stopReason: "max_turns", turns };
+            }
+            const next = await lines.next();
+            if (next.kind === "eof") {
+                return { exitCode: EXIT.answered, stopReason: "eof", turns };
+            }
+            if (next.kind === "too_long") {
+                // Rejected before the model sees it. Only the size is echoed: the line
+                // itself may contain anything and must not be mirrored into a log.
+                tryWrite(stderr, `jarvis: message rejected - ${next.bytes} bytes exceeds the limit\n`);
+                continue;
+            }
+            if (isIgnorable(next.text))
+                continue;
+            if (isTerminator(next.text)) {
+                return { exitCode: EXIT.answered, stopReason: "terminator", turns };
+            }
+            const code = await runJarvisAgent(turnArgv(request, session, next.text), turnDeps);
+            turns += 1;
+            if (code === EXIT.aborted) {
+                return { exitCode: EXIT.aborted, stopReason: "killed", turns };
+            }
+            if (chatConfirm.pendingExit) {
+                return { exitCode: EXIT.answered, stopReason: "terminator", turns };
+            }
+        }
+    }
+    finally {
+        // Idempotent by contract, and it must run on every exit path.
+        try {
+            await lines.close();
+        }
+        catch {
+            /* closing twice is not an error */
+        }
+    }
+}
+function tryWrite(stream, text) {
+    try {
+        stream.write(text);
+    }
+    catch {
+        /* a closed stream must not fail the session */
+    }
+}
+/** Re-exported so a prompt test can pin the constant directive (AC15). */
+export { CHAT_DIRECTIVE };

package/dist/jarvis/chat/terminator.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Loop-terminator predicates for `jarvis --chat` (design K8, AC7/AC8).
+ *
+ * The match is WHOLE-LINE, trimmed and case-insensitive on purpose. A
+ * substring test would make "exit now" or "how do I quit a program?" end the
+ * session, which is exactly the surprising behaviour the design forbids: only
+ * a line that is nothing but a terminator stops the loop.
+ */
+export declare const TERMINATORS: readonly ["exit", "quit", "bye"];
+export type TerminatorWord = (typeof TERMINATORS)[number];
+/** True only when the whole line, trimmed and lowercased, is a terminator. */
+export declare function isTerminator(line: string): boolean;
+/** True for an empty or all-whitespace line, which must be fully inert. */
+export declare function isIgnorable(line: string): boolean;

package/dist/jarvis/chat/terminator.js

@@ -0,0 +1,19 @@
+// xcoder:version 1 | xcoder:task task-482677 | xcoder:updated 2026-11-05T03:46:06.874Z | xcoder:subtask code-st-729fd8
+/**
+ * Loop-terminator predicates for `jarvis --chat` (design K8, AC7/AC8).
+ *
+ * The match is WHOLE-LINE, trimmed and case-insensitive on purpose. A
+ * substring test would make "exit now" or "how do I quit a program?" end the
+ * session, which is exactly the surprising behaviour the design forbids: only
+ * a line that is nothing but a terminator stops the loop.
+ */
+export const TERMINATORS = ["exit", "quit", "bye"];
+const TERMINATOR_SET = new Set(TERMINATORS);
+/** True only when the whole line, trimmed and lowercased, is a terminator. */
+export function isTerminator(line) {
+    return TERMINATOR_SET.has(line.trim().toLowerCase());
+}
+/** True for an empty or all-whitespace line, which must be fully inert. */
+export function isIgnorable(line) {
+    return line.trim().length === 0;
+}

package/dist/jarvis/decision.d.ts

@@ -0,0 +1,64 @@
+import { z } from "zod";
+/**
+ * The model's reply, parsed into a typed decision (PRM-07, PRM-08, LLM02).
+ *
+ * Nothing downstream ever sees raw model text: a reply becomes a
+ * `ReactDecision` or it becomes an error. That is what keeps a hostile or
+ * merely sloppy completion out of shells, SQL, eval, HTML and file paths —
+ * the only reachable destination for model output is a typed descriptor
+ * lookup plus that tool's own args schema.
+ */
+export declare const MAX_THOUGHT = 4000;
+export declare const MAX_ANSWER = 20000;
+export declare const MAX_ARGS = 12;
+export declare const MAX_RAW = 100000;
+/** Tool names: lowercase, 3-40 chars — a closed, unremarkable namespace. */
+export declare const TOOL_NAME_RE: RegExp;
+export declare const FinalDecision: z.ZodObject<{
+    kind: z.ZodLiteral<"final">;
+    thought: z.ZodString;
+    answer: z.ZodString;
+}, z.core.$strip>;
+export declare const ActionDecision: z.ZodObject<{
+    kind: z.ZodLiteral<"action">;
+    thought: z.ZodString;
+    tool: z.ZodString;
+    args: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+export declare const ReactDecision: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"final">;
+    thought: z.ZodString;
+    answer: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"action">;
+    thought: z.ZodString;
+    tool: z.ZodString;
+    args: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>], "kind">;
+export type ReactDecision = z.infer<typeof ReactDecision>;
+export type FinalDecision = z.infer<typeof FinalDecision>;
+export type ActionDecision = z.infer<typeof ActionDecision>;
+export declare class ReactParseError extends Error {
+    readonly stage: "extract" | "json" | "schema";
+    readonly detail?: string | undefined;
+    constructor(message: string, stage: "extract" | "json" | "schema", detail?: string | undefined);
+}
+/**
+ * Find the first balanced `{...}` region, ignoring braces inside JSON strings.
+ *
+ * Models wrap JSON in prose or fences routinely, so we cannot require the
+ * reply to be pure JSON. We also cannot use a greedy regex: `{...}{...}`
+ * would swallow both objects. Returns undefined when no balanced region
+ * exists.
+ */
+export declare function extractJsonObject(raw: string): string | undefined;
+/**
+ * Parse a model reply into a decision. Throws `ReactParseError`.
+ *
+ * Three distinct failure stages are reported so the corrective nudge can be
+ * specific ("that was not JSON" vs "that JSON was the wrong shape") without
+ * ever echoing the model's own text back into the prompt as an instruction.
+ */
+export declare function parseDecision(raw: string): ReactDecision;
+/** True when `name` is a syntactically legal tool name. */
+export declare function isValidToolName(name: string): boolean;

package/dist/jarvis/decision.js

@@ -0,0 +1,116 @@
+// xcoder:version 1 | xcoder:task task-f1b5f6 | xcoder:updated 2026-11-05T02:45:07.079Z | xcoder:subtask code-st-53c7b5
+import { z } from "zod";
+/**
+ * The model's reply, parsed into a typed decision (PRM-07, PRM-08, LLM02).
+ *
+ * Nothing downstream ever sees raw model text: a reply becomes a
+ * `ReactDecision` or it becomes an error. That is what keeps a hostile or
+ * merely sloppy completion out of shells, SQL, eval, HTML and file paths —
+ * the only reachable destination for model output is a typed descriptor
+ * lookup plus that tool's own args schema.
+ */
+export const MAX_THOUGHT = 4_000;
+export const MAX_ANSWER = 20_000;
+export const MAX_ARGS = 12;
+export const MAX_RAW = 100_000;
+/** Tool names: lowercase, 3-40 chars — a closed, unremarkable namespace. */
+export const TOOL_NAME_RE = /^[a-z][a-z0-9_]{2,39}$/;
+export const FinalDecision = z.object({
+    kind: z.literal("final"),
+    thought: z.string().max(MAX_THOUGHT),
+    answer: z.string().min(1).max(MAX_ANSWER),
+});
+export const ActionDecision = z.object({
+    kind: z.literal("action"),
+    thought: z.string().max(MAX_THOUGHT),
+    tool: z.string().regex(TOOL_NAME_RE),
+    args: z.record(z.string(), z.unknown()).refine((r) => Object.keys(r).length <= MAX_ARGS, {
+        message: `args must have at most ${MAX_ARGS} keys`,
+    }),
+});
+export const ReactDecision = z.discriminatedUnion("kind", [FinalDecision, ActionDecision]);
+export class ReactParseError extends Error {
+    stage;
+    detail;
+    constructor(message, stage, detail) {
+        super(message);
+        this.stage = stage;
+        this.detail = detail;
+        this.name = "ReactParseError";
+    }
+}
+/**
+ * Find the first balanced `{...}` region, ignoring braces inside JSON strings.
+ *
+ * Models wrap JSON in prose or fences routinely, so we cannot require the
+ * reply to be pure JSON. We also cannot use a greedy regex: `{...}{...}`
+ * would swallow both objects. Returns undefined when no balanced region
+ * exists.
+ */
+export function extractJsonObject(raw) {
+    const text = raw.length > MAX_RAW ? raw.slice(0, MAX_RAW) : raw;
+    const start = text.indexOf("{");
+    if (start === -1)
+        return undefined;
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let i = start; i < text.length; i += 1) {
+        const ch = text[i];
+        if (inString) {
+            if (escaped)
+                escaped = false;
+            else if (ch === "\\")
+                escaped = true;
+            else if (ch === '"')
+                inString = false;
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            continue;
+        }
+        if (ch === "{")
+            depth += 1;
+        else if (ch === "}") {
+            depth -= 1;
+            if (depth === 0)
+                return text.slice(start, i + 1);
+        }
+    }
+    return undefined;
+}
+/**
+ * Parse a model reply into a decision. Throws `ReactParseError`.
+ *
+ * Three distinct failure stages are reported so the corrective nudge can be
+ * specific ("that was not JSON" vs "that JSON was the wrong shape") without
+ * ever echoing the model's own text back into the prompt as an instruction.
+ */
+export function parseDecision(raw) {
+    if (typeof raw !== "string" || raw.trim().length === 0) {
+        throw new ReactParseError("empty reply", "extract");
+    }
+    const objectText = extractJsonObject(raw);
+    if (!objectText) {
+        throw new ReactParseError("no JSON object found in reply", "extract");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(objectText);
+    }
+    catch (err) {
+        throw new ReactParseError("reply contained invalid JSON", "json", err instanceof Error ? err.message.slice(0, 200) : undefined);
+    }
+    const result = ReactDecision.safeParse(parsed);
+    if (!result.success) {
+        const first = result.error.issues[0];
+        const where = first?.path.join(".") || "(root)";
+        throw new ReactParseError(`reply did not match the decision schema at ${where}`, "schema", first?.message.slice(0, 200));
+    }
+    return result.data;
+}
+/** True when `name` is a syntactically legal tool name. */
+export function isValidToolName(name) {
+    return TOOL_NAME_RE.test(name);
+}

package/dist/jarvis/memory/store.d.ts

@@ -0,0 +1,88 @@
+export interface MemoryScope {
+    /** sha256(realpath(workspace)).slice(0,16) — stable across runs. */
+    workspaceId: string;
+    /** Sanitised label from --user, or the OS user. A label, not an identity. */
+    userId: string;
+}
+export type MemoryKind = "fact" | "preference" | "task" | "observation";
+export type MemorySource = "user" | "agent" | "tool";
+export interface MemoryEntry {
+    v: 1;
+    id: string;
+    ts: string;
+    session: string;
+    scope: MemoryScope;
+    kind: MemoryKind;
+    key?: string;
+    value: string;
+    source: MemorySource;
+    bytes: number;
+}
+export interface AppendInput {
+    session: string;
+    kind: MemoryKind;
+    key?: string;
+    value: string;
+    source: MemorySource;
+}
+export interface MemoryStoreOptions {
+    rootDir: string;
+    scope: MemoryScope;
+    maxEntries?: number;
+    maxBytes?: number;
+    windowEntries?: number;
+    now?: () => Date;
+}
+export declare const DEFAULT_MAX_ENTRIES = 500;
+export declare const DEFAULT_MAX_BYTES = 1048576;
+export declare const DEFAULT_WINDOW_ENTRIES = 20;
+export declare const MAX_VALUE_CHARS = 2000;
+/** Build a workspace scope id from an absolute, already-resolved path. */
+export declare function workspaceScopeId(realWorkspacePath: string): string;
+export declare function resolveUserId(raw: string | undefined): string;
+/**
+ * File-backed, scoped, capped, redacted conversational memory (design §2.9).
+ *
+ * Three deliberate properties:
+ *  - Append-only JSONL. A crash can only tear the final line, and a torn line
+ *    is dropped on read rather than throwing, so memory never blocks startup.
+ *  - Redaction happens at WRITE time. A secret that reaches memory is scrubbed
+ *    before it ever lands on disk, so later reads cannot leak it either.
+ *  - Compaction is deterministic and never calls a model. Model output written
+ *    back into memory would let one injection persist across sessions, and it
+ *    would make compaction impossible to test.
+ */
+export declare class MemoryStore {
+    private readonly rootDir;
+    private readonly scope;
+    private readonly maxEntries;
+    private readonly maxBytes;
+    private readonly windowEntries;
+    private readonly now;
+    /** Redaction hits accumulated by this instance, reported in provenance. */
+    private redactionCount;
+    constructor(o: MemoryStoreOptions);
+    /** workspace/.xcoder/jarvis/memory/[workspaceId]/[userId].jsonl */
+    path(): string;
+    get scopeValue(): MemoryScope;
+    redactions(): number;
+    /** Tolerates a torn final line and any line that is not a valid entry. */
+    load(): Promise<MemoryEntry[]>;
+    append(input: AppendInput): Promise<MemoryEntry>;
+    /** Newest `n` entries, oldest-first for prompt readability. */
+    window(n?: number): Promise<MemoryEntry[]>;
+    /**
+     * Deterministic compaction: keep the newest entry per key (pinned), then
+     * fill remaining capacity newest-first. Identical input yields identical
+     * output, which is what makes it testable.
+     */
+    compactEntries(entries: readonly MemoryEntry[]): MemoryEntry[];
+    compact(): Promise<{
+        before: number;
+        after: number;
+    }>;
+    summary(): Promise<string>;
+    clear(): Promise<void>;
+    private appendLine;
+    private writeAll;
+}

package/dist/jarvis/memory/store.js

@@ -0,0 +1,189 @@
+// xcoder:version 1 | xcoder:task task-f1b5f6 | xcoder:updated 2026-11-05T02:46:33.019Z | xcoder:subtask code-st-53c7b5
+import crypto from "node:crypto";
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { redact, sanitizeLabel, shortHash, writeAtomic } from "../util/text.js";
+export const DEFAULT_MAX_ENTRIES = 500;
+export const DEFAULT_MAX_BYTES = 1_048_576;
+export const DEFAULT_WINDOW_ENTRIES = 20;
+export const MAX_VALUE_CHARS = 2_000;
+/** Build a workspace scope id from an absolute, already-resolved path. */
+export function workspaceScopeId(realWorkspacePath) {
+    return shortHash(realWorkspacePath, 16);
+}
+export function resolveUserId(raw) {
+    const candidate = raw?.trim() || process.env["USERNAME"] || process.env["USER"] || "unknown";
+    return sanitizeLabel(candidate, "unknown");
+}
+function isValidEntry(v) {
+    if (typeof v !== "object" || v === null)
+        return false;
+    const e = v;
+    return (e.v === 1 &&
+        typeof e.id === "string" &&
+        typeof e.ts === "string" &&
+        typeof e.session === "string" &&
+        typeof e.value === "string" &&
+        typeof e.kind === "string" &&
+        typeof e.source === "string" &&
+        typeof e.scope === "object" &&
+        e.scope !== null);
+}
+/**
+ * File-backed, scoped, capped, redacted conversational memory (design §2.9).
+ *
+ * Three deliberate properties:
+ *  - Append-only JSONL. A crash can only tear the final line, and a torn line
+ *    is dropped on read rather than throwing, so memory never blocks startup.
+ *  - Redaction happens at WRITE time. A secret that reaches memory is scrubbed
+ *    before it ever lands on disk, so later reads cannot leak it either.
+ *  - Compaction is deterministic and never calls a model. Model output written
+ *    back into memory would let one injection persist across sessions, and it
+ *    would make compaction impossible to test.
+ */
+export class MemoryStore {
+    rootDir;
+    scope;
+    maxEntries;
+    maxBytes;
+    windowEntries;
+    now;
+    /** Redaction hits accumulated by this instance, reported in provenance. */
+    redactionCount = 0;
+    constructor(o) {
+        this.rootDir = o.rootDir;
+        this.scope = o.scope;
+        this.maxEntries = o.maxEntries ?? DEFAULT_MAX_ENTRIES;
+        this.maxBytes = o.maxBytes ?? DEFAULT_MAX_BYTES;
+        this.windowEntries = o.windowEntries ?? DEFAULT_WINDOW_ENTRIES;
+        this.now = o.now ?? (() => new Date());
+    }
+    /** workspace/.xcoder/jarvis/memory/[workspaceId]/[userId].jsonl */
+    path() {
+        return path.join(this.rootDir, this.scope.workspaceId, `${this.scope.userId}.jsonl`);
+    }
+    get scopeValue() {
+        return this.scope;
+    }
+    redactions() {
+        return this.redactionCount;
+    }
+    /** Tolerates a torn final line and any line that is not a valid entry. */
+    async load() {
+        let raw;
+        try {
+            raw = await fsp.readFile(this.path(), "utf8");
+        }
+        catch {
+            return [];
+        }
+        const out = [];
+        for (const line of raw.split(/\r?\n/)) {
+            const trimmed = line.trim();
+            if (trimmed.length === 0)
+                continue;
+            try {
+                const parsed = JSON.parse(trimmed);
+                if (isValidEntry(parsed))
+                    out.push(parsed);
+            }
+            catch {
+                // A torn tail (process killed mid-append) is expected; skip it.
+            }
+        }
+        return out;
+    }
+    async append(input) {
+        const { text, hits } = redact(input.value.slice(0, MAX_VALUE_CHARS));
+        this.redactionCount += hits;
+        const entry = {
+            v: 1,
+            id: `mem-${crypto.randomBytes(4).toString("hex")}`,
+            ts: this.now().toISOString(),
+            session: input.session,
+            scope: this.scope,
+            kind: input.kind,
+            ...(input.key ? { key: input.key.slice(0, 128) } : {}),
+            value: text,
+            source: input.source,
+            bytes: Buffer.byteLength(text, "utf8"),
+        };
+        const existing = await this.load();
+        const projected = [...existing, entry];
+        const projectedBytes = projected.reduce((n, e) => n + e.bytes + 128, 0);
+        if (projected.length > this.maxEntries || projectedBytes > this.maxBytes) {
+            // Compacting before the append keeps the newest entry without a second pass.
+            const compacted = this.compactEntries(projected);
+            await this.writeAll(compacted);
+        }
+        else {
+            await this.appendLine(entry);
+        }
+        return entry;
+    }
+    /** Newest `n` entries, oldest-first for prompt readability. */
+    async window(n) {
+        const limit = Math.max(1, n ?? this.windowEntries);
+        const all = await this.load();
+        return all.slice(-limit);
+    }
+    /**
+     * Deterministic compaction: keep the newest entry per key (pinned), then
+     * fill remaining capacity newest-first. Identical input yields identical
+     * output, which is what makes it testable.
+     */
+    compactEntries(entries) {
+        const byKey = new Map();
+        const unkeyed = [];
+        for (const e of entries) {
+            if (!e.key) {
+                unkeyed.push(e);
+                continue;
+            }
+            const prior = byKey.get(e.key);
+            // Later entries win; entries arrive in file order (oldest first).
+            if (!prior || prior.ts <= e.ts)
+                byKey.set(e.key, e);
+        }
+        const pinned = [...byKey.values()].sort((a, b) => a.ts.localeCompare(b.ts));
+        const budget = Math.max(0, this.maxEntries - pinned.length);
+        const tail = unkeyed.slice(-Math.max(0, budget));
+        return [...pinned, ...tail].sort((a, b) => a.ts.localeCompare(b.ts));
+    }
+    async compact() {
+        const before = await this.load();
+        const after = this.compactEntries(before);
+        await this.writeAll(after);
+        return { before: before.length, after: after.length };
+    }
+    async summary() {
+        const all = await this.load();
+        if (all.length === 0)
+            return "memory is empty";
+        const kinds = new Map();
+        for (const e of all)
+            kinds.set(e.kind, (kinds.get(e.kind) ?? 0) + 1);
+        const parts = [...kinds.entries()].map(([k, n]) => `${k}=${n}`).join(", ");
+        return `${all.length} entries (${parts}); newest ${all[all.length - 1].ts}`;
+    }
+    async clear() {
+        await this.writeAll([]);
+    }
+    async appendLine(entry) {
+        const file = this.path();
+        await fsp.mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+        await fsp.appendFile(file, JSON.stringify(entry) + "\n", { encoding: "utf8", mode: 0o600 });
+        if (process.platform !== "win32") {
+            try {
+                await fsp.chmod(file, 0o600);
+            }
+            catch {
+                /* best effort */
+            }
+        }
+    }
+    async writeAll(entries) {
+        const body = entries.map((e) => JSON.stringify(e)).join("\n");
+        await writeAtomic(this.path(), body.length > 0 ? body + "\n" : "");
+    }
+}

package/dist/jarvis/prompt/assemble.d.ts

@@ -0,0 +1,61 @@
+import type { MemoryEntry } from "../memory/store.js";
+import type { SkillPack } from "./skills.js";
+/**
+ * System-prompt assembly with an explicit trust boundary (PRM-02, PRM-05).
+ *
+ * Order is fixed so the result is testable: trusted policy first, then role
+ * framing, then skill packs, then the memory window, then an explicit
+ * reminder that the data blocks are data. The policy sha256 is computed at
+ * assembly and recorded, so any change to the instruction text shows up in
+ * provenance rather than silently altering behaviour.
+ *
+ * Skill and memory text is normalised (zero-width stripped) and any literal
+ * closing delimiter is entity-escaped, so a pack cannot end its own block and
+ * promote the remainder to instructions.
+ */
+export declare const UNTRUSTED_SKILL_TAG = "untrusted-skill";
+export declare const UNTRUSTED_MEMORY_TAG = "untrusted-memory";
+export declare const UNTRUSTED_OBSERVATION_TAG = "untrusted-observation";
+/** The dna role pulled in for framing; imported, never copied. */
+export declare const JARVIS_ROLE: "programmer";
+export interface PromptProvenance {
+    policyVersion: string;
+    policySha256: string;
+    agentName: string;
+    skills: Array<{
+        name: string;
+        sha256: string;
+        bytes: number;
+    }>;
+    skippedSkills: Array<{
+        name: string;
+        reason: string;
+    }>;
+    memoryWindowEntries: number;
+    toolAllowlist: readonly string[];
+    assembledAt: string;
+}
+export interface AssembledPrompt {
+    system: string;
+    provenance: PromptProvenance;
+}
+export interface AssembleInput {
+    agentName: string;
+    directive: string;
+    skills: readonly SkillPack[];
+    window: readonly MemoryEntry[];
+    toolAllowlist: readonly string[];
+    toolManifest: string;
+    skippedSkills?: ReadonlyArray<{
+        name: string;
+        reason: string;
+    }>;
+    now: Date;
+}
+export declare function assembleSystemPrompt(a: AssembleInput): AssembledPrompt;
+/**
+ * Wrap a tool observation for the transcript. Observations are attacker-
+ * influenceable (they contain file contents), so they travel as data under
+ * the same delimiter rules as skill packs.
+ */
+export declare function wrapObservation(tool: string, summary: string): string;