pi-braid 0.40.1 → 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 +13 -13
- 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/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/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/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
|
package/docs/LOCAL_DEV.md
CHANGED
|
@@ -16,8 +16,10 @@ For one-time setup, the full install-path catalog, and module toggling see
|
|
|
16
16
|
| git | any | `git --version` |
|
|
17
17
|
| pi | peer-resolved | `which pi && pi --version` |
|
|
18
18
|
|
|
19
|
-
The Node floor is the `engines` field in every workspace manifest;
|
|
20
|
-
|
|
19
|
+
The Node floor is the `engines` field in every workspace manifest; the pi floor
|
|
20
|
+
is the `@earendil-works/*` peer range in the same manifests (a caret on the
|
|
21
|
+
family the seat runs, kept moving by the update pipeline). If this table and a
|
|
22
|
+
manifest ever disagree, trust the manifest.
|
|
21
23
|
|
|
22
24
|
## Monorepo layout
|
|
23
25
|
|
|
@@ -136,6 +138,26 @@ Example: `0.40.0-main.17`. When `package.json` already carries a full
|
|
|
136
138
|
versioned release string (e.g. `0.40.0-main.17`), it is used verbatim instead
|
|
137
139
|
of being double-suffixed.
|
|
138
140
|
|
|
141
|
+
### Provenance in the tarball
|
|
142
|
+
|
|
143
|
+
Every artifact carries `build-info.json` - package name, packed version, commit
|
|
144
|
+
sha and branch, dirty flag, pack time (`scripts/build-info.mjs` is the one
|
|
145
|
+
generator). It is written by each workspace's `prepack` (`scripts/pack-provenance.mjs`),
|
|
146
|
+
expanded into the `files` allowlist of every package, and removed by `postpack`,
|
|
147
|
+
so an `npm publish` pays the same step a plain `npm pack` does and the checkout
|
|
148
|
+
ends as it started. `publish-local` reads git before the version bump and
|
|
149
|
+
writes the record from that read, so the recorded `dirty` is the pre-bump
|
|
150
|
+
state; it carries the `BRAID_PROVENANCE_DEFER` marker into the pack, and the
|
|
151
|
+
prepack step keeps a record only under that marker, because the temporary bump
|
|
152
|
+
would otherwise read as a dirty tree. A record a killed pack left
|
|
153
|
+
behind is regenerated from a fresh read - a matching version and commit are not
|
|
154
|
+
enough to defer to.
|
|
155
|
+
|
|
156
|
+
Read the record to tell two builds of the same version apart, and to check what
|
|
157
|
+
a stranger installed: `sha` plus `dirty == false` is the pair that means the
|
|
158
|
+
tarball is a clean checkout of a named commit - a version string identifies
|
|
159
|
+
neither.
|
|
160
|
+
|
|
139
161
|
## Upstream pi update pipeline
|
|
140
162
|
|
|
141
163
|
`update-pipeline.mjs` codifies the full update run for the pair - the braid
|
|
@@ -151,11 +173,15 @@ npm run release:update:runtime -- --yes # real sequence plus `pi update` (last)
|
|
|
151
173
|
Default mode writes nothing. It resolves the upstream pi version, compares it
|
|
152
174
|
against the repo pins and the local-packages resolution, and prints the target
|
|
153
175
|
version, every pin it would change (file, field, from -> to), the braid version
|
|
154
|
-
bump, the publish commands, the runtime command, and the rollback commands.
|
|
176
|
+
bump, the publish commands, the runtime command, and the rollback commands. The
|
|
177
|
+
host-family peers are pins here too: each workspace manifest declares the
|
|
178
|
+
`@earendil-works/*` peers (and `typebox`) as an explicit caret floor, and the
|
|
179
|
+
plan rewrites those ranges alongside the exact pins, so the floor moves with
|
|
180
|
+
the runtime instead of drifting behind it.
|
|
155
181
|
|
|
156
182
|
The local-packages trap: braid resolves the pi family from
|
|
157
|
-
`~/.pi/agent/local-packages`, and
|
|
158
|
-
|
|
183
|
+
`~/.pi/agent/local-packages`, and those resolutions are not what its peer ranges
|
|
184
|
+
control. Installing a new braid tarball NEVER moves those copies - the
|
|
159
185
|
explicit pins in `local-packages/package.json` must be realigned to the
|
|
160
186
|
upstream version as their own step. That is why `--apply` aligns both sides,
|
|
161
187
|
then republishes braid, and why the runtime update is always last and only runs
|