@niwa-labs/pstack 0.0.0-stage → 0.0.0

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 (163) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +260 -2
  3. package/package.json +28 -4
  4. package/scripts/upstream-map.ts +90 -0
  5. package/src/author.ts +57 -0
  6. package/src/binding.ts +32 -0
  7. package/src/catalog.ts +86 -0
  8. package/src/composition.ts +66 -0
  9. package/src/index.ts +50 -0
  10. package/src/mapping/analyze.ts +223 -0
  11. package/src/mapping/assemble.ts +96 -0
  12. package/src/mapping/diff.ts +139 -0
  13. package/src/mapping/format.ts +67 -0
  14. package/src/mapping/git.ts +69 -0
  15. package/src/mapping/index.ts +18 -0
  16. package/src/mapping/maintain.ts +36 -0
  17. package/src/mapping/schema.ts +50 -0
  18. package/src/mapping/sources.ts +108 -0
  19. package/src/mapping/tool.ts +77 -0
  20. package/src/mapping/verify.ts +130 -0
  21. package/src/plugin.ts +136 -0
  22. package/src/policy.ts +115 -0
  23. package/src/ports.ts +184 -0
  24. package/src/pr-binding.ts +88 -0
  25. package/src/records.ts +61 -0
  26. package/src/roles.ts +49 -0
  27. package/src/trunk.ts +59 -0
  28. package/src/upstream-actions.ts +135 -0
  29. package/src/upstream-records.ts +71 -0
  30. package/src/upstream.ts +151 -0
  31. package/src/workflows/adapted.md +780 -0
  32. package/src/workflows/authoring-a-skill.ts +52 -0
  33. package/src/workflows/autonomous-run.ts +56 -0
  34. package/src/workflows/autopilot-full.ts +90 -0
  35. package/src/workflows/autopilot-stack.ts +125 -0
  36. package/src/workflows/babysit.ts +124 -0
  37. package/src/workflows/benny-reproduce.ts +122 -0
  38. package/src/workflows/benny-triage.ts +89 -0
  39. package/src/workflows/bug-fix.ts +54 -0
  40. package/src/workflows/entry.ts +130 -0
  41. package/src/workflows/eval.ts +63 -0
  42. package/src/workflows/feature.ts +54 -0
  43. package/src/workflows/hillclimb.ts +78 -0
  44. package/src/workflows/investigation.ts +41 -0
  45. package/src/workflows/lib/catalog.ts +45 -0
  46. package/src/workflows/lib/change.ts +70 -0
  47. package/src/workflows/lib/forensics.ts +37 -0
  48. package/src/workflows/lib/git.ts +30 -0
  49. package/src/workflows/lib/go.ts +58 -0
  50. package/src/workflows/lib/inputs.ts +34 -0
  51. package/src/workflows/lib/lane.ts +170 -0
  52. package/src/workflows/lib/measure.ts +34 -0
  53. package/src/workflows/lib/plan.ts +24 -0
  54. package/src/workflows/lib/script.ts +79 -0
  55. package/src/workflows/lib/ship.ts +110 -0
  56. package/src/workflows/lib/texts.ts +18 -0
  57. package/src/workflows/lib/trunk.ts +91 -0
  58. package/src/workflows/multi-phase-plan.ts +83 -0
  59. package/src/workflows/opening-a-pr.ts +62 -0
  60. package/src/workflows/pause-safely.ts +50 -0
  61. package/src/workflows/perf-issue.ts +87 -0
  62. package/src/workflows/prototype.ts +76 -0
  63. package/src/workflows/refactoring.ts +54 -0
  64. package/src/workflows/runtime-forensics.ts +26 -0
  65. package/src/workflows/scenarios.ts +380 -0
  66. package/src/workflows/session-pickup.ts +57 -0
  67. package/src/workflows/shipping.ts +63 -0
  68. package/src/workflows/suite.ts +129 -0
  69. package/src/workflows/texts/authoring-a-skill.json +5 -0
  70. package/src/workflows/texts/autonomous-run.json +5 -0
  71. package/src/workflows/texts/autopilot-full.json +5 -0
  72. package/src/workflows/texts/autopilot-stack.json +5 -0
  73. package/src/workflows/texts/babysit.json +5 -0
  74. package/src/workflows/texts/benny-reproduce.json +5 -0
  75. package/src/workflows/texts/benny-triage.json +5 -0
  76. package/src/workflows/texts/bug-fix.json +5 -0
  77. package/src/workflows/texts/bugbot-triage.json +5 -0
  78. package/src/workflows/texts/eval.json +5 -0
  79. package/src/workflows/texts/feature.json +5 -0
  80. package/src/workflows/texts/hillclimb.json +5 -0
  81. package/src/workflows/texts/investigation.json +5 -0
  82. package/src/workflows/texts/multi-phase-plan.json +5 -0
  83. package/src/workflows/texts/opening-a-pr.json +5 -0
  84. package/src/workflows/texts/pause-safely.json +5 -0
  85. package/src/workflows/texts/perf-issue.json +5 -0
  86. package/src/workflows/texts/prototype.json +5 -0
  87. package/src/workflows/texts/refactoring.json +5 -0
  88. package/src/workflows/texts/runtime-forensics.json +5 -0
  89. package/src/workflows/texts/session-pickup.json +5 -0
  90. package/src/workflows/texts/trace-forensics.json +5 -0
  91. package/src/workflows/texts/visual-parity.json +5 -0
  92. package/src/workflows/texts/worker.json +5 -0
  93. package/src/workflows/trace-forensics.ts +27 -0
  94. package/src/workflows/upstream-sync.ts +182 -0
  95. package/src/workflows/visual-parity.ts +52 -0
  96. package/src/workflows/worktree-cleanup.ts +57 -0
  97. package/test/author.test.ts +61 -0
  98. package/test/benny.test.ts +138 -0
  99. package/test/binding.test.ts +54 -0
  100. package/test/catalog-helpers.test.ts +49 -0
  101. package/test/closure.test.ts +45 -0
  102. package/test/composition.test.ts +23 -0
  103. package/test/eval.test.ts +23 -0
  104. package/test/lanes.test.ts +334 -0
  105. package/test/mapping-diff.test.ts +64 -0
  106. package/test/mapping-support.ts +110 -0
  107. package/test/mapping-texts.test.ts +106 -0
  108. package/test/mapping.test.ts +276 -0
  109. package/test/package-layout.ts +68 -0
  110. package/test/policy.test.ts +98 -0
  111. package/test/ports.test.ts +45 -0
  112. package/test/ports.ts +173 -0
  113. package/test/roles.test.ts +21 -0
  114. package/test/suite.test.ts +167 -0
  115. package/test/support.ts +541 -0
  116. package/test/texts.test.ts +174 -0
  117. package/test/tool.test.ts +48 -0
  118. package/test/trunk-helpers.test.ts +149 -0
  119. package/test/trunk.test.ts +24 -0
  120. package/test/upstream-sync.test.ts +246 -0
  121. package/test/upstream.test.ts +106 -0
  122. package/test/worktree-cleanup.test.ts +107 -0
  123. package/tsconfig.json +7 -0
  124. package/upstream/LICENSE +21 -0
  125. package/upstream/SOURCE.json +5 -0
  126. package/upstream/benny/FOR_AGENTS.md +89 -0
  127. package/upstream/benny/README.md +23 -0
  128. package/upstream/benny/skills/reproduce-and-fix-issues/SKILL.md +310 -0
  129. package/upstream/benny/skills/reproduce-and-fix-issues/references/control-adapter.md +169 -0
  130. package/upstream/benny/skills/reproduce-and-fix-issues/references/feature-map.example.md +205 -0
  131. package/upstream/benny/skills/reproduce-and-fix-issues/references/verify-existing-fix.md +93 -0
  132. package/upstream/benny/skills/setup-benny/SKILL.md +265 -0
  133. package/upstream/benny/skills/triage-issue-reports/SKILL.md +240 -0
  134. package/upstream/benny/skills/triage-issue-reports/references/routing.example.md +61 -0
  135. package/upstream/benny/templates/configuration.example.yaml +84 -0
  136. package/upstream/benny/templates/reproduce-automation-prompt.md +33 -0
  137. package/upstream/benny/templates/triage-automation-prompt.md +39 -0
  138. package/upstream/mapping.json +699 -0
  139. package/upstream/poteto-mode/SKILL.md +110 -0
  140. package/upstream/poteto-mode/playbooks/authoring-a-skill.md +12 -0
  141. package/upstream/poteto-mode/playbooks/autonomous-run.md +13 -0
  142. package/upstream/poteto-mode/playbooks/autopilot-full.md +25 -0
  143. package/upstream/poteto-mode/playbooks/autopilot-stack.md +8 -0
  144. package/upstream/poteto-mode/playbooks/babysit.md +10 -0
  145. package/upstream/poteto-mode/playbooks/bug-fix.md +15 -0
  146. package/upstream/poteto-mode/playbooks/eval.md +25 -0
  147. package/upstream/poteto-mode/playbooks/feature.md +21 -0
  148. package/upstream/poteto-mode/playbooks/hillclimb.md +21 -0
  149. package/upstream/poteto-mode/playbooks/investigation.md +14 -0
  150. package/upstream/poteto-mode/playbooks/multi-phase-plan.md +11 -0
  151. package/upstream/poteto-mode/playbooks/opening-a-pr.md +9 -0
  152. package/upstream/poteto-mode/playbooks/pause-safely.md +10 -0
  153. package/upstream/poteto-mode/playbooks/perf-issue.md +25 -0
  154. package/upstream/poteto-mode/playbooks/prototype.md +14 -0
  155. package/upstream/poteto-mode/playbooks/refactoring.md +16 -0
  156. package/upstream/poteto-mode/playbooks/runtime-forensics.md +11 -0
  157. package/upstream/poteto-mode/playbooks/session-pickup.md +11 -0
  158. package/upstream/poteto-mode/playbooks/shipping.md +12 -0
  159. package/upstream/poteto-mode/playbooks/trace-forensics.md +14 -0
  160. package/upstream/poteto-mode/playbooks/visual-parity.md +11 -0
  161. package/upstream/poteto-mode/playbooks/worktree-cleanup.md +12 -0
  162. package/upstream/poteto-mode/references/bugbot-triage.md +142 -0
  163. package/upstream/poteto-mode/worker.md +11 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Niwa Labs contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,261 @@
1
- # Temporary Holding Version
1
+ # @niwa-labs/pstack
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Delivery playbooks run as niwa's built-in workflows: an entry that routes a request to the playbook it needs, one
4
+ workflow per upstream playbook, Benny for issue reports when he is enabled, and a suite that tries every new version
5
+ of them before the host runs it.
6
+
7
+ ## Composition
8
+
9
+ ```ts
10
+ import { addressingOf, pstack } from "@niwa-labs/pstack";
11
+
12
+ const base = defaultComposition({ home, harnesses, agents });
13
+ const beforeWorkflow = base.filter((part) => part.name !== "workflow");
14
+ const workflow = base.filter((part) => part.name === "workflow");
15
+ export default [
16
+ ...beforeWorkflow,
17
+ ...pstack({
18
+ bind: addressingOf(base),
19
+ forge: { servers: [{ host: "gitlab.example.com", url: "https://gitlab.example.com", token: secret("GITLAB_TOKEN") }] },
20
+ roles: {
21
+ lead: { harness: "claude" },
22
+ author: { harness: "codex", box: true },
23
+ reviewer: { harness: "claude" },
24
+ verifier: { harness: "pi", vendor: "minimax" },
25
+ judge: { harness: "pi", vendor: "glm" },
26
+ },
27
+ benny: {
28
+ repo: { host: "gitlab.example.com", path: "acme/billing", local: "/work/billing" },
29
+ // Your plugins that provide his three ports; see "Benny needs your plugins".
30
+ ports: [acmeTracker(), acmeChat(), acmeControl()],
31
+ },
32
+ }),
33
+ ...workflow,
34
+ ];
35
+ ```
36
+
37
+ `pstack()` installs forge, evidence, watch and plan, then the pstack plugin. The host provides the sessions and git
38
+ modules before it and the workflow module after it. `bind` is the binding of the host's sessions and agents modules
39
+ (`addressingOf`), so a session attests under one address for its whole life and an agent's session as the agent. Without
40
+ `benny`, none of the ports below is needed.
41
+
42
+ ## Roles
43
+
44
+ - `lead` frames, routes and judges, read-only.
45
+ - `author` writes code. It carries `box: true`. The workflow checks the real worktree path before opening its author
46
+ session through the SDK. It grants that worktree's project writes and adds only the configured forge hosts covered by
47
+ the run's grant.
48
+ - `reviewer` judges review threads.
49
+ - `verifier` re-runs the gates and shows the behaviour live. It must run on another harness than the author, and it
50
+ attests its verdicts under its own name.
51
+ - `judge` grades an evaluation. It is of another vendor than the candidates.
52
+
53
+ ## Playbooks
54
+
55
+ | Playbook | What it does |
56
+ |---|---|
57
+ | investigation | Answers a question about the code, with sources |
58
+ | trace-forensics, runtime-forensics | Hold hypotheses against a trace or runtime evidence, and name the cause one confirmed hypothesis leaves |
59
+ | bug-fix, feature, refactoring, perf-issue, visual-parity, authoring-a-skill | The lead frames the work, and an owner lane carries it to a verified pull request |
60
+ | hillclimb | One metric, one change at a time: kept when the measurement moved, reverted in full otherwise |
61
+ | autonomous-run | Iterates in a boxed worktree until a done predicate holds |
62
+ | prototype | Throwaway variants in scratch worktrees, and a recommendation |
63
+ | eval | Variants answer blind; a judge of another vendor grades them on a rubric they never see |
64
+ | multi-phase-plan | Writes the plan as a revision in niwa and asks the owner's go, attested node by node |
65
+ | autopilot-full | One owner lane per plan node, in parallel off trunk; the nodes land one at a time under the merge policy |
66
+ | autopilot-stack | The same, stacked where one node builds on another, without merging; it can carry a stack onto a new lower head |
67
+ | shipping | Lands a verified stack bottom up under the merge policy |
68
+ | opening-a-pr | Opens a ready pull request with the briefing upstream asks for |
69
+ | babysit | Conflicts, threads, then CI, in `check`, `threads-only` or `drive` mode; it never merges or rebases |
70
+ | pause-safely | A `wip:` commit and a resume note in the worktree the work is in |
71
+ | session-pickup | Where the work stands, from the plan and what was attested on it |
72
+ | worktree-cleanup | On a merge on the forge, removes the clean worktrees the merged head was built in |
73
+ | upstream-sync | Not a playbook: carries the map of the upstream snapshot to a new snapshot, below; gated like the playbooks |
74
+
75
+ The playbooks are upstream's text with niwa's wording where upstream names something a session does not have: Cursor's
76
+ skills and their principles, model slugs, `/loop`, `gh` and `origin`, `agent-transcripts/`. Scripts use `ask()` for
77
+ a typed one-shot answer and `session()` for a conversation with durable turns. Where a playbook shows the session tools
78
+ to a model, the model can open a helper with `session.start`, ask it with `session.ask` and close it with `session.end`.
79
+ The helper belongs to the same run and inherits its launch limits. Pull requests go through the forge module, workflows
80
+ and timers wake work, and `session.read` reads a session's history. Every such change
81
+ is an `adapted` entry of the map, or a `dropped` one with its reason, and `check` fails on any difference between a
82
+ text and upstream that the map does not say. Every session also gets the worker rules, which carry the goal, candor and
83
+ reply rules of upstream's operator skill. Benny's draft pull request is the one stated exception to the rule that a pull
84
+ request is opened ready.
85
+
86
+ A lane builds in a worktree off trunk with a boxed author. It opens the pull request only for the commit the author
87
+ made; a head on the forge that the author did not answer is a push the lane did not make. Verifiers that did not write
88
+ the code attest the `gates` and `live` verdicts on that head.
89
+
90
+ ## The merge policy
91
+
92
+ A pull request lands only when all of these hold at its current head:
93
+
94
+ - the owner's go covers each plan node it delivers. A go is bound by digest to the plan's revision, the node and the
95
+ change, and only the owner or a run may give one. A revised plan needs a new go.
96
+ - the `gates` and `live` verdicts passed, from someone other than the patch's author;
97
+ - the pipeline of the head is green;
98
+ - the merge result of the pair the forge would merge now is green and attested with that pair of commits.
99
+
100
+ An authoring lane records its native author session and registered worktree for the exact repository, pull request
101
+ and head. Standalone shipping reads that receipt. A missing or ambiguous receipt, or an explicit author that
102
+ differs from it, stops shipping until the head has verified provenance.
103
+
104
+ Shipping reads the target branch tip from the forge and checks the latest pipelines of this merge request against
105
+ both commit IDs. GitLab's merge endpoint can condition on the source commit only. On GitLab even a verified pair
106
+ remains open for a separate landing decision. A capable forge must enforce both commit IDs in the merge operation.
107
+
108
+ ## Candidates and the suite
109
+
110
+ Every built-in but the suite is offered gated, the upstream sync among them. A new version comes in as a candidate that the host neither installs nor
111
+ runs on events. Before any version was accepted, the candidate is shown and runs on nothing.
112
+
113
+ The suite (`pstack-suite`) is started by the owner on a fixture: a repository it may change, on a forge project it may
114
+ merge into. Niwa pins the offered set to the suite run, and each scenario starts its pinned version. When the suite exercises the
115
+ entry, Niwa uses the same set for the entry's child runs. An ordinary entry starts accepted playbooks. One scenario
116
+ hands its plan to the next. The sync's scenario seeds what it
117
+ needs itself, in worktrees of the fixture: a tiny upstream checkout, and a branch holding a tiny package folder whose map
118
+ covers its snapshot; upstream is reworded, and the scenario passes when the sync carries the map across and assembles
119
+ the texts. Only when every scenario passes
120
+ does it ask Niwa to promote the pinned candidates together. If another trial or a new offer changed the set, Niwa
121
+ leaves the accepted versions in place. On its own fixture's plans, the suite gives the go itself, as a run may.
122
+
123
+ ## Benny
124
+
125
+ With `benny`, the plugin offers the agent `benny` to the agents module, an action `benny.report`, and two gated
126
+ automations. Every report is triaged as data: the triage session searches the issue tracker for it and files an issue
127
+ for a clear, new bug, and the workflow posts its verdict once, in the thread the report came in on. A report triaged as
128
+ a bug is reproduced twice through the product control before any code is touched, and then fixed in a draft pull
129
+ request, which is linked to its issue; the owner is told once how it ended. Benny never merges or deploys.
130
+
131
+ `benny.report` is for the report channel's plugin: it hands a report in with `source`, the channel's own address of the
132
+ report, which comes back to `benny.channel.reply` with the verdict. A report with no `source` is triaged and
133
+ reproduced all the same, and nothing is posted.
134
+
135
+ ## Benny needs your plugins
136
+
137
+ Benny's tracker, chat and product are yours, not pstack's, so pstack ships three typed contracts and no
138
+ implementation of them. Each is a port: a plugin of yours offers it and registers the actions of its contract.
139
+
140
+ | Port | Offered at | Actions it provides |
141
+ |---|---|---|
142
+ | issue tracker | `BENNY_TRACKER` | `benny.tracker.find` (search by text, state and source), `benny.tracker.create` (title, body, source, labels), `benny.tracker.comment` (a recurrence note and a source on an existing issue), `benny.tracker.link-pr` (a pull request, by subject or url, on an issue) |
143
+ | report channel | `BENNY_CHANNEL` | `benny.channel.reply` (one reply in the thread of a report, by its `source`), `benny.channel.notify` (a status for the owner) |
144
+ | product control | `BENNY_CONTROL` | `benny.control.capabilities`, `bring-up`, `drive`, `inspect`, `screenshot`, `record`, `cleanup`: what upstream's control-adapter contract asks of the app it drives |
145
+
146
+ The channel also takes reports in: when one arrives, its plugin calls `benny.report` with the text, who wrote it and
147
+ its `source`. The control has no default for any project; the others have none either.
148
+
149
+ - The types are the action references `bennyTrackerFind`, `bennyChannelReply`, `bennyControlDrive` and the rest,
150
+ exported from `@niwa-labs/pstack` with their zod schemas. `action(ref, { ... })` builds the action from a
151
+ reference, so a provider and pstack check against one schema. The description of each reference says what the
152
+ action must and must not do: `inspect` is read-only, `drive` is a real user action and never an injected state,
153
+ `reply` posts in the report's thread and nowhere else, `create` makes an issue that links back to its source.
154
+ - A provider offers its port in its setup, with `api.offer(BENNY_TRACKER, { description })`. pstack reads the offers
155
+ when it is installed, so the providers are installed before it: list them in `benny.ports` and `pstack()` does so, or
156
+ install them yourself ahead of `...pstack()`. A host that lacks a port does not start: the error names each missing
157
+ port and says to install its provider before pstack.
158
+ - The triage session is shown `find`, `create` and `comment`; the reproduction session is shown the control actions.
159
+ The channel is never shown to a session: the workflow is the only poster.
160
+ - Install the providers only on a host that enables `benny`: without it pstack registers refusing stand-ins under the
161
+ same action names (the suite's grant has to name them), and a provider would clash with them.
162
+
163
+ A minimal tracker provider:
164
+
165
+ ```ts
166
+ import { action } from "@niwa-labs/core";
167
+ import { plugin } from "@niwa-labs/plugin";
168
+ import { BENNY_TRACKER, bennyTrackerComment, bennyTrackerCreate, bennyTrackerFind, bennyTrackerLinkPr } from "@niwa-labs/pstack";
169
+
170
+ // `acme` is your tracker's own client; the plugin only maps it onto the contract.
171
+ export function acmeTracker() {
172
+ return plugin("acme-tracker", (api) => {
173
+ api.offer(BENNY_TRACKER, { description: "Acme's issue tracker" });
174
+ api.action(action(bennyTrackerFind, { recovery: "repeat", effect: "read", world: "external", run: async (input) => ({ items: await acme.search(input.text, input.state, input.source) }) }));
175
+ api.action(action(bennyTrackerCreate, { recovery: "do-not-repeat", effect: "write", world: "external", run: async (input) => await acme.create(input) }));
176
+ api.action(action(bennyTrackerComment, { recovery: "do-not-repeat", effect: "write", world: "external", run: async (input) => (await acme.comment(input), { ok: true as const }) }));
177
+ api.action(action(bennyTrackerLinkPr, { recovery: "do-not-repeat", effect: "write", world: "external", run: async (input) => (await acme.linkPr(input), { ok: true as const }) }));
178
+ });
179
+ }
180
+ ```
181
+
182
+ The chat and the control are written the same way, with their own references. The tests of this package install
183
+ in-memory providers of the three ports (`test/ports.ts`) so the suite can run Benny; they are a stand-in, not a default.
184
+
185
+ ## The upstream snapshot and its map
186
+
187
+ `upstream/` keeps the pstack plugin of [cursor/plugins](https://github.com/cursor/plugins) (MIT) at the commit in
188
+ `upstream/SOURCE.json`: the operator's skill, the worker rules, the playbooks, the references they name, and the Benny
189
+ pack. `upstream/mapping.json` records what became of it in pstack, an entry to a line:
190
+
191
+ ```json
192
+ {"id":"bug-fix:03","upstream":{"commit":"<upstream commit>","file":"poteto-mode/playbooks/bug-fix.md","range":[476,892]},"ours":[{"commit":"<pstack commit>","file":"packages/pstack/src/workflows/lib/texts.ts","range":[120,610]}],"kind":"prompt"}
193
+ ```
194
+
195
+ - A range is `[start, end)` in characters (UTF-16 code units, as `String.slice` counts), and no text is stored. The
196
+ upstream side names a file of the snapshot at a commit of upstream. Our side names a file of this repository, from
197
+ its root, at the pstack commit the range was recorded at.
198
+ - `kind` says what became of the block. `prompt`: it goes into a prompt as upstream wrote it. `adapted`: our own text
199
+ replaces it in a prompt (the text is in `src/workflows/adapted.md`, and the entry links to its range). `code`: code
200
+ of ours implements it. `dropped`: we do not take it, and `note` says why.
201
+ - The upstream side is covered almost entirely: the files of the snapshot are cut into blocks, and what is not taken is
202
+ `dropped`, which counts as covered. The target is 95% of upstream's characters. The two upstream ranges of one file at
203
+ one commit never overlap. Our side is not covered: `ours` only links a block to the code or text that implements or
204
+ carries it, so several entries may link to the same range, and code of ours with no entry is fine.
205
+ - The texts the scripts import, `src/workflows/texts/*.json`, are assembled from the map: the `prompt` blocks of a file
206
+ verbatim from the snapshot, the `adapted` ones from our text, in upstream's order. `dropped` blocks are in no prompt.
207
+ A text is the files it is made of, each cut at its last non-blank character and followed by one blank line, and that
208
+ glue is the only thing in it that is not a block. They are not edited by hand: `assemble` writes them.
209
+ - Nothing is edited in a prompt outside the map. A text equals upstream except exactly where an `adapted` entry puts our
210
+ wording in and a `dropped` entry takes a range out, so a file that goes into a text has no `code` block: a block that
211
+ code of ours implements and a prompt leaves out is `dropped`, and its note says where the code is. `check` reads the
212
+ texts as they are on disk and holds each to the map (see below).
213
+
214
+ The tool is `bun packages/pstack/scripts/upstream-map.ts`:
215
+
216
+ | Command | What it does |
217
+ |---|---|
218
+ | `check` | Validates the map and reports the coverage of upstream's characters, per file and in total, with the uncovered ranges. For each entry, on each side, it follows the range from the commit it was recorded at to the current one (upstream: to the snapshot's commit; ours: to `HEAD`, or the working tree with `--worktree`) and says unchanged (it only shifted), touched (with the old and the new text of the range) or gone. It also lists upstream text that is new and uncovered, and the texts' own problems (an edit by hand, a block left out as `code`, upstream text no entry accounts for, a text with no file or a file with no text), which it counts apart from the map's because they follow the map and lag it until `assemble`. It draws no conclusion. `--out <file>` writes the report as JSON, `--summary` prints the numbers. |
219
+ | `advance` | Records the entries that are unchanged at the current commits and positions. |
220
+ | `accept <id>...` | Records the named entries at the positions their ranges were carried to. |
221
+ | `assemble` | Writes the texts from the map; `--check` only compares. |
222
+ | `refresh <checkout> [<commit>]` | Takes a new snapshot of an upstream checkout at a commit of it, read through git: the checkout's working tree is not read and it is not written. The mapping stays. |
223
+
224
+ Ranges are carried by comparing the two texts by lines and then by the characters the changed lines share at their
225
+ start and end. `--upstream <checkout>` is needed only while the map has ranges at an upstream commit other than the
226
+ snapshot's.
227
+
228
+ ### Updating upstream
229
+
230
+ Start `pstack-upstream-sync` with the path of an upstream checkout (and a commit of it, if not its HEAD, and the
231
+ `package` folder of the repository, `packages/pstack` by default). It is gated like the playbooks: a new version of it
232
+ comes in as a candidate and the suite tries it first. In a worktree of its own it takes the snapshot and commits it, then
233
+ loops: the tool measures the map, and an author boxed to the worktree works on what the report shows (maps uncovered
234
+ text, follows touched and gone entries into our code and texts, drops what is not taken with the reason). The author
235
+ edits files and answers the ids of the entries that are settled where the report carried them; the workflow commits
236
+ what it edited, records those entries and the unchanged ones, and measures again. It stops when the coverage is at least
237
+ 95% (`min`) and no entry is touched or gone, or after `rounds` rounds, and says what is left. What would change what a
238
+ prompt or a workflow does is not the author's to decide: it goes to the owner as a question, and its answer is carried
239
+ out in a last round. The texts are then assembled from the map and committed, and the map is measured once more: the
240
+ texts lag the map until they are assembled, so they are held to it only then, and the run is `synced` only when the map
241
+ and the texts have no problem.
242
+
243
+ The tool and git run on the host, in the pstack plugin's actions (`pstack.upstream.refresh`, `measure`, `record`,
244
+ `assemble`, `commit` and `state`), never in `proc.run`: a real box reads only its own directory, so it can read neither
245
+ the upstream checkout nor the repository a worktree belongs to, and the boxed author cannot run git either. Each action
246
+ works only on one of niwa's worktrees, reads the checkout through git and never writes it, and writes inside the
247
+ worktree.
248
+
249
+ By hand, the same: `refresh`, then `check`, settle what it shows, `accept` or edit the entries, `advance`, `assemble`.
250
+ The tool reads and writes the package folder it is installed in.
251
+
252
+ ## What niwa does not give yet
253
+
254
+ - A script's `uses` holds call rules only, so a run cannot hold the write and network rules of a box. The author's box
255
+ is a right of the pstack plugin.
256
+ - The git module's actions carry no target, so the entry's `git.*@{repo.local}` reaches none of them. The entry names
257
+ the worktree actions it calls untargeted.
258
+ - A real `proc.run` box reads only its own directory, and a niwa worktree's `.git` leads into the main repository, outside
259
+ it: git does not run in a worktree there at all (`rev-parse`, `status`, `show` and `commit` all fail as "not a git
260
+ repository"). The lanes read git through `proc.run`, so they work only where the box is not applied; the upstream sync
261
+ does its tool and git work on the host instead.
package/package.json CHANGED
@@ -1,6 +1,30 @@
1
1
  {
2
2
  "name": "@niwa-labs/pstack",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.0.0",
4
+ "license": "MIT",
5
+ "type": "module",
6
+ "scripts": {
7
+ "upstream-map": "bun scripts/upstream-map.ts"
8
+ },
9
+ "exports": {
10
+ ".": "./src/index.ts"
11
+ },
12
+ "dependencies": {
13
+ "@niwa-labs/core": "*",
14
+ "@niwa-labs/evidence": "*",
15
+ "@niwa-labs/flow": "*",
16
+ "@niwa-labs/flow-code": "*",
17
+ "@niwa-labs/flow-eval": "*",
18
+ "@niwa-labs/forge": "*",
19
+ "@niwa-labs/plan": "*",
20
+ "@niwa-labs/plugin": "*",
21
+ "@niwa-labs/script": "*",
22
+ "@niwa-labs/watch": "*",
23
+ "@niwa-labs/workflow": "*",
24
+ "zod": "^4.6.7"
25
+ },
26
+ "devDependencies": {
27
+ "@niwa-labs/sessions": "*",
28
+ "@niwa-labs/testing": "*"
29
+ }
30
+ }
@@ -0,0 +1,90 @@
1
+ // Measure the mapping of the upstream snapshot: `bun packages/pstack/scripts/upstream-map.ts <command>`.
2
+ //
3
+ // check [--upstream <checkout>] [--head <rev> | --worktree] [--map <file>] [--out <file>] [--summary]
4
+ // validate the mapping, report coverage of the upstream text, and what became of each entry's ranges since
5
+ // the commits they were recorded at. Draws no conclusion. `--out` writes the whole report as JSON;
6
+ // `--summary` prints one line of JSON numbers instead of the text. A map that cannot be read at all is one
7
+ // problem, said in the same form. It also holds the texts the scripts import to the map, counted apart (`textProblems`):
8
+ // the exit is 1 whenever the map or a text has a problem.
9
+ // advance [--upstream <checkout>] [--head <rev>] record the unchanged entries at the current commits
10
+ // accept <id>... [--upstream <checkout>] [--head <rev>] record the named entries at the carried positions
11
+ // assemble [--check] write the texts the scripts import from the mapping; with `--check`, only compare them
12
+ // refresh <checkout> [<commit>] take a new snapshot of an upstream checkout, at a commit of it
13
+ //
14
+ // `--upstream` is needed only when the mapping has ranges at an upstream commit other than the snapshot's.
15
+
16
+ import { writeFileSync } from "node:fs";
17
+ import { resolve } from "node:path";
18
+
19
+ import { Git, WORKTREE, differingTexts, formatReport, openMap, recordMap, summaryOf, unreadable, writeAssembled } from "../src/mapping/index.ts";
20
+ import type { ToolContext } from "../src/mapping/index.ts";
21
+ import { PACKAGE_DIR, PACKAGE_PATHS, refreshUpstream } from "../src/upstream.ts";
22
+
23
+ const [command, ...rest] = process.argv.slice(2);
24
+
25
+ /** The value of a flag, and the arguments that are not flags. */
26
+ function parse(args: readonly string[], valued: readonly string[]): { flags: Map<string, string | true>; words: string[] } {
27
+ const flags = new Map<string, string | true>();
28
+ const words: string[] = [];
29
+ for (let i = 0; i < args.length; i += 1) {
30
+ const arg = args[i] as string;
31
+ if (!arg.startsWith("--")) words.push(arg);
32
+ else if (valued.includes(arg)) flags.set(arg, args[(i += 1)] ?? "");
33
+ else flags.set(arg, true);
34
+ }
35
+ return { flags, words };
36
+ }
37
+
38
+ const usage = (): never => {
39
+ console.error("usage: upstream-map check|advance|accept|assemble|refresh (see the head of this file)");
40
+ process.exit(2);
41
+ };
42
+
43
+ const { flags, words } = parse(rest, ["--upstream", "--head", "--out", "--map"]);
44
+ const text = (flag: string): string | undefined => {
45
+ const value = flags.get(flag);
46
+ return typeof value === "string" ? value : undefined;
47
+ };
48
+ const context = (): ToolContext => ({
49
+ paths: PACKAGE_PATHS,
50
+ root: new Git(PACKAGE_DIR).out(["rev-parse", "--show-toplevel"]).trim(),
51
+ ...(text("--upstream") === undefined ? {} : { checkout: text("--upstream") as string }),
52
+ head: flags.has("--worktree") ? WORKTREE : (text("--head") ?? "HEAD"),
53
+ ...(text("--map") === undefined ? {} : { map: text("--map") as string }),
54
+ });
55
+
56
+ if (command === "check") {
57
+ const out = text("--out");
58
+ let opened: ReturnType<typeof openMap>;
59
+ try {
60
+ opened = openMap(context());
61
+ } catch (error) {
62
+ // A map that cannot be read at all (bad JSON, a schema error, a commit that is not there) is a problem of the
63
+ // map, said as one: whoever reads the numbers gets a line to act on, not a crash.
64
+ const said = unreadable(error);
65
+ if (out !== undefined) writeFileSync(resolve(out), `${JSON.stringify({ error: said.error }, null, 2)}\n`);
66
+ console.log(flags.has("--summary") ? JSON.stringify(said) : `PROBLEMS 1\n the map could not be read: ${said.error}`);
67
+ process.exit(1);
68
+ }
69
+ const { report } = opened;
70
+ if (out !== undefined) writeFileSync(resolve(out), `${JSON.stringify(report, null, 2)}\n`);
71
+ console.log(flags.has("--summary") ? JSON.stringify(summaryOf(report)) : formatReport(report));
72
+ process.exit(report.problems.length === 0 && report.texts.length === 0 ? 0 : 1);
73
+ } else if (command === "advance" || command === "accept") {
74
+ const changed = recordMap(context(), command === "advance" ? "unchanged" : words);
75
+ console.log(`${command === "advance" ? "advanced" : "accepted"}: ${String(changed)} entries recorded`);
76
+ } else if (command === "assemble") {
77
+ if (flags.has("--check")) {
78
+ const wrong = differingTexts(context());
79
+ if (wrong.length > 0) {
80
+ console.error(`these texts differ from the mapping: ${wrong.join(", ")}`);
81
+ process.exit(1);
82
+ }
83
+ console.log("the texts match the mapping");
84
+ } else console.log(`${String(writeAssembled(context()))} texts written`);
85
+ } else if (command === "refresh") {
86
+ const [checkout, commit] = words;
87
+ if (checkout === undefined) usage();
88
+ const source = refreshUpstream(resolve(checkout as string), commit === undefined ? {} : { commit });
89
+ console.log(`snapshot taken at ${source.commit}`);
90
+ } else usage();
package/src/author.ts ADDED
@@ -0,0 +1,57 @@
1
+ /**
2
+ * The author's box keeps its project writes in a worktree of niwa. The plugin checks the place and chooses the
3
+ * forge hosts its caller's grant covers.
4
+ */
5
+
6
+ import { existsSync, realpathSync } from "node:fs";
7
+ import { join, sep } from "node:path";
8
+
9
+ import { CatchableError } from "@niwa-labs/core";
10
+
11
+ import type { Roles } from "./roles.ts";
12
+
13
+ /** Why the author was not started. */
14
+ export type AuthorRefusalCode = "no-box" | "no-place" | "not-a-worktree";
15
+
16
+ /** The author was not started: a refusal the run may catch. */
17
+ export class AuthorRefusal extends CatchableError {
18
+ override name = "AuthorRefusal";
19
+ override readonly code: AuthorRefusalCode;
20
+
21
+ constructor(code: AuthorRefusalCode, message: string) {
22
+ super(message);
23
+ this.code = code;
24
+ }
25
+ }
26
+
27
+ /** The folder niwa's git module keeps its worktrees in. */
28
+ export const worktreesOf = (home: string): string => join(realpathSync(home), "worktrees");
29
+
30
+ /**
31
+ * The real path of a place a role works in, checked before anything is read or written there: it exists and is one of
32
+ * niwa's worktrees under `worktrees` (its real path, so a link cannot lead out). `who` names the role in the refusal.
33
+ */
34
+ export function worktreePlace(who: string, place: string, worktrees: string): string {
35
+ if (place.trim() === "" || !existsSync(place)) throw new AuthorRefusal("no-place", `${who} has no place to work in: ${JSON.stringify(place)} is not there`);
36
+ const real = realpathSync(place);
37
+ const root = existsSync(worktrees) ? realpathSync(worktrees) : worktrees;
38
+ if (!real.startsWith(root + sep) || real.slice(root.length + 1).includes(sep)) {
39
+ throw new AuthorRefusal("not-a-worktree", `${who}'s place ${real} is not one of niwa's worktrees under ${root}`);
40
+ }
41
+ return real;
42
+ }
43
+
44
+ /**
45
+ * The launch of the author's session: its project is the worktree and its box also reaches the given forges.
46
+ * Refused when the role carries no box or the place is outside `worktrees`.
47
+ */
48
+ export function authorLaunch(
49
+ author: Roles["author"],
50
+ place: string,
51
+ worktrees: string,
52
+ forges: readonly string[],
53
+ ): { place: string; box: { allow: Array<"project" | { net: string }> } } {
54
+ if ((author as { box?: unknown }).box !== true) throw new AuthorRefusal("no-box", "the author role carries no box, and an author writes only in a box");
55
+ const real = worktreePlace("the author", place, worktrees);
56
+ return { place: real, box: { allow: ["project", ...forges.map((net) => ({ net }))] } };
57
+ }
package/src/binding.ts ADDED
@@ -0,0 +1,32 @@
1
+ /**
2
+ * Who an attestation is from. The merge policy refuses a verdict by the author of the patch, so the author must have
3
+ * one address for the life of its session: the principal of a session's token changes when the session is launched
4
+ * again under a new one, and an exclusion by principal would let the author's relaunched session count as someone
5
+ * else. The sessions module knows which session a token's mark names, and the agents module which agent a session
6
+ * works for; their bindings give that address, and evidence is given the result.
7
+ */
8
+
9
+ import { principalBinding } from "@niwa-labs/evidence";
10
+ import type { CallerBinding, Plugin } from "@niwa-labs/plugin";
11
+
12
+ /** A plugin that hands out a binding of its callers, as the sessions and agents modules do. */
13
+ export type Binding = Plugin & { bind(fallback?: CallerBinding): CallerBinding };
14
+
15
+ function bindingPlugin(plugins: readonly Plugin[], name: string): Binding | undefined {
16
+ const found = plugins.find((one) => String(one.name) === name);
17
+ return found !== undefined && typeof (found as Partial<Binding>).bind === "function" ? (found as Binding) : undefined;
18
+ }
19
+
20
+ /**
21
+ * The binding evidence attests with on a host of these plugins: a session the agents module started for an agent
22
+ * attests as the agent, another session as itself (`session` with its harness and its own id), and every other caller
23
+ * as the evidence module would bind it, the owner as the owner and a run as `run:<id>`. A host with no sessions module
24
+ * is refused: its sessions could not be told apart across a relaunch.
25
+ */
26
+ export function addressingOf(plugins: readonly Plugin[]): CallerBinding {
27
+ const sessions = bindingPlugin(plugins, "sessions");
28
+ if (sessions === undefined) throw new TypeError("pstack: the host has no sessions module to address the authors of verdicts by; install it before pstack");
29
+ const agents = bindingPlugin(plugins, "agents");
30
+ const bySession = sessions.bind(principalBinding);
31
+ return agents === undefined ? bySession : agents.bind(bySession);
32
+ }
package/src/catalog.ts ADDED
@@ -0,0 +1,86 @@
1
+ /**
2
+ * The built-in workflows pstack ships: the entry, one script per upstream playbook, the upstream sync, and the suite
3
+ * that tries a new set of them before the host runs it.
4
+ *
5
+ * Every script but the suite is gated: a new version of it comes in as a candidate, and the host runs it only once
6
+ * the suite has run its scenarios on the candidates and promoted the set. The suite itself is not gated, for it is
7
+ * what promotes.
8
+ */
9
+
10
+ import { fileURLToPath } from "node:url";
11
+
12
+ /** One built-in, as pstack offers it to the workflow module. */
13
+ export interface Builtin {
14
+ /** Its name among pstack's built-ins: the playbook's name for a playbook. */
15
+ readonly name: string;
16
+ /** A few words on one line: what it is registered under. */
17
+ readonly description: string;
18
+ /** The record types its `on` names, other than script records. */
19
+ readonly triggers?: readonly string[];
20
+ }
21
+
22
+ /** The folder of the scripts. */
23
+ const WORKFLOWS = new URL("./workflows/", import.meta.url);
24
+
25
+ /** The script of a built-in. */
26
+ export const scriptOf = (name: string): string => fileURLToPath(new URL(`${name}.ts`, WORKFLOWS));
27
+
28
+ /** The name of the entry. */
29
+ export const ENTRY = "entry";
30
+
31
+ /** The name of the suite. */
32
+ export const SUITE = "suite";
33
+
34
+ /** The playbooks, by the name of their upstream file. */
35
+ export const PLAYBOOKS: readonly Builtin[] = [
36
+ { name: "authoring-a-skill", description: "Write or change a skill and carry it to a pull request" },
37
+ { name: "autonomous-run", description: "Drive a change until its done predicate holds" },
38
+ { name: "autopilot-full", description: "Carry a plan with the go to merged pull requests" },
39
+ { name: "autopilot-stack", description: "Carry a plan to verified, stacked pull requests" },
40
+ { name: "babysit", description: "Clear one pull request's conflicts, threads and CI" },
41
+ { name: "bug-fix", description: "Find a bug's cause and carry its fix to a pull request" },
42
+ { name: "eval", description: "Compare variants blind on a rubric they never see" },
43
+ { name: "feature", description: "Design a feature and carry it to a verified pull request" },
44
+ { name: "hillclimb", description: "Improve one metric an attempt at a time" },
45
+ { name: "investigation", description: "Answer a question about the code with cited sources" },
46
+ { name: "multi-phase-plan", description: "Write a plan of pull requests and ask the owner's go" },
47
+ { name: "opening-a-pr", description: "Open a ready pull request for a published branch" },
48
+ { name: "pause-safely", description: "Stop cleanly with a checkpoint to resume from" },
49
+ { name: "perf-issue", description: "Measure a slow path, fix it, and measure the fix" },
50
+ { name: "prototype", description: "Settle a design decision with throwaway variants" },
51
+ { name: "refactoring", description: "Reshape code behind a pinned contract" },
52
+ { name: "runtime-forensics", description: "Find the cause of a symptom from the program running" },
53
+ { name: "session-pickup", description: "Pick up work from the trail niwa keeps of it" },
54
+ { name: "shipping", description: "Land a verified stack bottom up under the merge policy" },
55
+ { name: "trace-forensics", description: "Read a trace for the cause of a symptom" },
56
+ { name: "visual-parity", description: "Match a surface to its reference and verify it live" },
57
+ { name: "worktree-cleanup", description: "Remove the worktrees a merged pull request was built in", triggers: ["forge.pr.merged"] },
58
+ ];
59
+
60
+ /** Benny's two automations, offered when Benny is enabled: triage every report, reproduce and fix a confirmed bug. */
61
+ export const BENNY: readonly Builtin[] = [
62
+ { name: "benny-triage", description: "Triage an issue report handed to Benny", triggers: ["benny.reported"] },
63
+ { name: "benny-reproduce", description: "Reproduce a confirmed bug and fix it in a draft request" },
64
+ ];
65
+
66
+ /** The name of the upstream sync. */
67
+ export const SYNC = "upstream-sync";
68
+
69
+ /**
70
+ * The upstream sync: the owner starts it on a checkout of upstream, and it leaves commits on a branch. It is gated like
71
+ * the playbooks: the tool it runs and the author it prompts decide what a prompt becomes, so a new version of it comes
72
+ * in as a candidate and the suite tries it before the host runs it.
73
+ */
74
+ export const SYNC_BUILTIN: Builtin = { name: SYNC, description: "Carry the upstream map to a new snapshot of upstream" };
75
+
76
+ /** The built-ins that come in as candidates: the entry, the playbooks and the upstream sync. */
77
+ export const GATED: readonly Builtin[] = [{ name: ENTRY, description: "Pick the playbook a request needs and run it" }, ...PLAYBOOKS, SYNC_BUILTIN];
78
+
79
+ /** The suite: it is what promotes, so it is not gated. */
80
+ export const SUITE_BUILTIN: Builtin = { name: SUITE, description: "Run the scenarios on candidate playbooks and promote them" };
81
+
82
+ /** The built-ins that are not gated. */
83
+ export const UNGATED: readonly Builtin[] = [SUITE_BUILTIN];
84
+
85
+ /** The gated built-ins a pstack plugin offers: Benny's too when he is enabled. */
86
+ export const gatedOf = (benny: boolean): readonly Builtin[] => (benny ? [...GATED, ...BENNY] : GATED);