01Every plugin gets its own Fiber

A plugin is not a static module that is simply loaded and forgotten. The framework creates a Fiber for every loaded plugin — an isolated scope and lifecycle unit. Everything the plugin does through ctx inside apply (registering listeners, registering tools, acquiring resources) is booked under this Fiber, and the framework reclaims it all when the plugin unloads.

Start with a minimal plugin and watch its lifecycle output:

import type { Context } from '@deepseek-ai/cordis'

export const name = 'lifecycle-demo'

export function apply(ctx: Context) {
  console.log('[lifecycle-demo] plugin loading')

  // setup runs immediately; the returned cleanup runs on unload
  ctx.effect(() => {
    console.log('[lifecycle-demo] effect registered')
    return () => {
      console.log('[lifecycle-demo] effect cleaned up')
    }
  })
}

On load, apply prints "plugin loading", and the ctx.effect setup runs immediately and prints "effect registered"; on unload, the cleanup function runs and prints "effect cleaned up". The steps below break each of these behaviors down.

02The state machine: six states

At any moment, each Fiber is in one of six states:

• PENDING — declared, but required dependencies are not ready yet;
• LOADING — dependencies are ready and apply is executing;
• ACTIVE — the plugin is running;
• FAILED — apply threw an error;
• UNLOADING — the plugin is unloading and releasing resources;
• DISPOSED — the plugin is fully unloaded.

The happy path goes through PENDING, LOADING, ACTIVE, and UNLOADING, ending at DISPOSED. If apply throws while executing, the plugin goes from ACTIVE to FAILED — an error branch with no automatic retry; fix the code and reload.

03Dependency-driven loading and unloading

A plugin that declares inject does not load immediately — it stays PENDING until every required service is ready, and only then enters LOADING. This is why injected services are always usable inside apply: the framework eliminates the timing race for you.

The reverse also holds: if a required service disappears at runtime (for example, when its provider is replaced), every plugin that depends on it is unloaded automatically, going ACTIVE straight to DISPOSED; when the service comes back, those plugins reload automatically. No reconnection or retry logic on your side.

04Automatic cleanup: everything via ctx

The Fiber’s most convenient property: every registration made through ctx is revoked automatically on unload. The framework tracks and disposes of four kinds of registrations:

• ctx.on(event, handler) — event listeners;
• ctx.tools.register(tool) — tool registrations;
• ctx.llm.registerAdapter(names, adapter) — LLM adapter registrations;
• ctx.effect(() => cleanup) — custom resources.

In the snippet below, event, handler, tool and so on are placeholders for the objects you would register in a real plugin:

import type { Context } from '@deepseek-ai/cordis'

export function apply(ctx: Context) {
  // all of these registrations are revoked automatically on unload
  ctx.on(event, handler)                        // event listener
  ctx.tools.register(tool)                      // tool registration
  ctx.llm.registerAdapter(names, adapter)       // LLM adapter

  // custom resource: setup runs immediately, the returned cleanup runs on unload
  ctx.effect(() => {
    const timer = setInterval(() => {}, 1000)
    return () => clearInterval(timer)
  })
}

This means most plugins need no teardown code at all: listeners and tools vanish with the Fiber. Only resources created outside ctx (raw timers, native connections, file handles) need to be registered explicitly with ctx.effect.

05ctx.effect semantics

Two semantics of ctx.effect are easy to get wrong, and they decide whether your cleanup is reliable.

import type { Context } from '@deepseek-ai/cordis'

export function apply(ctx: Context) {
  const conn = createConnection()
  const session = conn.startSession()

  // order-dependent cleanup: one disposer, awaited serially inside
  ctx.effect(() => {
    return async () => {
      await session.close() // close the session first
      await conn.close()    // then drop the connection
    }
  })
}

06Nested contexts and child Fibers

ctx.plugin() creates a child Fiber under the current one. The child inherits the parent context (it can reach the same services) but has an independent lifecycle:

import type { Context } from '@deepseek-ai/cordis'

// child plugin: inherits the parent context, with its own lifecycle
const childPlugin = {
  name: 'child-plugin',
  apply(ctx: Context) {
    console.log('[child] loaded')
  },
}

export function apply(ctx: Context) {
  const fiber = ctx.plugin(childPlugin)
  console.log('[parent] child fiber created:', fiber)
}

A typical use is splitting a large plugin into internal modules that each manage their own registrations. When the parent unloads, its children unload with it — no manual cleanup required.

07Manual dispose and its guarantees

ctx.plugin() returns a handle to the child Fiber, and calling dispose() on it unloads the plugin manually:

import type { Context } from '@deepseek-ai/cordis'

export async function apply(ctx: Context) {
  const fiber = ctx.plugin(myPlugin)

  // unload manually when needed
  await fiber.dispose()
  // 1. every registration owned by the plugin is removed
  // 2. child plugins are unloaded recursively
  // 3. the promise resolves only after all async cleanup finishes
}

await fiber.dispose() gives three guarantees: every registration owned by the plugin is removed; child plugins are unloaded recursively; and the returned promise resolves only after all async cleanup finishes. The third one matters most — dispose() does not return as soon as unload starts, it returns when cleanup is fully done. When your next step depends on the unload being complete (a reload, for example), awaiting it is the safe move.

08Hot replacement (HMR)

Restarting on every edit is slow. With @deepseek-ai/cordis-plugin-hmr loaded from cordis.yml, saving a plugin source file triggers hot replacement automatically:

# cordis.yml: enable the HMR plugin
- insert:
    - id: hmr
      name: '@deepseek-ai/cordis-plugin-hmr'

Hot replacement takes three steps: unload the old plugin and clean up all its registrations, load the new code, then run the new apply. No Harness restart needed — edits take effect on save.