@jitsusama/agentic-harness.core 0.6.2 → 0.6.4

package/dist/command/tokenize.js

@@ -198,11 +198,20 @@ function toHeredoc(info) {
         span: { start: info.index, end: info.end },
     };
 }
-const REDIRECT = /^(\d*)(>>|>|<)(&\d+)?$/;
+/**
+ * A word that begins with a redirect operator: an optional file
+ * descriptor or `&`, the operator, then whatever is written against it.
+ * A `<`, `>` or `(` straight after the operator is a here-string or a
+ * process substitution, which name no file.
+ */
+const REDIRECT = /^(\d*|&)(>>|>|<)(?![<>(])(.*)$/s;
+/** What follows a duplication operator: a descriptor, or `-` to close. */
+const DUPLICATION = /^&(\d+|-)$/;
 /**
  * Pull redirects out of a word list. A redirect operator that names
- * a file descriptor duplication (2>&1) stands alone; any other
- * operator consumes the following word as its target.
+ * a file descriptor duplication (2>&1) stands alone. Any other
+ * operator names its target either in the same word (`2>/dev/null`)
+ * or, when written alone, in the word that follows.
  */
 function extractRedirects(words) {
     const argv = [];
@@ -214,8 +223,26 @@ function extractRedirects(words) {
             argv.push(word);
             continue;
         }
-        const hasDuplication = Boolean(match[3]);
-        const target = !hasDuplication ? words[j + 1] : undefined;
+        const attached = match[3] ?? "";
+        if (DUPLICATION.test(attached)) {
+            redirects.push({ span: word.span, operator: word.text });
+            continue;
+        }
+        if (attached) {
+            const operator = word.text.slice(0, word.text.length - attached.length);
+            const start = word.span.start + operator.length;
+            redirects.push({
+                span: word.span,
+                operator,
+                target: {
+                    span: { start, end: word.span.end },
+                    text: attached,
+                    quoting: quotingOf(attached),
+                },
+            });
+            continue;
+        }
+        const target = words[j + 1];
         if (target) {
             redirects.push({
                 span: { start: word.span.start, end: target.span.end },
@@ -303,6 +330,25 @@ function scanWords(source, start, end) {
     }
     return words;
 }
+/** The quote style of a word's text, read the way `scanWords` reads it. */
+function quotingOf(text) {
+    let sawSingle = false;
+    let sawDouble = false;
+    let i = 0;
+    while (i < text.length) {
+        const ch = text[i];
+        if (ch === "'" || ch === '"') {
+            if (ch === "'")
+                sawSingle = true;
+            else
+                sawDouble = true;
+            i = skipQuoted(text, i);
+            continue;
+        }
+        i++;
+    }
+    return classifyQuoting(sawSingle, sawDouble);
+}
 /** Classify a word's quote style from which quote kinds it used. */
 function classifyQuoting(sawSingle, sawDouble) {
     if (sawSingle && sawDouble)

package/dist/internal/file-lock.d.ts

@@ -0,0 +1,30 @@
+/**
+ * An advisory lock around one file's read-modify-write, for async
+ * callers.
+ *
+ * A read-modify-write that two writers run at once loses one of them:
+ * both read the same document and the second write lays its version
+ * over the first. Two layers stop that. Within a process, writers of
+ * one path queue behind each other, so parallel tool calls in one
+ * session never contend. Across processes, a lock file created with
+ * `wx` holds the holder's pid, and the next writer waits for it.
+ *
+ * The synchronous counterpart for quest READMEs is in
+ * `quest/io.ts`; its callers cannot await, so it spins instead.
+ *
+ * A lock is taken over when its holder has gone or it is older than
+ * any real write takes, since a crashed session must not wedge the
+ * file for good and a pid can be reused. Taking over renames the lock
+ * aside rather than deleting it, and checks the file it moved is the
+ * one it judged stale: between that judgement and the move, another
+ * writer may have taken over first and made a fresh one, and deleting
+ * by name would delete theirs. Release checks the same way, so a
+ * holder that was taken over from does not delete its successor's.
+ */
+/**
+ * Run `fn` while holding the lock for `path`, queued behind any other
+ * writer of the same path in this process and locked against every
+ * other process. The lock file is `${path}.lock`, so its directory has
+ * to exist.
+ */
+export declare function withFileLock<T>(path: string, fn: () => Promise<T>): Promise<T>;

package/dist/internal/file-lock.js

@@ -0,0 +1,183 @@
+/**
+ * An advisory lock around one file's read-modify-write, for async
+ * callers.
+ *
+ * A read-modify-write that two writers run at once loses one of them:
+ * both read the same document and the second write lays its version
+ * over the first. Two layers stop that. Within a process, writers of
+ * one path queue behind each other, so parallel tool calls in one
+ * session never contend. Across processes, a lock file created with
+ * `wx` holds the holder's pid, and the next writer waits for it.
+ *
+ * The synchronous counterpart for quest READMEs is in
+ * `quest/io.ts`; its callers cannot await, so it spins instead.
+ *
+ * A lock is taken over when its holder has gone or it is older than
+ * any real write takes, since a crashed session must not wedge the
+ * file for good and a pid can be reused. Taking over renames the lock
+ * aside rather than deleting it, and checks the file it moved is the
+ * one it judged stale: between that judgement and the move, another
+ * writer may have taken over first and made a fresh one, and deleting
+ * by name would delete theirs. Release checks the same way, so a
+ * holder that was taken over from does not delete its successor's.
+ */
+import { randomUUID } from "node:crypto";
+import { link, open, readFile, rename, stat, unlink } from "node:fs/promises";
+/** How long a writer waits for a live holder before saying so. */
+const WAIT_MS = 10_000;
+/** Pause between attempts at the lock. */
+const RETRY_MS = 20;
+/**
+ * A lock older than this is taken over whoever holds it. A write under
+ * it is a read and a rename of a small file, milliseconds, so anything
+ * this old is a holder that stopped rather than one still writing.
+ */
+const STALE_MS = 30_000;
+const queues = new Map();
+/**
+ * Run `fn` while holding the lock for `path`, queued behind any other
+ * writer of the same path in this process and locked against every
+ * other process. The lock file is `${path}.lock`, so its directory has
+ * to exist.
+ */
+export async function withFileLock(path, fn) {
+    const before = queues.get(path) ?? Promise.resolve();
+    const turn = before.then(() => locked(path, fn), () => locked(path, fn));
+    // The queue only orders writers; it never carries a failure from one
+    // to the next, so the entry it holds settles either way.
+    const settled = turn.then(() => undefined, () => undefined);
+    queues.set(path, settled);
+    try {
+        return await turn;
+    }
+    finally {
+        if (queues.get(path) === settled)
+            queues.delete(path);
+    }
+}
+async function locked(path, fn) {
+    const lockPath = `${path}.lock`;
+    const held = await acquire(lockPath);
+    try {
+        return await fn();
+    }
+    finally {
+        await release(lockPath, held);
+    }
+}
+async function acquire(lockPath) {
+    const deadline = Date.now() + WAIT_MS;
+    while (true) {
+        try {
+            const handle = await open(lockPath, "wx");
+            try {
+                await handle.writeFile(String(process.pid), "utf8");
+                return (await handle.stat()).ino;
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        catch (error) {
+            if (!hasCode(error, "EEXIST"))
+                throw error;
+        }
+        if (await takeOverIfStale(lockPath))
+            continue;
+        if (Date.now() >= deadline) {
+            const holder = await holderOf(lockPath);
+            throw new Error(`${lockPath} has been held for over ${WAIT_MS / 1000}s by ${holder === undefined ? "a process that did not say which" : `pid ${holder}`}, which is still running. Nothing was written. If that process is not writing, delete the lock file and try again.`);
+        }
+        await new Promise((done) => setTimeout(done, RETRY_MS));
+    }
+}
+async function takeOverIfStale(lockPath) {
+    let judged;
+    try {
+        judged = await stat(lockPath);
+    }
+    catch (error) {
+        // Released between the failed create and here: try again.
+        if (hasCode(error, "ENOENT"))
+            return true;
+        throw error;
+    }
+    const holder = await holderOf(lockPath);
+    const old = Date.now() - judged.mtimeMs > STALE_MS;
+    // A holder that has not written its pid yet is one mid-create, not
+    // one that has gone, so only age can make its lock stale.
+    const gone = holder !== undefined && !isAlive(holder);
+    if (!old && !gone)
+        return false;
+    const aside = `${lockPath}.stale-${process.pid}-${randomUUID()}`;
+    try {
+        await rename(lockPath, aside);
+    }
+    catch (error) {
+        // Somebody else took it over first.
+        if (hasCode(error, "ENOENT"))
+            return true;
+        throw error;
+    }
+    const moved = await stat(aside);
+    if (moved.ino !== judged.ino) {
+        // Between the judgement and the move another writer took over and
+        // made a fresh lock, and this moved theirs. Put it back, unless a
+        // third has already made one, in which case theirs stands and the
+        // one moved is left for its holder's release to find missing.
+        try {
+            await link(aside, lockPath);
+        }
+        catch (error) {
+            if (!hasCode(error, "EEXIST"))
+                throw error;
+        }
+    }
+    await unlink(aside);
+    return true;
+}
+async function release(lockPath, ino) {
+    try {
+        if ((await stat(lockPath)).ino === ino)
+            await unlink(lockPath);
+    }
+    catch (error) {
+        // Taken over and released by somebody else already: nothing of
+        // this holder's is left to remove.
+        if (!hasCode(error, "ENOENT"))
+            throw error;
+    }
+}
+async function holderOf(lockPath) {
+    try {
+        const pid = Number.parseInt(await readFile(lockPath, "utf8"), 10);
+        return Number.isFinite(pid) && pid > 0 ? pid : undefined;
+    }
+    catch (error) {
+        // Gone since the create failed, which the next attempt handles.
+        if (hasCode(error, "ENOENT"))
+            return undefined;
+        throw error;
+    }
+}
+function isAlive(pid) {
+    // This process never waits on its own lock, since its writers queue
+    // first, so a lock naming it is one a previous process with the same
+    // pid left behind.
+    if (pid === process.pid)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM is a process that exists and belongs to somebody else.
+        return hasCode(error, "EPERM");
+    }
+}
+function hasCode(error, code) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === code);
+}

package/dist/internal/quest/bash-effects.d.ts

@@ -0,0 +1,26 @@
+/**
+ * What a command does to files without a redirect: the copies, moves,
+ * links, directories, clones, downloads and unpacked archives it creates,
+ * and the files it removes.
+ *
+ * Each reader takes an unquoted argv and answers with the paths as the
+ * command names them, relative or not, so the caller can place them
+ * in the directory the command runs in. A reader reads options the way
+ * its command does, since an option's value taken for a destination is a
+ * path nobody wrote. What a command writes to standard output names no
+ * file and is left to the redirect that catches it.
+ */
+/**
+ * The command a wrapper runs, with the wrapper and its options removed.
+ *
+ * `env` also takes the assignments before the command, and `nice -5` is
+ * the old spelling of an adjustment, so neither is read as the command.
+ */
+export declare function unwrap(argv: readonly string[]): string[];
+/** The files a command creates without a redirect, as the command names them. */
+export declare function createdBy(argv: readonly string[]): string[];
+/**
+ * The files a command removes, as the command names them. A move removes
+ * its sources, since what was there is no longer there.
+ */
+export declare function removedBy(argv: readonly string[]): string[];