源码版本47f9438 (dsh@0.1)

Plugin Context API

dsh exposes "Cordis runtime introspection" to the agent via the tool-cordis extension — seven tools cover the full flow of discovery / query / define / activate / stop / delete. The Inspect Provider model turns every Host / Client-side Service / Event / Builtin / Tool / Slot / Theme into a "progressive catalog → precise contract" two-step query; the API catalog is generated by scripts/gen-cordis-api.ts from the same source as the docs, ensuring the signatures the agent sees match the human-facing docs.

The tool-cordis Extension

packages/extensions/tool-cordis/src/index.ts:26-40:

export const name = 'tool-cordis'
export const inject = ['tools', 'systemPrompt', 'dynamicCordisRunner', 'cordisInspect']

export function apply(ctx) {
  // register system prompt section
  // register host inspect providers
  // register seven tools
}

Seven Tools

1. cordis_inspect_list: Discovery

packages/extensions/tool-cordis/src/index.ts:41-58:

cordis_inspect_list  // no parameters
  → ctx.cordisInspect.list()
  → manifests of all Providers (id / description / methods / input-output schema)

2. cordis_inspect_query: Precise Contract

packages/extensions/tool-cordis/src/index.ts:60-94:

cordis_inspect_query
  → platform / provider / method / input
  → ctx.cordisInspect.query(...)

The agent must list before querying — guessing names is forbidden.

3. cordis_inspect_self: Self-Check

packages/extensions/tool-cordis/src/index.ts:96-120:

• No ID → list all Plugin summaries of the current Session
• Only pluginId → return the version pointer + most recent Run
• Both pluginId / packageId → return the source code and diagnostics

cordis_inspect_self is the agent's self-check tool: discover the cause of PENDING (via missingServices), read its own Package's source code to make fixes, and inspect the failure diagnostics of latestRun.

4. cordis_define: Define Without Executing

cordis_define at packages/extensions/tool-cordis/src/index.ts:148-200:

1. Validates name / purpose / idPrefix ([a-z]{3,6})
2. precheckCode sandbox pre-parse
3. Mints pluginId / packageId
4. Writes the definition — define does not execute

idPrefix validated as [a-z]{3,6}: prevents the agent from minting arbitrary IDs; the semantic prefix lets humans recognize "whose plugin is this" in the UI.

5-7. cordis_run / cordis_stop / cordis_undefine

Activate, stop, delete — correspond to the full lifecycle of dynamic plugins (see Plugin Registry).

Progressive Discovery: Host Providers

hostInspectProviders(ctx) at packages/extensions/tool-cordis/src/providers.ts:26-65 registers four Host Providers:

• Service.listService
• Event.listEvents
• Builtin.listBuiltins
• Tool.listTools

Service / Event use the two-step design where "no input = compact catalog, with input = precise contract".

Host Providers are static (Service / Event / Builtin come from the generated catalog); Client Providers are dynamic (Slot / Theme etc. require a page response); a cordis_inspect_query against a Client stays pending until the first page answers.

API Catalog: Docs and Tools Share One Source

SERVICE_API (2156 lines) at packages/extensions/tool-cordis/src/api-catalog.ts:83-160 + EVENT_API (at L2159): generated by gen-cordis-api.ts, each entry carries a key / type / methods / source pointer, sharing the same AST walk as the docs/cordis-catalog docs.

queryServiceApi(key?, services=SERVICE_API) and queryEventApi(name?, events=EVENT_API) at packages/extensions/tool-cordis/src/api-catalog.ts:4691-4760: with no key, return the compact catalog; with a key, return the structured contract for that service / event + the referenced-type closure.

This means citing a signature from docs/cordis-api/*.md on this site is equivalent to citing source code — verify-cordis-catalog is the doc-sync gate.

System Prompt: The Agent's Workflow and Red Lines

CORDIS_SYSTEM_PROMPT at packages/extensions/tool-cordis/src/prompt.ts:3-107 defines:

• Workflow: inspect → query → define → run → stop → undefine
• Identity / version / authorization semantics
• Host vs Client selection
• High-frequency error checklist:
  • plain JS only, no JSX/TS
  • do not serialize live data
  • every side effect must be reversible

The system prompt forbids "caching Inspect data as business data": Service / Event / Slot are live objects, JSON.stringify / structuredClone will blow up; only read the necessary leaf fields to construct minimal owned data.

Two-Step Query Summary

The core of this design is "the agent cannot guess" — it must look at the catalog before drilling in. This is both a defense against LLM hallucination and a prerequisite for keeping dynamic plugins auditable.

What to read next

• Plugin Registry — the three-layer identity of DynamicCordisRegistry
• Web UI and Plugin Interaction — how the UI renders the results of these tools