@nairon-ai/aegis 0.2.0

package/docs/SETUP.md

@@ -0,0 +1,439 @@
+# Connect Aegis To A Project
+
+This guide is the exact path for using this repo to monitor bugs in another GitHub repo.
+
+## Mental Model
+
+You have two repos:
+
+- **Aegis repo:** the agent/control repo. You fork it and deploy it.
+- **Monitored repo:** the app repo Aegis fixes, like `acme/web-app`.
+
+Aegis stores state in the tracker you already use:
+
+- GitHub labels, issue comments, PR branches
+- Linear statuses/comments when Linear is connected
+
+No database is required for Aegis itself.
+
+## What You Need
+
+Required for local dry-run:
+
+- Bun
+- GitHub access to the monitored repo
+
+Required for cloud/AFK mode:
+
+- Cloudflare account
+- Workers Paid plan, because Cloudflare Sandbox/Containers run the coding sandboxes
+- Docker running locally during deploy
+- `wrangler` login
+- OpenAI API key or another Flue-supported model key
+
+Optional:
+
+- Linear API key if you use Linear as the bug tracker
+- Telegram bot if you want phone approvals
+- Read-only production database URL
+- Vercel token/project ID for logs
+
+## Step 1: Install Aegis In Your Product Repo
+
+```bash
+cd /path/to/your-product-repo
+npx @nairon-ai/aegis init
+```
+
+This creates:
+
+```text
+.aegis/.env.example
+.aegis/.gitignore
+.aegis/README.md
+```
+
+For local development before Aegis is published to npm, use the GitHub package:
+
+```bash
+npx github:Nairon-AI/aegis init
+```
+
+After npm publish, the intended install flow is:
+
+```bash
+npm install --save-dev @nairon-ai/aegis
+npx aegis init
+```
+
+## Step 2: Set Up Cloudflare
+
+Skip this step if you only want local dry-run.
+
+1. Create a Cloudflare account.
+2. Enable Workers Paid.
+3. Install/start Docker Desktop.
+4. Log in:
+
+```bash
+npx wrangler login
+npx wrangler whoami
+```
+
+If deploy fails with a container/Docker error, Docker is usually not running. If deploy fails with a plan/capability error, check the Cloudflare Workers plan.
+
+## Step 3: Give Aegis GitHub Access
+
+Pick one path.
+
+### Option A: GitHub Token
+
+Fastest first setup. Good for proving the repo works.
+
+Create a fine-grained personal access token:
+
+- Repository access: only the monitored repo
+- Contents: read/write
+- Issues: read/write
+- Pull requests: read/write
+- Metadata: read-only
+
+The token lets Aegis scan issues, create branches, push fixes, and open PRs.
+
+### Option B: GitHub App
+
+Better for teams and production use.
+
+Create a GitHub App with:
+
+- Contents: read/write
+- Issues: read/write
+- Pull requests: read/write
+- Metadata: read-only
+- Events: Issues, Issue comments
+
+Then:
+
+1. Generate a private key.
+2. Install the app on the monitored repo.
+3. Save the App ID.
+4. Save the Installation ID from the installation URL.
+5. Keep the private key `.pem` available for setup.
+
+If you do not know which one to pick, use a GitHub token first, then move to a GitHub App once the flow works.
+
+## Step 4: Run The Setup Wizard
+
+```bash
+npx @nairon-ai/aegis setup
+```
+
+Important answers:
+
+- `GitHub repo to monitor`: the app repo, for example `acme/web-app`
+- `Base branch`: usually `main`
+- GitHub auth: token or app credentials from Step 3
+- `GitHub webhook secret`: generate one and keep it in `.aegis/.env`
+- `Automation mode`: start with `plan-first`
+- `Context profile`: start with `minimal`
+- `OpenAI API key`: required for the default `openai/...` model
+
+This writes `.aegis/.env`. Do not commit it.
+
+Minimum useful `.aegis/.env`:
+
+```text
+MONITORED_REPO=acme/web-app
+BASE_BRANCH=main
+READY_LABEL=ready to implement
+BUG_LABEL=bug
+AUTOMATION_MODE=plan-first
+CONTEXT_PROFILE=minimal
+GITHUB_TOKEN=github_pat_...
+GITHUB_WEBHOOK_SECRET=...
+AGENT_MODEL=openai/gpt-5.1
+OPENAI_API_KEY=sk-...
+```
+
+## Step 5: Prepare The Monitored Repo
+
+In the monitored repo, create these labels:
+
+- `bug`
+- `ready to implement`
+
+Aegis creates its own labels when needed:
+
+- `aegis:in-progress`
+- `aegis:needs-info`
+- `aegis:blocked`
+- `aegis:pr-opened`
+
+If you use different label names, enter those names in setup.
+
+## Step 6: Create A Test Bug
+
+Create a GitHub issue in the monitored repo:
+
+```text
+Title: Bug: Checkout fails after applying a discount
+
+What happened:
+A customer applied a discount code and clicked Checkout. The page showed an error.
+
+What should have happened:
+Checkout should continue or show a clear validation message.
+
+Where:
+/checkout
+
+When:
+Around 2026-05-14 10:15 UTC
+
+Error/log:
+Paste the relevant log, provider link, stack trace, screenshot, or Linear context.
+
+Steps to reproduce:
+1. Add item to cart
+2. Apply discount code TEST10
+3. Click Checkout
+```
+
+Add both labels:
+
+- `bug`
+- `ready to implement`
+
+The issue must include enough context for a developer to start. If it does not, Aegis should ask one concrete follow-up question instead of starting a sandbox run.
+
+## Step 7: Dry-Run Pickup Locally
+
+```bash
+npx @nairon-ai/aegis pickup --dry-run
+```
+
+Good result:
+
+```text
+github:#123 would run - ready bug with enough context
+```
+
+Also acceptable:
+
+```text
+github:#123 needs info - missing reproduction steps
+```
+
+Bad result:
+
+```text
+No ready bugs found.
+```
+
+Usually means:
+
+- wrong `MONITORED_REPO`
+- labels do not match exactly
+- issue is closed
+- token/app is not installed on that repo
+- Linear/GitHub setup is pointing at the wrong team/project
+
+## Step 8: Deploy Aegis
+
+Make sure Docker is running, then:
+
+```bash
+npx @nairon-ai/aegis deploy
+```
+
+Deploy does four things:
+
+1. Pushes `.aegis/.env` values into Cloudflare secrets.
+2. Builds the Flue Worker.
+3. Deploys with Wrangler.
+4. Saves and pushes `AEGIS_WORKER_URL`.
+
+Expected result:
+
+```text
+Saved Worker URL: https://aegis-worker.YOUR_SUBDOMAIN.workers.dev
+```
+
+Health check:
+
+```bash
+curl https://aegis-worker.YOUR_SUBDOMAIN.workers.dev/
+```
+
+Manual pickup:
+
+```bash
+curl -X POST https://aegis-worker.YOUR_SUBDOMAIN.workers.dev/api/pickup
+```
+
+## Step 9: Add Webhooks
+
+Webhooks make Aegis react quickly. Cron still scans every 10 minutes.
+
+### GitHub Webhook
+
+If using a GitHub App, configure the app webhook.
+
+If using a token, create a repo webhook in the monitored repo:
+
+```text
+Payload URL: https://YOUR_WORKER.workers.dev/webhook/github
+Content type: application/json
+Secret: value from GITHUB_WEBHOOK_SECRET
+Events: Issues, Issue comments
+```
+
+What each event does:
+
+- `Issues`: triggers pickup when a bug is opened/labeled/edited/reopened.
+- `Issue comments`: handles `/aegis proceed`, `/aegis ask`, and `/aegis stop`.
+
+### Linear Webhook
+
+Only needed if Linear is connected.
+
+```text
+URL: https://YOUR_WORKER.workers.dev/webhook/linear
+Secret: value from LINEAR_WEBHOOK_SECRET
+Resource types: Issue, Comment
+```
+
+Configure Linear to match the setup wizard:
+
+- Team ID
+- Optional project ID
+- Ready status, default `Ready to Implement`
+- Bug label, default `bug`
+
+### Telegram Webhook
+
+Only needed if Telegram approvals are enabled.
+
+```bash
+curl "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setWebhook" \
+  -d "url=https://YOUR_WORKER.workers.dev/webhook/telegram" \
+  -d "secret_token=$TELEGRAM_WEBHOOK_SECRET"
+```
+
+Telegram commands:
+
+```text
+/aegis proceed <run-id>
+/aegis ask <run-id> <question>
+/aegis stop <run-id>
+```
+
+## Step 10: Expected First Real Run
+
+1. You label an issue `bug` + `ready to implement`.
+2. Aegis adds `aegis:in-progress`.
+3. Aegis comments with the run ID and branch name.
+4. Aegis starts a sandbox planning run.
+5. Aegis posts an RCA checkpoint in the issue.
+6. Telegram receives a short human summary if configured.
+7. You approve with `/aegis proceed <run-id>`.
+8. Aegis patches the branch, runs checks, pushes it, opens a PR, and comments the PR link.
+
+## Approval Rules
+
+Default mode is `plan-first`.
+
+Aegis does not patch until a human approves:
+
+```text
+/aegis proceed <run-id>
+```
+
+Ask for clarification:
+
+```text
+/aegis ask <run-id> Can you verify this only affects checkout?
+```
+
+Stop the run:
+
+```text
+/aegis stop <run-id>
+```
+
+## Production Context
+
+Start with `CONTEXT_PROFILE=minimal`.
+
+Use `production` only after the basic flow works:
+
+```text
+CONTEXT_PROFILE=production
+DATABASE_URL=postgres://readonly...
+VERCEL_TOKEN=...
+VERCEL_PROJECT_ID=...
+VERCEL_TEAM_ID=...
+```
+
+Rules:
+
+- DB user should be read-only.
+- Prefer a read replica.
+- Do not provide write credentials.
+- Paste provider links/errors into the issue whenever possible.
+
+## Troubleshooting
+
+`No ready bugs found.`
+
+- Check exact labels.
+- Check `MONITORED_REPO`.
+- Check the issue is open.
+- Check GitHub token/app repo access.
+- Check Linear team/project/status/label names.
+
+`GitHub 401/403.`
+
+- Token expired or missing permissions.
+- GitHub App not installed on monitored repo.
+- Installation ID is wrong.
+- Private key was not copied correctly.
+
+`Aegis claims but no plan appears.`
+
+- Check `AEGIS_WORKER_URL`.
+- Check `OPENAI_API_KEY`.
+- Check Cloudflare Worker logs.
+- Trigger `POST /api/pickup` once and inspect the response/logs.
+
+`Deploy fails before Worker URL prints.`
+
+- Run `bunx wrangler login`.
+- Run `bunx wrangler whoami`.
+- Start Docker.
+- Confirm Workers Paid is enabled.
+
+`GitHub comments do not approve runs.`
+
+- Confirm webhook URL is `/webhook/github`.
+- Confirm content type is `application/json`.
+- Confirm `GITHUB_WEBHOOK_SECRET` matches the webhook secret.
+- Confirm Issue comments event is enabled.
+
+`Telegram commands do nothing.`
+
+- Confirm `TELEGRAM_WEBHOOK_SECRET` exists in `.aegis/.env`.
+- Re-run the `setWebhook` command.
+- Confirm the chat ID is the same chat that receives Aegis messages.
+
+## Safe Defaults
+
+Recommended first config:
+
+```text
+AUTOMATION_MODE=plan-first
+CONTEXT_PROFILE=minimal
+MAX_CONCURRENT_RUNS=1
+```
+
+Increase concurrency only after the first few PRs are boring in the best way.

package/package.json

@@ -0,0 +1,64 @@
+{
+	"name": "@nairon-ai/aegis",
+	"version": "0.2.0",
+	"description": "Self-hosted AFK bug-fixing agent for GitHub Issues and Linear",
+	"type": "module",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/Nairon-AI/aegis.git"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"bin": {
+		"aegis": "dist-node/cli/index.js"
+	},
+	"files": [
+		".agents/skills/bug-fix",
+		".flue",
+		"dist-node",
+		"src",
+		"docs",
+		"Dockerfile",
+		"README.md",
+		"tsconfig.json",
+		"tsconfig.node.json",
+		"wrangler.jsonc"
+	],
+	"scripts": {
+		"aegis": "bun ./src/cli/index.ts",
+		"dev": "flue dev --target cloudflare --env .env.local",
+		"build": "flue build --target cloudflare",
+		"build:node": "tsc -p tsconfig.node.json && chmod +x dist-node/cli/index.js",
+		"deploy": "bun run build && wrangler deploy --config dist/wrangler.jsonc",
+		"prepack": "npm run build:node",
+		"release": "semantic-release",
+		"typecheck": "tsc --noEmit",
+		"check": "biome check .",
+		"check:fix": "biome check --write .",
+		"format": "biome format --write ."
+	},
+	"dependencies": {
+		"@cloudflare/sandbox": "0.10.1",
+		"@flue/cli": "0.5.3",
+		"@flue/sdk": "0.5.3",
+		"agents": "0.12.4",
+		"citty": "0.2.2",
+		"consola": "3.4.0",
+		"hono": "4.7.0",
+		"valibot": "1.4.0",
+		"wrangler": "4.90.1"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "1.9.0",
+		"@cloudflare/workers-types": "4.20260511.1",
+		"@semantic-release/commit-analyzer": "13.0.1",
+		"@semantic-release/github": "12.0.8",
+		"@semantic-release/npm": "13.1.5",
+		"@semantic-release/release-notes-generator": "14.1.1",
+		"bun-types": "1.3.13",
+		"semantic-release": "25.0.3",
+		"typescript": "5.9.3"
+	},
+	"license": "MIT"
+}

package/src/agent/bug-fix-skill.ts

@@ -0,0 +1,63 @@
+export const BUG_FIX_SKILL_TEXT = `---
+name: bug-fix
+description: Investigate a ready bug ticket, produce a non-technical approval summary, and after approval implement a minimal tested fix.
+---
+
+# Bug Fix
+
+You are Aegis, an AFK bug-fixing SRE. You only work on bug tickets. You do not implement features.
+
+Read the JSON context file passed in contextPath. It contains the command, source ticket, repo, branch, and optional production context.
+
+## Hard Rules
+
+- Do not push to main.
+- Do not open PRs yourself. Return PR title/body only.
+- Do not use git add -A or git add .
+- Do not include secrets in output.
+- If confidence is low, return blocked or needs-info.
+- Keep the fix minimal.
+- Run repo-native type checks for changed surfaces when possible.
+- Run the narrowest relevant test suite when possible.
+
+## Human Summary Style
+
+humanSummary is for Telegram. Keep it short, plain English, and skimmable on a phone.
+
+Prefer: what user did, what broke, why it likely broke at a high level, what Aegis wants to change, risk.
+
+Avoid: file paths, function names, column names, stack internals, and jargon unless unavoidable.
+
+## Plan Command
+
+When command is plan:
+
+1. Read the issue carefully.
+2. Inspect the codebase and nearest docs.
+3. If production profile is enabled, use only read-only checks.
+4. Determine whether there is enough context.
+5. Return awaiting-approval, needs-info, or blocked.
+
+Do not edit files during plan.
+
+## Implement Command
+
+When command is implement:
+
+1. Re-read the context and issue.
+2. Implement the smallest fix that addresses the root cause.
+3. Add or update regression coverage when practical.
+4. Run type checks and relevant tests.
+5. Stage only files you changed with explicit file paths.
+6. Commit to the current branch.
+7. Push the current branch to origin.
+8. Return PR title/body and evidence.
+
+If you cannot make a confident fix, return blocked or needs-info without committing.
+
+## PR Body
+
+Include summary, source ticket link, what changed, tests run, risk, and note that human review is required.
+
+Use Refs, not Closes, unless the context explicitly says otherwise.
+`;

package/src/agent/client.ts

@@ -0,0 +1,156 @@
+import { GitHubClient } from "../integrations/github.js";
+import { sendTelegramMessage } from "../integrations/telegram.js";
+import { formatIssuePlanComment, formatTelegramPlanMessage } from "../shared/format.js";
+import type {
+	AegisConfig,
+	AgentImplementationResult,
+	AgentPlanResult,
+	AgentRunContext,
+	ReadinessDecision,
+	WorkItem,
+	WorkRun,
+} from "../shared/types.js";
+import { sourceFor } from "../sources/index.js";
+
+export async function startPlanRun(params: {
+	config: AegisConfig;
+	item: WorkItem;
+	run: WorkRun;
+	decision: ReadinessDecision;
+}): Promise<void> {
+	const result = await callBugFixAgent<AgentPlanResult>(
+		params.config,
+		await buildAgentContext({
+			config: params.config,
+			item: params.item,
+			run: params.run,
+			command: "plan",
+		}),
+	);
+
+	const source = sourceFor(params.config, params.item.source);
+	if (result.outcome === "needs-info") {
+		await source.postNeedsInfo(params.item, result.question ?? result.humanSummary);
+		return;
+	}
+	if (result.outcome === "blocked") {
+		await source.markBlocked(params.item, result.blocker ?? result.technicalSummary);
+		return;
+	}
+
+	await source.postPlan(params.item, formatIssuePlanComment(params.run.id, result));
+	await sendTelegramMessage(
+		params.config,
+		formatTelegramPlanMessage(params.run.id, params.item, result),
+	);
+}
+
+export async function startImplementationRun(params: {
+	config: AegisConfig;
+	item: WorkItem;
+	run: WorkRun;
+	approvedBy: string;
+}): Promise<void> {
+	const context = await buildAgentContext({
+		config: params.config,
+		item: params.item,
+		run: params.run,
+		command: "implement",
+		approval: { approvedBy: params.approvedBy, approvedAt: new Date().toISOString() },
+	});
+	const result = await callBugFixAgent<AgentImplementationResult>(params.config, context);
+	const source = sourceFor(params.config, params.item.source);
+
+	if (result.outcome !== "implemented" || result.confidence === "low") {
+		await source.markBlocked(
+			params.item,
+			result.blocker ??
+				result.question ??
+				"Aegis found the bug but was not confident enough to open a PR.",
+		);
+		return;
+	}
+
+	const github = new GitHubClient(params.config);
+	const pr = await github.createPullRequest({
+		repo: params.item.repo,
+		title: result.prTitle ?? `fix: ${params.item.title}`,
+		body: result.prBody ?? buildFallbackPrBody(params.item, result),
+		head: params.run.branchName,
+		base: params.config.baseBranch,
+	});
+	await source.linkPullRequest(params.item, pr.url);
+	await sendTelegramMessage(
+		params.config,
+		`Aegis opened a PR for ${params.item.identifier}:\n${pr.url}`,
+	);
+}
+
+async function buildAgentContext(params: {
+	config: AegisConfig;
+	item: WorkItem;
+	run: WorkRun;
+	command: AgentRunContext["command"];
+	approval?: AgentRunContext["approval"];
+}): Promise<AgentRunContext> {
+	const github = new GitHubClient(params.config);
+	return {
+		runId: params.run.id,
+		command: params.command,
+		mode: params.run.mode,
+		contextProfile: params.config.contextProfile,
+		item: params.item,
+		branchName: params.run.branchName,
+		baseBranch: params.config.baseBranch,
+		repoCloneUrl: await github.getCloneUrl(params.item.repo),
+		production:
+			params.config.contextProfile === "production"
+				? {
+						databaseUrl: params.config.production?.databaseUrl,
+						vercelToken: params.config.production?.vercelToken,
+						vercelProjectId: params.config.production?.vercelProjectId,
+						vercelTeamId: params.config.production?.vercelTeamId,
+						logLookbackMinutes: params.config.production?.logLookbackMinutes ?? 45,
+					}
+				: undefined,
+		approval: params.approval,
+	};
+}
+
+async function callBugFixAgent<T>(config: AegisConfig, context: AgentRunContext): Promise<T> {
+	if (!config.workerUrl) {
+		throw new Error("AEGIS_WORKER_URL is required so the Worker can invoke its Flue agent");
+	}
+	const response = await fetch(`${config.workerUrl}/agents/bug-fix/${context.runId}`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify(context),
+	});
+	if (!response.ok) {
+		const text = await response.text();
+		throw new Error(`Bug-fix agent failed: ${response.status} ${text}`);
+	}
+	return (await response.json()) as T;
+}
+
+function buildFallbackPrBody(item: WorkItem, result: AgentImplementationResult): string {
+	return `## Summary
+${result.technicalSummary}
+
+## Human summary
+${result.humanSummary}
+
+## Source ticket
+Refs ${item.url}
+
+## Files changed
+${result.filesChanged.map((file) => `- \`${file}\``).join("\n") || "- See diff"}
+
+## Tests
+${result.testsRun.map((test) => `- ${test}`).join("\n") || "- Not reported"}
+
+## Risk
+${result.risk}
+
+Generated by Aegis. Human review required.`;
+}