botmux 3.14.0 → 3.16.0

package/dist/adapters/backend/mojo-types.js

@@ -0,0 +1,682 @@
+/**
+ * Types for the mojo (@byted/mojo) backend.
+ *
+ * Kept in a separate module so `mojo.ts` (the CLI adapter) and
+ * `mojo-backend.ts` can share them without a cycle, and so the event shapes —
+ * which were established empirically against @byted/mojo 1.0.10 — are
+ * documented in one place.
+ */
+/**
+ * Keys that are INTERNAL plumbing and must never be accepted from user config.
+ *
+ * Each has a platform-wide source of truth that is frozen onto the session at
+ * creation (`Session.agentFrozen`), so a second entry point inside the `mojo`
+ * block would let live edits override a frozen identity — e.g. cancelling an
+ * orphaned remote session through a binary or wrapper the bot only gained
+ * afterwards, reaching the wrong gateway or tenant.
+ *
+ * bots.json parsing and `/config set mojo` both reject these outright rather
+ * than dropping them silently, because a silent drop reads as "applied".
+ */
+export const MOJO_INTERNAL_CONFIG_KEYS = [
+    'bin',
+    'cwd',
+    'model',
+    'disableCliBypass',
+    'wrapperCli',
+    'resumeCliSessionId',
+    'extraCliArgs',
+    'builtinSkillBlock',
+];
+/** The top-level bot field that owns each internal key, for error messages. */
+export const MOJO_INTERNAL_KEY_OWNER = {
+    bin: 'cliPathOverride',
+    cwd: 'workingDir',
+    model: 'model',
+    disableCliBypass: 'disableCliBypass',
+    wrapperCli: 'wrapperCli',
+    resumeCliSessionId: '(managed by botmux)',
+    extraCliArgs: 'CLI_EXTRA_ARGS',
+    builtinSkillBlock: 'skillInjection',
+};
+/**
+ * Control-plane fields that decide WHERE and AS WHOM a session executes:
+ * cloud-vs-host execution, the API endpoint, the PPE profile, and the
+ * workspace/agent it is routed to.
+ *
+ * These are frozen onto the session at creation (see MojoSessionIdentity). A live
+ * bot edit must never retroactively move an existing session between execution
+ * modes or tenants — a cold resume would otherwise resume, or a `/close` cancel,
+ * against a different endpoint than the one that created the remote session.
+ *
+ * Credentials (`jwt` / `jwtEnv` / `env`) are deliberately NOT here: they must
+ * stay live so a rotated token takes effect, and a plaintext JWT must not be
+ * persisted into session state.
+ */
+export const MOJO_IDENTITY_KEYS = [
+    'cloud',
+    'localDaemon',
+    'baseUrl',
+    'ppeEnv',
+    'workspaceId',
+    'agentId',
+];
+/**
+ * The child's effective environment, layered lowest → highest precedence:
+ *
+ *   base (worker-supplied session env / process env)
+ *   → bot `env`      (bots.json top-level, already sanitized)
+ *   → `mojo.env`     (bots.json mojo block — highest)
+ *
+ * This exists so the launcher and the backend cannot disagree. They previously
+ * layered independently and the launcher omitted `mojo.env` entirely, so a
+ * wrapper binary was resolved against a PATH the child never actually ran with:
+ * a same-named program earlier on the bot-level PATH shadowed the one the
+ * operator pinned in `mojo.env.PATH`. For a wrapper that carries auth or acts
+ * as a gateway, that means executing under the wrong identity.
+ *
+ * Callers that need control-plane hygiene must still strip
+ * MOJO_CONTROL_ENV_KEYS afterwards; this helper only fixes the layering.
+ */
+export function buildEffectiveChildEnv(layers) {
+    return {
+        ...(layers.base ?? {}),
+        ...(layers.botEnv ?? {}),
+        ...(layers.mojoEnv ?? {}),
+    };
+}
+/**
+ * Environment variables that carry the SAME control-plane decisions as the frozen
+ * identity keys. They exist because the mojo CLI reads its endpoint/profile from
+ * env, which makes `env` a back door around the freeze: a live
+ * `env: { AGENT_BASE_URL: ... }` would move an existing session to another tenant
+ * even though `baseUrl` itself is frozen.
+ *
+ * buildEnv() therefore DELETES all of these after merging and re-derives them
+ * from the (frozen) config alone. `X_JWT_TOKEN` is deliberately absent: a rotated
+ * credential must keep taking effect.
+ */
+export const MOJO_CONTROL_ENV_KEYS = [
+    'AGENT_BASE_URL',
+    'MOJO_PPE_ENV',
+    'AGENT_LOCAL_DAEMON',
+];
+/**
+ * The one env var name the mojo CLI actually reads its credential from.
+ *
+ * `jwtEnv` only tells the DAEMON where to look up the value; buildEnv() always
+ * hands the resolved token to the child as this name. That asymmetry is why the
+ * remote-execution proof exempts this fixed name and never `jwtEnv` — see
+ * mojoUnprovableEnvKeys.
+ */
+export const MOJO_CANONICAL_JWT_ENV_KEY = 'X_JWT_TOKEN';
+/** True only when the remote session is provably gone (cancelled or finished). */
+export function isMojoRemoteGone(outcome) {
+    return outcome.kind === 'cancelled' || outcome.kind === 'already_terminal';
+}
+/**
+ * Pick just the control-plane identity out of a (already normalized) config.
+ * Absent keys are omitted rather than stored as undefined, so the frozen record
+ * stays a faithful snapshot of what was actually configured.
+ */
+export function pickMojoSessionIdentity(cfg) {
+    const out = {};
+    if (!cfg)
+        return out;
+    for (const key of MOJO_IDENTITY_KEYS) {
+        const value = cfg[key];
+        if (value !== undefined)
+            out[key] = value;
+    }
+    return out;
+}
+/**
+ * Which control-plane keys differ between the frozen snapshot and live config,
+ * for the log line explaining why a session kept its original control plane.
+ * Empty array = identical.
+ *
+ * Returns KEY NAMES ONLY, never values. `baseUrl` is a URL that may legitimately
+ * carry userinfo (`https://user:pass@host`) or a signed query
+ * (`?sig=<token>`) — the URL validator allows both, because they are valid
+ * endpoints — so logging old/new values verbatim would write credentials into the
+ * daemon log. The key name is all an operator needs to know what changed; the
+ * value is already in their own config.
+ */
+export function diffMojoSessionIdentity(frozen, live) {
+    const changes = [];
+    for (const key of MOJO_IDENTITY_KEYS) {
+        const a = frozen[key];
+        const b = live[key];
+        if (a === b)
+            continue;
+        // Booleans are not secrets and the transition is the whole point
+        // (cloud→host execution is the dangerous one), so those are shown.
+        changes.push(typeof a === 'boolean' || typeof b === 'boolean'
+            ? `${key}: ${String(a)} → ${String(b)}`
+            : key);
+    }
+    return changes;
+}
+/**
+ * Combine the user's `mojo` block with the platform-owned launch identity into
+ * the ONE config both the worker (live session) and the daemon (workerless
+ * `/close`) run on.
+ *
+ * Sharing this matters: the daemon cancels an orphaned session WITHOUT a worker,
+ * so it never calls spawn() and cannot pick these up from SpawnOpts. Building
+ * the config only in the worker meant a bot running fine on a custom binary /
+ * per-bot JWT could not be cancelled once its worker died — leaving the remote
+ * session burning cloud sandbox time while still holding injected credentials.
+ *
+ * There is no precedence question to answer here: the launch identity has EXACTLY
+ * one source (`generic`, which callers populate from the session's frozen
+ * values). Anything the user put under those keys in the `mojo` block is stripped
+ * — both config entry points reject them, so reaching this function with one set
+ * means a hand-edited file, and honouring it would let a live edit override a
+ * frozen session identity.
+ */
+export function buildEffectiveMojoConfig(mojoBlock, generic) {
+    const block = { ...(mojoBlock ?? {}) };
+    for (const key of MOJO_INTERNAL_CONFIG_KEYS)
+        delete block[key];
+    const merged = block;
+    const bin = emptyToUndefined(generic.cliPathOverride);
+    if (bin !== undefined)
+        merged.bin = bin;
+    if (generic.workingDir !== undefined)
+        merged.cwd = generic.workingDir;
+    const model = emptyToUndefined(generic.model);
+    if (model !== undefined)
+        merged.model = model;
+    if (generic.disableCliBypass !== undefined) {
+        merged.disableCliBypass = generic.disableCliBypass;
+    }
+    // Per-bot env is the LOWER layer: an explicit `mojo.env` entry wins. This one
+    // IS a genuine two-source merge — `mojo.env` has no top-level equivalent.
+    if (generic.env || merged.env) {
+        merged.env = { ...(generic.env ?? {}), ...(merged.env ?? {}) };
+    }
+    if (generic.resumeCliSessionId !== undefined) {
+        merged.resumeCliSessionId = generic.resumeCliSessionId;
+    }
+    const wrapperCli = emptyToUndefined(generic.wrapperCli);
+    if (wrapperCli !== undefined)
+        merged.wrapperCli = wrapperCli;
+    if (generic.extraCliArgs && generic.extraCliArgs.length > 0) {
+        merged.extraCliArgs = [...generic.extraCliArgs];
+    }
+    const builtinSkillBlock = emptyToUndefined(generic.builtinSkillBlock);
+    if (builtinSkillBlock !== undefined)
+        merged.builtinSkillBlock = builtinSkillBlock;
+    return merged;
+}
+/** Treat a blank/whitespace-only override as unset. */
+function emptyToUndefined(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+}
+/**
+ * CLI flags that carry platform-owned decisions: the control plane, the execution
+ * mode, the approval bypass, the model, and the resume lineage.
+ *
+ * `CLI_EXTRA_ARGS` is appended AFTER the backend's own flags so an operator can
+ * override behaviour knobs (that is the documented contract), but with
+ * last-value-wins parsing that also let it override these — making env a second
+ * entry point for the very identity that is frozen per session. They are rejected
+ * instead.
+ *
+ * Long forms only: the mojo CLI has no short aliases for any of these, and
+ * `-r` is covered separately because it is the resume lineage.
+ */
+const MOJO_RESERVED_CLI_FLAGS = new Set([
+    '--workspace-id',
+    '--agent-id',
+    '--cloud',
+    '--no-cloud',
+    '--model',
+    '--yolo',
+    '--no-yolo',
+    '--resume',
+    '-r',
+    '--continue',
+    '-c',
+    '--background',
+    '--output-format',
+    '--include-partial',
+]);
+/**
+ * Reject platform-owned flags in operator-supplied extra args.
+ *
+ * Handles `--flag value`, `--flag=value` and the bare boolean form, since all
+ * three reach the CLI identically. Returns the offending flags, empty when clean.
+ */
+export function findReservedMojoCliFlags(args) {
+    const offending = [];
+    for (const arg of args) {
+        if (!arg.startsWith('-'))
+            continue;
+        // `--flag=value` and `--flag value` are the same flag to the CLI.
+        const flag = arg.includes('=') ? arg.slice(0, arg.indexOf('=')) : arg;
+        if (MOJO_RESERVED_CLI_FLAGS.has(flag) && !offending.includes(flag)) {
+            offending.push(flag);
+        }
+    }
+    return offending;
+}
+/**
+ * Can this mojo session prove it executes nothing locally?
+ *
+ * A launch prefix (wrapperCli) breaks the proof: it runs BEFORE the binary and
+ * can rewrite the very environment the decision depends on — `env
+ * AGENT_LOCAL_DAEMON=1 mojo` re-enables host execution after buildEnv() set it to
+ * 0, and buildEnv cannot defend against it because the prefix is applied later.
+ * Inspecting the wrapper string is not enough either: a wrapper may be a script
+ * that sets the variable internally.
+ *
+ * So a wrapper makes the session unprovable, and the local sandbox stays engaged.
+ * The launcher's ENV is treated exactly the same way, and for the same reason —
+ * see mojoUnprovableEnvKeys.
+ */
+export function mojoUnprovableEnvKeys(
+// `jwtEnv` is accepted (callers spread a whole config in) but deliberately
+// IGNORED — see the exemption note below. Keep it in the signature so those
+// spreads keep type-checking; do NOT read it.
+cfg) {
+    const keys = Object.keys(cfg?.env ?? {});
+    if (keys.length === 0)
+        return [];
+    // ALLOWLIST, deliberately: the set of variables that can redirect execution
+    // (PATH, NODE_OPTIONS, LD_PRELOAD, LD_LIBRARY_PATH, DYLD_*, …) cannot be
+    // enumerated completely — the same reason `env` is not live-patchable, see
+    // MOJO_LIVE_PATCH_KEYS below. So anything NOT known-harmless voids the proof.
+    //
+    // The exemption is the FIXED canonical name and nothing else. It must never be
+    // derived from `jwtEnv`, because that made the allowlist operator-extensible:
+    // `jwtEnv: 'PATH'` + `env: { PATH: <dir with a fake mojo> }` passed validation
+    // (PATH is not a reserved key) and then reported ZERO unprovable keys, so
+    // isMojoFullyRemote() returned true — the local sandbox was skipped and device
+    // isolation classified the session safe_remote, while resolveBin() picked the
+    // binary off that very PATH. Same trick with NODE_OPTIONS / LD_PRELOAD / DYLD_*.
+    //
+    // Ignoring `jwtEnv` here is not a compatibility break in the child: buildEnv()
+    // resolves whatever `jwtEnv` names and hands the VALUE to the CLI as
+    // X_JWT_TOKEN regardless (see MojoBackend.buildEnv). `jwtEnv` is a "where to
+    // read it from" pointer, never a name the child reads — so it has no business
+    // widening a proof about which binary executes.
+    return keys.filter(k => k !== MOJO_CANONICAL_JWT_ENV_KEY).sort();
+}
+/**
+ * Single source of truth for the execution mode a mojo config asks for.
+ *
+ * buildArgs (`--cloud`), buildEnv (`AGENT_LOCAL_DAEMON`) and the spawn audit
+ * log MUST all derive from this one function — they were previously three
+ * hand-kept copies and drifted twice (review F2: the audit label disagreed
+ * with the env for cloud+localDaemon both set, and for non-boolean values
+ * smuggled past strictBoolean by an old frozen snapshot).
+ *
+ * Precedence (review F3): an explicit `localDaemon: true` WINS over
+ * `cloud: true` and suppresses the `--cloud` flag entirely — previously both
+ * were emitted and the CLI received contradictory instructions. This stays
+ * consistent with isMojoFullyRemote(), which already returns false whenever
+ * `localDaemon === true`.
+ *
+ * Strict comparisons on purpose: a non-boolean survivor (e.g. the string
+ * "false" in a frozen snapshot written before strictBoolean existed) fails
+ * closed into the sandbox fallback rather than enabling host execution.
+ */
+export function deriveMojoExecutionMode(cfg) {
+    const cloud = cfg?.cloud;
+    const local = cfg?.localDaemon;
+    if (local === true) {
+        return {
+            agentLocalDaemon: '1',
+            passCloudFlag: false,
+            label: cloud === true
+                ? 'host (explicit localDaemon; cloud flag suppressed)'
+                : 'host (explicit localDaemon)',
+        };
+    }
+    if (cloud === true) {
+        return { agentLocalDaemon: '0', passCloudFlag: true, label: 'cloud-sandbox (--cloud)' };
+    }
+    if (local === undefined) {
+        return { agentLocalDaemon: '1', passCloudFlag: false, label: 'host (default)' };
+    }
+    return {
+        agentLocalDaemon: '0',
+        passCloudFlag: false,
+        label: local === false
+            ? 'sandbox-fallback (localDaemon=false, cloud off)'
+            : 'sandbox-fallback (invalid localDaemon value)',
+    };
+}
+export function isMojoFullyRemote(cfg) {
+    if (cfg?.cloud !== true)
+        return false;
+    if (cfg.localDaemon === true)
+        return false;
+    if (cfg.wrapperCli?.trim())
+        return false;
+    // The launcher ENV is part of the proof, not just the wrapper. resolveBin()
+    // picks the binary off the effective child PATH, so `env: { PATH: <dir with a
+    // fake mojo> }` runs different code while cloud/localDaemon/wrapperCli all
+    // still look clean — and loader hooks (LD_PRELOAD / NODE_OPTIONS / DYLD_*) do
+    // the same to the real binary.
+    //
+    // This is not hypothetical drift: `env` is NOT part of the frozen identity, so
+    // sessionMojoConfig() re-merges it from LIVE bot config on every cold refork.
+    // A session created as cloud-only could therefore be switched to a local fake
+    // after a daemon restart while this function kept returning true — bypassing
+    // the local sandbox AND getting classified safe_remote by device isolation.
+    if (mojoUnprovableEnvKeys(cfg).length > 0)
+        return false;
+    return true;
+}
+/**
+ * WHY this config cannot prove it runs nothing locally — one actionable
+ * explanation, or `undefined` when the proof holds.
+ *
+ * Shared deliberately. There are two independent places that refuse a
+ * not-provably-remote mojo session — the OPTIONAL sandbox gate
+ * (backendSandboxCompatibilityError) and the MANDATORY device-credential
+ * isolation path (which rewrites spawnBin, so MojoBackend.spawn refuses the
+ * wrapper it never asked for) — and they used to explain it differently. The
+ * device path told operators to "run fully remote (cloud on, localDaemon off)"
+ * even when cloud was already on and the real blocker was an env key, which is
+ * advice that cannot be acted on. Both now read from this one function.
+ *
+ * Returns key NAMES only, never values: these strings reach logs and chat, and
+ * one of the keys is by definition the operator's credential variable.
+ *
+ * Ordering mirrors isMojoFullyRemote so the two can never disagree about whether
+ * there is a problem — only about how much detail to print.
+ */
+export function mojoRemoteProofFailureReason(cfg) {
+    if (cfg?.cloud !== true) {
+        return 'mojo.cloud is not enabled, so tools run on this host — '
+            + 'set mojo.cloud=true (and leave mojo.localDaemon off).';
+    }
+    if (cfg.localDaemon === true) {
+        return 'mojo.localDaemon is on, which deliberately runs tools on this host — '
+            + 'turn it off to keep execution remote.';
+    }
+    const wrapper = cfg.wrapperCli?.trim();
+    if (wrapper) {
+        return 'a launch prefix (wrapperCli) runs before the binary and can rewrite the '
+            + 'environment the decision depends on, so it voids the proof.';
+    }
+    const unprovable = mojoUnprovableEnvKeys(cfg);
+    if (unprovable.length === 0)
+        return undefined;
+    const listed = unprovable.join(', ');
+    const dangerous = 'they can change which binary is executed (PATH) or inject into it '
+        + '(LD_PRELOAD / NODE_OPTIONS / DYLD_*)';
+    // A custom `jwtEnv` key is not dangerous in itself, so the generic wording reads
+    // as a false accusation against a JWT variable. Explain the real rule and give
+    // the two migrations that keep the credential working AND the session provable.
+    const credentialKey = cfg.jwtEnv?.trim();
+    const hitsCredential = !!credentialKey
+        && credentialKey !== MOJO_CANONICAL_JWT_ENV_KEY
+        && unprovable.includes(credentialKey);
+    if (!hitsCredential) {
+        return `the bot's \`env\` / \`mojo.env\` sets ${listed} — ${dangerous}.`;
+    }
+    const rest = unprovable.filter(k => k !== credentialKey);
+    const credentialAdvice = `\`${credentialKey}\` holds this bot's credential, but the proof exempts only `
+        + `\`${MOJO_CANONICAL_JWT_ENV_KEY}\` — a config-supplied name cannot be told apart `
+        + 'from one that redirects execution. Set `mojo.jwt` instead, or move that '
+        + "variable to the daemon's own environment (neither is a proof input).";
+    if (rest.length === 0) {
+        return `the bot's \`env\` / \`mojo.env\` sets ${listed}. ${credentialAdvice}`;
+    }
+    // Mixed case: migrating the credential alone would NOT make this provable, and a
+    // message that implies otherwise sends the operator round the loop a second time.
+    return `the bot's \`env\` / \`mojo.env\` sets ${listed}. ${credentialAdvice} `
+        + `Migrating the credential is not sufficient on its own: ${rest.join(', ')} `
+        + `must be removed as well — ${dangerous}.`;
+}
+/**
+ * The ONLY setting that may change on a live session: the JWT.
+ *
+ * Deliberately this narrow. The previous version allowed an arbitrary `env` patch,
+ * which review showed is equivalent to replacing the launcher: with no
+ * `cliPathOverride` the backend spawns the bare name `mojo`, so a live
+ * `env: { PATH: <dir with a fake mojo> }` executes a different binary on the next
+ * turn — and `NODE_OPTIONS` / `LD_PRELOAD` / `DYLD_*` are comparable. Enumerating
+ * dangerous variables cannot be made complete, so `env` is not patchable at all.
+ *
+ * Note this is not about a compromised daemon (which already has more authority
+ * than this); the problem was that a completely legitimate, validated patch could
+ * change what gets executed.
+ *
+ * Everything else in `mojo` (env / stream / systemPrompt / idleTimeoutSec) now
+ * requires a new session, matching how the control plane already behaves.
+ */
+export const MOJO_LIVE_PATCH_KEYS = ['jwt'];
+/**
+ * Build the complete live snapshot for a session.
+ *
+ * Resolves `jwtEnv` here rather than shipping the env map, so credential rotation
+ * works without giving a patch the power to change PATH / loader variables.
+ * Always returns an explicit value (`null` when there is no credential), because
+ * an omitted field cannot express "cleared".
+ */
+export function pickMojoLivePatch(cfg, sources = {}) {
+    const literal = cfg?.jwt?.trim();
+    if (literal)
+        return { jwt: literal };
+    // Resolve the configured key across the same layers buildEnv() would, reading
+    // only the VALUE — the map itself is never shipped, which is what stops a
+    // patch from rewriting PATH / loader variables.
+    const key = cfg?.jwtEnv?.trim() || MOJO_CANONICAL_JWT_ENV_KEY;
+    const fromMojoEnv = cfg?.env?.[key]?.trim();
+    if (fromMojoEnv)
+        return { jwt: fromMojoEnv };
+    const fromGeneric = sources.genericEnv?.[key]?.trim();
+    if (fromGeneric)
+        return { jwt: fromGeneric };
+    const fromAmbient = (sources.ambientEnv ?? process.env)[key]?.trim();
+    // Always explicit: `null` is the tombstone that lets a deleted credential
+    // actually be cleared on the backend.
+    return { jwt: fromAmbient ? fromAmbient : null };
+}
+/**
+ * Validate a live patch arriving over IPC.
+ *
+ * Separate from normalizeMojoConfig on purpose: that one validates the USER's
+ * config block, where `jwt` must be a non-empty string. A live patch is a
+ * different shape — `null` is a meaningful tombstone — so reusing the config
+ * validator rejected every clear request and the backend never saw it.
+ */
+export function normalizeMojoLivePatch(raw) {
+    if (raw === undefined || raw === null)
+        return { ok: true, value: {} };
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        return { ok: false, errors: ['mojo live patch must be a JSON object'] };
+    }
+    const errors = [];
+    const value = {};
+    for (const [key, val] of Object.entries(raw)) {
+        if (key !== 'jwt') {
+            // Deliberately strict: an `env` patch would be equivalent to replacing
+            // the launcher (see MOJO_LIVE_PATCH_KEYS), so anything beyond `jwt` is
+            // a bug or a stale payload, not something to accept quietly.
+            errors.push(`mojo live patch does not accept "${key}"`);
+            continue;
+        }
+        if (val === undefined)
+            continue;
+        if (val === null) {
+            value.jwt = null;
+            continue;
+        }
+        if (typeof val !== 'string' || !val.trim()) {
+            errors.push('mojo live patch jwt must be a non-empty string or null');
+            continue;
+        }
+        value.jwt = val;
+    }
+    return errors.length > 0 ? { ok: false, errors } : { ok: true, value };
+}
+/** Field-name → validator, so unknown keys are rejected rather than passed through. */
+const MOJO_FIELD_VALIDATORS = {
+    workspaceId: nonEmptyString,
+    agentId: nonEmptyString,
+    cloud: strictBoolean,
+    idleTimeoutSec: positiveInteger,
+    stream: strictBoolean,
+    systemPrompt: plainString,
+    jwt: nonEmptyString,
+    jwtEnv: jwtEnvVarName,
+    baseUrl: httpUrl,
+    localDaemon: strictBoolean,
+    ppeEnv: nonEmptyString,
+    env: stringMap,
+};
+function strictBoolean(v) {
+    // The reason this is strict rather than coerced: `localDaemon: "false"` used
+    // to satisfy `!== true` in the sandbox check (bypassing the local sandbox)
+    // while being truthy in buildEnv (setting AGENT_LOCAL_DAEMON=1). That
+    // combination skips isolation AND enables host execution.
+    return typeof v === 'boolean' ? undefined : 'must be a boolean (true/false, not a string)';
+}
+function positiveInteger(v) {
+    return typeof v === 'number' && Number.isInteger(v) && v > 0
+        ? undefined
+        : 'must be a positive integer';
+}
+function plainString(v) {
+    return typeof v === 'string' ? undefined : 'must be a string';
+}
+function nonEmptyString(v) {
+    if (typeof v !== 'string')
+        return 'must be a string';
+    return v.trim() ? undefined : 'must not be empty';
+}
+function envVarName(v) {
+    if (typeof v !== 'string')
+        return 'must be a string';
+    return /^[A-Za-z_][A-Za-z0-9_]*$/.test(v)
+        ? undefined
+        : 'must be a valid environment variable name';
+}
+/**
+ * `jwtEnv` is not just a name lookup: buildEnv() DELETES `env[jwtEnv]` before
+ * re-deriving the credential, so the name doubles as a deletion primitive. A
+ * shape-only check let `jwtEnv: "BOTMUX_MOJO_TREE_NONCE"` erase the containment
+ * tree nonce — the only signal that survives setsid + reparent — turning the
+ * termination proof blind while every gate still reported success. Reserved
+ * botmux keys and control-plane keys are therefore rejected by NAME, with the
+ * same delegation (not a copied list) the env-map validator uses.
+ */
+function jwtEnvVarName(v) {
+    const shape = envVarName(v);
+    if (shape)
+        return shape;
+    const key = v;
+    if (isReservedPerBotEnvKey(key)) {
+        return `must not name ${key} — botmux owns this variable (session identity, `
+            + 'CLI data root, or bot credential), and buildEnv() would delete it';
+    }
+    if (MOJO_CONTROL_ENV_KEYS.includes(key)) {
+        return `must not name ${key} — it is control-plane state frozen per session`;
+    }
+    return undefined;
+}
+function httpUrl(v) {
+    if (typeof v !== 'string' || !v.trim())
+        return 'must be a non-empty string';
+    let parsed;
+    try {
+        parsed = new URL(v);
+    }
+    catch {
+        return 'must be a valid URL';
+    }
+    return parsed.protocol === 'http:' || parsed.protocol === 'https:'
+        ? undefined
+        : 'must be an http(s) URL';
+}
+/**
+ * Same reserved-key rule the top-level `env` uses. Imported rather than
+ * duplicated: per-bot-env.ts is itself a dependency-free leaf, so this keeps
+ * mojo-types cheap for the many tests that pull it in.
+ */
+import { isReservedPerBotEnvKey } from '../../core/per-bot-env.js';
+/** Same rule the top-level `env` uses — see per-bot-env.ts. */
+const ENV_KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function stringMap(v) {
+    if (!v || typeof v !== 'object' || Array.isArray(v))
+        return 'must be a JSON object';
+    const control = new Set(MOJO_CONTROL_ENV_KEYS);
+    for (const [k, val] of Object.entries(v)) {
+        if (typeof val !== 'string')
+            return `value for "${k}" must be a string`;
+        if (!ENV_KEY_RE.test(k))
+            return `"${k}" is not a valid environment variable name`;
+        // `mojo.env` is the HIGHEST-precedence layer of the child env, so it must
+        // honour the SAME reserved list as the top-level `env`. Otherwise the block
+        // botmux already enforces there (session routing, CLI data roots, bot
+        // credentials) is bypassed just by moving the key in here — and it then
+        // WINS the merge. Delegated to isReservedPerBotEnvKey rather than
+        // re-listed, because a second copy of that set would drift.
+        if (isReservedPerBotEnvKey(k)) {
+            return `must not set ${k} — botmux owns this variable (session identity, `
+                + 'CLI data root, or bot credential); per-bot `env` rejects it too';
+        }
+        // Reject rather than silently strip: buildEnv() removes these anyway, and
+        // an operator who sets AGENT_BASE_URL here would otherwise believe their
+        // endpoint took effect while the session kept its frozen one.
+        if (control.has(k)) {
+            const owner = k === 'AGENT_BASE_URL' ? 'baseUrl'
+                : k === 'MOJO_PPE_ENV' ? 'ppeEnv'
+                    : 'localDaemon';
+            return `must not set ${k} — it is control-plane state frozen per session; `
+                + `use the \`${owner}\` setting instead`;
+        }
+    }
+    return undefined;
+}
+/**
+ * Validate a raw `mojo` block from ANY entry point (bots.json, `/config set
+ * mojo`, dashboard, or a defensive check before it reaches the worker).
+ *
+ * Fails closed on: unknown keys (typos like `cluod` would silently disable the
+ * cloud sandbox), internal launch-identity keys (they have top-level owners and
+ * are frozen on the session), and wrong types.
+ *
+ * Type strictness is a SECURITY requirement here, not tidiness — see
+ * strictBoolean for the concrete fail-open it prevents.
+ */
+export function normalizeMojoConfig(raw) {
+    if (raw === undefined || raw === null)
+        return { ok: true, value: {} };
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        return { ok: false, errors: ['mojo must be a JSON object'] };
+    }
+    const errors = [];
+    const value = {};
+    const internal = new Set(MOJO_INTERNAL_CONFIG_KEYS);
+    for (const [key, val] of Object.entries(raw)) {
+        if (internal.has(key)) {
+            errors.push(`mojo.${key} is not configurable inside the mojo block — `
+                + `use the top-level \`${MOJO_INTERNAL_KEY_OWNER[key] ?? key}\` instead`);
+            continue;
+        }
+        const validate = MOJO_FIELD_VALIDATORS[key];
+        if (!validate) {
+            errors.push(`mojo.${key} is not a recognized setting`);
+            continue;
+        }
+        // An explicit `undefined` (from JSON round-trips) means "unset", not invalid.
+        if (val === undefined)
+            continue;
+        const problem = validate(val);
+        if (problem)
+            errors.push(`mojo.${key} ${problem}`);
+        else
+            value[key] = val;
+    }
+    return errors.length > 0 ? { ok: false, errors } : { ok: true, value: value };
+}
+//# sourceMappingURL=mojo-types.js.map