pi-braid 0.40.1 → 0.40.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.
- package/CONTRIBUTING.md +27 -3
- package/README.md +13 -13
- package/TOOLS.md +27 -3
- package/build-info.json +9 -0
- package/dist/extensions/cognitive/metacognition/handlers/claim-verification.js +7 -1
- package/dist/extensions/cognitive/metacognition/handlers/finalize.js +20 -0
- package/dist/extensions/cognitive/metacognition/handlers/hypothesize.d.ts +9 -0
- package/dist/extensions/cognitive/metacognition/handlers/hypothesize.js +13 -1
- package/dist/extensions/cognitive/metacognition/handlers/verify.js +35 -4
- package/dist/extensions/cognitive/topic-drift/index.js +19 -2
- package/dist/extensions/core/prompt-builder/inspect.js +9 -3
- package/dist/extensions/core/prompt-builder/top-level-extensions.d.ts +6 -5
- package/dist/extensions/core/prompt-builder/top-level-extensions.js +64 -29
- package/dist/extensions/enforcement/handlers/register-tool-result-formatting.d.ts +1 -1
- package/dist/extensions/enforcement/handlers/register-tool-result-formatting.js +1 -1
- package/dist/extensions/enforcement/handlers/turn-end-handler.js +1 -1
- package/dist/extensions/enforcement/self-state-claims.d.ts +1 -1
- package/dist/extensions/enforcement/self-state-claims.js +3 -2
- package/dist/extensions/manifest.js +2 -2
- package/dist/extensions/memory/context-manager/handlers/tool-batch-boundary.d.ts +22 -5
- package/dist/extensions/memory/context-manager/handlers/tool-batch-boundary.js +43 -11
- package/dist/extensions/memory/context-manager/handlers/tools/context-compress.js +174 -50
- package/dist/extensions/memory/context-manager/handlers/tools/context-inspect.js +7 -1
- package/dist/extensions/memory/context-manager/handlers/tools/context-navigate.js +4 -1
- package/dist/extensions/memory/memory-agent-bridge/explore-paths.d.ts +2 -24
- package/dist/extensions/memory/memory-agent-bridge/explore-paths.js +33 -2
- package/dist/extensions/memory/memory-agent-bridge/memory-store-tool.js +16 -0
- package/dist/extensions/memory/memory-agent-bridge/memory-tool.js +21 -9
- package/dist/extensions/memory/scratchpad/format.js +8 -2
- package/dist/extensions/memory/scratchpad/index.js +11 -2
- package/dist/extensions/memory/session-recall/index.js +19 -6
- package/dist/extensions/memory/three-memory-stores/episodes.d.ts +1 -1
- package/dist/extensions/memory/three-memory-stores/episodes.js +2 -2
- package/dist/extensions/orchestrator/index.js +73 -8
- package/dist/extensions/scheduling/timer/index.js +9 -1
- package/dist/extensions/self/error-tracking/index.js +8 -1
- package/dist/extensions/self/health-maintenance/handlers/session-health-tool.js +9 -2
- package/dist/extensions/self/health-maintenance/index.js +112 -9
- package/dist/lib/config/braid-settings.d.ts +21 -0
- package/dist/lib/config/braid-settings.js +36 -0
- package/dist/lib/constants/session-thresholds.d.ts +2 -3
- package/dist/lib/constants/session-thresholds.js +2 -3
- package/dist/lib/enforcement/turn-dedup.d.ts +2 -2
- package/dist/lib/enforcement/turn-dedup.js +2 -2
- package/dist/lib/harness/index.d.ts +1 -1
- package/dist/lib/harness/index.js +1 -1
- package/dist/lib/harness/types.d.ts +1 -1
- package/dist/lib/harness/types.js +1 -1
- package/dist/lib/orchestrator/index.d.ts +2 -2
- package/dist/lib/orchestrator/index.js +1 -1
- package/dist/lib/orchestrator/workers.d.ts +184 -2
- package/dist/lib/orchestrator/workers.js +521 -6
- package/dist/lib/utils/injection-tracker.js +1 -1
- package/docs/CONTEXT-POLICY.md +13 -5
- package/docs/LOCAL_DEV.md +31 -5
- package/docs/ROADMAP.md +10 -7
- package/docs/SETUP.md +3 -2
- package/package.json +11 -8
- package/skills/braid-reference/SKILL.md +23 -23
- package/skills/release-pipeline/SKILL.md +46 -37
- package/skills/subagent-orchestration/SKILL.md +51 -1
- package/src/extensions/cognitive/metacognition/handlers/claim-verification.ts +8 -1
- package/src/extensions/cognitive/metacognition/handlers/finalize.ts +21 -0
- package/src/extensions/cognitive/metacognition/handlers/hypothesize.ts +14 -1
- package/src/extensions/cognitive/metacognition/handlers/verify.ts +39 -5
- package/src/extensions/cognitive/topic-drift/index.ts +20 -2
- package/src/extensions/core/prompt-builder/AGENTS.md +1 -1
- package/src/extensions/core/prompt-builder/inspect.ts +10 -3
- package/src/extensions/core/prompt-builder/top-level-extensions.ts +68 -29
- package/src/extensions/enforcement/AGENTS.md +25 -19
- package/src/extensions/enforcement/handlers/register-tool-result-formatting.ts +1 -1
- package/src/extensions/enforcement/handlers/turn-end-handler.ts +1 -1
- package/src/extensions/enforcement/self-state-claims.ts +3 -2
- package/src/extensions/heartbeat/heartbeat-scheduler/AGENTS.md +6 -3
- package/src/extensions/manifest.ts +2 -2
- package/src/extensions/memory/AGENTS.md +13 -5
- package/src/extensions/memory/context-manager/handlers/tool-batch-boundary.ts +45 -11
- package/src/extensions/memory/context-manager/handlers/tools/context-compress.ts +202 -60
- package/src/extensions/memory/context-manager/handlers/tools/context-inspect.ts +8 -1
- package/src/extensions/memory/context-manager/handlers/tools/context-navigate.ts +4 -1
- package/src/extensions/memory/memory-agent-bridge/explore-paths.ts +37 -3
- package/src/extensions/memory/memory-agent-bridge/memory-store-tool.ts +16 -0
- package/src/extensions/memory/memory-agent-bridge/memory-tool.ts +22 -9
- package/src/extensions/memory/scratchpad/format.ts +8 -2
- package/src/extensions/memory/scratchpad/index.ts +12 -2
- package/src/extensions/memory/session-recall/index.ts +20 -8
- package/src/extensions/memory/three-memory-stores/episodes.ts +2 -2
- package/src/extensions/orchestrator/index.ts +100 -11
- package/src/extensions/scheduling/timer/AGENTS.md +7 -0
- package/src/extensions/scheduling/timer/index.ts +10 -1
- package/src/extensions/self/error-tracking/index.ts +9 -1
- package/src/extensions/self/health-maintenance/handlers/session-health-tool.ts +10 -2
- package/src/extensions/self/health-maintenance/index.ts +143 -14
- package/src/extensions/self/watchdog/AGENTS.md +1 -0
- package/src/lib/AGENTS.md +21 -21
- package/src/lib/config/braid-settings.ts +74 -0
- package/src/lib/constants/session-thresholds.ts +2 -3
- package/src/lib/enforcement/turn-dedup.ts +2 -2
- package/src/lib/harness/AGENTS.md +1 -1
- package/src/lib/harness/index.ts +1 -1
- package/src/lib/harness/types.ts +1 -1
- package/src/lib/orchestrator/index.ts +26 -0
- package/src/lib/orchestrator/workers.ts +705 -7
- package/src/lib/utils/AGENTS.md +1 -1
- package/src/lib/utils/injection-tracker.ts +1 -1
package/src/lib/AGENTS.md
CHANGED
|
@@ -9,27 +9,27 @@ shared conventions.
|
|
|
9
9
|
|
|
10
10
|
## Subdirectory Index
|
|
11
11
|
|
|
12
|
-
| Subdir | Purpose
|
|
13
|
-
| ----------------------------------------- |
|
|
14
|
-
| [`ai/`](./ai/AGENTS.md) | LLM utilities - critic registry, model resolution, text classification, structured LLM call wrapper.
|
|
15
|
-
| [`memory/`](./memory/AGENTS.md) | Memory engine - the underlying storage and reasoning layer for memory-related extensions.
|
|
16
|
-
| [`config/`](./config/AGENTS.md) | Configuration loading and merging.
|
|
17
|
-
| [`constants/`](./constants/AGENTS.md) | Project-wide constants and enums.
|
|
18
|
-
| [`core/`](./core/AGENTS.md) | Foundation utilities - logger, event-name constants. Anything that's truly cross-cutting lives here.
|
|
19
|
-
| [`detection/`](./detection/AGENTS.md) | Detection primitives - degradation detection, topic-drift, context density, compression strategies.
|
|
20
|
-
| [`enforcement/`](./enforcement/AGENTS.md) | Cross-extension enforcement utilities - turn-dedup registry, whisper capping.
|
|
21
|
-
| [`events/`](./events/AGENTS.md) | Event-bus and channel infrastructure - consolidation, timer, turn-end coordination.
|
|
22
|
-
| [`reasoning/`](./reasoning/AGENTS.md) | Reasoning engines - dreamer (loop prediction), belief policy, MARS reflector, summarization, advice tracker.
|
|
23
|
-
| [`state/`](./state/AGENTS.md) | Per-extension state, session state, global state, checkpointing.
|
|
24
|
-
| [`store/`](./store/AGENTS.md) | Persistent stores - claims, evidence, conflicts, beliefs.
|
|
25
|
-
| [`types/`](./types/AGENTS.md) | Shared type definitions and result wrappers.
|
|
26
|
-
| [`utils/`](./utils/AGENTS.md) | Misc utilities - injection tracker, mutation queue, filter helpers, SOP extraction.
|
|
27
|
-
| [`cognitive/`](./cognitive/AGENTS.md) | Whisper-delivery libraries - project-relevant hints and active OpenSpec specs for the prompt.
|
|
28
|
-
| `errors/` | Unified LLM error classifier - provider-failure taxonomy (balance, rate-limit, context-window, transient).
|
|
29
|
-
| [`harness/`](./harness/AGENTS.md) | Self-harness loop - failure-trace collection, weakness mining, candidate proposal and validation.
|
|
30
|
-
| `orchestrator/` | Multi-agent coordination - file-lock registry, worker branches, conflict detection, merge verification.
|
|
31
|
-
| [`telemetry/`](./telemetry/AGENTS.md) | Bounded telemetry accumulators for the degradation-detection loop (drift signals, context/RSS heartbeat).
|
|
32
|
-
| `verification/` | Cross-file verification - downstream import tracing and derived-file coordination checks.
|
|
12
|
+
| Subdir | Purpose |
|
|
13
|
+
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
14
|
+
| [`ai/`](./ai/AGENTS.md) | LLM utilities - critic registry, model resolution, text classification, structured LLM call wrapper. |
|
|
15
|
+
| [`memory/`](./memory/AGENTS.md) | Memory engine - the underlying storage and reasoning layer for memory-related extensions. |
|
|
16
|
+
| [`config/`](./config/AGENTS.md) | Configuration loading and merging. |
|
|
17
|
+
| [`constants/`](./constants/AGENTS.md) | Project-wide constants and enums. |
|
|
18
|
+
| [`core/`](./core/AGENTS.md) | Foundation utilities - logger, event-name constants. Anything that's truly cross-cutting lives here. |
|
|
19
|
+
| [`detection/`](./detection/AGENTS.md) | Detection primitives - degradation detection, topic-drift, context density, compression strategies. |
|
|
20
|
+
| [`enforcement/`](./enforcement/AGENTS.md) | Cross-extension enforcement utilities - turn-dedup registry, whisper capping. |
|
|
21
|
+
| [`events/`](./events/AGENTS.md) | Event-bus and channel infrastructure - consolidation, timer, turn-end coordination. |
|
|
22
|
+
| [`reasoning/`](./reasoning/AGENTS.md) | Reasoning engines - dreamer (loop prediction), belief policy, MARS reflector, summarization, advice tracker. |
|
|
23
|
+
| [`state/`](./state/AGENTS.md) | Per-extension state, session state, global state, checkpointing. |
|
|
24
|
+
| [`store/`](./store/AGENTS.md) | Persistent stores - claims, evidence, conflicts, beliefs. |
|
|
25
|
+
| [`types/`](./types/AGENTS.md) | Shared type definitions and result wrappers. |
|
|
26
|
+
| [`utils/`](./utils/AGENTS.md) | Misc utilities - injection tracker, mutation queue, filter helpers, SOP extraction. |
|
|
27
|
+
| [`cognitive/`](./cognitive/AGENTS.md) | Whisper-delivery libraries - project-relevant hints and active OpenSpec specs for the prompt. |
|
|
28
|
+
| `errors/` | Unified LLM error classifier - provider-failure taxonomy (balance, rate-limit, context-window, transient). |
|
|
29
|
+
| [`harness/`](./harness/AGENTS.md) | Self-harness loop - failure-trace collection, weakness mining, candidate proposal and validation. |
|
|
30
|
+
| `orchestrator/` | Multi-agent coordination - file-lock registry, worker registry with close-time gate-row well-formedness, the production-write preflight read, and the population-stamp read the merge path compares against the repo, worker branches, conflict detection, merge verification. |
|
|
31
|
+
| [`telemetry/`](./telemetry/AGENTS.md) | Bounded telemetry accumulators for the degradation-detection loop (drift signals, context/RSS heartbeat). |
|
|
32
|
+
| `verification/` | Cross-file verification - downstream import tracing and derived-file coordination checks. |
|
|
33
33
|
|
|
34
34
|
## Conventions
|
|
35
35
|
|
|
@@ -66,6 +66,24 @@ interface BraidConfig {
|
|
|
66
66
|
mode?: string;
|
|
67
67
|
};
|
|
68
68
|
};
|
|
69
|
+
/**
|
|
70
|
+
* Orchestrator-layer config. `closeGateWellFormedness` gates the close
|
|
71
|
+
* path's gate evidence at close time: every recorded `{cmd, exit}` row is
|
|
72
|
+
* read as a string (parse, first-token resolution, no top-level
|
|
73
|
+
* decoration) and a completed close's exits must be 0. No gate is re-run.
|
|
74
|
+
*
|
|
75
|
+
* Example:
|
|
76
|
+
* "braid": { "orchestrator": { "closeGateWellFormedness": "shadow" } }
|
|
77
|
+
*/
|
|
78
|
+
orchestrator?: {
|
|
79
|
+
/**
|
|
80
|
+
* "shadow" (default) logs a failing row to the refusal log and lets the
|
|
81
|
+
* close proceed; "enforce" refuses the close naming the row, predicate
|
|
82
|
+
* and cmd; "off" skips the read entirely. An unknown value warns once
|
|
83
|
+
* and falls back to "shadow".
|
|
84
|
+
*/
|
|
85
|
+
closeGateWellFormedness?: string;
|
|
86
|
+
};
|
|
69
87
|
/**
|
|
70
88
|
* Memory-layer config. Review-before-write quality gate on durable episode
|
|
71
89
|
* writes: `writeGate` controls the per-site policies (repair/dedupe/reject)
|
|
@@ -415,6 +433,62 @@ export function getOverCorrectionGateConfig(): OverCorrectionGateConfig {
|
|
|
415
433
|
return resolveOverCorrectionGate(readSettings().braid?.enforcement?.overCorrectionGate);
|
|
416
434
|
}
|
|
417
435
|
|
|
436
|
+
// ── close-gate well-formedness (braid.orchestrator.closeGateWellFormedness) ──
|
|
437
|
+
// The close path reads every recorded gate evidence row {cmd, exit} against
|
|
438
|
+
// four string predicates before the row is stamped (see
|
|
439
|
+
// lib/orchestrator/workers.ts). Shipped default: shadow, so a failing row is
|
|
440
|
+
// logged and the close proceeds, and a first ship cannot refuse honest closes.
|
|
441
|
+
|
|
442
|
+
/** Close-gate modes: off (inert), shadow (log only), enforce (refuse). */
|
|
443
|
+
export type CloseGateWellFormednessMode = "off" | "shadow" | "enforce";
|
|
444
|
+
|
|
445
|
+
export interface CloseGateWellFormednessConfig {
|
|
446
|
+
mode: CloseGateWellFormednessMode;
|
|
447
|
+
}
|
|
448
|
+
|
|
449
|
+
/** Default mode: shadow; the validator logs before it is allowed to refuse. */
|
|
450
|
+
export const CLOSE_GATE_WELL_FORMEDNESS_DEFAULTS: CloseGateWellFormednessConfig = {
|
|
451
|
+
mode: "shadow",
|
|
452
|
+
};
|
|
453
|
+
|
|
454
|
+
/** Warned once per process about an invalid closeGateWellFormedness value. */
|
|
455
|
+
let _warnedInvalidCloseGateWellFormedness = false;
|
|
456
|
+
|
|
457
|
+
function _warnInvalidCloseGateWellFormedness(value: unknown): void {
|
|
458
|
+
if (_warnedInvalidCloseGateWellFormedness) return;
|
|
459
|
+
_warnedInvalidCloseGateWellFormedness = true;
|
|
460
|
+
_log.warn(
|
|
461
|
+
"Invalid braid.orchestrator.closeGateWellFormedness in settings.json - ignoring " +
|
|
462
|
+
'and using the default (mode "shadow"). Expected "off" | "shadow" | "enforce".',
|
|
463
|
+
{ value },
|
|
464
|
+
);
|
|
465
|
+
}
|
|
466
|
+
|
|
467
|
+
/**
|
|
468
|
+
* Pure resolver for braid.orchestrator.closeGateWellFormedness. Absent value
|
|
469
|
+
* ⇒ mode "shadow". A value outside the enum warns once and falls back to
|
|
470
|
+
* "shadow", so a typo can neither silently disarm the validator (off) nor
|
|
471
|
+
* arm it (enforce). Kept pure so the default merge is unit-testable without
|
|
472
|
+
* touching live settings.json.
|
|
473
|
+
*/
|
|
474
|
+
export function resolveCloseGateWellFormedness(raw: unknown): CloseGateWellFormednessConfig {
|
|
475
|
+
if (raw === undefined || raw === null) return { ...CLOSE_GATE_WELL_FORMEDNESS_DEFAULTS };
|
|
476
|
+
if (raw === "off" || raw === "shadow" || raw === "enforce") return { mode: raw };
|
|
477
|
+
_warnInvalidCloseGateWellFormedness(raw);
|
|
478
|
+
return { ...CLOSE_GATE_WELL_FORMEDNESS_DEFAULTS };
|
|
479
|
+
}
|
|
480
|
+
|
|
481
|
+
/**
|
|
482
|
+
* Read the effective close-gate well-formedness mode from settings.json,
|
|
483
|
+
* fresh on every call (no caching), like the other readers. Default: mode
|
|
484
|
+
* "shadow".
|
|
485
|
+
*/
|
|
486
|
+
export function getCloseGateWellFormedness(): CloseGateWellFormednessConfig {
|
|
487
|
+
return resolveCloseGateWellFormedness(
|
|
488
|
+
readSettings().braid?.orchestrator?.closeGateWellFormedness,
|
|
489
|
+
);
|
|
490
|
+
}
|
|
491
|
+
|
|
418
492
|
/**
|
|
419
493
|
* Read the braid.memory.writeGate block from settings.json.
|
|
420
494
|
*
|
|
@@ -27,9 +27,8 @@ export const NUDGE_COOLDOWN_MS = 5 * 60 * 1000; // 5 minutes
|
|
|
27
27
|
* retry end). Distinct from the 5-minute `NUDGE_COOLDOWN_MS` which is
|
|
28
28
|
* a cross-session cap; this is the per-site rate-limit value.
|
|
29
29
|
*
|
|
30
|
-
*
|
|
31
|
-
* rely on NudgeManager) needs per-NudgeType cooldown decisions
|
|
32
|
-
* is deferred.
|
|
30
|
+
* Promote to constant is deferred: the "remove" path (delete the field,
|
|
31
|
+
* rely on NudgeManager) needs per-NudgeType cooldown decisions.
|
|
33
32
|
*/
|
|
34
33
|
export const ERROR_TRACKING_NUDGE_COOLDOWN_MS = 60_000; // 1 minute
|
|
35
34
|
|
|
@@ -80,8 +80,8 @@ export const PER_SOURCE_CAP = 2;
|
|
|
80
80
|
* caps than PER_SOURCE_CAP are NOT supported via overrides - if a
|
|
81
81
|
* source needs a lower cap, add a new explicit value here.
|
|
82
82
|
*
|
|
83
|
-
*
|
|
84
|
-
*
|
|
83
|
+
* Drop the all-sources-share cap so high-priority sources can get
|
|
84
|
+
* through during a degraded turn.
|
|
85
85
|
*/
|
|
86
86
|
export const PER_SOURCE_CAP_OVERRIDES: Record<string, number> = {
|
|
87
87
|
// Enforcement whispers are critical/high priority. A 3rd
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
<!-- status: current -->
|
|
2
2
|
|
|
3
|
-
# Self-Harness Loop
|
|
3
|
+
# Self-Harness Loop: src/lib/harness/
|
|
4
4
|
|
|
5
5
|
Failure collection and weakness mining. `failure-trace-collector.ts` observes the
|
|
6
6
|
tool-loop detector's per-session state (written by the enforcement extension on
|
package/src/lib/harness/index.ts
CHANGED
package/src/lib/harness/types.ts
CHANGED
|
@@ -45,12 +45,25 @@ export {
|
|
|
45
45
|
closeWorker,
|
|
46
46
|
recordWorkerMerge,
|
|
47
47
|
validateResultSchema,
|
|
48
|
+
locateResultSchema,
|
|
48
49
|
evaluateWorker,
|
|
49
50
|
checkWorker,
|
|
50
51
|
computeWorkerStats,
|
|
51
52
|
WORKER_EFFECT_EVIDENCE_FLAG,
|
|
52
53
|
workerEffectEvidence,
|
|
53
54
|
workerEffectEvidenceForEntry,
|
|
55
|
+
firstCommandToken,
|
|
56
|
+
findTopLevelDecoration,
|
|
57
|
+
findGateRowViolation,
|
|
58
|
+
closeGateRefusalLogPath,
|
|
59
|
+
logCloseGateRefusal,
|
|
60
|
+
parsePopulationStamp,
|
|
61
|
+
readPopulationStamps,
|
|
62
|
+
populationRefusalDetail,
|
|
63
|
+
productionWriteClassPath,
|
|
64
|
+
readProductionWriteClass,
|
|
65
|
+
readProductionWrites,
|
|
66
|
+
productionWriteRefusalDetail,
|
|
54
67
|
} from "./workers.js";
|
|
55
68
|
|
|
56
69
|
export type {
|
|
@@ -75,4 +88,17 @@ export type {
|
|
|
75
88
|
WorkerEffectFacts,
|
|
76
89
|
WorkerStats,
|
|
77
90
|
WorkerLatencySummary,
|
|
91
|
+
GateRowPredicate,
|
|
92
|
+
GateRowViolation,
|
|
93
|
+
CloseGateRefusalRecord,
|
|
94
|
+
ResultSchemaLocation,
|
|
95
|
+
PopulationStamp,
|
|
96
|
+
PopulationVerdict,
|
|
97
|
+
PopulationRowRead,
|
|
98
|
+
PopulationRead,
|
|
99
|
+
PopulationCensus,
|
|
100
|
+
ProductionWriteRule,
|
|
101
|
+
ProductionWriteClass,
|
|
102
|
+
ProductionWriteRowRead,
|
|
103
|
+
ProductionWriteRead,
|
|
78
104
|
} from "./workers.js";
|