Skip to content

Commit f6aa2c0

Browse files
steipetesteipete
committed
docs: document plugin runtime load context
1 parent 7b4d14f commit f6aa2c0

8 files changed

Lines changed: 20 additions & 0 deletions

‎src/plugins/runtime/channel-runtime-contexts.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,7 @@ function doesRuntimeContextWatcherMatch(params: {
6969
return true;
7070
}
7171

72+
/** Creates the in-memory channel runtime context registry used by plugin runtime surfaces. */
7273
export function createChannelRuntimeContextRegistry(): ChannelRuntimeContextRegistry {
7374
const runtimeContexts = new Map<string, StoredRuntimeContext>();
7475
const runtimeContextWatchers = new Set<{

‎src/plugins/runtime/load-context.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ import type { PluginLogger } from "../types.js";
1818

1919
const log = createSubsystemLogger("plugins");
2020

21+
/** Resolved plugin runtime load context shared by runtime loader callers. */
2122
export type PluginRuntimeLoadContext = {
2223
rawConfig: OpenClawConfig;
2324
config: OpenClawConfig;
@@ -30,6 +31,7 @@ export type PluginRuntimeLoadContext = {
3031
installRecords?: Record<string, PluginInstallRecord>;
3132
};
3233

34+
/** Runtime load option values that can be passed directly to plugin loading. */
3335
export type PluginRuntimeResolvedLoadValues = Pick<
3436
PluginLoadOptions,
3537
| "config"
@@ -42,6 +44,7 @@ export type PluginRuntimeResolvedLoadValues = Pick<
4244
| "installRecords"
4345
>;
4446

47+
/** Options accepted while resolving plugin runtime load context. */
4548
export type PluginRuntimeLoadContextOptions = {
4649
config?: OpenClawConfig;
4750
activationSourceConfig?: OpenClawConfig;
@@ -51,6 +54,7 @@ export type PluginRuntimeLoadContextOptions = {
5154
manifestRegistry?: PluginManifestRegistry;
5255
};
5356

57+
/** Creates the default plugin runtime loader logger. */
5458
export function createPluginRuntimeLoaderLogger(): PluginLogger {
5559
return {
5660
info: (message) => log.info(message),
@@ -60,6 +64,7 @@ export function createPluginRuntimeLoaderLogger(): PluginLogger {
6064
};
6165
}
6266

67+
/** Resolves config, manifests, install records, and auto-enable state for runtime loads. */
6368
export function resolvePluginRuntimeLoadContext(
6469
options?: PluginRuntimeLoadContextOptions,
6570
): PluginRuntimeLoadContext {
@@ -93,6 +98,7 @@ export function resolvePluginRuntimeLoadContext(
9398
const workspaceDir =
9499
options?.workspaceDir ?? resolveAgentWorkspaceDir(config, resolveDefaultAgentId(config));
95100
if (metadataSnapshot) {
101+
// Reusable snapshots stay available to later manifest-policy lookups for this runtime load.
96102
if (isReusableCurrentPluginMetadataSnapshot(metadataSnapshot)) {
97103
setCurrentPluginMetadataSnapshot(metadataSnapshot, {
98104
config: rawConfig,
@@ -117,13 +123,15 @@ export function resolvePluginRuntimeLoadContext(
117123
};
118124
}
119125

126+
/** Builds plugin load options from a resolved runtime load context. */
120127
export function buildPluginRuntimeLoadOptions(
121128
context: PluginRuntimeLoadContext,
122129
overrides?: Partial<PluginLoadOptions>,
123130
): PluginLoadOptions {
124131
return buildPluginRuntimeLoadOptionsFromValues(context, overrides);
125132
}
126133

134+
/** Builds plugin load options from explicit runtime load values. */
127135
export function buildPluginRuntimeLoadOptionsFromValues(
128136
values: PluginRuntimeResolvedLoadValues,
129137
overrides?: Partial<PluginLoadOptions>,

‎src/plugins/runtime/metadata-registry-loader.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ import {
1010
type PluginRuntimeLoadContext,
1111
} from "./load-context.js";
1212

13+
/** Loads a non-activated plugin metadata registry snapshot for validation/status callers. */
1314
export function loadPluginMetadataRegistrySnapshot(options?: {
1415
config?: OpenClawConfig;
1516
activationSourceConfig?: OpenClawConfig;

‎src/plugins/runtime/runtime-agent.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ function resolveRuntimeThinkingCatalog(
3838
return configuredCatalog.length > 0 ? configuredCatalog : undefined;
3939
}
4040

41+
/** Creates the plugin runtime agent facade with lazy embedded-agent/session helpers. */
4142
export function createRuntimeAgent(): PluginRuntime["agent"] {
4243
const agentRuntime = {
4344
defaults: {

‎src/plugins/runtime/runtime-cache.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
/** Defines a lazily computed enumerable property on a runtime facade. */
12
export function defineCachedValue(target: object, key: PropertyKey, create: () => unknown): void {
23
let cached: unknown;
34
let ready = false;

‎src/plugins/runtime/runtime-embedded-agent.runtime.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,2 @@
1+
/** Lazy runtime barrel for embedded-agent execution. */
12
export { runEmbeddedAgent } from "../../agents/embedded-agent.js";

‎src/plugins/runtime/runtime-logging.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ function writeRuntimeLog(
1515
log(message);
1616
}
1717

18+
/** Creates the plugin runtime logging facade. */
1819
export function createRuntimeLogging(): PluginRuntime["logging"] {
1920
return {
2021
shouldLogVerbose,

‎src/plugins/runtime/task-domain-types.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ import type {
1111
} from "../../tasks/task-registry.types.js";
1212
import type { DeliveryContext } from "../../utils/delivery-context.types.js";
1313

14+
/** Aggregate task-run counts exposed to plugin task views. */
1415
export type TaskRunAggregateSummary = {
1516
total: number;
1617
active: number;
@@ -20,6 +21,7 @@ export type TaskRunAggregateSummary = {
2021
byRuntime: TaskRuntimeCounts;
2122
};
2223

24+
/** Public task run summary exposed through plugin runtime task APIs. */
2325
export type TaskRunView = {
2426
id: string;
2527
runtime: TaskRuntime;
@@ -48,15 +50,18 @@ export type TaskRunView = {
4850
terminalOutcome?: TaskTerminalOutcome;
4951
};
5052

53+
/** Detailed task run view; currently equal to the summary view. */
5154
export type TaskRunDetail = TaskRunView;
5255

56+
/** Result returned when cancelling a task run. */
5357
export type TaskRunCancelResult = {
5458
found: boolean;
5559
cancelled: boolean;
5660
reason?: string;
5761
task?: TaskRunDetail;
5862
};
5963

64+
/** Public task flow summary exposed through plugin runtime task APIs. */
6065
export type TaskFlowView = {
6166
id: string;
6267
ownerKey: string;
@@ -71,6 +76,7 @@ export type TaskFlowView = {
7176
endedAt?: number;
7277
};
7378

79+
/** Detailed task flow view with state, wait, blocked, and task summary data. */
7480
export type TaskFlowDetail = TaskFlowView & {
7581
state?: JsonValue;
7682
wait?: JsonValue;

0 commit comments

Comments
 (0)