@sjawhar/pi-envoy 16.3.1 → 16.4.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.
package/README.md CHANGED
@@ -169,8 +169,9 @@ pane that still loads the pre-split package beside the new ones.
169
169
 
170
170
  The tarball is self-contained: it ships `dist/envoy.js` — bundling every dependency except the OMP
171
171
  host packages (`@legion/pi-shared`, `@legion/contracts` and `@legion/envoy-client` are inlined) —
172
- `dist/THIRD_PARTY_NOTICES`, and the five skills every session with Dispatch reads, `asd-ste100`,
173
- `dispatch`, `dispatch-first`, `dispatch-writing-specs` and `envoy`, staged from the repository's `skills/` at
172
+ `dist/THIRD_PARTY_NOTICES`, and the eight skills every session with Dispatch reads,
173
+ `agent-secrets`, `asd-ste100`, `dispatch`, `dispatch-first`, `dispatch-writing-specs`, `envoy`,
174
+ `outside-message` and `plain-words`, staged from the repository's `skills/` at
174
175
  `dist/skills`. The manifest declares `omp.skills: ["dist/skills"]` alongside `omp.extensions`:
175
176
  OMP's own plugin discovery only reads `skill://`-resolvable skills from `<plugin root>/skills` or
176
177
  from directories a manifest's `omp.skills` array names, and this package ships skills at
package/dist/envoy.js CHANGED
@@ -38540,7 +38540,7 @@ var import_nats2 = __toESM(require_mod4(), 1);
38540
38540
 
38541
38541
  // package.json
38542
38542
  var name = "@sjawhar/pi-envoy";
38543
- var version2 = "16.3.1";
38543
+ var version2 = "16.4.0";
38544
38544
  var package_default = {
38545
38545
  name,
38546
38546
  version: version2,
@@ -0,0 +1,180 @@
1
+ ---
2
+ name: agent-secrets
3
+ description: Use before a command that needs a token, a key or a password; before you say that a service or an API is out of reach; and when an instruction names `agent-secrets`.
4
+ ---
5
+
6
+ # agent-secrets
7
+
8
+ The secrets broker holds the credentials this deployment gives its agents. `agent-secrets` is its
9
+ client. It asks the broker for a secret and gives it to one command, in that command's environment.
10
+ Your session never holds the value, and nothing of it reaches your transcript.
11
+
12
+ ## The one form
13
+
14
+ ```sh
15
+ agent-secrets NAME... [--reason TEXT] [--wait DURATION] [--ttl DURATION] -- <command> [args...]
16
+ ```
17
+
18
+ - Each granted secret reaches `<command>`'s environment under its own name. Nothing runs unless
19
+ every name is granted: a denial of one name denies the whole request, so the command never starts
20
+ with some of its secrets missing (`cmdExec`, `packages/envoy/cmd/agent-secrets/main.go`).
21
+ - `--reason` is what a person reads if the request waits for a decision. Write one.
22
+ - `agent-secrets --help` holds the rest: the flags that narrow a GitHub App token
23
+ (`--github-owner`, `--github-repo`, `--github-read-only`), and how long a grant lasts.
24
+
25
+ ## The command reads the value, your shell does not
26
+
27
+ This form sends an empty value, and the API answers as if you had sent no credential:
28
+
29
+ ```sh
30
+ # wrong
31
+ agent-secrets LEGION_SLACK_BOT_TOKEN -- \
32
+ curl -sS -H "Authorization: Bearer $LEGION_SLACK_BOT_TOKEN" https://slack.com/api/auth.test
33
+ ```
34
+
35
+ Your own shell expands `$LEGION_SLACK_BOT_TOKEN` before `agent-secrets` runs, and in your shell that
36
+ 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
39
+ `sh -c`, where the quotes keep the expansion for the child:
40
+
41
+ ```sh
42
+ # right
43
+ agent-secrets LEGION_SLACK_BOT_TOKEN -- \
44
+ sh -c 'curl -sS -H "Authorization: Bearer $LEGION_SLACK_BOT_TOKEN" https://slack.com/api/auth.test'
45
+ ```
46
+
47
+ The repository uses the same form for a GitHub App token in `docs/deployment.md`:
48
+
49
+ ```sh
50
+ agent-secrets LEGION_IMPLEMENT_APP --reason=… -- sh -c 'printf %s "$LEGION_IMPLEMENT_APP"'
51
+ ```
52
+
53
+ ## The value never reaches your transcript
54
+
55
+ Your transcript keeps everything a command prints.
56
+
57
+ - Never echo or print the value, and never run `curl -v`, `curl --trace` or a shell with `set -x`
58
+ 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:
60
+
61
+ ```sh
62
+ agent-secrets NAME -- sh -c 'echo "${#NAME}"; case "$NAME" in ghp_*) echo prefix-ok;; *) echo prefix-no;; esac'
63
+ ```
64
+
65
+ - Compare two values only as equal or not equal. Never print, slice or diff their characters.
66
+
67
+ ## Read the answer, not the status alone
68
+
69
+ Slack and most HTTP APIs answer `200` with `"ok": false`, so a call that failed can still exit 0.
70
+ Read the body. Send it to `jq` straight from `curl`, or through `printf '%s'`, and never through
71
+ `echo`: the pod's `sh` turns a `\n` inside a JSON string into a control character, which `jq` then
72
+ refuses.
73
+
74
+ ## What the exit status means
75
+
76
+ After a grant the client writes one line to stderr, `agent-secrets: <names> from <source>`, and the
77
+ status is then the command's own. One case breaks that: a line `agent-secrets: exec <command>: …`
78
+ after it means the command could not start, and the status is 1.
79
+
80
+ Without the grant line the status is the client's own:
81
+
82
+ - **1** — a refusal or a failure that the message names: a name the broker does not serve
83
+ (`UNKNOWN_SECRET`), a broker it cannot reach, a machine that is not logged in to the broker, a
84
+ request cancelled or expired, `REQUEST_PENDING`, a grant that is no longer live, or a command
85
+ that is not on `PATH`.
86
+ - **2** — a usage error: no broker identity at all (no key in the key dir and no helper socket), no
87
+ `AGENT_SECRETS_URL`, no `--`, no `NAME`, or a flag value the client refuses.
88
+ - **75** — the request still waits for a person. The message names who decides it, where, and the
89
+ `agent-secrets status <request_id>` that reads it.
90
+ - **77** — the request was denied.
91
+
92
+ The other statuses come from forms this skill does not use: 76 from `agent-secrets renew`, a
93
+ refusal that is permanent; 126 and 127 from `agent-secrets register --exec`, whose command could not
94
+ run or was not found; and 129, 130, 131 and 143 from a signal at the value prompt of
95
+ `agent-secrets secret create` or `secret set`. `agent-secrets --help` lists them all.
96
+
97
+ ## Waiting, and a grant you already hold
98
+
99
+ - `--wait` waits 30 minutes by default. A session that must not block passes `--wait 0s`, reads the
100
+ request id from the message, and reads the decision later with
101
+ `agent-secrets status <request_id>`.
102
+ - A later run with the same names and the same `--ttl` uses the live grant again and asks nobody;
103
+ while the first request still waits, such a run joins it. Any other run that would itself wait
104
+ for a person and shares a name with a waiting request, with another `--ttl` or another set of
105
+ names, is refused `REQUEST_PENDING`, which names the request already waiting.
106
+ - `agent-secrets identity` exits 0 when this session has a broker identity and 1 when it has none,
107
+ and it asks the broker nothing. `agent-secrets self` prints this session's live grants.
108
+
109
+ ## Where a name comes from, and how you may use it
110
+
111
+ The broker tells a session no names. A name comes from your deployment instructions, your role
112
+ prompt, a skill, or the issue you work on. There is no list to browse and nothing to guess.
113
+
114
+ - Request a secret only to use it for the work in front of you. A request made to learn whether a
115
+ secret exists reaches a person's Inbox.
116
+ - `UNKNOWN_SECRET` and a denial are final. Do not ask again, and do not try a name of your own.
117
+ - A secret that a service owns, such as `LEGION_SLACK_BOT_TOKEN`, goes to that service's own pods
118
+ and VMs and to nothing else: `Evaluate` in `packages/envoy/internal/broker/policy/policy.go`
119
+ grants a service-owned secret at once when the session's own service is the secret's owner, and
120
+ denies every other session, with no person asked.
121
+ - The `agent-secrets secret` forms (`list`, `show`, `create`, `set`, `retag`, `delete`, `restore`)
122
+ act under a person's own cloud sign-in. They belong to the secret's owner, not to an agent.
123
+ - Slack's read methods go through `curl` under this client. Every post to Slack stays a `slack_post`
124
+ call, which holds the reply to one thread, to 4,000 characters and to one send.
125
+
126
+ ## Before you say that a service is out of reach
127
+
128
+ 1. Run the call through `agent-secrets`, with the secret your instructions name.
129
+ 2. Report a service unreachable only with the command you ran and the output you saw.
130
+ 3. When no instruction names a secret for that service, report that instead, with what you checked:
131
+ `agent-secrets identity`, and which instructions you read. Request no name you guessed.
132
+
133
+ ## On a person's own machine
134
+
135
+ A session on a person's own development box is not a pod, and `agent-secrets identity` exits 1 there
136
+ for two reasons:
137
+
138
+ - **The machine is not logged in.** `agent-secrets machine login-status` prints `issued` only while
139
+ the machine holds its credential. The person logs the machine in; step 4b of `docs/joining.md` in
140
+ theorem-labs/agent-infra, "Log the VM in to the secrets broker", is that step.
141
+ - **The agent is not a broker session.** The helper knows only the process tree it registered. The
142
+ person restarts the agent as one:
143
+ `agent-secrets register --wait 10 --exec -- <the agent's command>`.
144
+
145
+ On `UNKNOWN_SECRET` you stop, as above. You may tell the secret's owner how to find the cause:
146
+ `agent-secrets secret list` and `agent-secrets secret show NAME`, under their own cloud sign-in
147
+ (`gcloud auth login` against a broker on Google Cloud, their `AWS_PROFILE` against one on AWS).
148
+
149
+ An owner who must store a secret does every write under their own cloud sign-in.
150
+ `agent-secrets secret set NAME` replaces the value of a secret that exists. A new one is
151
+ `agent-secrets secret create NAME --owner me|shared --tier agent|human`. Both read the value from
152
+ standard input or from a prompt with echo off, never from an argument. Type it at the prompt, so it
153
+ reaches no shell history.
154
+
155
+ ## A worked example: one page of a Slack thread
156
+
157
+ ```sh
158
+ agent-secrets LEGION_SLACK_BOT_TOKEN --reason 'read the thread of a Slack mention' --wait 0s -- sh -c '
159
+ curl -sS -G https://slack.com/api/conversations.replies \
160
+ -H "Authorization: Bearer $LEGION_SLACK_BOT_TOKEN" \
161
+ --data-urlencode channel=<channel_id> \
162
+ --data-urlencode ts=<thread_ts> \
163
+ --data-urlencode limit=200'
164
+ ```
165
+
166
+ Measured on 2026-11-04 from a Legion issue pod: it exited 0 and answered `"ok": true` with the 12
167
+ messages of the thread. A `ts` that names no message answers
168
+ `{"ok":false,"error":"thread_not_found"}`, also at exit 0, which is why the body decides and not the
169
+ status. A thread read needs the app's `channels:history` scope in a public channel and
170
+ `groups:history` in a private one; without them Slack answers `missing_scope`, which only a person
171
+ in the Slack workspace can fix. A session with a broker identity that is not one of the
172
+ `legion-daemon` service's own is denied this token, and the example exits 77; a session with no
173
+ broker identity exits 2.
174
+
175
+ Paging: Slack recommends a `limit` of at most 200. While the answer's `has_more` is true, pass its
176
+ `response_metadata.next_cursor` as `cursor` to the next call. Each page repeats the thread's root
177
+ message, so drop repeats by `ts` and sort by `ts`.
178
+
179
+ A message from the client that this skill does not cover is in the broker's troubleshooting guide,
180
+ `/legion/broker/guides/troubleshooting/` in the documentation site.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sjawhar/pi-envoy",
3
- "version": "16.3.1",
3
+ "version": "16.4.0",
4
4
  "license": "Apache-2.0",
5
5
  "type": "module",
6
6
  "omp": {