@sweny-ai/core 0.1.175 → 0.1.177

package/dist/safe-file.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Files the sweny process writes into an agent-writable workspace.
+ *
+ * An agent can leave a symlink or a hard link where sweny is about to write
+ * (`.sweny/runs/<id>/output.md` -> `~/.bashrc`), or swap a directory on the
+ * path for a link. These helpers never follow a link: every directory between
+ * the trusted root and the file must be a real directory owned by this user,
+ * the final component is opened `O_NOFOLLOW`, and the file written must be a
+ * regular file with one link (a replaced link or special file is unlinked and
+ * created fresh with `O_EXCL`). Data goes through the descriptor that was
+ * checked; the mode is set on it.
+ *
+ * Race with a process that swaps a checked directory for a link (TOCTOU):
+ * Node has no `openat(2)`, so the parent chain is checked by pathname and the
+ * file opened by pathname. After the open, {@link assertOpenedUnder} re-checks
+ * the chain (realpath equals the lexical path, every component a real owned
+ * directory) and requires that the pathname now names the very inode the
+ * descriptor holds (dev and ino). A swap before the open either leaves a link
+ * on the path or moves the opened inode off it; both fail closed before a byte
+ * is written. Residual risk: an `O_CREAT` through a swapped directory can leave
+ * an empty file outside the workspace before the check fails, and the unlink of
+ * a planted link or special file is by pathname (checked just before, not
+ * atomic). A regular file is never unlinked or truncated by pathname.
+ *
+ * Node only.
+ */
+/**
+ * Create `dir` and its missing parents below `root`, checking each component
+ * under `root` with lstat: a real directory, owned by this user. `root` itself
+ * is trusted. A `dir` outside `root` is created as usual and only its last
+ * component is checked.
+ */
+export declare function ensureDirNoFollow(dir: string, root: string, mode?: number): void;
+export interface NoFollowOptions {
+    /**
+     * Trusted base dir (the workspace root): every component below it, and the
+     * file, must be owned by this user. Default: the file's own dir, with no
+     * ownership check (a runner-owned GITHUB_STEP_SUMMARY, say).
+     */
+    root?: string;
+    /** File mode, set on the descriptor. Default 0o600. */
+    mode?: number;
+    /** Mode for directories created on the way. Default 0o700. */
+    dirMode?: number;
+    /** Append to an existing regular file instead of replacing it. */
+    append?: boolean;
+    /** Create missing directories. Default true. */
+    mkdirs?: boolean;
+}
+/**
+ * Open `file` for writing without following a link. Replace mode unlinks what
+ * is there and creates a fresh file; append mode refuses anything but a
+ * regular, singly linked file (owned by this user when under `root`).
+ * Returns the descriptor; the caller closes it.
+ */
+/**
+ * Fail unless `fd` is the file `file` names now, below `root`, with no link
+ * anywhere between them: the directory's realpath is the realpath of `root`
+ * plus the same relative path, each component under `root` is a real
+ * directory (owned by this user when `owned`), and `lstat(file)` has the
+ * descriptor's dev and ino. See the module comment for the race it closes.
+ */
+export declare function assertOpenedUnder(fd: number, file: string, root: string, owned?: boolean): void;
+export declare function openNoFollow(file: string, opts?: NoFollowOptions): number;
+/**
+ * `{ root: cwd }` when `file` is inside `cwd` (the workspace, where the agent
+ * can write), else `{}`: an operator path elsewhere is only opened without
+ * following a final link.
+ */
+export declare function workspaceRoot(file: string, cwd?: string): {
+    root?: string;
+};
+/** Write (or append) `data` to `file` through {@link openNoFollow}. Throws on any refusal. */
+export declare function writeFileNoFollow(file: string, data: string | Uint8Array, opts?: NoFollowOptions): void;

package/dist/safe-file.js

@@ -0,0 +1,211 @@
+/**
+ * Files the sweny process writes into an agent-writable workspace.
+ *
+ * An agent can leave a symlink or a hard link where sweny is about to write
+ * (`.sweny/runs/<id>/output.md` -> `~/.bashrc`), or swap a directory on the
+ * path for a link. These helpers never follow a link: every directory between
+ * the trusted root and the file must be a real directory owned by this user,
+ * the final component is opened `O_NOFOLLOW`, and the file written must be a
+ * regular file with one link (a replaced link or special file is unlinked and
+ * created fresh with `O_EXCL`). Data goes through the descriptor that was
+ * checked; the mode is set on it.
+ *
+ * Race with a process that swaps a checked directory for a link (TOCTOU):
+ * Node has no `openat(2)`, so the parent chain is checked by pathname and the
+ * file opened by pathname. After the open, {@link assertOpenedUnder} re-checks
+ * the chain (realpath equals the lexical path, every component a real owned
+ * directory) and requires that the pathname now names the very inode the
+ * descriptor holds (dev and ino). A swap before the open either leaves a link
+ * on the path or moves the opened inode off it; both fail closed before a byte
+ * is written. Residual risk: an `O_CREAT` through a swapped directory can leave
+ * an empty file outside the workspace before the check fails, and the unlink of
+ * a planted link or special file is by pathname (checked just before, not
+ * atomic). A regular file is never unlinked or truncated by pathname.
+ *
+ * Node only.
+ */
+import fs from "node:fs";
+import path from "node:path";
+const NOFOLLOW = fs.constants.O_NOFOLLOW ?? 0;
+/** The process uid, or undefined where there is none (Windows). */
+function uid() {
+    return typeof process.getuid === "function" ? process.getuid() : undefined;
+}
+/** True when `child` is `root` or inside it. */
+function within(root, child) {
+    const rel = path.relative(root, child);
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+function assertOwnedDir(dir) {
+    const st = fs.lstatSync(dir);
+    if (st.isSymbolicLink())
+        throw new Error(`${dir} is a symlink`);
+    if (!st.isDirectory())
+        throw new Error(`${dir} is not a directory`);
+    const me = uid();
+    if (me !== undefined && st.uid !== me)
+        throw new Error(`${dir} is not owned by this user`);
+}
+/**
+ * Create `dir` and its missing parents below `root`, checking each component
+ * under `root` with lstat: a real directory, owned by this user. `root` itself
+ * is trusted. A `dir` outside `root` is created as usual and only its last
+ * component is checked.
+ */
+export function ensureDirNoFollow(dir, root, mode = 0o700) {
+    const absRoot = path.resolve(root);
+    const absDir = path.resolve(dir);
+    if (!within(absRoot, absDir)) {
+        fs.mkdirSync(absDir, { recursive: true, mode });
+        assertOwnedDir(absDir);
+        return;
+    }
+    let cur = absRoot;
+    for (const part of path.relative(absRoot, absDir).split(path.sep).filter(Boolean)) {
+        cur = path.join(cur, part);
+        try {
+            fs.mkdirSync(cur, { mode });
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+        }
+        assertOwnedDir(cur);
+    }
+}
+/**
+ * Open `file` for writing without following a link. Replace mode unlinks what
+ * is there and creates a fresh file; append mode refuses anything but a
+ * regular, singly linked file (owned by this user when under `root`).
+ * Returns the descriptor; the caller closes it.
+ */
+/**
+ * Fail unless `fd` is the file `file` names now, below `root`, with no link
+ * anywhere between them: the directory's realpath is the realpath of `root`
+ * plus the same relative path, each component under `root` is a real
+ * directory (owned by this user when `owned`), and `lstat(file)` has the
+ * descriptor's dev and ino. See the module comment for the race it closes.
+ */
+export function assertOpenedUnder(fd, file, root, owned = true) {
+    const abs = path.resolve(file);
+    const absRoot = path.resolve(root);
+    const dir = path.dirname(abs);
+    if (!within(absRoot, dir))
+        throw new Error(`${abs} is outside ${absRoot}`);
+    const rel = path.relative(absRoot, dir);
+    const realDir = fs.realpathSync(dir);
+    if (path.relative(fs.realpathSync(absRoot), realDir) !== rel)
+        throw new Error(`${dir} moved during the open`);
+    let cur = absRoot;
+    for (const part of rel.split(path.sep).filter(Boolean)) {
+        cur = path.join(cur, part);
+        if (owned)
+            assertOwnedDir(cur);
+        else if (!fs.lstatSync(cur).isDirectory())
+            throw new Error(`${cur} is not a directory`);
+    }
+    const named = fs.lstatSync(abs);
+    const held = fs.fstatSync(fd);
+    if (named.dev !== held.dev || named.ino !== held.ino)
+        throw new Error(`${abs} changed during the open`);
+}
+// O_NONBLOCK: a FIFO left in place fails fast (ENXIO) instead of blocking the open.
+const NONBLOCK = fs.constants.O_NONBLOCK ?? 0;
+/** Open errors that mean a link (O_NOFOLLOW), a FIFO with no reader, or a socket at the path. */
+const LINK_OR_SPECIAL = new Set(["ELOOP", "EMLINK", "ENXIO", "EOPNOTSUPP"]);
+/**
+ * Replace mode. What is there is opened without following or truncating it: a
+ * regular, singly linked file (ours, under a root) is kept, and the caller
+ * truncates it through the descriptor once verified. Anything else (a link, a
+ * hard link, a FIFO, a socket, another user's file) is unlinked after the
+ * parent is re-checked, and the file created fresh with O_EXCL.
+ */
+function openForReplace(abs, root, owned, mode) {
+    const { O_WRONLY, O_CREAT, O_EXCL } = fs.constants;
+    try {
+        const fd = fs.openSync(abs, O_WRONLY | O_CREAT | NOFOLLOW | NONBLOCK, mode);
+        const st = fs.fstatSync(fd);
+        const me = uid();
+        if (st.isFile() && st.nlink === 1 && (!owned || me === undefined || st.uid === me))
+            return fd;
+        fs.closeSync(fd);
+    }
+    catch (err) {
+        if (!LINK_OR_SPECIAL.has(err.code ?? ""))
+            throw err;
+    }
+    if (fs.lstatSync(abs).isDirectory())
+        throw new Error(`${abs} is a directory`);
+    const dir = path.dirname(abs);
+    if (path.relative(fs.realpathSync(root), fs.realpathSync(dir)) !== path.relative(root, dir)) {
+        throw new Error(`${dir} moved during the open`);
+    }
+    fs.unlinkSync(abs);
+    return fs.openSync(abs, O_WRONLY | O_CREAT | O_EXCL | NOFOLLOW, mode);
+}
+export function openNoFollow(file, opts = {}) {
+    const abs = path.resolve(file);
+    const root = path.resolve(opts.root ?? path.dirname(abs));
+    if (opts.mkdirs !== false) {
+        if (opts.root === undefined)
+            fs.mkdirSync(root, { recursive: true, mode: opts.dirMode ?? 0o700 });
+        ensureDirNoFollow(path.dirname(abs), root, opts.dirMode ?? 0o700);
+    }
+    else if (opts.root !== undefined) {
+        // Check the existing chain without creating anything.
+        let cur = root;
+        for (const part of path.relative(root, path.dirname(abs)).split(path.sep).filter(Boolean)) {
+            cur = path.join(cur, part);
+            assertOwnedDir(cur);
+        }
+    }
+    const mode = opts.mode ?? 0o600;
+    const { O_WRONLY, O_CREAT, O_APPEND } = fs.constants;
+    const owned = opts.root !== undefined;
+    const fd = opts.append
+        ? fs.openSync(abs, O_WRONLY | O_APPEND | O_CREAT | NOFOLLOW | NONBLOCK, mode)
+        : openForReplace(abs, root, owned, mode);
+    try {
+        assertOpenedUnder(fd, abs, root, owned);
+        const st = fs.fstatSync(fd);
+        if (!st.isFile())
+            throw new Error(`${abs} is not a regular file`);
+        if (st.nlink !== 1)
+            throw new Error(`${abs} has ${st.nlink} links`);
+        const me = uid();
+        if (me !== undefined && opts.root !== undefined && st.uid !== me) {
+            throw new Error(`${abs} is not owned by this user`);
+        }
+        if (!opts.append)
+            fs.ftruncateSync(fd, 0);
+        // An operator's existing file (a runner's step summary) keeps its mode.
+        if (!opts.append || opts.root !== undefined)
+            fs.fchmodSync(fd, mode);
+    }
+    catch (err) {
+        fs.closeSync(fd);
+        throw err;
+    }
+    return fd;
+}
+/**
+ * `{ root: cwd }` when `file` is inside `cwd` (the workspace, where the agent
+ * can write), else `{}`: an operator path elsewhere is only opened without
+ * following a final link.
+ */
+export function workspaceRoot(file, cwd = process.cwd()) {
+    const root = path.resolve(cwd);
+    return within(root, path.resolve(cwd, file)) ? { root } : {};
+}
+/** Write (or append) `data` to `file` through {@link openNoFollow}. Throws on any refusal. */
+export function writeFileNoFollow(file, data, opts = {}) {
+    const fd = openNoFollow(file, opts);
+    try {
+        const buf = typeof data === "string" ? Buffer.from(data) : data;
+        for (let off = 0; off < buf.length;)
+            off += fs.writeSync(fd, buf, off, buf.length - off);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}

package/dist/safe-outputs.d.ts

@@ -13,7 +13,7 @@
  * labels, title prefix, dedupe, node cap, run cap. An optional model screen runs last
  * over the intents that passed and can only veto them.
  */
-import type { Logger, SafeOutputDeclaration, SafeOutputPin, SafeOutputReceipt, SafeOutputsPolicy, SafeOutputType, Skill, Tool } from "./types.js";
+import type { BranchPusher, Logger, SafeOutputDeclaration, SafeOutputPin, SafeOutputReceipt, SafeOutputsPolicy, SafeOutputType, Skill, Tool } from "./types.js";
 /** Name of the intent-recording tool a node with `outputs` receives. */
 export declare const EMIT_OUTPUT_TOOL = "emit_output";
 /** Longest title the write stage accepts (after the prefix). */
@@ -95,6 +95,12 @@ export interface ApplySafeOutputsOptions {
     actor: ActorInfo;
     /** Preview only: print what would be written, write nothing. */
     staged: boolean;
+    /** The run's checkout, for the PR head push (#473). */
+    cwd?: string;
+    /** The PR head push, bound to `cwd` (#473). */
+    pushBranch?: BranchPusher;
+    /** The operator's GITHUB_API_URL for the github skill (GHES). */
+    githubApiUrl?: string;
     state: WriteStageState;
     logger: Logger;
     /** The run input, for `number: { input }` pins. */

package/dist/safe-outputs.js

@@ -565,7 +565,13 @@ export async function applySafeOutputs(o) {
             continue;
         }
         try {
-            const output = await tool.handler(applier.build(write), { config: o.config, logger: o.logger });
+            const output = await tool.handler(applier.build(write), {
+                config: o.config,
+                logger: o.logger,
+                ...(o.cwd ? { cwd: o.cwd } : {}),
+                ...(o.pushBranch ? { pushBranch: o.pushBranch } : {}),
+                ...(o.githubApiUrl ? { githubApiUrl: o.githubApiUrl } : {}),
+            });
             const ref = refOf(output);
             const url = urlOf(output);
             receipts[index] = { ...receipts[index], ...(ref !== undefined ? { ref } : {}), ...(url ? { url } : {}) };

package/dist/skills/git-push.d.ts

@@ -7,14 +7,51 @@
  * the sweny process, with the github skill's token (`GITHUB_TOKEN`), right
  * before it opens the PR. The agent never holds the token.
  *
- * Guard rails: only a local branch that exists, only to `origin` when it is
- * the PR's own repo, never force, never the base branch or the remote's
- * default branch. The token goes to git through command-scope config in the
- * child env (`GIT_CONFIG_*`), never argv, as an `http.<server>/.extraheader`
- * that first resets any persisted one (so the job token is never sent twice).
+ * The checkout is agent-written, so nothing in it may run, or steer the push,
+ * while the token is in play. The push therefore never runs in the checkout:
+ *
+ * 1. Read-only git in the checkout, with no token in its env, resolves the
+ *    head commit, checks that every fetch and push URL of `origin` is the PR's
+ *    repo on the GitHub server, and finds the object store.
+ * 2. A private temporary bare repo borrows those objects (`alternates`, data
+ *    only) and gets one ref, the head commit.
+ * 3. git pushes from that repo, with no system or global config, an empty
+ *    hooks dir, `--no-verify` and no credential helper, to an explicit URL
+ *    built from the PR's repo (`<server>/<owner>/<repo>.git`) with an explicit
+ *    refspec. No agent-written config, hook, push URL or `insteadOf` is read.
+ *    The token goes to git as command-scope config in the child env, never
+ *    argv, and only on this one invocation.
+ *
+ * The git binary, its PATH, the proxy and CA settings and the server URL come
+ * from the environment captured at process startup (startup-env.ts), never
+ * from a value the workspace `.env` introduced, and git is run by an absolute
+ * path that lies outside the workspace, the temp dir and any directory this
+ * user can write (see {@link resolveTrustedGit}).
+ *
+ * The private repo lives in the temp dir, which this user (and so the agent)
+ * can write. A process the agent left running could edit its config between
+ * `init` and `push` (an `insteadOf`, a proxy, `sslVerify=false`). Two layers:
+ * the push carries command-scope config for its exact URL (proxy from the
+ * trusted env or none, `sslVerify=true`, CA only from the trusted env), which
+ * beats repo-local config of the same URL; and the repo's config, alternates,
+ * top-level entries and hooks dir are fingerprinted after setup and compared
+ * right before the push, which is refused on any change. git has no switch to
+ * skip `$GIT_DIR/config`, so a byte check is the idiomatic guard. Residual
+ * risk: a change landing in the milliseconds between that check and git's own
+ * config read. The harnesses stop the agent's process (Codex its whole process
+ * group) when a node ends, but a deliberately detached process (`setsid`)
+ * escapes any group kill; only the sandbox's own process boundary ends it.
+ *
+ * Guard rails: only a local branch that exists, only when origin is the PR's
+ * own repo, never the base branch or the repo's default branch (from the
+ * GitHub API, not the checkout's `origin/HEAD`). The head must be new on the
+ * remote, or an unprotected branch with an open PR into the base (checked by
+ * the caller through the API); the push leases on the sha that check saw and
+ * only fast-forwards.
  * A push that fails is logged and the PR is still requested: the agent may
  * already have pushed (persisted credentials, an `agent_env` grant).
  */
+import type { BranchPusher } from "../types.js";
 export interface GitRunResult {
     code: number;
     stdout: string;
@@ -24,6 +61,16 @@ export type GitRunner = (args: string[], opts: {
     cwd: string;
     env: NodeJS.ProcessEnv;
 }) => Promise<GitRunResult>;
+/** The trusted entries of a PATH value, in order (see {@link trustedDir}). */
+export declare function trustedPathDirs(pathValue: string | undefined, workspace: string): string[];
+/**
+ * The absolute path of the first `git` on `pathValue` (the startup PATH) whose
+ * directory, and whose resolved file and its directory, pass
+ * {@link trustedDir}. Undefined when there is none: nothing is pushed.
+ */
+export declare function resolveTrustedGit(pathValue: string | undefined, workspace: string): string | undefined;
+/** A runner that executes the git at `gitPath` (absolute), never a PATH lookup. */
+export declare function gitAt(gitPath: string): GitRunner;
 export interface PushHeadOptions {
     /** `owner/repo` the PR is for. */
     repo: string;
@@ -31,12 +78,30 @@ export interface PushHeadOptions {
     head: string;
     /** The PR's base branch. */
     base: string;
-    /** The github skill's token. Without it, git uses whatever credential the checkout has. */
+    /**
+     * The repo's default branch, from the GitHub API. Without it nothing is
+     * pushed: the checkout's `origin/HEAD` is agent-written and not consulted.
+     */
+    defaultBranch?: string;
+    /**
+     * The head branch's sha on the remote, as the API reported it, or "" when it
+     * did not exist (`headPushLease` in github.ts). The push leases on it, so a
+     * branch created or moved since the check is not overwritten. Without it
+     * nothing is pushed.
+     */
+    remoteSha?: string;
+    /** The github skill's token. Without it nothing is pushed. */
     token?: string;
-    /** The checkout. Default: `process.cwd()`. */
-    cwd?: string;
+    /** The checkout (the run's `cwd`). */
+    cwd: string;
+    /**
+     * The operator's env: `GITHUB_SERVER_URL`, proxy and CA settings. Default:
+     * `process.env`, read through the startup snapshot (startup-env.ts), so a
+     * value the workspace `.env` introduced is never used. PATH always comes from
+     * the startup snapshot.
+     */
     env?: NodeJS.ProcessEnv;
-    /** Test seam. */
+    /** Test seam. Default: the git {@link resolveTrustedGit} finds on the startup PATH. */
     git?: GitRunner;
 }
 export interface PushHeadResult {
@@ -54,9 +119,33 @@ export declare function repoFromRemote(url: string): {
 } | undefined;
 /** A branch name sweny will pass to git: plain ref characters, no option or traversal forms. */
 export declare function isSafeBranch(name: string): boolean;
+/** `owner/repo` with plain name characters only. */
+export declare function isSafeRepo(repo: string): boolean;
 /** The command-scope git config that authenticates one push to `server` with `token`. */
 export declare function pushAuthConfig(server: string, token: string, env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 /**
- * Push the PR's head branch to `origin` from the sweny process. Never throws.
+ * Command-scope transport config for the push to `destination`, keyed to that
+ * exact URL so it beats repo-local `http.*` and `http.<url>.*` entries: the
+ * proxy from the trusted env or none (an empty `http.proxy` disables proxying,
+ * env included), TLS verification on, and a CA bundle only from the trusted env.
+ */
+export declare function pushTransportConfig(destination: string, trusted: NodeJS.ProcessEnv): Array<[string, string]>;
+/**
+ * The env every sweny-side git call runs with: the trusted PATH, no system or
+ * global config, no prompts, no inherited git settings, and no kept value the
+ * workspace `.env` introduced.
+ */
+export declare function hardenedGitEnv(env: NodeJS.ProcessEnv, trustedPath?: string): NodeJS.ProcessEnv;
+/**
+ * True when a fresh `git init --bare` config holds only repo-format keys
+ * (`[core]` format/fs flags, `[extensions]` object format and ref storage).
+ */
+export declare function isPlainRepoConfig(text: string): boolean;
+/** A branch name without a leading `refs/heads/`, so `refs/heads/develop` and `develop` compare equal. */
+export declare function branchName(ref: string): string;
+/**
+ * Push the PR's head branch from the sweny process. Never throws.
  */
 export declare function pushHeadBranch(opts: PushHeadOptions): Promise<PushHeadResult>;
+/** A pusher bound to one run's checkout and env (handed to tools as `ToolContext.pushBranch`). */
+export declare function bindBranchPusher(cwd: string, env?: NodeJS.ProcessEnv): BranchPusher;