Inspect and manage extensions

While you build or debug an extension for DataMind Oda, Oda can look inside the extension runtime without changing anything. Two read-only calls do the looking, and the plugins Oda builds in Creator mode are installed as persistent bundles.

List, then query

Inspection happens in two calls:

The list call returns the inspect providers as formatted JSON. It is always first: a query needs the exact names it returns.
The query call asks one provider method for its data. Its inputs are the platform (host or client), the provider, the method and the input the method expects.

The list step is titled List Inspect Providers. A query step is titled Query followed by the platform, provider and method it asks about, as in Query host Service.listService.

Use the exact names the list result returns; do not guess them. A query sent to the client side waits for the first valid page: it stays pending until a page answers or the call is cancelled.

What you can inspect

Four providers come with the extension runtime:

Provider	Method	What it answers
`Service`	`listService`	The runtime's services: first a compact directory of keys and signatures, then one service's full contract.
`Event`	`listEvents`	The events a plugin can listen to, directory first. Events the runtime forwards internally are left out.
`Config`	`listConfigs`	The live plugin entries with their configuration status, paged as below.
`Tool`	`listTools`	The tools the asking agent can call, including scoped and dynamic registrations.

None of these calls can change anything. A query cannot invoke a service's methods or modify the running system, a Config query never runs a configuration's validators or transforms, and an inspection method is not a service that plugin code can call.

The catalogue behind the answers

The Service and Event answers come from a catalogue generated from the runtime itself, so it describes what this build actually exposes:

A directory answer lists each service and event with a summary and its signature. The current build counts 87 services and 77 events, with 883 types behind their signatures.
An exact answer adds the full contract: for a service, its methods and how a plugin should depend on it (an optional lookup that checks for absence, or a declared hard dependency); for an event, its parameters and how it is dispatched.
The client side answers the same way: a client query serves the slot catalogue, the seats where a plugin's interface can register, and registrations that failed can be read back from a temporary table.
Availability can differ between installations, so read the directory instead of assuming a name is there.

How a host half declares the services it uses is on The host half of a dynamic package.

Config queries and paging

A Config query accepts four fields:

entry: the id of one entry. Without it, you get a page of the entry directory.
name: an exact plugin name, to narrow the directory.
offset: where the page starts (default 0).
limit: how many entries one page holds (default 25, maximum 100).

A directory page reports the total and where the next page starts; the last page has no next page. Ask for one entry and you get that entry: its status, and, when it has one, its exact JSON schema.

What an entry's status means

Status	Meaning
`schema`	The entry has a configuration schema; query the entry to read it.
`absent`	No configuration is present for the entry.
`unsupported`	The configuration is not a form the inspector can show.
`tree`	The entry carries other entries instead of being one plugin, so it has no schema of its own.
`inactive`	The entry is not active: it is disabled, was never loaded, or has stopped.

Disabling a plugin after it has run flips its status to inactive.

Installed plugin bundles

When you work in Creator mode, Oda can build a plugin and install it as a persistent bundle rather than as a package that lives only in its chat. Installing is a managed operation:

An install can be refused or cancelled; a cancelled install reports cancelled, too-late or not-running.
If an install fails, is cancelled, or adds a package without a bundle change of its own, the package manifest and lockfile are restored as they were. Files already downloaded can stay.
To install a plugin yourself, from a package, a repository or a local folder, see Install a plugin.

The other way round, a dynamic package is defined and run inside a single chat; Dynamic packages covers running, approving and removing one.

When a call is refused

A refused call changes nothing. The message tells you what was wrong:

Wrong field values are refused: offset must be a non-negative integer, limit must be an integer from 1 to 100, and <key> must be a non-empty string, where <key> is the field's name, as in name must be a non-empty string.
unknown entry id "<id>": no entry has that id. Run the list call and query with an id from its result.
unknown Tool inspect method "<method>": the provider has no such method. The provider's name replaces Tool for the other providers; use the method names the list call returns.
A name that is not in the catalogue is refused with no catalogued Service named "<key>" or no catalogued Event named "<name>".
An inspection call must come from a session with an agent behind it; without one the call is refused and inspects nothing.
A Config query needs the live plugin directory of the running installation; an installation built without it refuses Config queries.
A query can fail on the provider's side: a provider that is unavailable or has no such method refuses the call, and an input it rejects, or an answer that is not valid JSON, fails it. A client query can also be cancelled while it waits.

Questions, answered

Can inspection change anything, or run a plugin's code?

No. Both calls are read-only: they cannot invoke a service's methods or change the running system, and a Config query never runs a configuration's validators or transforms.

Which providers can I inspect?

Service, Event, Config and Tool. Run the list call first: it returns them, and a query uses their exact names.

Why is an event missing from the `Event` list?

The Event provider leaves out the events the runtime forwards internally. Everything it lists is an event a plugin can listen to.

How many config entries does one query return?

25 by default, up to 100 per page. Page with offset; the directory page tells you where the next page starts, and the last page has no next page.

What does the `tree` status mean?

The entry carries other entries instead of being one plugin, so it has no schema of its own. The entries it holds are listed in the directory themselves.

What makes a config entry `inactive`?

It is not active: it is disabled, was never loaded, or has stopped. Disabling a plugin after it has run flips its entry to inactive.

Why was my query refused with `unknown entry id`?

The id is not in the directory. Run the list call and query with an exact id from its result.

Why did a query refuse my `offset` or `limit`?

One of the values is out of range: offset must be 0 or more, and limit must be 1 to 100. Correct the value and run the query again.

A client query seems to wait a long time. When does it finish?

It settles when the first valid page arrives, or when the call is cancelled. While it waits, it is not an error.

Why can this installation not run `Config` queries?

A Config query needs the live plugin directory of the running installation; an installation built without it refuses Config queries.

What happens to a plugin install that is cancelled or fails?

A cancelled install reports cancelled, too-late or not-running. If an install fails, is cancelled, or adds a package without a bundle change of its own, the package manifest and lockfile are restored as they were; files already downloaded can stay.