Skip to content

Commit 3d1a5ed

Browse files
committed
chore(python): merge main and resolve proto generator conflict
Signed-off-by: Max Dubrinsky <[email protected]>
2 parents af4c5b2 + ea265a2 commit 3d1a5ed

573 files changed

Lines changed: 81208 additions & 14834 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
name: apply-triage-action
3+
description: Apply, reject, or defer exactly one issue or CI recommendation from a local triage queue report. Use when the on-duty engineer explicitly supplies an item ID.
4+
metadata:
5+
internal: true
6+
---
7+
8+
# Apply Triage Action
9+
10+
Process exactly one item ID from a queue-review report. Do not accept a natural-language approval without an ID. PRs are informational in v1.
11+
12+
## Locate and validate
13+
14+
1. Read the checkpoint and action records under `.agents/triage-duty/`; reconcile dispositions using the [local-state rules](../review-triage-queue/SKILL.md#local-state).
15+
2. Use the named report, or the latest report containing the ID. Read the recommendation and current disposition. Material changes to a previously selected recommendation require fresh review and selection.
16+
3. Reject missing, superseded, already-final, or ambiguous recommendations without making a write. Never substitute another item.
17+
4. Append every explicit disposition or attempted action to a dated local action record. Record repository, target, source report, ID, timestamp, disposition, reason, confirmed payload, and outcome; update the checkpoint afterward. Keep sensitive content out of the record; use `private reason withheld` for private reasons.
18+
19+
## Reject or defer
20+
21+
For **reject** or **defer**, require the engineer to give a reason. Record the local disposition.
22+
23+
- **Reject** is terminal locally. Do not recommend the item again unless material new evidence changes the case.
24+
- **Defer** is non-terminal. Preserve its original priority and carry it into the next review's carried **Needs your decision** section.
25+
26+
For shareable deferrals, draft a GitHub issue comment with reason, public links, and next step, or link existing waiting context. Use the confirmation rule below; declined posting leaves a local-only deferral. Keep private reasons out of external payloads and committable files. For missing reporter evidence, also propose the awaiting-information assessment state using `triage-issue`; unrelated dependency waits do not change lifecycle labels.
27+
28+
## Apply
29+
30+
Before any external write, re-read the target and determine whether it materially changed. Follow [Label Discovery](../../../CONTRIBUTING.md#label-discovery), retrieving all pages of current definitions before proposing a label change; use [`triage-issue`](../triage-issue/SKILL.md) for assessment states and maintainer authority.
31+
32+
- If the action is already complete or would be a harmless no-op, make no external write and record the reason.
33+
- If new information makes the action unsafe or substantially different, stop and request a fresh review/selection.
34+
35+
You MUST ALWAYS preview the exact payload, item ID, source report, and canonical target, then receive explicit confirmation for each individual external write. Selecting or deferring an item is not confirmation; comments, label changes, and closures require separate confirmations. Revalidate immediately before execution; changed payloads require a new preview and confirmation. Never reuse confirmation for a later invocation.
36+
37+
After confirmation, perform only the approved action and record its outcome and public URL; mark applied only after success.
38+
39+
Supported v1 actions:
40+
41+
- Add the discovered triage-queue label to an open substantive community issue; recheck the [intake eligibility rules](../review-triage-queue/SKILL.md#gather-intake) and exclude duplicates, spam, and security disclosures.
42+
- Create one GitHub issue using [`create-github-issue`](../create-github-issue/SKILL.md).
43+
- Post one public issue comment, including waiting context or a duplicate explanation.
44+
- Change an issue's assessment state to awaiting information.
45+
- Close one issue with an evidenced reason; identify the canonical issue for duplicates.
46+
47+
Never create a public GitHub issue for a security finding. Follow [SECURITY.md](../../../SECURITY.md).

‎.agents/skills/build-from-issue/SKILL.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,3 +32,5 @@ Use a single issue comment beginning with `> **🏗️ build-plan**` when a plan
3232
Every PR from this issue-backed workflow must have its own existing issue and use `Closes #<id>` in its Related Issue section. For work needing multiple PRs, split the scope into a closable issue per PR. A high-level issue may track those issues but should not be closed by an incomplete PR. Report the implementation, verification, and any remaining limitation in the PR description, rather than copying earlier issue diagnostics.
3333

3434
Do not apply acceptance or roadmap decisions on behalf of a maintainer. Do not introduce `agent:*` workflow labels.
35+
36+
For first-party security-sensitive crypto, use `openshell-crypto` and extend its facade/backend contracts when needed. Follow the [crypto architecture](../../../crates/openshell-crypto/CRYPTO.md) for compatibility, failure handling, and explicit coverage exceptions.

‎.agents/skills/build-openshell-mxc-windows/SKILL.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,18 @@ Windows MSVC for the supported deliverables:
2121
It intentionally does not make Windows a Docker, Kubernetes, Podman, or VM
2222
runtime host.
2323

24+
The supervisor and supervisor-process libraries participate in native Windows
25+
checks and tests. Their gateway session, boundary attachment, and TCP readiness
26+
are portable; only the optional Unix SSH/readiness socket adapters are gated.
27+
This is compile and control-plane coverage, not Windows isolation qualification.
28+
Preserve readiness gating on authenticated gateway acceptance and reconnection.
29+
The supervisor process-access multiplexer consumes boundary-provided streams;
30+
do not restore local PID, PTY, or process-group operations there. Native process
31+
mechanics belong to the sandbox or isolation backend. Keep the optional Unix
32+
SSH access adapter separate from portable session orchestration.
33+
Shared Sandbox Protocol audit validation defaults to strict Linux evidence;
34+
concrete platform validators must be selected by the implementing backend.
35+
2436
## Current Repository Shape
2537

2638
The Windows build lane is implemented by these tracked files:

‎.agents/skills/build-openshell-mxc-windows/reference.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -111,8 +111,6 @@ top-level workspace targets for check/test:
111111
--exclude openshell-driver-vault
112112
--exclude openshell-driver-vm
113113
--exclude openshell-sandbox
114-
--exclude openshell-supervisor
115-
--exclude openshell-supervisor-process
116114
--exclude openshell-vfio
117115
```
118116

@@ -124,6 +122,10 @@ egress proxy. The Kubernetes Secrets and Vault libraries still compile as
124122
gateway dependencies; only their standalone Unix-socket binaries and
125123
package-level tests are excluded as top-level targets.
126124

125+
The supervisor and supervisor-process packages now participate as top-level
126+
native check/test targets. Their portable session, attachment, and TCP readiness
127+
coverage does not enable a Windows isolation runtime.
128+
127129
## Common Errors
128130

129131
### Unix imports leak into Windows builds

‎.agents/skills/create-github-pr/SKILL.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -176,6 +176,9 @@ PR descriptions must follow the project's [PR template](.github/PULL_REQUEST_TEM
176176
## Changes
177177
<!-- Bullet list of key changes -->
178178

179+
## Release Notes
180+
<!-- Optional: a few short, easy-to-read sentences about the user-facing change -->
181+
179182
## Testing
180183
<!-- What testing was done? -->
181184
- [ ] Checks appropriate to the affected code and behavior pass
@@ -188,6 +191,8 @@ PR descriptions must follow the project's [PR template](.github/PULL_REQUEST_TEM
188191
```
189192

190193
Populate the testing checklist based on what was actually run. Check boxes for steps that were completed.
194+
Keep the Release Notes section concise, with only a few easy-to-read sentences.
195+
Leave it empty when the summary already captures the user-facing change.
191196

192197
## Example PR (Complete)
193198

@@ -209,6 +214,10 @@ Closes #456
209214
- Default page size is 100, max is 1,000
210215
- Structured responses include `next_page_token`
211216
217+
## Release Notes
218+
219+
Sandbox list results can now be paged through with `--page-size` and `--page-token`.
220+
212221
## Testing
213222
214223
- [x] Relevant CLI format, lint, and unit checks pass

‎.agents/skills/fix-security-issue/SKILL.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,3 +16,5 @@ Use this skill after an authorized `review-security-issue` review identifies an
1616
5. Follow `create-github-pr` and use `Closes #<id>` for the reviewed issue. Every PR from this issue-backed remediation workflow must close its own issue; split multi-PR remediations into separate issues in the authorized security workflow. Keep the PR description appropriately scoped to its disclosure venue.
1717

1818
Begin any fix comments with `> **🔧 security-fix-agent**`. Do not change human disposition or introduce `agent:*` workflow labels.
19+
20+
For first-party security-sensitive crypto, use `openshell-crypto` and extend its facade/backend contracts when needed. Follow the [crypto architecture](../../../crates/openshell-crypto/CRYPTO.md) for compatibility, failure handling, and explicit coverage exceptions.

‎.agents/skills/helm-dev-environment/SKILL.md‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,7 +81,16 @@ The Skaffold flow builds distinct `gateway`, `sandbox`, and `supervisor` images
8181
and deploys the OpenShell Helm chart. The Kubernetes driver creates a
8282
capability-free workload Pod and a directly managed capability-free supervisor
8383
Pod. One namespace-wide NetworkPolicy denies direct egress from every OpenShell
84-
workload Pod. The
84+
workload Pod. New sandbox generations use `runtime-initiated` control: the sandbox
85+
runtime dials its supervisor through `os-supervisor-<id>`. The legacy
86+
`os-boundary-<id>` Service keeps selecting the workload for old gateways during
87+
rolling upgrades. New gateways create both Services and bind the control-mode
88+
annotation to its runtime generation. The driver adds a per-sandbox
89+
`os-control-<id>` NetworkPolicy for that path only. Existing running generations
90+
keep their connection until replaced; stop/start and gateway recovery that
91+
recreates both Pods upgrade legacy generations automatically. Use compatible
92+
gateway, supervisor, and sandbox runtime images together; there is no legacy
93+
rollout flag. The
8594
`pkiInitJob` hook (a pre-install Job that runs `openshell-gateway generate-certs`)
8695
generates gateway and CLI TLS secrets on first install. Supervisor Pods project
8796
only `ca.crt` and authenticate gateway RPCs with sandbox bearer tokens. User

‎.agents/skills/launch-openshell-gator/SKILL.md‎

Lines changed: 23 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -109,7 +109,7 @@ gateway_name="<selected-gateway-name>"
109109
openshell --gateway "$gateway_name" sandbox list
110110
```
111111

112-
Look for names like `gator-pr-<number>-supervised`. If one exists, inspect its log before deleting or relaunching.
112+
Look for names like `gtr-pr-<number>-watch`. If one exists, inspect its log before deleting or relaunching.
113113

114114
## Input Normalization
115115

@@ -129,11 +129,14 @@ pr_number="<digits-only>"
129129
[[ "$pr_number" =~ ^[0-9]+$ ]] || { echo "invalid PR number" >&2; exit 1; }
130130
```
131131

132-
Use the portable Kubernetes DNS-1123 sandbox-name format even when the selected gateway currently uses another driver:
132+
Sandbox names must be DNS-1123 labels of at most **19 characters**, including
133+
any suffix. The gateway reserves room for workspace, sandbox, and service
134+
segments in one DNS label; this limit applies to every compute driver. Use
135+
short names and validate them before launching:
133136

134137
```bash
135-
sandbox_name="gator-pr-${pr_number}-supervised"
136-
[[ "$sandbox_name" =~ ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ ]] || { echo "invalid sandbox name" >&2; exit 1; }
138+
sandbox_name="gtr-pr-${pr_number}-watch"
139+
[[ "$sandbox_name" =~ ^[a-z0-9]([a-z0-9-]{0,17}[a-z0-9])?$ ]] || { echo "invalid sandbox name" >&2; exit 1; }
137140
```
138141

139142
For local image contexts passed to `--from`, use an agent-created path such as `mktemp -d`; do not pass raw user-supplied paths without validating that they are expected local Dockerfile contexts.
@@ -149,8 +152,8 @@ gateway_name="<selected-gateway-name>"
149152
pr_number="<digits-only>"
150153
[[ "$gateway_name" =~ ^[A-Za-z0-9_.-]+$ ]] || { echo "invalid gateway name" >&2; exit 1; }
151154
[[ "$pr_number" =~ ^[0-9]+$ ]] || { echo "invalid PR number" >&2; exit 1; }
152-
sandbox_name="gator-pr-${pr_number}-supervised"
153-
[[ "$sandbox_name" =~ ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ ]] || { echo "invalid sandbox name" >&2; exit 1; }
155+
sandbox_name="gtr-pr-${pr_number}-watch"
156+
[[ "$sandbox_name" =~ ^[a-z0-9]([a-z0-9-]{0,17}[a-z0-9])?$ ]] || { echo "invalid sandbox name" >&2; exit 1; }
154157

155158
./scripts/agents/run.sh \
156159
--agent gator \
@@ -171,8 +174,8 @@ gateway_name="<selected-gateway-name>"
171174
issue_number="<digits-only>"
172175
[[ "$gateway_name" =~ ^[A-Za-z0-9_.-]+$ ]] || { echo "invalid gateway name" >&2; exit 1; }
173176
[[ "$issue_number" =~ ^[0-9]+$ ]] || { echo "invalid issue number" >&2; exit 1; }
174-
sandbox_name="gator-issue-${issue_number}-supervised"
175-
[[ "$sandbox_name" =~ ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ ]] || { echo "invalid sandbox name" >&2; exit 1; }
177+
sandbox_name="gtr-i-${issue_number}-watch"
178+
[[ "$sandbox_name" =~ ^[a-z0-9]([a-z0-9-]{0,17}[a-z0-9])?$ ]] || { echo "invalid sandbox name" >&2; exit 1; }
176179

177180
./scripts/agents/run.sh \
178181
--agent gator \
@@ -191,8 +194,8 @@ issue_number="<digits-only>"
191194
[[ "$gateway_name" =~ ^[A-Za-z0-9_.-]+$ ]] || { echo "invalid gateway name" >&2; exit 1; }
192195
[[ "$pr_number" =~ ^[0-9]+$ ]] || { echo "invalid PR number" >&2; exit 1; }
193196
[[ "$issue_number" =~ ^[0-9]+$ ]] || { echo "invalid issue number" >&2; exit 1; }
194-
sandbox_name="gator-pr-${pr_number}-supervised"
195-
[[ "$sandbox_name" =~ ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ ]] || { echo "invalid sandbox name" >&2; exit 1; }
197+
sandbox_name="gtr-pr-${pr_number}-watch"
198+
[[ "$sandbox_name" =~ ^[a-z0-9]([a-z0-9-]{0,17}[a-z0-9])?$ ]] || { echo "invalid sandbox name" >&2; exit 1; }
196199

197200
./scripts/agents/run.sh \
198201
--agent gator \
@@ -211,8 +214,8 @@ gateway_name="<selected-gateway-name>"
211214
pr_number="<digits-only>"
212215
[[ "$gateway_name" =~ ^[A-Za-z0-9_.-]+$ ]] || { echo "invalid gateway name" >&2; exit 1; }
213216
[[ "$pr_number" =~ ^[0-9]+$ ]] || { echo "invalid PR number" >&2; exit 1; }
214-
sandbox_name="gator-pr-${pr_number}-supervised"
215-
[[ "$sandbox_name" =~ ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ ]] || { echo "invalid sandbox name" >&2; exit 1; }
217+
sandbox_name="gtr-pr-${pr_number}-watch"
218+
[[ "$sandbox_name" =~ ^[a-z0-9]([a-z0-9-]{0,17}[a-z0-9])?$ ]] || { echo "invalid sandbox name" >&2; exit 1; }
216219

217220
./scripts/agents/run.sh \
218221
--agent gator \
@@ -231,8 +234,8 @@ gateway_name="<selected-gateway-name>"
231234
pr_number="<digits-only>"
232235
[[ "$gateway_name" =~ ^[A-Za-z0-9_.-]+$ ]] || { echo "invalid gateway name" >&2; exit 1; }
233236
[[ "$pr_number" =~ ^[0-9]+$ ]] || { echo "invalid PR number" >&2; exit 1; }
234-
sandbox_name="gator-pr-${pr_number}-gpt56sol-supervised"
235-
[[ "$sandbox_name" =~ ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ ]] || { echo "invalid sandbox name" >&2; exit 1; }
237+
sandbox_name="gtr-pr-${pr_number}-exp"
238+
[[ "$sandbox_name" =~ ^[a-z0-9]([a-z0-9-]{0,17}[a-z0-9])?$ ]] || { echo "invalid sandbox name" >&2; exit 1; }
236239

237240
CODEX_MODEL=gpt-5.6-sol \
238241
./scripts/agents/run.sh \
@@ -244,6 +247,8 @@ CODEX_MODEL=gpt-5.6-sol \
244247
```
245248

246249
If the installed Codex CLI is too old for a model, create a temporary copy of `scripts/agents/gator/`, adjust only that temporary Dockerfile, and launch with that generated context. Keep the repo Dockerfile unchanged unless the version bump is the intended code change.
250+
The short `-exp` suffix below identifies an experimental watcher; keep its full
251+
name within 19 characters.
247252

248253
Example shape:
249254

@@ -252,8 +257,8 @@ gateway_name="<selected-gateway-name>"
252257
pr_number="<digits-only>"
253258
[[ "$gateway_name" =~ ^[A-Za-z0-9_.-]+$ ]] || { echo "invalid gateway name" >&2; exit 1; }
254259
[[ "$pr_number" =~ ^[0-9]+$ ]] || { echo "invalid PR number" >&2; exit 1; }
255-
sandbox_name="gator-pr-${pr_number}-gpt56sol-supervised"
256-
[[ "$sandbox_name" =~ ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ ]] || { echo "invalid sandbox name" >&2; exit 1; }
260+
sandbox_name="gtr-pr-${pr_number}-exp"
261+
[[ "$sandbox_name" =~ ^[a-z0-9]([a-z0-9-]{0,17}[a-z0-9])?$ ]] || { echo "invalid sandbox name" >&2; exit 1; }
257262
tmp_context="$(mktemp -d "${TMPDIR:-/tmp}/gator-codex-XXXXXX")"
258263
cp -R scripts/agents/gator/. "$tmp_context"/
259264

@@ -298,7 +303,7 @@ The launcher streams image-build and provisioning output to the terminal. Import
298303
gateway_name="<selected-gateway-name>"
299304
sandbox_name="<safe-sandbox-name>"
300305
[[ "$gateway_name" =~ ^[A-Za-z0-9_.-]+$ ]] || { echo "invalid gateway name" >&2; exit 1; }
301-
[[ "$sandbox_name" =~ ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ ]] || { echo "invalid sandbox name" >&2; exit 1; }
306+
[[ "$sandbox_name" =~ ^[a-z0-9]([a-z0-9-]{0,17}[a-z0-9])?$ ]] || { echo "invalid sandbox name" >&2; exit 1; }
302307

303308
openshell --gateway "$gateway_name" sandbox list
304309
openshell --gateway "$gateway_name" sandbox get "$sandbox_name"
@@ -338,7 +343,7 @@ Before deleting, check that the sandbox is truly stale or that the operator aske
338343
gateway_name="<selected-gateway-name>"
339344
sandbox_name="<safe-sandbox-name>"
340345
[[ "$gateway_name" =~ ^[A-Za-z0-9_.-]+$ ]] || { echo "invalid gateway name" >&2; exit 1; }
341-
[[ "$sandbox_name" =~ ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ ]] || { echo "invalid sandbox name" >&2; exit 1; }
346+
[[ "$sandbox_name" =~ ^[a-z0-9]([a-z0-9-]{0,17}[a-z0-9])?$ ]] || { echo "invalid sandbox name" >&2; exit 1; }
342347

343348
openshell --gateway "$gateway_name" sandbox delete "$sandbox_name"
344349
./scripts/agents/run.sh \

‎.agents/skills/release-openshell/SKILL.md‎

Lines changed: 39 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -7,14 +7,46 @@ metadata:
77

88
# Release OpenShell
99

10-
For the intended release version, pick the latest prerelease whose Release
11-
Qualification job passed. Confirm that its qualification summary matches the
12-
tag and commit. Present the candidate and changes since the previous stable
13-
release to the maintainer; once approved, tag that exact commit as `vX.Y.Z`.
10+
For the intended release version and branch, inspect the latest passing
11+
prerelease and changes since the previous stable release. Present the candidate
12+
to the maintainer. Once approved, dispatch Release from that branch:
13+
14+
```shell
15+
gh workflow run release.yml --ref main -f tag=vX.Y.Z
16+
```
17+
18+
Use the support branch instead of `main` for a previous minor version. Release
19+
selects the highest-numbered `vX.Y.Z-pre.N` reachable from that branch with a
20+
successful Pre-release run triggered by that tag or dispatched on the same branch,
21+
and matching passing `release-tag-v1` qualification evidence. Missing or expired evidence blocks
22+
promotion. Inspect the selected candidate in the promotion job summary.
23+
The entire Pre-release run must succeed, including publication. If qualification
24+
passed but publication failed, rerun the failed jobs before promoting the candidate.
25+
26+
Release creates `vX.Y.Z` at that exact commit, then rebuilds and publishes all
27+
stable artifacts without rerunning qualification. Embedded versions change, so
28+
stable artifacts are not byte-identical to the qualified prerelease. An existing
29+
stable tag may be retried only if it already points to the selected commit.
30+
Stable images are saved as OCI archives during the build and pushed under the
31+
stable version tags during publication. Their SBOMs are verified before updating
32+
`latest`; the qualified prerelease's commit-SHA image tags remain unchanged.
1433

1534
If no prerelease exists, agree on the version and source commit, then create and
16-
push `vX.Y.Z-pre.1`. Wait for qualification to pass before promoting it.
35+
push `vX.Y.Z-pre.1`. Prerelease tag pushes start Pre-release. If the tag was
36+
created using `GITHUB_TOKEN`, dispatch Pre-release explicitly on the intended branch:
37+
38+
```shell
39+
gh workflow run release-prerelease.yml --ref main -f tag=vX.Y.Z-pre.1
40+
```
41+
42+
Wait for the entire Pre-release run to pass before promoting it. Stable tag pushes do not
43+
start Release. Release Auto-Tag creates and dispatches prereleases on `main`.
44+
45+
Stable releases serialize across branches. A release older than the highest
46+
stable Git tag publishes versioned artifacts without moving GHCR `latest`, the
47+
GitHub latest release, npm `latest`, or snap `latest/stable`. Its npm package
48+
uses `release-X.Y`; snap files remain available in its GitHub Release rather than
49+
updating a Snap Store support track. Docs retain an
50+
immutable version and advance latest only for a newer version.
1751

18-
Both prerelease and stable tag pushes start Release Tag. Release Auto-Tag uses
19-
an explicit dispatch because its `GITHUB_TOKEN` pushes do not trigger workflows.
2052
Watch the stable release run and report its result.

0 commit comments

Comments
 (0)