--output json, every terminating command answers with exactly one schema-1 envelope on stdout. Long-running commands stream the same shape as lifecycle frames.
From the release after 4.2.0, every JSON run ends with exactly one terminal frame. extension --output json with no command answers one usage frame with E_ARGS and exits 1. A run stopped by SIGINT or SIGTERM before its command answered ends with one stopped frame that carries E_INTERRUPTED and value.signal, and exits 130 or 143.
Envelope shape
The
error object:
Success and failure examples
Compile diagnostics
A failedbuild frame and the dev stream’s compile-failed frame carry error.details, one entry per compiler diagnostic, errors first. Each entry has this shape:
The list is capped at 20 entries. When the cap cuts it, the frame sets
truncated: true.
The error codes that can appear in details are the diagnostic rows of the error code table: E_MODULE_NOT_FOUND, E_CONTENT_SCRIPT_SYNTAX, E_CSS_PARSE, E_ENTRY_NOT_FOUND, E_ASSET_MISSING, E_SCRIPT_DEP_MISSING, E_RESERVED_FOLDER, E_CSS_PREPROCESSOR_MISSING, E_CSS_DEAD_REF, E_LOCALES_LAYOUT, E_WAR_INVALID, and E_PERF_BUDGET. Up to 4.2.0, E_BACKGROUND_REQUIRED could appear there too. A warning entry carries a code from the warning code table.
This is golden.build.compile.json with its two messages shortened to their first line:
E_CONFIG_LOAD) and an unusable package.json (E_PACKAGE_JSON_INVALID) give the same frame on build, dev, start, and preview. error holds code and message only, with no name, and the top-level hint reads Fix the error above and run <command> again. On preview, the status is failed.
A successful build keeps its warnings in the top-level warnings array. Each string there opens with W_CODE: when a code resolves, for example W_CSS_DEAD_REF: ..., the same convention logs and uninstall already use. Releases up to 4.1.41 opened these strings with the E_* name. From the release after 4.1.41, a failed build’s frame carries them too: each coded warning the build had, once, including those from a browser that built before the failure. The array is [] when there is none.
Where human copy goes
TheEXTENSION_OUTPUT environment variable is the machine-mode switch. When it is json or ndjson, frames own stdout and human copy moves aside:
- Informational lines and warnings go quiet, or move to stderr where a stream needs them.
- Error copy is never suppressed. It writes to stderr, so a launch failure stays visible while stdout stays parseable.
- From the release after 4.1.41, a refusal while
buildordevis still finding the project prints nothing on stderr. - For
build, that also covers finding the browser. The frame on stdout is then the whole answer. - Every later failure, such as a config file that fails to load, also prints its human lines on stderr.
Published contract artifacts
Theextension-develop package ships the contract as importable files under the ./contract/* export:
Validate your consumer against the schema, and pin your tests to the golden fixtures. Codes may be added, never renamed or removed.
Next steps
- Branch on failures with the error code table.
- Follow long-running sessions with the lifecycle stream.

