agentera 3.0.0-dev.4 → 3.0.0-dev.46

package/dist/core/atomicWriter.js

@@ -0,0 +1,20 @@
+import fs from "node:fs";
+export function writeFileAtomic(target, data, encoding = "utf8") {
+    const tmp = `${target}.tmp.${process.pid}.${Date.now()}`;
+    try {
+        if (Buffer.isBuffer(data))
+            fs.writeFileSync(tmp, data);
+        else
+            fs.writeFileSync(tmp, data, encoding);
+        fs.renameSync(tmp, target);
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(tmp);
+        }
+        catch {
+            // The stage may not exist or may already have been published.
+        }
+        throw err;
+    }
+}

package/dist/core/developmentChannel.js

@@ -0,0 +1 @@
+export const CANONICAL_DEVELOPMENT_CLI = "npx -y agentera@next";

package/dist/core/developmentInvocation.js

@@ -0,0 +1,374 @@
+import fs from "node:fs";
+import path from "node:path";
+import { CANONICAL_DEVELOPMENT_CLI } from "./developmentChannel.js";
+import { ENTITY_LIST_RUNTIME_FAMILIES, } from "../state/entityListRuntimeRegistry.js";
+import { runtimeOperationSpec, runtimeOperationSpecs, } from "../state/write/runtimeOperations.js";
+export const CANONICAL_DEVELOPMENT_INVOCATION = CANONICAL_DEVELOPMENT_CLI;
+const LOCAL_RUNTIME_INVOCATION = "agentera";
+export class DevelopmentInvocationError extends Error {
+    classification;
+    constructor(classification, reason) {
+        super(`development invocation rejected [${classification}]: ${reason}`);
+        this.name = "DevelopmentInvocationError";
+        this.classification = classification;
+    }
+}
+export const DEVELOPMENT_RUNTIME_REQUIRED_FILES = Object.freeze([
+    "package.json",
+    "README.md",
+    "LICENSE",
+    "dist/bin/agentera.js",
+    "bundle/.agentera-npx-bundle.json",
+    "bundle/registry.json",
+    "bundle/skills/agentera/SKILL.md",
+    "bundle/references/adapters/package-registry.yaml",
+]);
+export const DEVELOPMENT_CHILD_ENV_ALLOWLIST = Object.freeze([
+    "AGENTERA_BOOTSTRAP_SOURCE_ROOT",
+    "AGENTERA_HOME",
+    "AGENTERA_UPDATE_CHANNEL",
+    "DO_NOT_TRACK",
+    "HOME",
+    "LANG",
+    "LC_ALL",
+    "PATH",
+    "TMPDIR",
+    "XDG_CACHE_HOME",
+    "XDG_CONFIG_HOME",
+    "XDG_DATA_HOME",
+    "XDG_STATE_HOME",
+]);
+export const DEVELOPMENT_CHILD_PATH = process.platform === "win32"
+    ? path.dirname(process.execPath)
+    : "/usr/bin:/bin";
+function developmentCommand(argumentsText) {
+    return `${CANONICAL_DEVELOPMENT_INVOCATION} ${argumentsText}`;
+}
+const profileGroundingCommand = developmentCommand("report profile-grounding --format json");
+const GLOSSARY_PROJECTIONS = {
+    "profile_output.command": developmentCommand("report profile-glossary"),
+    "profile_grounding.command": profileGroundingCommand,
+    "profile_grounding.repair": `Use the Profile capability to repair or regenerate PROFILE.md, then retry \`${profileGroundingCommand}\`; no profile bytes were changed.`,
+    "profile_grounding.absent": `Use the Profile capability to generate PROFILE.md, then retry ${profileGroundingCommand}.`,
+    "advice.command": developmentCommand("report glossary-advice --input REQUEST --format json"),
+};
+function invalid(reason) {
+    throw new Error(`invalid development command projection: ${reason}`);
+}
+function runtimeValue(source) {
+    return source.split(CANONICAL_DEVELOPMENT_INVOCATION).join(LOCAL_RUNTIME_INVOCATION);
+}
+function assertExact(value, owner, source) {
+    if (typeof value !== "string" || value !== source)
+        invalid(`'${owner}' does not match its code-owned exact source value`);
+    return runtimeValue(source);
+}
+function commandWords(command) {
+    const words = [];
+    let value = "";
+    let started = false;
+    let quote = null;
+    for (let index = 0; index < command.length; index += 1) {
+        const character = command[index];
+        if (quote) {
+            if (character === quote) {
+                quote = null;
+                started = true;
+                continue;
+            }
+            if (quote === '"' && character === "\\") {
+                const escaped = command[++index];
+                if (escaped === undefined)
+                    invalid("trailing escape");
+                if (escaped === "\n" || escaped === "\r")
+                    invalid("shell continuation is not allowed");
+                value += escaped;
+                started = true;
+                continue;
+            }
+            if (quote === '"' && (character === "`" || (character === "$" && command[index + 1] === "(")))
+                invalid("command substitution is not allowed");
+            value += character;
+            started = true;
+            continue;
+        }
+        if (character === "\n" || character === "\r")
+            invalid("line separators are allowed only inside one quoted argument");
+        if (/\s/u.test(character)) {
+            if (started) {
+                words.push({ value });
+                value = "";
+                started = false;
+            }
+            continue;
+        }
+        if (character === "'" || character === '"') {
+            quote = character;
+            started = true;
+            continue;
+        }
+        if (character === "\\") {
+            const escaped = command[++index];
+            if (escaped === undefined)
+                invalid("trailing escape");
+            if (escaped === "\n" || escaped === "\r")
+                invalid("shell continuation is not allowed");
+            value += escaped;
+            started = true;
+            continue;
+        }
+        if (";&|<>()`".includes(character) || (character === "$" && command[index + 1] === "("))
+            invalid("composition, redirection, substitution, and grouping are not allowed");
+        value += character;
+        started = true;
+    }
+    if (quote)
+        invalid("unclosed quote");
+    if (started)
+        words.push({ value });
+    return words;
+}
+function parsedDevelopmentWords(command, classification) {
+    try {
+        return commandWords(command).map(({ value }) => value);
+    }
+    catch (error) {
+        throw new DevelopmentInvocationError(classification, error instanceof Error ? error.message : String(error));
+    }
+}
+function hasDevelopmentPrefix(words) {
+    return words[0] === "npx" && words[1] === "-y" && words[2] === "agentera@next";
+}
+/**
+ * Bind an untrusted command specification to one exact code-owned development
+ * command before a caller crosses a process boundary. The returned argv omits
+ * npx and the package selector because callers execute a verified local bin.
+ */
+export function bindDevelopmentInvocation(identity, candidate) {
+    if (!/^[a-z0-9][a-z0-9_.:-]*$/u.test(identity.owner)) {
+        throw new DevelopmentInvocationError("invalid_authority", "owner is not a canonical identity");
+    }
+    const authorityWords = parsedDevelopmentWords(identity.source, "invalid_authority");
+    if (!hasDevelopmentPrefix(authorityWords) || authorityWords.length === 3) {
+        throw new DevelopmentInvocationError("invalid_authority", `authority must be one complete ${CANONICAL_DEVELOPMENT_INVOCATION} command`);
+    }
+    const candidateWords = parsedDevelopmentWords(candidate, "malformed");
+    if (!hasDevelopmentPrefix(candidateWords)) {
+        throw new DevelopmentInvocationError("wrong_channel", `command must begin with the exact ${CANONICAL_DEVELOPMENT_INVOCATION} argv`);
+    }
+    if (candidate !== identity.source) {
+        throw new DevelopmentInvocationError("not_exact", `command does not match code-owned identity '${identity.owner}'`);
+    }
+    return Object.freeze({
+        owner: identity.owner,
+        source: identity.source,
+        argv: Object.freeze(candidateWords.slice(3)),
+    });
+}
+/** Fail closed before process start when a constructed runtime is incomplete. */
+export function assertDevelopmentRuntimeSurface(root) {
+    for (const relative of DEVELOPMENT_RUNTIME_REQUIRED_FILES) {
+        const target = path.join(root, relative);
+        let stat;
+        try {
+            stat = fs.lstatSync(target);
+        }
+        catch {
+            throw new DevelopmentInvocationError("invalid_authority", `runtime is missing required file '${relative}'`);
+        }
+        if (!stat.isFile()) {
+            throw new DevelopmentInvocationError("invalid_authority", `runtime required file '${relative}' is not a regular file`);
+        }
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+    }
+    catch {
+        throw new DevelopmentInvocationError("invalid_authority", "package manifest is not valid JSON");
+    }
+    if (manifest.bin?.agentera !== "dist/bin/agentera.js") {
+        throw new DevelopmentInvocationError("invalid_authority", "package bin declaration is not canonical");
+    }
+    const files = manifest.files;
+    if (!Array.isArray(files) || !["dist", "bundle"].every((entry) => files.includes(entry))) {
+        throw new DevelopmentInvocationError("invalid_authority", "package files declaration omits dist or bundle");
+    }
+    const bin = path.join(root, "dist/bin/agentera.js");
+    if ((fs.statSync(bin).mode & 0o111) === 0) {
+        throw new DevelopmentInvocationError("invalid_authority", "package bin is not executable");
+    }
+    return bin;
+}
+/** Keep only reviewed process inputs; PATH is always code-owned. */
+export function scrubDevelopmentChildEnvironment(inherited, explicit) {
+    const result = {};
+    for (const key of DEVELOPMENT_CHILD_ENV_ALLOWLIST) {
+        if (key === "PATH")
+            continue;
+        const value = explicit[key] ?? inherited[key];
+        if (value !== undefined)
+            result[key] = value;
+    }
+    result.PATH = DEVELOPMENT_CHILD_PATH;
+    return result;
+}
+function fieldValueIssue(field, value) {
+    if (field.validValues && !field.validValues.includes(value))
+        return "invalid value domain";
+    if (field.kind === "boolean" && value !== "true" && value !== "false")
+        return "invalid boolean";
+    if (field.kind === "integer" && !/^-?(?:0|[1-9][0-9]*)$/u.test(value))
+        return "invalid integer";
+    if (field.kind === "date" && !/^\d{4}-\d{2}-\d{2}$/u.test(value))
+        return "invalid date";
+    if (field.kind === "datetime" && !/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}$/u.test(value))
+        return "invalid datetime";
+    return undefined;
+}
+function validateOperationExample(spec, template) {
+    if (template.runtime !== runtimeValue(template.source))
+        invalid(`${spec.artifact}.${spec.verb} has a non-canonical runtime example`);
+    if (!template.source.startsWith(`${CANONICAL_DEVELOPMENT_INVOCATION} `))
+        invalid(`${spec.artifact}.${spec.verb} example has no canonical prefix`);
+    const words = commandWords(template.source).map(({ value }) => value);
+    const prefix = ["npx", "-y", "agentera@next", "state", spec.artifact, spec.verb];
+    if (!prefix.every((word, index) => words[index] === word))
+        invalid(`${spec.artifact}.${spec.verb} example has the wrong operation family`);
+    const fields = new Map(spec.fields.map((field) => [field.flag, field]));
+    const seen = new Map();
+    let input = false;
+    let format = false;
+    for (let index = prefix.length; index < words.length;) {
+        const flag = words[index++];
+        if (!flag.startsWith("--") || flag === "--")
+            invalid(`${spec.artifact}.${spec.verb} example has an extra positional argument`);
+        const count = (seen.get(flag) ?? 0) + 1;
+        seen.set(flag, count);
+        if (flag === "--dry-run" || flag === "--force") {
+            if (count > 1)
+                invalid(`${spec.artifact}.${spec.verb} example repeats ${flag}`);
+            if (flag === "--force" && !spec.allowForce)
+                invalid(`${spec.artifact}.${spec.verb} example uses unauthorized --force`);
+            continue;
+        }
+        const bareBoolean = fields.get(flag);
+        if (bareBoolean?.kind === "boolean" && (words[index] === undefined || words[index].startsWith("--"))) {
+            if (!bareBoolean.repeatable && count > 1)
+                invalid(`${spec.artifact}.${spec.verb} example repeats ${flag}`);
+            continue;
+        }
+        const argument = words[index++];
+        if (argument === undefined || argument.startsWith("--"))
+            invalid(`${spec.artifact}.${spec.verb} ${flag} needs one non-option value`);
+        if (flag === "--format") {
+            if (count > 1 || !spec.projection.formatValues.includes(argument))
+                invalid(`${spec.artifact}.${spec.verb} example has an invalid format`);
+            format = true;
+            continue;
+        }
+        if (flag === "--input") {
+            if (count > 1 || spec.inputMode !== "structured")
+                invalid(`${spec.artifact}.${spec.verb} example has an unauthorized input`);
+            input = true;
+            continue;
+        }
+        const field = fields.get(flag);
+        if (!field)
+            invalid(`${spec.artifact}.${spec.verb} example has unauthorized flag ${flag}`);
+        if (!field.repeatable && count > 1)
+            invalid(`${spec.artifact}.${spec.verb} example repeats ${flag}`);
+        const issue = fieldValueIssue(field, argument);
+        if (issue)
+            invalid(`${spec.artifact}.${spec.verb} example has ${issue} for ${flag}`);
+    }
+    if (!format)
+        invalid(`${spec.artifact}.${spec.verb} example omits --format`);
+    if (spec.inputMode === "structured" && !input)
+        invalid(`${spec.artifact}.${spec.verb} example omits --input`);
+    for (const field of spec.fields) {
+        if (field.required && !seen.has(field.flag))
+            invalid(`${spec.artifact}.${spec.verb} example omits ${field.flag}`);
+    }
+}
+const validatedOperations = new Set();
+function exactOperation(artifact, verb) {
+    const spec = runtimeOperationSpec(artifact, verb);
+    if (!spec)
+        invalid(`operation '${artifact}.${verb}' is not code-owned`);
+    const key = `${artifact}.${verb}`;
+    if (!validatedOperations.has(key)) {
+        if (spec.projection.recovery.runtime !== runtimeValue(spec.projection.recovery.source))
+            invalid(`${key} has a non-canonical runtime recovery`);
+        if (spec.projection.examples.length === 0)
+            invalid(`${key} has no code-owned example`);
+        for (const example of spec.projection.examples)
+            validateOperationExample(spec, example);
+        validatedOperations.add(key);
+    }
+    return spec;
+}
+export function projectRuntimeOperationRecovery(value, artifact, verb) {
+    const spec = exactOperation(artifact, verb);
+    return assertExact(value, `mutation.${artifact}.${verb}.recovery`, spec.projection.recovery.source);
+}
+export function projectRuntimeOperationExamples(value, artifact, verb) {
+    const spec = exactOperation(artifact, verb);
+    if (!Array.isArray(value) || value.length !== spec.projection.examples.length)
+        invalid(`'mutation.${artifact}.${verb}.examples' does not match its code-owned exact source list`);
+    return spec.projection.examples.map((template, index) => assertExact(value[index], `mutation.${artifact}.${verb}.examples[${index}]`, template.source));
+}
+export function projectEntityDevelopmentValue(value, familyKey, field) {
+    const family = ENTITY_LIST_RUNTIME_FAMILIES.find(({ key }) => key === familyKey);
+    const source = family?.projection[field];
+    if (!family || typeof source !== "string")
+        invalid(`retrieval.${familyKey}.${field} is not a code-owned projection`);
+    return assertExact(value, `retrieval.${familyKey}.${field}`, source);
+}
+export function projectGlossaryDevelopmentValue(value, owner) {
+    return assertExact(value, `glossary.${owner}`, GLOSSARY_PROJECTIONS[owner]);
+}
+export function developmentProjectionOwners() {
+    const owners = [];
+    for (const spec of runtimeOperationSpecs()) {
+        exactOperation(spec.artifact, spec.verb);
+        owners.push({
+            owner: `mutation.${spec.artifact}.${spec.verb}.recovery`,
+            family: "mutation",
+            ...spec.projection.recovery,
+            consumers: ["schema", "help", "explain"],
+        });
+        spec.projection.examples.forEach((example, index) => owners.push({
+            owner: `mutation.${spec.artifact}.${spec.verb}.examples[${index}]`,
+            family: "mutation",
+            ...example,
+            consumers: ["schema", "help", "explain", "parity"],
+        }));
+    }
+    for (const family of ENTITY_LIST_RUNTIME_FAMILIES) {
+        for (const field of ["list", "get", "example", "bareRecovery"]) {
+            const source = family.projection[field];
+            if (typeof source !== "string")
+                continue;
+            owners.push({
+                owner: `retrieval.${family.key}.${field}`,
+                family: "retrieval",
+                source,
+                runtime: runtimeValue(source),
+                consumers: ["schema", "help", "runtime_failure"],
+            });
+        }
+    }
+    for (const [owner, source] of Object.entries(GLOSSARY_PROJECTIONS)) {
+        owners.push({
+            owner: `glossary.${owner}`,
+            family: "glossary",
+            source,
+            runtime: runtimeValue(source),
+            consumers: ["schema", "help", "runtime_contract"],
+        });
+    }
+    if (new Set(owners.map(({ owner }) => owner)).size !== owners.length)
+        invalid("code-owned projection owner identities are not unique");
+    return owners;
+}

package/dist/core/difflib.js

@@ -271,4 +271,3 @@ export function unifiedDiff(a, b, fromfile = "", tofile = "", fromfiledate = "",
 export function splitLinesKeepEnds(text) {
     return text.match(/[^\n]*\n|[^\n]+/g) ?? [];
 }
-//# sourceMappingURL=difflib.js.map

package/dist/core/envPaths.js

@@ -0,0 +1,20 @@
+import os from "node:os";
+import path from "node:path";
+import { expanduser } from "./paths.js";
+/** Canonical profile-dir env var (v3). Matches artifact-registry-interface-model.yaml profile.path_template.env_precedence[0]. */
+export const AGENTERA_PROFILE_DIR_ENV = "AGENTERA_PROFILE_DIR";
+/** Deprecated v2 alias. Matches artifact-registry-interface-model.yaml profile.path_template.env_precedence[1]. */
+export const PROFILERA_PROFILE_DIR_ENV = "PROFILERA_PROFILE_DIR";
+/** v3 name wins; v2 name is the migration-window fallback only. */
+export function resolveProfileDirOverride(env) {
+    return env[AGENTERA_PROFILE_DIR_ENV] ?? env[PROFILERA_PROFILE_DIR_ENV];
+}
+/** True when source text references the legacy name without the canonical v3 name (unmigrated schema literal). */
+export function pluginSourceHasUnmigratedProfileDirSchema(text) {
+    return text.includes(PROFILERA_PROFILE_DIR_ENV) && !text.includes(AGENTERA_PROFILE_DIR_ENV);
+}
+/** Expand XDG_DATA_HOME the same way installRoot.ts does. */
+export function resolveXdgDataHome(env, home = os.homedir()) {
+    const xdg = env.XDG_DATA_HOME;
+    return xdg ? expanduser(xdg) : path.join(expanduser(home), ".local", "share");
+}

package/dist/core/jsonValue.js

@@ -0,0 +1,5 @@
+/**
+ * Canonical JSON/value shapes for CLI structured output and YAML artifact IO.
+ * Prefer these types at module export boundaries; narrow with casts only at IO edges.
+ */
+export {};

package/dist/core/paths.js

@@ -47,4 +47,3 @@ export function isFile(p) {
         return false;
     }
 }
-//# sourceMappingURL=paths.js.map

package/dist/core/pyjson.js

@@ -2,9 +2,26 @@
  * Python-faithful JSON string helpers.
  *
  * Mirrors CPython's `json` encoder for the cases the CLI/hook surfaces need:
- * ensure_ascii escaping and the default inline separators (", " / ": ") with
- * insertion-ordered object keys (no sort_keys).
+ * ensure_ascii escaping and the default inline separators (", " / ": ").
+ * `pyJsonInline` / `pyJsonIndent` keep insertion-ordered object keys; sorted
+ * variants match `json.dumps(..., sort_keys=True)` for doctor parity.
  */
+function formatScalar(value, hook) {
+    const hooked = hook?.(value);
+    if (hooked !== undefined)
+        return hooked;
+    if (value === null || value === undefined)
+        return "null";
+    if (value === true)
+        return "true";
+    if (value === false)
+        return "false";
+    if (typeof value === "number")
+        return String(value);
+    if (typeof value === "string")
+        return pyJsonString(value);
+    return null;
+}
 /** Mirror Python json encoder string escaping with ensure_ascii=True. */
 export function pyJsonString(str) {
     let out = '"';
@@ -98,4 +115,51 @@ export function pyJsonIndent(value, indent = 2, level = 0) {
     }
     return "null";
 }
-//# sourceMappingURL=pyjson.js.map
+/**
+ * Mirror Python `json.dumps(value, sort_keys=True)` with default options:
+ * sorted object keys, separators (", " / ": "), ensure_ascii=True.
+ */
+export function pyJsonDumps(value, hook) {
+    const scalar = formatScalar(value, hook);
+    if (scalar !== null)
+        return scalar;
+    if (Array.isArray(value))
+        return "[" + value.map((v) => pyJsonDumps(v, hook)).join(", ") + "]";
+    if (typeof value === "object") {
+        const keys = Object.keys(value).sort();
+        return ("{" +
+            keys
+                .map((k) => `${pyJsonString(k)}: ${pyJsonDumps(value[k], hook)}`)
+                .join(", ") +
+            "}");
+    }
+    return "null";
+}
+/**
+ * Mirror Python `json.dumps(value, indent=2, sort_keys=True)` with default
+ * options: sorted object keys, ensure_ascii=True, 2-space indentation.
+ */
+export function pyJsonIndentSorted(value, indent = 2, level = 0, hook) {
+    const pad = " ".repeat(indent * (level + 1));
+    const closePad = " ".repeat(indent * level);
+    const scalar = formatScalar(value, hook);
+    if (scalar !== null)
+        return scalar;
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return "[]";
+        const items = value.map((v) => pad + pyJsonIndentSorted(v, indent, level + 1, hook));
+        return "[\n" + items.join(",\n") + "\n" + closePad + "]";
+    }
+    if (typeof value === "object") {
+        const keys = Object.keys(value).sort();
+        if (keys.length === 0)
+            return "{}";
+        const items = keys.map((k) => pad +
+            pyJsonString(k) +
+            ": " +
+            pyJsonIndentSorted(value[k], indent, level + 1, hook));
+        return "{\n" + items.join(",\n") + "\n" + closePad + "}";
+    }
+    return "null";
+}

package/dist/core/shell.js

@@ -0,0 +1,4 @@
+/** Quote one argument for a POSIX shell command without permitting expansion. */
+export function shellQuoteArgument(value) {
+    return `'${String(value).replaceAll("'", "'\\''")}'`;
+}

package/dist/core/skillIdentity.js

@@ -0,0 +1,23 @@
+import YAML from "yaml";
+export function declaresAgenteraSkill(text) {
+    const lines = text.split(/\r?\n/);
+    if (lines[0] !== "---")
+        return false;
+    const closing = lines.indexOf("---", 1);
+    if (closing === -1)
+        return false;
+    const metadataLines = lines.slice(1, closing);
+    try {
+        const document = YAML.parseDocument(metadataLines.join("\n"));
+        if (document.errors.length > 0)
+            return false;
+        const metadata = document.toJS();
+        if (metadata === null || typeof metadata !== "object" || Array.isArray(metadata))
+            return false;
+    }
+    catch {
+        return false;
+    }
+    const names = metadataLines.filter((line) => /^name\s*:/.test(line));
+    return names.length === 1 && names[0] === "name: agentera";
+}

package/dist/core/sourceRoot.js

@@ -40,9 +40,9 @@ function walkUp(start) {
 }
 /**
  * Resolve the Agentera "app source root" that holds skills/, scripts/, schemas,
- * references/, etc. Mirrors the bootstrap precedence in src/agentera/__main__.py:
- * AGENTERA_BOOTSTRAP_SOURCE_ROOT wins, then a walk-up from the module location,
- * then a walk-up from the working directory.
+ * references/, etc. AGENTERA_BOOTSTRAP_SOURCE_ROOT wins, followed by a
+ * checkout containing the executing module, a self-contained package bundle,
+ * and finally a walk-up from the working directory.
  */
 export function resolveSourceRoot(env = process.env) {
     const configured = env[BOOTSTRAP_SOURCE_ROOT_ENV];
@@ -54,19 +54,16 @@ export function resolveSourceRoot(env = process.env) {
     if (fromModule) {
         return fromModule;
     }
+    // A packaged CLI must keep runtime code and app data on the same version.
+    // Otherwise an Agentera checkout used as cwd can override the package bundle.
+    const bundled = path.resolve(moduleDir, "..", "..", "bundle");
+    if (isNpxBundleRoot(bundled)) {
+        return bundled;
+    }
     const fromCwd = walkUp(process.cwd());
     if (fromCwd) {
         return fromCwd;
     }
-    // Self-contained npm package: app data is staged under <packageRoot>/bundle
-    // (see scripts/copy-bundle.mjs). This makes `npx agentera` work with no repo
-    // checkout and no AGENTERA_HOME. Only reached when no checkout/app-home is
-    // found, so it never overrides a real checkout, installed app, or cwd match.
-    const bundled = path.resolve(moduleDir, "..", "..", "bundle");
-    if (hasSourceMarker(bundled)) {
-        return bundled;
-    }
     // Last resort: package root two levels above dist/core.
     return path.resolve(moduleDir, "..", "..");
 }
-//# sourceMappingURL=sourceRoot.js.map

package/dist/core/text.js

@@ -0,0 +1,10 @@
+export function truncateCodePoints(value, maxChars, suffix = "", trimTrailingWhitespace = false) {
+    const characters = Array.from(value);
+    if (characters.length <= maxChars)
+        return value;
+    const suffixCharacters = Array.from(suffix).slice(0, maxChars);
+    const prefix = characters
+        .slice(0, Math.max(0, maxChars - suffixCharacters.length))
+        .join("");
+    return `${trimTrailingWhitespace ? prefix.replace(/\s+$/, "") : prefix}${suffixCharacters.join("")}`;
+}

package/dist/core/toml.js

@@ -8,4 +8,3 @@ export function parseToml(text) {
 export function loadTomlFile(path) {
     return parseToml(fs.readFileSync(path, "utf8"));
 }
-//# sourceMappingURL=toml.js.map

package/dist/core/yaml.js

@@ -22,4 +22,11 @@ export function loadYamlMappingFile(path) {
 export function parseYaml(text) {
     return YAML.parse(text);
 }
-//# sourceMappingURL=yaml.js.map
+/** Serialize a YAML mapping with stable block-style prose and insertion-order keys. */
+export function dumpYamlMapping(doc) {
+    return YAML.stringify(doc, {
+        blockQuote: "literal",
+        collectionStyle: "block",
+        lineWidth: 0,
+    });
+}