principles-disciple 4.1.1 → 4.1.3

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.
@@ -29,6 +29,19 @@
29
29
  *
30
30
  * Fail loud at module load if the derived declaration is invalid — a broken
31
31
  * static declaration is a programming error, not a runtime condition (rc-3).
32
+ *
33
+ * OG-4 DELIBERATE OMISSION (2026-11-13): `pd_submit_pain` (the shared MCP
34
+ * write tool) is NOT declared here. Two independent reasons, both required by
35
+ * this file's own contract:
36
+ * 1. DISPATCHABILITY — `hooks/gate.ts:363-366` only enters the RuleHost for
37
+ * `WRITE_TOOLS | BASH_TOOLS_SET | AGENT_TOOLS`; the MCP tool is in none
38
+ * of them, so declaring it would make `hasHostTool` true for a name no
39
+ * rule can ever fire on (the exact PRI-741 failure this list fixes).
40
+ * 2. SEMANTICS — `CanonicalKind` is a file-mutation axis. `write` feeds
41
+ * `computeBehaviorFacts.writeCount` and disables the `'other' ⇒ facts
42
+ * incomplete` conservative guard, but the MCP payload carries no target
43
+ * path. It stays `'other'` (conservative) until the enum grows a
44
+ * non-file mutation kind AND the gate routes it.
32
45
  */
33
46
  import { type ToolSemanticMappingV1, type ToolSemanticRegistry } from '@principles/core/runtime/internalization/tool-semantic-registry';
34
47
  export declare const OPENCLAW_TOOL_SEMANTIC_MAPPINGS: readonly ToolSemanticMappingV1[];
@@ -0,0 +1,40 @@
1
+ /**
2
+ * Correction → assistant-turn anchoring.
3
+ *
4
+ * A user correction must point at the turn the user is actually objecting to.
5
+ * "The most recent assistant turn" is only correct when the correction lands
6
+ * directly on the offending answer. The failure this module exists for is the
7
+ * cross-turn case:
8
+ *
9
+ * T1 assistant edits a config without evidence ← the real error
10
+ * T2 user asks "why did you touch it?"
11
+ * T3 assistant explains / apologises ← most recent turn
12
+ * T4 user: "不对,你刚才没有任何实测依据就修改了参数。"
13
+ *
14
+ * Anchoring T4 to the T3 explanation attaches the Pain to words the Owner was
15
+ * not objecting to, and the Diagnostician reasons about the wrong turn. Round 3
16
+ * observed exactly this: the correction referenced the explanation turn.
17
+ *
18
+ * Policy (round-3 brief: prefer an exact reference, never pretend the most
19
+ * recent turn is the target, allow a structured `unresolved`):
20
+ * 1. no back-reference → the latest assistant turn IS the target;
21
+ * 2. back-reference → anchor to the most recent assistant turn that actually
22
+ * EXECUTED something (write-type tool call, from runtime evidence);
23
+ * 3. back-reference with no such turn → unresolved (null), never fabricated.
24
+ */
25
+ export interface AnchoredAssistantTurn {
26
+ readonly id: number;
27
+ readonly text?: string;
28
+ readonly createdAt?: string;
29
+ }
30
+ export interface AnchoredToolCall {
31
+ readonly toolName: string;
32
+ readonly createdAt: string;
33
+ }
34
+ export type CorrectionAnchorReason = 'latest_turn' | 'back_reference_tool_evidence' | 'unresolved_back_reference' | 'unresolved_missing_turn_timestamp' | 'no_assistant_turn';
35
+ export interface CorrectionAnchorResult {
36
+ readonly turnId: number | null;
37
+ readonly reason: CorrectionAnchorReason;
38
+ }
39
+ export declare function hasBackReference(userMessage: string): boolean;
40
+ export declare function resolveCorrectionAnchor(userMessage: string, turns: readonly AnchoredAssistantTurn[], toolCalls?: readonly AnchoredToolCall[]): CorrectionAnchorResult;
@@ -11,6 +11,16 @@ export type ExperimentIsolationViolation = {
11
11
  */
12
12
  export declare function canonicalForIsolation(candidate: string): string;
13
13
  export declare function experimentRootFromEnv(env?: NodeJS.ProcessEnv): string | null;
14
+ /**
15
+ * The PD workspace this experiment process DECLARED it belongs to.
16
+ *
17
+ * Containment alone is not identity: a profile that resolves to a DIFFERENT
18
+ * workspace inside the same experiment root would silently fork the experiment
19
+ * (two state DBs, two owner identities, evidence split across both). P0-1
20
+ * round 3 therefore compares the resolved workspace with this declaration
21
+ * whenever the operator made one.
22
+ */
23
+ export declare function declaredExperimentWorkspace(env?: NodeJS.ProcessEnv): string | null;
14
24
  export declare function experimentIsolationNextAction(): string;
15
25
  /**
16
26
  * Returns `null` when the workspace is acceptable, else a structured violation.
@@ -17,7 +17,7 @@
17
17
  *
18
18
  * 降级不静默 (rc-9):所有降级路径走 SystemLogger。
19
19
  */
20
- import { type UnifiedKeywordStore, type SignalCollectorConfig } from '@principles/core/runtime';
20
+ import { type UnifiedKeywordStore, type SignalCollectorConfig, type Stage2ConversationContext } from '@principles/core/runtime';
21
21
  import type { PluginLogger } from '../openclaw-sdk.js';
22
22
  import type { WorkspaceContext } from './workspace-context.js';
23
23
  export declare const DEFAULT_SIGNAL_CONFIG: SignalCollectorConfig;
@@ -34,7 +34,14 @@ export declare function buildDefaultKeywordStore(): UnifiedKeywordStore;
34
34
  * Adapter abstraction for Stage-2 LLM classification. The plugin may inject
35
35
  * a real provider; null/unavailable keeps the host on keyword-only fallback.
36
36
  */
37
- export type SignalLlmClassifier = (text: string, promptTemplate: string) => Promise<{
37
+ /**
38
+ * PD-BEHAVIOR-FIDELITY-001 Gate 3: the second argument is host-owned
39
+ * conversation facts, not a prompt template. It used to carry
40
+ * `config.promptTemplate`, which the factory ignored; every caller either
41
+ * passed `''` or the unused template. Passing real context is what the R3
42
+ * misclassification was missing.
43
+ */
44
+ export type SignalLlmClassifier = (text: string, context?: Stage2ConversationContext) => Promise<{
38
45
  is_feedback: boolean;
39
46
  type: 'correction' | 'none';
40
47
  confidence: number;
@@ -135,11 +142,23 @@ export declare class SignalCollectorHost {
135
142
  * 只入队"词库命中过的歧义候选":零命中的普通消息体量与噪声不可控,其纠正
136
143
  * 语义覆盖由 G3 的词库扩充/earned 解锁承担。
137
144
  *
145
+ * Gate 3 review P1:零命中候选有一个例外——它已经作为 discovery 候选真实
146
+ * 调用过 Stage-2(消费了 discovery 配额)。此时若 LLM 判为 correction、只是
147
+ * 置信度没过 0.9 门槛,丢弃就等于把"保持 pending"偷偷变成"删除真纠正"。
148
+ * 因此 LLM 已表态的路径传入 `allowKeywordless`;没有 LLM 的降级路径
149
+ * (`llm_unavailable`)仍维持原过滤,避免普通消息无界入队。
150
+ *
138
151
  * AUDIT-P2-01: stage2Queued 计数推迟到微任务执行(本方法可从无 await 的
139
152
  * 降级分支同步到达);SQLite 入队本身保持同步——它是可靠性要求,不是旁路
140
153
  * 观测,微任务/事件循环淘汰不能承担丢候选的风险。
141
154
  */
142
155
  private queueUnconfirmedForBatch;
156
+ /**
157
+ * Gate 3 review P1: 候选未入队时留下结构化原因。此前该分支只做计数,
158
+ * 日志仍写着"queued for batch confirmation",线上无法区分"入队成功"与
159
+ * "被过滤/无 writer 丢弃"(rc-9)。
160
+ */
161
+ private logConfirmationNotQueued;
143
162
  /**
144
163
  * PRI-788 G4: 未经确认就消失的候选计数(旁路,失败不阻塞)。
145
164
  * AUDIT-P2-01: 推迟到微任务——本计数可从无 await 的降级分支同步到达,
@@ -225,6 +244,18 @@ export declare class SignalCollectorHost {
225
244
  * production-pain-evidence 的内容派生 canonicalization(同一 pain identity
226
245
  * 权威),不再铸造随机 `correction_<traceId>`;trace id 降级为 correlation 字段。
227
246
  */
247
+ /**
248
+ * PD-BEHAVIOR-FIDELITY-001 Gate 3: assemble the conversation facts Stage-2
249
+ * was missing.
250
+ *
251
+ * Read-only and bounded. Two contract points:
252
+ * - `priorAssistantTurnCount: null` means UNKNOWN (no trajectory writer or a
253
+ * failed read), never 0. A read failure must not be reported as "this
254
+ * session had no assistant behavior".
255
+ * - The snapshot is taken before the classifier await, i.e. before the
256
+ * assistant replies to this message, so it is exactly "prior turns".
257
+ */
258
+ private buildStage2Context;
228
259
  private routeStrong;
229
260
  /**
230
261
  * STRONG rate limit 门控:成功消耗一个名额返回 true;超限返回 false。
@@ -134,6 +134,37 @@ export declare class TrajectoryDatabase {
134
134
  * Not: Runtime truth or real-time queue state.
135
135
  */
136
136
  listAssistantTurns(sessionId: string): AssistantTurnRecord[];
137
+ /**
138
+ * PD-BEHAVIOR-FIDELITY-001 Gate 3: bounded assistant-turn facts for the
139
+ * signal collector's Stage-2 prompt.
140
+ *
141
+ * `listAssistantTurns` is an analytics reader: it returns every turn,
142
+ * including `raw_text` and blob refs. Stage-2 runs on the synchronous
143
+ * `before_prompt_build` stack, so a full-session read per candidate message
144
+ * does not scale with session length. This method answers only what Stage-2
145
+ * needs — how many prior turns exist, the last N sanitized summaries, and one
146
+ * explicitly referenced turn — over the existing `session_id` index and with
147
+ * a narrowed projection.
148
+ */
149
+ getAssistantTurnContext(sessionId: string, options: {
150
+ recentLimit: number;
151
+ anchorTurnId?: number;
152
+ }): {
153
+ /**
154
+ * `null` = the count row could not be read (UNKNOWN), never 0. 0 is a real
155
+ * fact ("this session has no prior assistant turn"); a failed/shape-broken
156
+ * COUNT must not be downgraded into that fact.
157
+ */
158
+ priorTurnCount: number | null;
159
+ recentTurns: {
160
+ id: number;
161
+ sanitizedText: string;
162
+ }[];
163
+ anchorTurn: {
164
+ id: number;
165
+ sanitizedText: string;
166
+ } | null;
167
+ };
137
168
  /**
138
169
  * List tool calls for a session.
139
170
  *
@@ -7,8 +7,6 @@ import { EvolutionReducerImpl } from './evolution-reducer.js';
7
7
  import type { TrajectoryDatabase } from './trajectory.js';
8
8
  import { PrincipleLifecycleService } from './principle-internalization/principle-lifecycle-service.js';
9
9
  import { type PrincipleSubtree, type LedgerPrinciple, type PrincipleValueMetrics } from './principle-tree-ledger.js';
10
- import { RuleHost } from './rule-host.js';
11
- import type { RuleHostLogger } from './rule-host.js';
12
10
  interface PrincipleTreeLedgerAccessor {
13
11
  getPrincipleSubtree(_principleId: string): PrincipleSubtree | undefined;
14
12
  updatePrinciple(_principleId: string, updates: Partial<LedgerPrinciple>): LedgerPrinciple;
@@ -31,7 +29,6 @@ export declare class WorkspaceContext {
31
29
  private _trajectory?;
32
30
  private _principleTreeLedger?;
33
31
  private _principleLifecycle?;
34
- private _ruleHost?;
35
32
  private constructor();
36
33
  /**
37
34
  * Governance configuration for this workspace.
@@ -64,7 +61,6 @@ export declare class WorkspaceContext {
64
61
  * injected principle on prompt build).
65
62
  */
66
63
  get trajectory(): TrajectoryDatabase;
67
- getRuleHost(logger: RuleHostLogger): RuleHost;
68
64
  /**
69
65
  * Locked ledger access for principle tree reads and metric writes in this workspace.
70
66
  */
@@ -12,11 +12,6 @@ import { WorkspaceContext } from '../core/workspace-context.js';
12
12
  import type { RuleContextV2 } from '@principles/core/runtime';
13
13
  import type { PluginHookBeforeToolCallEvent, PluginHookToolContext, PluginHookBeforeToolCallResult, PluginLogger } from '../openclaw-sdk.js';
14
14
  import type { HostEventResult } from '@principles/core/host';
15
- export declare function handleBeforeToolCall(event: PluginHookBeforeToolCallEvent, ctx: PluginHookToolContext & {
16
- workspaceDir?: string;
17
- pluginConfig?: Record<string, unknown>;
18
- logger?: Partial<PluginLogger>;
19
- }): PluginHookBeforeToolCallResult | void;
20
15
  export declare function buildOpenClawRuleInputEnrichment(event: PluginHookBeforeToolCallEvent): {
21
16
  epTier: number;
22
17
  bashRisk: "dangerous" | "normal" | "safe" | "unknown";
@@ -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": "4.1.1",
5
+ "version": "4.1.3",
6
6
  "activation": {
7
7
  "onStartup": true,
8
8
  "onCapabilities": [