principles-disciple 2.7.1 → 3.0.1

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.
@@ -31,11 +31,8 @@ export declare const DEFAULT_SIGNAL_CONFIG: SignalCollectorConfig;
31
31
  export declare function isUserInteractionTrigger(trigger: string | undefined): boolean;
32
32
  export declare function buildDefaultKeywordStore(): UnifiedKeywordStore;
33
33
  /**
34
- * adapter 抽象 (Stage2 LLM 调用)。plugin 层可注入真实 adapter (LMStudio);
35
- * 为 null / 不可用时 host 走纯关键词降级。
36
- *
37
- * 本文件不依赖具体的 PDRuntimeAdapter 实现,只依赖一个最小的分类函数,
38
- * 以保持 host 可单测 (测试可注入 mock classifier)。
34
+ * Adapter abstraction for Stage-2 LLM classification. The plugin may inject
35
+ * a real provider; null/unavailable keeps the host on keyword-only fallback.
39
36
  */
40
37
  export type SignalLlmClassifier = (text: string, promptTemplate: string) => Promise<{
41
38
  is_feedback: boolean;
@@ -43,6 +40,22 @@ export type SignalLlmClassifier = (text: string, promptTemplate: string) => Prom
43
40
  confidence: number;
44
41
  reason: string;
45
42
  } | null>;
43
+ /**
44
+ * PRI-1137: `detectSync` must report whether THIS invocation's `user_turns`
45
+ * row was actually persisted. A `void` return made a swallowed write failure
46
+ * indistinguishable from success, so the shared round-key provider could read
47
+ * a PREVIOUS ordinal and claim fair rotation for a round that was never
48
+ * recorded. Only `user_turn_persisted` authorises a round key / run claim.
49
+ */
50
+ export type SignalSyncOutcome = {
51
+ readonly status: 'not_user_interaction';
52
+ } | {
53
+ readonly status: 'user_turn_persisted';
54
+ readonly userTurnRowid: number;
55
+ } | {
56
+ readonly status: 'user_turn_persist_failed';
57
+ readonly reason: string;
58
+ };
46
59
  export interface SignalCollectorHostOptions {
47
60
  keywordStore?: UnifiedKeywordStore;
48
61
  /**
@@ -70,7 +83,13 @@ export declare class SignalCollectorHost {
70
83
  private readonly cueFeedbackRecorder?;
71
84
  /** rate limit 状态:sessionId → STRONG 计数桶 */
72
85
  private readonly rateLimit;
73
- /** 零命中「发现」调用的配额桶(每 host = 每 workspace,进程内) */
86
+ /**
87
+ * Same-run retry cache. A failed user_turn persistence may be retried, but
88
+ * Stage-1 classification, discovery-budget consumption and signal routing
89
+ * are one-shot for that host run.
90
+ */
91
+ private readonly processedRuns;
92
+ /** Zero-hit discovery budget for this workspace's host process. */
74
93
  private discoveryBucket;
75
94
  constructor(wctx: WorkspaceContext, options?: SignalCollectorHostOptions);
76
95
  /**
@@ -87,7 +106,8 @@ export declare class SignalCollectorHost {
87
106
  detectSync(userMessage: string, sessionId: string, trigger: string, options?: {
88
107
  referencesAssistantTurnId?: number | null;
89
108
  turnIndex?: number;
90
- }): void;
109
+ idempotencyKey?: string;
110
+ }): SignalSyncOutcome;
91
111
  /**
92
112
  * ★ 异步路径 (fire-and-forget)。
93
113
  *
@@ -0,0 +1,69 @@
1
+ /**
2
+ * Prompt presence forensics: freezes the per-activation expectation set for one
3
+ * prompt build (design v1.2 §3/§5, owner conditions 2 & 3; review-round fixes:
4
+ * final-assembly classification + collection bounding + overflow visibility).
5
+ *
6
+ * Rules:
7
+ * - Frozen AFTER all body, authorization, timeout and budget fallbacks: the
8
+ * classification runs against the FINAL text this hook returns.
9
+ * - Classification per candidate body (host-normalized):
10
+ * contained in the final assembly → bodyComplete=true;
11
+ * not in final but was in pre-guard → bodyComplete=false (truncated
12
+ * fragment; never yields full_hit);
13
+ * in neither → excluded (the activation is not
14
+ * part of this assembly at all).
15
+ * - bodyText replicates the host prompt-section normalization (CRLF→LF, strip
16
+ * trailing spaces per line, outer trim) so containment survives the host wrap.
17
+ * - Collection is bounded: the escape/normalize work happens only for kept
18
+ * entries; entries beyond the cap are counted as overflow, never silently
19
+ * dropped.
20
+ * - Memory-only: expectations ride the hook result to the host and are never
21
+ * persisted or logged here.
22
+ */
23
+ export type InjectedExpectation = {
24
+ activationId: string;
25
+ revision: number | string;
26
+ bodyText: string;
27
+ bodyChars: number;
28
+ bodyComplete: boolean;
29
+ };
30
+ export type BuiltInjectedExpectations = {
31
+ expectations: InjectedExpectation[];
32
+ /** Entries dropped because the collection cap was hit (visibility fact). */
33
+ overflowCount: number;
34
+ };
35
+ /**
36
+ * Mirrors the host's normalizeStructuredPromptSection (@openclaw/ai
37
+ * prompt-cache-stability.ts): sanitize-adjacent CRLF→LF, per-line trailing
38
+ * space strip, outer trim. Idempotent on already-normalized text.
39
+ */
40
+ export declare function normalizeForWireMatch(text: string): string;
41
+ export type FrozenExpectationCandidate = {
42
+ activationId: string;
43
+ /** Raw (pre-escape) body; `escape` is applied only to kept entries. */
44
+ body: string;
45
+ };
46
+ export declare function buildInjectedExpectations(params: {
47
+ /** FINAL post-guard, post-fallback prependSystemContext (what this hook returns). */
48
+ finalAssembly: string;
49
+ /** Pre-guard assembly snapshot, for the truncated-fragment classification. */
50
+ preGuardAssembly?: string;
51
+ /**
52
+ * Target priority body when the adaptive path prioritized one activation.
53
+ * `preEscaped: true` marks the body as ALREADY RENDERED text (the renderer
54
+ * contract applies escapeXml inside the directive slice — see
55
+ * adaptive-principle-intervention.ts), so the escape callback must NOT run
56
+ * again; re-escaping would double-escape and hide a fully assembled target.
57
+ */
58
+ target?: {
59
+ activationId: string;
60
+ body: string;
61
+ preEscaped?: boolean;
62
+ } | undefined;
63
+ /** Raw candidates from the render path (escape applied to kept entries only). */
64
+ rendered: FrozenExpectationCandidate[];
65
+ /** Escape applied to a raw body exactly as the renderer would (e.g. escapeXml). */
66
+ escape?: (text: string) => string;
67
+ /** Revision is unknown at this layer; recorded verbatim for the event. */
68
+ revision?: number | string;
69
+ }): BuiltInjectedExpectations | undefined;
@@ -28,6 +28,46 @@ export declare function beginAdaptivePromptInvocation(ctx: PluginHookAgentContex
28
28
  artifactId: string;
29
29
  activationId: string;
30
30
  }, runtimeMode: string, hookInvocationId?: string): string;
31
+ /**
32
+ * PRI-1137 PRE-SELECTION phase for the OpenClaw shared prompt route.
33
+ *
34
+ * The shared runtime must know the session round BEFORE it selects principles
35
+ * (`buildActivePrinciplePromptContext` → roundKey), but OpenClaw's user-turn
36
+ * record is written by `SignalCollectorHost.detectSync`, which the plugin
37
+ * previously ran inside `handleBeforePromptBuild` — i.e. AFTER the shared
38
+ * selection. Calling `nextSessionTurnOrdinal` before that write would read a
39
+ * PREVIOUS round and shift the rotation by one turn.
40
+ *
41
+ * So the plugin preparation is split in two halves that share ONE write:
42
+ * - pre-selection (this function): signal collection + user_turns write,
43
+ * then read the trusted ordinal;
44
+ * - post-selection (`handleBeforePromptBuild`): skips signal collection for
45
+ * an event already claimed here and assembles the host context.
46
+ *
47
+ * The returned ordinal is exactly `max(turn_index) + 1` AFTER this turn is
48
+ * persisted — the same derivation the former plugin-local route used, so the
49
+ * two routes agreed turn-for-turn. No unconditional `+1` offset is applied
50
+ * anywhere.
51
+ *
52
+ * PRI-1137 final review P1-3 — a round key is returned ONLY when this
53
+ * invocation has a real, persisted round of its own:
54
+ * - a run already claimed here reuses ITS OWN persisted ordinal (never the
55
+ * global counter, which a concurrent run's write may have advanced);
56
+ * - a fresh user-interaction write that reports `user_turn_persisted`
57
+ * claims the ordinal it just produced;
58
+ * - EVERYTHING ELSE — no sessionId, no resolvable user message, a message
59
+ * resolution failure, a non-interactive trigger (heartbeat/cron), an
60
+ * agent-to-agent message, a write that did not persist, an unreadable
61
+ * trajectory DB, a non-integer ordinal — returns `undefined` and the
62
+ * selection degrades to `legacy_fifo_prefix_v1`. Previously a write-free
63
+ * invocation still read the global ordinal and claimed fair rotation on a
64
+ * round it never recorded (a heartbeat could re-present the last window
65
+ * as a fresh fair rotation, and an empty session yielded a fabricated
66
+ * round 1). A constant round is never fabricated.
67
+ */
68
+ export declare function prepareOpenClawPromptRound(event: PluginHookBeforePromptBuildEvent, ctx: PluginHookAgentContext & {
69
+ api?: PromptHookApi;
70
+ }): number | undefined;
31
71
  export declare function handleBeforePromptBuild(event: PluginHookBeforePromptBuildEvent, ctx: PluginHookAgentContext & {
32
72
  api?: PromptHookApi;
33
73
  }, sharedActivePrinciplePrompt?: ActivePrinciplePromptResult): Promise<PluginHookBeforePromptBuildResult | void>;
@@ -3,6 +3,15 @@ import type { HostEventResult } from '@principles/core/host';
3
3
  import type { PluginHookAgentContext, PluginHookAfterToolCallEvent, PluginHookBeforePromptBuildEvent, PluginHookBeforePromptBuildResult, PluginHookBeforeToolCallEvent, PluginHookBeforeToolCallResult, PluginHookToolContext } from '../openclaw-sdk.js';
4
4
  export interface OpenClawHostRuntimeOptions {
5
5
  beforePromptBuild(event: PluginHookBeforePromptBuildEvent, context: PluginHookAgentContext, prompt: ActivePrinciplePromptResult): Promise<PluginHookBeforePromptBuildResult | void>;
6
+ /**
7
+ * PRI-1137: the OpenClaw prompt ROUND authority, supplied by the plugin
8
+ * adapter (`nextSessionTurnOrdinal` after its pre-selection signal
9
+ * collection). Runs before the shared prompt context is built; returning
10
+ * `undefined` (missing sessionId / unreadable trajectory DB / failed
11
+ * ordinal read) is the observable degraded case and selects
12
+ * `legacy_fifo_prefix_v1`. Never fabricate a round here.
13
+ */
14
+ roundKeyProvider?(event: PluginHookBeforePromptBuildEvent, context: PluginHookAgentContext): number | undefined | Promise<number | undefined>;
6
15
  adaptivePriorityProvider?(event: PluginHookBeforePromptBuildEvent, context: PluginHookAgentContext): {
7
16
  artifactId: string;
8
17
  activationId: string;
@@ -25,6 +34,20 @@ export interface OpenClawHostRuntime {
25
34
  readonly runtime: HostRuntime;
26
35
  dispatchBeforePromptBuild(event: PluginHookBeforePromptBuildEvent, context: PluginHookAgentContext): Promise<PluginHookBeforePromptBuildResult | void>;
27
36
  dispatchBeforeToolCall(event: PluginHookBeforeToolCallEvent, context: PluginHookToolContext): Promise<PluginHookBeforeToolCallResult | void>;
28
- dispatchAfterToolCall(event: PluginHookAfterToolCallEvent, context: PluginHookToolContext): Promise<void>;
37
+ /**
38
+ * PRI-1137 final review P1-4: after_tool_call dispatches return the shared
39
+ * runtime's degradation facts (e.g. `trajectory_db_not_found`) instead of an
40
+ * opaque void — evidence that failed to persist must be observable to the
41
+ * operator, never silently recorded as a successful hook execution.
42
+ */
43
+ dispatchAfterToolCall(event: PluginHookAfterToolCallEvent, context: PluginHookToolContext): Promise<AfterToolCallDispatch>;
44
+ }
45
+ /** Degradation facts surfaced by one after_tool_call dispatch (P1-4). */
46
+ export interface AfterToolCallDispatch {
47
+ /** Shared-runtime warnings (bounded); empty when the evidence path was healthy. */
48
+ warnings: readonly string[];
49
+ /** `unavailable` when the technical evidence could not be persisted. */
50
+ outcome?: 'unavailable' | string;
51
+ nextAction?: string;
29
52
  }
30
53
  export declare function createOpenClawHostRuntime(options: OpenClawHostRuntimeOptions): OpenClawHostRuntime;
package/dist/index.d.ts CHANGED
@@ -1,6 +1,7 @@
1
- import type { OpenClawPluginApi } from './openclaw-sdk.js';
1
+ import type { OpenClawPluginApi, PluginHookBeforePromptBuildEvent, PluginHookAgentContext } from './openclaw-sdk.js';
2
2
  export { checkConversationAccessConfig, getPluginEntry, ensureConversationAccessInConfig, isExplicitConversationAccessOptOut } from './core/config-health.js';
3
3
  export type { ConversationAccessCheckResult } from './core/config-health.js';
4
+ import { handleBeforePromptBuild } from './hooks/prompt.js';
4
5
  declare function isRecord(value: unknown): value is Record<string, unknown>;
5
6
  /**
6
7
  * PRI-305/PRI-307: Load feature flag from .pd/config.yaml instead of .pd/feature-flags.yaml.
@@ -31,14 +32,6 @@ export declare function shouldStartInternalizationAutoConsumer(workspaceDir: str
31
32
  info?: (msg: string) => void;
32
33
  warn?: (msg: string) => void;
33
34
  }): InternalizationAutoConsumerGateResult;
34
- export declare function shouldUseSharedHostRuntime(workspaceDir: string, logger: {
35
- info?: (msg: string) => void;
36
- warn?: (msg: string) => void;
37
- }): {
38
- enabled: boolean;
39
- source: string;
40
- rollbackReason: string | null;
41
- };
42
35
  /**
43
36
  * Gate 4 (PRI-1071): keep the host-wide launcher binding in lockstep with an
44
37
  * EXPLICITLY DECLARED PD workspace only.
@@ -72,6 +65,20 @@ export declare function syncMcpBindingFromExplicitWorkspace(options: {
72
65
  source: string;
73
66
  } | null;
74
67
  }): McpBindingSyncResult;
68
+ /**
69
+ * PRI-1137: the OpenClaw-specific adaptive-priority decision, extracted from
70
+ * the inline provider so the SAME decision runs on the shared-runtime path.
71
+ * The pre-selection half claims the operator admission (or begins a native
72
+ * delivery invocation) BEFORE the shared selector builds the prompt; the
73
+ * resulting priority is handed to `buildActivePrinciplePromptContext`.
74
+ */
75
+ export declare function resolveAdaptivePriorityForHook(event: PluginHookBeforePromptBuildEvent, context: PluginHookAgentContext, api: Parameters<typeof handleBeforePromptBuild>[1]['api']): {
76
+ artifactId: string;
77
+ activationId: string;
78
+ hookInvocationId?: string;
79
+ signal?: AbortSignal;
80
+ deadlineAt?: number;
81
+ } | undefined;
75
82
  declare const plugin: {
76
83
  name: string;
77
84
  description: string;
@@ -199,6 +199,22 @@ export interface PluginHookBeforePromptBuildResult {
199
199
  appendContext?: string;
200
200
  prependSystemContext?: string;
201
201
  appendSystemContext?: string;
202
+ /**
203
+ * Frozen forensic expectation set for this prompt build (prompt presence check).
204
+ * Frozen AFTER the size guard, authorization, timeout and budget fallbacks;
205
+ * bodyComplete=false marks a truncated fragment (never yields a full_hit);
206
+ * activations removed by a fallback are excluded entirely. Memory-only; host
207
+ * passes it to the wire checkpoint.
208
+ */
209
+ injectedExpectations?: {
210
+ activationId: string;
211
+ revision: number | string;
212
+ bodyText: string;
213
+ bodyChars: number;
214
+ bodyComplete: boolean;
215
+ }[];
216
+ /** Entries dropped by this hook's own collection cap; visibility fact. */
217
+ injectedExpectationsOverflow?: number;
202
218
  }
203
219
  export interface PluginHookBeforeToolCallEvent {
204
220
  toolName: string;
@@ -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.7.1",
5
+ "version": "3.0.1",
6
6
  "activation": {
7
7
  "onStartup": true,
8
8
  "onCapabilities": [
@@ -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.7.1",
5
+ "version": "3.0.1",
6
6
  "activation": {
7
7
  "onStartup": true,
8
8
  "onCapabilities": [
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "principles-disciple",
3
- "version": "2.7.1",
3
+ "version": "3.0.1",
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
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -76,8 +76,8 @@
76
76
  "compile-principles": "node scripts/compile-principles.mjs"
77
77
  },
78
78
  "devDependencies": {
79
- "@principles/core": "^5.0.0",
80
- "@principles/host-runtime": "^2.2.3",
79
+ "@principles/core": "^5.1.0",
80
+ "@principles/host-runtime": "^3.0.0",
81
81
  "@types/better-sqlite3": "^9.6.0",
82
82
  "@types/js-yaml": "^4.0.9",
83
83
  "@types/micromatch": "^4.0.10",
@@ -109,5 +109,5 @@
109
109
  "js-yaml": "^5.4.3",
110
110
  "micromatch": "^4.0.8"
111
111
  },
112
- "gitHead": "86b6208042b6083d4a7bbf840730d060188a1517"
112
+ "gitHead": "9656a64563e073c92aa8da0373ea96249de1a71b"
113
113
  }