pi-braid 0.40.0 → 0.40.2
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 +39 -33
- package/TOOLS.md +27 -3
- package/build-info.json +9 -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/core/prompt-builder/inspect.js +9 -3
- 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-navigate.js +4 -1
- 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/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/BEGINNERS.md +22 -0
- package/docs/CONTEXT-POLICY.md +13 -5
- package/docs/LOCAL_DEV.md +31 -5
- package/docs/ROADMAP.md +10 -7
- package/docs/SETUP.md +86 -42
- 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/hypothesize.ts +14 -1
- package/src/extensions/cognitive/metacognition/handlers/verify.ts +39 -5
- package/src/extensions/core/prompt-builder/inspect.ts +10 -3
- 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-navigate.ts +4 -1
- 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/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
|
@@ -19,11 +19,14 @@
|
|
|
19
19
|
* Writes are atomic (temp file + rename) with mode 0600. Reads tolerate a
|
|
20
20
|
* missing or corrupt file by returning an empty registry, like locks.ts.
|
|
21
21
|
*/
|
|
22
|
-
import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
|
|
22
|
+
import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
|
|
23
23
|
import { execFileSync } from "node:child_process";
|
|
24
24
|
import { dirname, join } from "node:path";
|
|
25
|
-
import { getWorkersFilePath, projectsDir } from "../config/braid-paths.js";
|
|
25
|
+
import { braidDir, getWorkersFilePath, projectsDir } from "../config/braid-paths.js";
|
|
26
|
+
import { getCloseGateWellFormedness } from "../config/braid-settings.js";
|
|
27
|
+
import { createLogger } from "../core/logger.js";
|
|
26
28
|
import { getAllLocks, releaseLock } from "./locks.js";
|
|
29
|
+
const log = createLogger("orchestrator:workers");
|
|
27
30
|
// ── Constants ──────────────────────────────────────────────────────────────
|
|
28
31
|
export const WORKER_REGISTRY_VERSION = 1;
|
|
29
32
|
/**
|
|
@@ -466,14 +469,476 @@ function assertGateEvidence(workerId, outcome, gates) {
|
|
|
466
469
|
if (!gate || typeof gate !== "object" || Array.isArray(gate)) {
|
|
467
470
|
throw new Error(`closeWorker: gates[${i}] must be an object carrying cmd and exit (worker ${workerId})`);
|
|
468
471
|
}
|
|
469
|
-
const { cmd, exit } = gate;
|
|
472
|
+
const { cmd, exit, stamp } = gate;
|
|
470
473
|
if (typeof cmd !== "string" || cmd.trim() === "") {
|
|
471
474
|
throw new Error(`closeWorker: gates[${i}].cmd must be a non-empty string (worker ${workerId})`);
|
|
472
475
|
}
|
|
473
476
|
if (typeof exit !== "number" || !Number.isFinite(exit)) {
|
|
474
477
|
throw new Error(`closeWorker: gates[${i}].exit must be a number (worker ${workerId})`);
|
|
475
478
|
}
|
|
479
|
+
// Only the field's type is decided here: whether a stamp is the contract's
|
|
480
|
+
// shape, or is missing from a gate that scanned a population, is the
|
|
481
|
+
// readers' business (the result validator warns; the merge path compares).
|
|
482
|
+
// A non-string stamp cannot be read by either, so it is a shape refusal.
|
|
483
|
+
if (stamp !== undefined && typeof stamp !== "string") {
|
|
484
|
+
throw new Error(`closeWorker: gates[${i}].stamp must be a string (worker ${workerId})`);
|
|
485
|
+
}
|
|
486
|
+
}
|
|
487
|
+
}
|
|
488
|
+
/** One leading `VAR=value` assignment, quoted value or not. */
|
|
489
|
+
const ENV_ASSIGNMENT_RE = /^\s*[A-Za-z_][A-Za-z0-9_]*=(?:"(?:[^"\\]|\\.)*"|'[^']*'|[^\s]*)(?=\s|$)/;
|
|
490
|
+
/**
|
|
491
|
+
* Strip leading env assignments one at a time. A single-assignment regex
|
|
492
|
+
* applied in a loop, rather than one repeated group: the repeated form
|
|
493
|
+
* backtracks over the whole field when it fails to match, and this runs before
|
|
494
|
+
* any row is judged, on a field a caller controls.
|
|
495
|
+
*/
|
|
496
|
+
function stripLeadingEnvAssignments(cmd) {
|
|
497
|
+
let rest = cmd;
|
|
498
|
+
for (;;) {
|
|
499
|
+
const match = rest.match(ENV_ASSIGNMENT_RE);
|
|
500
|
+
if (!match)
|
|
501
|
+
return rest;
|
|
502
|
+
rest = rest.slice(match[0].length);
|
|
503
|
+
}
|
|
504
|
+
}
|
|
505
|
+
/** The first whitespace-delimited token after leading env assignments, or null. */
|
|
506
|
+
export function firstCommandToken(cmd) {
|
|
507
|
+
const rest = stripLeadingEnvAssignments(cmd).trimStart();
|
|
508
|
+
const token = rest.split(/\s+/, 1)[0];
|
|
509
|
+
return token.length > 0 ? token : null;
|
|
510
|
+
}
|
|
511
|
+
function runShell(args) {
|
|
512
|
+
try {
|
|
513
|
+
execFileSync("sh", args, {
|
|
514
|
+
stdio: ["ignore", "ignore", "pipe"],
|
|
515
|
+
encoding: "utf8",
|
|
516
|
+
timeout: 5000,
|
|
517
|
+
});
|
|
518
|
+
return { ok: true };
|
|
519
|
+
}
|
|
520
|
+
catch (error) {
|
|
521
|
+
const e = error;
|
|
522
|
+
if (e.code === "ENOENT")
|
|
523
|
+
return { unavailable: true };
|
|
524
|
+
if (e.code === "ERR_INVALID_ARG_VALUE") {
|
|
525
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
526
|
+
return { ok: false, detail: `sh rejected the field (${message})` };
|
|
527
|
+
}
|
|
528
|
+
if (e.status == null)
|
|
529
|
+
return { unavailable: true };
|
|
530
|
+
const stderr = typeof e.stderr === "string" ? e.stderr : "";
|
|
531
|
+
const line = stderr
|
|
532
|
+
.split("\n")
|
|
533
|
+
.map((candidate) => candidate.trim())
|
|
534
|
+
.find((candidate) => candidate.length > 0);
|
|
535
|
+
return { ok: false, detail: line ?? `sh exited ${String(e.status)}` };
|
|
536
|
+
}
|
|
537
|
+
}
|
|
538
|
+
/**
|
|
539
|
+
* The (c) instrument: a top-level decoration that makes the field more than
|
|
540
|
+
* the command, so the recorded exit cannot be attributed to what the field
|
|
541
|
+
* names: an unquoted `;` or newline (whatever follows owns the exit), a
|
|
542
|
+
* background `&` (the shell owns it), or a word-starting `#` (the field
|
|
543
|
+
* carries a comment). Quotes, command substitutions and redirections are
|
|
544
|
+
* shell syntax rather than decorations and are skipped, so `2>&1 | tail`,
|
|
545
|
+
* `cd x && npm run ci:check` and a quoted `';'` stay accepted. Returns the
|
|
546
|
+
* decoration found, or null when the field carries none.
|
|
547
|
+
*/
|
|
548
|
+
export function findTopLevelDecoration(cmd) {
|
|
549
|
+
const frames = ["top"];
|
|
550
|
+
let quote = null;
|
|
551
|
+
let wordStart = true;
|
|
552
|
+
for (let i = 0; i < cmd.length; i++) {
|
|
553
|
+
const ch = cmd[i];
|
|
554
|
+
const next = cmd[i + 1];
|
|
555
|
+
if (quote === "single") {
|
|
556
|
+
if (ch === "'")
|
|
557
|
+
quote = null;
|
|
558
|
+
continue;
|
|
559
|
+
}
|
|
560
|
+
if (quote === "backtick") {
|
|
561
|
+
if (ch === "\\")
|
|
562
|
+
i++;
|
|
563
|
+
else if (ch === "`")
|
|
564
|
+
quote = null;
|
|
565
|
+
continue;
|
|
566
|
+
}
|
|
567
|
+
if (quote === "double") {
|
|
568
|
+
if (ch === "\\")
|
|
569
|
+
i++;
|
|
570
|
+
else if (ch === '"')
|
|
571
|
+
quote = null;
|
|
572
|
+
else if (ch === "$" && next === "(") {
|
|
573
|
+
frames.push("subst");
|
|
574
|
+
i++;
|
|
575
|
+
}
|
|
576
|
+
else if (ch === "`")
|
|
577
|
+
quote = "backtick";
|
|
578
|
+
continue;
|
|
579
|
+
}
|
|
580
|
+
// Unquoted: at the top level, or inside a command substitution.
|
|
581
|
+
if (ch === "\\") {
|
|
582
|
+
i++;
|
|
583
|
+
continue;
|
|
584
|
+
}
|
|
585
|
+
if (ch === "'") {
|
|
586
|
+
quote = "single";
|
|
587
|
+
wordStart = false;
|
|
588
|
+
continue;
|
|
589
|
+
}
|
|
590
|
+
if (ch === '"') {
|
|
591
|
+
quote = "double";
|
|
592
|
+
wordStart = false;
|
|
593
|
+
continue;
|
|
594
|
+
}
|
|
595
|
+
if (ch === "`") {
|
|
596
|
+
quote = "backtick";
|
|
597
|
+
wordStart = false;
|
|
598
|
+
continue;
|
|
599
|
+
}
|
|
600
|
+
if (ch === "$" && next === "(") {
|
|
601
|
+
frames.push("subst");
|
|
602
|
+
i++;
|
|
603
|
+
wordStart = false;
|
|
604
|
+
continue;
|
|
605
|
+
}
|
|
606
|
+
if (frames[frames.length - 1] === "subst") {
|
|
607
|
+
if (ch === "(")
|
|
608
|
+
frames.push("subst");
|
|
609
|
+
else if (ch === ")")
|
|
610
|
+
frames.pop();
|
|
611
|
+
continue;
|
|
612
|
+
}
|
|
613
|
+
if (ch === ";")
|
|
614
|
+
return ";";
|
|
615
|
+
if (ch === "\n")
|
|
616
|
+
return "newline";
|
|
617
|
+
if (ch === "#" && wordStart)
|
|
618
|
+
return "comment";
|
|
619
|
+
if (ch === "&") {
|
|
620
|
+
const previous = cmd[i - 1];
|
|
621
|
+
const andAnd = next === "&";
|
|
622
|
+
const redirection = previous === ">" || previous === "<" || next === ">";
|
|
623
|
+
if (!andAnd && !redirection)
|
|
624
|
+
return "&";
|
|
625
|
+
if (andAnd)
|
|
626
|
+
i++;
|
|
627
|
+
wordStart = false;
|
|
628
|
+
continue;
|
|
629
|
+
}
|
|
630
|
+
wordStart = ch === " " || ch === "\t";
|
|
631
|
+
}
|
|
632
|
+
return null;
|
|
633
|
+
}
|
|
634
|
+
/**
|
|
635
|
+
* Run the four predicates over one recorded row and return the first
|
|
636
|
+
* violation, or null when the row is well formed. (a)/(b) need `sh`; when the
|
|
637
|
+
* shell cannot be spawned they are left unjudged (the string-only (c) and (d)
|
|
638
|
+
* still run), so a missing instrument cannot fail every row.
|
|
639
|
+
*/
|
|
640
|
+
export function findGateRowViolation(cmd, exit, outcome) {
|
|
641
|
+
const parse = runShell(["-n", "-c", cmd]);
|
|
642
|
+
if ("ok" in parse && !parse.ok) {
|
|
643
|
+
return { predicate: "a", detail: `does not parse under sh -n (${parse.detail})` };
|
|
644
|
+
}
|
|
645
|
+
if ("ok" in parse) {
|
|
646
|
+
const token = firstCommandToken(cmd);
|
|
647
|
+
if (token === null) {
|
|
648
|
+
return { predicate: "b", detail: "no command token after the env prefixes" };
|
|
649
|
+
}
|
|
650
|
+
const resolved = runShell(["-c", 'command -v "$1" >/dev/null 2>&1', "sh", token]);
|
|
651
|
+
if ("ok" in resolved && !resolved.ok) {
|
|
652
|
+
return { predicate: "b", detail: `first token "${token}" does not resolve to an executable` };
|
|
653
|
+
}
|
|
654
|
+
}
|
|
655
|
+
const decoration = findTopLevelDecoration(cmd);
|
|
656
|
+
if (decoration !== null) {
|
|
657
|
+
return {
|
|
658
|
+
predicate: "c",
|
|
659
|
+
detail: `top-level ${decoration}: not the command alone`,
|
|
660
|
+
};
|
|
661
|
+
}
|
|
662
|
+
if (outcome === "completed" && exit !== 0) {
|
|
663
|
+
return { predicate: "d", detail: `exit ${exit} recorded under a completed outcome` };
|
|
664
|
+
}
|
|
665
|
+
return null;
|
|
666
|
+
}
|
|
667
|
+
/** Where close-gate refusals land: one JSONL line per failing row. */
|
|
668
|
+
export function closeGateRefusalLogPath() {
|
|
669
|
+
return join(braidDir(), "orchestrator", "close-gate-refusals.jsonl");
|
|
670
|
+
}
|
|
671
|
+
/** Warned once per process about an unwritable refusal log. */
|
|
672
|
+
let _warnedRefusalLogFailure = false;
|
|
673
|
+
/**
|
|
674
|
+
* Append one refusal line. Never throws: a failed append warns once and
|
|
675
|
+
* leaves the close's own behavior untouched, so an unwritable braid root
|
|
676
|
+
* cannot refuse a close that shadow mode would have accepted.
|
|
677
|
+
*/
|
|
678
|
+
export function logCloseGateRefusal(record) {
|
|
679
|
+
try {
|
|
680
|
+
const file = closeGateRefusalLogPath();
|
|
681
|
+
mkdirSync(dirname(file), { recursive: true });
|
|
682
|
+
appendFileSync(file, `${JSON.stringify(record)}\n`, { encoding: "utf8", mode: 0o600 });
|
|
683
|
+
}
|
|
684
|
+
catch (error) {
|
|
685
|
+
if (_warnedRefusalLogFailure)
|
|
686
|
+
return;
|
|
687
|
+
_warnedRefusalLogFailure = true;
|
|
688
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
689
|
+
log.warn(`close-gate refusal log not writable; refusals continue unlogged: ${message}`);
|
|
690
|
+
}
|
|
691
|
+
}
|
|
692
|
+
/** Where the seat publishes the production-write class it owns. */
|
|
693
|
+
export function productionWriteClassPath() {
|
|
694
|
+
return join(braidDir(), "orchestrator", "production-writes.json");
|
|
695
|
+
}
|
|
696
|
+
/** Warned once per process about an unreadable class file. */
|
|
697
|
+
let _warnedProductionWriteClass = false;
|
|
698
|
+
function warnProductionWriteClass(detail) {
|
|
699
|
+
if (_warnedProductionWriteClass)
|
|
700
|
+
return;
|
|
701
|
+
_warnedProductionWriteClass = true;
|
|
702
|
+
log.warn(`production-write class not read (${detail}); closes are not refused for recorded writes`);
|
|
703
|
+
}
|
|
704
|
+
/**
|
|
705
|
+
* Read one array of rules out of the class table, keeping only entries a reader
|
|
706
|
+
* can use: a non-empty id, a non-empty pattern that compiles, and a label
|
|
707
|
+
* (falling back to the id). Junk entries are dropped rather than thrown: the
|
|
708
|
+
* file is seat-edited data, and an unusable one must fail open.
|
|
709
|
+
*/
|
|
710
|
+
function readRuleList(raw) {
|
|
711
|
+
if (!Array.isArray(raw))
|
|
712
|
+
return [];
|
|
713
|
+
const rules = [];
|
|
714
|
+
for (const entry of raw) {
|
|
715
|
+
if (!entry || typeof entry !== "object" || Array.isArray(entry))
|
|
716
|
+
continue;
|
|
717
|
+
const { id, label, pattern, registry } = entry;
|
|
718
|
+
if (typeof id !== "string" || id.trim() === "")
|
|
719
|
+
continue;
|
|
720
|
+
if (typeof pattern !== "string" || pattern === "")
|
|
721
|
+
continue;
|
|
722
|
+
try {
|
|
723
|
+
new RegExp(pattern);
|
|
724
|
+
}
|
|
725
|
+
catch {
|
|
726
|
+
continue;
|
|
727
|
+
}
|
|
728
|
+
rules.push({
|
|
729
|
+
id,
|
|
730
|
+
label: typeof label === "string" && label !== "" ? label : id,
|
|
731
|
+
pattern,
|
|
732
|
+
...(typeof registry === "string" ? { registry } : {}),
|
|
733
|
+
});
|
|
476
734
|
}
|
|
735
|
+
return rules;
|
|
736
|
+
}
|
|
737
|
+
/**
|
|
738
|
+
* Load the class table the seat owns. Never throws: a braid home that cannot be
|
|
739
|
+
* resolved, a missing file, an unreadable file and a malformed one all yield an
|
|
740
|
+
* empty class, which refuses nothing.
|
|
741
|
+
*/
|
|
742
|
+
export function readProductionWriteClass(file) {
|
|
743
|
+
const empty = { members: [], pieces: [] };
|
|
744
|
+
let path;
|
|
745
|
+
try {
|
|
746
|
+
path = file ?? productionWriteClassPath();
|
|
747
|
+
}
|
|
748
|
+
catch (error) {
|
|
749
|
+
warnProductionWriteClass(error instanceof Error ? error.message : String(error));
|
|
750
|
+
return empty;
|
|
751
|
+
}
|
|
752
|
+
let parsed;
|
|
753
|
+
try {
|
|
754
|
+
parsed = JSON.parse(readFileSync(path, "utf-8"));
|
|
755
|
+
}
|
|
756
|
+
catch (error) {
|
|
757
|
+
const code = error.code;
|
|
758
|
+
if (code !== "ENOENT") {
|
|
759
|
+
warnProductionWriteClass(`${path}: ${error instanceof Error ? error.message : String(error)}`);
|
|
760
|
+
}
|
|
761
|
+
return empty;
|
|
762
|
+
}
|
|
763
|
+
if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
|
|
764
|
+
warnProductionWriteClass(`${path}: top level is not an object`);
|
|
765
|
+
return empty;
|
|
766
|
+
}
|
|
767
|
+
const table = parsed;
|
|
768
|
+
const pieces = table.preflight?.pieces;
|
|
769
|
+
return { members: readRuleList(table.members), pieces: readRuleList(pieces) };
|
|
770
|
+
}
|
|
771
|
+
/** Compile a rule list, dropping any pattern that does not compile. */
|
|
772
|
+
function compileProductionWriteRules(rules) {
|
|
773
|
+
const compiled = [];
|
|
774
|
+
for (const rule of rules) {
|
|
775
|
+
try {
|
|
776
|
+
compiled.push({ rule, re: new RegExp(rule.pattern) });
|
|
777
|
+
}
|
|
778
|
+
catch {
|
|
779
|
+
// readRuleList already dropped these; a caller-supplied table may not have.
|
|
780
|
+
}
|
|
781
|
+
}
|
|
782
|
+
return compiled;
|
|
783
|
+
}
|
|
784
|
+
/**
|
|
785
|
+
* Read a close's gate rows for production writes and their preflight evidence.
|
|
786
|
+
* A row is a write when any member pattern matches its cmd — a field carrying a
|
|
787
|
+
* write beside reads is still a write, because the members match the write
|
|
788
|
+
* verbs only. A piece is recorded when any row's cmd matches its pattern, so
|
|
789
|
+
* one composed preflight row and several separate ones both satisfy. Pure over
|
|
790
|
+
* the rows and the table.
|
|
791
|
+
*/
|
|
792
|
+
export function readProductionWrites(rows, table = readProductionWriteClass()) {
|
|
793
|
+
if (!rows || rows.length === 0)
|
|
794
|
+
return { rows: [], unsatisfied: [] };
|
|
795
|
+
const members = compileProductionWriteRules(table.members);
|
|
796
|
+
const pieces = compileProductionWriteRules(table.pieces);
|
|
797
|
+
if (members.length === 0)
|
|
798
|
+
return { rows: [], unsatisfied: [] };
|
|
799
|
+
const cmdAt = (row) => typeof row?.cmd === "string" ? row.cmd : "";
|
|
800
|
+
const writes = [];
|
|
801
|
+
for (let i = 0; i < rows.length; i++) {
|
|
802
|
+
const cmd = cmdAt(rows[i]);
|
|
803
|
+
const member = members.find(({ re }) => re.test(cmd));
|
|
804
|
+
if (!member)
|
|
805
|
+
continue;
|
|
806
|
+
const missing = [];
|
|
807
|
+
const preflightRows = new Set();
|
|
808
|
+
for (const piece of pieces) {
|
|
809
|
+
let recorded = false;
|
|
810
|
+
for (let j = 0; j < rows.length; j++) {
|
|
811
|
+
if (piece.re.test(cmdAt(rows[j]))) {
|
|
812
|
+
recorded = true;
|
|
813
|
+
preflightRows.add(j);
|
|
814
|
+
}
|
|
815
|
+
}
|
|
816
|
+
if (!recorded)
|
|
817
|
+
missing.push(piece.rule.id);
|
|
818
|
+
}
|
|
819
|
+
writes.push({
|
|
820
|
+
row: i,
|
|
821
|
+
cmd,
|
|
822
|
+
member: member.rule.id,
|
|
823
|
+
preflightRows: [...preflightRows].sort((a, b) => a - b),
|
|
824
|
+
missingPieces: missing,
|
|
825
|
+
});
|
|
826
|
+
}
|
|
827
|
+
return { rows: writes, unsatisfied: writes.filter((row) => row.missingPieces.length > 0) };
|
|
828
|
+
}
|
|
829
|
+
/**
|
|
830
|
+
* The refusal sentence for the first write row missing a piece: its index, the
|
|
831
|
+
* member, the missing piece ids and the command. Null when every write row is
|
|
832
|
+
* satisfied, so a caller cannot refuse on an empty read.
|
|
833
|
+
*/
|
|
834
|
+
export function productionWriteRefusalDetail(read) {
|
|
835
|
+
const row = read.unsatisfied[0];
|
|
836
|
+
if (!row)
|
|
837
|
+
return null;
|
|
838
|
+
return (`gates[${row.row}] records a production write ("${row.member}") without a complete ` +
|
|
839
|
+
`preflight row: missing pieces: ${row.missingPieces.join(", ")}; cmd: ${row.cmd}`);
|
|
840
|
+
}
|
|
841
|
+
/**
|
|
842
|
+
* Bare-token revision rules: an all-hex token is a sha only at 7-40 chars, so
|
|
843
|
+
* a six-char prefix does not slip through the ref-name alternative as a
|
|
844
|
+
* revision git can never resolve.
|
|
845
|
+
*/
|
|
846
|
+
const POPULATION_STAMP_RE = /^scanned (\d+) ([a-z]+) at ([0-9a-fA-F]{7,40}|[A-Za-z0-9][A-Za-z0-9._/-]*)$/;
|
|
847
|
+
const ALL_HEX_RE = /^[0-9a-fA-F]+$/;
|
|
848
|
+
/** Parse the stamp shape above; null when the value is not that shape. */
|
|
849
|
+
export function parsePopulationStamp(value) {
|
|
850
|
+
if (typeof value !== "string")
|
|
851
|
+
return null;
|
|
852
|
+
const match = POPULATION_STAMP_RE.exec(value);
|
|
853
|
+
if (!match)
|
|
854
|
+
return null;
|
|
855
|
+
const [, rawN, unit, revision] = match;
|
|
856
|
+
if (ALL_HEX_RE.test(revision) && (revision.length < 7 || revision.length > 40))
|
|
857
|
+
return null;
|
|
858
|
+
return { n: Number(rawN), unit, revision };
|
|
859
|
+
}
|
|
860
|
+
function populationLines(rows) {
|
|
861
|
+
const lines = [];
|
|
862
|
+
for (const row of rows) {
|
|
863
|
+
if (row.verdict === "unreadable") {
|
|
864
|
+
lines.push(`population stamp unreadable: row ${row.row} ${JSON.stringify(row.raw)}`);
|
|
865
|
+
continue;
|
|
866
|
+
}
|
|
867
|
+
if (row.stamp === null || row.stamp.unit !== "files")
|
|
868
|
+
continue;
|
|
869
|
+
if (row.verdict === "unresolved") {
|
|
870
|
+
lines.push(`population delta: recorded ${row.stamp.n} at ${row.stamp.revision} ` +
|
|
871
|
+
`(row ${row.row}; revision unresolved, not compared)`);
|
|
872
|
+
}
|
|
873
|
+
else if (row.census !== null) {
|
|
874
|
+
lines.push(`population delta: recorded ${row.stamp.n} vs census ${row.census} at ` +
|
|
875
|
+
`${row.stamp.revision} (row ${row.row})`);
|
|
876
|
+
}
|
|
877
|
+
}
|
|
878
|
+
if (!rows.some((row) => row.stamp !== null && row.stamp.unit === "files")) {
|
|
879
|
+
lines.push("no recorded population");
|
|
880
|
+
}
|
|
881
|
+
return lines;
|
|
882
|
+
}
|
|
883
|
+
/**
|
|
884
|
+
* Read every gate row for a population stamp and compare the `files` ones
|
|
885
|
+
* against the census the caller supplies for their named revision. Pure: the
|
|
886
|
+
* count is a lookup parameter, so the parse and the comparison are testable
|
|
887
|
+
* without a repository. Rows of another unit are not census subjects and are
|
|
888
|
+
* left uncompared; an unreadable stamp is named, never silently dropped.
|
|
889
|
+
*/
|
|
890
|
+
export function readPopulationStamps(gates, censusAt) {
|
|
891
|
+
const rows = [];
|
|
892
|
+
const list = Array.isArray(gates) ? gates : [];
|
|
893
|
+
for (let i = 0; i < list.length; i++) {
|
|
894
|
+
const gate = list[i];
|
|
895
|
+
const record = gate && typeof gate === "object" && !Array.isArray(gate)
|
|
896
|
+
? gate
|
|
897
|
+
: null;
|
|
898
|
+
const cmd = typeof record?.cmd === "string" ? record.cmd : "";
|
|
899
|
+
const present = record !== null && record.stamp !== undefined;
|
|
900
|
+
const raw = present ? record.stamp : undefined;
|
|
901
|
+
const stamp = present ? parsePopulationStamp(raw) : null;
|
|
902
|
+
let census = null;
|
|
903
|
+
let delta = null;
|
|
904
|
+
let verdict;
|
|
905
|
+
if (!present)
|
|
906
|
+
verdict = "absent";
|
|
907
|
+
else if (stamp === null)
|
|
908
|
+
verdict = "unreadable";
|
|
909
|
+
else if (stamp.unit !== "files")
|
|
910
|
+
verdict = "other-subject";
|
|
911
|
+
else {
|
|
912
|
+
census = censusAt(stamp.revision);
|
|
913
|
+
if (census === null)
|
|
914
|
+
verdict = "unresolved";
|
|
915
|
+
else {
|
|
916
|
+
delta = census - stamp.n;
|
|
917
|
+
verdict = delta === 0 ? "match" : delta > 0 ? "below" : "above";
|
|
918
|
+
}
|
|
919
|
+
}
|
|
920
|
+
rows.push({ row: i, cmd, raw, present, stamp, census, delta, verdict });
|
|
921
|
+
}
|
|
922
|
+
return {
|
|
923
|
+
rows,
|
|
924
|
+
comparisons: rows.filter((row) => row.stamp !== null && row.census !== null),
|
|
925
|
+
standing: rows.find((row) => row.verdict === "below") ?? null,
|
|
926
|
+
recorded: rows.some((row) => row.stamp !== null && row.stamp.unit === "files"),
|
|
927
|
+
lines: populationLines(rows),
|
|
928
|
+
};
|
|
929
|
+
}
|
|
930
|
+
/**
|
|
931
|
+
* The refusal sentence for the first standing delta: row index, stamp, census,
|
|
932
|
+
* delta, and the remedy. Null when no comparison sits below its census, so a
|
|
933
|
+
* caller cannot refuse on an empty read.
|
|
934
|
+
*/
|
|
935
|
+
export function populationRefusalDetail(read) {
|
|
936
|
+
const row = read.standing;
|
|
937
|
+
if (!row || row.stamp === null || row.census === null || row.delta === null)
|
|
938
|
+
return null;
|
|
939
|
+
return (`row ${row.row} stamp "scanned ${row.stamp.n} ${row.stamp.unit} at ${row.stamp.revision}" ` +
|
|
940
|
+
`records ${row.stamp.n} but the census at ${row.stamp.revision} is ${row.census} ` +
|
|
941
|
+
`(delta ${row.delta}); re-run the gate on the staged tree and re-issue the close`);
|
|
477
942
|
}
|
|
478
943
|
/**
|
|
479
944
|
* Close an entry with a terminal outcome and optional gate evidence.
|
|
@@ -484,8 +949,24 @@ function assertGateEvidence(workerId, outcome, gates) {
|
|
|
484
949
|
* A completed close carries evidence: the reporter contract requires a
|
|
485
950
|
* non-empty `gate_evidence` block, and a probe measured this path storing a
|
|
486
951
|
* bare `completed` with no gates at all. That contradiction is refused now,
|
|
487
|
-
* and each provided gate is shape-checked (non-empty `cmd`, numeric `exit
|
|
488
|
-
* before any write — a violation leaves the row
|
|
952
|
+
* and each provided gate is shape-checked (non-empty `cmd`, numeric `exit`,
|
|
953
|
+
* string `stamp` when present) before any write — a violation leaves the row
|
|
954
|
+
* and the lock table untouched. A valid `stamp` is stored verbatim, so the
|
|
955
|
+
* merge path can read the recorded population off the row.
|
|
956
|
+
*
|
|
957
|
+
* Every provided row is then read for well-formedness: its `cmd` must parse
|
|
958
|
+
* under `sh -n`, resolve its first token, and name the command alone, and a
|
|
959
|
+
* completed close's exits must be 0. The mode is settings-driven
|
|
960
|
+
* (`braid.orchestrator.closeGateWellFormedness`): "shadow" (default) records
|
|
961
|
+
* a refusal line and proceeds, "enforce" refuses before any write or lock
|
|
962
|
+
* release, "off" skips the read. No gate is re-run; replay stays the
|
|
963
|
+
* sampler's sampled job.
|
|
964
|
+
*
|
|
965
|
+
* Every row is also read against the seat's production-write class: a row the
|
|
966
|
+
* class marks as a write is refused unless the close records every named
|
|
967
|
+
* preflight piece (identity, registry, dry-run) somewhere in its rows. The
|
|
968
|
+
* class lives in the seat's data file; when it is absent the class is empty and
|
|
969
|
+
* nothing is refused.
|
|
489
970
|
*
|
|
490
971
|
* Releases the worker's file locks: close is terminal, and a lock that
|
|
491
972
|
* survives it blocks the next spawn on the same files. The release runs with
|
|
@@ -501,6 +982,35 @@ export function closeWorker(workerId, outcome, gates, cwd) {
|
|
|
501
982
|
if (entry.closedAt)
|
|
502
983
|
return entry;
|
|
503
984
|
assertGateEvidence(workerId, parsed, gates);
|
|
985
|
+
const wellFormedness = getCloseGateWellFormedness();
|
|
986
|
+
if (wellFormedness.mode !== "off" && gates && gates.length > 0) {
|
|
987
|
+
for (let i = 0; i < gates.length; i++) {
|
|
988
|
+
const violation = findGateRowViolation(gates[i].cmd, gates[i].exit, parsed);
|
|
989
|
+
if (!violation)
|
|
990
|
+
continue;
|
|
991
|
+
logCloseGateRefusal({
|
|
992
|
+
at: new Date().toISOString(),
|
|
993
|
+
workerId,
|
|
994
|
+
row: i,
|
|
995
|
+
predicate: violation.predicate,
|
|
996
|
+
cmd: gates[i].cmd,
|
|
997
|
+
mode: wellFormedness.mode,
|
|
998
|
+
outcome: parsed,
|
|
999
|
+
detail: violation.detail,
|
|
1000
|
+
});
|
|
1001
|
+
if (wellFormedness.mode === "enforce") {
|
|
1002
|
+
throw new Error(`closeWorker: gates[${i}] fails predicate (${violation.predicate}): ${violation.detail}; ` +
|
|
1003
|
+
`cmd: ${gates[i].cmd} (worker ${workerId}, outcome ${parsed})`);
|
|
1004
|
+
}
|
|
1005
|
+
}
|
|
1006
|
+
}
|
|
1007
|
+
// A recorded production write must carry its preflight evidence. The class
|
|
1008
|
+
// table is the seat's data, and an absent one reads as empty (fail-open), so
|
|
1009
|
+
// this refuses only what the seat has declared a write without its pieces.
|
|
1010
|
+
const productionRefusal = productionWriteRefusalDetail(readProductionWrites(gates, readProductionWriteClass()));
|
|
1011
|
+
if (productionRefusal) {
|
|
1012
|
+
throw new Error(`closeWorker: ${productionRefusal} (worker ${workerId}, outcome ${parsed})`);
|
|
1013
|
+
}
|
|
504
1014
|
releaseLock(workerId, located.key);
|
|
505
1015
|
const nowIso = new Date().toISOString();
|
|
506
1016
|
entry.status = parsed;
|
|
@@ -510,7 +1020,12 @@ export function closeWorker(workerId, outcome, gates, cwd) {
|
|
|
510
1020
|
entry.resultAt = nowIso;
|
|
511
1021
|
if (gates && gates.length > 0) {
|
|
512
1022
|
for (const gate of gates) {
|
|
513
|
-
entry.gates.push({
|
|
1023
|
+
entry.gates.push({
|
|
1024
|
+
cmd: gate.cmd,
|
|
1025
|
+
exit: gate.exit,
|
|
1026
|
+
at: nowIso,
|
|
1027
|
+
...(gate.stamp === undefined ? {} : { stamp: gate.stamp }),
|
|
1028
|
+
});
|
|
514
1029
|
}
|
|
515
1030
|
}
|
|
516
1031
|
writeWorkers(located.registry, located.key);
|
|
@@ -558,7 +558,7 @@ wakeDefer) {
|
|
|
558
558
|
`(source: ${injectionMeta.source})`);
|
|
559
559
|
return false;
|
|
560
560
|
}
|
|
561
|
-
//
|
|
561
|
+
// Apply the universal whisper envelope so the agent
|
|
562
562
|
// can distinguish system-injected messages from human user input. Done
|
|
563
563
|
// before the flood cap so the tracked (and potentially suppressed)
|
|
564
564
|
// content reflects what would have been delivered. See
|
package/docs/BEGINNERS.md
CHANGED
|
@@ -23,6 +23,28 @@ It is a monorepo of five workspaces; the one you care about first is
|
|
|
23
23
|
|
|
24
24
|
## 2. Install
|
|
25
25
|
|
|
26
|
+
The fast way, from npm:
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
pi install npm:pi-braid
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
`pi install` registers the package with pi in `~/.pi/agent/settings.json` and
|
|
33
|
+
installs it under pi's npm directory, so there is nothing to clone and nothing
|
|
34
|
+
to build. This one package carries the metacognitive suite and the core skill
|
|
35
|
+
set; the other packages are add-ons:
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
pi install npm:pi-braid-skills # the on-demand skill pack (per project)
|
|
39
|
+
pi install npm:pi-braid-contrib # standalone tool extensions
|
|
40
|
+
pi install npm:pi-braid-providers # extra LLM providers
|
|
41
|
+
pi install npm:pi-braid-telegram # bidirectional Telegram channel
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
### Working from a checkout
|
|
45
|
+
|
|
46
|
+
If you want to modify braid or run the latest `main`, clone and build instead:
|
|
47
|
+
|
|
26
48
|
```bash
|
|
27
49
|
git clone https://github.com/kifirkin/pi-braid.git ~/pi-braid
|
|
28
50
|
cd ~/pi-braid && npm install && npm run build
|
package/docs/CONTEXT-POLICY.md
CHANGED
|
@@ -38,6 +38,14 @@ usage; hygiene acts re-arm at most once every three turns.
|
|
|
38
38
|
Owner: [`src/lib/detection/context-thresholds.ts`](../src/lib/detection/context-thresholds.ts)
|
|
39
39
|
(single home; consumers import, never restate).
|
|
40
40
|
|
|
41
|
+
### Usage-driven slide compaction
|
|
42
|
+
|
|
43
|
+
| Setting | Default | Effect | Read cadence |
|
|
44
|
+
| ---------------------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
|
|
45
|
+
| `braid.context.contextAutoCompact` | `{ enabled: true, armPercent: 60, confirmTicks: 2 }` | When live usage stays at or above `armPercent` for `confirmTicks` consecutive heartbeat observations, queues one deterministic slide for the next turn boundary. Set `enabled: false` to turn off this automatic arm. | Re-read at use time, on each heartbeat observation. |
|
|
46
|
+
|
|
47
|
+
Owner: [`src/lib/config/braid-settings.ts`](../src/lib/config/braid-settings.ts); auto-arm runs in [`src/extensions/memory/context-manager/handlers/tools/context-compress.ts`](../src/extensions/memory/context-manager/handlers/tools/context-compress.ts).
|
|
48
|
+
|
|
41
49
|
## The compaction reserve
|
|
42
50
|
|
|
43
51
|
pi-core fires native threshold compaction when `contextTokens > contextWindow −
|
|
@@ -58,11 +66,11 @@ from [`src/extensions/core/polyfill/index.ts`](../src/extensions/core/polyfill/i
|
|
|
58
66
|
|
|
59
67
|
## Caps and offload
|
|
60
68
|
|
|
61
|
-
| Setting
|
|
62
|
-
|
|
|
63
|
-
| `braid.context.toolResultSizeCap`
|
|
64
|
-
| `braid.context.staleToolResultOffload`
|
|
65
|
-
| `braid.context.contextEmergencyOffload`
|
|
69
|
+
| Setting | Default | Effect | Read cadence |
|
|
70
|
+
| ----------------------------------------------------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ |
|
|
71
|
+
| `braid.context.toolResultSizeCap` (`enabled`; `maxChars`: `braid.context.toolResultSizeCap.maxChars`) | `enabled: true`, `maxChars: 262144` | Set `enabled: false` to turn off this cap. Results above `maxChars` are flushed losslessly to disk and replaced by a stub naming the file. | Re-read at use time on each tool result and offload recovery call. |
|
|
72
|
+
| `braid.context.staleToolResultOffload` | OFF | Age/size offload of stale large results (`minChars` 4000, `stalenessTurns` 40, `keepRecentTurns` 20, 65536/run). | Re-read at use time. |
|
|
73
|
+
| `braid.context.contextEmergencyOffload` | ON | On a context-window (413) error: offload the largest results, then retry once (`minChars` 262144, 1048576/run). | Re-read at use time. |
|
|
66
74
|
|
|
67
75
|
Offloaded payloads land at `<braid home>/offload/<sessionId>/<toolName>-<toolCallId>.txt`
|
|
68
76
|
(`offloadDir()` / `getOffloadFilePath` in
|