@sjawhar/pi-envoy 16.30.0 → 16.31.1

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/dist/envoy.js CHANGED
@@ -42650,7 +42650,7 @@ var import_nats2 = __toESM(require_mod4(), 1);
42650
42650
 
42651
42651
  // package.json
42652
42652
  var name = "@sjawhar/pi-envoy";
42653
- var version2 = "16.30.0";
42653
+ var version2 = "16.31.1";
42654
42654
  var package_default = {
42655
42655
  name,
42656
42656
  version: version2,
@@ -42680,7 +42680,7 @@ var package_default = {
42680
42680
  prepack: "../../scripts/pi-plugin-prepack.sh",
42681
42681
  postpack: "rm -rf dist/skills",
42682
42682
  typecheck: "bunx tsc --noEmit",
42683
- test: "bun test --path-ignore-patterns=extensions/card-delivery-omp.test.ts && bun test ./extensions/card-delivery-omp.test.ts",
42683
+ test: "bun test",
42684
42684
  lint: "bunx biome lint extensions/ src/"
42685
42685
  },
42686
42686
  devDependencies: {
@@ -42688,6 +42688,7 @@ var package_default = {
42688
42688
  "@legion/contracts": "workspace:*",
42689
42689
  "@legion/envoy-client": "workspace:*",
42690
42690
  "@legion/pi-shared": "workspace:*",
42691
+ "@legion/test-fixtures": "workspace:*",
42691
42692
  "@oh-my-pi/pi-tui": "^18.6.0",
42692
42693
  "@oh-my-pi/pi-utils": "^18.6.0",
42693
42694
  "@toon-format/toon": "^4.1.1",
@@ -47967,6 +47968,14 @@ function liveSessionSettings(live) {
47967
47968
  };
47968
47969
  }
47969
47970
  var codec2 = import_nats2.StringCodec();
47971
+ var NATS_CONNECT = Symbol.for("legion.pi-envoy.nats-connect");
47972
+ var natsConnectStore = globalThis;
47973
+ function setNatsConnectForTests(dial) {
47974
+ natsConnectStore[NATS_CONNECT] = dial;
47975
+ }
47976
+ function resetNatsConnectForTests() {
47977
+ delete natsConnectStore[NATS_CONNECT];
47978
+ }
47970
47979
  var NATS_RETRY_INTERVAL_MS = 15000;
47971
47980
  var DELIVERY_PICTURES_TIMEOUT_MS = 20000;
47972
47981
  var WHOLE_BODY_TIMEOUT_MS = 1e4;
@@ -48348,7 +48357,7 @@ function envoyExtension(pi) {
48348
48357
  };
48349
48358
  const dialNats = async () => {
48350
48359
  const { natsUrls, natsSeed } = requireInbound();
48351
- return import_nats2.connect(natsConnectionOptions({
48360
+ return (natsConnectStore[NATS_CONNECT] ?? import_nats2.connect)(natsConnectionOptions({
48352
48361
  servers: natsUrls,
48353
48362
  name: `omp-${sessionID || "unknown"}`,
48354
48363
  seed: natsSeed
@@ -50396,5 +50405,7 @@ function topicsFor(parameters, fallback = []) {
50396
50405
  return expandSubscriptionTopics(value);
50397
50406
  }
50398
50407
  export {
50399
- envoyExtension as default
50408
+ envoyExtension as default,
50409
+ resetNatsConnectForTests,
50410
+ setNatsConnectForTests
50400
50411
  };
@@ -15,12 +15,17 @@ Your session never holds the value, and nothing of it reaches your transcript.
15
15
  agent-secrets NAME... [--reason TEXT] [--wait DURATION] [--ttl DURATION] -- <command> [args...]
16
16
  ```
17
17
 
18
- - Each granted secret reaches `<command>`'s environment under its own name. Nothing runs unless
18
+ - Each granted secret reaches `<command>`'s environment under its own name, as the value or, for
19
+ a secret behind the airlock, as a placeholder standing for it (below). Nothing runs unless
19
20
  every name is granted: a denial of one name denies the whole request, so the command never starts
20
21
  with some of its secrets missing (`cmdExec`, `packages/envoy/cmd/agent-secrets/main.go`).
21
22
  - `--reason` is what a person reads if the request waits for a decision. Write one.
22
23
  - `agent-secrets --help` holds the rest: the flags that narrow a GitHub App token
23
24
  (`--github-owner`, `--github-repo`, `--github-read-only`), and how long a grant lasts.
25
+ - A narrowing and the airlock do not go together. Ask for a narrowing in a run whose grant holds
26
+ a secret behind the airlock (below) and the broker refuses the release, naming that secret;
27
+ nothing runs. Ask for the GitHub App secret in a run of its own, with no airlocked name beside
28
+ it.
24
29
 
25
30
  ## The command reads the value, your shell does not
26
31
 
@@ -34,8 +39,9 @@ agent-secrets LEGION_SLACK_BOT_TOKEN -- \
34
39
 
35
40
  Your own shell expands `$LEGION_SLACK_BOT_TOKEN` before `agent-secrets` runs, and in your shell that
36
41
  name is empty. Measured on 2026-11-04 from a Legion issue pod: Slack answered
37
- `{"ok":false,"error":"not_authed"}`. The value exists only in the environment of the command the
38
- client starts, so that command must read it itself. Put the command in single quotes, inside
42
+ `{"ok":false,"error":"not_authed"}`. What the client hands over — the value, or the placeholder of
43
+ a secret behind the airlock — exists only in the environment of the command the client starts, so
44
+ that command must read it itself. Put the command in single quotes, inside
39
45
  `sh -c`, where the quotes keep the expansion for the child:
40
46
 
41
47
  ```sh
@@ -50,13 +56,58 @@ The repository uses the same form for a GitHub App token in `docs/deployment.md`
50
56
  agent-secrets LEGION_IMPLEMENT_APP --reason=… -- sh -c 'printf %s "$LEGION_IMPLEMENT_APP"'
51
57
  ```
52
58
 
59
+ ## A secret behind the airlock
60
+
61
+ Your deployment can hold a secret's value back and give your command a stand-in. You see it in the
62
+ command's environment: the name holds `agent-secrets-placeholder-` and 32 letters and digits, not
63
+ the value. A length or a prefix probe there reads the placeholder, and proves nothing about the
64
+ real value.
65
+
66
+ A call to that secret's service goes through the broker's own proxy, which `agent-secrets` names
67
+ in the run's environment (`HTTPS_PROXY`, a `NO_PROXY` that keeps the secret's hosts on that proxy,
68
+ and a trust bundle). The proxy swaps the placeholder for the real value in the headers the
69
+ secret's rule names. Three things follow for the command you write:
70
+
71
+ - Make every call inside the `agent-secrets NAME -- command` run, with the environment that run
72
+ gives it. A tool that keeps a token in a cache file across runs, or that makes its calls outside
73
+ the run, stops working. Ask for the grant in the run that spends it.
74
+
75
+ - Pass no value you obtained some other way. The proxy refuses a request whose headers already
76
+ carry the real value.
77
+
78
+ - The placeholder is that one grant's, and works only while the grant lives.
79
+
80
+ A refusal comes from the proxy, not from the service:
81
+
82
+ - An HTTP error naming the rule that refused it: a TLS name or `Host` that is not the host the
83
+ command asked for, a method or a path outside the entry's `allow`, a path with a `.` or `..`
84
+ segment, an `X-HTTP-Method-Override`, `X-HTTP-Method` or `X-Method-Override` header where the
85
+ entry lists methods, plain `http://` to a host an entry binds, or a private address.
86
+
87
+ - `407` once the grant ends, on every call to any host. A WebSocket open at that moment is
88
+ closed with the grant. A tunnel to a host no entry binds carries no value, so it runs to its
89
+ idle limit instead.
90
+
91
+ - `503` when the broker could not read the grant at all. The grant has not ended and the call
92
+ can be made again.
93
+
94
+ A retry fixes neither of the first two, and neither does another name. A `407` needs a new
95
+ grant. A rule's refusal needs a change to the rules file in the deployment's own repository,
96
+ which a person reviews. Report the refusal as you report a service out of reach: the command you
97
+ ran and the output you saw.
98
+
99
+ Two calls are not refused by the proxy. A call to a host no entry binds goes out unread, and a
100
+ placeholder in a header the entry does not name goes out as it is, so the service refuses the
101
+ placeholder and its own error is what you see.
102
+
53
103
  ## The value never reaches your transcript
54
104
 
55
105
  Your transcript keeps everything a command prints.
56
106
 
57
107
  - Never echo or print the value, and never run `curl -v`, `curl --trace` or a shell with `set -x`
58
108
  around it: each of those writes the header, and so the value, to your output.
59
- - Check a value's shape by its length and its prefix alone:
109
+ - Check a value's shape by its length and its prefix alone. For a secret behind the airlock, that
110
+ reads the placeholder's shape and not the value's:
60
111
 
61
112
  ```sh
62
113
  agent-secrets NAME -- sh -c 'echo "${#NAME}"; case "$NAME" in ghp_*) echo prefix-ok;; *) echo prefix-no;; esac'
@@ -36,7 +36,8 @@ For each spec, ask, comment and message:
36
36
 
37
37
  - Write in `skill://asd-ste100`'s strict mode.
38
38
  - Write about the current design, never the person or how people reached it, and never quote or upload their words.
39
- - Link each source where the person wrote it, each id whole. With no link, state the design.
39
+ - Link each source where the person wrote it. With no link, state the design.
40
+ - Treat a person's stated preference or past answer as evidence of their taste, never as a ruling that settles the question: an answer given once is not a standing rule. A commit attributed to a person is not their decision, because agents commit the work.
40
41
  - In a spec, cite code by file and symbol, never a line number: it goes stale at the next edit.
41
42
  - A sentence citing a gate passing (test, review, check) also says what the pass does not show: "Tests pass: a wrong verdict, not a missing one."
42
43
  - Keep only text a reader needs to understand, decide, build or check, and say what each issue you name does for them (`skill://plain-words`).
@@ -46,7 +47,6 @@ For each spec, ask, comment and message:
46
47
 
47
48
  - Name the concrete case and its numbers, then the choice in those terms, never "Which option?".
48
49
  - A choice inside what the person asked for, one their messages favour, routine cleanup, sequencing, naming, a choice between equivalent options, and a fix you can make are yours.
49
- - Ask only for the person's authority, taste or risk appetite, when options differ on what they care about.
50
50
  - Ask with an [ask block](skill://dispatch/SKILL.md#asks-and-ask-blocks): 2 to 4 options, answerable on a phone, and name nothing the reader cannot see from it ("the message above").
51
51
  - For each technical term you coined in this session, count by exact match the files holding it, in the repositories the work touches and in Dispatch; a single-digit count means expand the term or drop it, because a coinage reads as familiar to you. A count misses a coinage of common words, so read the draft for those too.
52
52
  - Measure each claim the ask rests on, its premise and each option's precondition. Where you cannot, mark the claim unverified and name the missing measurement; call an option unavailable only where a precondition demonstrably fails. A premise can go stale within the hour; no unmeasured number goes in one.
@@ -70,7 +70,7 @@ Choices—answered asks included—earn `decisions.md` `##` sections only if a d
70
70
 
71
71
  ## Old specs
72
72
 
73
- Rewrite a spec outside the outline whole in one version, its ask blocks moved with `doc-edit`'s `move`; restate each retelling, quotation or unlinked attribution as design, or cut it.
73
+ Rewrite a spec outside the outline whole in one version, its ask blocks moved with `doc-edit`'s `move`.
74
74
 
75
75
  ## Approval
76
76
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sjawhar/pi-envoy",
3
- "version": "16.30.0",
3
+ "version": "16.31.1",
4
4
  "license": "Apache-2.0",
5
5
  "type": "module",
6
6
  "omp": {
@@ -27,7 +27,7 @@
27
27
  "prepack": "../../scripts/pi-plugin-prepack.sh",
28
28
  "postpack": "rm -rf dist/skills",
29
29
  "typecheck": "bunx tsc --noEmit",
30
- "test": "bun test --path-ignore-patterns=extensions/card-delivery-omp.test.ts && bun test ./extensions/card-delivery-omp.test.ts",
30
+ "test": "bun test",
31
31
  "lint": "bunx biome lint extensions/ src/"
32
32
  },
33
33
  "devDependencies": {
@@ -35,6 +35,7 @@
35
35
  "@legion/contracts": "0.10.0",
36
36
  "@legion/envoy-client": "0.1.0",
37
37
  "@legion/pi-shared": "0.1.0",
38
+ "@legion/test-fixtures": "0.1.0",
38
39
  "@oh-my-pi/pi-tui": "^18.6.0",
39
40
  "@oh-my-pi/pi-utils": "^18.6.0",
40
41
  "@toon-format/toon": "^4.1.1",