Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 12 additions & 2 deletions .agents/skills/launch-openshell-gator/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,10 +23,12 @@ For gator's PR/issue validation policy, load `gator-gate` inside the launched sa
| Path | Purpose |
|---|---|
| `scripts/agents/run.sh` | Manifest-driven OpenShell agent launcher. |
| `scripts/agents/gator/agent.yaml` | Gator manifest: default gateway, harness, providers, runtime, skills, and subagents. |
| `scripts/agents/gator/agent.yaml` | Gator manifest: immutable payload version, default gateway, harness, providers, runtime, skills, and subagents. |
| `scripts/agents/gator/Dockerfile` | Gator sandbox image source. Local launches build this image through OpenShell. |
| `scripts/agents/gator/policy.yaml` | Sandbox policy for the gator agent. |
| `scripts/agents/gator/bin/gh` | Gator-specific `gh` wrapper and same-SHA duplicate-post guard. |
| `scripts/agents/gator/bin/review-feedback-ledger` | Builds tree-aware review scope, durable findings, convergence telemetry, and checkpoint state. |
| `scripts/agents/gator/bin/validate-review-findings` | Enforces the blocker evidence schema and downgrades unsupported hypotheses. |
| `scripts/agents/gator/prompts/gator.md` | Rendered top-level prompt template baked into the payload. |
| `scripts/agents/gator/skills/gator-gate/SKILL.md` | In-sandbox gator state-machine skill. |
| `scripts/agents/gator/logs/` | Background launch and supervisor logs. |
Expand Down Expand Up @@ -283,6 +285,7 @@ Read that file directly. Important markers:
- `OpenAI Codex v...` plus `model: ...` confirms the Codex CLI and model actually used.
- `OPENSHELL_AGENT_RESULT {...}` is the bounded-cycle sentinel. In watch mode, the supervisor sleeps and relaunches after this line.
- `openshell-agent: still running watch cycle ...` is a heartbeat during long active model cycles.
- `review_feedback_lookup_failed` means Gator could not build the required cross-SHA feedback ledger and deliberately skipped a context-free review.

### Inspect Active Sandboxes

Expand All @@ -305,13 +308,20 @@ If `sandbox get` is not supported by the local CLI shape, use `openshell sandbox
| `status=waiting` | Normal watch wait. | Leave sandbox running. |
| `status=blocked` | Human/process blocker. | Read reason; decide whether a human action is needed. |
| `status=transient_failure` | Retryable infrastructure/auth/transport issue. | Let supervisor retry unless repeated failures hit the configured cap. |
| `status=terminal_failure` | Unrecoverable agent failure. | Inspect log and fix/relaunch. |
| `status=terminal_failure` | Unrecoverable or stale immutable payload. | Inspect the reason; rebuild/relaunch for `stale_gator_payload`. |
| `status=complete` | Target closed, merged, or one-shot complete. | Delete sandbox if no longer needed. |

## Restarting A Gator

Restart when the payload must change, the sandbox is wedged without a sentinel, the model/tooling version changed, or a transient failure repeats past the useful retry point.

Increment `payload_version` in `scripts/agents/gator/agent.yaml` whenever a
merged change alters the Gator prompt, gate skill, reviewer contract, write
guard, ledger, or bundled validator. Existing immutable watchers cannot replace
their own payload. New-version watchers detect later published versions and
stop with `stale_gator_payload`; relaunch every still-active older watcher after
the version bump is published.

Before deleting, check that the sandbox is truly stale or that the operator asked for a restart. If a bounded review cycle is actively running and still producing useful output, prefer leaving it alone.

```bash
Expand Down
6 changes: 5 additions & 1 deletion .agents/skills/openshell-cli/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,12 +52,15 @@ Use an `http://` endpoint only for trusted local port-forwarding or a protected

```bash
openshell status
openshell whoami
```

Confirm the gateway is reachable, authentication is valid or not required, and
the output shows a version. `Status: Connected` only proves the public health
endpoint is reachable; inspect the separate `Authentication` line before
running protected commands.
running protected commands. `openshell whoami` reports the identity validated
by the gateway, including the subject an administrator uses for workspace
membership. Add `--output json` for automation.

### Step 3: Create a sandbox

Expand Down Expand Up @@ -625,6 +628,7 @@ $ openshell sandbox upload --help
|------|---------|
| Register local port-forwarded gateway | `openshell gateway add http://127.0.0.1:8080 --local --name local` |
| Check gateway health and authentication | `openshell status` |
| Show authenticated identity and subject | `openshell whoami` |
| List/switch gateways | `openshell gateway select [name]` |
| Connect directly to a gateway | `openshell --gateway-endpoint <url> status` |
| Create sandbox (interactive) | `openshell sandbox create` |
Expand Down
10 changes: 10 additions & 0 deletions .agents/skills/openshell-cli/cli-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ openshell
│ ├── list
│ └── select [name]
├── status
├── whoami [--output <format>]
├── inference
│ ├── set --provider --model
│ ├── update [--provider] [--model]
Expand Down Expand Up @@ -186,6 +187,15 @@ gateway. Connectivity uses the public health RPC; authentication is checked
with the protected gateway-info capability query and can fail while the gateway
remains connected.

### `openshell whoami`

Show the authenticated user identity: subject, display name, roles, scopes, and
identity provider. Requires an authenticated gateway connection.

| Flag | Description |
|------|-------------|
| `--output <FORMAT>` | Output format: `table` (default), `json`, or `yaml` |

---

## Sandbox Commands
Expand Down
Loading
Loading