Plugin internals

Plugin authors extend the running Cordis tree through published Harness services. Start with User plugins for installation and Write a plugin for an executable example.

Available extension points

CapabilityInterfaceTerminal behavior
Slash commandsdsh-commands metadata, handlers and completionCommands appear in Help, completion and the runner.
ToolsHarness tool registration and ToolDefinition.presentCall / presentResultThe TUI renders provider-declared content with its own padding, wrapping and generic fallback.
Models and authorizationctx.llm and registered ctx.authorization flowsModels appear in the picker, and /login presents the flow’s notices and prompts.
Settings and credentialsctx.settings and ctx.credentialsSchema-declared live settings can appear in Advanced, subject to automatic-form policy. Secret values use the credential service.
Questions and noticesctx.tui.prompt, notice and commandOutputThe local provider owns focus, cancellation, readable results and return to the composer.
Session behaviorHarness Agent/session services and durable eventsPlugins observe lifecycle and contribute behavior within their Cordis scope.
Personas and skillsAgent presets and the Harness skill registry/agent selects a preset before model history exists, and /<skill-name> invokes a skill.

Declare required services in the plugin’s inject list and register effects through its Cordis context so unloading releases them. Use the installed package’s exports and types as the contract. The TUI manifest lists the shipped provider, service definition, runtime and command entry points.

Terminal ownership

The local provider owns raw mode, decoded input routing, cursor state, viewport layout, mouse selection and terminal writes. The runner is the single consumer of readInput. Plugin questions use prompt() and the request’s cancellation signal. Human approvals have priority over ordinary browsing.

The product owns the composer, status footer, theme palettes, transcript layout and Settings categories. Plugins contribute tool presentation intent through presentCall and presentResult. Advanced exposes eligible live schema fields, while specialized forms use the owning command and prompt service. The fixed footer formats Harness projections and degrades lower-priority metrics as width shrinks.

Custom presentation registries remain a design possibility. ctx.tui.contributions, custom component factories and theme-pack registration have no published API. Introducing one requires independently owned consumers whose needs exceed the existing tool and prompt contracts. Its lifecycle, compatibility, cancellation, focus restoration and width behavior must be specified and verified before public export. Existing implementation modules remain internal unless the package export map explicitly exposes them.

Durable events must satisfy the published session schema. Readers can skip an unknown event only when it is explicitly ignorable and safe to omit. A visual extension therefore needs a durable replay contract before it can add new conversation facts. Permission decisions continue through Harness authorization and audit.

Response language and complete personas

The product’s Response language setting contributes a system-prompt section. Follow UI resolves the interface language at the next turn; Auto contributes an empty fragment. A custom persona with complete: true must append {{omdsh_agent_behavior}} to honor the preference because complete personas suppress ordinary sections. The owning plugin and turn snapshot contract are documented in the Agent behavior design.

Composition and lifecycle

apps/omdsh owns Profile loading, installation and application composition. The TUI package owns terminal presentation and interaction. User bundles share the published Harness services and must declare compatible peers to preserve service identity. CLI package operations require a restart. Runtime plugin operations report whether they applied live or require a restart, while existing Agent compositions retain their revision.

Any future presentation seam must preserve display-cell layout, ANSI handling, CJK and emoji width, composer drafts, attachment order, cancellation and terminal restoration. Verification includes exceptions, unload, resize and nested human prompts. Source lookup and existing tests are described in Architecture.