pi-braid 0.43.12 → 0.43.17
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/CHANGELOG.md +37 -0
- package/build-info.json +4 -4
- package/dist/extensions/core/skills-tool/skill-triggers.d.ts +21 -9
- package/dist/extensions/core/skills-tool/skill-triggers.js +21 -9
- package/dist/extensions/orchestrator/index.js +14 -3
- package/docs/LOCAL_DEV.md +1 -1
- package/package.json +1 -1
- package/skills/subagent-orchestration/SKILL.md +30 -6
- package/src/extensions/core/skills-tool/skill-triggers.ts +21 -9
- package/src/extensions/orchestrator/index.ts +14 -3
package/CHANGELOG.md
CHANGED
|
@@ -53,6 +53,43 @@ record; the tag scheme above applies unchanged.
|
|
|
53
53
|
|
|
54
54
|
---
|
|
55
55
|
|
|
56
|
+
## Core — 0.43.17 (2026-11-02: a worker session stops being able to message the owner)
|
|
57
|
+
|
|
58
|
+
- **The telegram extension is a factory-level gate now, and the launch that sets it exists.** The worker
|
|
59
|
+
role used to withhold only the poller control and the pull-inbox: `telegram_send`, both process-global
|
|
60
|
+
send seams and two lifecycle senders stayed registered, and nothing in `packages/` wrote the marker the
|
|
61
|
+
extension reads, so "workers never contact the owner" was prompt discipline. A worker session now returns
|
|
62
|
+
from the factory before anything is registered (the read-only poller liveness probe stays, and reads
|
|
63
|
+
false), and the orchestrator's spawn instruction prints the launch that carries the marker: split the
|
|
64
|
+
pane, `export BRAID_SESSION_ROLE=worker` in its shell, then start the agent, which inherits the variable
|
|
65
|
+
and stays addressable in the agent registry; the command-prefix form is documented for one-shot runs.
|
|
66
|
+
Verified live rather than argued: a worker launched this way sees `worker` in its own environment, the
|
|
67
|
+
consumer test is a census of registered tools and send keys in both roles, and a spawned-child test
|
|
68
|
+
proves the marker in the environment is what the factory reads. Residual, stated: a launch that does not
|
|
69
|
+
set the marker still looks like a seat.
|
|
70
|
+
|
|
71
|
+
## Core — 0.43.16 (2026-11-02: a skill stops claiming phrases the reader throws away)
|
|
72
|
+
|
|
73
|
+
- **The trigger caps now fit what authors actually write, and a violation fails loudly.** The reader kept
|
|
74
|
+
12 phrases per skill and dropped the rest in silence, so three skills were claiming words that could
|
|
75
|
+
never match: `braid-reference` authored 16, `pi-reference` 15, `voice-replies` 13, and
|
|
76
|
+
`subagent-verification` had a 66-character phrase against a 64 cap. A question about `polyfill` or
|
|
77
|
+
`braid install paths` did not reach the skill that advertises it. The caps are 16 and 66, and the
|
|
78
|
+
justification is measured rather than argued: a phrase compiles to one word-bounded substring test over
|
|
79
|
+
the prompt, reaches no prompt, and costs the same at any length — 4.35 µs at 50 characters, 4.34 at 66,
|
|
80
|
+
4.32 at 98. So the old numbers bounded shape, not hazard, and the shape they bounded was wrong. A new
|
|
81
|
+
fixture reads the authored files itself and fails naming a skill that overflows, because the reader
|
|
82
|
+
cannot answer the question once the cap has already spent the list.
|
|
83
|
+
- **The TypeBox surface is pinned to JSON Schema, so the announced pi-schema swap stays an import edit.**
|
|
84
|
+
A fixture refuses any constructor outside the eight the tree uses, the six features JSON Schema cannot
|
|
85
|
+
carry, and any imported symbol beyond `Type` and a type-only `Static`. The point is timing: the way a
|
|
86
|
+
mechanical swap becomes a rewrite is somebody reaching for `Type.Refine` for a good local reason six
|
|
87
|
+
weeks before the dependency moves.
|
|
88
|
+
- **The skills block is priced the way an agent reads it.** The only gate that priced it measured one
|
|
89
|
+
pack; an agent reads the union. Every pack is now discovered from its manifest, each prices separately,
|
|
90
|
+
and one composition over the union prints the total, with controls proving the number moves when a row
|
|
91
|
+
moves and that the union is never the sum of separate renders.
|
|
92
|
+
|
|
56
93
|
## Core — 0.43.12 (2026-11-01: a skill that says it is retired stops being advertised)
|
|
57
94
|
|
|
58
95
|
- **A retired skill no longer competes with its successor.** Four skills in the packs declare
|
package/build-info.json
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-braid",
|
|
3
|
-
"version": "0.43.
|
|
4
|
-
"sha": "
|
|
5
|
-
"shaShort": "
|
|
3
|
+
"version": "0.43.17",
|
|
4
|
+
"sha": "5363db1f32ef66d9ab33dcbea97a6e4b4c18dfe3",
|
|
5
|
+
"shaShort": "5363db1f",
|
|
6
6
|
"branch": "detached",
|
|
7
7
|
"dirty": false,
|
|
8
|
-
"packedAt": "2026-11-
|
|
8
|
+
"packedAt": "2026-11-02T19:37:07.011Z"
|
|
9
9
|
}
|
|
@@ -36,16 +36,28 @@
|
|
|
36
36
|
* same bytes per process, and a status is not worth one.
|
|
37
37
|
*/
|
|
38
38
|
/**
|
|
39
|
-
* Max trigger phrases
|
|
40
|
-
*
|
|
41
|
-
*
|
|
42
|
-
*
|
|
43
|
-
*
|
|
44
|
-
*
|
|
39
|
+
* Max trigger phrases kept per skill: a budget, spent down the merged list so
|
|
40
|
+
* the lowest-priority source loses first. Past it the reader drops the tail and
|
|
41
|
+
* reports nothing, which is why test-trigger-cap.mjs reads the authored files
|
|
42
|
+
* itself and fails by name: a claim past the cap is a build failure, not a
|
|
43
|
+
* silent loss.
|
|
44
|
+
*
|
|
45
|
+
* It bounds what one file may claim, not what a turn may spend. A phrase costs
|
|
46
|
+
* one word-bounded regex test over the prompt per turn (`triggerMatches`, from
|
|
47
|
+
* the suggestion matcher and the applicability pass) — flat in the phrase,
|
|
48
|
+
* linear in the prompt — so the ceiling is about shape: a list this long is a
|
|
49
|
+
* page of situations, and a longer one is a description in disguise.
|
|
50
|
+
*/
|
|
51
|
+
export declare const MAX_TRIGGERS = 16;
|
|
52
|
+
/**
|
|
53
|
+
* Max characters of one trigger phrase. A phrase compiles to a literal,
|
|
54
|
+
* word-bounded substring test: it reaches no prompt and costs the same at any
|
|
55
|
+
* length, so this is a shape bound rather than a hazard bound. A string long
|
|
56
|
+
* enough to be a sentence is a condition, and it matches only a prompt that
|
|
57
|
+
* carries that sentence verbatim. The bound sits above the longest shipped
|
|
58
|
+
* phrase, and test-trigger-cap.mjs fails by name past it.
|
|
45
59
|
*/
|
|
46
|
-
export declare const
|
|
47
|
-
/** Max characters of one trigger phrase. */
|
|
48
|
-
export declare const MAX_TRIGGER_CHARS = 64;
|
|
60
|
+
export declare const MAX_TRIGGER_CHARS = 66;
|
|
49
61
|
/**
|
|
50
62
|
* Where an authored phrase came from. Precedence (frontmatter, heading,
|
|
51
63
|
* description) orders the merged list and decides which source the cap cuts
|
|
@@ -38,16 +38,28 @@
|
|
|
38
38
|
import { statSync, readFileSync } from "node:fs";
|
|
39
39
|
import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
|
|
40
40
|
/**
|
|
41
|
-
* Max trigger phrases
|
|
42
|
-
*
|
|
43
|
-
*
|
|
44
|
-
*
|
|
45
|
-
*
|
|
46
|
-
*
|
|
41
|
+
* Max trigger phrases kept per skill: a budget, spent down the merged list so
|
|
42
|
+
* the lowest-priority source loses first. Past it the reader drops the tail and
|
|
43
|
+
* reports nothing, which is why test-trigger-cap.mjs reads the authored files
|
|
44
|
+
* itself and fails by name: a claim past the cap is a build failure, not a
|
|
45
|
+
* silent loss.
|
|
46
|
+
*
|
|
47
|
+
* It bounds what one file may claim, not what a turn may spend. A phrase costs
|
|
48
|
+
* one word-bounded regex test over the prompt per turn (`triggerMatches`, from
|
|
49
|
+
* the suggestion matcher and the applicability pass) — flat in the phrase,
|
|
50
|
+
* linear in the prompt — so the ceiling is about shape: a list this long is a
|
|
51
|
+
* page of situations, and a longer one is a description in disguise.
|
|
52
|
+
*/
|
|
53
|
+
export const MAX_TRIGGERS = 16;
|
|
54
|
+
/**
|
|
55
|
+
* Max characters of one trigger phrase. A phrase compiles to a literal,
|
|
56
|
+
* word-bounded substring test: it reaches no prompt and costs the same at any
|
|
57
|
+
* length, so this is a shape bound rather than a hazard bound. A string long
|
|
58
|
+
* enough to be a sentence is a condition, and it matches only a prompt that
|
|
59
|
+
* carries that sentence verbatim. The bound sits above the longest shipped
|
|
60
|
+
* phrase, and test-trigger-cap.mjs fails by name past it.
|
|
47
61
|
*/
|
|
48
|
-
export const
|
|
49
|
-
/** Max characters of one trigger phrase. */
|
|
50
|
-
export const MAX_TRIGGER_CHARS = 64;
|
|
62
|
+
export const MAX_TRIGGER_CHARS = 66;
|
|
51
63
|
const cache = new Map();
|
|
52
64
|
/** Compiled word-boundary matchers, memoized per normalized phrase. */
|
|
53
65
|
const regexCache = new Map();
|
|
@@ -588,9 +588,20 @@ Spec: ${spec}
|
|
|
588
588
|
Output: ${outputFile}
|
|
589
589
|
|
|
590
590
|
To spawn the worker:
|
|
591
|
-
1.
|
|
592
|
-
2.
|
|
593
|
-
|
|
591
|
+
1. Split a pane for it: herdr_layout action=pane_split cwd=<project-root>
|
|
592
|
+
2. Put the role marker in that pane's shell, before the agent starts:
|
|
593
|
+
herdr_pane action=run pane=<pane-id> command="export BRAID_SESSION_ROLE=worker"
|
|
594
|
+
3. Start pi in the same pane through the agent channel, so the exported marker is inherited and the
|
|
595
|
+
seat can still drive and read the worker by name:
|
|
596
|
+
herdr_agent action=start pane=<pane-id> kind=pi name=<worker-id>
|
|
597
|
+
4. The worker should: git checkout ${branchName}, make changes, commit, then signal completion
|
|
598
|
+
|
|
599
|
+
A launch driven without the agent CLI (a one-shot json run, a pane nobody babysits) carries the
|
|
600
|
+
marker as a command prefix instead: command="BRAID_SESSION_ROLE=worker pi". Same environment,
|
|
601
|
+
no agent entry to prompt or read through.
|
|
602
|
+
|
|
603
|
+
The marker is what makes the worker session a worker to the extensions that read it: a process
|
|
604
|
+
started without it registers the seat's own outbound surfaces, including the Telegram channel.
|
|
594
605
|
|
|
595
606
|
When the worker signals completion, use orchestrate action=verify-and-merge to review and merge.`, { entry: registered.entry });
|
|
596
607
|
}
|
package/docs/LOCAL_DEV.md
CHANGED
|
@@ -138,7 +138,7 @@ before and after a full run. A non-zero delta is the leak this rule prevents.
|
|
|
138
138
|
### New fixtures: use `node:test`
|
|
139
139
|
|
|
140
140
|
A new fixture is written on `node:test`. The runner does not care which style a
|
|
141
|
-
file uses -
|
|
141
|
+
file uses - 101 of the core suite's 336 fixtures already use `node:test` - so the
|
|
142
142
|
reason is the failure the other style produces. A hand-rolled helper that calls
|
|
143
143
|
`fn()` without awaiting it discards the case's promise, so an `async` case runs
|
|
144
144
|
detached and the file can print its green tally before that case settles, with
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-braid",
|
|
3
|
-
"version": "0.43.
|
|
3
|
+
"version": "0.43.17",
|
|
4
4
|
"description": "🥨 Braid - Metacognitive extension suite for pi coding agent: Adds memory, plan tracking, structured cognitive signals and completion checks on top of pi core loop, so long sessions keep their context and stop claiming unfinished work.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -84,10 +84,14 @@ Uses the built-in `orchestrate` tool for code-modification tasks in git repos. H
|
|
|
84
84
|
1. Determine the task, target files, and repo
|
|
85
85
|
2. orchestrate action=spawn-worker workerId=<id> slug=<kebab-task> files=[<file-paths>]
|
|
86
86
|
— Creates branch worker/<id>/<slug> and locks the files
|
|
87
|
-
3.
|
|
88
|
-
|
|
87
|
+
3. Launch it in its own pane, marked as a worker, with the commands the spawn result prints:
|
|
88
|
+
herdr action=pane_split cwd=<repo-dir>, then
|
|
89
|
+
herdr action=run pane=<pane> command="export BRAID_SESSION_ROLE=worker", then
|
|
90
|
+
herdr_agent start <name> --kind pi --pane <pane>
|
|
91
|
+
4. The worker checks out the branch, makes changes, commits, signals completion
|
|
92
|
+
5. orchestrate action=verify-and-merge workerId=<id> branch=worker/<id>/<slug>
|
|
89
93
|
— Reads the diff, prompts for verification, squash-merges to main
|
|
90
|
-
|
|
94
|
+
6. orchestrate action=release-locks workerId=<id>
|
|
91
95
|
```
|
|
92
96
|
|
|
93
97
|
**Lock-only mode**: When CWD is not a git repo, orchestrate falls back to lock-only coordination. Use herdr for task handoff.
|
|
@@ -96,8 +100,9 @@ Uses the built-in `orchestrate` tool for code-modification tasks in git repos. H
|
|
|
96
100
|
|
|
97
101
|
```
|
|
98
102
|
1. Create pane: herdr action=pane_split cwd=<target> label=worker-<task>
|
|
99
|
-
2.
|
|
100
|
-
3.
|
|
103
|
+
2. Export the role marker in that pane's shell: herdr action=run pane=<worker> command="export BRAID_SESSION_ROLE=worker"
|
|
104
|
+
3. Start TUI pi from that shell, through the agent channel: herdr_agent start <name> --kind pi --pane <worker>
|
|
105
|
+
4. Wait for pi to render its prompt, then give the task:
|
|
101
106
|
herdr action=send pane=<worker> text="[agent:orchestrator→worker] <task>"
|
|
102
107
|
```
|
|
103
108
|
|
|
@@ -108,14 +113,33 @@ The worker signals completion back via `herdr send`.
|
|
|
108
113
|
|
|
109
114
|
```
|
|
110
115
|
1. Create pane: herdr action=pane_split cwd=<target> label=worker-<task>
|
|
111
|
-
2. Start pi: herdr action=run pane=<worker> command="pi --mode json '<task>' 2>/dev/null"
|
|
116
|
+
2. Start pi: herdr action=run pane=<worker> command="BRAID_SESSION_ROLE=worker pi --mode json '<task>' 2>/dev/null"
|
|
112
117
|
3. Read output: herdr action=read pane=<worker> source=recent
|
|
113
118
|
```
|
|
114
119
|
|
|
115
120
|
JSON mode exits after one turn. Use for simple extraction where you don't need ongoing control.
|
|
121
|
+
It carries the marker as a command prefix because there is no agent entry to inherit an export
|
|
122
|
+
through: the process is gone when the turn ends.
|
|
116
123
|
|
|
117
124
|
**CRITICAL: `pane_split` creates a SHELL, not an agent.** You MUST `herdr action=run` to start pi inside the pane. `herdr action=send` is for signaling between already-running agents - it does NOT start a task. Use `herdr action=run` to start, then `herdr send` to signal.
|
|
118
125
|
|
|
126
|
+
**Mark every worker launch.** The marker goes into the environment the agent process is exec'd
|
|
127
|
+
with, so it has to be set before the agent starts:
|
|
128
|
+
|
|
129
|
+
```
|
|
130
|
+
herdr action=run pane=<worker> command="export BRAID_SESSION_ROLE=worker"
|
|
131
|
+
herdr_agent start <name> --kind pi --pane <worker>
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
`herdr agent start` has `--kind`, `--pane`, `--timeout` and trailing agent arguments, no env
|
|
135
|
+
option, so the export is the only way to give the agent the marker and keep it in the agent
|
|
136
|
+
registry (lifecycle states, prompts, reads). A launch that is not driven through the agent CLI
|
|
137
|
+
carries the marker as a command prefix instead, `command="BRAID_SESSION_ROLE=worker pi"`: the
|
|
138
|
+
same environment, and no agent entry to babysit through. An unmarked worker is a seat to every
|
|
139
|
+
extension that reads the marker: it registers the outbound surfaces a seat owns, the Telegram
|
|
140
|
+
channel among them, so it can message the owner with the seat's own bot token and can try to
|
|
141
|
+
take the getUpdates singleton the seat is polling.
|
|
142
|
+
|
|
119
143
|
### Which to use
|
|
120
144
|
|
|
121
145
|
| Situation | Method |
|
|
@@ -40,17 +40,29 @@ import { statSync, readFileSync } from "node:fs";
|
|
|
40
40
|
import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
|
|
41
41
|
|
|
42
42
|
/**
|
|
43
|
-
* Max trigger phrases
|
|
44
|
-
*
|
|
45
|
-
*
|
|
46
|
-
*
|
|
47
|
-
*
|
|
48
|
-
*
|
|
43
|
+
* Max trigger phrases kept per skill: a budget, spent down the merged list so
|
|
44
|
+
* the lowest-priority source loses first. Past it the reader drops the tail and
|
|
45
|
+
* reports nothing, which is why test-trigger-cap.mjs reads the authored files
|
|
46
|
+
* itself and fails by name: a claim past the cap is a build failure, not a
|
|
47
|
+
* silent loss.
|
|
48
|
+
*
|
|
49
|
+
* It bounds what one file may claim, not what a turn may spend. A phrase costs
|
|
50
|
+
* one word-bounded regex test over the prompt per turn (`triggerMatches`, from
|
|
51
|
+
* the suggestion matcher and the applicability pass) — flat in the phrase,
|
|
52
|
+
* linear in the prompt — so the ceiling is about shape: a list this long is a
|
|
53
|
+
* page of situations, and a longer one is a description in disguise.
|
|
49
54
|
*/
|
|
50
|
-
export const MAX_TRIGGERS =
|
|
55
|
+
export const MAX_TRIGGERS = 16;
|
|
51
56
|
|
|
52
|
-
/**
|
|
53
|
-
|
|
57
|
+
/**
|
|
58
|
+
* Max characters of one trigger phrase. A phrase compiles to a literal,
|
|
59
|
+
* word-bounded substring test: it reaches no prompt and costs the same at any
|
|
60
|
+
* length, so this is a shape bound rather than a hazard bound. A string long
|
|
61
|
+
* enough to be a sentence is a condition, and it matches only a prompt that
|
|
62
|
+
* carries that sentence verbatim. The bound sits above the longest shipped
|
|
63
|
+
* phrase, and test-trigger-cap.mjs fails by name past it.
|
|
64
|
+
*/
|
|
65
|
+
export const MAX_TRIGGER_CHARS = 66;
|
|
54
66
|
|
|
55
67
|
/**
|
|
56
68
|
* Where an authored phrase came from. Precedence (frontmatter, heading,
|
|
@@ -876,9 +876,20 @@ Spec: ${spec}
|
|
|
876
876
|
Output: ${outputFile}
|
|
877
877
|
|
|
878
878
|
To spawn the worker:
|
|
879
|
-
1.
|
|
880
|
-
2.
|
|
881
|
-
|
|
879
|
+
1. Split a pane for it: herdr_layout action=pane_split cwd=<project-root>
|
|
880
|
+
2. Put the role marker in that pane's shell, before the agent starts:
|
|
881
|
+
herdr_pane action=run pane=<pane-id> command="export BRAID_SESSION_ROLE=worker"
|
|
882
|
+
3. Start pi in the same pane through the agent channel, so the exported marker is inherited and the
|
|
883
|
+
seat can still drive and read the worker by name:
|
|
884
|
+
herdr_agent action=start pane=<pane-id> kind=pi name=<worker-id>
|
|
885
|
+
4. The worker should: git checkout ${branchName}, make changes, commit, then signal completion
|
|
886
|
+
|
|
887
|
+
A launch driven without the agent CLI (a one-shot json run, a pane nobody babysits) carries the
|
|
888
|
+
marker as a command prefix instead: command="BRAID_SESSION_ROLE=worker pi". Same environment,
|
|
889
|
+
no agent entry to prompt or read through.
|
|
890
|
+
|
|
891
|
+
The marker is what makes the worker session a worker to the extensions that read it: a process
|
|
892
|
+
started without it registers the seat's own outbound surfaces, including the Telegram channel.
|
|
882
893
|
|
|
883
894
|
When the worker signals completion, use orchestrate action=verify-and-merge to review and merge.`,
|
|
884
895
|
{ entry: registered.entry },
|