principles-disciple 2.4.0 → 2.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -4,7 +4,7 @@
4
4
  * Extracted functions from handleAfterToolCall that implement
5
5
  * individual pipeline stages. Each function has a focused responsibility.
6
6
  *
7
- * Pipeline order: classify → record → triage → gate → emit
7
+ * Pipeline order: classify → record → hygiene
8
8
  *
9
9
  * ERR checklist:
10
10
  * - ERR-001: No `as` casts on untrusted runtime values.
@@ -16,7 +16,7 @@ import { normalizeProfile } from '../core/profile.js';
16
16
  import { type SessionState } from '../core/session-tracker.js';
17
17
  import { WorkspaceContext } from '../core/workspace-context.js';
18
18
  import type { PluginHookAfterToolCallEvent } from '../openclaw-sdk.js';
19
- import type { ToolCallOutcome, ToolCallObservation, PainAdmissionDecision } from './after-tool-call-types.js';
19
+ import type { ToolCallOutcome, ToolCallObservation } from './after-tool-call-types.js';
20
20
  /**
21
21
  * Extract a preview string from tool call result for diagnostic evidence.
22
22
  * Pure function — no I/O, no side effects. ERR-001 / ERR-014 compliant.
@@ -37,58 +37,18 @@ export declare function classifyToolCallOutcome(event: PluginHookAfterToolCallEv
37
37
  */
38
38
  export declare function buildToolCallObservation(event: PluginHookAfterToolCallEvent, outcome: ToolCallOutcome, workspaceDir: string, profile: ReturnType<typeof normalizeProfile>): ToolCallObservation;
39
39
  /**
40
- * Handle friction tracking for a tool failure.
41
- *
42
- * Updates GFI, records to event log and trajectory.
43
- * Returns the updated session state and friction info.
40
+ * Record a failed tool call and mark session activity.
44
41
  */
45
- export declare function handleFrictionTrackingForFailure(sessionId: string, event: PluginHookAfterToolCallEvent, outcome: ToolCallOutcome, observation: ToolCallObservation, gfiBefore: number, workspaceDir: string, config: {
46
- get: (key: string) => unknown;
47
- }, wctx: WorkspaceContext, options?: {
42
+ export declare function recordToolCallFailure(sessionId: string, event: PluginHookAfterToolCallEvent, outcome: ToolCallOutcome, observation: ToolCallObservation, workspaceDir: string, wctx: WorkspaceContext, options?: {
48
43
  recordTrajectory?: boolean;
49
44
  }): SessionState;
50
45
  /**
51
- * Handle friction relief and recording for a tool success.
52
- *
53
- * Relieves both tool_failure and dispatch_error GFI sources proportionally.
46
+ * Record a successful tool call and mark session activity.
54
47
  */
55
- export declare function handleFrictionTrackingForSuccess(sessionId: string, event: PluginHookAfterToolCallEvent, outcome: ToolCallOutcome, observation: ToolCallObservation, gfiBefore: number, workspaceDir: string, wctx: WorkspaceContext, options?: {
48
+ export declare function recordToolCallSuccess(sessionId: string, event: PluginHookAfterToolCallEvent, outcome: ToolCallOutcome, observation: ToolCallObservation, workspaceDir: string, wctx: WorkspaceContext, options?: {
56
49
  recordTrajectory?: boolean;
57
50
  }): SessionState;
58
51
  /**
59
52
  * Record hygiene tracking for memory/plan persistence actions on success.
60
53
  */
61
54
  export declare function recordHygieneTracking(event: PluginHookAfterToolCallEvent, observation: ToolCallObservation, wctx: WorkspaceContext): void;
62
- /**
63
- * Evaluate whether a tool failure should trigger pain diagnosis.
64
- *
65
- * PRI-363: Single-gate architecture — only TriggerController decides.
66
- *
67
- * Combines:
68
- * 1. Write-tool check — only write tools on failures enter this path
69
- * 2. PEAT-B1 triage — evidence triage (always enabled now)
70
- * 3. PEAT-B2 trigger controller — single source of truth for task creation
71
- * 4. Cooldown tracking — plugin layer owns this state
72
- *
73
- * Returns a structured decision with reason and stage.
74
- */
75
- export declare function evaluatePainAdmissionForToolCall(event: PluginHookAfterToolCallEvent, observation: ToolCallObservation, outcome: ToolCallOutcome, latestFailureState: SessionState | undefined, sessionState: SessionState | undefined, sessionId: string, workspaceDir: string, _config: {
76
- get: (key: string) => unknown;
77
- }): PainAdmissionDecision;
78
- /**
79
- * Emit pain signal after admission.
80
- *
81
- * Records to trajectory, event log, principle value tracker,
82
- * and emits the pain_detected event.
83
- *
84
- * Only called when the admission decision is 'admitted'.
85
- */
86
- export declare function emitPainIfAdmitted(wctx: WorkspaceContext, event: PluginHookAfterToolCallEvent, observation: ToolCallObservation, outcome: ToolCallOutcome, admission: PainAdmissionDecision, sessionId: string, agentId: string | undefined, workspaceDir: string, emitPainDetectedEvent: (wctx: WorkspaceContext, event: import('../core/evolution-types.js').EvolutionLoopEvent, options?: {
87
- recordObservability?: boolean;
88
- }) => Promise<void>): void;
89
- export { buildTrajectoryEvidence } from './trajectory-evidence.js';
90
- /**
91
- * Reset trigger cooldown state (for tests).
92
- * PRI-454: Delegates to shared cooldown Map reset.
93
- */
94
- export declare function resetTriggerCooldownForTest(): void;
@@ -10,7 +10,6 @@
10
10
  * - ERR-002: Every decision/result carries structured reason + nextAction.
11
11
  * - EP-01: These types document boundaries, not runtime validation targets.
12
12
  */
13
- import type { SessionState } from '../core/session-tracker.js';
14
13
  /**
15
14
  * Result of classifying what happened in a tool call event.
16
15
  *
@@ -27,7 +26,7 @@ export interface ToolCallOutcome {
27
26
  /**
28
27
  * Normalized observation built from the tool call event and context.
29
28
  *
30
- * Used by friction tracking, event recording, and pain admission.
29
+ * Used by friction tracking, event log recording, and trajectory recording.
31
30
  * Constructed after classification, before any I/O.
32
31
  */
33
32
  export interface ToolCallObservation {
@@ -51,36 +50,6 @@ export interface ToolCallObservation {
51
50
  readonly errorHash: string;
52
51
  /** Error text for logging */
53
52
  readonly errorText: string;
54
- /** Pain score (only meaningful for write-tool failures on risky paths) */
55
- readonly painScore: number;
56
53
  /** Trace ID for this observation chain */
57
54
  readonly traceId: string;
58
55
  }
59
- /**
60
- * Result of evaluating whether a tool failure should trigger pain diagnosis.
61
- *
62
- * Encapsulates the single-gate trigger controller decision.
63
- */
64
- export interface PainAdmissionDecision {
65
- /** Whether the tool failure should proceed to pain emission */
66
- readonly admitted: boolean;
67
- /** The admission stage that made the decision */
68
- readonly stage: 'not_applicable' | 'trigger_admitted' | 'trigger_rejected';
69
- /** Human-readable reason for the decision */
70
- readonly reason: string;
71
- /** Detail about the decision */
72
- readonly detail: string;
73
- }
74
- /**
75
- * Result of friction tracking for a tool call.
76
- */
77
- export interface FrictionUpdateResult {
78
- /** GFI before this update */
79
- readonly gfiBefore: number;
80
- /** GFI after this update */
81
- readonly gfiAfter: number;
82
- /** Updated session state (if failure) */
83
- readonly sessionState: SessionState | undefined;
84
- /** The error hash used for tracking */
85
- readonly errorHash: string;
86
- }
@@ -54,7 +54,7 @@ export declare function persistGateBlock(wctx: WorkspaceContext, blockCtx: Block
54
54
  * Single authoritative block helper.
55
55
  *
56
56
  * Responsibilities:
57
- * 1. Call trackBlock() for session-level GFI tracking
57
+ * 1. Call trackBlock() for the session block tally
58
58
  * 2. Record to EventLog for operator visibility
59
59
  * 3. Record to trajectory for analytics
60
60
  * 4. Handle retry logic for trajectory persistence failures
@@ -17,8 +17,7 @@ export declare function handleBeforeToolCall(event: PluginHookBeforeToolCallEven
17
17
  pluginConfig?: Record<string, unknown>;
18
18
  logger?: Partial<PluginLogger>;
19
19
  }): PluginHookBeforeToolCallResult | void;
20
- export declare function buildOpenClawRuleInputEnrichment(event: PluginHookBeforeToolCallEvent, workspaceDir: string, sessionId: string | undefined): {
21
- currentGfi: number;
20
+ export declare function buildOpenClawRuleInputEnrichment(event: PluginHookBeforeToolCallEvent): {
22
21
  epTier: number;
23
22
  bashRisk: "dangerous" | "normal" | "safe" | "unknown";
24
23
  };
@@ -47,8 +46,8 @@ export declare function handleSharedRuleHostResult(event: PluginHookBeforeToolCa
47
46
  *
48
47
  * Both shared-handler deny branches (resolvable and unresolved target path)
49
48
  * funnel here: receipt-ledger effect row (flag-gated, failure-degrading —
50
- * parity with the legacy hook path) plus persistGateBlock (session GFI,
51
- * EventLog gate_block, trajectory gate_blocks with bounded retry). A null
49
+ * parity with the legacy hook path) plus persistGateBlock (session block
50
+ * tally, EventLog gate_block, trajectory gate_blocks with bounded retry). A null
52
51
  * filePath is accounted with a null trajectory file_path; the EventLog copy
53
52
  * carries an '<unresolved>' placeholder. Never throws into the caller;
54
53
  * every skip/failure warns with a reasonCode (rc-9).
@@ -1,32 +1,23 @@
1
1
  /**
2
2
  * Pain Hook — PRI-326 decomposed
3
3
  *
4
- * After-tool-call hook that captures tool failures and emits pain signals.
4
+ * After-tool-call hook. Phase A retired every automatic Pain admission that
5
+ * was triggered by a technical tool failure: failures are still classified,
6
+ * recorded in the trajectory, and recorded as events, but they never create
7
+ * a Pain Event or a Diagnostician task by themselves.
5
8
  *
6
- * Pipeline stages (delegated to after-tool-call-helpers):
9
+ * Remaining stages (delegated to after-tool-call-helpers):
7
10
  * 1. classifyToolCallOutcome — determine failure/success + source
8
11
  * 2. buildToolCallObservation — normalize event into observation
9
- * 3. handleFrictionTracking — GFI, event log, trajectory recording
10
- * 4. evaluatePainAdmission — triage + gate evaluation
11
- * 5. emitPainIfAdmitted — pain signal emission
12
+ * 3. recordToolCallFailure/Success — event log + trajectory recording
12
13
  *
13
14
  * The manual pain path (toolName === 'pain') remains inline because it
14
- * has a different control flow (early return, no triage, no gate on cooldown).
15
+ * has a different control flow (early return, Owner-explicit admission).
15
16
  */
16
17
  import { WorkspaceContext } from '../core/workspace-context.js';
17
18
  import type { EvolutionLoopEvent } from '../core/evolution-types.js';
18
19
  import type { PluginHookAfterToolCallEvent, PluginHookToolContext, OpenClawPluginApi } from '../openclaw-sdk.js';
19
20
  import type { ProductionPainEnrichment } from '@principles/host-runtime';
20
- import type { HostEventResult } from '@principles/core/host';
21
- import { buildTrajectoryEvidence } from './trajectory-evidence.js';
22
- export { buildTrajectoryEvidence };
23
- /**
24
- * Host-owned best-effort continuation after durable shared persistence.
25
- * The hook may return once SQLite commits, while rejections remain observable
26
- * and tests/shutdown code can explicitly drain scheduled work.
27
- */
28
- export declare function schedulePainContinuation(workspaceDir: string, continuation: Promise<void>): void;
29
- export declare function drainPainContinuationsForTest(): Promise<void>;
30
21
  export declare function emitPainDetectedEvent(wctx: WorkspaceContext, event: EvolutionLoopEvent, options?: {
31
22
  recordObservability?: boolean;
32
23
  }): Promise<void>;
@@ -43,14 +34,10 @@ export declare function handleAfterToolCall(event: PluginHookAfterToolCallEvent,
43
34
  }, api?: OpenClawPluginApi): void;
44
35
  /**
45
36
  * OpenClaw-owned enrichment for the shared ordinary after-tool kernel.
46
- * Session/GFI, event-log, PROFILE and hygiene behavior stays here;
37
+ * Session/event-log, PROFILE and hygiene behavior stays here;
47
38
  * the shared runtime owns classification/admission and the atomic trajectory write.
48
39
  */
49
40
  export declare function prepareOrdinaryAfterToolCallForSharedRuntime(event: PluginHookAfterToolCallEvent, ctx: PluginHookToolContext & {
50
41
  workspaceDir: string;
51
42
  pluginConfig?: Record<string, unknown>;
52
43
  }): ProductionPainEnrichment;
53
- /** Restore OpenClaw-owned pain UX/diagnosis after the shared atomic evidence write. */
54
- export declare function handleSharedPainEvidenceResult(event: PluginHookAfterToolCallEvent, ctx: PluginHookToolContext & {
55
- workspaceDir: string;
56
- }, result: HostEventResult): void;
@@ -7,10 +7,9 @@
7
7
  * Pure data extraction — reads from trajectory DB, sanitizes, returns evidence entries.
8
8
  *
9
9
  * PRI-642 Scope A adds the typed acquisition API `acquireTrajectoryEvidence`
10
- * (discriminated available/unavailable, SPEC §7.2). The legacy array API
11
- * `buildTrajectoryEvidence` remains as a compatibility wrapper for automatic
12
- * emitters and MUST keep its exact sentinel shapes until Scope B migrates
13
- * those consumers (frozen decision #3).
10
+ * (discriminated available/unavailable, SPEC §7.2). Phase A retired the last
11
+ * automatic emitter, so the legacy untyped array wrapper was removed: the
12
+ * Owner manual pain path is the only consumer and it uses the typed API.
14
13
  */
15
14
  import type { PainEvidenceEntry } from '@principles/core/runtime-v2';
16
15
  import type { WorkspaceContext } from '../core/workspace-context.js';
@@ -34,9 +33,3 @@ export type TrajectoryEvidenceAcquisition = {
34
33
  * as available evidence.
35
34
  */
36
35
  export declare function acquireTrajectoryEvidence(wctx: WorkspaceContext, sessionId: string): TrajectoryEvidenceAcquisition;
37
- /**
38
- * Legacy array API (compatibility wrapper, PRI-642 frozen decision #3).
39
- * Automatic emitters still consume this shape; Scope B migrates them to the
40
- * typed API one family at a time before this wrapper may be removed.
41
- */
42
- export declare function buildTrajectoryEvidence(wctx: WorkspaceContext, sessionId: string): PainEvidenceEntry[];
@@ -14,6 +14,10 @@
14
14
  * (TriggerController) is the only admission authority.
15
15
  * Core only sees SourceKind and TriageResult.
16
16
  *
17
+ * Phase A: the context-driven upgrade flags (unsafe-high-confidence,
18
+ * risky-high-score, repeated-failure) are retired. A descriptor decision is
19
+ * final; technical failures and RuleHost blocks never self-admit as Pain.
20
+ *
17
21
  * ERR checklist:
18
22
  * - ERR-001: Source kind derived from runtime values with guards, not `as` casts.
19
23
  * - ERR-002: Every triage result carries reason + nextAction.
@@ -30,30 +34,13 @@ import { type TriageResult, type SourceKind } from '@principles/core/runtime-v2'
30
34
  */
31
35
  export { resolveSourceKind, buildToolFailureObservation, type RawObservation } from './raw-observation-adapter.js';
32
36
  /**
33
- * Evaluate evidence triage for a given source kind and context.
37
+ * Evaluate evidence triage for a given source kind and score.
34
38
  *
35
39
  * This is the main entry point for hooks. It calls the pure triage policy
36
- * from principles-core and returns the result.
40
+ * from principles-core and returns the descriptor decision unchanged.
37
41
  *
38
42
  * PRI-752 reality check: the painEvidenceAdmission flag is NOT consulted by
39
43
  * any caller on this path — Gate B admission is unconditional. This doc block
40
44
  * previously described a flag check / fallback that does not exist as code.
41
45
  */
42
- export declare function evaluateEvidenceTriage(sourceKind: SourceKind, score: number, options?: {
43
- isUnsafeHighConfidence?: boolean;
44
- provenance?: 'host_context_bound' | 'owner_reported_no_host_trace' | 'automatic_hook';
45
- consecutiveErrors?: number;
46
- isRisky?: boolean;
47
- }): TriageResult;
48
- /**
49
- * Determine if a gate-blocked action is a high-confidence unsafe action.
50
- *
51
- * This is a heuristic that the plugin adapter owns. Core does not know about
52
- * these heuristics — it only receives the boolean flag.
53
- *
54
- * Criteria for high-confidence unsafe:
55
- * - Score >= 70 (high severity)
56
- * - Tool is in the risky write set
57
- * - Action would be irreversible (file deletion, force push, etc.)
58
- */
59
- export declare function isHighConfidenceUnsafeAction(score: number, isRisky: boolean): boolean;
46
+ export declare function evaluateEvidenceTriage(sourceKind: SourceKind, score: number): TriageResult;
@@ -7,7 +7,6 @@ export interface OpenClawHostRuntimeOptions {
7
7
  ruleInputEnrichmentProvider?(event: PluginHookBeforeToolCallEvent, context: PluginHookToolContext, request: ProductionRuleContextRequest): unknown | Promise<unknown>;
8
8
  onBeforeToolResult?(event: PluginHookBeforeToolCallEvent, context: PluginHookToolContext, result: HostEventResult): PluginHookBeforeToolCallResult | void;
9
9
  painEnrichmentProvider?(event: PluginHookAfterToolCallEvent, context: PluginHookToolContext): ProductionPainEnrichment | Promise<ProductionPainEnrichment>;
10
- onAfterToolResult?(event: PluginHookAfterToolCallEvent, context: PluginHookToolContext, result: HostEventResult): void | Promise<void>;
11
10
  }
12
11
  export interface OpenClawHostRuntime {
13
12
  readonly runtime: HostRuntime;
@@ -2,7 +2,7 @@
2
2
  "id": "principles-disciple",
3
3
  "name": "Principles Disciple",
4
4
  "description": "Principles Disciple is an AI Agent Governance System. Stop correcting the same AI behavior across sessions. Turn repeated Agent corrections into Owner-approved, observable, reversible behavior principles.",
5
- "version": "2.4.0",
5
+ "version": "2.6.0",
6
6
  "activation": {
7
7
  "onStartup": true,
8
8
  "onCapabilities": [