pi-braid 0.43.16 → 0.43.18

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 CHANGED
@@ -53,6 +53,34 @@ record; the tag scheme above applies unchanged.
53
53
 
54
54
  ---
55
55
 
56
+ ## Core — 0.43.18 (2026-11-03: braid follows the 1.5.0 harness, and its home link leaves the repository)
57
+
58
+ - **The harness pins move to 1.5.0 and the three surfaces it changed are handled where they live.** 1.5.0
59
+ validates tool schemas through `pi-schema`, and a `StringEnum` now loses its static type at its one read,
60
+ so the action union is named in the module that reads it; `pi-ai` no longer re-exports typebox's `Type`, so
61
+ the providers builder imports it from the package that owns it and declares the peer floor; and the
62
+ release's fatal-error vocabulary gains one token, mirrored in the two lists that already hold that class of
63
+ literal. Two fixtures pin the behaviour rather than the version: a JSON-Schema coercion case and a cost
64
+ reader that keeps `total` and `totalFromProvider` apart.
65
+ - **The package's home link points at the deck, not the repository.** npm metadata is read per version, so
66
+ this release carries the move: `homepage` is `https://kifirkin.github.io` while `repository` stays the
67
+ monorepo, which is why the package page showed the same destination twice.
68
+
69
+ ## Core — 0.43.17 (2026-11-02: a worker session stops being able to message the owner)
70
+
71
+ - **The telegram extension is a factory-level gate now, and the launch that sets it exists.** The worker
72
+ role used to withhold only the poller control and the pull-inbox: `telegram_send`, both process-global
73
+ send seams and two lifecycle senders stayed registered, and nothing in `packages/` wrote the marker the
74
+ extension reads, so "workers never contact the owner" was prompt discipline. A worker session now returns
75
+ from the factory before anything is registered (the read-only poller liveness probe stays, and reads
76
+ false), and the orchestrator's spawn instruction prints the launch that carries the marker: split the
77
+ pane, `export BRAID_SESSION_ROLE=worker` in its shell, then start the agent, which inherits the variable
78
+ and stays addressable in the agent registry; the command-prefix form is documented for one-shot runs.
79
+ Verified live rather than argued: a worker launched this way sees `worker` in its own environment, the
80
+ consumer test is a census of registered tools and send keys in both roles, and a spawned-child test
81
+ proves the marker in the environment is what the factory reads. Residual, stated: a launch that does not
82
+ set the marker still looks like a seat.
83
+
56
84
  ## Core — 0.43.16 (2026-11-02: a skill stops claiming phrases the reader throws away)
57
85
 
58
86
  - **The trigger caps now fit what authors actually write, and a violation fails loudly.** The reader kept
package/README.md CHANGED
@@ -3,7 +3,7 @@
3
3
  # pi-braid
4
4
 
5
5
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6
- [![pi-coding-agent ^1.2.0](https://img.shields.io/badge/pi--coding--agent-%5E1.2.0-blueviolet)](https://github.com/earendil-works/pi)
6
+ [![pi-coding-agent ^1.5.0](https://img.shields.io/badge/pi--coding--agent-%5E1.5.0-blueviolet)](https://github.com/earendil-works/pi)
7
7
 
8
8
  <!-- braid:intro:start -->
9
9
 
package/build-info.json CHANGED
@@ -1,9 +1,9 @@
1
1
  {
2
2
  "name": "pi-braid",
3
- "version": "0.43.16",
4
- "sha": "22a4c1c3ef6d7a1f50a6877810d635eabb021ce1",
5
- "shaShort": "22a4c1c3",
3
+ "version": "0.43.18",
4
+ "sha": "27dd175c0d7724dc9ec7dc570c25174a53a078e5",
5
+ "shaShort": "27dd175c",
6
6
  "branch": "detached",
7
7
  "dirty": false,
8
- "packedAt": "2026-11-02T00:28:28.254Z"
8
+ "packedAt": "2026-11-02T22:01:13.482Z"
9
9
  }
@@ -588,9 +588,20 @@ Spec: ${spec}
588
588
  Output: ${outputFile}
589
589
 
590
590
  To spawn the worker:
591
- 1. Use herdr to create a new pane
592
- 2. Pass the branch name and locked files to the worker
593
- 3. The worker should: git checkout ${branchName}, make changes, commit, then signal completion
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
  }
@@ -154,9 +154,11 @@ export const WAKE_RETRY_MAX_ATTEMPTS = MAX_WAKE_ATTEMPTS_DEFAULT;
154
154
  *
155
155
  * Pinned by test/runtime/lib/test-wake-retry-nonretryable-mirror.mjs, which
156
156
  * reads the token array out of the installed pi-ai module and requires each
157
- * one to be vetoed here. The retryable side below is NOT pinned: it is a
158
- * hand-written subset of pi-ai's retryable classes, so a failure pi-ai retries
159
- * but this mirror does not match settles with no hold. */
157
+ * entry to be vetoed here - including the one pi-ai declares as a pattern
158
+ * rather than a literal (Zhipu/Z.ai's plan-limit code, matched as a JSON body
159
+ * so the bare number does not veto the turn). The retryable side below is NOT
160
+ * pinned: it is a hand-written subset of pi-ai's retryable classes, so a
161
+ * failure pi-ai retries but this mirror does not match settles with no hold. */
160
162
  const WAKE_NON_RETRYABLE_ERROR_PATTERN = new RegExp([
161
163
  "GoUsageLimitError",
162
164
  "FreeUsageLimitError",
@@ -167,6 +169,10 @@ const WAKE_NON_RETRYABLE_ERROR_PATTERN = new RegExp([
167
169
  "quota exceeded",
168
170
  "billing",
169
171
  "subscription_sharing_usage_limit_exceeded",
172
+ "subscription_sharing_workplace_individual_usage_limit_exceeded",
173
+ // Zhipu/Z.ai plan-limit code, matched as the JSON body pi-ai matches; the
174
+ // digit guard keeps a longer number from matching a 1308 prefix.
175
+ '"code"\\s*:\\s*"?1308(?![0-9])',
170
176
  ].join("|"), "i");
171
177
  /** The retryable classes braid mirrors from pi-core's
172
178
  * RETRYABLE_PROVIDER_ERROR_PATTERN (pi-ai/dist/utils/retry.js): transport
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 - 100 of the core suite's 335 fixtures already use `node:test` - so the
141
+ file uses - 103 of the core suite's 338 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.16",
3
+ "version": "0.43.18",
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",
@@ -35,7 +35,7 @@
35
35
  "bugs": {
36
36
  "url": "https://github.com/kifirkin/pi-braid/issues"
37
37
  },
38
- "homepage": "https://github.com/kifirkin/pi-braid#readme",
38
+ "homepage": "https://kifirkin.github.io",
39
39
  "pi": {
40
40
  "extensions": [
41
41
  "./src/index.ts"
@@ -81,10 +81,10 @@
81
81
  "typescript-eslint": "8.59.1"
82
82
  },
83
83
  "peerDependencies": {
84
- "@earendil-works/pi-agent-core": "^1.2.0",
85
- "@earendil-works/pi-ai": "^1.2.0",
86
- "@earendil-works/pi-coding-agent": "^1.2.0",
87
- "@earendil-works/pi-tui": "^1.2.0",
84
+ "@earendil-works/pi-agent-core": "^1.5.0",
85
+ "@earendil-works/pi-ai": "^1.5.0",
86
+ "@earendil-works/pi-coding-agent": "^1.5.0",
87
+ "@earendil-works/pi-tui": "^1.5.0",
88
88
  "typebox": "^1.1.38"
89
89
  },
90
90
  "keywords": [
@@ -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. The worker checks out the branch, makes changes, commits, signals completion
88
- 4. orchestrate action=verify-and-merge workerId=<id> branch=worker/<id>/<slug>
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
- 5. orchestrate action=release-locks workerId=<id>
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. Start TUI pi: herdr action=run pane=<worker> command="pi"
100
- 3. Wait for pi to render its prompt, then give the task:
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 |
@@ -876,9 +876,20 @@ Spec: ${spec}
876
876
  Output: ${outputFile}
877
877
 
878
878
  To spawn the worker:
879
- 1. Use herdr to create a new pane
880
- 2. Pass the branch name and locked files to the worker
881
- 3. The worker should: git checkout ${branchName}, make changes, commit, then signal completion
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 },
@@ -225,9 +225,11 @@ export const WAKE_RETRY_MAX_ATTEMPTS = MAX_WAKE_ATTEMPTS_DEFAULT;
225
225
  *
226
226
  * Pinned by test/runtime/lib/test-wake-retry-nonretryable-mirror.mjs, which
227
227
  * reads the token array out of the installed pi-ai module and requires each
228
- * one to be vetoed here. The retryable side below is NOT pinned: it is a
229
- * hand-written subset of pi-ai's retryable classes, so a failure pi-ai retries
230
- * but this mirror does not match settles with no hold. */
228
+ * entry to be vetoed here - including the one pi-ai declares as a pattern
229
+ * rather than a literal (Zhipu/Z.ai's plan-limit code, matched as a JSON body
230
+ * so the bare number does not veto the turn). The retryable side below is NOT
231
+ * pinned: it is a hand-written subset of pi-ai's retryable classes, so a
232
+ * failure pi-ai retries but this mirror does not match settles with no hold. */
231
233
  const WAKE_NON_RETRYABLE_ERROR_PATTERN = new RegExp(
232
234
  [
233
235
  "GoUsageLimitError",
@@ -239,6 +241,10 @@ const WAKE_NON_RETRYABLE_ERROR_PATTERN = new RegExp(
239
241
  "quota exceeded",
240
242
  "billing",
241
243
  "subscription_sharing_usage_limit_exceeded",
244
+ "subscription_sharing_workplace_individual_usage_limit_exceeded",
245
+ // Zhipu/Z.ai plan-limit code, matched as the JSON body pi-ai matches; the
246
+ // digit guard keeps a longer number from matching a 1308 prefix.
247
+ '"code"\\s*:\\s*"?1308(?![0-9])',
242
248
  ].join("|"),
243
249
  "i",
244
250
  );
@@ -42,6 +42,16 @@ const EVOLVE_ACTIONS = [
42
42
  "benchmark",
43
43
  ] as const;
44
44
 
45
+ /**
46
+ * The action union the schema declares. `StringEnum` returns a pi-schema
47
+ * `Schema<T>`, which TypeBox's `Static` cannot read, so the framework infers
48
+ * `params.action` as `unknown` while every hand-written field beside it keeps
49
+ * its type. The alias restores the declared union at the one read that needs a
50
+ * string; it coerces nothing, so a value the schema would not accept still
51
+ * cannot reach this file.
52
+ */
53
+ type EvolveAction = (typeof EVOLVE_ACTIONS)[number];
54
+
45
55
  const healthMaintenanceSchema = Type.Object({
46
56
  action: StringEnum([...EVOLVE_ACTIONS], { description: "Action to perform" }),
47
57
  checkpoint: Type.Optional(Type.String({ description: "Checkpoint hash for rollback" })),
@@ -209,7 +219,7 @@ export default function healthMaintenanceExtension(pi: ExtensionAPI) {
209
219
  };
210
220
  } catch (error) {
211
221
  const errorResult: HealthMaintenanceResult = {
212
- action: params.action,
222
+ action: params.action as EvolveAction,
213
223
  success: false,
214
224
  error: error instanceof Error ? error.message : String(error),
215
225
  };