Result envelope (schema 1)

Parse one JSON document per command instead of scraping log lines. Under --output json, every terminating command answers with exactly one schema-1 envelope on stdout. Long-running commands stream the same shape as lifecycle frames.

Envelope shape

Field	Type	Meaning
`schema`	`1`	The envelope version. Additive changes keep this number.
`ok`	boolean	Whether the command succeeded.
`command`	string	The command that produced this result.
`status`	string	A short machine status, for example `ready`, `usage`, or `failed`.
`value`	any or null	The command’s payload. A failure can still carry one, `doctor` is the motivating case.
`error`	object or null	Present when `ok` is false, see below.
`warnings`	string[]	Non-fatal notices.
`truncated`	boolean	Optional. Set when a payload was cut to fit a size cap.
`hint`	string	Optional. A next-step suggestion.

The error object:

Field	Type	Meaning
`code`	string	A stable `E_*` identifier from the error code table. Match on this.
`message`	string	Free copy that may be rewritten at any time. Plain text with no glyph and no color codes. Never match on it.
`name`	string	Optional. The originating error class name.
`engine`	string	Optional. The browser engine where the failure happened.
`hint`	string	Optional. Remediation copy.
`refs`	object	Optional. The actionable parts that the message names: `flag`, `command`, `path`, `version`.
`details`	array	Optional. Present on a failed compile. One entry per compiler diagnostic, see Compile diagnostics below.

Success and failure examples

{
  "schema": 1,
  "ok": true,
  "command": "capabilities",
  "status": "ok",
  "value": {
    "name": "extension",
    "version": "4.1.3",
    "envelopeSchema": 1,
    "readySchemaVersion": 2,
    "outputJsonCommands": [
      "build",
      "capabilities",
      "create",
      "dev",
      "doctor",
      "eval",
      "inspect",
      "install",
      "logs",
      "open",
      "preview",
      "publish",
      "reload",
      "start",
      "storage",
      "telemetry",
      "uninstall"
    ]
  },
  "error": null,
  "warnings": []
}

{
  "schema": 1,
  "ok": false,
  "command": "eval",
  "status": "failed",
  "value": null,
  "error": {
    "code": "E_TARGET_NOT_FOUND",
    "message": "No tab matched the requested target.",
    "hint": "List targets with `extension inspect --list-tabs`."
  },
  "warnings": []
}

Compile diagnostics

A failed build frame and the dev stream’s compile-failed frame carry error.details, one entry per compiler diagnostic, errors first. Each entry has this shape:

Field	Type	Meaning
`code`	string	Optional. The table code the diagnostic resolves to, for example `E_MODULE_NOT_FOUND`. Absent when none does.
`message`	string	The compiler text, ANSI-stripped. Free copy, never match on it.
`file`	string	Optional. The source file, relative to the project root.
`line`	integer	Optional. The line in that file when the compiler reports one.
`column`	integer	Optional. The column on that line when the compiler reports one.
`severity`	`"error"` or `"warning"`	Which kind of diagnostic this is.
`name`	string	Optional. The compiler’s error class name.

The list is capped at 20 entries. When the cap cuts it, the frame sets truncated: true. The 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, E_BACKGROUND_REQUIRED, E_REMOTE_RESOURCE_BLOCKED, E_PERF_BUDGET, and E_ENV_NO_MATCH. This is golden.build.compile.json with its two messages shortened to their first line:

{
  "schema": 1,
  "ok": false,
  "command": "build",
  "status": "build-failed",
  "value": null,
  "error": {
    "code": "E_COMPILE",
    "message": "Build failed with errors",
    "details": [
      {
        "code": "E_CONTENT_SCRIPT_SYNTAX",
        "message": "Module build failed (from builtin:swc-loader): Syntax Error: Expression expected",
        "file": "content/scripts.js",
        "severity": "error",
        "name": "ModuleBuildError"
      },
      {
        "code": "E_MODULE_NOT_FOUND",
        "message": "Module not found: Can't resolve './missing' in '/home/dev/my-extension'",
        "file": "background.js",
        "line": 1,
        "column": 1,
        "severity": "error"
      }
    ]
  },
  "warnings": [],
  "hint": "Fix the error above and run build again."
}

A successful build keeps its warnings in the top-level warnings array. Each string there opens with E_CODE: when a code resolves, for example E_CSS_DEAD_REF: ..., the same convention logs and uninstall already use.

Where human copy goes

The EXTENSION_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 always writes to stderr, so a launch failure stays visible while stdout stays parseable.

Pipe stdout to your parser and keep stderr for humans. The two never mix.

Published contract artifacts

The extension-develop package ships the contract as importable files under the ./contract/* export:

Artifact	What it is
`extension-develop/contract/envelope.schema.json`	JSON Schema for the envelope. Its `$id` is `https://extension.js.org/contract/envelope-1.json`.
`extension-develop/contract/codes.json`	The durable error-code table with `folded` and `legacy` mappings.
`extension-develop/contract/golden.*.json`	Golden fixtures, one per command and status, for example `golden.dev.ready.json` and `golden.eval.target-not-found.json`.

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.

Introduction

Browser extension fundamentals

Getting started

Templates

Compare and migrate

Commands reference

Features

Browsers

Languages and frameworks

Integrations

Workflows

Machine contracts

Publish to the stores

Debugging

Implementation guide

Community

Result envelope (schema 1)

Envelope shape

Success and failure examples

Compile diagnostics

Where human copy goes

Published contract artifacts

Next steps

​Envelope shape

​Success and failure examples

​Compile diagnostics

​Where human copy goes

​Published contract artifacts

​Next steps

Envelope shape

Success and failure examples

Compile diagnostics

Where human copy goes

Published contract artifacts

Next steps