Interface: MakaioExtension<THostContext>

Makaio Framework / contracts / MakaioExtension

Interface: MakaioExtension<THostContext>

Defined in: ../../../packages/contracts/src/extension/makaio-extension.ts:122

Executable Makaio extension manifest.

Extends ExtensionManifest with executable code: a service factory, a CLI contribution with interactive TUI support, and a Drizzle storage handler registration callback.

Source-of-truth rule: fields on this executable extension are the runtime wiring source. Serializable descriptor fields, including ExtensionManifest.contributions, are discovery metadata and are not promoted into executable contribution surfaces by the loader.

The host runtime calls create (if defined) with a ExtensionContext to instantiate the service. Window-only extensions that have no background service may omit create entirely.

Example

export const myExtension: MakaioExtension = {
  name: 'my-extension',
  displayName: 'My Extension',
  create: (ctx) => new MyService(ctx.bus),
};

Extends

ExtensionManifest

Type Parameters

THostContext

THostContext extends ExtensionContext = NodeExtensionContext

Concrete context shape supplied by the host runtime. Defaults to NodeExtensionContext because the current framework hosts are Node-based.

Properties

adapters?

readonly optional adapters?: readonly AdapterContribution<unknown>[]

Defined in: ../../../packages/contracts/src/extension/makaio-extension.ts:277

Adapter runtime definitions contributed by this extension.

Each entry pairs JSON-serializable discovery metadata with the full runtime adapter definition typed via AdapterDefinitionContract. The adapter contribution processor consumes this executable field directly; descriptor contributions.adapters is not a registration fallback.

bootstrap?

readonly optional bootstrap?: ExtensionBootstrap

Defined in: ../../../packages/contracts/src/extension/makaio-extension.ts:334

Bootstrap capability for project config import/export.

When present, this extension participates in:

Project export: extension data can be saved to .makaio/bootstrap/
Project import: extension data can be restored from .makaio/bootstrap/

browser?

readonly optional browser?: object

Defined in: ../../../packages/contracts/src/extension/manifest.ts:388

Browser entry point for this extension. URL path the renderer fetches to load the extension’s UI.

entrypoint

entrypoint: string

URL path the renderer fetches to load the extension’s UI. Must be an absolute path (starts with /). The loader additionally enforces a /extensions/ prefix at runtime as defence-in-depth.

Example

'/extensions/my-extension/browser/index.js'

Inherited from

ExtensionManifest.browser

cli?

readonly optional cli?: ExtensionCliContribution

Defined in: ../../../packages/contracts/src/extension/makaio-extension.ts:161

Executable CLI contribution registered under makaio <name>.

The runtime exposes the fully typed helper API through @makaio/kernel/cli when authoring CLI commands. This manifest stores only the type-erased executable shape used after loading.

Overrides

ExtensionManifest.cli

clients?

readonly optional clients?: readonly object[]

Defined in: ../../../packages/contracts/src/extension/makaio-extension.ts:246

Client runtime definitions contributed by this extension.

Loaded clients are passed to createClientsCorePackage during boot and registered with the client bootstrap service. These definitions are the runtime source of truth for client wiring; descriptor contributions.clients is discovery metadata only.

configSchema?

readonly optional configSchema?: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>

Defined in: ../../../packages/contracts/src/extension/makaio-extension.ts:223

Zod schema describing this extension’s configuration shape.

When present, the coordinator:

Exposes the schema as JSON Schema via extension.getConfigSchema RPC
Loads stored config from ExtensionConfigStorageSubjects at boot
Parses it through this schema and injects the result into ExtensionContext.config

The schema should provide .default() values for all optional fields so parsing {} always yields a valid config.

contributions?

readonly optional contributions?: ContributionManifest

Defined in: ../../../packages/contracts/src/extension/manifest.ts:398

Adapters and client binaries contributed by this extension.

Discovery-time metadata only — serializable and safe to inspect without loading any extension code. Runtime activation and registration use the executable contribution fields on MakaioExtension; descriptor metadata may mirror those fields for pre-load introspection but is not used as a fallback wiring source.

Inherited from

ExtensionManifest.contributions

create?

readonly optional create?: (ctx) => ExtensionService | Promise<ExtensionService>

Defined in: ../../../packages/contracts/src/extension/makaio-extension.ts:135

Factory that creates and returns the extension’s service.

Optional — window-only extensions that have no background service may omit this field entirely. When present, the host calls this during startup; the extension is responsible for all internal composition (choosing backends, creating sources, etc.) based on the provided context.

Parameters

ctx

THostContext

Runtime context with bus, host details, and machine identity.

Returns

ExtensionService | Promise<ExtensionService>

The extension’s service instance (not yet initialized — host calls init).

critical?

readonly optional critical?: boolean

Defined in: ../../../packages/contracts/src/extension/makaio-extension.ts:153

When true, startup fails if this extension fails to initialize.

Optional extensions default to isolated failure so one extension cannot prevent the runtime from booting. Framework and host core extensions set this to true when the runtime cannot safely continue without them.

dependencies?

readonly optional dependencies?: readonly string[]

Defined in: ../../../packages/contracts/src/extension/manifest.ts:355

Names of other extensions this extension depends on.

The registry ensures dependencies are initialized before this extension. Values are ExtensionManifest.name identifiers.

Inherited from

ExtensionManifest.dependencies

displayName

readonly displayName: string

Defined in: ../../../packages/contracts/src/extension/manifest.ts:340

Human-readable display name shown in UI surfaces (e.g. 'Auth Switcher').

Inherited from

ExtensionManifest.displayName

http?

readonly optional http?: object

Defined in: ../../../packages/contracts/src/extension/makaio-extension.ts:169

Server-side HTTP routes. Hosts that support HTTP route contributions call mount() on a fresh, rebuildable app graph as extensions activate or stop. Contracts keeps the app type erased so this layer does not depend on Hono.

mount

readonly mount: (app) => void

Parameters

app

unknown

Returns

void

prefix

readonly prefix: string

Param

Host-owned HTTP app instance.

logImport?

readonly optional logImport?: LogImportContribution

Defined in: ../../../packages/contracts/src/extension/makaio-extension.ts:285

Log import capability for external tool session import.

Opaque in contracts. The log-import contribution processor narrows config to PluginLogImport at processing time.

name

readonly name: string

Defined in: ../../../packages/contracts/src/extension/manifest.ts:338

Unique extension identifier.

Accepts plain identifiers (e.g. 'account-manager') and npm-scoped names (e.g. '@acme/weather-tools'). Used as the primary key in the extension registry and as the top-level CLI command name when no cli override is provided.

Inherited from

ExtensionManifest.name

namespace?

readonly optional namespace?: ExtensionNamespaceContribution

Defined in: ../../../packages/contracts/src/extension/makaio-extension.ts:343

Bus namespace introspection for this extension.

The domain is auto-prefixed to 'extension:NAME' to avoid collisions. Register schemas statically in a namespace.ts file for type-safe subjects, then reference them here for documentation and introspection.

providers?

readonly optional providers?: readonly object[]

Defined in: ../../../packages/contracts/src/extension/makaio-extension.ts:263

Provider definitions contributed by this extension.

Each entry defines a model provider (e.g., Anthropic, OpenAI) with its supported models, capabilities, and credential requirements. Loaded providers are registered with the provider subsystem during boot.

Provider definitions are executable extension contributions. Descriptor contributions.providers may mirror provider identity metadata for pre-load discovery, but is not a registration fallback.

provides?

readonly optional provides?: readonly CapabilityToken[]

Defined in: ../../../packages/contracts/src/extension/manifest.ts:369

Capability tokens this extension provides when active.

Consumers and onboarding surfaces can inspect these declarations to decide whether a capability exists at all before prompting the user to configure it.

Inherited from

ExtensionManifest.provides

requires?

readonly optional requires?: readonly string[]

Defined in: ../../../packages/contracts/src/extension/manifest.ts:362

Host-provided environment capability tokens this extension requires.

This is an environment compatibility gate, not an extension-to-extension dependency. Use dependencies for structural extension ordering.

Inherited from

ExtensionManifest.requires

runtimeBoot?

readonly optional runtimeBoot?: ExtensionRuntimeBootContribution<THostContext>

Defined in: ../../../packages/contracts/src/extension/makaio-extension.ts:145

Boot-time executable contribution for registering runtime processors or services before package startup begins.

runtimeOwnership?

readonly optional runtimeOwnership?: ExtensionRuntimeOwnership

Defined in: ../../../packages/contracts/src/extension/makaio-extension.ts:140

Executable ownership declarations for runtime responsibilities that must have exactly one owner in a booted runtime.

sessionEventActions?

readonly optional sessionEventActions?: ExtensionSessionEventActionsContribution

Defined in: ../../../packages/contracts/src/extension/makaio-extension.ts:325

Session event action factory for this extension.

When present, the runtime calls createActions(ctx) after all dependencies are loaded and registers the returned declarations with SessionEventActionService. Unregister callbacks are stored for shutdown cleanup.

storage?

readonly optional storage?: StorageManifest & object

Defined in: ../../../packages/contracts/src/extension/makaio-extension.ts:185

Executable storage contribution.

Extends StorageManifest (migration paths) with a Drizzle handler registration callback invoked by the composition root after migrations have been applied but before services are started.

The db parameter is typed as unknown in the contracts layer (which does not take a drizzle dependency) — composition roots cast it to MakaioDatabase before calling. The returned cleanup function is invoked during graceful shutdown to unregister bus handlers.

Type Declaration

migrationSourceId?

readonly optional migrationSourceId?: string

Stable runtime identity for the migration bundle.

Bundled hosts use this instead of packaged output paths when they need a durable key for migration deduplication and embedded lookup.

packageRoot?

readonly optional packageRoot?: string

Absolute extension root used to resolve relative storage asset paths.

Required when a code-defined extension declares relative StorageManifest.migrations paths, since there is no descriptor file path for the runtime to infer from.

registerHandlers?

readonly optional registerHandlers?: (bus, db, ctx) => void | (() => void)

Registers Drizzle-backed bus storage handlers for this extension.

Parameters

bus

IMakaioBus

The application bus instance.

db

unknown

The Drizzle database instance (typed opaquely here; cast at the call site).

ctx

THostContext

Runtime extension context supplying host details and machine identity (e.g., for machine-scoped storage registration).

Returns

void | (() => void)

Optional cleanup function called during shutdown to unregister handlers.

Overrides

ExtensionManifest.storage

surface?

readonly optional surface?: "any" | "interactive" | "headless"

Defined in: ../../../packages/contracts/src/extension/manifest.ts:348

Execution surface the extension targets.

'interactive' — requires a UI shell (e.g., Electron renderer).
'headless' — suitable for daemon or CLI-only runtimes.
'any' — works in any surface (default when omitted).

Inherited from

ExtensionManifest.surface

tools?

readonly optional tools?: ExtensionToolsContribution<THostContext>

Defined in: ../../../packages/contracts/src/extension/makaio-extension.ts:299

Tool contribution factory for this extension.

When present, the runtime calls createToolsets(ctx) after all dependencies are loaded and registers the returned toolsets with ToolRegistry. Extensions that contribute tools should declare a dependency on the tool-registry service if one is required for registration.

tray?

readonly optional tray?: TrayManifest

Defined in: ../../../packages/contracts/src/extension/manifest.ts:373

System tray entry for this extension.

Inherited from

ExtensionManifest.tray

triggers?

readonly optional triggers?: ExtensionTriggersContribution

Defined in: ../../../packages/contracts/src/extension/makaio-extension.ts:315

Hash trigger factory for this extension.

When present, the runtime calls createTriggers(bus) after all dependencies are loaded, then registers the returned triggers with HashTriggerService.

Extensions declaring triggers should depend on 'hash-trigger' to ensure the service exists when triggers are registered.

ui?

readonly optional ui?: ExtensionUiContribution

Defined in: ../../../packages/contracts/src/extension/makaio-extension.ts:356

Browser UI contributions for this extension.

Groups all UI-layer contribution surfaces. Absent for headless-only extensions. The coordinator passes this bag to the web-framework loader which bridges each surface to the appropriate client-side registry.

uiConfig?

readonly optional uiConfig?: object

Defined in: ../../../packages/contracts/src/extension/makaio-extension.ts:232

UI configuration for schema-driven configuration forms.

Controls how the config form is rendered: edit mode (slidePanel vs full), which fields to hide, and per-field widget overrides (e.g. slider, color picker). Only meaningful when configSchema is also declared.

editMode

editMode: "inline" | "slidePanel" | "fullPage"

The editing mode for this entity

inline: Edit directly in the list/card
slidePanel: Edit in a slide-out panel
fullPage: Edit on a dedicated full page

fieldOverrides?

optional fieldOverrides?: Record<string, { delimiter?: string; helpText?: string; max?: number; min?: number; options?: object[]; placeholder?: string; step?: number; widget?: string; }>

Field-specific overrides for custom widgets and behavior Maps field name to widget configuration

hiddenFields?

optional hiddenFields?: string[]

Fields to hide from the form UI These fields will not be rendered and cannot be edited

readOnlyInEditMode?

optional readOnlyInEditMode?: string[]

Fields that are read-only in edit mode These fields are visible but cannot be modified during editing

sections?

optional sections?: object[]

Optional form sections for grouping related fields. When provided, fields are rendered in the given section order.

windows?

readonly optional windows?: readonly WindowManifest[]

Defined in: ../../../packages/contracts/src/extension/manifest.ts:371

Windows this extension can open, keyed by WindowManifest.id.

Inherited from

ExtensionManifest.windows