Plugin Manifest Data Model

Experimental: internal/plugins defines the manifest types described
here, but the current plugin discovery and execution path does not load a
manifest file. Do not rely on these fields for runtime permission or sandbox
enforcement.

The manifest data model records plugin metadata, reproducible-build inputs,
declared inputs and permissions, and resource limits. The authoritative field
definitions are in internal/plugins/manifest.go.

For the plugin mechanism that is currently active, see
Plugin Development.

JSON Shape

{
  "name": "example",
  "version": "1.0.0",
  "description": "Example session enricher",
  "author": "Example Author",
  "source": {
    "repository": "https://github.com/tmc/it2",
    "commit": "0123456789abcdef0123456789abcdef01234567",
    "tag": "v1.0.0",
    "build": {
      "go_version": "1.24.6",
      "flags": ["-trimpath"],
      "env": {
        "CGO_ENABLED": "0"
      },
      "main_package": "./cmd/example"
    }
  },
  "binary": {
    "sha256": "0123456789abcdef...",
    "url": "https://example.com/",
    "code_signature": {
      "developer_id": "Developer ID Application: Example",
      "team_id": "ABCDEFGHIJ"
    }
  },
  "inputs": {
    "session_id": true,
    "screen_lines": {
      "lines": 50,
      "include_escapes": false
    },
    "buffer_lines": {
      "lines": 100,
      "include_escapes": false
    },
    "session_metadata": ["title", "working_directory"],
    "environment_vars": ["ITERM_SESSION_ID"]
  },
  "permissions": {
    "filesystem": {
      "read_only": ["/path/to/input"],
      "read_write": ["/path/to/cache"]
    },
    "network": false,
    "execute": ["/usr/bin/git"]
  },
  "sandbox": {
    "timeout": 500000000,
    "max_output_bytes": 1024,
    "max_memory_bytes": 0,
    "max_cpu_millis": 0
  }
}

timeout is a Go time.Duration encoded as an integer number of
nanoseconds.

Fields

Metadata

Field	Go type	Description
`name`	string	Plugin name
`version`	string	Plugin version
`description`	string	Short description
`author`	string	Author name

Source

Field	Go type	Description
`repository`	string	Source repository
`commit`	string	Full source commit
`tag`	string	Optional human-readable tag
`build.go_version`	string	Go version used for the build
`build.flags`	array of strings	Arguments passed to `go build`
`build.env`	object	Build environment entries
`build.main_package`	string	Optional main package

Binary

Field	Go type	Description
`sha256`	string	Expected binary digest
`url`	string	Optional download URL
`code_signature`	object	Optional macOS developer and team identifiers

Inputs

Field	Go type	Description
`session_id`	boolean	Whether the plugin needs a session ID
`screen_lines`	object	Requested line count and escape-sequence setting
`buffer_lines`	object	Requested scrollback count and escape-sequence setting
`session_metadata`	array of strings	Requested session metadata fields
`environment_vars`	array of strings	Requested environment variable names

Permissions

Field	Go type	Description
`filesystem.read_only`	array of strings	Declared read-only paths
`filesystem.read_write`	array of strings	Declared writable paths
`network`	boolean	Declared network access
`execute`	array of strings	Declared executable paths

Sandbox Limits

Field	Go type	Description
`timeout`	duration	Execution deadline
`max_output_bytes`	integer	Maximum output size
`max_memory_bytes`	integer	Memory limit; zero means unspecified
`max_cpu_millis`	integer	CPU limit; zero means unspecified

The package defines two presets:

DefaultSandboxConfig: 500 ms timeout and 1 KiB output.
RelaxedSandboxConfig: 2 s timeout and 4 KiB output.

These presets are data-model helpers. They are not evidence that the current
executable-plugin path applies operating-system sandboxing.

Current Runtime Behavior

The current runtime:

discovers executable it2-session-*, it2-tab-*, it2-window-*, and
it2-session-process-* files from PATH, IT2_PLUGIN_PATHS, and embedded
plugins;
gives PATH plugins priority over custom and embedded plugins;
filters the environment passed to plugins;
applies the IT2_PLUGIN_DEADLINE execution deadline, which defaults to
five seconds;
passes JSON input to enrichment plugins and reads their standard output.

It does not currently load this manifest model during discovery, installation,
or execution. In particular, the current runtime does not enforce manifest
permission declarations, cache policy, trust levels, transparency logs, or
reproducible-build verification.

Future Integration

Before manifests become a runtime contract, the implementation needs:

A documented manifest filename and discovery rule.
JSON decoding and validation.
An explicit compatibility/version policy.
Enforcement for declared inputs, permissions, and resource limits.
Integration tests proving the effective runtime restrictions.