Skip to content
Merged
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
140 changes: 140 additions & 0 deletions .agents/skills/release/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,140 @@
---
name: release
description: Run the remote-agent release flow end-to-end. Use when the user asks to release patch, minor, major, beta, or an explicit semver; includes non-interactive release execution, GitHub Actions monitoring with gh, draft release note cleanup, and publishing the GitHub Release.
---

# remote-agent Release

Use this skill to perform an end-to-end release for this repository.

## Inputs

Interpret the user's argument as the release version spec:

- `patch`, `minor`, `major`, `beta`
- or an explicit semver such as `0.1.0` / `0.1.0-beta.0`

If no version spec is present, ask the user which one to use.

## Preconditions

1. Work from the repository root.
2. Inspect the current branch and working tree:

```bash
git branch --show-current
git status --short
```

3. If there are unrelated uncommitted changes, stop and ask the user how to handle them.
4. If release-related changes were just made, commit them before running release because `scripts/release.ts` requires a clean working tree.
5. The release script requires SSH signing config:

```bash
git config --get gpg.format
git config --get commit.gpgsign
git config --get tag.gpgsign
```

Expected values are `ssh`, `true`, `true`.

## Release command

Run the non-interactive release:

```bash
VERSION_SPEC="patch" # replace with the user's requested spec
pnpm release -y --version "$VERSION_SPEC"
```

The script runs audit/build/license/gatecheck/test/pack checks, updates `package.json`, creates a signed release commit, creates a signed tag, and pushes commits and tags.

## If push fails because the branch has no upstream

The release commit and tag may already exist locally. Push the current branch with upstream, then push tags:

```bash
BRANCH="$(git branch --show-current)"
git push --set-upstream origin "$BRANCH"
git push --tags
```

Do not rerun `pnpm release` unless the local release commit/tag were removed or the previous run failed before creating them.

## Monitor GitHub Actions

After tags are pushed, find and watch the Release workflow run:

```bash
gh run list --workflow Release --limit 5
RUN_ID="<id from the vX.Y.Z row>"
gh run watch "$RUN_ID" --exit-status
```

A reusable one-liner variant:

```bash
TAG="v0.0.0"; RUN_ID="$(gh run list --workflow Release --limit 20 --json databaseId,headBranch,event --jq ".[] | select(.headBranch == \"$TAG\" and .event == \"push\") | .databaseId" | head -n 1)"; test -n "$RUN_ID" && gh run watch "$RUN_ID" --exit-status
```

If the workflow fails, inspect logs before taking corrective action:

```bash
gh run view "$RUN_ID" --log-failed
```

## Verify publish

After the workflow succeeds:

```bash
TAG="v0.0.0" # replace
npm view @kimuson/remote-agent version
gh release view "$TAG" --json tagName,name,isDraft,isPrerelease,url
```

## Rewrite and publish GitHub Release

The workflow creates a draft release. Inspect the generated notes:

```bash
TAG="v0.0.0" # replace
gh release view "$TAG" --json body --jq .body
```

Rewrite the notes according to `docs/release-note-guideline.md`. The generated draft is based on commit logs, so categories and wording may be wrong from the remote-agent product perspective. Remove internal-only updates, move entries to the correct category, merge intermediate same-release fixes into their related feature, and rewrite commit-message phrasing into release-note prose.

For a second-pass review before publishing, delegate a focused review to another agent:

```bash
RELEASE_URL="https://github.com/d-kimuson/remote-agent/releases/tag/v0.0.0" # replace
pi -p "Read docs/release-note-guideline.md, review the Release Note at $RELEASE_URL, and identify concrete changes that should be made. Do not edit files or GitHub releases; only report findings."
```

Apply the review findings when they are consistent with the guideline.

Publish the draft with the rewritten notes:

```bash
TAG="v0.0.0" # replace
NOTES_FILE="/tmp/remote-agent-$TAG-release-notes.md"
$EDITOR "$NOTES_FILE" # or write the file with the agent's file tool
gh release edit "$TAG" --notes-file "$NOTES_FILE" --draft=false
```

Confirm it is public:

```bash
gh release view "$TAG" --json tagName,name,isDraft,isPrerelease,url
```

## Final report

Report:

- released tag/version
- local release command used
- GitHub Actions run ID and result
- npm version verification result
- GitHub Release URL and draft/public state
- any follow-up commits created for release automation or skill updates
34 changes: 33 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,10 +70,15 @@ Then clients must send the API key as a bearer token for `/api/*` requests. You
- 🛠️ Visual tool viewers: inspect common tool calls such as Bash, Read, Write, and Edit with
terminal, file, and diff viewers.
- ✅ Tool approval: approve or reject tool-approval requests from supported agents.
- 🧱 Sandboxed execution: optionally run agent CLIs through `srt` sandboxing with global,
project-level, and per-session controls.
- 🔔 Notifications: receive task-completion and approval-request notifications. When installed as a
PWA, device notifications are available through the service worker.
- 🔊 Completion sound: play an audible notification when an agent task finishes.
- ✍️ Efficient prompt input: use agent command completion, file-path completion, and voice input.
- ✍️ Efficient prompt input: use agent command completion, file-path completion, voice input, and
image attachments.
- 🎚️ Model and mode controls: switch supported providers' model/mode from the UI, remember the last
used choices per project/provider, and pin favorite models.
- 🧑‍💻 Code review: open a GitHub-like diff viewer, leave line comments, and seamlessly turn them
into review instructions for the agent.
- 🌿 Git worktree support: start sessions in a selected worktree. Supports `.worktreeinclude`,
Expand Down Expand Up @@ -128,6 +133,33 @@ See the ACP agent list at https://agentclientprotocol.com/get-started/agents to
agent. If the agent you want is not listed, implement an ACP-compatible agent server and register
its command as a Custom Provider.

## Sandboxed Agent Execution

`remote-agent` can launch agent CLIs through `@anthropic-ai/sandbox-runtime` (`srt`) so agent
processes run with explicit filesystem and network rules.

Sandboxing is opt-in and has three layers:

1. **Global Settings → Sandbox**: choose which provider presets are allowed to use sandboxing and
define global filesystem/network rules.
2. **Project Settings → Sandbox**: enable sandboxing by default for that project and add project
rules. Relative paths are resolved from the session working directory.
3. **New session toolbar**: toggle sandboxing for an individual session before it starts.

Filesystem rules support read/write allowlists and denylists. Network policy can be unrestricted
(`none`) or restricted to an allowlist of domains. Project network policy can inherit the global
policy, override it with its own restricted allowlist, or disable network restriction for that
project.

For agent runtime files, `remote-agent` automatically grants read access to common local agent
configuration directories such as `~/.codex`, `~/.pi`, `~/.claude`, `~/.github`, and `~/.copilot`.
Provider-specific writable runtime directories are added where needed, such as `~/.codex` for Codex
and `~/.pi` for pi-coding-agent. The default write allowlist includes the session working directory
(`.`).

Sandboxing is a defense-in-depth feature, not a replacement for normal security controls. Keep using
private networks, API key authentication, IP restrictions, and trusted agent credentials.

## How It Works

`remote-agent` keeps ACP sessions on the Node.js server instead of starting local agents directly from the browser. The browser SPA talks to the Hono API/BFF, the server manages ACP-compatible provider processes, and agent output, plans, diffs, terminal data, and approval requests are streamed back to the browser.
Expand Down
2 changes: 1 addition & 1 deletion docs/openapi.json

Large diffs are not rendered by default.

134 changes: 134 additions & 0 deletions docs/release-note-guideline.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,134 @@
# Release Note Guideline

This guideline is for agents reviewing and rewriting GitHub Release notes for remote-agent.

## Background

Release notes are initially generated automatically from commit logs. Treat them as a draft, not as the final source of truth.

Because they come from commits:

- Conventional Commit types such as `feat`, `fix`, and `perf` may not match the actual user-facing release-note category.
- Internal implementation details may be included even when they are not useful to remote-agent users.
- Commit-message phrasing may be too terse, too technical, or written from a developer workflow perspective.
- Intermediate commits may appear as fixes even though the feature they fix has never been released before.

## Review Perspective

Review the draft from the perspective of the released remote-agent software, not from the perspective of the repository commit history.

Ask:

- What changed for users or operators of remote-agent?
- Is this an actual product feature, bug fix, performance improvement, or maintenance-only change?
- Would this entry help someone decide whether to upgrade or understand what changed?

## Categorization Rules

### Features

Use `Features` for new or expanded remote-agent capabilities visible to users, operators, or API consumers.

Do not classify development workflow improvements as product features. For example, adding lefthook-based commit checks may be a `feat` commit, but it is not a remote-agent software feature and usually should not appear in release notes.

### Fixes

Use `Fixes` for bugs that existed in a previously released version and are now corrected.

Be careful with fix commits that only repair a feature introduced earlier in the same unreleased cycle. If the broken state was never released to users, do not list it as a bug fix. Instead:

- merge it into the related feature entry, or
- omit it if it is only an implementation correction.

Do not list CI fixes, release automation fixes, test fixes, lint fixes, or development-tool fixes as product bug fixes unless they directly affect the published package or user-visible behavior.

### Performance

Use `Performance` only for changes that improve runtime behavior, responsiveness, resource usage, or scalability of remote-agent.

Do not use it for build-time, CI-time, or developer-tool performance unless that is relevant to users of the published software.

### Maintenance / Internal Changes

Most internal changes should be omitted from release notes, including:

- CI changes
- test-only updates
- lint/format/tooling configuration
- refactors with no user-visible impact
- release automation changes
- dependency updates with no notable user-facing impact
- documentation-only changes that do not change product behavior

Include such changes only when they are important for users, operators, or package consumers to know.

## Rewriting Rules

The generated draft uses commit-message text. Rewrite entries into release-note prose.

Good release-note entries should be:

- user-facing or operator-facing
- concise but understandable
- written in past tense or neutral descriptive style
- free of commit-message prefixes, implementation noise, and unnecessary scopes
- grouped under the category that best reflects the released product behavior

Avoid:

- raw commit-message phrasing such as “add x”, “fix y”, or “refactor z” when it reads like a developer task
- mentioning commit hashes or authors unless intentionally preserving generated metadata
- exposing temporary bugs that were introduced and fixed before the release
- listing every small internal commit separately

## Suggested Review Workflow

1. Read the generated release note draft.
2. Inspect the commit list between the previous tag and the new tag when needed:

```bash
git log --oneline vPREVIOUS..vNEXT
```

3. Identify entries that should be:
- kept as-is
- rewritten
- moved to another category
- merged with another entry
- removed entirely
4. Produce a concrete review report before editing.
5. Rewrite the release notes based on that report.

For a second-pass review, ask another agent to review the draft against this guideline, for example:

```bash
pi -p 'Read docs/release-note-guideline.md, review the Release Note at <url>, and identify concrete changes that should be made. Do not edit files or GitHub releases; only report findings.'
```

## Final Shape

A typical release note should look like:

```markdown
## Highlights

- Summarize the most important user-facing changes.

## Changes

### Features

- Describe product capabilities added or expanded.

### Fixes

- Describe user-visible bugs fixed from previous releases.

### Performance

- Describe runtime performance improvements.

[View changes on GitHub](https://github.com/d-kimuson/remote-agent/compare/vPREVIOUS...vNEXT)
```

Omit empty sections.
6 changes: 3 additions & 3 deletions package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@kimuson/remote-agent",
"version": "0.0.5",
"version": "0.0.6",
"description": "A CLI that serves a web UI and bridge server for interacting with ACP-compatible agents",
"license": "MIT",
"repository": {
Expand Down Expand Up @@ -50,9 +50,9 @@
"test": "vitest run"
},
"dependencies": {
"@agentclientprotocol/claude-agent-acp": "0.31.4",
"@agentclientprotocol/claude-agent-acp": "0.32.0",
"@anthropic-ai/sandbox-runtime": "0.0.49",
"@zed-industries/codex-acp": "0.12.0",
"@zed-industries/codex-acp": "0.13.0",
"pi-acp": "0.0.26"
},
"devDependencies": {
Expand Down
Loading
Loading