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. 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`.

Success and failure examples

{
  "schema": 1,
  "ok": true,
  "command": "capabilities",
  "status": "ok",
  "value": {
    "name": "extension",
    "version": "4.0.22",
    "envelopeSchema": 1,
    "readySchemaVersion": 2,
    "outputJsonCommands": [
      "build",
      "capabilities",
      "create",
      "dev",
      "doctor",
      "eval",
      "inspect",
      "install",
      "logs",
      "open",
      "preview",
      "publish",
      "reload",
      "start",
      "storage",
      "telemetry"
    ]
  },
  "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": []
}

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.

⌘I

Introduction

Browser extension fundamentals

Getting started

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

Where human copy goes

Published contract artifacts

Next steps

​Envelope shape

​Success and failure examples

​Where human copy goes

​Published contract artifacts

​Next steps

Envelope shape

Success and failure examples

Where human copy goes

Published contract artifacts

Next steps