@karmaniverous/jeeves 0.5.12 → 0.6.0-0

package/dist/index.d.ts

@@ -2,13 +2,94 @@ import { Command } from '@commander-js/extra-typings';
 import { z } from 'zod';
 
 /**
- * Core types for the OpenClaw plugin SDK.
+ * Structural types for OpenClaw's `before_prompt_build` hook and plugin
+ * lifecycle API (subset, OpenClaw v2026.9.6).
  *
  * @remarks
- * These types define the contract between plugins and the OpenClaw gateway.
- * They unify the various `PluginApi` definitions previously duplicated
- * across component plugins into a single canonical source.
+ * `PromptBuildResult` deliberately omits `systemPrompt`: in OpenClaw it
+ * REPLACES the entire system prompt (first value wins). Jeeves plugins must
+ * only append, via `appendSystemContext` (runbook D5).
+ *
+ * @module
+ */
+/** Event passed to `before_prompt_build` handlers (subset). */
+interface PromptBuildEvent {
+    /** Current prompt text. */
+    prompt: string;
+    /** Session messages prepared for this run. */
+    messages: unknown[];
+}
+/** Agent context passed to hook handlers (subset). */
+interface PromptBuildContext {
+    /** Agent id. */
+    agentId?: string;
+    /** Session key. */
+    sessionKey?: string;
+    /** Workspace directory for this run. */
+    workspaceDir?: string;
+    /** Channel/plugin id for channel-originated runs. */
+    channel?: string;
+    /** What triggered this turn (e.g. `user`, `heartbeat`, `cron`). */
+    trigger?: string;
+}
+/**
+ * Result a Jeeves `before_prompt_build` handler may return.
+ *
+ * @remarks
+ * `appendSystemContext` is appended after the prompt-cache boundary in an
+ * "OpenClaw plugin-injected system context" block; text from several plugins
+ * is concatenated in priority order and does not count toward
+ * `bootstrapMaxChars`.
  */
+interface PromptBuildResult {
+    /** Text appended to the agent system prompt. */
+    appendSystemContext?: string;
+}
+/** A `before_prompt_build` handler. */
+type PromptBuildHandler = (event: PromptBuildEvent, ctx: PromptBuildContext) => Promise<PromptBuildResult | undefined> | PromptBuildResult | undefined;
+/** Hook registration options (subset). */
+interface HookRegistrationOptions {
+    /** Ordering among handlers; higher runs first. */
+    priority?: number;
+    /** Stable id for this registration. */
+    registrationId?: string;
+    /** Per-handler timeout in ms (OpenClaw default for this hook: 15 000). */
+    timeoutMs?: number;
+}
+/** Plugin-owned lifecycle API (subset of `api.lifecycle`). */
+interface PluginLifecycleApi {
+    /** Aborted when the plugin instance is retired. */
+    readonly signal?: AbortSignal;
+    /**
+     * Register a disposer run when the plugin instance is retired.
+     *
+     * @returns A function that unregisters the disposer.
+     */
+    onDispose?: (dispose: () => void | Promise<void>) => () => void;
+    /** Register named cleanup for plugin-owned background work. */
+    registerRuntimeLifecycle?: (registration: {
+        /** Registration id. */
+        id: string;
+        /** Human-readable description. */
+        description?: string;
+        /** Release resources. */
+        dispose?: () => void | Promise<void>;
+    }) => void;
+}
+
+/**
+ * Structural subset of the OpenClaw plugin API used by Jeeves plugins.
+ *
+ * @remarks
+ * Mirrors the shapes in OpenClaw's plugin SDK (v2026.9.6:
+ * `src/plugins/plugin-api.types.ts`, `hook-types.ts`,
+ * `hook-before-agent-start.types.ts`, `plugin-instance.types.ts`) without
+ * depending on OpenClaw. Only the members Jeeves uses are declared; optional
+ * members degrade gracefully on older hosts.
+ *
+ * @module
+ */
+
 /** Result shape returned by tool executions. */
 interface ToolResult {
     /** Content blocks — typically a single text block. */
@@ -72,6 +153,27 @@ interface PluginApi {
      * Present on newer OpenClaw builds; optional for backwards compatibility.
      */
     resolvePath?: (input: string) => string;
+    /** Plugin-scoped config (`plugins.entries.<id>.config`), when provided. */
+    pluginConfig?: Record<string, unknown>;
+    /** Host logger, when provided. */
+    logger?: {
+        /** Log a warning. */
+        warn: (message: string) => void;
+    };
+    /**
+     * Plugin-owned lifecycle: disposal signal and cleanup registration.
+     * Present on OpenClaw 2026.9.x.
+     */
+    lifecycle?: PluginLifecycleApi;
+    /**
+     * Register a typed hook handler. Jeeves only uses `before_prompt_build`
+     * (see {@link registerPromptContext}).
+     *
+     * @param hookName - Hook name.
+     * @param handler - Hook handler.
+     * @param opts - Registration options.
+     */
+    on?(hookName: 'before_prompt_build', handler: PromptBuildHandler, opts?: HookRegistrationOptions): void;
     /**
      * Register a tool with the OpenClaw gateway.
      *
@@ -85,18 +187,14 @@ interface PluginApi {
  * Zod schema for the Jeeves component descriptor.
  *
  * @remarks
- * The descriptor replaces the v0.4.0 `JeevesComponent` interface with a
- * Zod-first approach. The TypeScript type is inferred via `z.infer<>`.
- * Validates at parse time: prime interval, callable functions.
- */
-
-/**
- * Check whether a number is prime.
+ * Zod-first: the TypeScript type is inferred via `z.infer<>`. The descriptor
+ * drives the service CLI, service manager, config handlers, and standard
+ * plugin toolset. v1 removed the TOOLS.md writer fields (`sectionId`,
+ * `refreshIntervalSeconds`, `generateToolsContent`, `dependencies`).
  *
- * @param n - Number to check.
- * @returns `true` if n is prime.
+ * @module
  */
-declare function isPrime(n: number): boolean;
+
 /**
  * Zod schema for the Jeeves component descriptor.
  *
@@ -119,13 +217,6 @@ declare const jeevesComponentDescriptorSchema: z.ZodObject<{
     customMerge: z.ZodOptional<z.ZodFunction<z.ZodTuple<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodRecord<z.ZodString, z.ZodUnknown>], null>, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
     startCommand: z.ZodFunction<z.ZodTuple<readonly [z.ZodString], null>, z.ZodArray<z.ZodString>>;
     run: z.ZodFunction<z.ZodTuple<readonly [z.ZodString], null>, z.ZodPromise<z.ZodVoid>>;
-    sectionId: z.ZodString;
-    refreshIntervalSeconds: z.ZodNumber;
-    generateToolsContent: z.ZodFunction<z.ZodTuple<readonly [], null>, z.ZodString>;
-    dependencies: z.ZodOptional<z.ZodObject<{
-        hard: z.ZodArray<z.ZodString>;
-        soft: z.ZodArray<z.ZodString>;
-    }, z.core.$strip>>;
     customCliCommands: z.ZodOptional<z.ZodFunction<z.ZodTuple<readonly [z.ZodCustom<Command<[], {}, {}>, Command<[], {}, {}>>], null>, z.ZodVoid>>;
     customPluginTools: z.ZodOptional<z.ZodFunction<z.ZodTuple<readonly [z.ZodCustom<PluginApi, PluginApi>], null>, z.ZodArray<z.ZodUnknown>>>;
 }, z.core.$strip>;
@@ -189,6 +280,8 @@ declare function createConfigApplyHandler(descriptor: JeevesComponentDescriptor,
  * Provides a transport-agnostic config query function that can be
  * used by any Jeeves component's HTTP API. Returns the full config
  * document or filters it via JSONPath expressions.
+ *
+ * @module
  */
 /** Response shape for config query results. */
 interface ConfigQueryResponse {
@@ -223,9 +316,11 @@ declare function createConfigQueryHandler(getConfig: () => unknown): ConfigQuery
  * Factory for a framework-agnostic `/status` HTTP handler.
  *
  * @remarks
- * Returns a standard status response shape consumed by HEARTBEAT
- * orchestration and the `{name}_status` plugin tool.
+ * Returns a standard status response shape consumed by `jeeves status` and
+ * the `{name}_status` plugin tool.
  * Tracks process start time internally for uptime calculation.
+ *
+ * @module
  */
 /** Options for creating a status handler. */
 interface CreateStatusHandlerOptions {
@@ -295,11 +390,13 @@ declare function substituteEnvVars<T>(value: T): T;
  * Workspace-level shared configuration: `jeeves.config.json`.
  *
  * @remarks
- * Lives at the OpenClaw workspace root alongside TOOLS.md and SOUL.md.
+ * Lives at the OpenClaw workspace root alongside SOUL.md and AGENTS.md.
  * Provides namespaced shared defaults consumed by the root Jeeves CLI.
  * Resolution precedence: CLI flags → env vars → jeeves.config.json → defaults.
  *
  * This does not replace component-owned config schemas (Decision 41).
+ *
+ * @module
  */
 
 /** Workspace config file name. */
@@ -429,35 +526,6 @@ interface ResolvedCliConfig {
  */
 declare function buildEffectiveConfig(opts: WorkspaceOptions): ResolvedCliConfig;
 
-/**
- * Factory for the standard `-openclaw` plugin installer CLI.
- *
- * @module
- */
-
-/** Options for creating a plugin installer CLI. */
-interface CreatePluginCliOptions {
-    /** Plugin identifier (e.g., 'jeeves-watcher-openclaw'). */
-    pluginId: string;
-    /** `import.meta.url` for the calling plugin CLI module. */
-    importMetaUrl: string;
-    /** npm package name for the plugin. */
-    pluginPackage: string;
-    /** Component name (e.g., 'watcher'). Derived from pluginId if omitted. */
-    componentName?: string;
-    /** Workspace root (defaults to OpenClaw workspace). */
-    workspace?: string;
-    /** Config root (defaults to 'j:/config'). */
-    configRoot?: string;
-}
-/**
- * Create a standard plugin installer CLI program.
- *
- * @param options - Plugin CLI configuration.
- * @returns A Commander program ready for `.parse()`.
- */
-declare function createPluginCli(options: CreatePluginCliOptions): Command;
-
 /**
  * Factory for the standard Jeeves service CLI.
  *
@@ -491,336 +559,30 @@ declare function createPluginCli(options: CreatePluginCliOptions): Command;
 declare function createServiceCli(descriptor: JeevesComponentDescriptor): Command;
 
 /**
- * Shared component version state file management.
+ * Platform component registry.
  *
  * @remarks
- * Each `ComponentWriter` cycle writes its component's entry to
- * `{coreConfigDir}/component-versions.json`. The Platform Handlebars
- * template reads this file to populate ALL rows in the service health
- * table, not just the calling component's.
- */
-/** Version entry for a single component. */
-interface ComponentVersionEntry {
-    /** Plugin version (the OpenClaw plugin package version). */
-    pluginVersion?: string;
-    /** npm package name for the service. */
-    servicePackage?: string;
-    /** npm package name for the plugin. */
-    pluginPackage?: string;
-    /** ISO timestamp of last update. */
-    updatedAt: string;
-}
-/** Shape of the component-versions.json file. */
-type ComponentVersionsState = Record<string, ComponentVersionEntry>;
-/**
- * Read the component versions state file.
+ * The four essential components that constitute the Jeeves platform.
  *
- * @param coreConfigDir - Path to the core config directory.
- * @returns The parsed state, or an empty object if the file doesn't exist.
- */
-declare function readComponentVersions(coreConfigDir: string): ComponentVersionsState;
-/** Options for writing a component version entry. */
-interface WriteComponentVersionOptions {
-    /** Component name. */
-    componentName: string;
-    /** Plugin version. */
-    pluginVersion?: string;
-    /** Service npm package name. */
-    servicePackage?: string;
-    /** Plugin npm package name. */
-    pluginPackage?: string;
-}
-/**
- * Write a component's version entry to the shared state file.
- *
- * @remarks
- * Reads the existing file, merges the new entry, and writes atomically.
- *
- * @param coreConfigDir - Path to the core config directory.
- * @param options - Component version data to write.
- */
-declare function writeComponentVersion(coreConfigDir: string, options: WriteComponentVersionOptions): void;
-/**
- * Remove a component's version entry from the shared state file.
- *
- * @remarks
- * Called during plugin uninstall to prevent the HEARTBEAT writer from
- * probing a service that's intentionally gone. If the component isn't
- * in the file, this is a no-op.
- *
- * @param coreConfigDir - Path to the core config directory.
- * @param componentName - The component name to remove.
- */
-declare function removeComponentVersion(coreConfigDir: string, componentName: string): void;
-
-/**
- * Timer-based orchestrator for managed content writing.
- *
- * @remarks
- * `ComponentWriter` manages a component's TOOLS.md section writes
- * and platform content maintenance (SOUL.md, AGENTS.md, Platform section)
- * on a configurable prime-interval timer cycle.
- */
-
-/** Options for ComponentWriter construction. */
-interface ComponentWriterOptions {
-    /**
-     * Gateway URL for cleanup escalation (e.g., 'http://localhost:3000').
-     * When provided, the writer will attempt to spawn a cleanup session
-     * via the gateway when orphaned content is detected.
-     * When omitted, cleanup escalation is silently skipped.
-     */
-    gatewayUrl?: string;
-}
-/**
- * Orchestrates managed content writing for a single Jeeves component.
- *
- * @remarks
- * Created via {@link createComponentWriter}. Manages a timer that fires
- * at the component's prime-interval, calling `generateToolsContent()`
- * and `refreshPlatformContent()` on each cycle.
- */
-declare class ComponentWriter {
-    private timer;
-    private jitterTimeout;
-    private readonly component;
-    private readonly configDir;
-    private readonly gatewayUrl;
-    private readonly pendingCleanups;
-    private cyclePromise;
-    private stopped;
-    /** @internal */
-    constructor(component: JeevesComponentDescriptor, options?: ComponentWriterOptions);
-    /** The component's config directory path. */
-    get componentConfigDir(): string;
-    /** Whether the writer timer is currently running or pending its first cycle. */
-    get isRunning(): boolean;
-    /**
-     * Start the writer timer.
-     *
-     * @remarks
-     * Delays the first cycle by a random jitter (0 to one full interval) to
-     * spread initial writes across all component plugins and reduce EPERM
-     * contention on startup.
-     */
-    start(): void;
-    /** Stop the writer timer. */
-    stop(): void;
-    private scheduleNextCycle;
-    /**
-     * Execute a single write cycle.
-     *
-     * @remarks
-     * 1. Write the component's TOOLS.md section.
-     * 2. Refresh shared platform content (SOUL.md, AGENTS.md, Platform section).
-     * 3. Scan for cleanup flags and escalate if a gateway URL is configured.
-     * 4. Run HEARTBEAT health orchestration.
-     */
-    cycle(): Promise<void>;
-    private runCycle;
-}
-
-/**
- * Creates a synchronous content accessor backed by an async data source.
- *
- * @remarks
- * Solves the sync/async gap in `JeevesComponentDescriptor.generateToolsContent()`:
- * the interface is synchronous, but most components fetch live data from
- * their HTTP service. This utility returns a sync `() => string` that
- * serves the last successfully fetched value while kicking off a background
- * refresh on each call.
- *
- * First call returns `placeholder`. Subsequent calls return the last
- * successfully fetched content. If a refresh fails, the previous good
- * value is retained.
- *
- * @example
- * ```typescript
- * const getContent = createAsyncContentCache({
- *   fetch: async () => {
- *     const res = await fetch('http://127.0.0.1:1936/status');
- *     return formatWatcherStatus(await res.json());
- *   },
- *   placeholder: '> Initializing watcher status...',
- * });
- *
- * const writer = createComponentWriter({
- *   // ...
- *   generateToolsContent: getContent,
- * });
- * ```
- */
-/** Options for {@link createAsyncContentCache}. */
-interface AsyncContentCacheOptions {
-    /**
-     * Async function that fetches fresh content.
-     * Errors are caught and logged; the previous value is retained.
-     */
-    fetch: () => Promise<string>;
-    /**
-     * Content returned before the first successful fetch.
-     *
-     * @defaultValue `'> Initializing...'`
-     */
-    placeholder?: string;
-    /**
-     * Optional error handler. Called when `fetch` throws.
-     * Defaults to a handler that logs transient network errors as
-     * concise warnings and unexpected errors with full details.
-     */
-    onError?: (error: unknown) => void;
-}
-/**
- * Creates a synchronous content accessor backed by an async data source.
- *
- * @param options - Cache configuration.
- * @returns A sync `() => string` suitable for `generateToolsContent`.
- */
-declare function createAsyncContentCache(options: AsyncContentCacheOptions): () => string;
-
-/**
- * Factory function for creating a ComponentWriter from a descriptor.
- *
- * @remarks
- * Validates the descriptor via Zod schema and creates a ComponentWriter.
- * Accepts `JeevesComponentDescriptor` (v0.5.0) only. The v0.4.0
- * `JeevesComponent` interface is no longer accepted.
- */
-
-/**
- * Create a ComponentWriter for a validated component descriptor.
- *
- * @remarks
- * The descriptor is validated via the Zod schema at runtime.
- * This replaces the v0.4.0 `createComponentWriter(JeevesComponent)`.
- *
- * @param descriptor - The component descriptor to validate and wrap.
- * @param options - Optional writer configuration (e.g., gatewayUrl for cleanup escalation).
- * @returns A new `ComponentWriter` instance.
- * @throws ZodError if the descriptor is invalid.
- */
-declare function createComponentWriter(descriptor: JeevesComponentDescriptor, options?: ComponentWriterOptions): ComponentWriter;
-
-/**
- * Heading-based HEARTBEAT section writer.
- *
- * @remarks
- * Manages the `# Jeeves Platform Status` section in HEARTBEAT.md.
- * Unlike TOOLS/SOUL/AGENTS (which use HTML comment markers), HEARTBEAT
- * uses markdown headings as markers — this ensures the file passes
- * OpenClaw's heartbeat emptiness check when only headings remain.
- *
- * The section is always at the bottom of the file (H1 to EOF).
- * User heartbeat items above the section are preserved.
- */
-/** The H1 heading that anchors the platform status section. */
-declare const HEARTBEAT_HEADING = "# Jeeves Platform Status";
-/** A single component entry in the HEARTBEAT section. */
-interface HeartbeatEntry {
-    /** Component name (e.g., 'runner', 'watcher'). */
-    name: string;
-    /** Whether the component is declined. */
-    declined: boolean;
-    /** Alert content (list items). Empty string if healthy or declined. */
-    content: string;
-}
-/** Result of parsing the HEARTBEAT section. */
-interface ParsedHeartbeat {
-    /** Content above the `# Jeeves Platform Status` heading (user zone). */
-    userContent: string;
-    /** Whether the heading was found. */
-    found: boolean;
-    /** Parsed component entries. */
-    entries: HeartbeatEntry[];
-}
-/**
- * Parse the HEARTBEAT.md file content.
- *
- * @param fileContent - Full file content.
- * @returns Parsed result with user zone and component entries.
- */
-declare function parseHeartbeat(fileContent: string): ParsedHeartbeat;
-/**
- * Build the HEARTBEAT section content from entries.
- *
- * @param entries - Component entries to write.
- * @returns The full section string (H1 + H2s).
- */
-declare function buildHeartbeatSection(entries: HeartbeatEntry[]): string;
-/**
- * Write the HEARTBEAT section to a file.
- *
- * @remarks
- * Replaces everything from `# Jeeves Platform Status` to EOF.
- * Preserves user content above the heading.
- *
- * @param filePath - Absolute path to HEARTBEAT.md.
- * @param entries - Component entries to write.
- */
-declare function writeHeartbeatSection(filePath: string, entries: HeartbeatEntry[]): Promise<void>;
-
-/**
- * HEARTBEAT health orchestration.
- *
- * @remarks
- * Determines the state of each platform component and generates
- * HEARTBEAT entries with actionable alert text. Applies the dependency
- * graph for alert suppression and auto-decline.
- */
-
-/** Component state as determined by the orchestrator. */
-type ComponentState = 'not_installed' | 'deps_missing' | 'config_missing' | 'service_not_installed' | 'service_stopped' | 'healthy' | 'update_available';
-/** Options for the orchestrator. */
-interface OrchestrateHeartbeatOptions {
-    /** Path to the core config directory. */
-    coreConfigDir: string;
-    /** Path to the config root. */
-    configRoot: string;
-    /** Existing declined component names (from parsing current HEARTBEAT). */
-    declinedNames: Set<string>;
-}
-/**
- * Orchestrate HEARTBEAT entries for all platform components.
- *
- * @param options - Orchestration configuration.
- * @returns Array of HeartbeatEntry for writeHeartbeatSection.
+ * @module
  */
-declare function orchestrateHeartbeat(options: OrchestrateHeartbeatOptions): Promise<HeartbeatEntry[]>;
+/** The four essential platform components. */
+declare const PLATFORM_COMPONENTS: readonly ["runner", "watcher", "server", "meta"];
+/** A platform component name. */
+type PlatformComponent = (typeof PLATFORM_COMPONENTS)[number];
 
 /**
- * Component interface types for the Jeeves platform.
+ * Comment markers delimiting Jeeves managed content blocks in SOUL.md and AGENTS.md.
  *
  * @remarks
- * These types support the platform's HEARTBEAT orchestration and
- * dependency graph resolution.
- */
-/** Component dependency declarations. */
-interface ComponentDependencies {
-    /**
-     * Hard dependencies — the component cannot function without these.
-     * If a hard dep is not healthy, suppress all alerts for this component
-     * except a "waiting for dependency" message. If a hard dep is declined,
-     * auto-decline this component.
-     */
-    hard: string[];
-    /**
-     * Soft dependencies — the component works without these but with reduced
-     * functionality. When the component is healthy and a soft dep is missing,
-     * generate an informational alert. No alert when a soft dep is declined.
-     */
-    soft: string[];
-}
-
-/**
- * Comment markers for managed content blocks.
+ * Managed content is enclosed in HTML comment markers so that re-rendering by
+ * `jeeves install` can replace the Jeeves block in place while leaving user content
+ * outside the markers untouched. Marker text is unchanged from v0.x so that
+ * blocks written by earlier versions are recognised and replaced.
  *
- * @remarks
- * Managed content in TOOLS.md, SOUL.md, and AGENTS.md is enclosed
- * in HTML comment markers. Content between markers is refreshed
- * atomically on each writer cycle. User content outside the markers
- * is never touched.
+ * @module
  */
-/** Shape of managed content markers used by updateManagedSection and removeManagedSection. */
+/** Shape of a managed content marker set. */
 interface ManagedMarkers {
     /** BEGIN comment marker text. */
     begin: string;
@@ -829,65 +591,61 @@ interface ManagedMarkers {
     /** Optional H1 title prepended inside the managed block. */
     title?: string;
     /**
-     * Position of the managed block within the file.
-     * - `'top'`: managed block first, user content below (current default).
+     * Position of a newly inserted managed block within the file.
+     * - `'top'`: managed block first, user content below.
      * - `'bottom'`: user content first, managed block at end.
      *
      * @defaultValue `'top'`
      */
     position?: 'top' | 'bottom';
 }
-/** Default markers for TOOLS.md managed block. */
-declare const TOOLS_MARKERS: ManagedMarkers;
-/** Default markers for SOUL.md managed block. */
+/** Markers for the SOUL.md managed block. */
 declare const SOUL_MARKERS: ManagedMarkers;
-/** Default markers for AGENTS.md managed block. */
+/** Markers for the AGENTS.md managed block. */
 declare const AGENTS_MARKERS: ManagedMarkers;
 /**
- * Regex pattern to extract version stamp from a BEGIN marker comment.
+ * Markers for the legacy (v0.x) TOOLS.md managed block.
+ *
+ * @remarks
+ * OpenClaw 2026.9.6 no longer loads TOOLS.md, and Jeeves no longer writes it.
+ * Retained only so that tooling can recognise and strip blocks written by
+ * earlier versions (e.g. `jeeves uninstall`).
+ */
+declare const LEGACY_TOOLS_MARKERS: ManagedMarkers;
+/**
+ * Regex pattern to extract the version stamp from a BEGIN marker comment.
  *
  * @remarks
  * Format: `\<!-- BEGIN MARKER | core:X.Y.Z | ISO-TIMESTAMP --\>`
  * Captures: [1] marker text, [2] version, [3] timestamp
  */
 declare const VERSION_STAMP_PATTERN: RegExp;
-/** Staleness threshold for version-stamp convergence in milliseconds. */
-declare const STALENESS_THRESHOLD_MS: number;
-/** Warning text injected inside managed block when cleanup is needed. */
-declare const CLEANUP_FLAG = "> \u26A0\uFE0F CLEANUP NEEDED: Orphaned Jeeves content detected outside this managed block. Review the file and remove any content outside the BEGIN/END markers that duplicates what appears inside them.";
 
 /**
  * Directory and file path conventions for the Jeeves platform.
+ *
+ * @module
  */
 /** Core config directory name within the config root. */
 declare const CORE_CONFIG_DIR = "jeeves-core";
 /** Prefix for component config directories: `jeeves-{name}`. */
 declare const COMPONENT_CONFIG_PREFIX = "jeeves-";
-/** Default workspace file names. */
+/** Workspace file names that Jeeves renders into or reads. */
 declare const WORKSPACE_FILES: {
-    /** TOOLS.md — live platform state and component sections. */
-    readonly tools: "TOOLS.md";
     /** SOUL.md — professional discipline and behavioral foundations. */
     readonly soul: "SOUL.md";
-    /** AGENTS.md — operational protocols and memory architecture. */
+    /** AGENTS.md — operational protocols. */
     readonly agents: "AGENTS.md";
-    /** HEARTBEAT.md — platform status and health alerts. */
-    readonly heartbeat: "HEARTBEAT.md";
     /** MEMORY.md — curated long-term memory. */
     readonly memory: "MEMORY.md";
+    /**
+     * TOOLS.md — legacy (v0.x) only. No longer loaded by OpenClaw and no longer
+     * written by Jeeves; retained so tooling can strip legacy managed blocks.
+     */
+    readonly legacyTools: "TOOLS.md";
 };
-/** Skill directory name within workspace. */
-declare const SKILLS_DIR = "skills";
-/** Jeeves skill directory name. */
-declare const JEEVES_SKILL_DIR = "jeeves";
-/** Templates directory name within core config. */
-declare const TEMPLATES_DIR = "templates";
-/** Registry cache file name. */
-declare const REGISTRY_CACHE_FILE = "registry-cache.json";
 /** Core config file name. */
 declare const CONFIG_FILE = "config.json";
-/** Component versions state file name. */
-declare const COMPONENT_VERSIONS_FILE = "component-versions.json";
 
 /**
  * Default port assignments for Jeeves platform services.
@@ -910,47 +668,6 @@ declare const META_PORT = 1938;
 /** Map of service names to their default ports. */
 declare const DEFAULT_PORTS: Record<string, number>;
 
-/**
- * Managed section IDs, stable ordering, and platform component registry.
- *
- * @remarks
- * Section ordering is fixed to prevent diff churn regardless of which
- * component writes last. Sections always appear in this order.
- */
-/** Known section IDs for TOOLS.md managed block. */
-declare const SECTION_IDS: {
-    /** Platform health and guidance section. */
-    readonly Platform: "Platform";
-    /** Watcher index stats and search configuration. */
-    readonly Watcher: "Watcher";
-    /** Server export capabilities and connected services. */
-    readonly Server: "Server";
-    /** Runner job status and active scripts. */
-    readonly Runner: "Runner";
-    /** Meta synthesis entity summary and tools. */
-    readonly Meta: "Meta";
-};
-/** Section ID type. */
-type SectionId = (typeof SECTION_IDS)[keyof typeof SECTION_IDS];
-/**
- * Stable ordering of sections within the managed TOOLS.md block.
- * Sections always appear in this order regardless of write order.
- */
-declare const SECTION_ORDER: readonly string[];
-/**
- * The four essential platform components.
- *
- * @remarks
- * These components constitute the Jeeves platform. `jeeves install` writes
- * initial HEARTBEAT "Not installed" alerts for all of them. The HEARTBEAT
- * writer generates "Not installed" alerts only for platform components not
- * in `component-versions.json`. Optional future components (not in this list)
- * appear in HEARTBEAT only after explicit install.
- */
-declare const PLATFORM_COMPONENTS: readonly ["runner", "watcher", "server", "meta"];
-/** A platform component name. */
-type PlatformComponent = (typeof PLATFORM_COMPONENTS)[number];
-
 /**
  * Core library version, inlined at build time.
  *
@@ -973,6 +690,11 @@ declare const CORE_VERSION: string;
  * 1. Component's own config file
  * 2. Core config file
  * 3. Hardcoded library defaults
+ *
+ * Unknown keys are stripped on parse, so files that still carry retired
+ * keys (e.g. v0.x `registryCache`) keep validating.
+ *
+ * @module
  */
 
 /** Default bind address for all Jeeves services. */
@@ -985,9 +707,6 @@ declare const coreConfigSchema: z.ZodObject<{
     services: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         url: z.ZodURL;
     }, z.core.$strip>>>;
-    registryCache: z.ZodPrefault<z.ZodObject<{
-        ttlSeconds: z.ZodDefault<z.ZodNumber>;
-    }, z.core.$strip>>;
 }, z.core.$strip>;
 /** Core config type derived from the Zod schema. */
 type CoreConfig = z.infer<typeof coreConfigSchema>;
@@ -1053,23 +772,6 @@ declare function getServiceState(serviceName: string): ServiceState;
  */
 declare function getServiceUrl(serviceName: string, consumerName?: string): string;
 
-/**
- * Registry version cache for npm package update awareness.
- *
- * @remarks
- * Caches the latest npm registry version in a local JSON file
- * to avoid expensive `npm view` calls on every refresh cycle.
- */
-/**
- * Check the npm registry for the latest version of a package.
- *
- * @param packageName - The npm package name (e.g., '\@karmaniverous/jeeves').
- * @param cacheDir - Directory to store the cache file.
- * @param ttlSeconds - Cache TTL in seconds (default 3600).
- * @returns The latest version string, or undefined if the check fails.
- */
-declare function checkRegistryVersion(packageName: string, cacheDir: string, ttlSeconds?: number): string | undefined;
-
 /**
  * Workspace and config root initialization.
  *
@@ -1160,50 +862,53 @@ declare function getComponentConfigPath(componentName: string): string | undefin
 declare function resetInit(): void;
 
 /**
- * Similarity-based cleanup detection for orphaned managed content.
+ * Cross-process advisory file lock using an atomic `mkdir` of `{file}.lock`.
  *
  * @remarks
- * Uses Jaccard similarity on 3-word shingles (Decision 22) to detect
- * when orphaned managed content exists in the user content zone.
- */
-/**
- * Generate a set of n-word shingles from text.
+ * Replaces `proper-lockfile`, whose `signal-exit` dependency registered
+ * process-level SIGINT/SIGTERM/... handlers at import time in every process
+ * that loaded this library (including the OpenClaw gateway and CLI, via the
+ * Jeeves plugins). This implementation registers no process handlers and
+ * starts no timers, so it cannot keep a process alive.
  *
- * @param text - Input text.
- * @param n - Shingle size (default 3).
- * @returns Set of n-word shingles.
- */
-declare function shingles(text: string, n?: number): Set<string>;
-/**
- * Compute Jaccard similarity between two sets.
+ * The lock directory name (`{file}.lock`) matches proper-lockfile's
+ * convention, so v0.x holders and this implementation exclude each other
+ * during a mixed-version rollout. A lock whose mtime is older than
+ * {@link STALE_LOCK_MS} is considered abandoned and is taken over; takeovers
+ * are serialised through a `{file}.lock.takeover` guard so a freshly
+ * re-taken lock is never deleted. The lock's mtime is not refreshed while it
+ * is held (that would need a timer), so callbacks must finish well within
+ * the stale threshold: they are meant to be a short read-modify-write.
  *
- * @param a - First set.
- * @param b - Second set.
- * @returns Jaccard similarity coefficient (0 to 1).
+ * @module
  */
-declare function jaccard(a: Set<string>, b: Set<string>): number;
+/** Stale lock threshold in ms (2 minutes). */
+declare const STALE_LOCK_MS = 120000;
 /**
- * Check whether user content contains orphaned managed content.
+ * Execute a callback while holding an exclusive lock on a file.
+ *
+ * @remarks
+ * Fails fast (no retries) with an `ELOCKED` error when the lock is held,
+ * matching the v0.x behaviour. The lock is always released in a `finally`
+ * block. The target file need not exist. `fn` must complete well within
+ * `staleMs`: the lock is not refreshed while held, so a longer callback can
+ * be taken over by another process.
  *
- * @param managedContent - The current managed block content.
- * @param userContent - Content below the END marker.
- * @param threshold - Jaccard threshold (default 0.15).
- * @returns `true` if cleanup is needed.
+ * @param filePath - Absolute path to the file to lock.
+ * @param fn - Callback to execute while holding the lock.
+ * @param staleMs - Stale threshold in ms. Defaults to {@link STALE_LOCK_MS}.
  */
-declare function needsCleanup(managedContent: string, userContent: string, threshold?: number): boolean;
+declare function withFileLock(filePath: string, fn: () => void | Promise<void>, staleMs?: number): Promise<void>;
 
 /**
- * Shared file I/O helpers for managed section operations.
+ * Atomic file write (temp file + rename) with Windows EPERM retry.
  *
  * @remarks
- * Extracts the atomic write pattern and file-level locking into
- * reusable utilities, eliminating duplication between
- * `updateManagedSection` and `removeManagedSection`.
+ * Synchronous; touches only the target directory. Used by service-side config
+ * persistence and by `jeeves install`.
+ *
+ * @module
  */
-/** Stale lock threshold in ms (2 minutes). */
-declare const STALE_LOCK_MS = 120000;
-/** Default core version when none provided. */
-declare const DEFAULT_CORE_VERSION: string;
 /**
  * Write content to a file atomically via a temp file + rename.
  *
@@ -1211,168 +916,127 @@ declare const DEFAULT_CORE_VERSION: string;
  * Retries the rename up to three times on EPERM (Windows file-handle
  * contention) with a 100 ms synchronous delay between attempts.
  *
+ * When `options.mode` is given, the temp file gets exactly that mode before
+ * the rename (so a secret-bearing file is never visible with wider
+ * permissions); on Windows only the read-only bit is affected.
+ *
  * @param filePath - Absolute path to the target file.
  * @param content - Content to write.
+ * @param options - Optional file mode for the written file.
  */
-declare function atomicWrite(filePath: string, content: string): void;
+declare function atomicWrite(filePath: string, content: string, options?: {
+    mode?: number;
+}): void;
+
 /**
- * Execute a callback while holding a file lock.
+ * Pure string transforms that render, insert, replace, and remove a Jeeves
+ * managed block in workspace file content. No I/O.
  *
  * @remarks
- * Acquires a lock on the file, executes the callback, and releases
- * the lock in a finally block. The lock uses a 2-minute stale threshold
- * and retries up to 5 times.
+ * Used by `jeeves install` / `jeeves uninstall`; exported for any tool that
+ * edits a managed block with its own marker set. An existing block is replaced in
+ * place; a new block is inserted at the marker set's configured position.
+ * User content outside the markers is preserved verbatim (trimmed).
  *
- * @param filePath - Absolute path to the file to lock.
- * @param fn - Async callback to execute while holding the lock.
+ * @module
  */
-declare function withFileLock(filePath: string, fn: () => void | Promise<void>): Promise<void>;
 
-/**
- * Parse managed block from file content.
- *
- * @remarks
- * Extracts managed content delimited by comment markers, parses H2
- * sections within the block, and returns the structured result plus
- * user content outside the markers.
- */
-/** A parsed H2 section within the managed block. */
-interface ManagedSection {
-    /** Section heading text (without the `## ` prefix). */
-    id: string;
-    /** Content below the heading (trimmed). */
-    content: string;
-}
-/** Version stamp extracted from the BEGIN marker. */
-interface VersionStamp {
-    /** Core library version (semver). */
+/** Options controlling the version stamp on a rendered BEGIN marker. */
+interface ManagedBlockStampOptions {
+    /** Core library version written into the stamp. */
     version: string;
-    /** ISO timestamp of last write. */
-    timestamp: string;
-}
-/** Result of parsing a managed block from file content. */
-interface ParseManagedResult {
-    /** Whether valid markers were found. */
-    found: boolean;
-    /** Version stamp from the BEGIN marker, if present. */
-    versionStamp: VersionStamp | undefined;
-    /** Raw managed block content (between markers, excluding markers). */
-    managedContent: string;
-    /** Parsed H2 sections within the managed block. */
-    sections: ManagedSection[];
-    /** Content before the BEGIN marker. */
-    beforeContent: string;
-    /** Content after the END marker (user content). */
-    userContent: string;
+    /** Render time written into the stamp. Defaults to now. */
+    now?: Date;
 }
 /**
- * Parse a managed block from file content.
+ * Format the BEGIN marker comment with a version stamp.
  *
- * @param fileContent - Full file content.
- * @param markers - Optional custom markers (defaults to TOOLS markers).
- * @returns Parsed result with sections, version stamp, and user content.
+ * @param markerText - The marker text.
+ * @param version - The core library version.
+ * @param now - Render time. Defaults to now.
+ * @returns Formatted comment line.
  */
-declare function parseManaged(fileContent: string, markers?: {
-    begin: string;
-    end: string;
-}): ParseManagedResult;
-
+declare function formatBeginMarker(markerText: string, version: string, now?: Date): string;
 /**
- * Remove a managed section or entire managed block from a file.
- *
- * @remarks
- * Supports two modes:
- * - No `sectionId`: Remove the entire managed block (markers + content),
- *   leaving user content intact.
- * - With `sectionId`: Remove a specific H2 section from within the
- *   managed block. If it was the last section, remove the entire block.
+ * Format the END marker comment.
  *
- * Provides file-level locking and atomic writes (temp file + rename).
- * Missing markers or nonexistent sections are no-ops (no error thrown).
+ * @param markerText - The marker text.
+ * @returns Formatted comment line.
  */
-
-/** Options for removeManagedSection. */
-interface RemoveManagedSectionOptions {
-    /** Section ID to remove. If omitted, removes the entire managed block. */
-    sectionId?: string;
-    /** Custom markers. Defaults to TOOLS markers. */
-    markers?: ManagedMarkers;
-}
+declare function formatEndMarker(markerText: string): string;
 /**
- * Remove a managed section or entire managed block from a file.
+ * Render a complete managed block (BEGIN marker, optional H1 title, body,
+ * END marker).
  *
- * @param filePath - Absolute path to the target file.
- * @param options - Optional section ID and custom markers.
+ * @param markers - Marker set.
+ * @param body - Managed body (Markdown).
+ * @param stamp - Version stamp options.
+ * @returns The managed block, without a trailing newline.
  */
-declare function removeManagedSection(filePath: string, options?: RemoveManagedSectionOptions): Promise<void>;
-
+declare function renderManagedBlock(markers: ManagedMarkers, body: string, stamp: ManagedBlockStampOptions): string;
 /**
- * Generic managed-section writer with block and section modes.
+ * Insert or replace the managed block in file content.
  *
  * @remarks
- * Supports two modes:
- * - `block`: Replaces the entire managed block (SOUL.md, AGENTS.md).
- * - `section`: Upserts a named H2 section within the managed block (TOOLS.md).
+ * If a block with these markers exists, it is replaced in place. Otherwise
+ * the block is inserted at `markers.position` (default `'top'`), and any
+ * orphaned BEGIN marker of the same type is stripped from user content so it
+ * cannot pair with the new END marker later.
  *
- * Provides version-stamp convergence and atomic writes.
+ * @param fileContent - Existing file content (empty string for a new file).
+ * @param markers - Marker set.
+ * @param body - Managed body (Markdown).
+ * @param stamp - Version stamp options.
+ * @returns The new file content.
  */
-
-/** Options for updateManagedSection. */
-interface UpdateManagedSectionOptions {
-    /** Write mode. Default: 'block'. */
-    mode?: 'block' | 'section';
-    /** Section ID — required when mode is 'section'. */
-    sectionId?: string;
-    /** Custom markers. Defaults to TOOLS markers. */
-    markers?: ManagedMarkers;
-    /** Core library version for version-stamp convergence. */
-    coreVersion?: string;
-    /** Staleness threshold in ms for version-stamp convergence. */
-    stalenessThresholdMs?: number;
-}
+declare function upsertManagedBlock(fileContent: string, markers: ManagedMarkers, body: string, stamp: ManagedBlockStampOptions): string;
 /**
- * Update a managed section in a file.
+ * Remove the managed block from file content, keeping user content.
  *
- * @param filePath - Absolute path to the target file.
- * @param content - New content to write.
- * @param options - Write mode and optional configuration.
+ * @param fileContent - Existing file content.
+ * @param markers - Marker set.
+ * @returns The new file content (unchanged if no block is present).
  */
-declare function updateManagedSection(filePath: string, content: string, options?: UpdateManagedSectionOptions): Promise<void>;
+declare function removeManagedBlock(fileContent: string, markers: Pick<ManagedMarkers, 'begin' | 'end'>): string;
 
 /**
- * Version-stamp parsing and convergence logic.
+ * Parse a Jeeves managed block out of workspace file content (pure).
  *
  * @remarks
- * When multiple component plugins bundle different core library versions,
- * they independently maintain shared managed content. The version-stamp
- * mechanism ensures convergence without coordination state.
- */
-
-/**
- * Format the BEGIN marker comment with a version stamp.
+ * Locates the BEGIN/END comment markers, extracts the managed content and its
+ * version stamp, and returns the user content before and after the block.
  *
- * @param markerText - The marker text (e.g., 'BEGIN JEEVES PLATFORM TOOLS').
- * @param version - The core library version.
- * @returns Formatted comment line.
- */
-declare function formatBeginMarker(markerText: string, version: string): string;
-/**
- * Format the END marker comment.
- *
- * @param markerText - The marker text (e.g., 'END JEEVES PLATFORM TOOLS').
- * @returns Formatted comment line.
+ * @module
  */
-declare function formatEndMarker(markerText: string): string;
+
+/** Version stamp extracted from the BEGIN marker. */
+interface VersionStamp {
+    /** Core library version (semver). */
+    version: string;
+    /** ISO timestamp of the render. */
+    timestamp: string;
+}
+/** Result of parsing a managed block from file content. */
+interface ParseManagedResult {
+    /** Whether a valid BEGIN/END marker pair was found. */
+    found: boolean;
+    /** Version stamp from the BEGIN marker, if present. */
+    versionStamp: VersionStamp | undefined;
+    /** Raw managed block content (between markers, excluding markers). */
+    managedContent: string;
+    /** Content before the BEGIN marker (trimmed). */
+    beforeContent: string;
+    /** Content after the END marker (trimmed), or the whole file if not found. */
+    userContent: string;
+}
 /**
- * Determine whether this writer should proceed based on version-stamp
- * convergence rules.
+ * Parse a managed block from file content.
  *
- * @param myVersion - The current core library version.
- * @param existing - The existing version stamp (if any).
- * @param stalenessThresholdMs - Staleness threshold in ms (default: 5 min).
- * @returns `true` if the writer should proceed with the write.
+ * @param fileContent - Full file content.
+ * @param markers - BEGIN/END marker pair to look for.
+ * @returns Parsed result with version stamp and surrounding user content.
  */
-declare function shouldWrite(myVersion: string, existing: VersionStamp | undefined, stalenessThresholdMs?: number): boolean;
+declare function parseManaged(fileContent: string, markers: Pick<ManagedMarkers, 'begin' | 'end'>): ParseManagedResult;
 
 /**
  * Memory budget accounting for MEMORY.md.
@@ -1415,123 +1079,58 @@ interface MemoryHygieneOptions {
 declare function analyzeMemory(options: MemoryHygieneOptions): MemoryHygieneResult;
 
 /**
- * HEARTBEAT integration for memory hygiene.
+ * Build/test-time check that a plugin's `package.json` declares the OpenClaw
+ * conversation hooks it registers (e.g. via `registerPromptContext`), as
+ * `"jeeves": { "conversationHooks": [...] }`. Pure apart from calling the
+ * plugin's own `register` with a recording API.
  *
  * @remarks
- * Calls `analyzeMemory()` and converts the result into a `HeartbeatEntry`
- * suitable for inclusion in the HEARTBEAT.md platform status section.
- * Returns `undefined` when MEMORY.md is healthy (no alert needed).
- *
- * Uses the `## MEMORY.md` heading (Decision 50) to distinguish memory
- * alerts from component alerts (`## jeeves-{name}`).
- */
-
-/** The HEARTBEAT heading name for memory alerts. */
-declare const MEMORY_HEARTBEAT_NAME = "MEMORY.md";
-/**
- * Check memory health and return a HEARTBEAT entry if unhealthy.
+ * OpenClaw blocks every conversation hook of a non-bundled plugin unless
+ * `plugins.entries.<id>.hooks.allowConversationAccess` is `true`, and it has
+ * no static record of the typed hooks a plugin registers. `jeeves install` /
+ * `jeeves update` therefore grant access only to plugins whose `package.json`
+ * declares such hooks. A plugin that registers one without declaring it
+ * installs cleanly and then silently never runs the hook, so plugins should
+ * run {@link validateConversationHooks} in a test or build step:
  *
- * @param options - Memory hygiene options (workspacePath, budget, etc.).
- * @returns A `HeartbeatEntry` when memory needs attention, `undefined` when healthy.
- */
-declare function checkMemoryHealth(options: MemoryHygieneOptions): HeartbeatEntry | undefined;
-
-/**
- * Internal function to maintain SOUL.md, AGENTS.md, and TOOLS.md Platform section.
- *
- * @remarks
- * Called by `ComponentWriter` on each cycle. Not directly exposed to components.
- * Reads content files from the package's `content/` directory, renders the
- * Platform template with live data, and writes managed sections using
- * `updateManagedSection`.
- */
-
-/** Options for refreshPlatformContent. */
-interface RefreshPlatformContentOptions {
-    /** Core library version for version-stamp convergence. */
-    coreVersion: string;
-    /** Component name (for registry cache directory). */
-    componentName?: string;
-    /** Component plugin version (e.g., '0.2.0'). */
-    componentVersion?: string;
-    /** npm package name for the service (for registry update check). */
-    servicePackage?: string;
-    /** npm package name for the plugin (for registry update check). */
-    pluginPackage?: string;
-    /** Staleness threshold override in ms. */
-    stalenessThresholdMs?: number;
-    /** Pre-loaded workspace config (avoids redundant reads when caller already loaded it). */
-    workspaceConfig?: WorkspaceConfig;
-}
-/**
- * Refresh platform content: SOUL.md, AGENTS.md, and TOOLS.md Platform section.
- *
- * @param options - Configuration for the refresh cycle.
- */
-declare function refreshPlatformContent(options: RefreshPlatformContentOptions): Promise<void>;
-
-/**
- * One-shot content seeding used by the CLI install command.
- *
- * @remarks
- * Seeds SOUL.md, AGENTS.md, and TOOLS.md Platform section using the same
- * `updateManagedSection()` code path as writer cycles. Also copies templates
- * and creates core config with defaults if missing.
- */
-/** Options for seeding content. */
-interface SeedContentOptions {
-    /** Core library version for version-stamp convergence. */
-    coreVersion: string;
-}
-/**
- * Seed all platform content into the workspace.
- *
- * @remarks
- * Uses the same `updateManagedSection()` code path as writer cycles.
- * Creates core config with defaults if missing. Copies templates.
- * Writes initial HEARTBEAT with "Not installed" alerts for all platform components.
- * Jaccard cleanup detection runs automatically via `updateManagedSection`.
- *
- * @param options - Seeding configuration.
- */
-declare function seedContent(options: SeedContentOptions): Promise<void>;
-
-/**
- * Backward-compatible re-export of `seedSkills`.
- *
- * @remarks
- * Delegates to `seedSkills` which seeds all bundled platform skills.
- * Retained for API compatibility with existing component plugins.
+ * ```typescript
+ * const hooks = await recordRegisteredHooks(register);
+ * validateConversationHooks(JSON.parse(readFileSync('package.json', 'utf-8')), hooks);
+ * ```
  *
  * @module
  */
+
 /**
- * Seed all bundled platform skills into the workspace.
- *
- * @param workspacePath - Workspace root directory.
+ * OpenClaw's conversation hooks: the typed hooks gated by
+ * `allowConversationAccess` (v2026.9.6 `src/plugins/hook-types.ts`
+ * `CONVERSATION_HOOK_NAMES`).
  */
-declare function seedSkill(workspacePath: string): void;
-
+declare const CONVERSATION_HOOK_NAMES: readonly string[];
 /**
- * Skill seeding: write all bundled platform skills to the workspace.
- *
- * @remarks
- * Skill files are entirely generated — no user-authored content (Decision 48).
- * Every installer (core CLI and component plugins) writes them unconditionally.
- * Content is inlined at build time via `rollup-plugin-md.ts`.
+ * Run a plugin's `register(api)` against a recording API and return the
+ * typed hook names it registers with `api.on` (e.g. `before_prompt_build`
+ * from `registerPromptContext`).
  *
- * @module
+ * @param register - The plugin's register function.
+ * @param api - Extra API members the plugin needs at registration (config,
+ *   logger, ...). `on` is always the recorder; `registerTool` defaults to a
+ *   no-op.
+ * @returns Registered hook names, in registration order.
  */
+declare function recordRegisteredHooks(register: (api: PluginApi) => unknown, api?: Partial<PluginApi>): Promise<string[]>;
 /**
- * Seed all bundled platform skills into the workspace.
- *
- * @remarks
- * Writes each skill to `{workspace}/skills/{name}/SKILL.md`, creating
- * directories as needed. Overwrites existing content unconditionally.
+ * Check that `package.json` declares exactly the conversation hooks a plugin
+ * registers.
  *
- * @param workspacePath - Workspace root directory.
+ * @param packageJson - Parsed `package.json` of the plugin package.
+ * @param registeredHooks - Hook names the plugin registers (see
+ *   {@link recordRegisteredHooks}); non-conversation hooks are ignored.
+ * @returns The declared conversation hooks.
+ * @throws Error when the field is malformed, a registered conversation hook
+ *   is not declared, or a declared hook is not a registered conversation hook.
  */
-declare function seedSkills(workspacePath: string): void;
+declare function validateConversationHooks(packageJson: unknown, registeredHooks: readonly string[]): string[];
 
 /**
  * Factory for the standard plugin tool set.
@@ -1616,63 +1215,84 @@ declare function fetchJson(url: string, init?: RequestInit): Promise<unknown>;
 declare function postJson(url: string, body: unknown): Promise<unknown>;
 
 /**
- * OpenClaw configuration helpers for plugin CLI installers.
+ * Tie plugin-owned resources (timers, sockets, clients) to the OpenClaw
+ * plugin lifecycle so a process that loads the plugin can exit.
  *
  * @remarks
- * Provides resolution of OpenClaw home directory and config file path,
- * plus idempotent config patching for plugin install/uninstall.
+ * Plugins must not install process-level signal handlers or leave live
+ * timers/handles behind: `openclaw plugins inspect` and other CLI commands
+ * load plugin code and must exit on their own, and the gateway force-retires
+ * plugins that do not release work on shutdown (runbook S1).
+ *
+ * @module
  */
+
 /**
- * Resolve the OpenClaw home directory.
+ * Register a disposer with the host plugin lifecycle.
  *
  * @remarks
- * Resolution order:
- * 1. `OPENCLAW_CONFIG` env var → dirname of the config file path
- * 2. `OPENCLAW_HOME` env var → resolved path
- * 3. Default: `~/.openclaw`
+ * Prefers `api.lifecycle.onDispose` (instance retirement); falls back to
+ * `api.lifecycle.registerRuntimeLifecycle({ id, dispose })`.
  *
- * @returns Absolute path to the OpenClaw home directory.
+ * @param api - The OpenClaw plugin API passed to `register(api)`.
+ * @param id - Stable id for the resource (used by the fallback path).
+ * @param dispose - Releases the resource. Must be idempotent.
+ * @returns `true` if registered; `false` if the host exposes no lifecycle API
+ *   (the caller should then avoid starting long-lived work).
  */
-declare function resolveOpenClawHome(): string;
+declare function onPluginDispose(api: PluginApi, id: string, dispose: () => void | Promise<void>): boolean;
+
 /**
- * Resolve the OpenClaw config file path.
+ * Register always-in-context plugin rules via OpenClaw's `before_prompt_build`
+ * hook, returning `{ appendSystemContext }` (never `systemPrompt`).
  *
  * @remarks
- * If `OPENCLAW_CONFIG` is set, uses that directly.
- * Otherwise defaults to `{home}/openclaw.json`.
- *
- * @param home - The OpenClaw home directory.
- * @returns Absolute path to the config file.
- */
-declare function resolveConfigPath(home: string): string;
-/** Options for writing a plugin install provenance record. */
-interface PluginInstallRecord {
-    /** Absolute path to the extensions directory where the plugin was installed. */
-    installPath: string;
-    /** Plugin version string from package.json, if known. */
-    version?: string;
-    /** ISO timestamp of installation. Defaults to `new Date().toISOString()`. */
-    installedAt?: string;
-}
-/**
- * Patch an OpenClaw config for plugin install.
+ * Runbook D5 / spike S2: `appendSystemContext` is appended after the prompt
+ * cache boundary, concatenated across plugins in priority order, and does not
+ * count toward `bootstrapMaxChars`. `systemPrompt` would replace the whole
+ * prompt, so the result type here cannot express it.
+ *
+ * **Host config gate:** OpenClaw only runs this hook for non-bundled plugins
+ * when `plugins.entries.<id>.hooks.allowConversationAccess` is `true`.
+ * `openclaw plugins install --accept-capabilities` does NOT set it;
+ * `jeeves install` / `jeeves update` grant it to plugins that declare the
+ * hook in `package.json` `jeeves.conversationHooks`.
  *
- * @param config - The parsed OpenClaw config object (mutated in place).
- * @param pluginId - The plugin identifier.
- * @param mode - Install mode.
- * @param installRecord - Install provenance record.
- * @returns Array of log messages describing changes made.
+ * @module
  */
-declare function patchConfig(config: Record<string, unknown>, pluginId: string, mode: 'add', installRecord: PluginInstallRecord): string[];
+
+/** Produces prompt context text; empty/undefined means "inject nothing". */
+type PromptContextProvider = (ctx: PromptBuildContext) => string | undefined | Promise<string | undefined>;
+/** Zod schema for {@link registerPromptContext} options. */
+declare const promptContextOptionsSchema: z.ZodObject<{
+    content: z.ZodUnion<readonly [z.ZodString, z.ZodCustom<PromptContextProvider, PromptContextProvider>]>;
+    priority: z.ZodOptional<z.ZodNumber>;
+    registrationId: z.ZodOptional<z.ZodString>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/** Options for {@link registerPromptContext}. */
+type PromptContextOptions = z.infer<typeof promptContextOptionsSchema>;
 /**
- * Patch an OpenClaw config for plugin uninstall.
+ * Register plugin rules that must always be in the agent's context.
  *
- * @param config - The parsed OpenClaw config object (mutated in place).
- * @param pluginId - The plugin identifier.
- * @param mode - Uninstall mode.
- * @returns Array of log messages describing changes made.
+ * @remarks
+ * Provider errors are logged (via `api.logger` when present) and yield no
+ * injection for that turn; they never fail the prompt build. Registers no
+ * timers or process handlers.
+ *
+ * @example
+ * ```typescript
+ * export default function register(api: PluginApi): void {
+ *   registerPromptContext(api, { content: WATCHER_RULES, priority: 10 });
+ * }
+ * ```
+ *
+ * @param api - The OpenClaw plugin API passed to `register(api)`.
+ * @param options - Content and registration options.
+ * @returns `true` if registered; `false` if the host has no `api.on`.
+ * @throws ZodError if options are invalid.
  */
-declare function patchConfig(config: Record<string, unknown>, pluginId: string, mode: 'remove'): string[];
+declare function registerPromptContext(api: PluginApi, options: PromptContextOptions): boolean;
 
 /**
  * Plugin resolution helpers for the OpenClaw plugin SDK.
@@ -1759,6 +1379,32 @@ declare function fail(error: unknown): ToolResult;
  */
 declare function connectionFail(error: unknown, baseUrl: string, pluginId: string): ToolResult;
 
+/**
+ * Minimal validation of SKILL.md frontmatter (`name` and `description`).
+ *
+ * @remarks
+ * OpenClaw skips skills without `name`/`description` frontmatter. Plugins
+ * can call this from a build or test step to enforce it (runbook D4). Pure.
+ *
+ * @module
+ */
+/** Parsed required frontmatter fields. */
+interface SkillFrontmatter {
+    /** Skill name. */
+    name: string;
+    /** Skill description (block scalars are folded to one line). */
+    description: string;
+}
+/**
+ * Validate that SKILL.md content carries non-empty `name` and `description`
+ * frontmatter.
+ *
+ * @param content - Full SKILL.md content.
+ * @returns The parsed fields.
+ * @throws Error describing the first missing requirement.
+ */
+declare function validateSkillFrontmatter(content: string): SkillFrontmatter;
+
 /**
  * Shared filesystem utilities for runner job scripts.
  *
@@ -1970,5 +1616,5 @@ declare function getErrorMessage(err: unknown): string;
  */
 declare function isTransientError(err: unknown): boolean;
 
-export { AGENTS_MARKERS, CLEANUP_FLAG, COMPONENT_CONFIG_PREFIX, COMPONENT_VERSIONS_FILE, CONFIG_FILE, CORE_CONFIG_DIR, CORE_VERSION, ComponentWriter, DEFAULT_BIND_ADDRESS, DEFAULT_CORE_VERSION, DEFAULT_PORTS, HEARTBEAT_HEADING, JEEVES_SKILL_DIR, MEMORY_HEARTBEAT_NAME, META_PORT, PLATFORM_COMPONENTS, REGISTRY_CACHE_FILE, RUNNER_PORT, SECTION_IDS, SECTION_ORDER, SERVER_PORT, SKILLS_DIR, SOUL_MARKERS, STALENESS_THRESHOLD_MS, STALE_LOCK_MS, TEMPLATES_DIR, TOOLS_MARKERS, VERSION_STAMP_PATTERN, WATCHER_PORT, WORKSPACE_CONFIG_DEFAULTS, WORKSPACE_CONFIG_FILE, WORKSPACE_FILES, analyzeMemory, appendJsonl, atomicWrite, buildEffectiveConfig, buildHeartbeatSection, checkMemoryHealth, checkNodeVersion, checkRegistryVersion, connectionFail, coreConfigSchema, createAsyncContentCache, createComponentWriter, createConfigApplyHandler, createConfigQueryHandler, createGoogleAuth, createPluginCli, createPluginToolset, createServiceCli, createServiceManager, createStatusHandler, ensureDir, fail, fetchJson, fetchWithTimeout, formatBeginMarker, formatEndMarker, generateJsonSchema, generateWorkspaceJsonSchema, getArg, getBindAddress, getChannelWorkspace, getComponentConfigDir, getComponentConfigPath, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getEffectiveServiceName, getErrorMessage, getPackageRoot, getPackageVersion, getServiceState, getServiceUrl, getWorkspacePath, init, isPrime, isTransientError, jaccard, jeevesComponentDescriptorSchema, loadEnvFile, loadWorkspaceConfig, needsCleanup, nowIso, ok, orchestrateHeartbeat, parseArgs, parseHeartbeat, parseManaged, patchConfig, postJson, readComponentVersions, readJson, readJsonl, refreshPlatformContent, registerComponentConfigPath, rejectWindowsDrivePath, removeComponentVersion, removeManagedSection, resetInit, resolveConfigPath, resolveConfigValue, resolveOpenClawHome, resolveOptionalPluginSetting, resolvePluginSetting, resolveWorkspacePath, run, runScript, runWithRetry, saveCache, seedContent, seedSkill, seedSkills, shingles, shouldWrite, sleepAsync, sleepMs, substituteEnvVars, updateManagedSection, uuid, withFileLock, workspaceConfigSchema, writeComponentVersion, writeHeartbeatSection, writeJsonAtomic, writeJsonl };
-export type { AccountConfig, AsyncContentCacheOptions, ComponentDependencies, ComponentState, ComponentVersionEntry, ComponentVersionsState, ComponentWriterOptions, ConfigApplyHandler, ConfigApplyRequest, ConfigApplyResult, ConfigProvenance, ConfigQueryHandler, ConfigQueryResponse, CoreConfig, CreatePluginCliOptions, CreateStatusHandlerOptions, GoogleAuthOptions, HeartbeatEntry, InitOptions, JeevesComponentDescriptor, ManagedMarkers, ManagedSection, MemoryHygieneOptions, MemoryHygieneResult, OrchestrateHeartbeatOptions, ParseManagedResult, ParsedHeartbeat, PlatformComponent, PluginApi, PluginInstallRecord, RefreshPlatformContentOptions, RemoveManagedSectionOptions, ResolvedCliConfig, ResolvedValue, RetryOptions, RunOptions, SectionId, SeedContentOptions, ServiceAccountFileConfig, ServiceManager, ServiceManagerOptions, ServiceState, SlackWorkspaceOptions, StatusHandler, StatusHandlerResult, StatusResponse, ToolDescriptor, ToolRegistrationOptions, ToolResult, UpdateManagedSectionOptions, VersionStamp, WorkspaceConfig, WorkspaceOptions, WriteComponentVersionOptions };
+export { AGENTS_MARKERS, COMPONENT_CONFIG_PREFIX, CONFIG_FILE, CONVERSATION_HOOK_NAMES, CORE_CONFIG_DIR, CORE_VERSION, DEFAULT_BIND_ADDRESS, DEFAULT_PORTS, LEGACY_TOOLS_MARKERS, META_PORT, PLATFORM_COMPONENTS, RUNNER_PORT, SERVER_PORT, SOUL_MARKERS, STALE_LOCK_MS, VERSION_STAMP_PATTERN, WATCHER_PORT, WORKSPACE_CONFIG_DEFAULTS, WORKSPACE_CONFIG_FILE, WORKSPACE_FILES, analyzeMemory, appendJsonl, atomicWrite, buildEffectiveConfig, checkNodeVersion, connectionFail, coreConfigSchema, createConfigApplyHandler, createConfigQueryHandler, createGoogleAuth, createPluginToolset, createServiceCli, createServiceManager, createStatusHandler, ensureDir, fail, fetchJson, fetchWithTimeout, formatBeginMarker, formatEndMarker, generateJsonSchema, generateWorkspaceJsonSchema, getArg, getBindAddress, getChannelWorkspace, getComponentConfigDir, getComponentConfigPath, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getEffectiveServiceName, getErrorMessage, getPackageRoot, getPackageVersion, getServiceState, getServiceUrl, getWorkspacePath, init, isTransientError, jeevesComponentDescriptorSchema, loadEnvFile, loadWorkspaceConfig, nowIso, ok, onPluginDispose, parseArgs, parseManaged, postJson, promptContextOptionsSchema, readJson, readJsonl, recordRegisteredHooks, registerComponentConfigPath, registerPromptContext, rejectWindowsDrivePath, removeManagedBlock, renderManagedBlock, resetInit, resolveConfigValue, resolveOptionalPluginSetting, resolvePluginSetting, resolveWorkspacePath, run, runScript, runWithRetry, saveCache, sleepAsync, sleepMs, substituteEnvVars, upsertManagedBlock, uuid, validateConversationHooks, validateSkillFrontmatter, withFileLock, workspaceConfigSchema, writeJsonAtomic, writeJsonl };
+export type { AccountConfig, ConfigApplyHandler, ConfigApplyRequest, ConfigApplyResult, ConfigProvenance, ConfigQueryHandler, ConfigQueryResponse, CoreConfig, CreateStatusHandlerOptions, GoogleAuthOptions, HookRegistrationOptions, InitOptions, JeevesComponentDescriptor, ManagedBlockStampOptions, ManagedMarkers, MemoryHygieneOptions, MemoryHygieneResult, ParseManagedResult, PlatformComponent, PluginApi, PluginLifecycleApi, PromptBuildContext, PromptBuildEvent, PromptBuildHandler, PromptBuildResult, PromptContextOptions, PromptContextProvider, ResolvedCliConfig, ResolvedValue, RetryOptions, RunOptions, ServiceAccountFileConfig, ServiceManager, ServiceManagerOptions, ServiceState, SkillFrontmatter, SlackWorkspaceOptions, StatusHandler, StatusHandlerResult, StatusResponse, ToolDescriptor, ToolRegistrationOptions, ToolResult, VersionStamp, WorkspaceConfig, WorkspaceOptions };