create-principles-disciple 1.80.0 → 1.82.0

package/plugin/dist/core/surface-guard.js

@@ -1,4 +1,42 @@
 import { PLUGIN_SURFACE_REGISTRY, validateSurfaceRegistry, getSurfacesByCategory, } from '@principles/core/runtime-v2';
+// Surface-level once-only log state (PRI-298).
+// The first time a quiet/non-core surface guard actually fires in this
+// process, the disabled reason is emitted once. Subsequent fires for the
+// same surfaceId are still observable (the no-op handler preserves
+// behaviour) but no longer flood the log. Fresh processes start with an
+// empty set, so each plugin load gets one observable skip per surface.
+//
+// The Set is only updated when the log was actually emitted, so passing
+// `undefined` for the logger on a quiet first fire does NOT consume the
+// one-shot slot — a later registration that supplies a logger still gets
+// the first-fire reason (PRI-298 / ERR-002).
+const loggedSkipSurfaces = new Set();
+/**
+ * Emit the disabled-reason log line for `surfaceId` at most once per
+ * process. Returns true if the log was emitted, false if it was suppressed
+ * (already logged, or no logger available). Only marks the surface as
+ * logged when the log was actually written, so a missing logger on first
+ * call does not consume the one-shot slot.
+ */
+function logSkipOnce(surfaceId, logger, message) {
+    if (loggedSkipSurfaces.has(surfaceId)) {
+        return false;
+    }
+    if (!logger?.info) {
+        return false;
+    }
+    loggedSkipSurfaces.add(surfaceId);
+    logger.info(message);
+    return true;
+}
+/**
+ * Reset the per-process surface-guard skip log bookkeeping. Intended for tests
+ * that need to assert on the first-fire log without cross-test pollution.
+ * Not part of the production API surface; do not call from runtime code.
+ */
+export function __resetSurfaceGuardSkipLogStateForTests() {
+    loggedSkipSurfaces.clear();
+}
 export function checkSurfaceGuard() {
     const validation = validateSurfaceRegistry(PLUGIN_SURFACE_REGISTRY);
     const violations = [];
@@ -65,8 +103,15 @@ export function guardHook(surfaceId, logger, handler) {
         return handler;
     }
     const reason = check.reason ?? 'surface not enabled';
+    // Log on the first ACTUAL no-op invocation, not at construction time
+    // (PRI-298). Construction-time logging would emit a `SKIP` line at
+    // plugin startup for every registered quiet hook, regardless of
+    // whether the hook ever fires — which is exactly the startup log
+    // noise this change is meant to prevent. The one-shot is consumed only
+    // when the log was actually written, so `undefined` logger on first
+    // call does not eat the slot.
     return (_event, _ctx) => {
-        logger?.info?.(`[PD:surface-guard] SKIP ${surfaceId}: ${reason}`);
+        logSkipOnce(surfaceId, logger, `[PD:surface-guard] SKIP ${surfaceId}: ${reason}`);
         return undefined;
     };
 }
@@ -76,7 +121,11 @@ export function guardService(surfaceId, service, logger) {
         return service;
     }
     const reason = check.reason ?? 'surface not enabled';
-    logger?.info?.(`[PD:surface-guard] SKIP service ${surfaceId}: ${reason}`);
+    // guardService is called once per service during plugin registration,
+    // so the once-only check fires on the registration call itself. The
+    // shared helper makes the consumption rule identical to guardHook:
+    // a missing logger on first call does not consume the one-shot.
+    logSkipOnce(surfaceId, logger, `[PD:surface-guard] SKIP service ${surfaceId}: ${reason}`);
     return null;
 }
 export { PLUGIN_SURFACE_REGISTRY, validateSurfaceRegistry, getSurfacesByCategory };

package/plugin/dist/hooks/gate.js

@@ -316,6 +316,9 @@ export function handleBeforeToolCall(event, ctx) {
 // ---------------------------------------------------------------------------
 function _extractParamsSummary(params) {
     const summary = {};
+    // NOTE: Do NOT redact here — this feeds into RuleHost.evaluate() which
+    // may match against paramsSummary.command. Redaction happens at
+    // EventLog.record() before persistence.
     if (params.file_path)
         summary.file_path = params.file_path;
     if (params.path)

package/plugin/dist/index.d.ts

@@ -1,5 +1,9 @@
 import type { OpenClawPluginApi } from './openclaw-sdk.js';
 declare function isRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * PRI-305/PRI-307: Load feature flag from .pd/config.yaml instead of .pd/feature-flags.yaml.
+ * Delegates to the shared plugin config loader for consistency.
+ */
 declare function loadFeatureFlagFromWorkspace(workspaceDir: string, flagId: string, logger?: {
     warn?: (msg: string) => void;
     info?: (msg: string) => void;

package/plugin/dist/index.js

@@ -1,7 +1,5 @@
 import * as path from 'path';
-import * as fs from 'fs';
-import * as yaml from 'js-yaml';
-import { computeEffectiveFlags, DEFAULT_FEATURE_FLAGS } from '@principles/core/runtime-v2';
+import { loadFeatureFlagFromConfig } from './core/pd-config-loader.js';
 import { classifyTask } from './core/local-worker-routing.js';
 import { completeShadowObservation, recordShadowRouting } from './core/shadow-observation-registry.js';
 import { getCommandDescription } from './i18n/commands.js';
@@ -52,57 +50,15 @@ const pendingShadowObservations = new Map();
 // ── Feature Flag Loader (plugin I/O boundary) ─────────────────────────────
 // Reads workspace feature-flags.yaml and checks a specific flag.
 // Returns the flag definition with effective enabled state.
-const DANGEROUS_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
 function isRecord(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
+/**
+ * PRI-305/PRI-307: Load feature flag from .pd/config.yaml instead of .pd/feature-flags.yaml.
+ * Delegates to the shared plugin config loader for consistency.
+ */
 function loadFeatureFlagFromWorkspace(workspaceDir, flagId, logger) {
-    const configPath = path.join(workspaceDir, '.pd', 'feature-flags.yaml');
-    if (!fs.existsSync(configPath)) {
-        const flags = computeEffectiveFlags({}, DEFAULT_FEATURE_FLAGS, configPath);
-        const flag = flags.flags[flagId];
-        return { enabled: flag?.enabled ?? false, source: 'defaults' };
-    }
-    let raw;
-    try {
-        raw = fs.readFileSync(configPath, 'utf8');
-    }
-    catch (e) {
-        const msg = e instanceof Error ? e.message : String(e);
-        logger?.warn?.(`[PD:FeatureFlags] Feature flags unreadable: ${msg} — using defaults`);
-        const flags = computeEffectiveFlags({}, DEFAULT_FEATURE_FLAGS, configPath);
-        const flag = flags.flags[flagId];
-        return { enabled: flag?.enabled ?? false, source: 'defaults' };
-    }
-    let parsed;
-    try {
-        parsed = yaml.load(raw, { schema: yaml.JSON_SCHEMA });
-    }
-    catch (e) {
-        const parseMsg = e instanceof Error ? e.message : String(e);
-        logger?.warn?.(`[PD:FeatureFlags] Feature flags YAML parse error: ${parseMsg} — using defaults`);
-        const flags = computeEffectiveFlags({}, DEFAULT_FEATURE_FLAGS, configPath);
-        const flag = flags.flags[flagId];
-        return { enabled: flag?.enabled ?? false, source: 'defaults' };
-    }
-    if (!isRecord(parsed)) {
-        logger?.warn?.(`[PD:FeatureFlags] Feature flags not a mapping — using defaults`);
-        const flags = computeEffectiveFlags({}, DEFAULT_FEATURE_FLAGS, configPath);
-        const flag = flags.flags[flagId];
-        return { enabled: flag?.enabled ?? false, source: 'defaults' };
-    }
-    // parsed is now narrowed to Record<string, unknown> by isRecord guard
-    const parsedRecord = Object.create(null);
-    for (const key of Object.keys(parsed)) {
-        if (DANGEROUS_KEYS.has(key))
-            continue;
-        if (Object.hasOwn(parsed, key)) {
-            parsedRecord[key] = parsed[key];
-        }
-    }
-    const flags = computeEffectiveFlags(parsedRecord, DEFAULT_FEATURE_FLAGS, configPath);
-    const flag = flags.flags[flagId];
-    return { enabled: flag?.enabled ?? false, source: flags.source };
+    return loadFeatureFlagFromConfig(workspaceDir, flagId, logger);
 }
 export function shouldStartEvolutionWorker(workspaceDir, logger) {
     const flag = loadFeatureFlagFromWorkspace(workspaceDir, 'evolution_worker', logger);
@@ -111,7 +67,7 @@ export function shouldStartEvolutionWorker(workspaceDir, logger) {
     }
     const disabledInfo = JSON.stringify({
         reason: 'mvp_quiet_per_adr0014',
-        nextAction: 'set evolution_worker.enabled=true in .pd/feature-flags.yaml to enable',
+        nextAction: 'set features.evolution_worker.enabled=true in .pd/config.yaml to enable',
         featureFlag: 'evolution_worker',
         boundedContext: 'legacy_evolution_worker',
         flagSource: flag.source,
@@ -125,7 +81,7 @@ export function shouldStartCorrectionObserver(workspaceDir, logger) {
     }
     const disabledInfo = JSON.stringify({
         reason: 'correction_observer_disabled',
-        nextAction: 'set correction_observer.enabled=true in .pd/feature-flags.yaml to enable',
+        nextAction: 'set features.correction_observer.enabled=true in .pd/config.yaml to enable',
         featureFlag: 'correction_observer',
         boundedContext: 'correction_observer_service',
         flagSource: flag.source,

package/plugin/dist/service/correction-observer-service.d.ts

@@ -6,6 +6,14 @@ export interface CorrectionObserverServiceShape {
     start: (ctx: OpenClawPluginServiceContext) => void;
     stop?: (ctx: OpenClawPluginServiceContext) => void;
 }
+/**
+ * PRI-307: Resolve CorrectionObserver from .pd/config.yaml.
+ *
+ * States:
+ * - disabled: feature flag off → return null, no noisy logs
+ * - needs_setup: enabled but missing API key or profile → return null with structured reason
+ * - ready/not_ready: enabled and configured → return observer instance
+ */
 export declare function resolveCorrectionObserver(wctx: WorkspaceContext, logger?: Pick<PluginLogger, 'info' | 'warn' | 'error' | 'debug'>): CorrectionObserver | null;
 export declare function runCorrectionObserverCycle(wctx: WorkspaceContext, logger: PluginLogger): Promise<void>;
 export declare const CorrectionObserverService: CorrectionObserverServiceShape;

package/plugin/dist/service/correction-observer-service.js

@@ -1,9 +1,10 @@
 import { WorkspaceContext } from '../core/workspace-context.js';
 import { TrajectoryRegistry } from '../core/trajectory.js';
 import { CorrectionCueLearner } from '../core/correction-cue-learner.js';
-import { WorkflowFunnelLoader, PiAiRuntimeAdapter, CorrectionObserver, AgentScheduler, } from '@principles/core/runtime-v2';
+import { PiAiRuntimeAdapter, CorrectionObserver, AgentScheduler, } from '@principles/core/runtime-v2';
 import { KeywordOptimizationService } from './keyword-optimization-service.js';
 import { SystemLogger } from '../core/system-logger.js';
+import { resolveObserverConfig } from '../core/pd-config-loader.js';
 let correctionObserverTimeoutId = null;
 let correctionObserverStopped = false;
 const startedWorkspaces = new Set();
@@ -11,40 +12,45 @@ const CORRECTION_OBSERVER_INTERVAL_MS = 15 * 60 * 1000;
 const CORRECTION_OBSERVER_INITIAL_DELAY_MS = 10_000;
 const CORRECTION_OBSERVER_MAX_RECENT_SESSIONS = 20;
 const CORRECTION_OBSERVER_MAX_PAYLOAD_SESSIONS = 5;
+/**
+ * PRI-307: Resolve CorrectionObserver from .pd/config.yaml.
+ *
+ * States:
+ * - disabled: feature flag off → return null, no noisy logs
+ * - needs_setup: enabled but missing API key or profile → return null with structured reason
+ * - ready/not_ready: enabled and configured → return observer instance
+ */
 export function resolveCorrectionObserver(wctx, logger) {
     try {
-        const loader = new WorkflowFunnelLoader(wctx.stateDir);
-        const funnel = loader.getFunnel('pd-correction-observer');
-        const policy = funnel?.policy;
-        if (!policy || policy.runtimeKind !== 'pi-ai') {
-            logger?.debug?.('[PD:CorrectionObserver] workflows.yaml pd-correction-observer policy not found. Falling back to environment variables.');
-            const provider = process.env.PD_CORRECTION_PROVIDER || 'anthropic';
-            const model = process.env.PD_CORRECTION_MODEL || 'anthropic/claude-3-5-sonnet';
-            const apiKeyEnv = process.env.PD_CORRECTION_API_KEY_ENV || 'ANTHROPIC_API_KEY';
-            const baseUrl = process.env.PD_CORRECTION_BASE_URL;
-            if (!process.env[apiKeyEnv]) {
-                logger?.debug?.(`[PD:CorrectionObserver] API key env ${apiKeyEnv} is not set. Periodic optimization disabled.`);
-                return null;
+        const observerConfig = resolveObserverConfig(wctx.workspaceDir, 'correction_observer', 'correctionObserver', logger);
+        if (!observerConfig.enabled) {
+            if (observerConfig.readiness === 'config_malformed') {
+                logger?.warn?.(`[PD:CorrectionObserver] Config malformed: ${observerConfig.reason}. ${observerConfig.nextAction}`);
             }
+            else {
+                logger?.debug?.(`[PD:CorrectionObserver] ${observerConfig.reason}`);
+            }
+            return null;
+        }
+        if (observerConfig.readiness === 'needs_setup') {
+            logger?.info?.(`[PD:CorrectionObserver] ${observerConfig.reason}. ${observerConfig.nextAction}`);
+            return null;
+        }
+        // ready or not_ready — create the observer
+        if (observerConfig.runtimeProfileType === 'pi-ai') {
             const adapter = new PiAiRuntimeAdapter({
-                provider,
-                model,
-                apiKeyEnv,
-                baseUrl,
+                provider: observerConfig.provider ?? 'anthropic',
+                model: observerConfig.model ?? 'anthropic/claude-3-5-sonnet',
+                apiKeyEnv: observerConfig.apiKeyEnv ?? 'ANTHROPIC_API_KEY',
+                timeoutMs: observerConfig.timeoutMs ?? undefined,
+                baseUrl: observerConfig.baseUrl ?? undefined,
                 workspace: wctx.workspaceDir,
             });
-            return new CorrectionObserver({ runtimeAdapter: adapter });
+            return new CorrectionObserver({ runtimeAdapter: adapter }, { timeoutMs: observerConfig.timeoutMs ?? undefined });
         }
-        const adapter = new PiAiRuntimeAdapter({
-            provider: String(policy.provider),
-            model: String(policy.model),
-            apiKeyEnv: String(policy.apiKeyEnv),
-            maxRetries: policy.maxRetries,
-            timeoutMs: policy.timeoutMs ?? 30_000,
-            baseUrl: policy.baseUrl,
-            workspace: wctx.workspaceDir,
-        });
-        return new CorrectionObserver({ runtimeAdapter: adapter }, { timeoutMs: policy.timeoutMs });
+        // OpenClaw profile — not yet supported for observer runtime
+        logger?.info?.(`[PD:CorrectionObserver] OpenClaw runtime profile not yet supported for correction observer. Skipping.`);
+        return null;
     }
     catch (err) {
         logger?.warn?.(`[PD:CorrectionObserver] Failed to resolve CorrectionObserver: ${String(err)}`);
@@ -55,7 +61,8 @@ export async function runCorrectionObserverCycle(wctx, logger) {
     try {
         const observer = resolveCorrectionObserver(wctx, logger);
         if (!observer) {
-            logger?.info?.('[PD:CorrectionObserver] Observer not resolved (no API key or config). Skipping cycle.');
+            // PRI-307: No noisy "no API key" cycling. Only log at debug level.
+            logger?.debug?.(`[PD:CorrectionObserver] Observer not resolved. Skipping cycle.`);
             return;
         }
         logger?.info?.('[PD:CorrectionObserver] Observer resolved. Initiating periodic optimization...');
@@ -135,6 +142,18 @@ export const CorrectionObserverService = {
                 logger.info(`[PD:CorrectionObserver] Already started for workspace: ${workspaceDir}. Skipping duplicate start.`);
             return;
         }
+        // PRI-307: Check observer config before starting
+        const observerConfig = resolveObserverConfig(workspaceDir, 'correction_observer', 'correctionObserver', logger);
+        if (!observerConfig.enabled) {
+            // Disabled → no start, no noisy cycling. Single structured log.
+            logger?.info?.(`[PD:CorrectionObserver] ${observerConfig.reason}. ${observerConfig.nextAction}`);
+            return;
+        }
+        if (observerConfig.readiness === 'needs_setup') {
+            // Enabled but missing setup → structured needs_setup, no noisy cycling
+            logger?.info?.(`[PD:CorrectionObserver] ${observerConfig.reason}. ${observerConfig.nextAction}`);
+            return;
+        }
         startedWorkspaces.add(workspaceDir);
         correctionObserverStopped = false;
         const wctx = WorkspaceContext.fromHookContext({ workspaceDir, ...ctx.config });