dsh-plugin-guide 0.1.0

package/references/official-docs/docs/subsystems/credentials.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/subsystems/credentials.md
+credentials.md: fe480c4311dd5f7e0b1f26996ad53d5f0cd79e7d
+credentials.zh.md: 1d8712f8b01a6d6b92e2036172c151d22728f2a4

package/references/official-docs/docs/subsystems/credentials.md

@@ -0,0 +1,133 @@
+# User Credentials
+
+English | [中文](credentials.zh.md)
+
+The credential seam of [dsh-credentials](../../packages/credentials/credentials) keeps secrets out of configuration: settings sections and `cordis.yml` entries carry *references* (environment-variable names), providers such as [dsh-credentials-local](../../packages/credentials/credentials-local) own the values, and consumers resolve a reference once per operation — the LLM adapters resolve once per model request, so a rotated credential reaches the very next request without any restart. One seam-wide rule binds every provider: an empty stored value is absent everywhere.
+
+Source: [`packages/credentials/credentials/src/index.ts`](../../packages/credentials/credentials/src/index.ts)
+
+## Identity
+
+A reference names one credential as a POSIX-style environment-variable name. The brand prevents callers from mixing credential references with other strings passed between packages or processes; construction validates the shell-identifier syntax.
+
+```ts type-equiv
+/** Nominal reference to one credential: a POSIX-style environment-variable name. */
+type CredentialRef = Branded<'CredentialRef'>
+```
+
+## Resolution
+
+`resolve(ref)` returns the value with the provider-defined source layer that supplied it, or `undefined` while unconfigured. Consumers re-resolve at each operation and never cache across operations — that per-operation read is the hot-update mechanism.
+
+```ts type-equiv
+/** One resolved credential value and the source layer that supplied it. */
+interface ResolvedCredential {
+  /** The non-empty secret value. */
+  value: string
+  /** Provider-defined source layer id (the local provider uses `env`, `file`, `project-env`, and `user-env`). */
+  source: string
+}
+```
+
+## Description
+
+`describe(ref)` answers configuration surfaces without ever exposing a value: whether the reference resolves, from which layer, and whether `set` would currently succeed. The local provider reports a reference supplied by the live process environment as `writable: false` — a write would appear to succeed while resolution kept returning the shadowing value, so the seam rejects it and the UI can render the reference read-only up front.
+
+```ts type-equiv
+/** Source and writability facts for one reference, safe for configuration UIs — never the value. */
+interface CredentialInfo {
+  /** Whether {@link CredentialProvider.resolve} would currently return a value. */
+  configured: boolean
+  /** Source layer currently supplying the value; absent while unconfigured. */
+  source?: string
+  /** Whether {@link CredentialProvider.set} would currently succeed for this reference. */
+  writable: boolean
+}
+```
+
+## Change commits
+
+`credentials/updated (ref)` fires after a committed change to a provider-managed source — a `set`, an `unset`, or an external edit observed in storage. Ambient process-environment changes are not observable and never emit. Consumers do not need the event (they re-resolve per operation); it exists for configuration surfaces refreshing a "configured" badge.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis API
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxcredentials--credentialprovider-abstract-seam"></a>
+
+### `ctx.credentials` — `CredentialProvider` (abstract seam)
+
+Abstract credential service. Providers implement the four operations over their source layers; one seam-wide rule binds them all: an empty stored value is absent everywhere — `resolve` skips it, `describe` reports it unconfigured — so a blank never masquerades as a configured secret.
+
+```ts cordis-catalog
+/**
+ * Resolve one reference to its current value. Resolution is per call:
+ * consumers re-resolve at each operation and must not cache across
+ * operations — that per-operation read is what makes a changed credential
+ * reach the next operation without a restart.
+ * @param ref - the reference to resolve.
+ * @returns the value and its source, or `undefined` while unconfigured.
+ */
+abstract resolve(ref: CredentialRef): Promise<ResolvedCredential | undefined>
+
+/**
+ * Describe one reference for configuration surfaces without exposing the
+ * value.
+ * @param ref - the reference to describe.
+ * @returns configured state, supplying source, and writability.
+ */
+abstract describe(ref: CredentialRef): Promise<CredentialInfo>
+
+/**
+ * Durably store one value in the provider-managed writable source. Rejects
+ * while a read-only source shadows the reference — the write would appear
+ * to succeed while resolution keeps returning the shadowing value — and
+ * rejects an empty value (use {@link unset}).
+ * @param ref - the reference to store.
+ * @param value - the non-empty secret value.
+ */
+abstract set(ref: CredentialRef, value: string): Promise<void>
+
+/**
+ * Remove one reference from the provider-managed writable source; removing
+ * an absent reference is a no-op. Rejects while a read-only source shadows
+ * the reference, like {@link set}.
+ * @param ref - the reference to remove.
+ */
+abstract unset(ref: CredentialRef): Promise<void>
+```
+
+Source: [`packages/credentials/credentials/src/index.ts:60`](../../packages/credentials/credentials/src/index.ts)
+
+<a id="credentials-events"></a>
+
+### `credentials/*` events
+
+<a id="credentialsupdated--emit"></a>
+
+#### `credentials/updated` — emit
+
+Committed change to a provider-managed credential source: a `set`, an `unset`, or an external edit observed in storage. Ambient process-environment changes are not observable and never emit. Listener failures are contained and logged — a sync throw and an async rejection alike — without changing the committed operation's outcome, except `INVARIANT`-coded failures, which rethrow after every listener ran; that rethrow reaches the emitter only from synchronous listeners, so invariant checks on this event must not be async functions.
+
+```ts cordis-catalog
+/**
+ * Committed change to a provider-managed credential source: a `set`, an
+ * `unset`, or an external edit observed in storage. Ambient
+ * process-environment changes are not observable and never emit. Listener
+ * failures are contained and logged — a sync throw and an async rejection
+ * alike — without changing the committed operation's outcome, except
+ * `INVARIANT`-coded failures, which rethrow after every listener ran;
+ * that rethrow reaches the emitter only from synchronous listeners, so
+ * invariant checks on this event must not be async functions.
+ * @param ref - the reference whose stored value changed.
+ * @mode emit
+ */
+'credentials/updated'(ref: CredentialRef): void
+```
+
+Source: [`packages/credentials/credentials/src/types.ts:29`](../../packages/credentials/credentials/src/types.ts)
+<!-- END GENERATED cordis-surface -->

package/references/official-docs/docs/subsystems/credentials.zh.md

@@ -0,0 +1,133 @@
+# 用户凭据
+
+[English](credentials.md) | 中文
+
+[dsh-credentials](../../packages/credentials/credentials) 的凭据 seam 把机密挡在配置之外：settings 分节与 `cordis.yml` 条目携带的是*引用*（环境变量名），值归 [dsh-credentials-local](../../packages/credentials/credentials-local) 这类提供方所有，消费方每个操作解析一次引用——LLM（大语言模型）适配器每次模型请求解析一次，因此轮换后的凭据无需任何重启即可作用于紧随其后的下一次请求。一条 seam 级规则约束每个提供方：空的存储值在任何地方都视为不存在。
+
+来源：[`packages/credentials/credentials/src/index.ts`](../../packages/credentials/credentials/src/index.ts)
+
+## 标识
+
+引用以 POSIX 风格环境变量名命名一条凭据。brand 防止调用方将凭据引用与在包或进程之间传递的其他字符串混用；构造时校验 shell 标识符语法。
+
+```ts type-equiv
+/** Nominal reference to one credential: a POSIX-style environment-variable name. */
+type CredentialRef = Branded<'CredentialRef'>
+```
+
+## 解析
+
+`resolve(ref)` 返回值及提供该值的来源层（由提供方定义）；未配置期间返回 `undefined`。消费方在每个操作中重新解析，绝不跨操作缓存——这种按操作进行的读取正是热更新机制。
+
+```ts type-equiv
+/** One resolved credential value and the source layer that supplied it. */
+interface ResolvedCredential {
+  /** The non-empty secret value. */
+  value: string
+  /** Provider-defined source layer id (the local provider uses `env`, `file`, `project-env`, and `user-env`). */
+  source: string
+}
+```
+
+## 描述
+
+`describe(ref)` 在绝不暴露值的前提下回应配置界面：引用当前是否可解析、来自哪一层、`set` 当前能否成功。本地提供方把由当前进程环境供值的引用报告为 `writable: false`——那样的写入会表面成功而解析持续返回遮蔽值，因此 seam 直接拒绝，界面也得以提前把该引用渲染为只读。
+
+```ts type-equiv
+/** Source and writability facts for one reference, safe for configuration UIs — never the value. */
+interface CredentialInfo {
+  /** Whether {@link CredentialProvider.resolve} would currently return a value. */
+  configured: boolean
+  /** Source layer currently supplying the value; absent while unconfigured. */
+  source?: string
+  /** Whether {@link CredentialProvider.set} would currently succeed for this reference. */
+  writable: boolean
+}
+```
+
+## 已提交的变更
+
+`credentials/updated (ref)` 在提供方管理的来源发生已提交变更后发出——`set`、`unset` 或在存储中观察到的外部编辑。进程环境自身的变化不可观测，永不发出事件。消费方不需要该事件（它们按操作重新解析）；它服务于配置界面刷新「已配置」徽标。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis API
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxcredentials--credentialprovider-abstract-seam"></a>
+
+### `ctx.credentials` — `CredentialProvider` (abstract seam)
+
+Abstract credential service. Providers implement the four operations over their source layers; one seam-wide rule binds them all: an empty stored value is absent everywhere — `resolve` skips it, `describe` reports it unconfigured — so a blank never masquerades as a configured secret.
+
+```ts cordis-catalog
+/**
+ * Resolve one reference to its current value. Resolution is per call:
+ * consumers re-resolve at each operation and must not cache across
+ * operations — that per-operation read is what makes a changed credential
+ * reach the next operation without a restart.
+ * @param ref - the reference to resolve.
+ * @returns the value and its source, or `undefined` while unconfigured.
+ */
+abstract resolve(ref: CredentialRef): Promise<ResolvedCredential | undefined>
+
+/**
+ * Describe one reference for configuration surfaces without exposing the
+ * value.
+ * @param ref - the reference to describe.
+ * @returns configured state, supplying source, and writability.
+ */
+abstract describe(ref: CredentialRef): Promise<CredentialInfo>
+
+/**
+ * Durably store one value in the provider-managed writable source. Rejects
+ * while a read-only source shadows the reference — the write would appear
+ * to succeed while resolution keeps returning the shadowing value — and
+ * rejects an empty value (use {@link unset}).
+ * @param ref - the reference to store.
+ * @param value - the non-empty secret value.
+ */
+abstract set(ref: CredentialRef, value: string): Promise<void>
+
+/**
+ * Remove one reference from the provider-managed writable source; removing
+ * an absent reference is a no-op. Rejects while a read-only source shadows
+ * the reference, like {@link set}.
+ * @param ref - the reference to remove.
+ */
+abstract unset(ref: CredentialRef): Promise<void>
+```
+
+Source: [`packages/credentials/credentials/src/index.ts:60`](../../packages/credentials/credentials/src/index.ts)
+
+<a id="credentials-events"></a>
+
+### `credentials/*` events
+
+<a id="credentialsupdated--emit"></a>
+
+#### `credentials/updated` — emit
+
+Committed change to a provider-managed credential source: a `set`, an `unset`, or an external edit observed in storage. Ambient process-environment changes are not observable and never emit. Listener failures are contained and logged — a sync throw and an async rejection alike — without changing the committed operation's outcome, except `INVARIANT`-coded failures, which rethrow after every listener ran; that rethrow reaches the emitter only from synchronous listeners, so invariant checks on this event must not be async functions.
+
+```ts cordis-catalog
+/**
+ * Committed change to a provider-managed credential source: a `set`, an
+ * `unset`, or an external edit observed in storage. Ambient
+ * process-environment changes are not observable and never emit. Listener
+ * failures are contained and logged — a sync throw and an async rejection
+ * alike — without changing the committed operation's outcome, except
+ * `INVARIANT`-coded failures, which rethrow after every listener ran;
+ * that rethrow reaches the emitter only from synchronous listeners, so
+ * invariant checks on this event must not be async functions.
+ * @param ref - the reference whose stored value changed.
+ * @mode emit
+ */
+'credentials/updated'(ref: CredentialRef): void
+```
+
+Source: [`packages/credentials/credentials/src/types.ts:29`](../../packages/credentials/credentials/src/types.ts)
+<!-- END GENERATED cordis-surface -->

package/references/official-docs/docs/subsystems/extensions.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/subsystems/extensions.md
+extensions.md: f212f99704cb1cc871a77ee6cc10188746771958
+extensions.zh.md: 717b14951dd262213cfc42a380777d233fb6eea5

package/references/official-docs/docs/subsystems/extensions.md

@@ -0,0 +1,364 @@
+# Extensions
+
+English | [中文](extensions.zh.md)
+
+The extensions subsystem lets an agent define versioned Cordis packages, run their host and browser halves, and query approved runtime metadata before writing code. Package lifecycle and sandbox behavior belong to the [`packages/extensions`](../../packages/extensions/README.md) package group.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis API
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxcordisinspect--cordisinspectregistryservice"></a>
+
+### `ctx.cordisInspect` — `CordisInspectRegistryService`
+
+Registry and cross-page router behind the two model-facing inspect tools.
+
+```ts cordis-catalog
+/**
+ * Register one Host provider.
+ * @param registration - manifest and local query handler.
+ * @returns idempotent disposer.
+ */
+register(registration: HostCordisInspectProviderRegistration): () => void
+
+/**
+ * Replace the mirrored Client provider directory.
+ * @param providers - complete Client manifest snapshot.
+ */
+syncClientManifest(providers: readonly CordisInspectProviderManifest[]): void
+
+/**
+ * Return the complete known Host and Client provider directory.
+ * @returns Host providers followed by the Client providers.
+ */
+list(): CordisInspectProviderView[]
+
+/**
+ * Execute one provider query on its owning platform.
+ * @param platform - Host or Client runtime.
+ * @param providerId - provider selected from {@link list}.
+ * @param methodName - declared method name.
+ * @param input - optional lossless JSON input.
+ * @param agent - requesting Agent and scope.
+ * @param signal - tool-call cancellation.
+ * @returns provider JSON data.
+ */
+async query( platform: CordisInspectPlatform, providerId: string, methodName: string, input: JsonValue | undefined, agent: Agent, signal: AbortSignal, ): Promise<JsonValue>
+
+/**
+ * Accept the first valid Client response for a pending query.
+ * @param agent - Agent whose Session owns the query.
+ * @param requestId - Pending Client query identity.
+ * @param resolution - Client provider result or failure.
+ * @returns whether this response settled the still-pending query.
+ */
+resolveClientQuery( agent: Agent, requestId: CordisInspectRequestId, resolution: CordisInspectQueryResolution, ): CordisInspectResolveAck
+```
+
+Types: [Agent](core.md)
+
+Source: [`packages/extensions/cordis-host-runner/src/inspect-registry.ts:46`](../../packages/extensions/cordis-host-runner/src/inspect-registry.ts)
+
+<a id="ctxdynamiccordisrunner--dynamiccordisrunnerservice"></a>
+
+### `ctx.dynamicCordisRunner` — `DynamicCordisRunnerService`
+
+Dynamic Plugin registry and Host-half lifecycle.
+
+```ts cordis-catalog
+/**
+ * Define a new Plugin's first Package or append a Package to an existing Plugin.
+ * @param request - Session ownership, Plugin selection, metadata, and source code.
+ * @returns Host-minted Plugin and Package identities with declared-half metadata.
+ */
+define(request: DynamicCordisDefineRequest): DynamicCordisDefineReceipt
+
+/**
+ * Remove a Plugin, its active run, and all immutable Packages.
+ * @param agent - Agent whose Session must own the Plugin.
+ * @param pluginId - Stable Plugin identity to remove.
+ * @returns Whether removal succeeded and whether it stopped an active run.
+ */
+async undefine(agent: Agent, pluginId: CordisDynamicPluginId): Promise<DynamicCordisUndefineReceipt>
+
+/**
+ * Remove a Plugin from the user panel and queue the resulting state change for the model's next step.
+ * @param agent - Agent whose Session owns the Plugin and receives the context.
+ * @param pluginId - Stable Plugin identity to remove.
+ * @returns Whether removal succeeded and whether it stopped an active run.
+ */
+@Remote('undefineFromPanel') async undefineFromPanel(agent: Agent, pluginId: CordisDynamicPluginId): Promise<DynamicCordisUndefineReceipt>
+
+/**
+ * Start or update one Package for a model tool call. An unauthorized Client
+ * Package waits for approval; Plugin-wide authorization covers later versions.
+ * @param agent - Agent whose Session must own the Plugin.
+ * @param pluginId - Stable Plugin identity to activate.
+ * @param packageId - Immutable Package version to activate.
+ * @param mode - Whether to run the current version or switch versions.
+ * @param signal - Tool-call cancellation signal while the activation request is being created.
+ * @returns The successful activation identity or an actionable refusal.
+ */
+async run( agent: Agent, pluginId: CordisDynamicPluginId, packageId: CordisDynamicPackageId, mode: CordisDynamicRunMode, signal?: AbortSignal, ): Promise<DynamicCordisRunResponse>
+
+/**
+ * Start Host code for an approved request or a direct panel gesture.
+ * @param agent - Agent whose Session must own the Plugin.
+ * @param pluginId - Stable Plugin identity to activate.
+ * @param packageId - Immutable Package version to activate.
+ * @param mode - Whether to run the current version or switch versions.
+ * @param requestId - Model-driven request identity, or null for a direct user gesture.
+ * @param approveFutureVersions - Whether this approval covers later Packages of the same Plugin.
+ * @returns The exact Host activation or a failure message.
+ */
+@Remote('runHostHalf') async runHostHalf( agent: Agent, pluginId: CordisDynamicPluginId, packageId: CordisDynamicPackageId, mode: CordisDynamicRunMode, requestId: ApprovalRequestId | null, approveFutureVersions: boolean, ): Promise<DynamicCordisHostHalfResult>
+
+/**
+ * Fetch Client code for the exact active run.
+ * @param agent - Agent whose Session must own the Plugin.
+ * @param pluginId - Stable Plugin identity to read.
+ * @param pluginRunId - Exact active run authorized to receive source.
+ * @returns Client source and its Plugin, Package, and run identities.
+ */
+@Remote('getClientCode') getClientCode( agent: Agent, pluginId: CordisDynamicPluginId, pluginRunId: CordisDynamicPluginRunId, ): DynamicCordisClientSource
+
+/**
+ * Resolve one model-driven Client activation request.
+ * @param requestId - Request identity to settle once.
+ * @param resolution - Browser refusal or exact Client activation result.
+ * @returns Whether the still-pending request accepted this resolution.
+ */
+@Remote('resolveRequestRun') async resolveRequestRun( requestId: ApprovalRequestId, resolution: DynamicCordisRunResolution, ): Promise<DynamicCordisResolveAck>
+
+/**
+ * Settle a direct panel run after this page loaded or failed its Client half.
+ * @param agent - Agent whose Session must own the Plugin.
+ * @param pluginId - Stable Plugin identity being settled.
+ * @param resolution - Exact Client activation result from the acting page.
+ * @returns The committed activation or its failure.
+ */
+@Remote('settleUserRun') async settleUserRun( agent: Agent, pluginId: CordisDynamicPluginId, resolution: DynamicCordisRunResolution, ): Promise<DynamicCordisRunResponse>
+
+/**
+ * Stop the active run while retaining every Package version.
+ * @param agent - Agent whose Session must own the Plugin.
+ * @param pluginId - Stable Plugin identity to stop.
+ * @returns Success or the reason no run was stopped.
+ */
+async stop(agent: Agent, pluginId: CordisDynamicPluginId): Promise<DynamicCordisStopResponse>
+
+/**
+ * Stop a Plugin from the user panel and queue the resulting state change for the model's next step.
+ * @param agent - Agent whose Session owns the Plugin and receives the context.
+ * @param pluginId - Stable Plugin identity to stop.
+ * @returns Success or the reason no run was stopped.
+ */
+@Remote('stopFromPanel') async stopFromPanel(agent: Agent, pluginId: CordisDynamicPluginId): Promise<DynamicCordisStopResponse>
+
+/**
+ * Replace the Host mirror of the Client inspect provider directory.
+ * @param providers - complete Client provider manifest.
+ * @returns null after accepting the manifest.
+ */
+@Remote('syncInspectManifest') syncInspectManifest(providers: readonly CordisInspectProviderManifest[]): null
+
+/**
+ * Claim one pending Client inspect query with its live result.
+ * @param agent - Session that owns the query.
+ * @param requestId - exact pending query identity.
+ * @param resolution - provider result or structured refusal.
+ * @returns whether this answer won the query.
+ */
+@Remote('resolveInspectQuery') resolveInspectQuery( agent: Agent, requestId: CordisInspectRequestId, resolution: CordisInspectQueryResolution, ): CordisInspectResolveAck
+
+/**
+ * Frame-wide inventory, grouped as one row per stable Plugin.
+ * @returns Source-free metadata for every process-local Plugin.
+ */
+@Remote('inventory') inventory(): DynamicCordisInventoryRow[]
+
+/**
+ * Read one Session's Host-rich state for inspection and result rendering.
+ * @param agent - Agent whose Session selects visible Plugins.
+ * @returns Plugin versions, active runs, Host fibers, and render failures.
+ */
+snapshot(agent: Agent): DynamicCordisSnapshotRow[]
+
+/**
+ * Read source-free context for an explicit `@pluginId` user gesture.
+ * @param agent - Agent whose Session must own the Plugin.
+ * @param pluginId - Stable Plugin identity referenced by the user.
+ * @returns The preferred modification base, or undefined when unavailable.
+ */
+reference(agent: Agent, pluginId: CordisDynamicPluginId): DynamicCordisReference | undefined
+
+/**
+ * List source-free Plugin summaries owned by one Session.
+ * @param agent - Agent whose Session selects visible Plugins.
+ * @returns one summary per Plugin in creation order.
+ */
+listPlugins(agent: Agent): DynamicCordisPluginInspection[]
+
+/**
+ * Inspect one Plugin without returning Package source.
+ * @param agent - Agent whose Session must own the Plugin.
+ * @param pluginId - stable Plugin identity.
+ * @returns version pointers, latest run, and all Package summaries.
+ */
+inspectPlugin(agent: Agent, pluginId: CordisDynamicPluginId): DynamicCordisPluginInspection
+
+/**
+ * Read one exact immutable Package and its Host and Client source.
+ * @param agent - Agent whose Session must own the Plugin.
+ * @param pluginId - Stable Plugin identity that owns the Package.
+ * @param packageId - Exact immutable Package identity to inspect.
+ * @returns Package metadata, source, and the Plugin's lifecycle pointers.
+ */
+inspectPackage( agent: Agent, pluginId: CordisDynamicPluginId, packageId: CordisDynamicPackageId, ): DynamicCordisPackageInspection
+
+/**
+ * Record a post-load render failure for the exact active run.
+ * @param agent - Agent whose Session must own the Plugin.
+ * @param pluginId - Stable Plugin identity that rendered.
+ * @param pluginRunId - Exact active run that produced the failure.
+ * @param failure - Slot, message, and entry-retirement result.
+ * @returns Null after recording or ignoring a stale report.
+ */
+@Remote('reportRenderFailure') async reportRenderFailure( agent: Agent, pluginId: CordisDynamicPluginId, pluginRunId: CordisDynamicPluginRunId, failure: DynamicCordisRenderFailure, ): Promise<null>
+
+/**
+ * Report a Client guard rejection that happened after the Package completed activation.
+ * @param agent - Agent whose Session must own the Plugin.
+ * @param pluginId - Stable Plugin identity whose Client code was rejected.
+ * @param pluginRunId - Exact active run that produced the rejection.
+ * @param failure - Original guard message and stack.
+ * @returns Null after reporting or ignoring a stale/startup failure.
+ */
+@Remote('reportClientGuardFailure') async reportClientGuardFailure( agent: Agent, pluginId: CordisDynamicPluginId, pluginRunId: CordisDynamicPluginRunId, failure: CordisErrorDetails, ): Promise<null>
+
+/**
+ * Invoke an active Host method while rejecting stale Client runs.
+ * @param pluginId - Stable Plugin identity that owns the method.
+ * @param pluginRunId - Exact active run authorizing the call.
+ * @param method - Registered Host handler name.
+ * @param args - JSON argument delivered to the handler.
+ * @returns The JSON result or a typed invocation failure.
+ */
+@Remote('invoke') async invoke( pluginId: CordisDynamicPluginId, pluginRunId: CordisDynamicPluginRunId, method: string, args: JsonValue, ): Promise<DynamicCordisInvokeResult>
+```
+
+Types: [Agent](core.md)
+
+Source: [`packages/extensions/cordis-host-runner/src/index.ts:124`](../../packages/extensions/cordis-host-runner/src/index.ts)
+
+<a id="cordis-events"></a>
+
+### `cordis/*` events
+
+<a id="cordisdynamic-package--emit"></a>
+
+#### `cordis/dynamic-package` — emit
+
+One exact Plugin/Package activation is now live in the Host.
+
+```ts cordis-catalog
+/**
+ * One exact Plugin/Package activation is now live in the Host.
+ * @param pkg - stable plugin, immutable package, run identity, and label.
+ * @mode emit
+ */
+'cordis/dynamic-package'(pkg: DynamicCordisPackage): void
+```
+
+Source: [`packages/extensions/cordis-host-runner/src/types.ts:379`](../../packages/extensions/cordis-host-runner/src/types.ts)
+
+<a id="cordisdynamic-retract--emit"></a>
+
+#### `cordis/dynamic-retract` — emit
+
+One exact activation was withdrawn.
+
+```ts cordis-catalog
+/**
+ * One exact activation was withdrawn.
+ * @param retracted - plugin, package, and run identity.
+ * @mode emit
+ */
+'cordis/dynamic-retract'(retracted: DynamicCordisRetracted): void
+```
+
+Source: [`packages/extensions/cordis-host-runner/src/types.ts:385`](../../packages/extensions/cordis-host-runner/src/types.ts)
+
+<a id="cordisinspect-query--emit"></a>
+
+#### `cordis/inspect-query` — emit
+
+Request a live read-only query from the Client inspect registry.
+
+```ts cordis-catalog
+/**
+ * Request a live read-only query from the Client inspect registry.
+ * @param request - correlation, Session, provider, method, and JSON input.
+ * @mode emit
+ */
+'cordis/inspect-query'(request: CordisInspectQueryRequest): void
+```
+
+Source: [`packages/extensions/cordis-host-runner/src/types.ts:391`](../../packages/extensions/cordis-host-runner/src/types.ts)
+
+<a id="cordisinspect-query-resolved--emit"></a>
+
+#### `cordis/inspect-query-resolved` — emit
+
+Notify every Client that an inspect query has settled or been cancelled.
+
+```ts cordis-catalog
+/**
+ * Notify every Client that an inspect query has settled or been cancelled.
+ * @param resolved - exact query identity that is no longer answerable.
+ * @mode emit
+ */
+'cordis/inspect-query-resolved'(resolved: CordisInspectQueryResolved): void
+```
+
+Source: [`packages/extensions/cordis-host-runner/src/types.ts:397`](../../packages/extensions/cordis-host-runner/src/types.ts)
+
+<a id="cordisrequest-run--emit"></a>
+
+#### `cordis/request-run` — emit
+
+A Client-bearing activation needs a browser page, and may require a user decision.
+
+```ts cordis-catalog
+/**
+ * A Client-bearing activation needs a browser page, and may require a user decision.
+ * @param request - correlation identity, owner, target version, mode, and approval requirement.
+ * @mode emit
+ */
+'cordis/request-run'(request: DynamicCordisRunRequest): void
+```
+
+Source: [`packages/extensions/cordis-host-runner/src/types.ts:367`](../../packages/extensions/cordis-host-runner/src/types.ts)
+
+<a id="cordisrequest-run-resolved--emit"></a>
+
+#### `cordis/request-run-resolved` — emit
+
+A pending Client activation request left the answerable state.
+
+```ts cordis-catalog
+/**
+ * A pending Client activation request left the answerable state.
+ * @param resolved - request identity and outcome.
+ * @mode emit
+ */
+'cordis/request-run-resolved'(resolved: DynamicCordisRequestResolved): void
+```
+
+Source: [`packages/extensions/cordis-host-runner/src/types.ts:373`](../../packages/extensions/cordis-host-runner/src/types.ts)
+<!-- END GENERATED cordis-surface -->