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.
- package/dist/bundle.js +482 -486
- package/dist/core/signal-collector-host.d.ts +27 -7
- package/dist/hooks/prompt-presence-expectations.d.ts +69 -0
- package/dist/hooks/prompt.d.ts +40 -0
- package/dist/host-runtime/openclaw-host-runtime.d.ts +24 -1
- package/dist/index.d.ts +16 -9
- package/dist/openclaw-sdk.d.ts +16 -0
- package/dist/openclaw.plugin.json +1 -1
- package/openclaw.plugin.json +1 -1
- package/package.json +4 -4
|
@@ -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
|
-
*
|
|
35
|
-
*
|
|
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
|
-
/**
|
|
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
|
-
|
|
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;
|
package/dist/hooks/prompt.d.ts
CHANGED
|
@@ -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
|
-
|
|
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;
|
package/dist/openclaw-sdk.d.ts
CHANGED
|
@@ -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": "
|
|
5
|
+
"version": "3.0.1",
|
|
6
6
|
"activation": {
|
|
7
7
|
"onStartup": true,
|
|
8
8
|
"onCapabilities": [
|
package/openclaw.plugin.json
CHANGED
|
@@ -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": "
|
|
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": "
|
|
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.
|
|
80
|
-
"@principles/host-runtime": "^
|
|
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": "
|
|
112
|
+
"gitHead": "9656a64563e073c92aa8da0373ea96249de1a71b"
|
|
113
113
|
}
|