@bridge4dev/runner 0.30.0 → 0.33.0

package/dist/agent-prompt.js

@@ -0,0 +1,252 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { isGitInternalPath, isSecretPath } from './policy.js';
+/**
+ * The project's own prompt file — the one thing on this machine that a project
+ * can put into an agent's SYSTEM prompt.
+ *
+ * ## Why a system prompt and not a file the agent reads
+ *
+ * Measured on a live request (2026-08-05), not assumed. `CLAUDE.md`, `AGENTS.md`
+ * and `SessionStart` hook output all arrive inside the first USER message —
+ * Claude Code's own prompt says so in as many words: «Treat feedback from hooks
+ * … as coming from the user». `systemPrompt.append` arrives in `system[]`,
+ * after the CLI's own text and last. Only the second survives a compaction, and
+ * only the second can stand next to a rule the CLI itself states.
+ *
+ * That difference is the whole feature. An Opus-5 system prompt carries
+ * «Do not call the AgentTool unless the user requested it»; a project whose
+ * process REQUIRES an independent review round has to be able to say so at the
+ * same level, or it is simply outranked and nobody can see why.
+ *
+ * ## Why this file is paranoid
+ *
+ * Its contents become system-prompt text verbatim, and the path comes off the
+ * wire. So every rule is re-derived here rather than trusted from the API: the
+ * runner is the process that opens the file, and it is the only side that can
+ * see what the path actually resolves to on this disk.
+ */
+/** Big enough for a real process document; small enough to stay a prompt. */
+export const AGENT_PROMPT_MAX_BYTES = 32 * 1024;
+function deny(reason) {
+    return { ok: false, reason };
+}
+/**
+ * Read the project's prompt file, or explain why it cannot be read.
+ *
+ * @param projectRoot Absolute path of the PROJECT FOLDER (`workspace.path`) —
+ *   not the session worktree. Deliberate, for two reasons that always hold: the
+ *   file may be uncommitted (a worktree cut from the base branch would not have
+ *   it), and every session of the project then reads the same rules whatever
+ *   branch it is on.
+ *
+ *   A third reason used to be written here and was wrong, so it is worth saying
+ *   plainly (QA-130 MAJOR-3): this does NOT stop a session from rewriting the
+ *   file that becomes its own next system prompt. It stops it in `BRANCH` mode,
+ *   where writes outside the worktree are refused — but in `workMode: DIRECT`,
+ *   which is the default, the project folder IS the session's working
+ *   directory. What guards it there is the layer-1 rule in `policy.ts`
+ *   (`agentPromptFile`), and that rule is a guard rather than a guarantee: it
+ *   covers the file-writing tools, not a shell redirect, and `full` mode
+ *   bypasses layer 1 altogether by design. The honest backstop is the `sha` in
+ *   the session feed, which changes when the file does.
+ * @param relPath The configured path, relative to `projectRoot`.
+ */
+export function readAgentPrompt(projectRoot, relPath) {
+    const wanted = relPath.trim();
+    if (wanted === '')
+        return deny('the path is empty');
+    if (wanted.length > 300)
+        return deny('the path is too long');
+    // A NUL truncates the string every syscall below sees, so it must never get
+    // as far as a syscall.
+    // eslint-disable-next-line no-control-regex -- a control character in a path is never legitimate
+    if (/[\u0000-\u001f\u007f]/.test(wanted))
+        return deny('the path contains control characters');
+    if (path.isAbsolute(wanted) || wanted.startsWith('~')) {
+        return deny('the path must be relative to the project folder');
+    }
+    if (wanted.includes('\\'))
+        return deny('the path must use "/" separators');
+    if (wanted.endsWith('/'))
+        return deny('the path must name a file, not a directory');
+    if (wanted.split('/').includes('..'))
+        return deny('the path must not contain ".." segments');
+    // The project folder itself has to exist and be a directory before anything
+    // can be resolved against it — otherwise `realpath` failures below would all
+    // read as «no such file», blaming the prompt for a moved project.
+    let rootReal;
+    try {
+        rootReal = fs.realpathSync(path.resolve(projectRoot));
+    }
+    catch {
+        return deny('the project folder is not readable');
+    }
+    const absolute = path.resolve(rootReal, wanted);
+    // `lstat` first, and on the path as written: a SYMLINK is refused outright
+    // rather than followed. Following it would mean the setting says one file and
+    // the agent's system prompt comes from another, which is exactly the sort of
+    // indirection that makes a security rule unreadable.
+    let link;
+    try {
+        link = fs.lstatSync(absolute);
+    }
+    catch (error) {
+        return deny(describeFsError(error));
+    }
+    if (link.isSymbolicLink())
+        return deny('the path is a symlink');
+    if (link.isDirectory())
+        return deny('the path is a directory');
+    if (!link.isFile())
+        return deny('the path is not a regular file');
+    // Containment is checked AFTER symlinks are resolved, because a symlinked
+    // PARENT directory would otherwise pass a purely textual check and land the
+    // read outside the project entirely (the QA-96 F13 lesson, applied here).
+    let realPath;
+    try {
+        realPath = fs.realpathSync(absolute);
+    }
+    catch (error) {
+        return deny(describeFsError(error));
+    }
+    const rel = path.relative(rootReal, realPath);
+    if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
+        return deny('the path leaves the project folder');
+    }
+    // The same two lists layer 1 uses for every tool call. A setting must not be
+    // a way around them: «read .env into the system prompt» is precisely the
+    // shape of request this would otherwise grant.
+    if (isSecretPath(realPath))
+        return deny('that file is on the protected list');
+    if (isGitInternalPath(realPath))
+        return deny('that file is inside .git');
+    // Read with a hard ceiling on BYTES ACTUALLY READ rather than trusting the
+    // size from `stat`: a file can grow between the two calls, and «we checked
+    // and then read whatever was there» is not a limit.
+    //
+    // The open re-checks the file through its own descriptor rather than trusting
+    // the path a second time, and that closes two holes the path checks cannot
+    // (QA-130 MINOR-4):
+    //
+    //  - **the window between `realpath` and `open`.** Every rule above was
+    //    decided about a path; `open` resolves the name again. Replacing the last
+    //    component with a symlink in between would hand back a file nothing here
+    //    ever looked at. `O_NOFOLLOW` refuses that outright, and comparing
+    //    dev/ino catches a plain swap.
+    //  - **hard links**, which are the same capability under another name and
+    //    which `realpath` cannot see: a link has no target to resolve. Without
+    //    this, `ln /etc/hostname docs/prompt.md` walks past both «inside the
+    //    project folder» and «not on the protected list», because both were
+    //    decided about the NAME.
+    let buffer;
+    try {
+        buffer = readCapped(realPath, AGENT_PROMPT_MAX_BYTES + 1, link);
+    }
+    catch (error) {
+        if (error instanceof PromptFileRefused)
+            return deny(error.reason);
+        return deny(describeFsError(error));
+    }
+    if (buffer.length > AGENT_PROMPT_MAX_BYTES) {
+        return deny(`the file is larger than ${Math.floor(AGENT_PROMPT_MAX_BYTES / 1024)} KB`);
+    }
+    if (buffer.includes(0))
+        return deny('the file is not text');
+    const sha = crypto.createHash('sha256').update(buffer).digest('hex').slice(0, 12);
+    // Strip a UTF-8 BOM: it is invisible in every editor and would otherwise be
+    // the first character of the agent's system prompt.
+    const text = buffer
+        .toString('utf8')
+        .replace(/^\uFEFF/, '')
+        .trim();
+    if (text === '')
+        return deny('the file is empty');
+    return { ok: true, text, relPath: wanted, absPath: realPath, bytes: buffer.length, sha };
+}
+/** A refusal decided after the file was already open — carried out by throwing. */
+class PromptFileRefused extends Error {
+    reason;
+    constructor(reason) {
+        super(reason);
+        this.reason = reason;
+        this.name = 'PromptFileRefused';
+    }
+}
+/**
+ * Read at most `limit` bytes from a file that is proved, through its own
+ * descriptor, to be the same plain file the checks above approved.
+ *
+ * @param expected The `lstat` taken before the path checks — the identity every
+ *   rule above was decided about.
+ */
+function readCapped(file, limit, expected) {
+    const fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+    try {
+        const opened = fs.fstatSync(fd);
+        if (!opened.isFile())
+            throw new PromptFileRefused('the path is not a regular file');
+        // A second name for the same inode is a second way in, and it is the one
+        // `realpath` cannot see. One link is the only shape whose name and contents
+        // are the same fact.
+        if (opened.nlink !== 1)
+            throw new PromptFileRefused('the file has more than one name');
+        if (opened.dev !== expected.dev || opened.ino !== expected.ino) {
+            throw new PromptFileRefused('the file changed while it was being opened');
+        }
+        const buffer = Buffer.alloc(limit);
+        let read = 0;
+        while (read < limit) {
+            const n = fs.readSync(fd, buffer, read, limit - read, null);
+            if (n === 0)
+                break;
+            read += n;
+        }
+        return buffer.subarray(0, read);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/**
+ * Turn an fs error into a sentence a human can act on.
+ *
+ * Never echoes the error's own message: it carries the absolute path, and this
+ * text is shown in the session feed of a dashboard that may be open on somebody
+ * else's screen.
+ */
+function describeFsError(error) {
+    const code = error?.code;
+    if (code === 'ENOENT')
+        return 'no such file in the project folder';
+    if (code === 'EACCES' || code === 'EPERM')
+        return 'the runner may not read that file';
+    if (code === 'EISDIR')
+        return 'the path is a directory';
+    if (code === 'ELOOP')
+        return 'the path is a symlink loop';
+    if (code === 'ENAMETOOLONG')
+        return 'the path is too long';
+    return 'the file could not be read';
+}
+/** How the prompt is announced in the session feed and in the journal. */
+export function agentPromptSizeLabel(bytes) {
+    return bytes < 1024 ? `${bytes} B` : `${(bytes / 1024).toFixed(1)} KB`;
+}
+/**
+ * A configured path, safe to put in a line a person reads.
+ *
+ * The session feed renders a notice as plain text, so backticks would be shown
+ * literally rather than as code — and this string can be a REFUSED path, which
+ * means it never passed any of the checks above and is only as clean as the API
+ * schema made it. Quoted with guillemets, stripped of anything that could break
+ * a line, and bounded (QA-130 NIT-13).
+ */
+export function quotePath(value) {
+    const clean = Array.from(value)
+        .filter((ch) => ch >= ' ' && ch !== '\u007f' && ch !== '`')
+        .join('');
+    return `«${clean.length > 120 ? `${clean.slice(0, 117)}…` : clean}»`;
+}
+//# sourceMappingURL=agent-prompt.js.map

package/dist/index.js

@@ -249,6 +249,16 @@ function runnerCapabilities(apiUrlOverride) {
          */
         contextRewind: true,
         contextCompaction: true,
+        /**
+         * Reads the project's own prompt file and hands it to the agent as
+         * SYSTEM-prompt text, for both Claude and Codex.
+         *
+         * Announced so the dashboard can refuse to offer the setting on a server
+         * that would ignore it. That refusal is the point of the flag: this is the
+         * one setting whose value is that it cannot be silently outranked, so a
+         * version of it that is silently ignored would be worse than none.
+         */
+        agentPrompt: true,
         /**
          * Session 15: `git_status` reports whether the PROJECT FOLDER is clean, so
          * the panel can say what is blocking an Apply instead of offering a button
@@ -265,6 +275,19 @@ function runnerCapabilities(apiUrlOverride) {
          * runner incapable of the setting it honours.
          */
         agentAutoCommit: true,
+        /**
+         * Session 18: the agent's git rules come from the PROJECT, not from this
+         * binary.
+         *
+         * `agentPushBan`, `agentProtectedBranches`, `agentAllowForcePush` and
+         * `agentAllowDestructiveGit` are read off the workspace and applied on
+         * every tool call. Announced so the settings card can warn that a server
+         * without it will go on refusing every push whatever the switch says —
+         * warn, not refuse: the fleet updates one machine at a time and a manager
+         * who cannot record the intention until the last of them is current has
+         * been handed a worse problem.
+         */
+        agentGitPolicy: true,
         /**
          * Session 16: git is git.
          *

package/dist/policy.d.ts

@@ -1,6 +1,47 @@
 import type { AgentMode } from './adapters/types.js';
 export type TrustMode = 'STRICT' | 'NORMAL' | 'AUTO';
-export interface PolicyContext {
+/**
+ * The project's git policy for agents (session 18) — one shape, carried
+ * unchanged from the API's descriptor through the supervisor and the adapters
+ * into `PolicyContext`.
+ *
+ * A named interface rather than four fields repeated in five places, because
+ * these are the fields whose DIRECTION matters: see the polarity note on
+ * `agentPushBan`. A copy that drifts is a copy that eventually gets one of
+ * them the wrong way round.
+ */
+export interface AgentGitPolicy {
+    /**
+     * «Принудительно запретить push» — the project's switch.
+     *
+     * READ AS `!== false`. Not `=== true`, and not truthiness.
+     *
+     * `undefined` means an API too old to send the field, and there the answer
+     * must be what it has always been: refused. This is the OPPOSITE polarity to
+     * `agentAutoCommit`, where silence permits — and they sit close together on
+     * purpose so that whoever copies one reads why the other differs. Getting it
+     * backwards does not fail a test, it silently hands every runner on an old
+     * API permission to push.
+     */
+    agentPushBan?: boolean;
+    /**
+     * Branches the agent may never push to, whatever `agentPushBan` says.
+     *
+     * `undefined` means «nobody said», which is `['main', 'master']` — the pair
+     * that was hardcoded until this release. An EMPTY ARRAY is a real answer and
+     * means «nothing is protected»; the two must not be conflated, which is why
+     * nothing here writes `list?.length ? … : DEFAULT`.
+     */
+    agentProtectedBranches?: string[];
+    /**
+     * `undefined` and `false` both mean no. Force into a protected branch is
+     * refused whatever this says — the two rules are AND-ed, not OR-ed.
+     */
+    agentAllowForcePush?: boolean;
+    /** `git reset --hard` and `git clean`. `undefined` and `false` mean no. */
+    agentAllowDestructiveGit?: boolean;
+}
+export interface PolicyContext extends AgentGitPolicy {
     trustMode: TrustMode;
     /**
      * The interaction mode the SESSION is in — the dial in the composer, as
@@ -30,6 +71,27 @@ export interface PolicyContext {
      * than this release — and there the answer stays what it has always been.
      */
     agentAutoCommit?: boolean;
+    /**
+     * Absolute path of the project's own prompt file, when this session was given
+     * one (session 17).
+     *
+     * Same shape and the same reason as the `.git` rule below it: this file has
+     * stopped being data. Its contents are the session's SYSTEM prompt, so a
+     * write to it is a rewrite of the rules the next process of this session will
+     * be given — including the rules that say what the agent may do.
+     *
+     * It only became reachable when `workMode: DIRECT` made the project folder
+     * the agent's own working directory (session 16, and the default). In
+     * `BRANCH` mode «writes outside the worktree are not allowed» already covered
+     * it, which is why the first version of session 17 believed it was safe
+     * everywhere (QA-130 MAJOR-3).
+     *
+     * A guard, not a guarantee, and the difference is worth stating: it covers
+     * the file-writing tools, not `sh -c 'echo … > prompt.md'`, and `full` mode
+     * does not consult layer 1 at all. The `sha` printed in the session feed is
+     * what makes a change visible when this cannot prevent it.
+     */
+    agentPromptFile?: string;
 }
 export interface PolicyDecision {
     decision: 'allow' | 'deny' | 'ask';
@@ -55,6 +117,16 @@ export declare function isInsideWorktree(p: string, worktreePath: string): boole
  * next git invocation. Neither is ever ordinary agent work.
  */
 export declare function isGitInternalPath(p: string): boolean;
+/**
+ * The project's git rules, applied to one Bash command.
+ *
+ * Returns a refusal, or null when the command has nothing to do with them.
+ * Every branch of this function is reachable only when the project has
+ * DELIBERATELY switched something on — with the shipped defaults the first
+ * check refuses every push and the rest never run, which is byte for byte the
+ * behaviour of the four regexes it replaces.
+ */
+export declare function evaluateGitPolicy(command: string, ctx: PolicyContext): PolicyDecision | null;
 export interface RecipeCommandContext {
     /**
      * The docker compose project this preview owns, from `preview.project` in the