@dailephd/my-dev-kit-lab 0.9.2 → 0.9.3

package/dist/src/experiments/plugins/agentSuccessRate/strictDiffResponse.js

@@ -0,0 +1,312 @@
+/**
+ * Application-level output validation for the real-agent prompt contract. It runs on the final answer text that a
+ * provider adapter has ALREADY extracted from its transport (Codex JSONL / Claude result envelope) and before the
+ * Lab-owned patch pipeline. It never parses a provider transport envelope and never falls back to legacy extraction
+ * for an invalid strict response.
+ */
+export const STRICT_DIFF_RESPONSE_SCHEMA_VERSION = "1.0.0";
+export const STRICT_DIFF_MAX_PATCH_BYTES = 1_048_576;
+// Worst case JSON escaping (\u00XX) expands one patch byte to six response bytes, plus the fixed envelope.
+const MAX_RESPONSE_BYTES = STRICT_DIFF_MAX_PATCH_BYTES * 6 + 1024;
+const MAX_DEPTH = 32;
+export const OUTPUT_CONTRACT_CODES = [
+    "STRICT_EMPTY_RESPONSE",
+    "STRICT_RESPONSE_TOO_LARGE",
+    "STRICT_INVALID_UNICODE",
+    "STRICT_MARKDOWN_FENCE",
+    "STRICT_NOT_JSON",
+    "STRICT_TOO_DEEP",
+    "STRICT_DUPLICATE_KEY",
+    "STRICT_MULTIPLE_DOCUMENTS",
+    "STRICT_TRAILING_CONTENT",
+    "STRICT_NOT_OBJECT",
+    "STRICT_MISSING_FIELD",
+    "STRICT_UNKNOWN_FIELD",
+    "STRICT_FIELD_TYPE",
+    "STRICT_SCHEMA_VERSION",
+    "STRICT_EMPTY_PATCH",
+    "STRICT_PATCH_TOO_LARGE",
+    "STRICT_PATCH_NOT_RAW_DIFF",
+    "EXPLANATION_EMPTY",
+    "EXPLANATION_CODE_FENCE",
+    "EXPLANATION_PROSE_BEFORE",
+    "EXPLANATION_PROSE_IN_DIFF",
+    "EXPLANATION_MALFORMED_DIFF"
+];
+class JsonProblem extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+    }
+}
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+const isWellFormedUnicode = (value) => !LONE_SURROGATE.test(value);
+const isWhitespace = (char) => char === " " || char === "\t" || char === "\n" || char === "\r";
+/** Small bounded RFC 8259 parser. It exists because JSON.parse silently keeps the last of duplicate object keys. */
+function parseJsonStrict(text) {
+    let index = 0;
+    const skip = () => {
+        while (index < text.length && isWhitespace(text[index]))
+            index += 1;
+    };
+    const bad = () => {
+        throw new JsonProblem("STRICT_NOT_JSON");
+    };
+    const parseString = () => {
+        index += 1; // opening quote
+        let out = "";
+        for (;;) {
+            if (index >= text.length)
+                bad();
+            const char = text[index];
+            if (char === '"') {
+                index += 1;
+                return out;
+            }
+            if (char.charCodeAt(0) < 0x20)
+                bad();
+            if (char === "\\") {
+                const next = text[index + 1];
+                index += 2;
+                switch (next) {
+                    case '"':
+                        out += '"';
+                        break;
+                    case "\\":
+                        out += "\\";
+                        break;
+                    case "/":
+                        out += "/";
+                        break;
+                    case "b":
+                        out += "\b";
+                        break;
+                    case "f":
+                        out += "\f";
+                        break;
+                    case "n":
+                        out += "\n";
+                        break;
+                    case "r":
+                        out += "\r";
+                        break;
+                    case "t":
+                        out += "\t";
+                        break;
+                    case "u": {
+                        const hex = text.slice(index, index + 4);
+                        if (!/^[0-9a-fA-F]{4}$/.test(hex))
+                            bad();
+                        out += String.fromCharCode(parseInt(hex, 16));
+                        index += 4;
+                        break;
+                    }
+                    default:
+                        bad();
+                }
+                continue;
+            }
+            out += char;
+            index += 1;
+        }
+    };
+    const parseValue = (depth) => {
+        if (depth > MAX_DEPTH)
+            throw new JsonProblem("STRICT_TOO_DEEP");
+        skip();
+        const char = text[index];
+        if (char === undefined)
+            return bad();
+        if (char === "{") {
+            index += 1;
+            const object = new Map();
+            skip();
+            if (text[index] === "}") {
+                index += 1;
+                return object;
+            }
+            for (;;) {
+                skip();
+                if (text[index] !== '"')
+                    bad();
+                const key = parseString();
+                if (object.has(key))
+                    throw new JsonProblem("STRICT_DUPLICATE_KEY");
+                skip();
+                if (text[index] !== ":")
+                    bad();
+                index += 1;
+                object.set(key, parseValue(depth + 1));
+                skip();
+                if (text[index] === ",") {
+                    index += 1;
+                    continue;
+                }
+                if (text[index] === "}") {
+                    index += 1;
+                    return object;
+                }
+                bad();
+            }
+        }
+        if (char === "[") {
+            index += 1;
+            const array = [];
+            skip();
+            if (text[index] === "]") {
+                index += 1;
+                return array;
+            }
+            for (;;) {
+                array.push(parseValue(depth + 1));
+                skip();
+                if (text[index] === ",") {
+                    index += 1;
+                    continue;
+                }
+                if (text[index] === "]") {
+                    index += 1;
+                    return array;
+                }
+                bad();
+            }
+        }
+        if (char === '"')
+            return parseString();
+        for (const [literal, value] of [["true", true], ["false", false], ["null", null]]) {
+            if (text.startsWith(literal, index)) {
+                index += literal.length;
+                return value;
+            }
+        }
+        const number = /^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/.exec(text.slice(index, index + 64));
+        if (number) {
+            index += number[0].length;
+            return Number(number[0]);
+        }
+        return bad();
+    };
+    const value = parseValue(0);
+    skip();
+    return { value, end: index };
+}
+const HUNK_HEADER = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/;
+const HEADER_PREFIXES = [
+    "diff --git ", "index ", "--- ", "+++ ", "new file mode ", "deleted file mode ", "old mode ", "new mode ",
+    "similarity index ", "dissimilarity index ", "rename from ", "rename to ", "copy from ", "copy to ", "Binary files "
+];
+/**
+ * Raw-diff-only grammar check: every line must be a git diff header, a hunk header, or a hunk body line whose count
+ * is consumed exactly by the preceding hunk header. Prose before, between or after the diff is a violation.
+ */
+function checkRawDiffOnly(text) {
+    if (text.trim() === "")
+        return "EXPLANATION_EMPTY";
+    if (/^[ \t]*```/m.test(text))
+        return "EXPLANATION_CODE_FENCE";
+    const trimmed = text.trimStart();
+    if (!trimmed.startsWith("diff --git ") && !trimmed.startsWith("--- "))
+        return "EXPLANATION_PROSE_BEFORE";
+    const lines = trimmed.split(/\r?\n/);
+    while (lines.length > 0 && lines[lines.length - 1] === "")
+        lines.pop();
+    let oldRemaining = 0;
+    let newRemaining = 0;
+    for (const line of lines) {
+        if (oldRemaining > 0 || newRemaining > 0) {
+            if (line.startsWith("\\"))
+                continue;
+            const marker = line.length === 0 ? " " : line[0];
+            if (marker === " ") {
+                oldRemaining -= 1;
+                newRemaining -= 1;
+            }
+            else if (marker === "-")
+                oldRemaining -= 1;
+            else if (marker === "+")
+                newRemaining -= 1;
+            else
+                return "EXPLANATION_PROSE_IN_DIFF";
+            if (oldRemaining < 0 || newRemaining < 0)
+                return "EXPLANATION_PROSE_IN_DIFF";
+            continue;
+        }
+        if (line.startsWith("\\"))
+            continue;
+        const hunk = HUNK_HEADER.exec(line);
+        if (hunk) {
+            oldRemaining = hunk[2] === undefined ? 1 : Number(hunk[2]);
+            newRemaining = hunk[4] === undefined ? 1 : Number(hunk[4]);
+            continue;
+        }
+        if (HEADER_PREFIXES.some((prefix) => line.startsWith(prefix)))
+            continue;
+        return "EXPLANATION_PROSE_IN_DIFF";
+    }
+    return oldRemaining === 0 && newRemaining === 0 ? null : "EXPLANATION_MALFORMED_DIFF";
+}
+/** Validates one strict-diff-v1 final answer. Returns the decoded patch only for an exactly-conforming response. */
+export function parseStrictDiffResponse(text) {
+    if (typeof text !== "string" || text.trim() === "")
+        return { ok: false, code: "STRICT_EMPTY_RESPONSE" };
+    if (Buffer.byteLength(text, "utf8") > MAX_RESPONSE_BYTES)
+        return { ok: false, code: "STRICT_RESPONSE_TOO_LARGE" };
+    if (!isWellFormedUnicode(text))
+        return { ok: false, code: "STRICT_INVALID_UNICODE" };
+    if (/^\s*```/.test(text))
+        return { ok: false, code: "STRICT_MARKDOWN_FENCE" };
+    let parsed;
+    try {
+        parsed = parseJsonStrict(text);
+    }
+    catch (error) {
+        return { ok: false, code: error instanceof JsonProblem ? error.code : "STRICT_NOT_JSON" };
+    }
+    const rest = text.slice(parsed.end);
+    if (rest !== "") {
+        const next = rest.trimStart()[0];
+        return { ok: false, code: next === "{" || next === "[" ? "STRICT_MULTIPLE_DOCUMENTS" : "STRICT_TRAILING_CONTENT" };
+    }
+    const value = parsed.value;
+    if (!(value instanceof Map))
+        return { ok: false, code: "STRICT_NOT_OBJECT" };
+    for (const key of value.keys()) {
+        if (key !== "schemaVersion" && key !== "patch")
+            return { ok: false, code: "STRICT_UNKNOWN_FIELD" };
+    }
+    if (!value.has("schemaVersion") || !value.has("patch"))
+        return { ok: false, code: "STRICT_MISSING_FIELD" };
+    const schemaVersion = value.get("schemaVersion");
+    const patch = value.get("patch");
+    if (typeof schemaVersion !== "string" || typeof patch !== "string")
+        return { ok: false, code: "STRICT_FIELD_TYPE" };
+    if (schemaVersion !== STRICT_DIFF_RESPONSE_SCHEMA_VERSION)
+        return { ok: false, code: "STRICT_SCHEMA_VERSION" };
+    if (!isWellFormedUnicode(patch))
+        return { ok: false, code: "STRICT_INVALID_UNICODE" };
+    if (patch.trim() === "")
+        return { ok: false, code: "STRICT_EMPTY_PATCH" };
+    if (Buffer.byteLength(patch, "utf8") > STRICT_DIFF_MAX_PATCH_BYTES)
+        return { ok: false, code: "STRICT_PATCH_TOO_LARGE" };
+    if (checkRawDiffOnly(patch) !== null)
+        return { ok: false, code: "STRICT_PATCH_NOT_RAW_DIFF" };
+    return { ok: true, response: { schemaVersion: STRICT_DIFF_RESPONSE_SCHEMA_VERSION, patch } };
+}
+/**
+ * Applies the effective output contract to an extracted provider final answer.
+ *  - strict-diff-v1: exactly StrictDiffResponseV1; the decoded patch is returned.
+ *  - legacy-diff-v1 + explanationMode none: a raw unified diff with no fence or prose; the text is returned unchanged.
+ *  - legacy-diff-v1 + explanationMode legacy: historical behavior, text returned unchanged.
+ */
+export function validateAgentSuccessFinalAnswer(settings, finalAnswerText) {
+    if (settings.templateId === "strict-diff-v1") {
+        const parsed = parseStrictDiffResponse(finalAnswerText);
+        return parsed.ok ? { ok: true, patchText: parsed.response.patch } : { ok: false, code: parsed.code };
+    }
+    if (settings.explanationMode === "none") {
+        const violation = checkRawDiffOnly(finalAnswerText);
+        return violation === null ? { ok: true, patchText: finalAnswerText } : { ok: false, code: violation };
+    }
+    return { ok: true, patchText: finalAnswerText };
+}

package/dist/src/gallery/galleryPathSafety.js

@@ -0,0 +1,111 @@
+import { open, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+// Fail-closed path and media validation for gallery source artifacts. Source artifacts are untrusted
+// filesystem inputs: a reference is accepted only when it is a safe run-root-relative POSIX path whose
+// physically resolved target is an ordinary supported file inside the verified source root.
+const SCHEME_PATTERN = /^[a-zA-Z][a-zA-Z0-9+.-]*:/;
+// eslint-disable-next-line no-control-regex
+const CONTROL_PATTERN = /[\u0000-\u001f\u007f]/;
+export const GALLERY_MEDIA_EXTENSIONS = {
+    video: [".webm"],
+    screenshot: [".png", ".jpg", ".jpeg", ".webp"],
+    markdown: [".md"],
+    text: [".txt", ".srt", ".vtt", ".html"],
+    json: [".json"]
+};
+/** True only for a non-empty relative POSIX path with no traversal, drive, UNC, scheme, NUL or encoding tricks. */
+export function isSafeRelativeArtifactPath(value) {
+    if (typeof value !== "string" || value.length === 0 || value.length > 1024)
+        return false;
+    if (CONTROL_PATTERN.test(value) || value.includes("\\") || value.includes("%"))
+        return false;
+    if (value.startsWith("/") || SCHEME_PATTERN.test(value))
+        return false;
+    return value.split("/").every((segment) => segment !== "" && segment !== "." && segment !== "..");
+}
+/**
+ * Validates a link value for the gallery HTML. A gallery link is output-relative, so a leading "../" run is
+ * legitimate (the artifact lives in a verified source root outside the gallery directory); any other
+ * traversal, absolute form, scheme or malformed segment is rejected. Returns the percent-encoded href or null.
+ */
+export function safeGalleryHref(value, allowedExtensions) {
+    if (typeof value !== "string" || value.length === 0 || value.length > 2048)
+        return null;
+    if (CONTROL_PATTERN.test(value) || value.includes("\\") || value.includes("%"))
+        return null;
+    if (value.startsWith("/") || SCHEME_PATTERN.test(value))
+        return null;
+    const segments = value.split("/");
+    let index = 0;
+    while (segments[index] === "..")
+        index += 1;
+    const rest = segments.slice(index);
+    if (rest.length === 0 || rest.some((segment) => segment === "" || segment === "." || segment === ".."))
+        return null;
+    if (allowedExtensions) {
+        const ext = path.posix.extname(rest[rest.length - 1]).toLowerCase();
+        if (!allowedExtensions.includes(ext))
+            return null;
+    }
+    return [...segments.slice(0, index), ...rest.map((segment) => encodeURIComponent(segment))].join("/");
+}
+function within(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative !== "" && relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+async function sniff(file, kind, ext) {
+    if (kind === "markdown" || kind === "text" || kind === "json")
+        return true;
+    const handle = await open(file, "r");
+    try {
+        const buffer = Buffer.alloc(12);
+        const { bytesRead } = await handle.read(buffer, 0, 12, 0);
+        if (bytesRead < 4)
+            return false;
+        if (kind === "video")
+            return buffer[0] === 0x1a && buffer[1] === 0x45 && buffer[2] === 0xdf && buffer[3] === 0xa3;
+        if (ext === ".png")
+            return buffer.subarray(0, 4).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47]));
+        if (ext === ".jpg" || ext === ".jpeg")
+            return buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff;
+        if (ext === ".webp")
+            return bytesRead >= 12 && buffer.toString("latin1", 0, 4) === "RIFF" && buffer.toString("latin1", 8, 12) === "WEBP";
+        return false;
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Resolves and verifies one run-root-relative artifact reference. Never throws; failure carries a reason. */
+export async function verifyArtifactFile(realRoot, reference, kind) {
+    if (!isSafeRelativeArtifactPath(reference))
+        return { ok: false, reason: "the recorded path is not a safe run-root-relative path" };
+    const ext = path.posix.extname(reference).toLowerCase();
+    if (!GALLERY_MEDIA_EXTENSIONS[kind].includes(ext))
+        return { ok: false, reason: `the file type ${ext || "(none)"} is not supported for ${kind}` };
+    try {
+        const real = await realpath(path.resolve(realRoot, ...reference.split("/")));
+        if (!within(realRoot, real))
+            return { ok: false, reason: "the file resolves outside the source root" };
+        const info = await stat(real);
+        if (!info.isFile())
+            return { ok: false, reason: "the path is not an ordinary file" };
+        if (!(await sniff(real, kind, ext)))
+            return { ok: false, reason: `the file content is not a valid ${ext.slice(1)} ${kind}` };
+        return { ok: true, absolutePath: real };
+    }
+    catch {
+        return { ok: false, reason: "the file is missing or unreadable" };
+    }
+}
+/** Output-relative POSIX link text for a verified file, or null when no relative path exists (for example another drive). */
+export function outputRelativePath(realOutDir, absoluteFile) {
+    const relative = path.relative(realOutDir, absoluteFile);
+    if (relative === "" || path.isAbsolute(relative))
+        return null;
+    return relative.split(path.sep).join("/");
+}
+/** Explicit user-supplied source text must be a local filesystem path, never a URL. */
+export function looksLikeUrl(value) {
+    return /^[a-zA-Z][a-zA-Z0-9+.-]+:/.test(value) && !/^[a-zA-Z]:[\/]/.test(value);
+}