Plugin Lifecycle

Plugin lifecycle is about long-lived runtime ownership.

It is not the same thing as:

• static enablement
• runtime availability
• one-shot actions

The lifecycle surface

A lifecycle-capable plugin may declare:

• lifecycle.start
• lifecycle.stop
• lifecycle.command

These hooks are for plugin-owned runtime behavior, not for normal one-shot capability calls.

When lifecycle is the right shape

Use lifecycle when the plugin must own:

• workers
• poll loops
• long-lived connections
• in-memory runtime state
• recoverable runtime engines

Typical examples:

• chat
• task
• memory
• shell

ActionSchedule is not a plugin. It is an Agent-level action scheduling loop that boots together with plugin lifecycles when the Agent is constructed.

Runtime state is not enablement

These are different facts:

• enabled: whether the current project config says the plugin is on
• available: whether runtime checks say the plugin is usable now
• running: whether the lifecycle runtime is currently started

Runtime state snapshots

Current runtime state snapshots use states such as:

• running
• stopped
• starting
• stopping
• error

What starts lifecycle plugins

In the local SDK, plugin lifecycles boot automatically inside new Agent(...). Call await agent.ready() to wait for them, and await agent.dispose() to stop them.

Advanced runtime code may also use exported helpers such as:

• startAllPlugins(context)
• stopAllPlugins(context)

Lifecycle command vs action

Use lifecycle.command when the plugin needs one runtime-control command such as:

• reload
• reschedule
• restart

Use actions when the plugin is exposing normal capability work.

task is a good example of a plugin that has both.

Managed vs local plugin mental model

One useful distinction is:

• local plugin: does not depend on a running lifecycle
• managed plugin: owns lifecycle behavior

Related docs

• Plugin Availability
• Plugin Design Patterns
• Built-ins Overview