@agimon-ai/doompi-extension-contracts

Validated payloads, named Cordis services, and lifecycle contracts shared by DoomPi extensions.

Part of the DoomPi distribution.

This is a library, not a Pi extension: it has no Pi manifest and nothing to add to a DoomPi layer. It declares Pi as an optional peer for the host bridge types. Extension authors install it when contributing to shared DoomPi surfaces.

Alpha: service and event contracts may change between releases.

Requirements

• Node.js 22.19.0 or newer

Install

npm install @agimon-ai/doompi-extension-contracts

Contract map

Focused subpaths define ownership boundaries. Use /protocol only for genuine process or transport boundaries; same-runner extensions collaborate through the named Cordis services and events below.

Subpath	Contract
/protocol	Runtime creation, request/reply, notification, job, validation, and protocol errors
/cordis-host	Versioned host discovery, runtime/session services, and standalone fallback
/mode	doom/minor-mode-catalog registration, snapshots, and owner-routed actions
/ui-hub, /leader, /footer	doom/ui-hub aggregation and typed UI contribution values
/help	doom/help contributions and active-skill snapshots
/skills, /loop-launchers	Provider-owned registries for skill directories and recurring-loop launchers
/voice-tools, /narration	doom/voice-tools registration and doom/narration requests
/notification	Versioned doom/notification requests and doom-notification session entry data
/ask-user	Typed doom/ask-user/* fan-out events
/voice-reload-handoff	Generation- and TTL-fenced Voice reload handoff state
/background-work, /delegation	Team-owned Cordis services and events for background/delegated work
/subagent-policy, /subagent-tool	Team-owned policy service and tool boundaries
/mcp-projection	Immutable, session-scoped MCP configuration projection over Cordis
/readiness	Generation-safe package initialization and Cordis service coordination
/config, /mcp-status, /transition	Other shared DoomPi service and transition-coordination surfaces
/child-process, /fable-plan	Process-role and Team-owned Fable service contracts
/context-contributions	Session-scoped broker for bounded, provider-rendered context
/tool-overrides	Runtime-scoped ownership registry for Pi tool replacements
/mcp-session	Validated MCP session documents for child-process boundaries
/mcp-tool-resolver	Session-scoped resolution of MCP selectors to registered Pi tools

Schemas validate data at package boundaries. Notification callers submit bounded body text with optional title, subtitle, and info, warning, or error level. Providers publish normalized version 1 entry data with every field present under the doom-notification entry type. Live collaboration providers are mounted in Cordis plugin fibers; consumers use ctx.inject(...), so provider unload and replacement automatically retract and rebind their handles.

Example: contribute a Leader binding

import { DOOM_UI_HUB_SERVICE, requireDoomUiHub } from '@agimon-ai/doompi-extension-contracts/ui-hub';
import type { Context } from '@deepseek-ai/cordis';

export function reviewPlugin(ctx: Context): void {
  ctx.inject([DOOM_UI_HUB_SERVICE], (uiContext) => {
    const handle = requireDoomUiHub(uiContext).registerLeader({
      source: '@example/review-extension',
      bindings: [
        {
          id: 'review.open',
          path: [{ key: 'r', label: 'review' }],
          command: { name: 'review' },
        },
      ],
    });
    return () => handle.dispose();
  });
}

Mount this plugin beneath the shared Doom Cordis host. The injection fiber stays pending until the UI provider appears, owns the registration while it is active, retracts it when the provider disappears, and rebinds it to a replacement provider.

Session boundaries

The contracts coordinate runtimes; they do not create global persistence. Team owns doom/background-work, doom/delegation, doom/subagent-policy, and doom/fable-plan for the active session. Parent and child processes install their own providers and consumers. Fiber lifetime and generation tokens prevent stale providers from controlling a later session.

Use these contracts when authoring DoomPi extensions, host adapters, Help contributors, Leader entries, mode owners, Team consumers, transition integrations, or Voice-aware capabilities.

The readiness coordinator lets factories register capabilities immediately while package-specific startup continues in the background. Calls can await only the package they use, and session disposal aborts pending generations before hot reload installs replacements.

Development

pnpm build
pnpm typecheck
pnpm test
pnpm lint

Maintained by Agimon.

License

MIT