Use extensions and connectors

Outcome

You can inspect and install one immutable curated extension version, enable only an explicitly approved remote tool, and use the trusted GitHub connector without placing provider credentials or unreviewed executable behavior in a sandbox.

Prerequisites

Read approval and schedule boundaries and network and tool policy. Use an authenticated workspace, review the generated API, and use only approved server-side secret handling for first-party connectors. Raw connector or MCP credentials must never enter a command body, prompt, browser bundle, sandbox, or artifact; hosted remote MCP is credential-free only.

Lumen's portable package contract is Agent Plugins 1.0.0. A package has one required root plugin.json, optional Agent Skills under fixed skills/<name>/SKILL.md paths, and optional MCP declarations in root mcp.json. Lumen validates the pinned 1.0.0 rules locally; importing a package never downloads a schema, connects to MCP, starts a process, or runs package code. Curated source adapters may read the same safe subset from supported bundle layouts, but they enter this one catalog and do not create another runtime.

Operator import

The production importer accepts only one already-reviewed local ZIP archive plus its exact SHA-256. It has no URL, marketplace, package-manager, Git checkout, installer, or arbitrary upload mode. Hash the archive outside Lumen, transfer it through the approved operator channel, and invoke the worker- authority CLI with absolute local paths:

uv run lumen import-agent-plugin \
  --archive /absolute/private/reviewed-plugin.zip \
  --archive-sha256 sha256:<exact-archive-digest> \
  --source-name reviewed-plugin

If the package declares remote MCP servers, perform discovery separately under the reviewed network procedure. Lumen does not connect during import. Supply the exact local discovery report and its independent digest only after review:

uv run lumen import-agent-plugin \
  --archive /absolute/private/reviewed-plugin.zip \
  --archive-sha256 sha256:<exact-archive-digest> \
  --source-name reviewed-plugin \
  --mcp-discovery /absolute/private/reviewed-mcp-discovery.json \
  --mcp-discovery-sha256 sha256:<exact-discovery-digest>

The discovery report is a strict JSON object with schema_version: 1, reviewed: true, the exact archive_digest, and a bounded tools list containing only server_name, name, title, description, and input_schema. Tool names must bind to servers already declared by that archive. The CLI stores only normalized safe bytes through the canonical immutable artifact store, persists the version in PostgreSQL, and emits a redacted receipt. Repeating the same version is idempotent. Every imported server and tool remains disabled and approval-required until the separate workspace review and installation flow succeeds.

Steps

1. List the curated catalog, then inspect the exact extension ID, source revision, archive digest, version digest, license, instruction digests, remote MCP hosts, tools, and capability-diff digest. Catalog instruction text and metadata remain untrusted input.
2. Reject or quarantine every unsupported surface. Lumen retains only exact SKILL.md bytes and safe declarative reference files. Imported hooks, installers, scripts, assets, commands, agents, subagents, local binaries, package-supplied filesystem or shell tools, language servers, client extensions, resource discovery, provider credentials, and control-plane behavior are never executed by the hosted product. This does not remove the fixed runner-local tools built into the reviewed Lumen runtime. At attempt start, applicable installed skill instructions and safe resources are copied by exact digest into the reserved local .lumen/skills tree and chmodded 0400. Direct write and edit reject that path, but same-UID bash can alter only the disposable copy; restart rematerializes exact bytes. The agent reads skills with ordinary local file discovery, and a skill does not become a remote tool or gain authority by being materialized. Unknown manifest fields are ignored. A malformed manifest rejects the package; an invalid skill or MCP server is isolated so independently valid siblings remain reviewable.
3. Preview the workspace capability diff and install only by presenting the exact version and diff digests you reviewed. An upgrade is another exact version decision and resets tool authority.
4. Treat every imported remote MCP server and tool as disabled by default. Enable one tool with the current installation version, exact version/diff digests, explicit external-side-effect approval, and no credential requirement or binding. Disable it through the same versioned product command. Hosted imports accept only public, credential-free HTTPS Streamable HTTP endpoints. They reject stdio, legacy HTTP+SSE, private or credential-bearing URLs, configured headers, environment values, arguments, and working directories. Redirects never gain authority to forward headers or change origin. Credentialed remote MCP execution is not enabled in the hosted control plane.
5. Enable the exact tool at workspace scope. Tasks do not carry ordinary tool allowlists. When the worker composes a non-planning attempt, it resolves current enabled installations, freezes each selected remote MCP tool's definition digest, installation ID, version digest, and policy version in the attempt runtime manifest, and revalidates policy immediately before dispatch. Planning attempts receive no remote MCP tools. The trusted adapter resolves only public DNS addresses, pins the selected address while preserving the original TLS server name and Host, ignores environment proxies, performs the strict MCP initialize/session flow, and never sends authorization or cookie headers. Existing approval, capability, budget, cancellation, and ambiguous-side-effect rules remain authoritative.
6. For the trusted GitHub connector, configure the app-only token together with an exact owner/repository allowlist. github.read_issue returns untrusted content that is not evidence eligible. github.create_issue_comment is always an approval-required external side effect bound to the exact repository, issue, and body; comment bodies are limited to 32,000 UTF-8 bytes.

The private GitHub route is intentionally absent from the public OpenAPI document. The worker calls it with an attempt- and generation-scoped capability; neither the browser nor sandbox receives the app token. A product operation marker reconciles a comment after response loss without posting a duplicate.

Verify

Prove cross-workspace catalog and installation reads fail. Change the presented version, capability diff, installation version, host, secret binding, or tool arguments and confirm the request is rejected. Confirm quarantined bundles cannot install, newly installed tools remain disabled and approval-required, and an upgrade cannot inherit old authority. Confirm an arbitrary, disabled, credential-requiring, stale-digest, or cross-workspace tool ID cannot enter the frozen runtime manifest or resolve at attempt start. Revoke policy between approval and dispatch and confirm the adapter refuses the call. Exercise public and private DNS answers, redirects, oversized or malformed JSON/SSE, schema references, timeouts, cancellation during DNS/body/in-flight work, and response loss after dispatch. The remote request must contain no authorization, cookie, proxy credential, or package-supplied header.

For an Agent Plugin, also verify a path escape or archive symlink rejects the package, an unsupported manifest schema version rejects every component, a bad mcp.json disables MCP without hiding valid skills, and one invalid MCP entry does not suppress a valid remote sibling.

For GitHub, test an unallowlisted repository, malformed issue target, oversized or marker-containing comment, denied approval, expired capability, cancellation, provider error, duplicate delivery, and lost response. A reconciled retry must return the one marked comment rather than create another.

Recover

Disable the affected extension tool or remove its secret binding when authority is uncertain. Preserve the immutable source and capability diff for review; do not edit a catalog version in place. Revoke and rotate any connector credential that may have crossed its app-only boundary.

For an ambiguous GitHub comment, keep the external operation unresolved and reconcile by its product marker before retry. Returned issue text remains untrusted and must be captured through the web-source or another eligible immutable evidence path before it can support a claim.

Next task

Inspect artifacts, claims, and evidence.