@sema-agent/core 7.16.0 → 7.17.0

package/dist/tools/artifact/local-stub.js

@@ -0,0 +1,296 @@
+import { randomBytes } from "node:crypto";
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve, sep } from "node:path";
+import {} from "../../core/artifact-host.js";
+import { acquireStoreDirLock } from "../../stores/file/fs-atomic.js";
+import { normalizePublishedPath } from "./artifact-tool.js";
+export const EVAL_STUB_URL_PREFIX = "eval-stub://artifact/";
+export const LOCAL_STUB_MAX_FILE_BYTES = 16 * 1024 * 1024;
+export const LOCAL_STUB_MAX_TOTAL_BYTES = 64 * 1024 * 1024;
+const LEDGER_FILE = "ledger.json";
+const TMP_DIR = ".tmp";
+const LOCK_FILE = "LOCK";
+const RESERVED_NAMES = new Set([LEDGER_FILE, TMP_DIR, LOCK_FILE].map((n) => n.toLowerCase()));
+const SLUG_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const ATTEMPT_WINDOW = 512;
+const emptyLedger = () => ({ v: 1, artifacts: {}, attempts: {} });
+const isRow = (x, key) => {
+    if (x === null || typeof x !== "object")
+        return false;
+    const r = x;
+    if (typeof r.slug !== "string" || r.slug !== key || !SLUG_RE.test(r.slug) || r.slug.startsWith(".") || RESERVED_NAMES.has(r.slug.toLowerCase()))
+        return false;
+    if (typeof r.url !== "string" || !Number.isSafeInteger(r.version) || r.version < 1 || !Array.isArray(r.files))
+        return false;
+    return r.files.every((f) => f !== null && typeof f === "object" && typeof f.path === "string" && normalizePublishedPath(f.path).ok && Number.isSafeInteger(f.bytes));
+};
+function parseLedger(text, path) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`artifact stub ledger is corrupt (not JSON): ${path}`);
+    }
+    const l = parsed;
+    if (l === null || typeof l !== "object" || l.v !== 1 || l.artifacts === null || typeof l.artifacts !== "object" || l.attempts === null || typeof l.attempts !== "object") {
+        throw new Error(`artifact stub ledger is corrupt (unexpected shape): ${path}`);
+    }
+    for (const [key, row] of Object.entries(l.artifacts))
+        if (!isRow(row, key))
+            throw new Error(`artifact stub ledger is corrupt (bad artifact row): ${path}`);
+    return { v: 1, artifacts: { ...l.artifacts }, attempts: { ...l.attempts } };
+}
+function fsyncDirBestEffort(dir) {
+    try {
+        const fd = openSync(dir, "r");
+        try {
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch {
+    }
+}
+function fsyncTreeBestEffort(dir) {
+    for (const entry of readdirSync(dir, { withFileTypes: true }))
+        if (entry.isDirectory())
+            fsyncTreeBestEffort(join(dir, entry.name));
+    fsyncDirBestEffort(dir);
+}
+function writeFsync(path, bytes) {
+    const fd = openSync(path, "w", 0o600);
+    try {
+        writeFileSync(fd, bytes);
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function slugBase(fileName) {
+    const dot = fileName.lastIndexOf(".");
+    const stem = (dot > 0 ? fileName.slice(0, dot) : fileName).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40);
+    return stem.length > 0 ? stem : "artifact";
+}
+export class LocalArtifactStub {
+    dir;
+    #mint = new Map();
+    #chain = Promise.resolve();
+    constructor(opts) {
+        if (typeof opts?.dir !== "string" || opts.dir.length === 0)
+            throw new Error("localArtifactStub: `dir` is required");
+        this.dir = resolve(opts.dir);
+    }
+    capabilities() {
+        return { plane: "local-stub", actions: ["publish"], defaultVisibility: "private", maxFileBytes: LOCAL_STUB_MAX_FILE_BYTES, maxTotalBytes: LOCAL_STUB_MAX_TOTAL_BYTES, multiFile: false, storageDir: this.dir };
+    }
+    onMount(runId) {
+        this.#mint.set(runId, new Set());
+    }
+    ownMinted(runId) {
+        return new Set(this.#mint.get(runId) ?? []);
+    }
+    publish(req, ctx) {
+        const run = this.#chain.then(() => this.#publishLocked(req, ctx));
+        this.#chain = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    #ledgerPath() {
+        return join(this.dir, LEDGER_FILE);
+    }
+    #loadLedger() {
+        const p = this.#ledgerPath();
+        if (!existsSync(p))
+            return emptyLedger();
+        return parseLedger(readFileSync(p, "utf8"), p);
+    }
+    #versionDir(slug, version) {
+        return join(this.dir, slug, `v${version}`);
+    }
+    #snapshotOf(row) {
+        const base = this.#versionDir(row.slug, row.version);
+        const realBase = realpathSync(base);
+        const files = row.files.map((f) => {
+            const target = realpathSync(resolve(base, ...f.path.split("/")));
+            if (!target.startsWith(realBase + sep))
+                throw new Error(`artifact stub ledger is corrupt (a file resolves outside its version directory): ${this.#ledgerPath()}`);
+            return { path: f.path, content: new Uint8Array(readFileSync(target)), ...(f.mediaType !== undefined ? { mediaType: f.mediaType } : {}) };
+        });
+        return {
+            files,
+            ...(row.title !== undefined ? { title: row.title } : {}),
+            ...(row.description !== undefined ? { description: row.description } : {}),
+            ...(row.favicon !== undefined ? { favicon: row.favicon } : {}),
+            ...(row.label !== undefined ? { label: row.label } : {}),
+        };
+    }
+    #mintSlug(ledger, requested, firstFile) {
+        const fold = requested?.toLowerCase();
+        if (requested !== undefined && fold !== undefined && SLUG_RE.test(requested) && !RESERVED_NAMES.has(fold) && !requested.startsWith(".") && !Object.keys(ledger.artifacts).some((s) => s.toLowerCase() === fold))
+            return requested;
+        const base = slugBase(firstFile);
+        const taken = new Set(Object.keys(ledger.artifacts).map((s) => s.toLowerCase()));
+        for (;;) {
+            const slug = `${base}-${randomBytes(3).toString("hex")}`;
+            if (!taken.has(slug))
+                return slug;
+        }
+    }
+    #commitLedger(next) {
+        const ledgerTmp = join(this.dir, `${LEDGER_FILE}.${randomBytes(4).toString("hex")}.tmp`);
+        try {
+            const text = JSON.stringify(next, null, 2);
+            writeFsync(ledgerTmp, text);
+            const verified = parseLedger(readFileSync(ledgerTmp, "utf8"), ledgerTmp);
+            if (JSON.stringify(verified) !== JSON.stringify(next))
+                throw new Error("artifact stub ledger did not read back as written");
+            renameSync(ledgerTmp, this.#ledgerPath());
+        }
+        catch (err) {
+            try {
+                rmSync(ledgerTmp, { force: true });
+            }
+            catch {
+            }
+            throw err;
+        }
+        fsyncDirBestEffort(this.dir);
+    }
+    #withAttempt(ledger, attemptId, attempt) {
+        const entries = Object.entries(ledger.attempts).filter(([k]) => k !== attemptId);
+        while (entries.length >= ATTEMPT_WINDOW)
+            entries.shift();
+        entries.push([attemptId, attempt]);
+        return Object.fromEntries(entries);
+    }
+    #replayOf(ledger, attempt) {
+        if ("ref" in attempt)
+            return { ok: true, ref: attempt.ref };
+        if (attempt.code === "conflict") {
+            const row = ledger.artifacts[attempt.slug];
+            return { ok: false, code: "conflict", currentVersion: row !== undefined ? String(row.version) : attempt.currentVersion, current: row !== undefined ? this.#snapshotOf(row) : "reread" };
+        }
+        return { ok: false, code: attempt.code, message: attempt.message };
+    }
+    async #publishLocked(req, ctx) {
+        mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+        const lease = acquireStoreDirLock(this.dir, { label: "artifact stub", fileName: LOCK_FILE });
+        try {
+            const ledger = this.#loadLedger();
+            const replay = ledger.attempts[ctx.attemptId];
+            if (replay !== undefined)
+                return this.#replayOf(ledger, replay);
+            const decided = this.#decide(ledger, req, ctx);
+            if (!decided.ok) {
+                const attempt = decided.outcome.code === "conflict" ? { code: "conflict", slug: decided.slug ?? "", currentVersion: decided.outcome.currentVersion } : { code: decided.outcome.code, message: decided.outcome.message };
+                this.#commitLedger({ ...ledger, attempts: this.#withAttempt(ledger, ctx.attemptId, attempt) });
+                return decided.outcome;
+            }
+            const { slug, version, existing, files, mint } = decided;
+            const versionDir = this.#versionDir(slug, version);
+            const tmpDir = join(this.dir, TMP_DIR, `${slug}-v${version}-${randomBytes(4).toString("hex")}`);
+            let staged = false;
+            try {
+                if (existsSync(versionDir))
+                    rmSync(versionDir, { recursive: true, force: true });
+                mkdirSync(tmpDir, { recursive: true, mode: 0o700 });
+                for (const f of files) {
+                    const target = join(tmpDir, ...f.path.split("/"));
+                    mkdirSync(dirname(target), { recursive: true, mode: 0o700 });
+                    writeFsync(target, f.content);
+                }
+                fsyncTreeBestEffort(tmpDir);
+                mkdirSync(dirname(versionDir), { recursive: true, mode: 0o700 });
+                renameSync(tmpDir, versionDir);
+                staged = true;
+                fsyncDirBestEffort(dirname(versionDir));
+                const now = new Date().toISOString();
+                const url = `${EVAL_STUB_URL_PREFIX}${slug}`;
+                const row = {
+                    slug,
+                    url,
+                    version,
+                    ...(req.title !== undefined ? { title: req.title } : existing?.title !== undefined ? { title: existing.title } : {}),
+                    ...(req.description !== undefined ? { description: req.description } : existing?.description !== undefined ? { description: existing.description } : {}),
+                    ...(req.favicon !== undefined ? { favicon: req.favicon } : existing?.favicon !== undefined ? { favicon: existing.favicon } : {}),
+                    ...(req.label !== undefined ? { label: req.label } : {}),
+                    files: files.map((f) => ({ path: f.path, ...(f.mediaType !== undefined ? { mediaType: f.mediaType } : {}), bytes: f.content.byteLength })),
+                    createdAt: existing?.createdAt ?? now,
+                    updatedAt: now,
+                };
+                const ref = { url, slug, version: String(version), ...(row.title !== undefined ? { title: row.title } : {}) };
+                this.#commitLedger({ v: 1, artifacts: { ...ledger.artifacts, [slug]: row }, attempts: this.#withAttempt(ledger, ctx.attemptId, { ref }) });
+                mint.add(slug);
+                return { ok: true, ref };
+            }
+            catch (err) {
+                for (const orphan of [tmpDir, ...(staged ? [versionDir] : [])]) {
+                    try {
+                        rmSync(orphan, { recursive: true, force: true });
+                    }
+                    catch {
+                    }
+                }
+                throw err;
+            }
+        }
+        finally {
+            lease.release();
+        }
+    }
+    #decide(ledger, req, ctx) {
+        const refuse = (code, message, slug) => ({ ok: false, outcome: { ok: false, code, message }, ...(slug !== undefined ? { slug } : {}) });
+        if (req.removeFiles !== undefined && req.removeFiles.length > 0)
+            return refuse("refused", "the local stub does not apply removeFiles");
+        if (req.files.length === 0)
+            return refuse("refused", "a publish needs at least one file");
+        const seen = new Set();
+        const files = [];
+        let total = 0;
+        for (const f of req.files) {
+            const norm = normalizePublishedPath(f.path);
+            if (!norm.ok)
+                return refuse("refused", `published path ${JSON.stringify(f.path).slice(0, 120)} ${norm.reason}`);
+            const fold = norm.path.toLowerCase();
+            if (seen.has(fold))
+                return refuse("refused", `published path ${JSON.stringify(norm.path).slice(0, 120)} collides with another entry`);
+            seen.add(fold);
+            total += f.content.byteLength;
+            if (f.content.byteLength > LOCAL_STUB_MAX_FILE_BYTES)
+                return refuse("payload_too_large", `${norm.path.slice(0, 120)} is ${f.content.byteLength} bytes; the limit is ${LOCAL_STUB_MAX_FILE_BYTES} bytes per file`);
+            files.push({ path: norm.path, content: f.content, ...(f.mediaType !== undefined ? { mediaType: f.mediaType } : {}) });
+        }
+        if (total > LOCAL_STUB_MAX_TOTAL_BYTES)
+            return refuse("payload_too_large", `the files total ${total} bytes; the limit is ${LOCAL_STUB_MAX_TOTAL_BYTES} bytes per version`);
+        const mint = this.#mint.get(ctx.runId) ?? new Set();
+        this.#mint.set(ctx.runId, mint);
+        if (req.url !== undefined) {
+            if (!req.url.startsWith(EVAL_STUB_URL_PREFIX))
+                return refuse("url_foreign", "not an eval-stub:// link this run published");
+            const slug = req.url.slice(EVAL_STUB_URL_PREFIX.length);
+            if (!mint.has(slug))
+                return refuse("url_foreign", "this run did not publish that artifact", slug);
+            const existing = ledger.artifacts[slug];
+            if (existing === undefined)
+                return refuse("not_found", "the artifact is no longer in the ledger", slug);
+            if (req.baseVersion !== undefined && req.baseVersion !== String(existing.version) && req.force !== true) {
+                return { ok: false, outcome: { ok: false, code: "conflict", currentVersion: String(existing.version), current: this.#snapshotOf(existing) }, slug };
+            }
+            return { ok: true, slug, version: existing.version + 1, existing, files, mint };
+        }
+        return { ok: true, slug: this.#mintSlug(ledger, req.slug, files[0].path), version: 1, existing: undefined, files, mint };
+    }
+    rows() {
+        return Object.values(this.#loadLedger().artifacts).map((r) => ({ url: r.url, slug: r.slug, version: String(r.version), ...(r.title !== undefined ? { title: r.title } : {}) }));
+    }
+    versionFiles(slug, version) {
+        const dir = this.#versionDir(slug, version);
+        return existsSync(dir) ? readdirSync(dir, { recursive: true }).map(String).sort() : [];
+    }
+}
+export function localArtifactStub(opts) {
+    return new LocalArtifactStub(opts);
+}

package/dist/tools/fs/bash-readonly-classifier.d.ts

@@ -209,9 +209,10 @@ export interface BashReadonlyRootBoundary {
     /** Base for resolving relative operands. Defaults to `roots[0]`. Callers tracking an observable `cd`
      *  should pass the LIVE working directory, or a `..` operand will be judged against the wrong base. */
     cwd?: string;
-    /** Expansion for a leading `~`. Without it a `~`-rooted operand is unresolvable and demotes (with no
-     *  out-of-root signal — the classifier does not know where it points, which is a different verdict
-     *  from knowing it points outside). */
+    /** Expansion for a leading `~` — and the value the read faces substitute for the `$HOME` / `${HOME}` word
+     *  spellings before segmenting ({@link foldHomeVariableSpelling}). Without it a `~`-rooted operand is unresolvable
+     *  and demotes (with no out-of-root signal — the classifier does not know where it points, which is a
+     *  different verdict from knowing it points outside). */
     homeDir?: string;
     /** The sensitive-path read deny judge over LEXICALLY RESOLVED operands: a hit
      *  demotes the command (ask, never auto-allow), independently of the roots — in-root operands are
@@ -248,11 +249,13 @@ export interface BashReadonlyRootBoundary {
 export interface CompoundReadonlyVerdict {
     /** Demotion reason (the same string {@link classifyCompoundReadonly} returns), or undefined. */
     reason?: string;
-    /** Set only when the SOLE obstacle to the read-only verdict was the root boundary: every segment is
-     *  an allowlisted reader, no blocking/device/backgrounding arm fired, and the offending arguments are
-     *  statically resolved paths outside the roots. A gate can therefore offer the narrow "allow reading
-     *  from <dir>" approval instead of a generic shell prompt. Absent for every other demotion — an
-     *  unresolvable path deliberately does NOT carry it (nothing concrete to grant). */
+    /** Set when a listed reader's statically resolved path operand lies outside the roots. With `reason` the
+     *  containment sentence itself, the roots were the SOLE obstacle (every segment a listed reader, no
+     *  blocking/device/guarded-form arm fired, every operand resolved) and the narrow "allow reading from <dir>"
+     *  approval would make the command auto-allowable; with `reason` a SHAPE refusal (follow mode, a device, a
+     *  blocking stdin read, a guarded verb form, multi-cd) or an UNRESOLVABLE-operand refusal (another operand
+     *  the walk could not read) the finding rides beside the sentence — the read of that path is the same read,
+     *  so the boundary's objection is stated either way, while the command stays refused after any grant. */
     outOfRootRead?: true;
     /** The resolved out-of-root paths, de-duplicated, in first-seen order. Present iff `outOfRootRead`. */
     outOfRootPaths?: readonly string[];
@@ -312,6 +315,15 @@ export interface CompoundReadonlyVerdict {
      * and miss the other.
      */
     undecidedPaths?: readonly string[];
+    /**
+     * Operands (written spellings) the walk could NOT resolve at all — a `~user` form, a `~` under no declared
+     * home, an argument the shell rewrites (brace/variable/command expansion), a `cd` target it cannot follow
+     * (`cd -`, bare `cd`, a pattern). The STRUCTURAL form of the unresolvable sentence: `reason` carries the
+     * first one's sentence, this member every one of them, and both survive whatever other sentence (a shape
+     * refusal) takes precedence. CONSUMER CONTRACT: non-empty ⇒ the boundary could not read where the command
+     * reads — a fail-closed ask (plain: nothing was declared), never a vouch.
+     */
+    unresolvedOperands?: readonly string[];
     /**
      * Operands of a RECURSIVE/EXPANDING read form (`grep -r`, `ls -R`, `du`, … — see
      * {@link RECURSIVE_READ_FORMS}) judged with a {@link BashReadonlyRootBoundary.denyMatch} seat wired.
@@ -343,6 +355,51 @@ export interface CompoundReadonlyVerdict {
  * uses the host's native separator.
  */
 export declare function formatOutOfRootReadApprovalOption(directory: string): string;
+/** Resolve one operand against the boundary's base, WITHOUT touching the filesystem. Returns undefined
+ *  when the token cannot be resolved statically — the fail-closed direction, reported as its own
+ *  demotion rather than silently treated as in-root.
+ *
+ *  The resolution is TEXTUAL, and its limitation runs in BOTH directions (only the first shows up as
+ *  a refusal, so only that half tends to get reported):
+ *   · false REFUSAL — a non-canonical spelling of an in-root path (a symlinked `/tmp` → `/private/tmp`
+ *     prefix) does not textually match the canonical roots and is refused;
+ *   · false ALLOW — a symlink INSIDE a root that points outside it (`<root>/vendor` → `/etc`) resolves
+ *     to a textual prefix match, so `cat vendor/passwd` is judged in-root and the real command follows
+ *     the link. This face is therefore lexical containment, NOT filesystem containment: it is weaker
+ *     than the structured Read/Grep tools, which canonicalize through `realpath` before comparing
+ *     (see safety.ts's `canonicalizeAndEnforceRoot`). Closing it means resolving each candidate against
+ *     the live filesystem, which this function deliberately cannot do (it is synchronous, pure, and
+ *     shared with the approval-gate face); the seam for it is the ENFORCING caller, which holds the
+ *     ExecutionEnv.
+ *
+ *  The verdict now carries {@link CompoundReadonlyVerdict.checkedPaths} (the
+ *  candidates that landed inside), and `createBashReadonlyTool` canonicalizes them on a LOCAL env
+ *  before running — closing BOTH directions above for that face (an escaping symlink is refused; a
+ *  non-canonical spelling that resolves back inside is no longer refused). Two residuals stay here by
+ *  construction, and belong to the caller rather than to this function: the compound/approval-gate face
+ *  has no filesystem and stays lexical, and a REMOTE env keeps the lexical behaviour (its
+ *  `canonicalPath` is an RPC per candidate). */
+export declare function resolveOperandLexically(base: string | undefined, operand: string, homeDir: string | undefined): string | undefined;
+/**
+ * The home directory's VARIABLE spellings, SUBSTITUTED with the declared value before a read face segments the
+ * command: `$HOME` / `${HOME}` at the START of a word (an empty quote pair before it included), unquoted or
+ * double-quoted, followed by `/` or by the word's end. Those are exactly the words whose expansion is the home
+ * directory and nothing else, so the word is rewritten to what bash hands the program — the value itself, in
+ * place, with the word's quote structure untouched (`"$HOME/x"` → `"/home/u/x"`, `$HOME"/x"` → `/home/u"/x"`)
+ * — and every arm reads an ordinary absolute path; no tilde is minted, so the tilde-prefix rule of
+ * {@link tokenizeSegment} judges only tildes the command actually wrote. Substituted only against a DECLARED
+ * home (`homeDir`): with none declared the child's `$HOME` may differ from what `~` falls back to, so the
+ * spelling is left as written and meets the substitution hard-reject. The value must survive this file's own
+ * reading of the rewritten word: the UNQUOTED spelling only for a value with no `$IFS` whitespace, glob or
+ * shell metacharacter (word splitting / pathname expansion / a connector this file would then split on — none
+ * of which a real expansion is subject to here), the double-quoted one for any value carrying no `"`, `$`,
+ * backtick, backslash or line break (the characters that would change the quote structure or meet the
+ * hard-reject). Everything else is left as written: a single-quoted spelling does not expand, and a mid-word
+ * or suffixed one (`x$HOME`, `$HOME.bak`, `$HOMES`) still meets the substitution hard-reject. Bails whole on
+ * an escape or a backtick in the command (the hard-reject refuses those strings regardless, and the quote
+ * walk below is exact only without them) and on unbalanced quoting.
+ */
+export declare function foldHomeVariableSpelling(command: string, homeDir: string | undefined): string;
 /**
  * {@link classifyCompoundReadonly} with the structured verdict. The name/operator/blocking arms
  * run FIRST and unchanged, so an existing demotion keeps its exact reason and never acquires the
@@ -568,3 +625,12 @@ export declare const POLL_LOOP_MAX_SLEEP_SECONDS = 600;
  * ({@link NON_ASCII_WHITESPACE}), so the grammar's tokenization and bash's stay identical.
  */
 export declare function classifyBoundedReadonlyPollLoop(command: string, allow: ReadonlySet<string>, boundary?: BashReadonlyRootBoundary): string | undefined;
+/**
+ * The poll-loop face's STRUCTURED verdict — the same {@link CompoundReadonlyVerdict} the compound face
+ * returns, so a consumer reads the boundary's structural findings (deny row, containment, recursive or
+ * undecided operands) off the loop body exactly as off a plain compound, beside whatever sentence the
+ * loop grammar or the body's shape produced. {@link classifyBoundedReadonlyPollLoop} is its `reason`
+ * projection. A refusal of the LOOP GRAMMAR itself (not a bounded loop, an unlisted body program, an
+ * unvetted sleep) carries no structure: no reader segment was walked.
+ */
+export declare function classifyBoundedReadonlyPollLoopDetailed(command: string, allow: ReadonlySet<string>, boundary?: BashReadonlyRootBoundary): CompoundReadonlyVerdict;