Baike.dev
Log in
Back to tool/Back to issues
#2507·airi

[Feature]: Track the AIRI plugin system roadmap with the Agent Activity plugin

Author: leaftCreated Sep 10, 2026Updated Sep 16, 2026
Labelspending triage

This issue was prepared by Codex from source-code review, related issues, merged PR #2506, and lessons from closed draft PR #2549.

It is a working implementation plan for maintainer review. It does not represent an approved project roadmap.

Progress was last updated on 2026-09-16.

Progress snapshot

Phase Status Tracking
Phase 1: Manifest v2 and folder import Complete PR #2506 merged on 2026-09-16.
Phase 2: Activation Planner Next Restart from current main as one focused change. No implementation PR exists yet.
Phase 3: Extension-hosted Kit registration Planned Start after Phase 2 defines and merges the activation contract.
Phase 4: Kit Router and bindings Planned Start after Phase 3 defines the Provider lifecycle.
Phase 5: Inspection and diagnostics Planned Build on the accepted Phase 2 to Phase 4 state models.
Phase 6: User-facing plugin management Planned Folder import exists in Devtools. The product management page and global switch remain open.
Phase 7: Isolation and remote routing Planned Define this boundary after the local runtime contracts are stable.
Agent Activity reference implementation Planned Start after the required plugin-system phases are merged.

Delivery rule

Each Phase must be a focused review and delivery unit. A prototype from a later Phase does not count as progress for an earlier Phase.

Task-list items count as complete only after the implementation is accepted and merged into main. Closed or abandoned drafts remain historical evidence only.

Draft PR #2549 combined partial work from Phase 2 through Phase 5. It was closed without merge on 2026-09-16 and is not an implementation base.

Immediate next steps

  • Close combined draft PR #2549 without merging it.
  • Start Phase 2 from current main without copying the #2549 implementation.
  • Complete the Activation Planner and its Host integration as one focused Phase 2 change.
  • Start Phase 3 only after the Phase 2 contract is accepted and merged.
  • Keep Agent Activity outside the AIRI repository until its required platform phases are available.

Background

This plan is inspired by the existing but incomplete airi-plugin-claude-code implementation.

The current Claude Code plugin demonstrates an early integration path:

Claude Code Hook
  -> plugin CLI
  -> AIRI Channel Server
  -> AIRI

This proves that an external agent can send lifecycle events to AIRI. However, the implementation is specific to Claude Code and does not yet provide a complete foundation for installing, configuring, activating, routing, and inspecting general AIRI extensions.

The proposed agent-activity-airi plugin will generalize this idea. It will initially support simple agent task reminders:

  • The agent is waiting for user input.
  • The agent task has completed.
  • AIRI presents the event through text, semantics, expressions, and character motion.
  • Communication is one-way.
  • The first version only observes the main agent task.
  • The user explicitly installs the integration and permits the required Hook.

Codex, Claude Code, Pi Agent, and other agent tools should connect through separate adapters instead of placing agent-specific contracts inside the AIRI Host.

Goal

Use the development and implementation of agent-activity-airi as a practical reference project to complete the missing foundations of the AIRI plugin system.

The reference plugin should exercise the complete path:

Install
  -> Review manifest
  -> Review permissions
  -> Resolve dependencies
  -> Enable
  -> Load
  -> Provide or consume a Kit
  -> Route events
  -> React in AIRI
  -> Unload
  -> Disable
  -> Uninstall

When this path exposes a missing general capability, the capability should be implemented in the AIRI plugin system rather than embedded as a special case in the Agent Activity plugin.

Generic Host infrastructure belongs in the AIRI repository. Agent adapters, Agent Activity business contracts, and the reference plugin can remain in an external repository.

Terminology

  • Extension: An installable and loadable package.
  • Extension Host: The AIRI runtime that discovers, validates, activates, and unloads Extensions.
  • Kit Contract: A separate SDK package that defines the operations and events of one capability.
  • Host-provided Kit: A Kit implemented by the AIRI Host.
  • Extension-hosted Kit: A Kit implemented by a Provider Extension.
  • Provider Extension: An ordinary Extension that provides a Kit.
  • Consumer Extension: An ordinary Extension that uses a Kit.
  • Binding: One Consumer's resolved connection to a Kit Provider.
  • Peer: A transport endpoint. It may use WebSocket, Electron IPC, MessagePort, or another transport.

Provider and Consumer are roles. They are not new top-level plugin types.

Current state

Area Status Notes
Plugin Protocol Implemented foundation Defines Eventa-based communication contracts.
Plugin SDK Implemented foundation Supports defineExtension() and extension contexts.
Electron Extension Host Implemented foundation Can load local extensions and manage runtime cleanup.
Host-provided Kits Implemented Widget, Gamelet, and Tool capabilities can be registered by the Host.
Extension lifecycle controls Implemented Devtools can enable and load, or disable and unload, an Extension.
Static assets and cookies Implemented Available through Host-controlled plugin capabilities.
Development auto-reload Implemented Local plugin development can reload changed code.
Manifest v2 Implemented Merged in PR #2506.
Import from folder Implemented in Devtools PR #2506 adds review, confirmation, safe copy, and disabled-by-default installation.
Extension-hosted Kits Not implemented in main Closed PR #2549 is a discarded combined exploration. Phase 3 will redesign this boundary later.
Activation Planner Not implemented Phase 2 will restart from current main as a focused change.
User permission confirmation Partial Folder import shows declared permissions before confirmation. Runtime consent and Hook approval remain open.
User plugin management UI Not implemented Management is currently focused on Devtools.
Plugin-system global switch Not implemented No complete user-facing switch exists.
Process isolation Not implemented Extensions currently share more runtime trust than the final design should allow.
General remote Kit routing Not implemented Local routing belongs to Phase 4. Remote routing belongs to Phase 7.

Target architecture

flowchart LR
  subgraph External["External agent integration"]
    Codex["Codex adapter"]
    Claude["Claude Code adapter"]
    Pi["Pi Agent adapter"]
  end

  subgraph Extensions["AIRI Extensions"]
    Provider["Agent Activity Provider Extension"]
    Consumer["AIRI Reaction Consumer Extension"]
  end

  subgraph Host["AIRI Extension Host"]
    Importer["Folder Importer"]
    Validator["Manifest Validator"]
    Planner["Activation Planner"]
    Lifecycle["Lifecycle Manager"]
    Registry["Hosted Kit Registry"]
    Router["Kit Router"]
    Permissions["Permission Service"]
    Inspector["Inspection Service"]
  end

  Contract["Agent Activity Kit Contract"]

  Codex --> Provider
  Claude --> Provider
  Pi --> Provider

  Provider --> Registry
  Consumer --> Router
  Registry --> Router
  Router --> Provider
  Router --> Consumer

  Importer --> Validator
  Validator --> Planner
  Planner --> Lifecycle
  Permissions --> Planner
  Permissions --> Router
  Lifecycle --> Registry
  Registry --> Inspector

  Contract -.implemented by.-> Provider
  Contract -.used by.-> Consumer

The Host understands Kit identity, version, ownership, permissions, lifecycle, and routing. It does not interpret Agent Activity business payloads.

Core design decisions

One active Provider per Kit

The first implementation allows only one active Provider for each kitId.

If two enabled Extensions provide the same Kit, configuration validation must fail before any Extension is enabled, disabled, loaded, or unloaded.

Host-provided Kits reserve their Kit IDs and participate in the same conflict validation.

Kit merging, rewriting, and multi-provider selection remain future design ideas.

Dependencies and permissions are separate

kits.uses declares what an Extension needs.

Permissions declare what the Extension is allowed to do.

A required Kit may exist while a requested operation is still denied by policy.

Configuration changes use an Activation Plan

The Host should evaluate the complete proposed enabled configuration before changing runtime state.

The plan validates:

  • Duplicate Providers.
  • Missing required Kits.
  • Kit version compatibility.
  • Dependency cycles.
  • Runtime compatibility.
  • Permission requirements.
  • Load and unload order.

A failed plan must not leave the Host in a partially changed state.

The Host owns identity

The Host assigns the calling Extension identity. Extensions must not provide or override their own caller identity in Kit requests.

Reload creates a new Provider generation

Each Provider load receives a new generation.

Bindings and pending requests from an older generation must not reach the replacement Provider after reload.

Start with local Host-mediated routing

The first implementation uses local clients that the Host creates from explicit method and event contracts.

Kit payloads must use the serializable KitValue model. Raw Provider objects must remain inside the Provider session.

Later phases can map the same contracts to Eventa, WebSocket, Electron IPC, MessagePort, or isolated processes.

Global disable preserves user intent

The plugin-system switch should temporarily stop Extension activation while preserving each Extension's enabled preference.

Re-enabling the system restores the intended configuration through a new Activation Plan.

Host management operations must remain available while the system is disabled.

Implementation roadmap

Phase 1: Manifest v2 and folder import

Complete in merged PR #2506.

  • Add a strict versioned Extension manifest.
  • Separate manifest schema version, Extension version, and AIRI compatibility.
  • Declare runtime entrypoints.
  • Declare permissions.
  • Declare kits.provides and kits.uses.
  • Validate unknown fields and unsafe identifiers.
  • Add native folder selection.
  • Prepare an import plan before copying files.
  • Reject symbolic links, special files, unsafe entrypoints, and changed sources.
  • Copy through a staging directory and use an atomic final rename.
  • Keep imported Extensions disabled and unloaded.
  • Add Devtools review UI and English and Simplified Chinese text.
  • Complete review and merge PR #2506.

Phase 2: Activation Planner

This is the next implementation Phase. It restarts from current main; closed PR #2549 does not supply the implementation.

  • Build a pure planner from installed manifests and the proposed enabled state.
  • Resolve required and optional Kit dependencies across the full proposed configuration.
  • Reject duplicate Providers before runtime state changes.
  • Reject Host-provided and Extension-provided Kit ID conflicts before runtime state changes.
  • Validate Kit version ranges.
  • Detect dependency cycles.
  • Produce deterministic load and unload order.
  • Return structured diagnostics without changing runtime state.
  • Use the plan for startup, enable, disable, system enable, system disable, load, unload, and reload operations.

Phase 3: Extension-hosted Kit registration

This Phase starts after Phase 2 is accepted and merged. The closed #2549 implementation will be redesigned against the Phase 2 contract.

  • Add ctx.kits.provide(...).
  • Verify that the provided Kit appears in the Extension manifest.
  • Store kitId, version, owner Extension, session, and Provider generation.
  • Reject duplicate pending and active Providers.
  • Revoke all provided Kits during unload.
  • Reject registrations from stale or disposed sessions.
  • Keep business Kit Contracts in independent SDK packages.

Phase 4: Kit Router and bindings

This Phase starts after Phase 3 defines the Provider lifecycle and registration contract.

  • Resolve a Consumer's kits.use(...) request through the Hosted Kit Registry.
  • Create an explicit, inspectable Consumer-to-Provider binding record.
  • Inject caller identity at the Host boundary.
  • Route requests, responses, events, errors, and cancellation.
  • Define correlation keys and timeout behavior.
  • Reject work from a replaced or stopped Provider generation.
  • Reject calls after unload or revocation.
  • Notify Consumers when a Provider becomes available or unavailable.
  • Apply permissions at the routing boundary.

Phase 5: Inspection and diagnostics

  • Show installed, enabled, loaded, failed, and blocked states separately.
  • Show provided and consumed Kits.
  • Show Provider ownership and generation.
  • Show resolved bindings.
  • Show missing dependencies and version conflicts.
  • Show duplicate Provider conflicts.
  • Show permission denials.
  • Add deterministic Provider and Consumer development fixtures.
  • Add development fixtures for conflict, reload, and failure cases.

Phase 6: User-facing plugin management

  • Add a plugin-system global switch.
  • Add an Extension management page outside Devtools.
  • Import an Extension from a folder.
  • Review identity, source, permissions, and Kit dependencies before installation.
  • Enable and disable an Extension.
  • Load and unload an Extension.
  • Uninstall an Extension.
  • Explain blocked activation with actionable diagnostics.
  • Recover safely from invalid or failed Extensions.

Phase 7: Isolation and remote routing

  • Define the Extension process isolation boundary.
  • Reuse the same Kit contracts across local and remote transports.
  • Add transport-independent request envelopes.
  • Handle disconnects and pending requests.
  • Define reconnect and recovery behavior.
  • Keep permissions and caller identity enforced by the Host.

Agent Activity reference implementation

agent-activity-airi should be developed alongside these phases as a vertical reference implementation.

Its purpose is to verify that the plugin system supports a real external Extension without adding agent-specific logic to the Host.

Proposed external packages:

agent-activity-contract
agent-activity-provider
agent-activity-adapter-codex
agent-activity-adapter-claude
agent-activity-adapter-pi
agent-activity-reaction-airi

The first Codex integration should support:

  • Explicit installation.
  • Explicit approval to install or use the Codex Hook.
  • Main Codex task only.
  • One-way communication to AIRI.
  • Notification when Codex needs user input.
  • Notification when a Codex task completes.
  • AIRI text and semantic reactions.
  • AIRI expressions and character motion.
  • A short-lived sender process.
  • Fast failure when AIRI is unavailable.
  • No persistent background service in the first version.

As this implementation progresses, each missing general capability should be added to the relevant plugin-system phase and verified through the reference plugin.

For example:

Agent Activity need Plugin-system capability
Install the AIRI reaction Extension Manifest validation and folder import
Ask permission to install a Hook Permission review and consent
Connect an adapter to the Provider Extension-hosted Kit registration
Deliver activity events Kit Router and Eventa contracts
Reload the Provider safely Provider generation and binding revocation
Explain why activation failed Activation Planner diagnostics
Turn off all integrations temporarily Plugin-system global switch
Support Claude Code and Pi Agent Separate adapters using the same Kit Contract

Acceptance criteria

The plugin-system foundation is complete for the first Agent Activity integration when:

  • A user can import the required Extensions from folders through Devtools.
  • AIRI validates manifests before installation.
  • AIRI displays requested permissions and Kit dependencies during import review.
  • Conflicting Providers fail before runtime state changes.
  • A Provider Extension can register the Agent Activity Kit.
  • A Consumer Extension can discover and use that Kit.
  • The Host routes events without understanding agent-specific payloads.
  • Unload and reload revoke stale bindings and pending work.
  • Devtools explain Provider, Consumer, binding, and failure state.
  • The global plugin-system switch stops and restores Extensions safely.
  • The Codex adapter can notify AIRI when the main task needs input.
  • The Codex adapter can notify AIRI when the main task completes.
  • AIRI reacts through text, semantics, expressions, and motion.
  • Agent-specific types remain outside the AIRI Host.

Related work

  • #255
  • #520
  • #1423
  • #2476
  • Merged PR #2506
  • Closed draft PR #2549 — abandoned combined Phase 2 to Phase 5 exploration; not merged and not an implementation base

Future ideas

These ideas are outside the first implementation:

  • Merge or rewrite Kit client interfaces.
  • Allow several Providers for one Kit.
  • Select Providers by priority, user preference, or capability.
  • Add an Extension marketplace.
  • Add signed Extension packages.
  • Add managed upgrades and rollback.
  • Support richer bidirectional agent interactions.
  • Run untrusted Extensions in isolated processes.

Source: moeru-ai/airi

View original on GitHubView discussion on GitHub