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.
Files changed (85) hide show
  1. package/CONTRIBUTING.md +27 -3
  2. package/README.md +39 -33
  3. package/TOOLS.md +27 -3
  4. package/build-info.json +9 -0
  5. package/dist/extensions/cognitive/metacognition/handlers/hypothesize.d.ts +9 -0
  6. package/dist/extensions/cognitive/metacognition/handlers/hypothesize.js +13 -1
  7. package/dist/extensions/cognitive/metacognition/handlers/verify.js +35 -4
  8. package/dist/extensions/core/prompt-builder/inspect.js +9 -3
  9. package/dist/extensions/enforcement/handlers/register-tool-result-formatting.d.ts +1 -1
  10. package/dist/extensions/enforcement/handlers/register-tool-result-formatting.js +1 -1
  11. package/dist/extensions/enforcement/handlers/turn-end-handler.js +1 -1
  12. package/dist/extensions/enforcement/self-state-claims.d.ts +1 -1
  13. package/dist/extensions/enforcement/self-state-claims.js +3 -2
  14. package/dist/extensions/manifest.js +2 -2
  15. package/dist/extensions/memory/context-manager/handlers/tool-batch-boundary.d.ts +22 -5
  16. package/dist/extensions/memory/context-manager/handlers/tool-batch-boundary.js +43 -11
  17. package/dist/extensions/memory/context-manager/handlers/tools/context-compress.js +174 -50
  18. package/dist/extensions/memory/context-manager/handlers/tools/context-navigate.js +4 -1
  19. package/dist/extensions/memory/memory-agent-bridge/memory-store-tool.js +16 -0
  20. package/dist/extensions/memory/memory-agent-bridge/memory-tool.js +21 -9
  21. package/dist/extensions/memory/scratchpad/format.js +8 -2
  22. package/dist/extensions/memory/scratchpad/index.js +11 -2
  23. package/dist/extensions/memory/session-recall/index.js +19 -6
  24. package/dist/extensions/memory/three-memory-stores/episodes.d.ts +1 -1
  25. package/dist/extensions/memory/three-memory-stores/episodes.js +2 -2
  26. package/dist/extensions/orchestrator/index.js +73 -8
  27. package/dist/extensions/self/health-maintenance/index.js +112 -9
  28. package/dist/lib/config/braid-settings.d.ts +21 -0
  29. package/dist/lib/config/braid-settings.js +36 -0
  30. package/dist/lib/constants/session-thresholds.d.ts +2 -3
  31. package/dist/lib/constants/session-thresholds.js +2 -3
  32. package/dist/lib/enforcement/turn-dedup.d.ts +2 -2
  33. package/dist/lib/enforcement/turn-dedup.js +2 -2
  34. package/dist/lib/harness/index.d.ts +1 -1
  35. package/dist/lib/harness/index.js +1 -1
  36. package/dist/lib/harness/types.d.ts +1 -1
  37. package/dist/lib/harness/types.js +1 -1
  38. package/dist/lib/orchestrator/index.d.ts +2 -2
  39. package/dist/lib/orchestrator/index.js +1 -1
  40. package/dist/lib/orchestrator/workers.d.ts +184 -2
  41. package/dist/lib/orchestrator/workers.js +521 -6
  42. package/dist/lib/utils/injection-tracker.js +1 -1
  43. package/docs/BEGINNERS.md +22 -0
  44. package/docs/CONTEXT-POLICY.md +13 -5
  45. package/docs/LOCAL_DEV.md +31 -5
  46. package/docs/ROADMAP.md +10 -7
  47. package/docs/SETUP.md +86 -42
  48. package/package.json +11 -8
  49. package/skills/braid-reference/SKILL.md +23 -23
  50. package/skills/release-pipeline/SKILL.md +46 -37
  51. package/skills/subagent-orchestration/SKILL.md +51 -1
  52. package/src/extensions/cognitive/metacognition/handlers/hypothesize.ts +14 -1
  53. package/src/extensions/cognitive/metacognition/handlers/verify.ts +39 -5
  54. package/src/extensions/core/prompt-builder/inspect.ts +10 -3
  55. package/src/extensions/enforcement/AGENTS.md +25 -19
  56. package/src/extensions/enforcement/handlers/register-tool-result-formatting.ts +1 -1
  57. package/src/extensions/enforcement/handlers/turn-end-handler.ts +1 -1
  58. package/src/extensions/enforcement/self-state-claims.ts +3 -2
  59. package/src/extensions/heartbeat/heartbeat-scheduler/AGENTS.md +6 -3
  60. package/src/extensions/manifest.ts +2 -2
  61. package/src/extensions/memory/AGENTS.md +13 -5
  62. package/src/extensions/memory/context-manager/handlers/tool-batch-boundary.ts +45 -11
  63. package/src/extensions/memory/context-manager/handlers/tools/context-compress.ts +202 -60
  64. package/src/extensions/memory/context-manager/handlers/tools/context-navigate.ts +4 -1
  65. package/src/extensions/memory/memory-agent-bridge/memory-store-tool.ts +16 -0
  66. package/src/extensions/memory/memory-agent-bridge/memory-tool.ts +22 -9
  67. package/src/extensions/memory/scratchpad/format.ts +8 -2
  68. package/src/extensions/memory/scratchpad/index.ts +12 -2
  69. package/src/extensions/memory/session-recall/index.ts +20 -8
  70. package/src/extensions/memory/three-memory-stores/episodes.ts +2 -2
  71. package/src/extensions/orchestrator/index.ts +100 -11
  72. package/src/extensions/scheduling/timer/AGENTS.md +7 -0
  73. package/src/extensions/self/health-maintenance/index.ts +143 -14
  74. package/src/extensions/self/watchdog/AGENTS.md +1 -0
  75. package/src/lib/AGENTS.md +21 -21
  76. package/src/lib/config/braid-settings.ts +74 -0
  77. package/src/lib/constants/session-thresholds.ts +2 -3
  78. package/src/lib/enforcement/turn-dedup.ts +2 -2
  79. package/src/lib/harness/AGENTS.md +1 -1
  80. package/src/lib/harness/index.ts +1 -1
  81. package/src/lib/harness/types.ts +1 -1
  82. package/src/lib/orchestrator/index.ts +26 -0
  83. package/src/lib/orchestrator/workers.ts +705 -7
  84. package/src/lib/utils/AGENTS.md +1 -1
  85. 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 and the lock table untouched.
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 {