Plugins

Plugins are standards-based packages selected by stable ID at typed locations in agent.md and pinned in plugins.lock. Published plugins resolve from the agent's installed dependency graph; there is no official-plugin catalog in core. checked-in local plugins are auto-discovered under plugins/<name>/ and must contain an Agent Plugins v1 plugin.json. Portable Skills and MCP servers need no client extension; native Assembly Line capabilities add an ai.assemblyline/ entry. Official plugins ship integrations maintained with Assembly Line; community plugins use the same public contracts from independent packages. This page is the catalog and install guide. Plugin installation resolves a published ID or checked-in local plugin and records it in plugins.lock; it does not scaffold executable root files. Channels and infrastructure are selected explicitly in agent.md. To implement a plugin, see Authoring Plugins.

Locking reviews what is installed; selection decides what is active. Artifact packaging walks only the selected plugin graph, so an installed but unselected published package contributes no code, dependency, route, or authority. A checked-in local plugin is the intentional exception and activates by presence.

• What A Plugin Contributes
• Taxonomy
• Plugin Catalog
• Install A Plugin With assembly-line add
• Community Plugins
• Auditability And Trust

What A Plugin Contributes

A plugin can contribute one or more cohesive surfaces:

The ai.assemblyline entry has one canonical value contract. It must use an ESM default export or CommonJS module.exports. Its root may declare one plugin-wide configSchema and the contribution sections tools, connections, hooks, lifecycle, composition, contexts, instrumentation, channels, providers, models, and channelHooks. Obsolete singular/plural aliases and the named assemblyLinePlugin native-entry export are rejected. Package-level helper exports with that name are a separate connection-package API and do not change the native entry contract.

Model, channel, and infrastructure packages are full Agent Plugins, but they are not entries in the capabilities: capability list. Authors select them through explicit fields such as channels: [slack] or sandbox: e2b, or through the provider prefix in model. A plugin may provide a custom implementation for one of those boundaries, but it does not make the boundary disappear from agent.md.

Published capability plugins may expose schema-validated per-agent options at capabilities.<plugin>.config. Configuration belongs to the plugin as a whole; contribution-level tools and connections mappings remain policy exceptions. Credentials never belong in config. Tool and connection contributions declare environment requirements so preflight, secret sync, runtime boot, and inspection share one inventory.

Taxonomy

These terms are used consistently across the Assembly Line docs:

• Plugin: a published or checked-in Agent Plugins v1 package selected at a typed authoring location or activated by local presence.
• Contribution: what a plugin declares in its statically inspected ai.assemblyline entry: a model, provider, channel, connection, tool, hook, Skill, or other typed extension. Infrastructure packages export assemblyLineProvider; model packages export assemblyLineModelProvider. Their complete static contracts live in that same package and lock entry.
• Provider plugin: an implementation selected by a model prefix, channel, or explicit infrastructure field rather than by capabilities:.
• Adapter: the runtime instance resolved from an agent.md singular plugin selection or its typed options mapping.
• Connection: an agent-scoped capability and credential contract contributed by a selected plugin; it is not a root connections/ file.

The word "capability" is overloaded; the meaning depends on where it appears:

Plugin Catalog

The framework includes a minimal zero-install kernel baseline for local state, blob storage, scheduling orchestration, sandbox behavior, process-env secrets, and the Node/Pi runtime. A model plugin is still required. The framework kernel packages themselves (@assemblyline-agents/core, compiler, runtime, node, cli, sdk, docs, and pi) are not plugins. openrouter, openai, and openai-codex are ordinary model plugins, not privileged kernel packages.

Provider-specific setup, OAuth registration, CLI installation, and account policy live in each package's README (packages/<kind> in the Assembly Line repo, or the package page on npm).

Models

The prefix resolves the locked plugin's models contribution. Pi receives only those selected registrations and contains no bundled provider catalog or provider-specific behavior. The openai-codex plugin delegates directly to Pi's standard provider and OAuth flow; the removed custom Codex app-server package is not part of the architecture.

Channels

Channel plugins normalize provider events into durable Assembly Line turns and deliver replies. Consumption details are in Adapters: Channels.

Channel provider implementations stay inside the selected plugin; agent authors only declare the channel ID and any explicit exceptions in agent.md. That selection also activates plugin-owned channel tools, such as Photon's conversation tools and Slack's private-file retrieval tool. Optional MCP connections remain explicit capabilities: entries.

The Slack channel also exposes typed resolve_dm_by_email and post_message operations to authored tools through callSlackChannelOperation. These are semantic, allowlisted channel operations rather than a raw Web API passthrough. They reuse the configured workspace credential, and post_message applies the channel's Markdown splitting, error handling, and stable per-chunk Slack idempotency IDs. Scope declarations stay operation-specific: resolve_dm_by_email requires users:read, users:read.email, and im:write; post_message requires chat:write.

See Photon iMessage Channel for the Photon bridge.

The attachment-capable channel packages declare the official audio plugin as a package dependency. assembly-line add installs and locks that dependency without activating it under capabilities:; the channel's audio selector chooses one of its provider contributions.

Observability

The OTLP package owns its instrumentation factory, defaults, required environment, and accepted option schema. Install and select it with assembly-line add otlp agent.

Substrate Providers

Substrate plugins provide explicit infrastructure profiles selected in agent.md. Configuration, helper functions, and full env tables are in Adapters.

Connection Plugins

Every connection plugin exports its Agent Plugins v1 and ai.assemblyline entries. Selection is recorded by plugin ID; no connections/<kind>.ts is scaffolded. Tool connections enable their reviewed tool surface under the plugin's compiled access and approval policy. Credential-only connections declare their own static capability ceiling. Protocol is MCP over Streamable HTTP unless the table says otherwise. R = required, O = optional.

Each connections.<name> entry contains its complete reviewed contract. It does not point to a privileged compiler profile or require the compiler to join a second connection catalog.

Assembly Line's connection packages are not hosted integration accounts. The package supplies endpoint/spec defaults, tool classification, reviewed access defaults, and preflight metadata. You create the provider application, API token, OAuth client, local process, or bridge. Official connection plugins are supported unless an entry explicitly says otherwise.

Google services are separate direct REST connections. Select only the grants an agent needs: gmail, google-calendar, and google-drive. Connecting or revoking one does not affect the others. The three packages can share one deployment-owned Google OAuth web client (GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET), while Assembly Line stores a separate refreshable grant and requests service-specific scopes for each connection.

Connection Event Sources

These connection plugins include host-only event adapters. API and watch sources are registered and renewed by Assembly Line. Manual sources still verify, queue, deduplicate, retry, and dispatch deliveries, but the provider requires a console step that assembly-line connections wire reports. Event sources are enabled by default and can be disabled with events: false. Deliveries start agent work only when an explicit event automation matches; unmatched events are acknowledged without durable payload storage.

Higgsfield is not in this table. Its official SDK supports a callback attached to an individual generation, while the packaged connection uses the official sandbox CLI, whose current command surface does not accept that callback. The plugin therefore does not advertise a persistent event source it cannot wire.

Orgo is a connection because its tools manage and control provider-owned desktops by computer_id; it does not implement the per-run SandboxSession filesystem contract. The package can add a separate sandbox role later if it binds one computer to a session and supplies the canonical file and shell operations.

Tool Packs

Tool packs are trusted runtime code, not connections. They need no credential contract unless the tool itself uses a separately declared connection.

OpenUI TextContent parses GitHub-Flavored Markdown, including pipe tables, task lists, strikethrough, and autolinks. Markdown workspace files passed to openui_create or openui_update use the same renderer.

deliver_artifact remains the private file-delivery mechanism. It snapshots one exact workspace file for the active channel. openui_publish instead fetches and verifies the exact HTTPS URL issued by public blob storage; it never asks the model to invent a link.

LiveKit Voice And Telephony

LiveKit voice dispatch and SIP tools live in packages/livekit as @assemblyline-agents/livekit. assembly-line add livekit agent selects one conforming plugin that contributes its credential contract plus livekit_dispatch_agent, livekit_outbound_call, and livekit_transfer_call. It requires LIVEKIT_URL, LIVEKIT_API_KEY, and LIVEKIT_API_SECRET (optional LIVEKIT_OUTBOUND_TRUNK_ID and LIVEKIT_VOICE_AGENT_NAME). All three external actions are approval-gated. See the LiveKit package guide.

Plugin Packages Ship Automatically

Artifact packaging derives its dependency set from the compiled selected graph: models, providers, channels, capabilities, connections, and qualified plugin references all carry the package that implements them. The build vendors (local mode) or pins (release mode) only that graph. There is no allowlist, kind-to-package guess, or unconditional model-provider dependency. An unresolvable selected package fails validation/build instead of producing an artifact that cannot boot.

Install A Plugin With assembly-line add

assembly-line add <kind> <agentRoot> installs the capability or provider package with your detected package manager and updates the appropriate agent.md selection. The command does not hide changes in global configuration. Each result is a visible file or a printed instruction.

assembly-line add notion agent

The command installs the package, selects notion in agent.md, updates plugins.lock, and prints its required environment and validation steps.

What gets selected depends on the contribution's role:

• Connection provider: exposes every reviewed tool through the selected plugin's ai.assemblyline extension, with no root connections/ file:

  capabilities:
    notion:
      connections:
        notion:
          disable: [delete_page]
          approval:
            update_page: always

  The provider's reviewed default policy applies when no exception is present. disable narrows its surface and approval changes an individual action within the plugin and host policy ceilings. Connection tools stay behind deferred discovery; they are not copied into a root tools/ folder or injected into every model prompt.

  Connection plugins do not contribute or copy root skills. Live provider tool names, descriptions, schemas, and the resolved access policy remain the authoritative model-facing contract.

• Tool provider: exposes tools through the plugin's ai.assemblyline extension and may bundle namespaced skills. Nothing is copied into a root tools/ folder.

• Channel: contributes a channel provider selected explicitly in agent.md; ingress and delivery remain inside the plugin boundary.

• Infrastructure provider (state, blob, sandbox, deploy, secrets): implements an explicit reviewed plugin selection in agent.md. The runtime is always Node. Audio processors are selected only through channels.<name>.audio.

• Model provider: selects the plugin's declared default provider/model value under model and packages its Pi registration.

After wiring, the CLI prints the plugin's required env vars, optional env vars, and setup steps, then the assembly-line validate command to run next.

Pass --no-install to skip the package manager and print the exact install command. It does not mutate agent.md or plugins.lock, because the CLI cannot trust a declaration it has not installed and inspected. A published plugin is not selected or locked until its installed manifest can be validated. Plugin skills remain namespaced and become available after the selected plugin is resolved.

Role Disambiguation

Some package IDs exist under more than one role. --role <role> disambiguates the requested capability or explicit provider profile. A connection role adds a plugin ID; a channel or infrastructure role updates its dedicated agent.md field. No role creates a root channel, connection, tool, or gateway file.

Community Plugins

Install a community plugin by package name:

assembly-line add @acme/assembly-line-search agent

The CLI installs the package and validates its Agent Plugins v1 plugin.json without executing source. Portable Skills and mcp.json are discovered at their standard locations. Native contributions are statically inspected from the declared ai.assemblyline entry. The published plugin ID is added to agent.md and its exact package, integrity, components, and authority are pinned in plugins.lock.

Use assembly-line plugin init <name> <agentRoot> for checked-in code. After editing it, run assembly-line plugin lock <agentRoot>; a new or changed capability descriptor requires --confirm-upgrade, while implementation-only content changes simply refresh the integrity hash.

To build such a package, see Authoring Plugins.

Auditability And Trust

Plugins execute trusted host code and should be reviewed like application dependencies. Assembly Line deliberately limits them to named extension points with static authority inventories. Agent authors should be able to audit a plugin's effect from the package dependency plus the explicit files and adapter selections in the agent folder.

Provider-specific secrets stay in host environment variables, authorization flows, or encrypted connection grants. They must not be embedded in plugin skills, prompts, tool inputs, or agent source files.

Stdio and sandbox-CLI plugins are trusted host dependencies: Assembly Line never lets a model or dynamic connection choose their command, arguments, working directory, or environment. Sandbox-CLI connections additionally run only reviewed operations inside the active run sandbox with individually quoted arguments. The plugin never receives an unsandboxed gateway command channel.

Related Docs

• Adapters: consuming substrate adapters: role matrix, gateway config, per-adapter env.
• Plugin connections: connection contributions, access, approval, and transports.
• Authoring Plugins: implementation contracts for every contribution type.
• Runtime Configuration: runtime and operator environment variables.