#Module: launch-env

#Interfaces

#OperatorEnvFile

#Properties

#applied?

readonly optional applied?: number

#path

readonly path: string

#state

readonly state: "absent" | "loaded" | "unreadable"

applied counts the variables this file set; absent means the file does not exist.

---

#OperatorEnvOptions

#Properties

#env?

readonly optional env?: ProcessEnv

The environment to fill; process.env by default. Mutated in place.

#manifestEnv?

readonly optional manifestEnv?: Readonly<Record<string, string>>

The manifest env defaults the host merged into env before launch (the stdio server's declared block, as built). A variable whose current value equals its default is treated as the pass-through it almost always is, so the file may override it; one that differs was exported by the host or the operator and stays reserved. The one ambiguity is accepted: an operator export that equals the manifest default reads as the default. A default that still carries a path token never matches its expanded value, so such a variable stays reserved.

#platform?

readonly optional platform?: Platform

The platform whose environment-key rules apply; process.platform by default. Windows environment names are case-insensitive, so a host Path reserves PATH there.

#pluginRoot

readonly pluginRoot: string

The plugin root the files live under: the expanded AGENT_BUNDLE_PLUGIN_ROOT when the host set one, otherwise the shell's own fallback (the artifact root — the parent of mcp/, bin/, hooks/ — or the caller's .agent-bundle).

---

#OperatorEnvResult

#Properties

#applied

readonly applied: readonly string[]

The variables the layer set, sorted; a name only, never a value.

#files

readonly files: readonly OperatorEnvFile[]

The files considered, in the order they were applied.

#Variables

#applyOperatorEnv

const applyOperatorEnv: (options) => OperatorEnvResult

Applies the operator .env layer to env in place, filling only variables the host did not set (a variable still holding its manifestEnv default counts as unset), and reports what happened without ever touching a value. Missing files are the normal case (most packs need none); an unreadable one is reported and skipped, never fatal — a pack must start even when its operator file has the wrong permissions.

#Parameters

#options

OperatorEnvOptions

#Returns

OperatorEnvResult

---

#OPERATOR_ENV_FILE_NAMES

const OPERATOR_ENV_FILE_NAMES: readonly string[]

The conventional files, lowest priority first: .env.local overrides .env.

---

#OPERATOR_ENV_FILE_NONE

const OPERATOR_ENV_FILE_NONE: "none" = "none"

The AGENT_BUNDLE_ENV_FILE value that disables the operator env layer.

---

#OPERATOR_ENV_FILE_VARIABLE

const OPERATOR_ENV_FILE_VARIABLE: "AGENT_BUNDLE_ENV_FILE" = "AGENT_BUNDLE_ENV_FILE"

Names the file(s) to read instead of the plugin root's .env / .env.local pair: one path, or several joined by the platform path delimiter, applied in order (later files win). The value none disables the layer — which is what agent-bundle mcp run --no-env hands its child, so the shell's own layer never re-adds what the operator asked to leave out.

---

#operatorEnvFilePaths

const operatorEnvFilePaths: (pluginRoot, env?) => readonly string[]

The files a launch considers, in application order: the explicit AGENT_BUNDLE_ENV_FILE list, nothing for none, or the plugin root's conventional pair.

#Parameters

#pluginRoot

string

#env?

Readonly<Record<string, string | undefined>>

#Returns

readonly string[]

---

#operatorEnvPluginRoot

const operatorEnvPluginRoot: (fallback, env?) => string

The plugin root an emitted shell reads its operator files from: the same precedence the runtime's resolvePluginRoot applies (an expanded AGENT_BUNDLE_PLUGIN_ROOT, else the shell's fallback), spelled here without a runtime import so the shared-runtime hook wrapper stays dependency-free. Like the runtime, only the blank check reads a trimmed copy: a configured path is resolved exactly as written, so both resolutions name one directory.

#Parameters

#fallback

string

#env?

Readonly<Record<string, string | undefined>>

#Returns

string

---

#parseOperatorEnv

const parseOperatorEnv: (contents) => Record<string, string>

The dotenv grammar the shells accept: KEY=value lines, an optional export prefix, blank lines and # comments (including after a closing quote: TOKEN="secret" # note), single-, double-, or backtick-quoted values (double quotes expand \n, \r, \"), and a multi-line double- or single-quoted value that closes on a later line. No ${VAR} interpolation — a value is used exactly as written. Later lines win over earlier ones for the same key.

#Parameters

#contents

string

#Returns

Record<string, string>