365 lines
16 KiB
Markdown
365 lines
16 KiB
Markdown
# 运行时自修改
|
|
|
|
[English](self-modification.md) | 中文
|
|
|
|
self-modification 子系统允许 agent（智能体）定义带版本的 Cordis 包、运行其 host 与浏览器两半，并在编写代码前查询获准公开的运行时元数据。包生命周期与沙箱行为由 [`packages/self-modification`](../../packages/self-modification/README.md) 包组说明。
|
|
|
|
<!-- 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/self-modification/cordis-host-runner/src/inspect-registry.ts:46`](../../packages/self-modification/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/self-modification/cordis-host-runner/src/index.ts:124`](../../packages/self-modification/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/self-modification/cordis-host-runner/src/types.ts:379`](../../packages/self-modification/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/self-modification/cordis-host-runner/src/types.ts:385`](../../packages/self-modification/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/self-modification/cordis-host-runner/src/types.ts:391`](../../packages/self-modification/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/self-modification/cordis-host-runner/src/types.ts:397`](../../packages/self-modification/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/self-modification/cordis-host-runner/src/types.ts:367`](../../packages/self-modification/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/self-modification/cordis-host-runner/src/types.ts:373`](../../packages/self-modification/cordis-host-runner/src/types.ts)
|
|
<!-- END GENERATED cordis-surface -->
|