pi-braid 0.40.5 → 0.40.6
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/AGENTS.md +17 -18
- package/README.md +116 -130
- package/TOOLS.md +35 -35
- package/build-info.json +4 -4
- package/dist/extensions/core/agent-environment/index.js +4 -3
- package/dist/extensions/core/prompt-builder/index.js +12 -7
- package/dist/extensions/core/prompt-builder/instance-composition.d.ts +51 -10
- package/dist/extensions/core/prompt-builder/instance-composition.js +87 -14
- package/dist/extensions/core/prompt-builder/system-info-tool.d.ts +3 -3
- package/dist/extensions/core/prompt-builder/system-info-tool.js +3 -3
- package/dist/extensions/core/prompt-builder/tool-guidelines.js +1 -1
- package/dist/extensions/core/skills-tool/auto-inject.d.ts +89 -10
- package/dist/extensions/core/skills-tool/auto-inject.js +150 -21
- package/dist/extensions/core/skills-tool/index.d.ts +70 -2
- package/dist/extensions/core/skills-tool/index.js +149 -15
- package/dist/extensions/core/skills-tool/reach.d.ts +119 -0
- package/dist/extensions/core/skills-tool/reach.js +213 -0
- package/dist/extensions/core/skills-tool/skill-triggers.d.ts +47 -10
- package/dist/extensions/core/skills-tool/skill-triggers.js +66 -23
- package/dist/extensions/enforcement/handlers/register-session-compact.js +12 -1
- package/dist/extensions/enforcement/handlers/register-session-shutdown-resumption.js +15 -34
- package/dist/extensions/enforcement/handlers/register-session-start-discoverability.d.ts +2 -1
- package/dist/extensions/enforcement/handlers/register-session-start-discoverability.js +55 -28
- package/dist/extensions/enforcement/handlers/register-turn-end-hygiene.d.ts +14 -10
- package/dist/extensions/enforcement/handlers/register-turn-end-hygiene.js +88 -82
- package/dist/extensions/enforcement/resume-state.d.ts +76 -0
- package/dist/extensions/enforcement/resume-state.js +90 -0
- package/dist/extensions/enforcement/substate/context-hygiene-state.d.ts +9 -0
- package/dist/extensions/enforcement/substate/context-hygiene-state.js +8 -0
- package/dist/extensions/enforcement/whisper.d.ts +12 -0
- package/dist/extensions/enforcement/whisper.js +16 -1
- package/dist/extensions/heartbeat/heartbeat-scheduler/index.js +14 -6
- package/dist/extensions/heartbeat/heartbeat-scheduler/policies.d.ts +7 -0
- package/dist/extensions/heartbeat/heartbeat-scheduler/policies.js +372 -0
- package/dist/extensions/memory/context-manager/handlers/tools/context-compress.d.ts +8 -2
- package/dist/extensions/memory/context-manager/handlers/tools/context-compress.js +54 -21
- package/dist/lib/config/braid-paths.d.ts +14 -0
- package/dist/lib/config/braid-paths.js +18 -0
- package/dist/lib/config/braid-settings.d.ts +21 -0
- package/dist/lib/config/braid-settings.js +16 -0
- package/dist/lib/detection/context-tiers.d.ts +47 -3
- package/dist/lib/detection/context-tiers.js +122 -13
- package/dist/lib/events/turn-boundary.d.ts +78 -0
- package/dist/lib/events/turn-boundary.js +91 -0
- package/dist/lib/orchestrator/workers.d.ts +3 -2
- package/dist/lib/orchestrator/workers.js +22 -4
- package/dist/lib/state/global-state.d.ts +1 -1
- package/docs/CONTEXT-POLICY.md +8 -0
- package/docs/LOCAL_DEV.md +0 -1
- package/docs/ROADMAP.md +5 -5
- package/docs/SETUP.md +19 -18
- package/package.json +1 -1
- package/skills/herdr-topology/SKILL.md +6 -1
- package/skills/research/SKILL.md +32 -0
- package/skills/subagent-orchestration/SKILL.md +2 -2
- package/src/extensions/core/agent-environment/index.ts +4 -3
- package/src/extensions/core/prompt-builder/AGENTS.md +8 -4
- package/src/extensions/core/prompt-builder/index.ts +12 -7
- package/src/extensions/core/prompt-builder/instance-composition.ts +98 -14
- package/src/extensions/core/prompt-builder/system-info-tool.ts +3 -3
- package/src/extensions/core/prompt-builder/tool-guidelines.ts +1 -1
- package/src/extensions/core/skills-tool/auto-inject.ts +196 -24
- package/src/extensions/core/skills-tool/index.ts +217 -15
- package/src/extensions/core/skills-tool/reach.ts +256 -0
- package/src/extensions/core/skills-tool/skill-triggers.ts +90 -20
- package/src/extensions/enforcement/handlers/register-session-compact.ts +12 -1
- package/src/extensions/enforcement/handlers/register-session-shutdown-resumption.ts +23 -36
- package/src/extensions/enforcement/handlers/register-session-start-discoverability.ts +59 -29
- package/src/extensions/enforcement/handlers/register-turn-end-hygiene.ts +101 -81
- package/src/extensions/enforcement/resume-state.ts +127 -0
- package/src/extensions/enforcement/substate/context-hygiene-state.ts +17 -0
- package/src/extensions/enforcement/whisper.ts +21 -1
- package/src/extensions/heartbeat/heartbeat-scheduler/index.ts +20 -5
- package/src/extensions/heartbeat/heartbeat-scheduler/policies.ts +370 -0
- package/src/extensions/memory/AGENTS.md +25 -1
- package/src/extensions/memory/context-manager/handlers/tools/context-compress.ts +80 -27
- package/src/lib/config/braid-paths.ts +20 -0
- package/src/lib/config/braid-settings.ts +46 -0
- package/src/lib/detection/context-tiers.ts +186 -13
- package/src/lib/events/AGENTS.md +1 -0
- package/src/lib/events/turn-boundary.ts +115 -0
- package/src/lib/orchestrator/workers.ts +33 -12
- package/src/lib/state/global-state.ts +1 -0
- package/src/lib/utils/AGENTS.md +1 -1
- package/src/types/extension-context.d.ts +22 -79
|
@@ -444,8 +444,9 @@ export type PopulationCensus = (revision: string) => number | null;
|
|
|
444
444
|
* Read every gate row for a population stamp and compare the `files` ones
|
|
445
445
|
* against the census the caller supplies for their named revision. Pure: the
|
|
446
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
|
|
448
|
-
* left uncompared; an unreadable stamp is named,
|
|
447
|
+
* without a repository. Rows of another unit are not census subjects: they are
|
|
448
|
+
* read, named in the lines, and left uncompared; an unreadable stamp is named,
|
|
449
|
+
* never silently dropped.
|
|
449
450
|
*/
|
|
450
451
|
export declare function readPopulationStamps(gates: unknown, censusAt: PopulationCensus): PopulationRead;
|
|
451
452
|
/**
|
|
@@ -842,8 +842,15 @@ export function productionWriteRefusalDetail(read) {
|
|
|
842
842
|
* Bare-token revision rules: an all-hex token is a sha only at 7-40 chars, so
|
|
843
843
|
* a six-char prefix does not slip through the ref-name alternative as a
|
|
844
844
|
* revision git can never resolve.
|
|
845
|
+
*
|
|
846
|
+
* The unit is one token of lowercase letters and digits, joined by single
|
|
847
|
+
* hyphens or underscores and starting with a letter: a reporter writes
|
|
848
|
+
* `test-files` as readily as `files`, and the earlier letters-only rule threw
|
|
849
|
+
* that evidence away as unreadable. A unit is never a phrase — `scanned 5 test
|
|
850
|
+
* files at main` stays refused, because a two-word unit cannot be told from a
|
|
851
|
+
* malformed stamp.
|
|
845
852
|
*/
|
|
846
|
-
const POPULATION_STAMP_RE = /^scanned (\d+) ([a-z]+) at ([0-9a-fA-F]{7,40}|[A-Za-z0-9][A-Za-z0-9._/-]*)$/;
|
|
853
|
+
const POPULATION_STAMP_RE = /^scanned (\d+) ([a-z][a-z0-9]*(?:[_-][a-z0-9]+)*) at ([0-9a-fA-F]{7,40}|[A-Za-z0-9][A-Za-z0-9._/-]*)$/;
|
|
847
854
|
const ALL_HEX_RE = /^[0-9a-fA-F]+$/;
|
|
848
855
|
/** Parse the stamp shape above; null when the value is not that shape. */
|
|
849
856
|
export function parsePopulationStamp(value) {
|
|
@@ -864,8 +871,18 @@ function populationLines(rows) {
|
|
|
864
871
|
lines.push(`population stamp unreadable: row ${row.row} ${JSON.stringify(row.raw)}`);
|
|
865
872
|
continue;
|
|
866
873
|
}
|
|
867
|
-
if (row.stamp === null
|
|
874
|
+
if (row.stamp === null)
|
|
875
|
+
continue;
|
|
876
|
+
if (row.stamp.unit !== "files") {
|
|
877
|
+
// A stamp names the population it scanned. Only `files` is a census
|
|
878
|
+
// subject here (the tracked-entry count at the revision), so another
|
|
879
|
+
// unit is read and named but never compared — and never dropped as if it
|
|
880
|
+
// had been unreadable, which is what the old unit pattern did to
|
|
881
|
+
// `test-files`.
|
|
882
|
+
lines.push(`population recorded: ${row.stamp.n} ${row.stamp.unit} at ${row.stamp.revision} ` +
|
|
883
|
+
`(row ${row.row}; unit is not the tracked-entry census, not compared)`);
|
|
868
884
|
continue;
|
|
885
|
+
}
|
|
869
886
|
if (row.verdict === "unresolved") {
|
|
870
887
|
lines.push(`population delta: recorded ${row.stamp.n} at ${row.stamp.revision} ` +
|
|
871
888
|
`(row ${row.row}; revision unresolved, not compared)`);
|
|
@@ -884,8 +901,9 @@ function populationLines(rows) {
|
|
|
884
901
|
* Read every gate row for a population stamp and compare the `files` ones
|
|
885
902
|
* against the census the caller supplies for their named revision. Pure: the
|
|
886
903
|
* 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
|
|
888
|
-
* left uncompared; an unreadable stamp is named,
|
|
904
|
+
* without a repository. Rows of another unit are not census subjects: they are
|
|
905
|
+
* read, named in the lines, and left uncompared; an unreadable stamp is named,
|
|
906
|
+
* never silently dropped.
|
|
889
907
|
*/
|
|
890
908
|
export function readPopulationStamps(gates, censusAt) {
|
|
891
909
|
const rows = [];
|
|
@@ -297,7 +297,7 @@ export declare function getShownDiscoveryBundles(): Set<string>;
|
|
|
297
297
|
export declare function resetShownDiscoveryBundles(): void;
|
|
298
298
|
/** Signal type identifiers used by the discoverability handler.
|
|
299
299
|
* These are the dedup keys — keep them stable across releases. */
|
|
300
|
-
export type DiscoverySignalType = "scratchpad_prior" | "memory_prior" | "sessions_prior" | "resume" | "tags_prior" | "context_hygiene_tip";
|
|
300
|
+
export type DiscoverySignalType = "scratchpad_prior" | "memory_prior" | "sessions_prior" | "resume" | "tags_prior" | "journal_prior" | "context_hygiene_tip";
|
|
301
301
|
/** Get the shared shown-signal-types set (process-global, survives /reload). */
|
|
302
302
|
export declare function getShownSignals(): Set<DiscoverySignalType>;
|
|
303
303
|
/** Reset the shown-signal set. Test helper. */
|
package/docs/CONTEXT-POLICY.md
CHANGED
|
@@ -35,6 +35,14 @@ arms fire late on large windows, which is why both ladders exist. `CONTEXT_COMPA
|
|
|
35
35
|
mode, guarding against max-call-stack crashes and session corruption at high
|
|
36
36
|
usage; hygiene acts re-arm at most once every three turns.
|
|
37
37
|
|
|
38
|
+
The two ladders arm one enforcement nudge between them, ordered by position on
|
|
39
|
+
the percent axis both units measure: 0.18W, 30%, 0.45W, 50%, 65%, 75%, 80%. The
|
|
40
|
+
highest reached rung renders, so a token arm never shadows a percent tier above
|
|
41
|
+
it (0.45W is 45% of every window). The nudge latch records the rung that fired
|
|
42
|
+
and re-arms on a fall back below that rung, in that rung's own unit - a percent
|
|
43
|
+
bar would clear a 0.45W arm on the very next turn, repeating the same line.
|
|
44
|
+
Owner: [`src/lib/detection/context-tiers.ts`](../src/lib/detection/context-tiers.ts).
|
|
45
|
+
|
|
38
46
|
Owner: [`src/lib/detection/context-thresholds.ts`](../src/lib/detection/context-thresholds.ts)
|
|
39
47
|
(single home; consumers import, never restate).
|
|
40
48
|
|
package/docs/LOCAL_DEV.md
CHANGED
|
@@ -53,7 +53,6 @@ npm run format:check # prettier --check .
|
|
|
53
53
|
npm run check:docs # every in-scope .md has a status marker
|
|
54
54
|
npm run check:doc-drift # current-state docs must not reference APIs missing from code
|
|
55
55
|
npm run check:deps # layer-boundary check
|
|
56
|
-
npm run check:private-data # whole-tree private-data scan
|
|
57
56
|
```
|
|
58
57
|
|
|
59
58
|
Per-workspace variants use the workspace flag, e.g.
|
package/docs/ROADMAP.md
CHANGED
|
@@ -46,8 +46,7 @@ provenance; they are no longer work.
|
|
|
46
46
|
1. **Providers de-reference (P10b)** - RESOLVED: the Venice registration is a
|
|
47
47
|
userland catalog seam (`providers/venice-catalog.ts`, resolved from
|
|
48
48
|
`$VENICE_CATALOG_FILE` or `~/.pi/agent/venice-models.json`); the provider
|
|
49
|
-
registers only when that catalog exists
|
|
50
|
-
whole tree in `ci:check`.
|
|
49
|
+
registers only when that catalog exists.
|
|
51
50
|
2. **Version-drift cleanup** - RESOLVED: the four workspace packages declare
|
|
52
51
|
the pi peer as `"*"`; the root manifest pins the installed version
|
|
53
52
|
(`package.json`, the `@earendil-works/*` deps).
|
|
@@ -55,9 +54,10 @@ provenance; they are no longer work.
|
|
|
55
54
|
the root `CHANGELOG.md` - core keeps the bare `v` (iteration tags `v0.40.0-main.N`,
|
|
56
55
|
`package.json` `0.40.0-main.N`; release tag `v0.40.0`), every sibling tags as
|
|
57
56
|
`<workspace>-v<version>` (`telegram-v0.1.4`).
|
|
58
|
-
4. **
|
|
59
|
-
|
|
60
|
-
|
|
57
|
+
4. **Documentation path rule** - RESOLVED: docs may name product paths
|
|
58
|
+
(`~/.pi/agent/…`, `~/pi-braid/…`) and never a private home layout;
|
|
59
|
+
`check-doc-links` fails on the latter, and every in-repo reference must
|
|
60
|
+
resolve.
|
|
61
61
|
5. **Skills pack** - finish validating the five skills still marked
|
|
62
62
|
`verdict: UNVALIDATED` (`braid-reference`, `misdirection-audit`,
|
|
63
63
|
`placement-discipline`, `probe-evaluation`, `voice-replies`); keep the pack
|
package/docs/SETUP.md
CHANGED
|
@@ -298,24 +298,25 @@ The user-global file always exists; the project one is optional and belongs to p
|
|
|
298
298
|
|
|
299
299
|
`packages` is pi-native - what to load as extensions. Everything braid reads sits under the top-level `braid` key. Keys that exist in code today:
|
|
300
300
|
|
|
301
|
-
| Key | Type
|
|
302
|
-
| --------------------------------------- |
|
|
303
|
-
| `braid.modules.<ref>` | boolean
|
|
304
|
-
| `braid.suppressNudges` | boolean
|
|
305
|
-
| `braid.timezone` | IANA name
|
|
306
|
-
| `braid.enforcement.nudgeConfigs.<type>` | object
|
|
307
|
-
| `braid.memory.writeGate` | object
|
|
308
|
-
| `braid.timers.maxWakeAttempts` | integer 1..10
|
|
309
|
-
| `braid.timers.wakeAlert` | object
|
|
310
|
-
| `braid.context.contextLimitTokens` | positive number
|
|
311
|
-
| `braid.context.toolResultSizeCap` | object
|
|
312
|
-
| `braid.context.staleToolResultOffload` | object
|
|
313
|
-
| `braid.context.contextEmergencyOffload` | object
|
|
314
|
-
| `braid.
|
|
315
|
-
| `braid.telegram.
|
|
316
|
-
| `braid.telegram.
|
|
317
|
-
| `braid.
|
|
318
|
-
| `braid.contrib.<
|
|
301
|
+
| Key | Type | Default | Purpose |
|
|
302
|
+
| --------------------------------------- | ------------------------ | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
303
|
+
| `braid.modules.<ref>` | boolean | per manifest | Force-enable (`true`) or disable (`false`) an extension id or module group (`memory`, `heartbeat`); a persisted `false` removes a default-enabled extension from the boot set (see [§ Module toggling](#module-toggling)). |
|
|
304
|
+
| `braid.suppressNudges` | boolean | `false` | Silence all cognitive nudges (enforcement whispers, heartbeat suggestions, feedback reminders). |
|
|
305
|
+
| `braid.timezone` | IANA name | `Europe/Moscow` | Time zone for all braid-facing time rendering. |
|
|
306
|
+
| `braid.enforcement.nudgeConfigs.<type>` | object | built-in per-type defaults | Per-nudge-type overrides with leaf shape `braid.enforcement.nudgeConfigs.<type>.<key>`; accepted fields are `baseCooldownMs` (number), `escalateAfter` (number), and `deduplicate` (boolean). Types: `validation`, `recordFailure`, `malformed`, `memory`, `scratchpad`, `context`, `sessionSignals`. Invalid entries are logged and dropped. |
|
|
307
|
+
| `braid.memory.writeGate` | object | gate ON, 20-min cooldown, `enforce` | Review-before-write gate on episode writes; `mode: "warn"` logs decisions and writes anyway; `sites` opts individual writers out. |
|
|
308
|
+
| `braid.timers.maxWakeAttempts` | integer 1..10 | `3` | Redelivery cap for a failed timer wake before it is dropped with a visible notice. |
|
|
309
|
+
| `braid.timers.wakeAlert` | object | ON, `outcomeTimeouts: 2` | Dead-wake page: repeated outcome timeouts / exhausted redeliveries feed the watchdog's wake-delivery condition, which pages the owner out of band (telegram) once per episode plus one recovery line. `mode: "off"` disables the feed (delivery itself is unchanged); `outcomeTimeouts` is an integer 2..10 (1 would page on every normal long turn). |
|
|
310
|
+
| `braid.context.contextLimitTokens` | positive number | provider context window | The window every surface computes with (usage math, density, fallbacks, pi-core threshold compaction and overflow detection, TUI footer). A CEILING: min(contextLimitTokens, true window) when known, else the cap; re-plumbed on session start and /reload and never widens a smaller true window. The provider catalog keeps the true size. |
|
|
311
|
+
| `braid.context.toolResultSizeCap` | object | ON, 262144 chars | Capture-time cap: oversized tool results are flushed to disk and replaced by a stub. |
|
|
312
|
+
| `braid.context.staleToolResultOffload` | object | OFF | Opt-in age/size offload of stale large tool results (defaults: `minChars` 4000, `stalenessTurns` 40, `keepRecentTurns` 20, `maxOffloadCharsPerRun` 65536). |
|
|
313
|
+
| `braid.context.contextEmergencyOffload` | object | ON | Emergency offload of the largest tool results when a context-window (413) error fires, then one retry (defaults: `minChars` 262144, `maxCharsPerRun` 1048576, `keepRecentTurns` 1). |
|
|
314
|
+
| `braid.skills.ranking` | `keyword`/`auto`/`model` | `keyword` | Tier policy for the `list_skills` relevance ranking. `keyword` (implemented): the deterministic scorer orders the rows and reports its own verdict (`unambiguous` / `tie` / `thin-margin` / `short-task` / `no-score` / `no-task`) with per-row `relevance {score, reason}`. `auto` and `model` are reserved for a model tier that would answer on an ambiguous verdict; it was measured against the scorer and not kept, so both evaluate to the keyword path and the read echoes the configured value as `ranking.policy`. An unknown value falls back to `keyword`. |
|
|
315
|
+
| `braid.telegram.sendMaxChars` | positive number | `4096` | Plain-text cap for `telegram_send`, re-read per call. |
|
|
316
|
+
| `braid.telegram.notifyMaxChars` | positive number | `1200` | Craft target and guard for turn-end notifications. |
|
|
317
|
+
| `braid.telegram.pauseStateFile` | path string | built-in default | Override for the `/telegram` pause-state file path. |
|
|
318
|
+
| `braid.contrib.<name>` | boolean or object | enabled / per-extension | Per-contrib-extension config - see [§ Contrib extensions](#contrib-extensions). |
|
|
319
|
+
| `braid.contrib.<extensionName>.enabled` | string[] | unset | Generic per-extension tool-enable list. The shared helper reads and writes string entries; the `/tools` surface stores its shared list in `braid.contrib._global.enabled`. |
|
|
319
320
|
|
|
320
321
|
### Worked example
|
|
321
322
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-braid",
|
|
3
|
-
"version": "0.40.
|
|
3
|
+
"version": "0.40.6",
|
|
4
4
|
"description": "Metacognitive extension suite for pi-coding-agent: enforcement, memory, reasoning, self-improvement, and structured cognitive signals.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -52,7 +52,12 @@ columns or short rows.
|
|
|
52
52
|
|
|
53
53
|
Keep the user's focus where it is unless they asked to switch context. Do
|
|
54
54
|
not close workspaces, tabs, panes, or sessions you did not create unless
|
|
55
|
-
the user explicitly asks.
|
|
55
|
+
the user explicitly asks. The one exception is the pane of the agent you
|
|
56
|
+
replaced: a process cannot close the pane it runs in, so during a
|
|
57
|
+
mastership transfer the incoming seat owns that close and runs
|
|
58
|
+
`herdr_pane close <pane>` on the outgoing seat's pane. The exception covers
|
|
59
|
+
that pane and nothing else - worker panes you did not spawn, tabs, and
|
|
60
|
+
workspaces still wait for the user's word.
|
|
56
61
|
|
|
57
62
|
## Panes: raw terminal control
|
|
58
63
|
|
package/skills/research/SKILL.md
CHANGED
|
@@ -107,6 +107,38 @@ curl -sL --max-time 10 'https://<instance>/search?q=query&format=json'
|
|
|
107
107
|
|
|
108
108
|
**Do not rely on this.** The JSON API is disabled on most public instances. Use Method A (DuckDuckGo HTML) instead.
|
|
109
109
|
|
|
110
|
+
### Method E: Reading an X Post (oEmbed, No Auth)
|
|
111
|
+
|
|
112
|
+
A direct fetch of an X status URL is refused (403), and the page renders its
|
|
113
|
+
text with JavaScript. The embed endpoint serves the same post as JSON, with
|
|
114
|
+
no login and no key:
|
|
115
|
+
|
|
116
|
+
```bash
|
|
117
|
+
curl -s "https://publish.x.com/oembed?url=https%3A%2F%2Fx.com%2F<account>%2Fstatus%2F<id>&omit_script=true"
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
- `publish.x.com` is the live host. `publish.twitter.com` answers 301 to it,
|
|
121
|
+
so a client that does not follow redirects gets an empty body (`curl -L`
|
|
122
|
+
there).
|
|
123
|
+
- The `url` parameter is the status URL percent-encoded (`%3A` for `:`, `%2F`
|
|
124
|
+
for `/`). Unencoded, the link's own `?` and `&` read as oEmbed parameters
|
|
125
|
+
instead of as part of the link.
|
|
126
|
+
- The response is application/json: the author name and handle, and an HTML
|
|
127
|
+
blockquote holding the post text and its date. That text is HTML-escaped
|
|
128
|
+
(`—` before the author name), so decode entities before quoting.
|
|
129
|
+
|
|
130
|
+
**What it does not give.** Text only - no media, no reply thread, no quoted
|
|
131
|
+
post body. A post X will not render fails instead of degrading: deleted,
|
|
132
|
+
protected, and age-gated posts answer with an error page and a 4xx rather
|
|
133
|
+
than JSON (deleted verified at 404), so check the status and content type
|
|
134
|
+
before parsing. A bare account URL has no status id to embed - it returns a
|
|
135
|
+
timeline anchor link with no post text, so an account's page still needs
|
|
136
|
+
another route.
|
|
137
|
+
|
|
138
|
+
Verified against public posts of two different accounts. Public nitter
|
|
139
|
+
instances are not a fallback any more: X's cease-and-desist letters took them
|
|
140
|
+
down, and `nitter.net` now serves only an offline notice.
|
|
141
|
+
|
|
110
142
|
---
|
|
111
143
|
|
|
112
144
|
## Fact Verification
|
|
@@ -323,7 +323,7 @@ herdr action=send pane=<successor> text="[agent:orchestrator→successor] Read /
|
|
|
323
323
|
|
|
324
324
|
Best for a successor that will orchestrate subagents. TUI pi persists, accepts signaling, can spawn its own workers.
|
|
325
325
|
|
|
326
|
-
3. Transfer mastership: the current session closes when the successor completes. The successor
|
|
326
|
+
3. Transfer mastership: the current session closes when the successor completes. The successor closes the predecessor's pane with `herdr_pane close <predecessor-pane>` - the predecessor cannot close the pane it runs in, so the incoming seat owns that one close and the transfer ends there.
|
|
327
327
|
4. The successor starts clean (no bloat) and reads the handoff.
|
|
328
328
|
|
|
329
329
|
This is a **pipeline, not a loop**: each session is a fresh stage. Never compact above 70% - cascade instead.
|
|
@@ -410,7 +410,7 @@ At regular intervals (every few turns, or when spawning new work), check for sta
|
|
|
410
410
|
2. **Inspect each pane** - For each pane that looks complete (long idle, exited to shell prompt, error message), read its visible content:
|
|
411
411
|
`herdr action=read pane=<id> source=visible`
|
|
412
412
|
3. **Close completed panes** - If a worker signaled completion and was approved, or crashed and was not restarted:
|
|
413
|
-
`
|
|
413
|
+
`herdr_pane close <pane>`
|
|
414
414
|
4. **Close error-state panes** - If a pane shows a provider error or retry loop with no recovery path, close it rather than leaving it spinning.
|
|
415
415
|
|
|
416
416
|
### Lock cleanup
|
|
@@ -106,9 +106,10 @@ export function gatherL1Environment(_pi: ExtensionAPI, ctx: ExtensionContext): L
|
|
|
106
106
|
};
|
|
107
107
|
}
|
|
108
108
|
|
|
109
|
-
// The L1 environment
|
|
110
|
-
// (
|
|
111
|
-
//
|
|
109
|
+
// The L1 environment data is consumed by instance-composition.ts: the
|
|
110
|
+
// volatile stats (elapsed, last event, turns, tool average) render only in
|
|
111
|
+
// the system_info tool, while the compact prompt line takes just the PID,
|
|
112
|
+
// which is process-stable.
|
|
112
113
|
|
|
113
114
|
export default function agentEnvironmentExtension(pi: ExtensionAPI) {
|
|
114
115
|
registerSessionStartHandler(pi, SessionPhase.Background, async (_event, ctx) => {
|
|
@@ -19,28 +19,32 @@ Every file in this folder either:
|
|
|
19
19
|
## Ownership
|
|
20
20
|
|
|
21
21
|
| File | Purpose |
|
|
22
|
-
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
22
|
+
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
23
23
|
| `index.ts` | Main handler. Wires `before_agent_start`, calls the 4 `deliver*` functions, composes the final prompt. |
|
|
24
24
|
| `section.ts` | The `PromptSection` primitive + `composeSections` joiner + `simpleSection`, `linesSection`, `headingSection` builders. |
|
|
25
25
|
| `identity.ts` | Framing constants: `IDENTITY_INTRO` (generalist identity), `DISCOVERY` (D1 guarded exploration stance), `WORK_ETHIC` (methodical precision, signal-not-noise), `REPAIR_DISCIPLINE` (root cause named falsifiably before repair; re-derivation of claims that are not yours; weighted repair decisions), `SELF_MANAGEMENT` (memory workspace, evidence-carrying done items, known-open-check done gate), `COMMUNICATION` (conclusion-first, output style), `EPISTEMIC_STANCE` (identity-core: claim gate, self-state gate, retrieved-context preference), `SELF_AUDIT` (symmetric doubt; handoff ends with the unverified), `PHILOSOPHY` (character-level stance - silence, calm strategist, precise self-irony). |
|
|
26
26
|
| `surface-discipline-section.ts` | `SURFACE_DISCIPLINE` (signal discipline across code, commits, tests, docs, reports, logs) + `surfaceDisciplineSection()` - its own section, rendered between the identity and identity-core blocks. Text pinned verbatim by test-prompt-budget.mjs. |
|
|
27
|
-
| `instance-composition.ts` | **v3.8** Instance
|
|
27
|
+
| `instance-composition.ts` | **v3.8** Full Instance block: agent identity + pi-core version + core root + cwd + settings dir + os/pid + session (id + elapsed/last-event/turns/tool-avg) + top-level extension packages. Served on demand by the `system_info` tool. The prompt carries `renderCompactInstance`: braid build + install root, model, PID, session id, and skill/memory counts (process-stable facts only; see Local Contracts). |
|
|
28
28
|
| `top-level-extensions.ts` | **v3.8** Discovery logic for top-level pi extension PACKAGES. Reads pi-core's `packages` field from `<cwd>/.pi/settings.json` (project) and `~/.pi/agent/settings.json` (user-global); project wins on collision. Resolves `npm:` specs in pi's managed install tree (`<agentDir>/npm/node_modules`) first, falling back to the global npm root (`npm root -g`); resolves local paths in place. Source tags: `project` / `user-global`. |
|
|
29
29
|
| `project-docs-section.ts` | Project docs (AGENTS.md / CLAUDE.md) pointer-only rendering as plain-text bullets (`- <basename> at <path>`). Mirrors the skills discoverability model but uses plain text (no XML tags) so the system prompt stays prose. Includes fingerprint cache and `RESOURCES_DISCOVER` invalidation. |
|
|
30
30
|
| `memory-section.ts` | Memory store pointer block (episodes + semantic + heuristics) as plain-text bullets (`- episodes at PATH`; count-free - per-store counts go stale at print time and are not rendered). Mirrors project-docs. Cached per session (static content, no fingerprint needed); invalidated on `RESOURCES_DISCOVER`. |
|
|
31
31
|
| `context-section.ts` | **v3.6** body fragment for the unified context block: context %, session health, steps-since-checkpoint. Returns `""` when nothing to surface. Composer (`index.ts`) joins this with project-docs and memory bodies. No heading. (Memory stores render pointer-only: per-store entry counts are not rendered; the whisper carries token counts, not memory counts.) |
|
|
32
32
|
| `awareness-whisper.ts` | Once-per-session context-hygiene steer whisper (customType `hygiene`): tokens in context + delta since the previous emission's baseline, the inspector pointer, and the injection-channel catalog; `formatAwarenessText` is tool-availability-aware; the TG inbound row is state-aware: it asserts reachability only when the poller liveness registry (`lib/state/telegram-poller-liveness.ts`) says the poller is running, else it hedges and names `telegram_poller status`. The catalog describes subsystem whispers by their stable envelope (produced by `lib/utils/whisper-format.ts`) instead of enumerating subsystems. |
|
|
33
33
|
| ~~`contrast-phrases.ts`~~ | **DELETED 2026-08-12 (keep+cut)** - legacy RepE-style phrase library (TRUTH_FIRST, ANTI_SYCOPHANCY, EPISTEMIC_STABILITY, KNOWLEDGE_BOUNDARY). Consolidated into `EPISTEMIC_STANCE` (identity.ts) on 2026-07-16; zero importers; provenance in the deleted file's git history. |
|
|
34
|
-
| ~~`resources-section.ts`~~ | **DELETED** - the `Resources: N skills` pointer line was dead: duplicated by the skills-loading contract and the list_skills tool description.
|
|
34
|
+
| ~~`resources-section.ts`~~ | **DELETED** - the standalone `Resources: N skills` pointer line was dead: duplicated by the skills-loading contract and the list_skills tool description. The counts return only on the compact instance line (`Resources: N skills, M memories`) as a load signal. `excludeSkillsBlock` in `inspect.ts` keeps its Resources parser (absent-degrades-to-0) for non-braid prompt shapes. |
|
|
35
35
|
| `tool-pipelines.ts` | Guarded multi-tool usage pipelines (research/debugging - the implementation pipeline was dropped, merged into COMMUNICATION's understand-before-act; the verification pipeline was dropped as a restatement of the verify/verify_claim/finalize rows); pinned by test-tool-pipelines.mjs. |
|
|
36
36
|
| `tool-guidelines.ts` | Per-tool guideline sync: `TOOL_GUIDELINES` (tool → one-line reflection, synced 1:1 with `packages/core/TOOLS.md`; mirror when-nots were trimmed and description restatements) + `perToolGuidelines()` `if has <tool>`-gated renderer + `resolveOwnedToolLine()` (tools-section resolver: owned lines only, the description fallback renders no row); pinned by the `tool-guidelines` describe block in test-tool-pipelines.mjs. |
|
|
37
37
|
| `pi-reference-section.ts` | Pi docs seat: `PI_REFERENCE_POINTER` + `piReferenceSection()` - a static pointer to the `pi-reference` skill (docs index + install paths), rendered after the tools section. Replaced the native `<docs>` re-emission; the parity registry marks the native `docs` key dropped. |
|
|
38
|
-
| `system-info-tool.ts` | `system_info` tool: full Instance data on demand (detail
|
|
38
|
+
| `system-info-tool.ts` | `system_info` tool: full Instance data on demand (detail full or compact). The seat for volatile facts (elapsed, last event, turns, tool average) and the core/cwd/settings path triple; a tool result is not a cached prefix. |
|
|
39
39
|
| `inspect.ts` | `prompt_inspect` tool: reads the actual system prompt from runtime. |
|
|
40
40
|
| `tool-description-trim.ts` | Third-party tool-description trim: `before_provider_request` handler that shortens registered descriptions of `herdr_*` tools to 1-2 lines in the API tools channel (curated map + prefix fallback); the deep form moved to the `herdr-topology` skill (progressive disclosure). When-gate preserved in every rewrite. |
|
|
41
41
|
|
|
42
42
|
## Local Contracts
|
|
43
43
|
|
|
44
|
+
### Compact instance line (volatility rule)
|
|
45
|
+
|
|
46
|
+
`renderCompactInstance` renders the one-line `instance` section in the system prompt. The system prompt is a cached prefix, so the line carries process-stable facts only: braid build + install root, model (provider/id), PID, session id, and skill/memory counts. A timestamp, elapsed time, turn count, tool average, or context size would rewrite that prefix on every request and cost more than the field is worth; those facts stay in the `system_info` tool, which is a fresh turn by construction. The counts answer "did the skill pack and memory stores load", not "how many exactly". `test-instance-block.mjs` pins the line: no cwd field, no timestamp or duration token, and a 320-byte cap.
|
|
47
|
+
|
|
44
48
|
### Identity vs behaviors (architectural split)
|
|
45
49
|
|
|
46
50
|
This folder holds the **shared identity layer** -- IDENTITY framings, not project-specific behaviors. The split:
|
|
@@ -40,7 +40,7 @@ import {
|
|
|
40
40
|
} from "./project-docs-section.js";
|
|
41
41
|
import { setCachedSkills, getCachedVisibleSkillNames } from "../skills-tool/index.js";
|
|
42
42
|
import { reconstructMemorySection, resetMemorySectionCache } from "./memory-section.js";
|
|
43
|
-
import { gatherInstanceData } from "./instance-composition.js";
|
|
43
|
+
import { gatherInstanceData, renderCompactInstance } from "./instance-composition.js";
|
|
44
44
|
import { sendTrackedMessage } from "../../../lib/utils/injection-tracker.js";
|
|
45
45
|
import { formatLocalTime } from "../../../lib/utils/local-time.js";
|
|
46
46
|
import { flushRecoveredFires } from "../../../extensions/scheduling/timer/wake-retry.js";
|
|
@@ -434,7 +434,10 @@ export default function promptBuilderExtension(pi: ExtensionAPI) {
|
|
|
434
434
|
} catch {
|
|
435
435
|
/* already init'd or non-fatal */
|
|
436
436
|
}
|
|
437
|
-
|
|
437
|
+
// getAll(limit) slices the in-memory store, so a small limit turned the
|
|
438
|
+
// rendered memory count into a floor of 3. The instance line reports a
|
|
439
|
+
// true count: ask for the whole store.
|
|
440
|
+
memoryCount = memory.getAll(Number.MAX_SAFE_INTEGER).length;
|
|
438
441
|
} catch {
|
|
439
442
|
/* memory unavailable - non-fatal */
|
|
440
443
|
}
|
|
@@ -480,9 +483,12 @@ export default function promptBuilderExtension(pi: ExtensionAPI) {
|
|
|
480
483
|
// Build the prompt as a flat list of sections. Every section is a
|
|
481
484
|
// `PromptSection`; the top-level handler never touches raw strings
|
|
482
485
|
// or arrays of strings.
|
|
483
|
-
// Instance: compact
|
|
484
|
-
//
|
|
485
|
-
//
|
|
486
|
+
// Instance: compact one-line orientation (build + install root, model,
|
|
487
|
+
// PID, session, resource counts); full data stays in the system_info
|
|
488
|
+
// tool. The block carries process-stable facts only: the system prompt
|
|
489
|
+
// is a cached prefix, so a field that changes between turns (a clock,
|
|
490
|
+
// elapsed time, turn or tool counters, context size) would invalidate
|
|
491
|
+
// that prefix on every request and cost more than the field is worth.
|
|
486
492
|
const instanceData = await gatherInstanceData(pi, ctx, {
|
|
487
493
|
skillCount: skills.length,
|
|
488
494
|
skillDirs,
|
|
@@ -493,8 +499,7 @@ export default function promptBuilderExtension(pi: ExtensionAPI) {
|
|
|
493
499
|
})),
|
|
494
500
|
memoryCount,
|
|
495
501
|
});
|
|
496
|
-
const
|
|
497
|
-
const compactInstanceLine = `Agent: Braid v${instanceData.braidVersion} (over pi-core v${instanceData.pi.version}) | Cwd: ${instanceData.cwd} | Session: ${sessionId}`;
|
|
502
|
+
const compactInstanceLine = renderCompactInstance(instanceData);
|
|
498
503
|
// Discovery & exploration stance. Guarded by tool availability: each
|
|
499
504
|
// line only appears when its tools exist; the stance paragraph is
|
|
500
505
|
// unconditional. Placed after guidelines, before tools — a stance, not
|
|
@@ -1,14 +1,26 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Instance Composition: renders the
|
|
3
|
-
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
* the
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
11
|
-
*
|
|
2
|
+
* Instance Composition: two renders over the same gathered data.
|
|
3
|
+
*
|
|
4
|
+
* renderInstance is the full block (versions, runtime paths, OS/PID,
|
|
5
|
+
* session stats, extension packages, other pi instances) served on demand by
|
|
6
|
+
* the system_info tool. renderCompactInstance is the one-line orientation in
|
|
7
|
+
* the system prompt (braid version + install root, model, PID, session id,
|
|
8
|
+
* resource counts).
|
|
9
|
+
*
|
|
10
|
+
* Volatility rule: the system prompt is a cached prefix, so the compact line
|
|
11
|
+
* may carry only process-stable facts. A timestamp, elapsed time, turn count,
|
|
12
|
+
* tool average or context size would rewrite the prefix on every request and
|
|
13
|
+
* cost more than the field is worth; those facts stay in the system_info
|
|
14
|
+
* tool, which is a fresh turn by construction.
|
|
15
|
+
*
|
|
16
|
+
* Invariants: "Core" = pi-core's npm package folder, "braid root" = the
|
|
17
|
+
* loaded pi-braid package folder; packages come from the settings `packages`
|
|
18
|
+
* field (project / user-global, pi-core precedence), never a sibling walk;
|
|
19
|
+
* the pi-core version is pi-core's own `VERSION` export (the library braid is
|
|
20
|
+
* loaded into names the core that is running), with a filesystem walk as the
|
|
21
|
+
* fallback and as the source of the binary/package-folder fields; skills+memory
|
|
22
|
+
* live in memory-section.ts / the list_skills tool; output never contains
|
|
23
|
+
* internal module paths or "->".
|
|
12
24
|
*/
|
|
13
25
|
|
|
14
26
|
import { execSync, spawnSync } from "node:child_process";
|
|
@@ -16,7 +28,7 @@ import { readFileSync, existsSync, realpathSync } from "node:fs";
|
|
|
16
28
|
import { dirname, join } from "node:path";
|
|
17
29
|
import { fileURLToPath } from "node:url";
|
|
18
30
|
import * as os from "node:os";
|
|
19
|
-
import { getAgentDir } from "@earendil-works/pi-coding-agent";
|
|
31
|
+
import { getAgentDir, VERSION as PI_CORE_VERSION } from "@earendil-works/pi-coding-agent";
|
|
20
32
|
import type { PromptSection } from "./section.js";
|
|
21
33
|
import { discoverTopLevelExtensions, type TopLevelExtension } from "./top-level-extensions.js";
|
|
22
34
|
import { gatherL1Environment, type L1EnvironmentData } from "../agent-environment/index.js";
|
|
@@ -33,13 +45,43 @@ export interface SkillEntry {
|
|
|
33
45
|
}
|
|
34
46
|
|
|
35
47
|
interface PiVersionInfo {
|
|
48
|
+
/** The running library's own `VERSION`; the package.json version found by
|
|
49
|
+
* the walk only when that export is unavailable. */
|
|
36
50
|
version: string;
|
|
37
51
|
root: string;
|
|
38
52
|
/** Path to the resolved `pi` binary. */
|
|
39
53
|
binary: string;
|
|
40
54
|
}
|
|
41
55
|
|
|
56
|
+
/**
|
|
57
|
+
* The pi-core version of the library braid is loaded into, read from pi-core's
|
|
58
|
+
* own `VERSION` export.
|
|
59
|
+
*
|
|
60
|
+
* Braid is loaded by the harness, so that constant names the core actually
|
|
61
|
+
* running. A filesystem walk cannot answer the same question: the managed
|
|
62
|
+
* install keeps the entrypoint as a regular shell shim at `bin/pi` (so
|
|
63
|
+
* `realpathSync` changes nothing) and the package in a sibling
|
|
64
|
+
* `install/releases/<version>/node_modules` subtree, which no ancestor of
|
|
65
|
+
* `bin/` contains. Null when the export is absent or is not a version, so the
|
|
66
|
+
* caller falls back to the walk.
|
|
67
|
+
*/
|
|
68
|
+
function piCoreVersionFromLibrary(): string | null {
|
|
69
|
+
const value = typeof PI_CORE_VERSION === "string" ? PI_CORE_VERSION.trim() : "";
|
|
70
|
+
return /^\d+\.\d+\.\d+/.test(value) ? value : null;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/** The pi-core the current process is running over: the library's `VERSION`
|
|
74
|
+
* for the version, the filesystem walk for the binary and package folder. */
|
|
42
75
|
function discoverRunningPi(): PiVersionInfo {
|
|
76
|
+
const located = locateRunningPi();
|
|
77
|
+
const libraryVersion = piCoreVersionFromLibrary();
|
|
78
|
+
return libraryVersion ? { ...located, version: libraryVersion } : located;
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/** Walk PATH and the filesystem for the running pi binary and its package
|
|
82
|
+
* folder. Supplies `root` and `binary`, and a version only as the fallback
|
|
83
|
+
* for a runtime where pi-core's `VERSION` export is missing. */
|
|
84
|
+
function locateRunningPi(): PiVersionInfo {
|
|
43
85
|
// 1. Find the actually-running `pi` binary. We DON'T just call
|
|
44
86
|
// `which pi` because that follows PATH order and can return a
|
|
45
87
|
// stale binary from a sibling repo's `node_modules/.bin` (e.g.
|
|
@@ -175,7 +217,10 @@ function readBraidVersion(): { version: string; root: string } {
|
|
|
175
217
|
} catch {
|
|
176
218
|
// fall through
|
|
177
219
|
}
|
|
178
|
-
|
|
220
|
+
// No cwd fallback: the compact line renders this path as the braid root,
|
|
221
|
+
// and a cwd there would read as a real install while duplicating the
|
|
222
|
+
// pi-injected <cwd>. An unresolved root is the honest value.
|
|
223
|
+
return { version: "unknown", root: "" };
|
|
179
224
|
}
|
|
180
225
|
|
|
181
226
|
// Discovers all `pi` processes running on the system (including the current
|
|
@@ -328,8 +373,14 @@ export interface InstanceContext {
|
|
|
328
373
|
/** Exported for system-info-tool — the full Instance data shape. */
|
|
329
374
|
export interface InstanceData {
|
|
330
375
|
braidVersion: string;
|
|
376
|
+
/** Folder of the running pi-braid package (where the loaded build lives).
|
|
377
|
+
* Empty when resolution failed. */
|
|
378
|
+
braidRoot: string;
|
|
331
379
|
/** Resolved pi-core info (version + npm package folder). */
|
|
332
380
|
pi: PiVersionInfo;
|
|
381
|
+
/** Session model as pi sees it (provider + model id); null when the
|
|
382
|
+
* runtime has no model selected. */
|
|
383
|
+
model: { provider: string; id: string } | null;
|
|
333
384
|
/** Userland pi settings directory (~/.pi/agent or
|
|
334
385
|
* PI_CODING_AGENT_DIR override). The agent uses this to find
|
|
335
386
|
* its own settings, skills, memory, and session files. */
|
|
@@ -371,7 +422,7 @@ export async function gatherInstanceData(
|
|
|
371
422
|
instanceCtx: InstanceContext,
|
|
372
423
|
): Promise<InstanceData> {
|
|
373
424
|
const pi = discoverRunningPi();
|
|
374
|
-
const
|
|
425
|
+
const { version: braidVersion, root: braidRoot } = readBraidVersion();
|
|
375
426
|
const session = gatherL1Environment(_pi, ctx);
|
|
376
427
|
const topLevelExtensions = discoverTopLevelExtensions();
|
|
377
428
|
const osInfo = {
|
|
@@ -388,8 +439,10 @@ export async function gatherInstanceData(
|
|
|
388
439
|
};
|
|
389
440
|
const otherPiInstances = discoverOtherPiInstances();
|
|
390
441
|
return {
|
|
391
|
-
braidVersion
|
|
442
|
+
braidVersion,
|
|
443
|
+
braidRoot,
|
|
392
444
|
pi,
|
|
445
|
+
model: ctx.model ? { provider: String(ctx.model.provider), id: ctx.model.id } : null,
|
|
393
446
|
settingsDir: getAgentDir(),
|
|
394
447
|
os: osInfo,
|
|
395
448
|
cwd: process.cwd(),
|
|
@@ -418,6 +471,37 @@ export async function instanceSection(
|
|
|
418
471
|
};
|
|
419
472
|
}
|
|
420
473
|
|
|
474
|
+
/**
|
|
475
|
+
* The compact Instance line for the system prompt.
|
|
476
|
+
*
|
|
477
|
+
* One field per question the agent would otherwise spend a tool call on:
|
|
478
|
+
*
|
|
479
|
+
* Agent which braid and pi-core build is answering?
|
|
480
|
+
* Root which pi-braid folder is loaded (stale local install vs global)?
|
|
481
|
+
* Model which provider/model will the next request go to?
|
|
482
|
+
* PID which OS process is this session, for ps/lock checks?
|
|
483
|
+
* Session which session file holds this transcript?
|
|
484
|
+
* Resources did the skill pack and memory stores load at all?
|
|
485
|
+
*
|
|
486
|
+
* A field answering only "nice to know" does not belong here, and neither
|
|
487
|
+
* does anything volatile: see the volatility rule in the module docstring.
|
|
488
|
+
* The block is process-stable by construction, so it renders byte-identical
|
|
489
|
+
* on every turn and the provider prefix cache holds across the session.
|
|
490
|
+
*/
|
|
491
|
+
export function renderCompactInstance(d: InstanceData): string {
|
|
492
|
+
const model = d.model ? `${d.model.provider}/${d.model.id}` : "(unset)";
|
|
493
|
+
const skills = `${d.skillCount} skill${d.skillCount === 1 ? "" : "s"}`;
|
|
494
|
+
const memories = `${d.memoryCount} memor${d.memoryCount === 1 ? "y" : "ies"}`;
|
|
495
|
+
return [
|
|
496
|
+
`Agent: Braid v${d.braidVersion} (over pi-core v${d.pi.version})`,
|
|
497
|
+
`Root: ${d.braidRoot || "(unknown)"}`,
|
|
498
|
+
`Model: ${model}`,
|
|
499
|
+
`PID: ${d.session.pid}`,
|
|
500
|
+
`Session: ${d.sessionId || "(unknown)"}`,
|
|
501
|
+
`Resources: ${skills}, ${memories}`,
|
|
502
|
+
].join(" | ");
|
|
503
|
+
}
|
|
504
|
+
|
|
421
505
|
/** Exported for system-info-tool — renders InstanceData to plain text. */
|
|
422
506
|
export async function renderInstance(d: InstanceData): Promise<string> {
|
|
423
507
|
const lines: string[] = [];
|
|
@@ -3,9 +3,9 @@
|
|
|
3
3
|
*
|
|
4
4
|
* Extracts the Instance section (Agent version, pi-core version, paths,
|
|
5
5
|
* OS, session stats, extensions, other instances) from the system prompt
|
|
6
|
-
* into a read-on-demand tool. The prompt keeps only
|
|
7
|
-
* orientation (
|
|
8
|
-
* block lives here.
|
|
6
|
+
* into a read-on-demand tool. The prompt keeps only the compact one-line
|
|
7
|
+
* orientation (build + install root, model, PID, session, resource counts)
|
|
8
|
+
* at the bottom; the full Instance block lives here.
|
|
9
9
|
*
|
|
10
10
|
* This saves ~60-100+ tokens per prompt turn while keeping the data
|
|
11
11
|
* available when the agent actually needs it.
|