@tea-agent/loop-agent 0.1.0-fe-test.0

package/dist/shared/package-metadata.js

@@ -0,0 +1,530 @@
+import { createHash } from "node:crypto";
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { realpathSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { platform } from "node:os";
+export const LOOP_AGENT_PACKAGE_NAME = "@tea-agent/loop-agent";
+// ---------------------------------------------------------------------------
+// Public helpers
+// ---------------------------------------------------------------------------
+/**
+ * Read the `version` field from a package.json file.
+ *
+ * Returns `undefined` when the file is missing, unreadable, or lacks a
+ * string `version` field — callers must treat `undefined` as a hard failure
+ * for identity construction.
+ */
+export function readPackageVersion(packageDir) {
+    try {
+        const raw = readFileSync(path.join(packageDir, "package.json"), "utf-8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.version === "string")
+            return parsed.version;
+    }
+    catch {
+        // file missing or unreadable
+    }
+    return undefined;
+}
+/**
+ * Read the `name` field from a package.json file.
+ *
+ * Returns `undefined` when the file is missing, unreadable, or lacks a
+ * string `name` field.
+ */
+export function readPackageName(packageDir) {
+    try {
+        const raw = readFileSync(path.join(packageDir, "package.json"), "utf-8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.name === "string")
+            return parsed.name;
+    }
+    catch {
+        // file missing or unreadable
+    }
+    return undefined;
+}
+/**
+ * Read the build stamp (git SHA + build time) written by the build pipeline
+ * into `<packageDir>/dist/build-stamp.json`. `undefined` when absent (e.g.
+ * running from source via tsx, or a hand-assembled package), which callers
+ * treat as "no stamp available".
+ */
+export function readBuildStamp(packageDir) {
+    try {
+        const raw = readFileSync(path.join(packageDir, "dist", "build-stamp.json"), "utf-8");
+        const parsed = JSON.parse(raw);
+        if (parsed.schemaVersion !== 1 ||
+            typeof parsed.version !== "string" ||
+            typeof parsed.builtAt !== "string")
+            return undefined;
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Human-readable CLI version label: plain version, enriched with the build
+ * stamp (short git SHA + build date) when available so a stale dist/ that was
+ * built from an old commit is immediately recognizable in `--version`.
+ */
+export function readCliVersionLabel(packageDir) {
+    const version = readPackageVersion(packageDir) ?? "0.0.0";
+    const stamp = readBuildStamp(packageDir);
+    if (!stamp?.gitSha)
+        return version;
+    return `${version} (build ${stamp.gitSha.slice(0, 8)} ${stamp.builtAt.slice(0, 10)})`;
+}
+/**
+ * Strip the build-stamp suffix from a CLI `--version` label, returning the bare
+ * SemVer. Controller-identity/preflight comparisons must use this rather than
+ * the raw label so a build-stamped `0.35.0 (build 7f8c5b5b …)` still matches
+ * `packageVersion === "0.35.0"`.
+ */
+export function normalizeCliVersionLabel(label) {
+    const match = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?/.exec(label.trim());
+    return match ? match[0] : label.trim();
+}
+/**
+ * Compute the SHA-256 hash of a file on disk.
+ *
+ * Returns `undefined` when the file is unreadable — callers must treat this
+ * as a hard failure for identity construction.
+ */
+export function computeBinarySha256(filePath) {
+    try {
+        const buffer = readFileSync(filePath);
+        return createHash("sha256").update(buffer).digest("hex");
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Compute a portable, deterministic content fingerprint for the installed
+ * package rooted at `packageRoot`.
+ *
+ * The fingerprint covers four scopes (package.json, bin/**, dist/**,
+ * skills/**) and is independent of the absolute installation path.
+ *
+ * Sorting uses code-point order (UTF-8 byte comparison), NOT localeCompare,
+ * to ensure deterministic behaviour across locales.
+ */
+export function computePackageFingerprint(packageRoot) {
+    const scope = [
+        "package.json",
+        "bin/**",
+        "dist/**",
+        "skills/**",
+    ];
+    // Collecting entries ---------------------------------------------------
+    const entries = [];
+    // 1) package.json (required single file)
+    addRequiredFile(entries, path.join(packageRoot, "package.json"), "");
+    // 2) bin/**, dist/**, skills/** via recursive walk
+    for (const dir of ["bin", "dist", "skills"]) {
+        const absoluteDir = path.join(packageRoot, dir);
+        collectTree(entries, absoluteDir, dir);
+    }
+    // 3) Deterministic sort by relative path (code-point / byte order)
+    entries.sort((a, b) => {
+        const aBuf = Buffer.from(a.relativePath, "utf-8");
+        const bBuf = Buffer.from(b.relativePath, "utf-8");
+        const minLen = Math.min(aBuf.length, bBuf.length);
+        for (let i = 0; i < minLen; i++) {
+            if (aBuf[i] !== bBuf[i])
+                return aBuf[i] - bBuf[i];
+        }
+        return aBuf.length - bBuf.length;
+    });
+    // 4) Cumulative hash: hash of (<relativePath> + "\t" + <contentHash>) lines
+    const cumulative = createHash("sha256");
+    for (const entry of entries) {
+        cumulative.update(`${entry.relativePath}\t${entry.contentHash}\n`);
+    }
+    return {
+        algorithm: "sha256",
+        scopeVersion: 1,
+        scope,
+        value: `sha256:${cumulative.digest("hex")}`,
+        fileCount: entries.length,
+    };
+}
+/**
+ * Resolve a requested bin name or path to the absolute executable.
+ *
+ * Resolution strategy:
+ * 1. If `requested` is already an absolute path, use it directly.
+ * 2. If `requested` contains a path separator (/, \\), resolve against cwd.
+ * 3. Otherwise, search PATH directories (with optional PATHEXT on Windows).
+ * PATH misses fail closed; a bare command name is never invented relative to
+ * cwd when it was not actually found.
+ *
+ * After this call, the result must be treated as frozen — subsequent PATH
+ * mutations must not trigger a new resolution.
+ */
+export function resolveBinPaths(requested, resolvedAt, inputs) {
+    const cwd = inputs?.cwd ?? process.cwd();
+    const env = inputs?.env ?? process.env;
+    const osPlatform = inputs?.platform ?? platform();
+    if (path.isAbsolute(requested)) {
+        const entry = path.resolve(requested);
+        assertRegularFile(entry, requested);
+        return { requested, entry, realEntry: realpathSync(entry), resolvedAt };
+    }
+    // Path-like relative (contains / or \)
+    if (requested.includes("/") || requested.includes("\\")) {
+        const resolved = path.resolve(cwd, requested);
+        assertRegularFile(resolved, requested);
+        return { requested, entry: resolved, realEntry: realpathSync(resolved), resolvedAt };
+    }
+    // Search PATH
+    const pathEnv = env.PATH ?? env.Path ?? env.path ?? "";
+    const candidates = resolveFromPath(requested, pathEnv, osPlatform, env.PATHEXT ?? env.Pathext ?? env.pathext, cwd);
+    if (candidates.length > 0) {
+        const entry = candidates[0];
+        assertRegularFile(entry, requested);
+        return { requested, entry, realEntry: realpathSync(entry), resolvedAt };
+    }
+    throw new Error(`controller identity: cannot resolve executable ${JSON.stringify(requested)}`);
+}
+/**
+ * Resolve an npm-generated Windows `.cmd` shim to the referenced JavaScript
+ * bin entry within the same package.
+ *
+ * On Windows, npm creates `.cmd` wrappers like:
+ * ```
+ * @IF EXIST "%~dp0\node.exe" (
+ *   "%~dp0\node.exe"  "%~dp0\..\package\bin\cli.js" %*
+ * ) ELSE (
+ *   ...
+ * )
+ * ```
+ *
+ * This function parses the `.cmd` shim, extracts the JS script reference, and
+ * returns the resolved absolute path. Returns `undefined` if the shim cannot
+ * be parsed or the referenced script does not exist.
+ *
+ * Pure function: does not require a Windows host to execute.
+ */
+export function resolveCmdShim(shimPath) {
+    try {
+        const content = readFileSync(shimPath, "utf-8");
+        const matches = content.matchAll(/"(?:%dp0%|%~dp0)([^"]+\.(?:js|mjs|cjs))"/gi);
+        for (const match of matches) {
+            if (!match[1])
+                continue;
+            const windowsRelative = match[1].replace(/^[/\\]+/, "");
+            const scriptPath = path.resolve(path.dirname(shimPath), ...windowsRelative.split(/[\\/]+/));
+            try {
+                if (statSync(scriptPath).isFile())
+                    return realpathSync(scriptPath);
+            }
+            catch {
+                // Try the next JavaScript reference in the shim.
+            }
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Check whether a file is a JavaScript script (node shebang or JS extension). */
+export function isJavaScriptScript(filePath) {
+    try {
+        const header = readFileSync(filePath).subarray(0, 256).toString("utf-8").trimStart();
+        if (header.startsWith("#!/usr/bin/env node") || header.startsWith("#!/usr/bin/node") || header.startsWith("#!node")) {
+            return true;
+        }
+    }
+    catch {
+        // can't read — check by extension only
+    }
+    const ext = path.extname(filePath).toLowerCase();
+    return ext === ".js" || ext === ".mjs" || ext === ".cjs" || ext === ".ts";
+}
+// ---------------------------------------------------------------------------
+// Package root resolution
+// ---------------------------------------------------------------------------
+/**
+ * Find the nearest package root by walking upward from `startDir` until a
+ * `package.json` is found.
+ *
+ * Returns `undefined` if no package.json was found at any ancestor (up to 100
+ * levels). Callers must treat `undefined` as a hard failure for identity
+ * construction.
+ */
+export function findPackageRoot(startDir) {
+    let current = path.resolve(startDir);
+    for (let i = 0; i < 100; i++) {
+        try {
+            statSync(path.join(current, "package.json"));
+            return current;
+        }
+        catch {
+            const parent = path.dirname(current);
+            if (parent === current)
+                break;
+            current = parent;
+        }
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// PATHEXT resolution
+// ---------------------------------------------------------------------------
+/**
+ * Expand a Windows executable name into candidate entries using PATHEXT.
+ *
+ * Example: on a system with `PATHEXT=.COM;.EXE;.BAT;.CMD;.VBS;.JS`,
+ * resolving "loop-agent" produces:
+ *   ["loop-agent.COM", "loop-agent.EXE", "loop-agent.BAT", "loop-agent.CMD", ...]
+ *
+ * If the name already has an extension matching a PATHEXT entry, no expansion
+ * is performed and the name is used as-is.
+ *
+ * Pure function for testability.
+ */
+export function expandPathext(bin, pathext) {
+    if (!pathext)
+        return [bin];
+    const extensions = pathext
+        .split(";")
+        .map((ext) => ext.trim())
+        .filter(Boolean);
+    if (extensions.length === 0)
+        return [bin];
+    const binLower = bin.toLowerCase();
+    const alreadyHasExt = extensions.some((ext) => binLower.endsWith(ext.toLowerCase()));
+    if (alreadyHasExt)
+        return [bin];
+    return extensions.map((ext) => bin + ext);
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function addRequiredFile(entries, absolutePath, relativeDir) {
+    const buffer = readFileSync(absolutePath);
+    const contentHash = createHash("sha256").update(buffer).digest("hex");
+    const relativePath = relativeDir
+        ? path.posix.join(relativeDir, path.basename(absolutePath))
+        : path.basename(absolutePath);
+    entries.push({ relativePath, contentHash });
+}
+function collectTree(entries, absoluteDir, relativeDir) {
+    let stats;
+    try {
+        stats = statSync(absoluteDir);
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return; // optional scope directory does not exist
+        throw error;
+    }
+    if (!stats.isDirectory())
+        return;
+    const dirents = readdirSync(absoluteDir, { withFileTypes: true });
+    for (const dirent of dirents) {
+        const childAbs = path.join(absoluteDir, dirent.name);
+        const childRel = path.posix.join(relativeDir, dirent.name);
+        if (dirent.isFile()) {
+            addRequiredFile(entries, childAbs, relativeDir);
+        }
+        else if (dirent.isDirectory()) {
+            collectTree(entries, childAbs, childRel);
+        }
+        // Ignore symlinks, sockets, etc.
+    }
+}
+function isNotFound(error) {
+    return Boolean(error
+        && typeof error === "object"
+        && "code" in error
+        && error.code === "ENOENT");
+}
+// ---------------------------------------------------------------------------
+// Internal: PATH resolution (synchronous, no external dependencies)
+// ---------------------------------------------------------------------------
+function resolveFromPath(bin, pathEnv, osPlatform, pathext, cwd) {
+    const results = [];
+    const dirs = pathEnv.split(osPlatform === "win32" ? ";" : path.delimiter);
+    // On Windows, expand with PATHEXT
+    const isWindows = osPlatform === "win32";
+    for (const rawDir of dirs) {
+        const dir = rawDir || cwd;
+        if (isWindows) {
+            // Get PATHEXT from a well-known env var — in tests, passed via the
+            // merged env through ResolutionInputs. Here we fall back to process.env.
+            const candidates = expandPathext(bin, pathext ?? ".COM;.EXE;.BAT;.CMD;.VBS;.VBE;.JS;.JSE;.WSF;.WSH;.MSC");
+            for (const candidate of candidates) {
+                const filePath = path.join(dir, candidate);
+                try {
+                    if (!statSync(filePath).isFile())
+                        continue;
+                    results.push(filePath);
+                }
+                catch {
+                    // not found in this PATH entry
+                }
+            }
+        }
+        else {
+            const candidate = path.join(dir, bin);
+            try {
+                if (!statSync(candidate).isFile())
+                    continue;
+                results.push(candidate);
+            }
+            catch {
+                // not found in this PATH entry
+            }
+        }
+    }
+    return results;
+}
+function assertRegularFile(filePath, requested) {
+    try {
+        if (statSync(filePath).isFile())
+            return;
+    }
+    catch {
+        // Fall through to the stable error below.
+    }
+    throw new Error(`controller identity: resolved executable for ${JSON.stringify(requested)} is not a readable file: ${filePath}`);
+}
+// ---------------------------------------------------------------------------
+// Running-controller identity (in-process capture)
+// ---------------------------------------------------------------------------
+function safeRealpath(filePath) {
+    try {
+        return realpathSync(filePath);
+    }
+    catch {
+        return filePath;
+    }
+}
+/**
+ * Build a ControllerIdentityV1 from a readable entry file inside a Node package
+ * root. Returns `undefined` when any required identity component cannot be
+ * resolved. This reuses the same ControllerIdentityV1 protocol the Worker uses;
+ * it never invents a second identity shape.
+ */
+export function buildControllerIdentityFromEntry(input) {
+    const resolvedAt = (input.now ?? new Date()).toISOString();
+    const realEntry = safeRealpath(path.resolve(input.entry));
+    try {
+        if (!statSync(realEntry).isFile())
+            return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    const packageRoot = findPackageRoot(path.dirname(realEntry));
+    if (!packageRoot)
+        return undefined;
+    const packageName = readPackageName(packageRoot);
+    if (!packageName)
+        return undefined;
+    const packageVersion = readPackageVersion(packageRoot);
+    if (!packageVersion)
+        return undefined;
+    const binarySha256 = computeBinarySha256(realEntry);
+    if (!binarySha256)
+        return undefined;
+    let packageFingerprint;
+    try {
+        packageFingerprint = computePackageFingerprint(packageRoot);
+    }
+    catch {
+        return undefined;
+    }
+    const isScript = isJavaScriptScript(realEntry);
+    const launch = isScript
+        ? { command: safeRealpath(process.execPath), argsPrefix: [realEntry] }
+        : { command: realEntry, argsPrefix: [] };
+    return {
+        schemaVersion: 1,
+        packageName,
+        binName: path.basename(realEntry),
+        requested: input.requested,
+        entry: path.resolve(input.entry),
+        realEntry,
+        launch,
+        binarySha256,
+        packageRoot,
+        packageVersion,
+        packageFingerprint,
+        resolvedAt,
+    };
+}
+/**
+ * Stable content anchor for a controller identity. Two identities are the same
+ * controller when their anchors are equal. Kept in sync with the Worker anchor
+ * so DAG-owned and Worker-owned identity facts are comparable.
+ */
+export function controllerIdentityAnchor(identity) {
+    return JSON.stringify({
+        schemaVersion: identity.schemaVersion,
+        packageName: identity.packageName,
+        binName: identity.binName,
+        requested: identity.requested,
+        entry: identity.entry,
+        realEntry: identity.realEntry,
+        launch: identity.launch,
+        binarySha256: identity.binarySha256,
+        packageRoot: identity.packageRoot,
+        packageVersion: identity.packageVersion,
+        packageFingerprint: identity.packageFingerprint,
+    });
+}
+export function controllerIdentitiesMatch(left, right) {
+    return Boolean(left && right && controllerIdentityAnchor(left) === controllerIdentityAnchor(right));
+}
+/**
+ * Resolve the identity of the controller that is executing this process.
+ *
+ * Preference order:
+ * 1. The launched CLI entry (argv[1]) when it resolves inside the loop-agent
+ *    package — this is the real controller binary in production.
+ * 2. The package that physically contains this module — always the loop-agent
+ *    package, which keeps identity resolvable under tests and source runs.
+ *
+ * Returns `undefined` when no loop-agent-rooted identity can be built. Callers
+ * treat `undefined` as legacy-unpinned rather than fabricating an identity.
+ */
+export function resolveRunningControllerIdentity(options) {
+    const argv = options?.argv ?? process.argv;
+    const entryArg = argv[1];
+    if (entryArg) {
+        try {
+            const abs = path.resolve(entryArg);
+            const root = findPackageRoot(path.dirname(abs));
+            if (root && readPackageName(root) === LOOP_AGENT_PACKAGE_NAME) {
+                const identity = buildControllerIdentityFromEntry({
+                    requested: entryArg,
+                    entry: abs,
+                    ...(options?.now ? { now: options.now } : {}),
+                });
+                if (identity)
+                    return identity;
+            }
+        }
+        catch {
+            // Fall back to the module location below.
+        }
+    }
+    try {
+        const moduleFile = fileURLToPath(import.meta.url);
+        return buildControllerIdentityFromEntry({
+            requested: entryArg ?? "loop-agent",
+            entry: moduleFile,
+            ...(options?.now ? { now: options.now } : {}),
+        });
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/shared/path-refs.js

@@ -0,0 +1,31 @@
+import path from "node:path";
+export function toPosixPath(value) {
+    return value.replace(/\\/g, "/");
+}
+export function repoRelativePath(repoRoot, filePath) {
+    const relative = path.relative(repoRoot, filePath) || ".";
+    return toPosixPath(relative);
+}
+export function referencePathJoin(...parts) {
+    return path.posix.join(...parts.map(toPosixPath));
+}
+export function resolveCliPath(value, cwd = process.cwd()) {
+    if (process.platform === "win32" && value.startsWith("/") && !value.startsWith("//")) {
+        return value;
+    }
+    return path.isAbsolute(value) ? value : path.resolve(cwd, value);
+}
+export function rewritePathPrefix(value, oldPrefix, newPrefix) {
+    const normalizedValue = toPosixPath(value);
+    const normalizedOld = toPosixPath(oldPrefix).replace(/\/+$/, "");
+    const normalizedNew = toPosixPath(newPrefix).replace(/\/+$/, "");
+    const toNewPrefixStyle = (rewritten) => value.includes("\\") || newPrefix.includes("\\")
+        ? rewritten.replace(/\//g, "\\")
+        : rewritten;
+    if (normalizedValue === normalizedOld)
+        return toNewPrefixStyle(normalizedNew);
+    if (normalizedValue.startsWith(`${normalizedOld}/`)) {
+        return toNewPrefixStyle(`${normalizedNew}${normalizedValue.slice(normalizedOld.length)}`);
+    }
+    return value;
+}

package/dist/shared/pi-retry-settings.js

@@ -0,0 +1,23 @@
+/**
+ * Recommended Pi auto-retry settings for gateway rate limits.
+ *
+ * Work-hours gateways often enforce rolling windows (e.g. 100 req / 10 min).
+ * Pi's built-in default (2s / 4s / 8s) exhausts before the window recovers;
+ * a 60s base delay yields 1m → 2m → 4m … and tolerates transient 429s.
+ *
+ * Used by:
+ * - project / user `.pi` settings merge (`client-recovery`)
+ * - loop-agent Pi SDK executor (injected SettingsManager, independent of ~/.pi)
+ */
+export const PI_RECOMMENDED_RETRY = {
+    enabled: true,
+    maxRetries: 5,
+    /** First retry wait; subsequent attempts use exponential backoff. */
+    baseDelayMs: 60_000,
+    provider: {
+        /** Disable nested SDK provider retries; outer auto-retry owns the budget. */
+        maxRetries: 0,
+        maxRetryDelayMs: 60_000,
+    },
+};
+export const PI_RECOMMENDED_COMPACTION = { enabled: true };

package/dist/shared/playwright-cli-command-policy.js

@@ -0,0 +1,41 @@
+/**
+ * Neutral command-policy source shared by the structured Pi runtime and
+ * pre-execution frontend case checklist. Keep this list capability-only: argv
+ * and browser-safety validation remain owned by the executor.
+ */
+export const PLAYWRIGHT_CLI_ALLOWED_COMMANDS = [
+    "open",
+    "close",
+    "goto",
+    "snapshot",
+    "find",
+    "click",
+    "dblclick",
+    "fill",
+    "type",
+    "press",
+    "keydown",
+    "keyup",
+    "hover",
+    "select",
+    "check",
+    "uncheck",
+    "drag",
+    "drop",
+    "upload",
+    "go-back",
+    "go-forward",
+    "reload",
+    "dialog-accept",
+    "dialog-dismiss",
+    "resize",
+    "screenshot",
+    "pdf",
+    "console",
+    "requests",
+    "request",
+];
+const allowedCommandSet = new Set(PLAYWRIGHT_CLI_ALLOWED_COMMANDS);
+export function isPlaywrightCliCommand(value) {
+    return allowedCommandSet.has(value);
+}

package/dist/shared/preview.js

@@ -0,0 +1,39 @@
+const ENCODER = new TextEncoder();
+const DECODER = new TextDecoder();
+export function redactSecrets(text) {
+    return text
+        .replace(/\bBearer\s+[^\s"']+/gi, "Bearer ***")
+        .replace(/(\b[A-Z][A-Z0-9_]*=)[^\s]+/g, "$1***")
+        .replace(/(["']?(?:api[_-]?key|token|password|secret|authorization)["']?\s*[:=]\s*["']?)([^"'\s,}]+)/gi, "$1***");
+}
+export function truncateUtf8Preview(text, maxBytes = 4096) {
+    if (maxBytes <= 0)
+        return "";
+    const bytes = ENCODER.encode(text);
+    if (bytes.length <= maxBytes)
+        return text;
+    let prefixEnd = safeUtf8End(bytes, Math.max(0, maxBytes - 32));
+    for (let attempt = 0; attempt < 8; attempt += 1) {
+        const omittedBytes = bytes.length - prefixEnd;
+        const suffix = `…<truncated ${omittedBytes} bytes>`;
+        const suffixBytes = ENCODER.encode(suffix);
+        if (suffixBytes.length >= maxBytes) {
+            const suffixEnd = safeUtf8End(suffixBytes, maxBytes);
+            return DECODER.decode(suffixBytes.subarray(0, suffixEnd));
+        }
+        const nextPrefixEnd = safeUtf8End(bytes, maxBytes - suffixBytes.length);
+        if (nextPrefixEnd === prefixEnd) {
+            return DECODER.decode(bytes.subarray(0, prefixEnd)) + suffix;
+        }
+        prefixEnd = nextPrefixEnd;
+    }
+    const omittedBytes = bytes.length - prefixEnd;
+    return `${DECODER.decode(bytes.subarray(0, prefixEnd))}…<truncated ${omittedBytes} bytes>`;
+}
+function safeUtf8End(bytes, budget) {
+    let end = Math.min(bytes.length, Math.max(0, budget));
+    while (end > 0 && end < bytes.length && (bytes[end] & 0xc0) === 0x80) {
+        end -= 1;
+    }
+    return end;
+}

package/dist/shared/prompts.js

@@ -0,0 +1,26 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { isFeatureStudyTask } from './reference-context.js';
+export async function loadPrompt(repoRoot, step, taskConfig) {
+    const filename = resolvePromptFilename(step, taskConfig);
+    const promptPath = path.join(repoRoot, '.harness', 'prompts', filename);
+    try {
+        return await readFile(promptPath, 'utf-8');
+    }
+    catch {
+        if (filename !== `${step}.md`) {
+            return readFile(path.join(repoRoot, '.harness', 'prompts', `${step}.md`), 'utf-8');
+        }
+        throw new Error(`prompt not found: ${promptPath}`);
+    }
+}
+function resolvePromptFilename(step, taskConfig) {
+    if (!taskConfig || !isFeatureStudyTask(taskConfig)) {
+        return `${step}.md`;
+    }
+    if (step === 'analyze')
+        return 'feature-study-analyze.md';
+    if (step === 'plan')
+        return 'feature-study-plan.md';
+    return `${step}.md`;
+}