@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 +3 -2
- package/dist/envoy.js +1 -1
- package/dist/skills/agent-secrets/SKILL.md +180 -0
- package/package.json +1 -1
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
|
|
173
|
-
`dispatch`, `dispatch-first`, `dispatch-writing-specs
|
|
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.
|
|
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.
|