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,6 +19,7 @@
|
|
|
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 type { CloseGateWellFormednessMode } from "../config/braid-settings.js";
|
|
22
23
|
export type WorkerStatus = "admitted" | "working" | "merged" | "completed" | "error" | "stalled" | "false-done" | "closed";
|
|
23
24
|
/** Terminal outcomes accepted by closeWorker. */
|
|
24
25
|
export type WorkerOutcome = "completed" | "error" | "stalled" | "false-done" | "closed";
|
|
@@ -26,6 +27,14 @@ export interface WorkerGate {
|
|
|
26
27
|
cmd: string;
|
|
27
28
|
exit: number;
|
|
28
29
|
at: string;
|
|
30
|
+
/**
|
|
31
|
+
* What the gate's population scan recorded, in the contract's shape
|
|
32
|
+
* (`scanned <n> <unit> at <revision>`). Optional: a gate with no population
|
|
33
|
+
* subject carries none, and a row recorded before the field existed stays
|
|
34
|
+
* valid. Stored verbatim; the read that compares it against the repo lives
|
|
35
|
+
* on the merge path.
|
|
36
|
+
*/
|
|
37
|
+
stamp?: string;
|
|
29
38
|
}
|
|
30
39
|
/** One duplicate admission a live entry turned away, and the request it refused. */
|
|
31
40
|
export interface WorkerAdmissionRefusal {
|
|
@@ -289,6 +298,162 @@ export declare function recordWorkerMerge(workerId: string, info: {
|
|
|
289
298
|
mergeSha: string;
|
|
290
299
|
cwd?: string;
|
|
291
300
|
}): WorkerEntry | null;
|
|
301
|
+
/** Predicate letters, in the order the four are evaluated. */
|
|
302
|
+
export type GateRowPredicate = "a" | "b" | "c" | "d";
|
|
303
|
+
export interface GateRowViolation {
|
|
304
|
+
predicate: GateRowPredicate;
|
|
305
|
+
detail: string;
|
|
306
|
+
}
|
|
307
|
+
/** The first whitespace-delimited token after leading env assignments, or null. */
|
|
308
|
+
export declare function firstCommandToken(cmd: string): string | null;
|
|
309
|
+
/**
|
|
310
|
+
* The (c) instrument: a top-level decoration that makes the field more than
|
|
311
|
+
* the command, so the recorded exit cannot be attributed to what the field
|
|
312
|
+
* names: an unquoted `;` or newline (whatever follows owns the exit), a
|
|
313
|
+
* background `&` (the shell owns it), or a word-starting `#` (the field
|
|
314
|
+
* carries a comment). Quotes, command substitutions and redirections are
|
|
315
|
+
* shell syntax rather than decorations and are skipped, so `2>&1 | tail`,
|
|
316
|
+
* `cd x && npm run ci:check` and a quoted `';'` stay accepted. Returns the
|
|
317
|
+
* decoration found, or null when the field carries none.
|
|
318
|
+
*/
|
|
319
|
+
export declare function findTopLevelDecoration(cmd: string): string | null;
|
|
320
|
+
/**
|
|
321
|
+
* Run the four predicates over one recorded row and return the first
|
|
322
|
+
* violation, or null when the row is well formed. (a)/(b) need `sh`; when the
|
|
323
|
+
* shell cannot be spawned they are left unjudged (the string-only (c) and (d)
|
|
324
|
+
* still run), so a missing instrument cannot fail every row.
|
|
325
|
+
*/
|
|
326
|
+
export declare function findGateRowViolation(cmd: string, exit: number, outcome: WorkerOutcome): GateRowViolation | null;
|
|
327
|
+
/** Where close-gate refusals land: one JSONL line per failing row. */
|
|
328
|
+
export declare function closeGateRefusalLogPath(): string;
|
|
329
|
+
export interface CloseGateRefusalRecord {
|
|
330
|
+
at: string;
|
|
331
|
+
workerId: string;
|
|
332
|
+
/** Zero-based index into the close's gate evidence rows. */
|
|
333
|
+
row: number;
|
|
334
|
+
predicate: GateRowPredicate;
|
|
335
|
+
cmd: string;
|
|
336
|
+
mode: CloseGateWellFormednessMode;
|
|
337
|
+
outcome: WorkerOutcome;
|
|
338
|
+
detail: string;
|
|
339
|
+
}
|
|
340
|
+
/**
|
|
341
|
+
* Append one refusal line. Never throws: a failed append warns once and
|
|
342
|
+
* leaves the close's own behavior untouched, so an unwritable braid root
|
|
343
|
+
* cannot refuse a close that shadow mode would have accepted.
|
|
344
|
+
*/
|
|
345
|
+
export declare function logCloseGateRefusal(record: CloseGateRefusalRecord): void;
|
|
346
|
+
/** One named pattern in the production-write table, as the seat publishes it. */
|
|
347
|
+
export interface ProductionWriteRule {
|
|
348
|
+
id: string;
|
|
349
|
+
label: string;
|
|
350
|
+
pattern: string;
|
|
351
|
+
/** Seat-side metadata (its guard prints this default); unread here. */
|
|
352
|
+
registry?: string;
|
|
353
|
+
}
|
|
354
|
+
/** The seat-owned table: what is a write, and what a preflight records. */
|
|
355
|
+
export interface ProductionWriteClass {
|
|
356
|
+
members: ProductionWriteRule[];
|
|
357
|
+
pieces: ProductionWriteRule[];
|
|
358
|
+
}
|
|
359
|
+
/** One write row and what the close recorded for it. */
|
|
360
|
+
export interface ProductionWriteRowRead {
|
|
361
|
+
row: number;
|
|
362
|
+
cmd: string;
|
|
363
|
+
member: string;
|
|
364
|
+
/** Indices of the rows carrying at least one preflight piece. */
|
|
365
|
+
preflightRows: number[];
|
|
366
|
+
/** Piece ids no row in the close carries. */
|
|
367
|
+
missingPieces: string[];
|
|
368
|
+
}
|
|
369
|
+
export interface ProductionWriteRead {
|
|
370
|
+
rows: ProductionWriteRowRead[];
|
|
371
|
+
/** The write rows still missing at least one piece; the first one refuses. */
|
|
372
|
+
unsatisfied: ProductionWriteRowRead[];
|
|
373
|
+
}
|
|
374
|
+
/** Where the seat publishes the production-write class it owns. */
|
|
375
|
+
export declare function productionWriteClassPath(): string;
|
|
376
|
+
/**
|
|
377
|
+
* Load the class table the seat owns. Never throws: a braid home that cannot be
|
|
378
|
+
* resolved, a missing file, an unreadable file and a malformed one all yield an
|
|
379
|
+
* empty class, which refuses nothing.
|
|
380
|
+
*/
|
|
381
|
+
export declare function readProductionWriteClass(file?: string): ProductionWriteClass;
|
|
382
|
+
/**
|
|
383
|
+
* Read a close's gate rows for production writes and their preflight evidence.
|
|
384
|
+
* A row is a write when any member pattern matches its cmd — a field carrying a
|
|
385
|
+
* write beside reads is still a write, because the members match the write
|
|
386
|
+
* verbs only. A piece is recorded when any row's cmd matches its pattern, so
|
|
387
|
+
* one composed preflight row and several separate ones both satisfy. Pure over
|
|
388
|
+
* the rows and the table.
|
|
389
|
+
*/
|
|
390
|
+
export declare function readProductionWrites(rows: Array<{
|
|
391
|
+
cmd: string;
|
|
392
|
+
exit: number;
|
|
393
|
+
stamp?: string;
|
|
394
|
+
}> | undefined, table?: ProductionWriteClass): ProductionWriteRead;
|
|
395
|
+
/**
|
|
396
|
+
* The refusal sentence for the first write row missing a piece: its index, the
|
|
397
|
+
* member, the missing piece ids and the command. Null when every write row is
|
|
398
|
+
* satisfied, so a caller cannot refuse on an empty read.
|
|
399
|
+
*/
|
|
400
|
+
export declare function productionWriteRefusalDetail(read: ProductionWriteRead): string | null;
|
|
401
|
+
export interface PopulationStamp {
|
|
402
|
+
/** Population size the gate recorded. */
|
|
403
|
+
n: number;
|
|
404
|
+
/** The population's unit, one lowercase word. */
|
|
405
|
+
unit: string;
|
|
406
|
+
/** Commit sha or ref name the gate read. */
|
|
407
|
+
revision: string;
|
|
408
|
+
}
|
|
409
|
+
/** Parse the stamp shape above; null when the value is not that shape. */
|
|
410
|
+
export declare function parsePopulationStamp(value: unknown): PopulationStamp | null;
|
|
411
|
+
/** What one gate row's stamp read decided. */
|
|
412
|
+
export type PopulationVerdict = "absent" | "unreadable" | "other-subject" | "unresolved" | "match" | "below" | "above";
|
|
413
|
+
export interface PopulationRowRead {
|
|
414
|
+
/** Zero-based index into the close's gate rows. */
|
|
415
|
+
row: number;
|
|
416
|
+
/** The row's command, as recorded (empty when the row carries none). */
|
|
417
|
+
cmd: string;
|
|
418
|
+
/** The raw stamp value, as recorded; undefined when the field is absent. */
|
|
419
|
+
raw: unknown;
|
|
420
|
+
/** True when the row carries a stamp field at all (even an unreadable one). */
|
|
421
|
+
present: boolean;
|
|
422
|
+
/** The parsed stamp, or null when absent or unreadable. */
|
|
423
|
+
stamp: PopulationStamp | null;
|
|
424
|
+
/** The census at the stamp's revision, or null when not compared. */
|
|
425
|
+
census: number | null;
|
|
426
|
+
/** `census - recorded`, or null when there is no comparison. */
|
|
427
|
+
delta: number | null;
|
|
428
|
+
verdict: PopulationVerdict;
|
|
429
|
+
}
|
|
430
|
+
export interface PopulationRead {
|
|
431
|
+
rows: PopulationRowRead[];
|
|
432
|
+
/** Rows whose unit is `files` and whose revision resolved (the comparisons). */
|
|
433
|
+
comparisons: PopulationRowRead[];
|
|
434
|
+
/** The first comparison recorded below its census; null when none stands. */
|
|
435
|
+
standing: PopulationRowRead | null;
|
|
436
|
+
/** True when any row carries a parseable `files` stamp. */
|
|
437
|
+
recorded: boolean;
|
|
438
|
+
/** The report lines, one per readable row, in row order. */
|
|
439
|
+
lines: string[];
|
|
440
|
+
}
|
|
441
|
+
/** The census lookup the caller supplies: revision to tree size, or null. */
|
|
442
|
+
export type PopulationCensus = (revision: string) => number | null;
|
|
443
|
+
/**
|
|
444
|
+
* Read every gate row for a population stamp and compare the `files` ones
|
|
445
|
+
* against the census the caller supplies for their named revision. Pure: the
|
|
446
|
+
* count is a lookup parameter, so the parse and the comparison are testable
|
|
447
|
+
* without a repository. Rows of another unit are not census subjects and are
|
|
448
|
+
* left uncompared; an unreadable stamp is named, never silently dropped.
|
|
449
|
+
*/
|
|
450
|
+
export declare function readPopulationStamps(gates: unknown, censusAt: PopulationCensus): PopulationRead;
|
|
451
|
+
/**
|
|
452
|
+
* The refusal sentence for the first standing delta: row index, stamp, census,
|
|
453
|
+
* delta, and the remedy. Null when no comparison sits below its census, so a
|
|
454
|
+
* caller cannot refuse on an empty read.
|
|
455
|
+
*/
|
|
456
|
+
export declare function populationRefusalDetail(read: PopulationRead): string | null;
|
|
292
457
|
/**
|
|
293
458
|
* Close an entry with a terminal outcome and optional gate evidence.
|
|
294
459
|
* Already-closed entries are left untouched (first close wins); the checks
|
|
@@ -298,8 +463,24 @@ export declare function recordWorkerMerge(workerId: string, info: {
|
|
|
298
463
|
* A completed close carries evidence: the reporter contract requires a
|
|
299
464
|
* non-empty `gate_evidence` block, and a probe measured this path storing a
|
|
300
465
|
* bare `completed` with no gates at all. That contradiction is refused now,
|
|
301
|
-
* and each provided gate is shape-checked (non-empty `cmd`, numeric `exit
|
|
302
|
-
* before any write — a violation leaves the row
|
|
466
|
+
* and each provided gate is shape-checked (non-empty `cmd`, numeric `exit`,
|
|
467
|
+
* string `stamp` when present) before any write — a violation leaves the row
|
|
468
|
+
* and the lock table untouched. A valid `stamp` is stored verbatim, so the
|
|
469
|
+
* merge path can read the recorded population off the row.
|
|
470
|
+
*
|
|
471
|
+
* Every provided row is then read for well-formedness: its `cmd` must parse
|
|
472
|
+
* under `sh -n`, resolve its first token, and name the command alone, and a
|
|
473
|
+
* completed close's exits must be 0. The mode is settings-driven
|
|
474
|
+
* (`braid.orchestrator.closeGateWellFormedness`): "shadow" (default) records
|
|
475
|
+
* a refusal line and proceeds, "enforce" refuses before any write or lock
|
|
476
|
+
* release, "off" skips the read. No gate is re-run; replay stays the
|
|
477
|
+
* sampler's sampled job.
|
|
478
|
+
*
|
|
479
|
+
* Every row is also read against the seat's production-write class: a row the
|
|
480
|
+
* class marks as a write is refused unless the close records every named
|
|
481
|
+
* preflight piece (identity, registry, dry-run) somewhere in its rows. The
|
|
482
|
+
* class lives in the seat's data file; when it is absent the class is empty and
|
|
483
|
+
* nothing is refused.
|
|
303
484
|
*
|
|
304
485
|
* Releases the worker's file locks: close is terminal, and a lock that
|
|
305
486
|
* survives it blocks the next spawn on the same files. The release runs with
|
|
@@ -309,6 +490,7 @@ export declare function recordWorkerMerge(workerId: string, info: {
|
|
|
309
490
|
export declare function closeWorker(workerId: string, outcome: WorkerOutcome, gates?: Array<{
|
|
310
491
|
cmd: string;
|
|
311
492
|
exit: number;
|
|
493
|
+
stamp?: string;
|
|
312
494
|
}>, cwd?: string): WorkerEntry | null;
|
|
313
495
|
/** A located result block plus where it sat in the assistant-message tail. */
|
|
314
496
|
export interface ResultSchemaLocation {
|