principles-disciple 1.202.1 → 1.204.0

package/dist/core/pd-config-loader.d.ts

@@ -1,96 +1,25 @@
-/**
- * PD Config Loader (Plugin I/O boundary) — PRI-307
- *
- * Reads `.pd/config.yaml`, validates via core, computes effective config.
- * Replaces the old `.pd/feature-flags.yaml` and `.state/workflows.yaml` reading
- * for plugin production paths.
- *
- * ADR-0016: PD owns exactly one user config file.
- * - Missing config → defaults with nextAction
- * - Malformed config → fail loud with errors and nextAction
- * - No secrets in output
- * - Observer disabled → no start / no noisy log cycling
- * - Observer enabled + missing setup → structured needs_setup + nextAction
- */
-import type { EffectivePdConfig } from '@principles/core/runtime-v2';
-export declare const PD_CONFIG_DIR = ".pd";
-export declare const PD_CONFIG_FILENAME = "config.yaml";
+import { type PluginConfigLoadResult } from '@principles/host-runtime';
+export { getPdConfigPath, loadFeatureFlagFromConfig, loadPdConfigForPlugin, PD_CONFIG_DIR, PD_CONFIG_FILENAME, } from '@principles/host-runtime';
+export type { PluginConfigLoadResult } from '@principles/host-runtime';
 export type ObserverReadiness = 'disabled' | 'needs_setup' | 'ready' | 'not_ready' | 'config_malformed';
 export interface ObserverConfigResult {
-    /** Whether the observer feature is enabled in config */
     enabled: boolean;
-    /** Observer readiness state */
     readiness: ObserverReadiness;
-    /** Config source: 'defaults' | 'user_config' | 'malformed' */
     source: string;
-    /** Reason for current state */
     reason: string;
-    /** What the user should do next */
     nextAction: string;
-    /** The runtime profile ID for this observer, if configured */
     runtimeProfileId: string | null;
-    /** The runtime profile type, if configured */
     runtimeProfileType: string | null;
-    /** The apiKeyEnv for the runtime profile, if applicable */
     apiKeyEnv: string | null;
-    /** Whether the apiKeyEnv is present in process.env */
     apiKeyPresent: boolean;
-    /** Provider name from runtime profile */
     provider: string | null;
-    /** Model name from runtime profile */
     model: string | null;
-    /** Timeout from runtime profile */
     timeoutMs: number | null;
-    /** Base URL from runtime profile */
     baseUrl: string | null;
-    /** Config validation errors (only present when readiness=config_malformed) */
-    configErrors?: Array<{
-        path: string;
-        reason: string;
-        nextAction: string;
-    }>;
+    configErrors?: PluginConfigLoadResult['errors'];
 }
-export interface PluginConfigLoadResult {
-    ok: boolean;
-    effective: EffectivePdConfig;
-    source: 'defaults' | 'user_config' | 'malformed';
-    configPath: string;
-    warnings: string[];
-    errors: Array<{
-        path: string;
-        reason: string;
-        nextAction: string;
-    }>;
-}
-export declare function getPdConfigPath(workspaceDir: string): string;
-/**
- * Load and validate `.pd/config.yaml` from the workspace.
- * Never throws on malformed input. Always provides a usable fallback.
- */
-export declare function loadPdConfigForPlugin(workspaceDir: string): PluginConfigLoadResult;
-/**
- * Get a single feature flag's enabled state from .pd/config.yaml.
- * Replaces the old `loadFeatureFlagFromWorkspace` which read .pd/feature-flags.yaml.
- */
-export declare function loadFeatureFlagFromConfig(workspaceDir: string, flagId: string, logger?: {
-    warn?: (msg: string) => void;
-    info?: (msg: string) => void;
-}): {
-    enabled: boolean;
-    source: string;
-};
-/**
- * Resolve observer configuration from .pd/config.yaml.
- *
- * Returns structured state:
- * - config_malformed: config file is invalid — no guessing, fail loud
- * - disabled: observer feature flag is off OR agent.enabled=false → no start, no noisy logs
- * - needs_setup: observer enabled but runtime profile missing, API key not set, or unsupported profile type
- * - ready: observer enabled and fully configured (pi-ai with key present)
- * - not_ready: observer enabled, API key present, but runtime availability unknown
- */
 export declare function resolveObserverConfig(workspaceDir: string, observerFlagId: string, observerAgentName: string, _logger?: {
-    warn?: (msg: string) => void;
-    info?: (msg: string) => void;
-    debug?: (msg: string) => void;
+    warn?: (message: string) => void;
+    info?: (message: string) => void;
+    debug?: (message: string) => void;
 }): ObserverConfigResult;

package/dist/hooks/after-tool-call-helpers.d.ts

@@ -44,13 +44,17 @@ export declare function buildToolCallObservation(event: PluginHookAfterToolCallE
  */
 export declare function handleFrictionTrackingForFailure(sessionId: string, event: PluginHookAfterToolCallEvent, outcome: ToolCallOutcome, observation: ToolCallObservation, gfiBefore: number, workspaceDir: string, config: {
     get: (key: string) => unknown;
-}, wctx: WorkspaceContext): SessionState;
+}, wctx: WorkspaceContext, options?: {
+    recordTrajectory?: boolean;
+}): SessionState;
 /**
  * Handle friction relief and recording for a tool success.
  *
  * Relieves both tool_failure and dispatch_error GFI sources proportionally.
  */
-export declare function handleFrictionTrackingForSuccess(sessionId: string, event: PluginHookAfterToolCallEvent, outcome: ToolCallOutcome, observation: ToolCallObservation, gfiBefore: number, workspaceDir: string, wctx: WorkspaceContext): SessionState;
+export declare function handleFrictionTrackingForSuccess(sessionId: string, event: PluginHookAfterToolCallEvent, outcome: ToolCallOutcome, observation: ToolCallObservation, gfiBefore: number, workspaceDir: string, wctx: WorkspaceContext, options?: {
+    recordTrajectory?: boolean;
+}): SessionState;
 /**
  * Record hygiene tracking for memory/plan persistence actions on success.
  */

package/dist/hooks/gate.d.ts

@@ -8,9 +8,38 @@
  * 1. Early Return: Skip if not write/bash/agent tool or no workspace
  * 2. Rule Host: Dynamic principle-based evaluation (sole gate)
  */
+import { WorkspaceContext } from '../core/workspace-context.js';
+import type { RuleContextV2 } from '@principles/core/runtime-v2';
 import type { PluginHookBeforeToolCallEvent, PluginHookToolContext, PluginHookBeforeToolCallResult, PluginLogger } from '../openclaw-sdk.js';
+import type { HostEventResult } from '@principles/core/host';
 export declare function handleBeforeToolCall(event: PluginHookBeforeToolCallEvent, ctx: PluginHookToolContext & {
     workspaceDir?: string;
     pluginConfig?: Record<string, unknown>;
     logger?: Partial<PluginLogger>;
 }): PluginHookBeforeToolCallResult | void;
+export declare function buildOpenClawRuleInputEnrichment(event: PluginHookBeforeToolCallEvent, workspaceDir: string, sessionId: string | undefined): {
+    currentGfi: number;
+    recentThinking: boolean;
+    epTier: number;
+    bashRisk: "dangerous" | "normal" | "safe" | "unknown";
+};
+/**
+ * PRI-483 Phase 4 — Build RuleContextV2 for RuleHost.evaluate when the
+ * `rulecode_context_v2` feature flag is ON. Returns `undefined` when the flag
+ * is OFF (v1 zero-change — does NOT touch trajectory) or when config loading
+ * fails (conservative fail-soft: can't determine flag state → v1-style).
+ *
+ * ERR-024 prevention: context assembly failures never skip RuleHost.evaluate.
+ * - loadPdConfigForPlugin throws → return undefined (v1-style)
+ * - buildProductionRuleContext throws → return UNAVAILABLE_RULE_CONTEXT
+ *   (structured unavailable so v2 rules see "context unavailable" and allow)
+ *
+ * Spec: docs/superpowers/specs/2026-06-27-rulecode-context-vision-design.md §5.3
+ */
+export declare function buildRuleContextIfEnabled(wctx: WorkspaceContext, targetPath: string, sessionId: string | undefined, logger: {
+    warn?: (msg: string) => void;
+} | undefined): RuleContextV2 | undefined;
+export declare function handleSharedRuleHostResult(event: PluginHookBeforeToolCallEvent, ctx: PluginHookToolContext & {
+    workspaceDir: string;
+    logger?: Partial<PluginLogger>;
+}, result: HostEventResult): void;

package/dist/hooks/pain.d.ts

@@ -17,8 +17,17 @@
 import { WorkspaceContext } from '../core/workspace-context.js';
 import type { EvolutionLoopEvent } from '../core/evolution-types.js';
 import type { PluginHookAfterToolCallEvent, PluginHookToolContext, OpenClawPluginApi } from '../openclaw-sdk.js';
+import type { ProductionPainEnrichment } from '@principles/host-runtime';
+import type { HostEventResult } from '@principles/core/host';
 import { buildTrajectoryEvidence } from './trajectory-evidence.js';
 export { buildTrajectoryEvidence };
+/**
+ * Host-owned best-effort continuation after durable shared persistence.
+ * The hook may return once SQLite commits, while rejections remain observable
+ * and tests/shutdown code can explicitly drain scheduled work.
+ */
+export declare function schedulePainContinuation(workspaceDir: string, continuation: Promise<void>): void;
+export declare function drainPainContinuationsForTest(): Promise<void>;
 export declare function emitPainDetectedEvent(wctx: WorkspaceContext, event: EvolutionLoopEvent, options?: {
     recordObservability?: boolean;
 }): Promise<void>;
@@ -33,3 +42,16 @@ export declare function handleAfterToolCall(event: PluginHookAfterToolCallEvent,
     workspaceDir?: string;
     pluginConfig?: Record<string, unknown>;
 }, api?: OpenClawPluginApi): void;
+/**
+ * OpenClaw-owned enrichment for the shared ordinary after-tool kernel.
+ * Session/GFI, event-log, probation, PROFILE and hygiene behavior stays here;
+ * the shared runtime owns classification/admission and the atomic trajectory write.
+ */
+export declare function prepareOrdinaryAfterToolCallForSharedRuntime(event: PluginHookAfterToolCallEvent, ctx: PluginHookToolContext & {
+    workspaceDir: string;
+    pluginConfig?: Record<string, unknown>;
+}): ProductionPainEnrichment;
+/** Restore OpenClaw-owned pain UX/diagnosis after the shared atomic evidence write. */
+export declare function handleSharedPainEvidenceResult(event: PluginHookAfterToolCallEvent, ctx: PluginHookToolContext & {
+    workspaceDir: string;
+}, result: HostEventResult): void;

package/dist/hooks/prompt.d.ts

@@ -1,6 +1,16 @@
-import type { PluginHookBeforePromptBuildEvent, PluginHookAgentContext, PluginHookBeforePromptBuildResult } from '../openclaw-sdk.js';
+import type { PluginHookBeforePromptBuildEvent, PluginHookAgentContext, PluginHookBeforePromptBuildResult, PluginLogger } from '../openclaw-sdk.js';
+import { WorkspaceContext } from '../core/workspace-context.js';
 import type { ContextInjectionConfig } from '../types.js';
+import type { ActivePrinciplePromptResult } from '@principles/host-runtime';
 import type { PromptHookApi } from './prompt-types.js';
+import type { InjectablePrinciple } from '../core/principle-injection.js';
+export interface LegacyPrinciplePromptSelection {
+    active: InjectablePrinciple[];
+    probation: InjectablePrinciple[];
+    content: string;
+    selectedIds: ReadonlySet<string>;
+}
+export declare function selectLegacyPrinciplesForPrompt(workspaceDir: string, reducer: Pick<WorkspaceContext['evolutionReducer'], 'getActivePrinciples' | 'getProbationPrinciples'>, logger?: PluginLogger): LegacyPrinciplePromptSelection;
 /**
  * Reset all module-level prompt state for a workspace.
  * Intended for test isolation — call in beforeEach().
@@ -19,4 +29,4 @@ export declare function resetPromptStateForTest(workspaceDir?: string): void;
 export declare function loadContextInjectionConfig(workspaceDir: string): ContextInjectionConfig;
 export declare function handleBeforePromptBuild(event: PluginHookBeforePromptBuildEvent, ctx: PluginHookAgentContext & {
     api?: PromptHookApi;
-}): Promise<PluginHookBeforePromptBuildResult | void>;
+}, sharedActivePrinciplePrompt?: ActivePrinciplePromptResult, preparedLegacyPrinciples?: LegacyPrinciplePromptSelection): Promise<PluginHookBeforePromptBuildResult | void>;

package/dist/host-runtime/openclaw-host-runtime.d.ts

@@ -0,0 +1,19 @@
+import { type ActivePrinciplePromptResult, type HostRuntime, type ProductionRuleContextRequest, type ProductionPainEnrichment } from '@principles/host-runtime';
+import type { HostEventResult } from '@principles/core/host';
+import type { PluginHookAgentContext, PluginHookAfterToolCallEvent, PluginHookBeforePromptBuildEvent, PluginHookBeforePromptBuildResult, PluginHookBeforeToolCallEvent, PluginHookBeforeToolCallResult, PluginHookToolContext } from '../openclaw-sdk.js';
+export interface OpenClawHostRuntimeOptions {
+    beforePromptBuild(event: PluginHookBeforePromptBuildEvent, context: PluginHookAgentContext, prompt: ActivePrinciplePromptResult): Promise<PluginHookBeforePromptBuildResult | void>;
+    promptExcludePrincipleIds?(event: PluginHookBeforePromptBuildEvent, context: PluginHookAgentContext): ReadonlySet<string>;
+    ruleContextProvider?(event: PluginHookBeforeToolCallEvent, context: PluginHookToolContext, request: ProductionRuleContextRequest): unknown | Promise<unknown>;
+    ruleInputEnrichmentProvider?(event: PluginHookBeforeToolCallEvent, context: PluginHookToolContext, request: ProductionRuleContextRequest): unknown | Promise<unknown>;
+    onBeforeToolResult?(event: PluginHookBeforeToolCallEvent, context: PluginHookToolContext, result: HostEventResult): PluginHookBeforeToolCallResult | void;
+    painEnrichmentProvider?(event: PluginHookAfterToolCallEvent, context: PluginHookToolContext): ProductionPainEnrichment | Promise<ProductionPainEnrichment>;
+    onAfterToolResult?(event: PluginHookAfterToolCallEvent, context: PluginHookToolContext, result: HostEventResult): void | Promise<void>;
+}
+export interface OpenClawHostRuntime {
+    readonly runtime: HostRuntime;
+    dispatchBeforePromptBuild(event: PluginHookBeforePromptBuildEvent, context: PluginHookAgentContext): Promise<PluginHookBeforePromptBuildResult | void>;
+    dispatchBeforeToolCall(event: PluginHookBeforeToolCallEvent, context: PluginHookToolContext): Promise<PluginHookBeforeToolCallResult | void>;
+    dispatchAfterToolCall(event: PluginHookAfterToolCallEvent, context: PluginHookToolContext): Promise<void>;
+}
+export declare function createOpenClawHostRuntime(options: OpenClawHostRuntimeOptions): OpenClawHostRuntime;

package/dist/index.d.ts

@@ -40,6 +40,14 @@ export declare function shouldStartInternalizationAutoConsumer(workspaceDir: str
     info?: (msg: string) => void;
     warn?: (msg: string) => void;
 }): InternalizationAutoConsumerGateResult;
+export declare function shouldUseSharedHostRuntime(workspaceDir: string, logger: {
+    info?: (msg: string) => void;
+    warn?: (msg: string) => void;
+}): {
+    enabled: boolean;
+    source: string;
+    rollbackReason: string | null;
+};
 declare const plugin: {
     name: string;
     description: string;

package/dist/openclaw-sdk.d.ts

@@ -195,14 +195,28 @@ export interface PluginHookBeforePromptBuildResult {
 }
 export interface PluginHookBeforeToolCallEvent {
     toolName: string;
+    /** Host-provided tool call arguments (OpenClaw 2026.7.x sends `params`). */
     params?: Record<string, unknown>;
+    /** @deprecated Host sends `params`; kept for older adapter shims. */
     toolArgs?: Record<string, unknown>;
     agentId?: string;
     sessionId?: string;
     [key: string]: unknown;
 }
 export interface PluginHookBeforeToolCallResult {
+    /**
+     * Host merge contract (OpenClaw 2026.7.x, hook-before-tool-call-result.ts):
+     * only `params`, `block`, `blockReason`, `requireApproval` are read from the
+     * hook result. New code must use these fields.
+     */
+    params?: Record<string, unknown>;
+    block?: boolean;
+    blockReason?: string;
+    /** Shape is host-defined (approval request details). */
+    requireApproval?: unknown;
+    /** @deprecated Use `params`. Host does not read `toolArgs`. */
     toolArgs?: Record<string, unknown>;
+    /** @deprecated Blocking is expressed via `block: true`. Host does not read `skipToolCall`. */
     skipToolCall?: boolean;
     [key: string]: unknown;
 }
@@ -250,15 +264,21 @@ export interface PluginHookSubagentEndedEvent {
     [key: string]: unknown;
 }
 export interface PluginHookLlmOutputEvent {
-    output: string;
+    /**
+     * @deprecated Host (OpenClaw 2026.7.x) does not send `output`. It fires once
+     * per model-loop attempt with `assistantTexts` + `lastAssistant`; read those.
+     */
+    output?: string;
     agentId?: string;
     sessionId?: string;
     runId?: string;
     provider?: string;
     model?: string;
     usage?: TokenUsage;
+    /** Host-provided full assistant texts for this model-loop attempt. */
     assistantTexts?: string[];
     trigger?: string;
+    /** Last complete assistant message object (host-defined shape). */
     lastAssistant?: unknown;
     [key: string]: unknown;
 }
@@ -314,6 +334,8 @@ export interface PluginHookBeforeMessageWriteResult {
         role?: string;
         content?: unknown;
     };
+    /** Host contract: `block: true` prevents the transcript write entirely. */
+    block?: boolean;
     [key: string]: unknown;
 }
 export interface OpenClawPluginHttpRouteParams {

package/dist/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "principles-disciple",
   "name": "Principles Disciple",
   "description": "Turn repeated Agent corrections into Owner-approved, observable, reversible behavior principles. Stop correcting the same AI behavior across sessions.",
-  "version": "1.202.1",
+  "version": "1.204.0",
   "activation": {
     "onCapabilities": [
       "hook"

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "principles-disciple",
   "name": "Principles Disciple",
   "description": "Turn repeated Agent corrections into Owner-approved, observable, reversible behavior principles. Stop correcting the same AI behavior across sessions.",
-  "version": "1.202.1",
+  "version": "1.204.0",
   "activation": {
     "onCapabilities": [
       "hook"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "principles-disciple",
-  "version": "1.202.1",
+  "version": "1.204.0",
   "description": "Turn repeated Agent corrections into Owner-approved, observable, reversible behavior principles. Stop correcting the same AI behavior across sessions.",
   "type": "module",
   "main": "./dist/index.js",
@@ -62,6 +62,7 @@
     "test": "vitest run",
     "test:unit": "vitest run --config vitest.unit.config.ts tests/core tests/service tests/hooks tests/commands tests/utils tests/scripts --exclude tests/commands/evolver.test.ts",
     "test:integration": "vitest run tests/integration/",
+    "test:host-runtime-parity": "vitest run --config vitest.parity.config.ts tests/bdd/openclaw-shared-host-runtime-parity.steps.test.ts tests/package/published-host-runtime-bundle.test.ts",
     "test:coverage": "vitest run --coverage",
     "test:all": "vitest run",
     "lint": "eslint \"src/**/*.ts\"",
@@ -70,6 +71,7 @@
     "sync-plugin": "node scripts/sync-plugin.mjs"
   },
   "devDependencies": {
+    "@principles/host-runtime": "^0.1.0",
     "@types/better-sqlite3": "^9.6.0",
     "@types/js-yaml": "^4.0.9",
     "@types/micromatch": "^4.0.10",