blitzdotdev/blitzos/cordis-plugin-development

Develop Dynamic Cordis Plugins

First determine whether a capability belongs on Host or Client, then query the real interface before writing code. Never infer a complete API from a Service name, Event payload, Slot props, theme token, or example.

Standard workflow

1. Call cordis_inspect_list to obtain the Providers, methods, and schemas currently registered on Host and Client.
2. Select the smallest set of cordis_inspect_query calls needed to read the exact Services, Events, Builtins, Slots, Theme tokens, or Tools that the implementation will use.
3. For a new Plugin, design its first Package. To modify an existing Plugin, first use cordis_inspect_self(pluginId, packageId) to read the base source and diagnostics.
4. Write plain JavaScript in code.host, code.client, or both, then call cordis_define.
5. Call cordis_run with the final pluginId and packageId returned by define.
6. Handle approval, waiting, Client loading, and render failures from the Run card, steering messages, or cordis_inspect_self.
7. Use cordis_stop to disable the Plugin temporarily. Use cordis_undefine only when it is no longer needed.

Do not wait in the same turn for user approval or asynchronous browser results. After cordis_run returns awaiting-approval or starting, end the current Tool flow and wait for the system to report the final outcome through state updates and steering.

Tool usage guidance

Choose a platform

Prefer the capability closest to the data owner. If Slot props already provide the Conversation Snapshot, do not fetch it again through Host. If only the Package's own styles need to change, do not override the global theme. If only a small entry point is needed, do not replace an entire product UI region.

Provider navigation

Select methods from the actual cordis_inspect_list result. Common initial methods include:

• Service.listService: without service, returns every callable Service with its purpose and exact method signatures. Query the selected service again for access rules, structured method descriptions/parameters/returns, and only its referenced types.
• Event.listEvents: without event, returns every Event with its purpose, dispatch mode, and exact listener signature. Query the selected event again for its structured listener contract and only its referenced types; a Waterfall listener must call next().
• Builtin.listBuiltins: returns evaluator-provided symbols and signatures that cannot be obtained through ctx.get().
• Slots.listSubTree: without root, returns compact live trees with each Slot's purpose, kind, scope, registration keys, replacement risk, and children. With an exact root, it also returns that selected Slot's full contract, props, and current occupants while keeping descendants compact.
• Theme.listTokens: returns theme tokens that may currently be queried and overridden; it does not modify the theme.
• Tool.listTools: returns Tool schemas actually visible to the current Agent, including dynamically registered Tools.

Provider names, methods, and inputs must come from the current list result. The Service/Event Catalog describes which interfaces this version permits; it does not guarantee that a Service is currently mounted. At runtime, use real Services and Events rather than caching or displaying Catalog query results.

Execution environment

Both code.host and code.client are plain JavaScript function bodies that return a Cordis Plugin. They are not compiled by TypeScript, JSX, or a bundler.

Do not use:

• import, require, TypeScript types, as, decorators, or JSX;
• globals not confirmed by Builtin.listBuiltins;
• guessed access to window, document, process, Buffer, fetch, or native timers.

Client React code must use React.createElement(...).

Correct:

return {
  apply(ctx) {
    const slots = ctx.get('slots')
    if (slots === undefined) return
    slots.inject('tool.view.cordis', () => slots.register(
      { name: 'tool.view.cordis', key: 'self' },
      () => React.createElement('div', null, 'Hello'),
    ))
  },
}

Incorrect:

return {
  apply(ctx) {
    return <div>Hello</div>
  },
}

JSX is not the only problem in this example. apply() registers lifecycle contributions and cannot return a React Element as the Plugin result. UI must be registered in a queried Slot.

Access Services

Read optional capabilities with ctx.get(name) by default and handle their absence:

return {
  apply(ctx) {
    const service = ctx.get('serviceName')
    if (service === undefined) return
    service.someMethod()
  },
}

Declare inject only when a Service is a hard dependency and the Plugin must enter waiting until Cordis reactivates it after the Service appears:

return {
  inject: ['requiredService'],
  apply(ctx) {
    ctx.requiredService.someMethod()
  },
}

Do not overuse inject merely to avoid an undefined check. Do not access ctx.requiredService without declaring the injection; the Guard rejects undeclared dependencies.

Manage side effects

Every contribution must be removed after the Plugin is stopped, updated, or removed. Prefer Cordis lifecycle APIs:

• Use ctx.on() to register Event listeners.
• Use ctx.effect() to own an external subscription that returns a disposer.
• Retain disposers returned by Cordis Service, Tool, Slot, timer, and theme APIs.
• Do not create process-wide or page-wide side effects at module scope or outside apply().

Recommended:

return {
  apply(ctx) {
    const service = ctx.get('serviceName')
    if (service === undefined) return
    ctx.effect(() => service.subscribe((value) => {
      console.log(value)
    }))
  },
}

If subscribe() does not return a disposer, first query whether the Service provides a supported cleanup mechanism. Do not assume unload automatically removes arbitrary third-party callbacks.

Host and Client timers

On both platforms, the timer is a Service named timer with the same interface; it is not a Builtin. Query { "service": "timer" } through the corresponding platform's Service.listService before using it. Declare inject: ['timer'] before using the timer mixin.

One-shot delay:

return {
  inject: ['timer'],
  apply(ctx) {
    const onClick = () => {
      ctx.timeout(() => console.log('done'), 300)
    }
    // Pass onClick to a queried Slot UI.
  },
}

Periodic work in a React component:

return {
  inject: ['timer'],
  apply(ctx) {
    function Clock() {
      React.useEffect(() => ctx.interval(() => console.log('tick'), 1000), [])
      return React.createElement('div', null, 'Running')
    }
    // Register Clock in a queried Slot.
  },
}

Incorrect:

return {
  apply(ctx) {
    ctx.timeout(() => console.log('invalid'), 300)
  },
}

setTimeout(() => console.log('invalid'), 300)

The first example does not declare the timer hard dependency. The second uses a global timer that does not exist.

Listen to Events

Query the Event Provider first to confirm the platform, parameter order, return value, and mode.

Ordinary emit Event:

return {
  apply(ctx) {
    ctx.on('some/event', (payload) => {
      console.log(payload)
    })
  },
}

The last parameter of a Waterfall Event is next. Unless the listener intentionally stops downstream processing, it must call and return it:

return {
  apply(ctx) {
    ctx.on('some/waterfall', (payload, next) => {
      console.log(payload)
      return next()
    })
  },
}

Register Client UI

Query Slots.listSubTree without root to choose a target from the compact purpose and topology tree, then query the exact Slot with root before writing its registration. The exact result determines:

• the Slot's purpose in the layout;
• whether its registration protocol is single, list, keyed, or chain;
• registration options;
• scope standard props and business owner props;
• current occupants, replacement risks, and descendant Slots.

Use ctx.get('slots') and handle its absence. Then use slots.inject to wait for the Slot declaration and call slots.register inside the callback:

return {
  apply(ctx) {
    const slots = ctx.get('slots')
    if (slots === undefined) return
    slots.inject('target.slot', () => slots.register(
      { name: 'target.slot', id: 'my-view' },
      (props) => React.createElement('div', null, String(props.someValue)),
    ))
  },
}

ctx.get('slots') does not require an injection. Do not rewrite it as ctx.slots unless inject: ['slots'] is declared:

return {
  apply(ctx) {
    ctx.slots.register({ name: 'target.slot' }, () => null)
  },
}

Do not guess an id, key, selector, or props before querying the Slot protocol. Do not default to root-level root, sidebar, conversation, or details Slots; replacing an entire occupant also removes the descendant Slots it declares.

Settings pages

A full settings UI should usually register its own section through settings.section to obtain a complete content area. settings.general.item is only appropriate for one compact, general-purpose preference. Query the actual subtree, options, and props for both, then select the narrowest entry point that is still sufficient.

Dynamic Plugins are temporary and process-local, so their settings UI does not need persistent storage. Do not add durable settings or another persistence mechanism for it. Register the UI in the appropriate settings Slot and keep any transient interaction state in memory for the lifetime of the Plugin.