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.
- package/dist/bundle.js +504 -494
- package/dist/config/defaults/runtime.d.ts +0 -4
- package/dist/core/config.d.ts +0 -35
- package/dist/core/pain.d.ts +0 -1
- package/dist/core/session-tracker.d.ts +3 -51
- package/dist/core/signal-collector-host.d.ts +5 -13
- package/dist/core/signal-keyword-store.d.ts +2 -2
- package/dist/core/trajectory.d.ts +0 -2
- package/dist/governance-audit.js +2 -2
- package/dist/hooks/after-tool-call-helpers.d.ts +6 -46
- package/dist/hooks/after-tool-call-types.d.ts +1 -32
- package/dist/hooks/gate-block-helper.d.ts +1 -1
- package/dist/hooks/gate.d.ts +3 -4
- package/dist/hooks/pain.d.ts +8 -21
- package/dist/hooks/trajectory-evidence.d.ts +3 -10
- package/dist/hooks/triage-adapter.d.ts +7 -20
- package/dist/host-runtime/openclaw-host-runtime.d.ts +0 -1
- package/dist/openclaw.plugin.json +1 -1
- package/dist/rulehost-evidence.js +45 -45
- package/dist/templates/pain_settings.json +0 -46
- package/dist/types/event-types.d.ts +1 -1
- package/openclaw.plugin.json +1 -1
- package/package.json +4 -4
- package/templates/pain_settings.json +0 -46
|
@@ -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 →
|
|
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
|
|
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
|
-
*
|
|
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
|
|
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
|
-
*
|
|
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
|
|
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
|
|
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
|
|
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
|
package/dist/hooks/gate.d.ts
CHANGED
|
@@ -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
|
|
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
|
|
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).
|
package/dist/hooks/pain.d.ts
CHANGED
|
@@ -1,32 +1,23 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Pain Hook — PRI-326 decomposed
|
|
3
3
|
*
|
|
4
|
-
* After-tool-call hook
|
|
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
|
-
*
|
|
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.
|
|
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,
|
|
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/
|
|
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).
|
|
11
|
-
*
|
|
12
|
-
*
|
|
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
|
|
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
|
|
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
|
|
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.
|
|
5
|
+
"version": "2.6.0",
|
|
6
6
|
"activation": {
|
|
7
7
|
"onStartup": true,
|
|
8
8
|
"onCapabilities": [
|