diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 00000000..0f4ae7cb --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,32 @@ +--- +name: Bug report +about: Help us reproduce a CLI problem +title: "[Bug] " +labels: bug +assignees: "" +--- + + + +## What happened + +Describe the behavior and what you expected instead. + +## Reproduction + +1. List the smallest sequence of commands or actions that triggers the problem. +2. Include a minimal public repository or sample when possible. +3. Say whether it reproduces consistently. + +## Environment + +- Aether Agent version (`aether --version`): +- Install path (npm or source): +- OS and terminal: +- Node.js version (`node --version`): +- Model route (hosted or Ollama; no credentials or account IDs): + +## Evidence + +Paste the relevant error, sanitized logs, and verification command/output. If the +working tree changed, summarize the affected paths. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..b000f08b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: true +contact_links: + - name: Security vulnerability + url: https://github.com/AetherAI3/aether-agent/security/policy + about: Report vulnerabilities privately; do not open a public issue. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 00000000..b68a0f42 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,20 @@ +--- +name: Feature request +about: Propose a focused improvement to Aether Agent +title: "[Feature] " +labels: enhancement +assignees: "" +--- + +## Problem + +What workflow is difficult or impossible today? Include a concrete example. + +## Proposed outcome + +Describe the result you want, not just a command name or implementation. + +## Constraints and alternatives + +Note any security, local-authority, compatibility, or offline requirements, plus +workarounds you already tried. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..2f8fc6ab --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,20 @@ +## Why + +What problem does this pull request solve? + +## What changed + +Summarize the focused change and call out any user-visible behavior. + +## Verification + +- [ ] Relevant tests and checks pass, or the reason they were not run is below. +- [ ] Public commands, examples, and generated docs were checked when applicable. + +Evidence or commands: + +## Scope and risk + +- Security or local-authority impact: +- Compatibility or release impact: +- Follow-up work intentionally left out: diff --git a/README.md b/README.md index 823df637..1696a567 100644 --- a/README.md +++ b/README.md @@ -1,102 +1,60 @@
- # Aether Agent -image +**Aether Agent is an open-source terminal coding agent that edits your repository, runs your chosen checks, and reports verified results through hosted models or local Ollama.** -**A terminal coding agent built around verifiable results and portable work.** +Aether Agent cyan-to-violet wordmark on a dark textured background [![CI](https://github.com/AetherAI3/aether-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/AetherAI3/aether-agent/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/aether-agents?label=npm)](https://www.npmjs.com/package/aether-agents) [![Node 24+](https://img.shields.io/badge/node-24%2B-14b8a6)](https://nodejs.org/) [![License](https://img.shields.io/badge/license-Apache--2.0-06b6d4)](LICENSE) -[Install](#install-the-right-version) · [Hosted or Ollama](#hosted-or-ollama) · [Workflow](#a-verified-coding-workflow) · [Handoffs](#continue-on-another-model-or-machine) · [Commands](#essential-commands) · [Security](#security-and-permissions) · [Develop](#development) +[Quickstart](#quickstart) · [Choose a model route](#choose-a-model-route) · [Why Aether](#why-aether-agent) · [Commands](#core-commands) · [Security](#security-and-local-authority) · [Docs](#documentation-and-support)
-Aether Agent is an open-source TypeScript CLI for coding, testing, review, and -handoff. Use Aether-hosted models when the required local-authority service -capability is available, or run through Ollama without an Aether account. The same -local host owns workspace tools, permissions, sessions, review, and verification. - -## Install the right version + -Use npm for the published CLI. The `main` source build is available for -contributors and for testing unreleased changes; both paths carry the 0.3 -workflow when the installed version is 0.3.0 or newer. +> **Requires 0.3.0 or newer.** Check the installed CLI with `aether --version`. -| Install | Version | What you get | -|---|---:|---| -| npm `latest` | [![npm latest](https://img.shields.io/npm/v/aether-agents?label=&color=14b8a6)](https://www.npmjs.com/package/aether-agents) | Published package; the badge tracks the live `latest` dist-tag. | -| `main` source build | **0.3.0** | The 0.3 coding, Ollama, session, review, and ship workflows below. | +## Quickstart -> **Confirm your version before following a version-labelled section.** Run -> `npm view aether-agents version` for the live `latest` dist-tag, and -> `aether --version` for what you actually have installed. Sections marked -> “source 0.3.0” require **0.3.0 or newer**. The -> [release record](docs/releases/2026-08-22.md) and -> [operator packet](docs/releases/OPERATOR-PACKET-v0.3.0.md) preserve the evidence. - -Install from npm: +From the repository you want Aether to work on: ```bash npm install -g aether-agents@latest --ignore-scripts -aether --version -``` - -The published 0.3.0 package includes every workflow below. Try the hosted basics: - -```bash aether auth login -aether models -aether chat "hello" +aether agent --test-cmd "npm test" "fix the failing test" ``` -Contributors who need unreleased changes can use the source-build instructions in -the next section. - - - -> **Requires 0.3.0 or newer**, from npm or from the source build below. +The third command gives Aether one task and one verification command. The local +host runs `npm test`; its real exit code determines whether the result is verified. -Node.js 24 or newer is required: +## Choose a model route -```bash -git clone https://github.com/AetherAI3/aether-agent.git -cd aether-agent -npm ci --ignore-scripts -npm run build -npm link -``` +Both routes keep workspace tools, permission decisions, session records, and +verification on the CLI host. The difference is where model inference runs. -## Hosted or Ollama +### Hosted Aether models -Both routes use the same local host for workspace confinement, permission prompts, -tool execution, session records, review, and final verification. Only the model -transport changes. - -### Hosted Aether +Sign in, then inspect the models available to your account: ```bash aether auth login aether models -aether agent --test-cmd "npm test" "fix the failing test" ``` -Hosted coding is capability- and account-dependent. The task and context you supply -are sent to the Aether API, but tools and verification execute in your checkout. If -the service cannot provide that local-authority protocol, the CLI refuses the run -instead of silently moving tool execution to the server. +Hosted runs send the task and context you provide to the Aether API. Repository +tools and verification still execute in your checkout. Hosted coding is account- +and capability-dependent; if the service cannot provide the required local- +authority protocol, the CLI refuses the run instead of silently moving tool +execution to the server. - -A dated, sanitized offline fallback snapshot is available as [HTML](docs/model-catalogue/index.html), [JSON](docs/model-catalogue/catalogue.json), and [Markdown](docs/generated/model-catalogue.md). It was generated at `2026-08-23T00:00:00.000Z` from Cloud public projection `model-catalogue-v1` with verified digest `sha256:80ba3ba1144d301e2cca407ceced74cb2b371f1da6e3982b87305ff12a3d4712`. Listed availability is not an account entitlement; use `aether models` while signed in. - - -### Ollama +### Local Ollama -Install [Ollama](https://ollama.com/), start its app or server, then select a model: +Install [Ollama](https://ollama.com/), start it, then prepare and select a model: ```bash aether setup --local @@ -105,82 +63,59 @@ aether local use qwen2.5-coder:7b --yes aether agent --local --test-cmd "npm test" "fix the failing test" ``` -This route requires no Aether account. By default it talks to Ollama on -`http://localhost:11434`; if you configure `OLLAMA_HOST`, requests go to that -endpoint. Pulls and configuration changes show a plan and require confirmation. +This route requires no Aether account. With Ollama on the default +`http://localhost:11434` endpoint, inference can stay on the machine after Ollama +and the model are downloaded. If `OLLAMA_HOST` points elsewhere, prompts go to +that configured endpoint. Network-capable tools remain separate, permissioned +actions. ## Why Aether Agent -- **Evidence, not confidence.** The host reruns the command supplied through - `--test-cmd`; its real exit code determines the verified result. Without one, the - run is recorded as unverified. -- **One workflow across model routes.** Switching between hosted and Ollama changes - the brain, not the host that owns tools, permissions, sessions, and verification. -- **Work that can move.** Export a bounded continuation record and resume it in - another checkout, on another machine, or with another model. -- **Review before publication.** Inspect the measured repository state and its - verification status before `aether ship` proposes a push and pull request. - -## A verified coding workflow - -```mermaid -flowchart LR - A[Task] --> B{Model route} - B -->|Hosted| C[Aether model] - B -->|Ollama| D[Configured Ollama model] - C --> E[Local host and permission gate] - D --> E - E --> F[Tools in your checkout] - F --> G[Your test command] - G --> H[Verified or unverified result] -``` - -```bash -aether agent --test-cmd "npm test" "fix the failing test" -aether review diff -``` - -The verification record is bound to the repository state. If the tree changes after -verification, review and ship report the evidence as stale instead of reusing an old -green result. `aether ship` prints the branch, commit, destination, and pull-request -plan before acting; `--yes` alone does not grant publication authority. - -## Continue on another model or machine - -```bash -aether resume export --out aether-handoff.json -aether agent --resume aether-handoff.json --model -``` - -A handoff is a bounded continuation record, not a transcript or repository copy. It -can include the task, prior model, verification result and command, repository -identity, touched paths, and summarized highlights. It omits file contents, shell -commands, absolute paths, and the full conversation. Review it before sharing: -bounded does not mean secret-free. - -## In the 0.3 source line +- **Terminal-first coding.** Start from the repository and keep the task, diff, + tests, and review in one command-line workflow. +- **Local and offline-capable inference.** Use a local Ollama endpoint without an + Aether account; after installation and model download, model inference does not + require the hosted Aether service. +- **Hosted frontier-model access.** Use the live model set exposed to your Aether + account when you want hosted inference. +- **Repository-aware tools.** File, search, shell, Git, session, and review tools + operate against the selected workspace rather than an unbounded machine view. +- **Verification loops.** Supply `--test-cmd` so completion is tied to a real + command and exit code; later repository changes make that evidence stale. +- **MCP support.** Inspect and diagnose configured MCP servers from the same CLI, + without bypassing tool permissions. +- **Operator-controlled execution.** Writes, shell commands, network access, Git + operations, and publication stay behind host-side authority checks. + +## Model stack + +The dated public snapshot marks Aether Neo, DeepSeek V4, GPT-5.4/5.5/5.6, and +Claude 4.5/4.8/5 text entries as available at the catalogue level. That is not an +account entitlement: **`aether models` is the authoritative live result for the +signed-in account.** Kimi K2.6/K3 and Gemma 4 are catalogued but marked +**unavailable** in the current snapshot, so they are not presented here as usable. + +Local Ollama availability is independent of that hosted catalogue and depends on +the models installed at the configured Ollama endpoint. -Coding runs, hosted and Ollama routing, verified completion, project sessions, -portable handoffs, review and ship, skills and capability reporting, doctor and -support bundles, MCP, workflows, previews, and media commands. - -Detailed inventories live in the generated -[command reference](docs/generated/commands.md) and -[model catalogue](docs/generated/model-catalogue.md). Hosted model visibility and -entitlement remain account- and service-dependent; `aether models` is authoritative -for the signed-in account. + +A dated, sanitized offline fallback snapshot is available as [HTML](docs/model-catalogue/index.html), [JSON](docs/model-catalogue/catalogue.json), and [Markdown](docs/generated/model-catalogue.md). It was generated at `2026-08-23T00:00:00.000Z` from Cloud public projection `model-catalogue-v1` with verified digest `sha256:80ba3ba1144d301e2cca407ceced74cb2b371f1da6e3982b87305ff12a3d4712`. Listed availability is not an account entitlement; use `aether models` while signed in. + -## Essential commands +## Core commands | Command | Purpose | |---|---| -| `aether agent [task]` | Start the coding agent or its REPL. | -| `aether agent --local [task]` | Use the configured Ollama endpoint. | -| `aether models` | Show models visible to the signed-in account. | -| `aether resume` | Replay a session or export a portable handoff. | -| `aether review` | Inspect changes and current verification status. | -| `aether ship` | Preview and approve branch and pull-request publication. | +| `aether auth login` | Sign in for hosted model access. | +| `aether agent [task]` | Run the coding agent or open its REPL. | +| `aether agent --local [task]` | Run through the configured Ollama endpoint. | +| `aether models` | Show the hosted models visible to the signed-in account. | +| `aether local doctor\|models\|use\|pull` | Diagnose and manage local Ollama. | +| `aether sessions` | Inspect and continue project-scoped sessions. | +| `aether review` | Inspect changes and current verification evidence. | +| `aether mcp` | List, diagnose, or repair configured MCP servers. | | `aether doctor` | Diagnose the configured environment. | +| `aether ship` | Preview and approve branch and pull-request publication. | Use `aether help ` or the generated [command reference](docs/generated/commands.md) for flags, slash commands, @@ -188,21 +123,64 @@ environment variables, and exit codes. -## Security and permissions +## Security and local authority - File tools are confined to the selected workspace. Write, shell, Git, network, - and publishing actions pass through host permission gates. -- Hosted tasks and supplied context are sent to the configured Aether API. The - local-authority coding route refuses incompatible server execution. -- Ollama requests are sent to the configured Ollama endpoint. Network-capable tools - remain separate, permissioned actions. -- Credentials and session records live outside the repository. Handoffs omit the - transcript and repository contents, but should still be reviewed before sharing. - -Read [SECURITY.md](SECURITY.md) for vulnerability reporting and supported versions. -Protocol and architecture contracts live under [`docs/`](docs/). Other Aether web -and desktop products are separate surfaces; this CLI does not claim cross-product -session continuation. + and publishing actions pass through host-side permission gates. +- Hosted tasks and supplied context are sent to the configured Aether API, while + repository tools and checks run locally. The local-authority coding route fails + closed when the server cannot honor that contract. +- Ollama prompts go to the configured Ollama endpoint. The default is loopback; + offline use also requires avoiding separately permissioned network tools. +- Credentials and session records live outside the repository. Portable handoffs + omit transcripts, file contents, shell commands, and absolute paths, but should + still be reviewed before sharing. +- `aether ship` prints its branch, commit, destination, and pull-request plan + before acting. `--yes` alone does not grant publication authority. + +Read [SECURITY.md](SECURITY.md) for supported versions, the security boundary, +and private vulnerability reporting. + +## Documentation and support + +- [Generated command reference](docs/generated/commands.md) and + [model catalogue](docs/generated/model-catalogue.md) +- [Protocol and architecture documentation](docs/) and + [production operations](docs/PRODUCTION_OPERATIONS.md) +- [Contributing guide](CONTRIBUTING.md) +- [GitHub issues](https://github.com/AetherAI3/aether-agent/issues) for bugs and + feature requests; use the private path in [SECURITY.md](SECURITY.md) for + vulnerabilities +- [Apache-2.0 license](LICENSE) and [Aether name/service notice](NOTICE.md) + +Other Aether web and desktop products are separate surfaces; this CLI does not +claim cross-product session continuation. + +## Release and source notes + +The repository and published package are versioned independently. Use the live +badge or `npm view aether-agents version` for the npm `latest` dist-tag, and +`aether --version` for the installed CLI. + +| Install | Version | What it represents | +|---|---:|---| +| npm `latest` | [![npm latest](https://img.shields.io/npm/v/aether-agents?label=&color=14b8a6)](https://www.npmjs.com/package/aether-agents) | Published package; the badge resolves the live dist-tag. | +| `main` source build | **0.3.0** | Current repository source and its 0.3 workflow. | + +The [release record](docs/releases/2026-08-22.md), +[release notes](RELEASE_NOTES.md), and +[operator packet](docs/releases/OPERATOR-PACKET-v0.3.0.md) preserve detailed +release and package evidence. + +For a source build, Node.js 24 or newer is required: + +```bash +git clone https://github.com/AetherAI3/aether-agent.git +cd aether-agent +npm ci --ignore-scripts +npm run build +npm link +``` ## Development @@ -217,9 +195,8 @@ npm run release:truth npm pack --dry-run ``` -See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. Security issues -follow [SECURITY.md](SECURITY.md), not the public issue tracker. The package has no -runtime dependencies; TypeScript and Node types are development-only. +See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. The package +has no runtime dependencies; TypeScript and Node types are development-only. Apache-2.0 — use it, fork it, and ship it. The license covers the code, not the Aether name or hosted service ([LICENSE](LICENSE) · [NOTICE.md](NOTICE.md)). diff --git a/package.json b/package.json index fa945314..6ca381bb 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "aether-agents", "version": "0.3.0", - "description": "Open-source terminal coding agent — runs on hosted frontier models (Claude, GPT, DeepSeek, Kimi, Gemma) or fully offline via Ollama. Edits your code, runs your tests, and verifies the result.", + "description": "Open-source terminal coding agent for hosted models or local Ollama, with repository-aware tools, operator-controlled execution, and verified results.", "type": "module", "bin": { "aether": "dist/src/main.js", @@ -48,24 +48,18 @@ "demo:handoff": "npm run build && node dist/scripts/handoff-demo.js" }, "keywords": [ - "aether", "coding-agent", - "coding-assistant", - "autonomous-agent", - "ai-agent", - "cli", - "llm", - "ai", - "terminal", - "agent", - "ollama", + "ai-coding-assistant", + "developer-tools", + "terminal-agent", + "local-first", "local-llm", - "offline-ai", - "claude", - "gpt", - "deepseek", - "neo", - "kronus" + "ollama", + "mcp", + "typescript", + "code-review", + "software-engineering", + "open-source" ], "license": "Apache-2.0", "author": "Brandon Barrante (Aether AI)",