@nairon-ai/aegis 0.2.0

package/.agents/skills/bug-fix/SKILL.md

@@ -0,0 +1,91 @@
+---
+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:
+
+- `command`: `plan` or `implement`
+- source ticket title/body/url
+- repo, branch, and context profile
+- optional read-only 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`; do not pretend.
+- Keep the fix minimal. This is bug repair, not refactor time.
+- 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. It must be 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
+- jargon
+
+Use low-level names only when they are the only unambiguous way to explain the problem.
+
+## 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. For a DB, inspect data only. For Vercel logs, use the provided token/project metadata and inspect around the issue timestamp when possible.
+4. Determine whether there is enough context.
+5. Return:
+   - `awaiting-approval` when likely root cause and fix are clear
+   - `needs-info` when one human answer is needed
+   - `blocked` when the bug cannot be safely diagnosed
+
+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
+- note that human review is required
+
+Use `Refs`, not `Closes`, unless the context explicitly says otherwise.

package/.flue/agents/bug-fix.ts

@@ -0,0 +1,107 @@
+import { getSandbox } from "@cloudflare/sandbox";
+import type { FlueContext } from "@flue/sdk/client";
+import { cfSandboxToSessionEnv } from "@flue/sdk/cloudflare";
+import * as v from "valibot";
+import { BUG_FIX_SKILL_TEXT } from "../../src/agent/bug-fix-skill.js";
+import {
+	AGENT_CONTEXT_PATH,
+	BUG_FIX_SKILL,
+	SANDBOX_REPO_PATH,
+} from "../../src/shared/constants.js";
+import type { AgentRunContext } from "../../src/shared/types.js";
+
+export const triggers = { webhook: true };
+
+const PlanSchema = v.object({
+	outcome: v.picklist(["awaiting-approval", "needs-info", "blocked"]),
+	confidence: v.picklist(["low", "medium", "high"]),
+	risk: v.picklist(["low", "medium", "high"]),
+	technicalSummary: v.string(),
+	humanSummary: v.string(),
+	proposedFix: v.string(),
+	question: v.optional(v.string()),
+	blocker: v.optional(v.string()),
+	requiresApproval: v.boolean(),
+});
+
+const ImplementationSchema = v.object({
+	outcome: v.picklist(["implemented", "blocked", "needs-info"]),
+	confidence: v.picklist(["low", "medium", "high"]),
+	risk: v.picklist(["low", "medium", "high"]),
+	technicalSummary: v.string(),
+	humanSummary: v.string(),
+	filesChanged: v.array(v.string()),
+	testsRun: v.array(v.string()),
+	branchName: v.optional(v.string()),
+	commitSha: v.optional(v.string()),
+	prTitle: v.optional(v.string()),
+	prBody: v.optional(v.string()),
+	question: v.optional(v.string()),
+	blocker: v.optional(v.string()),
+});
+
+export default async function ({ init, id, payload, env }: FlueContext) {
+	const context = payload as AgentRunContext;
+	const sandbox = getSandbox(env.Sandbox, id);
+	const sandboxFactory = {
+		createSessionEnv: async (options: { cwd?: string }) =>
+			cfSandboxToSessionEnv(sandbox, options.cwd),
+	};
+	const setupHarness = await init({
+		name: "setup",
+		sandbox: sandboxFactory,
+		model: env.AGENT_MODEL ?? "openai/gpt-5.1",
+	});
+	const setup = await setupHarness.session();
+
+	await setup.shell(`rm -rf ${SANDBOX_REPO_PATH}`);
+	await setup.shell(`git clone ${shellQuote(context.repoCloneUrl)} ${SANDBOX_REPO_PATH}`);
+	await setup.shell(`git checkout ${shellQuote(context.baseBranch)}`, { cwd: SANDBOX_REPO_PATH });
+	await setup.shell(`git checkout -B ${shellQuote(context.branchName)}`, {
+		cwd: SANDBOX_REPO_PATH,
+	});
+	await setup.shell(`mkdir -p $(dirname ${shellQuote(AGENT_CONTEXT_PATH)})`);
+	await setup.shell(
+		`cat > ${shellQuote(AGENT_CONTEXT_PATH)} <<'AEGIS_CONTEXT'\n${JSON.stringify(
+			context,
+			null,
+			2,
+		)}\nAEGIS_CONTEXT`,
+	);
+	const skillPath = `${SANDBOX_REPO_PATH}/.agents/skills/bug-fix/SKILL.md`;
+	const skillB64 = btoa(unescape(encodeURIComponent(BUG_FIX_SKILL_TEXT)));
+	await setup.shell(`mkdir -p ${shellQuote(`${SANDBOX_REPO_PATH}/.agents/skills/bug-fix`)}`);
+	await setup.shell(`echo ${shellQuote(skillB64)} | base64 -d > ${shellQuote(skillPath)}`);
+
+	const projectHarness = await init({
+		name: "project",
+		sandbox: sandboxFactory,
+		cwd: SANDBOX_REPO_PATH,
+		model: env.AGENT_MODEL ?? "openai/gpt-5.1",
+	});
+	const session = await projectHarness.session();
+
+	if (context.command === "plan") {
+		const { data } = await session.skill(BUG_FIX_SKILL, {
+			args: {
+				command: "plan",
+				contextPath: AGENT_CONTEXT_PATH,
+			},
+			schema: PlanSchema,
+		});
+		return data;
+	}
+
+	const { data } = await session.skill(BUG_FIX_SKILL, {
+		args: {
+			command: "implement",
+			contextPath: AGENT_CONTEXT_PATH,
+		},
+		schema: ImplementationSchema,
+	});
+	return data;
+}
+
+function shellQuote(value: string): string {
+	return `'${value.replace(/'/g, "'\\''")}'`;
+}

package/.flue/app.ts

@@ -0,0 +1,16 @@
+import { flue } from "@flue/sdk/app";
+import { createAegisApp, scheduledPickup } from "../src/server/app.js";
+import type { Bindings } from "../src/shared/types.js";
+
+const app = createAegisApp();
+const flueApp = flue();
+
+export default {
+	fetch(request: Request, env?: Bindings, ctx?: ExecutionContext) {
+		if (new URL(request.url).pathname.startsWith("/agents/")) {
+			return flueApp.fetch(request, env, ctx);
+		}
+		return app.fetch(request, env, ctx);
+	},
+	scheduled: scheduledPickup,
+};

package/Dockerfile

@@ -0,0 +1,8 @@
+FROM docker.io/cloudflare/sandbox:0.10.1
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+	git \
+	curl \
+	ca-certificates \
+	postgresql-client \
+	&& rm -rf /var/lib/apt/lists/*

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nairon AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,251 @@
+# Aegis
+
+Self-hosted AFK bug-fixing agent for GitHub Issues and Linear.
+
+Aegis watches bug tickets marked ready to implement, checks whether they have enough context, claims one safely, investigates in a Flue agent running inside Cloudflare Sandbox, posts a human-readable RCA checkpoint, waits for approval, then opens a PR. Human review stays in control.
+
+```text
+GitHub/Linear bug ticket marked ready
+        |
+        v
+Aegis readiness check
+        |
+        v
+Flue agent in Cloudflare Sandbox
+        |
+        v
+RCA checkpoint -> approve from GitHub/Linear or Telegram
+        |
+        v
+Minimal fix branch -> PR -> stop
+```
+
+## Start Here
+
+If you want to connect Aegis to another repo and monitor its bugs, follow [docs/SETUP.md](docs/SETUP.md).
+
+Short version:
+
+1. In your product repo, run `npx @nairon-ai/aegis init`.
+2. Create a Cloudflare account and use Workers Paid for deployed cloud mode.
+3. Log in with `npx wrangler login`.
+4. Create GitHub access for the repo Aegis should fix.
+5. Run `npx @nairon-ai/aegis setup`.
+6. Add `bug` and `ready to implement` labels to the monitored repo.
+7. Run `npx @nairon-ai/aegis pickup --dry-run`.
+8. Run `npx @nairon-ai/aegis deploy`.
+9. Add webhooks after deploy.
+
+## Two Repos
+
+Aegis is installed from npm/GitHub and configured inside the app repo.
+
+- **Aegis package:** this repo, installed through `npx` or as a dev dependency.
+- **Monitored repo:** the product repo Aegis fixes, for example `your-org/your-app`.
+- **Project config:** `.aegis/` in the monitored repo.
+
+`MONITORED_REPO=your-org/your-app` is the pointer between them.
+
+## Do I Need Cloudflare?
+
+- **Local dry-run:** no Cloudflare required. `npx @nairon-ai/aegis pickup --dry-run` only scans GitHub/Linear and prints decisions.
+- **Real AFK watcher:** yes. Aegis v1 deploys as a Cloudflare Worker and runs coding work in Cloudflare Sandbox/Containers.
+- **Database:** no. Aegis uses GitHub/Linear labels, statuses, comments, and PR branches as its state tracker.
+
+Cloudflare Sandbox is currently available on Workers Paid and uses Docker during deploy. See Cloudflare's [Sandbox overview](https://developers.cloudflare.com/sandbox/) and [getting started guide](https://developers.cloudflare.com/sandbox/get-started/).
+
+## What Aegis Does
+
+- Watches GitHub Issues and/or Linear issues.
+- Picks up bugs only.
+- Requires a ready signal plus a readiness check.
+- Uses Flue as the programmable agent harness.
+- Runs code work in Cloudflare Sandbox.
+- Uses GitHub/Linear as the tracker and durable state.
+- Optionally sends Telegram approval summaries.
+- Optionally gives the agent read-only DB access and Vercel logs.
+- Opens PRs, then stops. No auto-merge.
+
+## What Aegis Does Not Do
+
+- It does not host customer code or secrets for you.
+- It does not require a database.
+- It does not implement features in v1.
+- It does not write to production systems by default.
+- It does not self-heal PR review comments yet.
+- It does not require Sentry. Error providers should be linked or pasted into the issue.
+
+## Requirements
+
+- Bun
+- Docker running locally for Cloudflare Sandbox image deploy
+- Cloudflare account and Workers Paid for deployed mode
+- GitHub App or GitHub token with Contents, Issues, and Pull Requests read/write access
+- OpenAI API key or another Flue-supported model provider key
+- Optional: Linear API key
+- Optional: Telegram bot
+- Optional: read-only production database URL
+- Optional: Vercel API token/project ID for logs
+
+## Quick Start
+
+```bash
+cd your-product-repo
+npx @nairon-ai/aegis init
+npx @nairon-ai/aegis setup
+```
+
+Create a bug in the monitored repo with:
+
+- label: `bug`
+- label: `ready to implement`
+- enough context: what happened, what should have happened, where it happened, and an error/log excerpt if available
+
+Then run:
+
+```bash
+npx @nairon-ai/aegis pickup --dry-run
+```
+
+If that finds the issue, deploy:
+
+```bash
+npx wrangler login
+npx @nairon-ai/aegis deploy
+```
+
+Then configure webhooks using the Worker URL printed by deploy. Full details: [docs/SETUP.md](docs/SETUP.md).
+
+## How Pickup Works
+
+Aegis scans every 10 minutes and also reacts to GitHub/Linear webhooks.
+
+Manual cloud trigger:
+
+```bash
+curl -X POST https://YOUR_WORKER.workers.dev/api/pickup
+```
+
+For each ticket:
+
+1. Must be labeled/statused ready.
+2. Must be a bug.
+3. Must have enough context.
+4. Must not already have an active Aegis run.
+5. Aegis claims it.
+6. Aegis starts a Flue planning run.
+
+If context is too thin, Aegis comments with one concrete question and does not burn a sandbox run.
+
+## Approval Flow
+
+Aegis posts the full RCA to GitHub/Linear.
+
+Telegram gets a short non-technical summary:
+
+```text
+Aegis found a likely fix
+
+Bug: Users see an error after clicking Checkout
+
+Why: The app expects a related record to exist, but sometimes it is missing.
+
+Fix: Add a safe check and a regression test.
+Risk: Low
+
+Approve: /aegis proceed <run-id>
+Stop: /aegis stop <run-id>
+```
+
+Approve from GitHub/Linear or Telegram:
+
+```text
+/aegis proceed <run-id>
+```
+
+Cancel:
+
+```text
+/aegis stop <run-id>
+```
+
+Ask a follow-up or add context:
+
+```text
+/aegis ask <run-id> <question or extra detail>
+```
+
+Aegis reruns the planning checkpoint with that extra context.
+
+## Production Context
+
+Minimal mode uses only:
+
+- issue text
+- repo code
+
+Production mode can add:
+
+- read-only `DATABASE_URL`
+- Vercel logs around the issue time
+
+Use read-only production access. Do not give Aegis write access unless you have a tighter policy layer.
+
+## Commands
+
+```bash
+npx @nairon-ai/aegis init
+npx @nairon-ai/aegis setup
+npx @nairon-ai/aegis pickup --dry-run
+npx @nairon-ai/aegis status
+npx @nairon-ai/aegis deploy
+```
+
+## Releases
+
+Aegis uses semantic-release. Push conventional commits to `main`:
+
+- `fix:` -> patch npm release
+- `feat:` -> minor npm release
+- `feat!:` or `BREAKING CHANGE:` -> major npm release
+
+See [docs/RELEASING.md](docs/RELEASING.md).
+
+Worker endpoints:
+
+```text
+GET  /
+GET  /api/pickup
+POST /api/pickup
+POST /api/runs/:id/proceed
+POST /api/runs/:id/stop
+POST /webhook/github
+POST /webhook/linear
+POST /webhook/telegram
+POST /agents/bug-fix/:runId
+```
+
+## Architecture
+
+```text
+.flue/app.ts                    Worker app wrapper + Flue route
+.flue/agents/bug-fix.ts         Flue coding agent
+.agents/skills/bug-fix          Agent instructions
+src/server/app.ts               Hono routes, cron, webhooks
+src/core/pickup.ts              scan/claim orchestration
+src/sources/*                   GitHub + Linear source adapters
+src/integrations/*              GitHub, Linear, Telegram, webhook helpers
+src/shared/*                    config, types, readiness, formatting
+```
+
+## Current Limits
+
+- Bugs only.
+- PR self-heal is not implemented.
+- WhatsApp is not implemented.
+- Arbitrary third-party tool connectors are not implemented.
+- Cloudflare Sandbox is the primary runtime; freestyle.sh support was removed.
+
+## License
+
+MIT

package/dist-node/agent/bug-fix-skill.d.ts

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

package/dist-node/agent/bug-fix-skill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bug-fix-skill.d.ts","sourceRoot":"","sources":["../../src/agent/bug-fix-skill.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,kBAAkB,kmEA8D9B,CAAC"}

package/dist-node/agent/bug-fix-skill.js

@@ -0,0 +1,64 @@
+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.
+`;
+//# sourceMappingURL=bug-fix-skill.js.map

package/dist-node/agent/bug-fix-skill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bug-fix-skill.js","sourceRoot":"","sources":["../../src/agent/bug-fix-skill.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,kBAAkB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8DjC,CAAC"}

package/dist-node/agent/client.d.ts

@@ -0,0 +1,14 @@
+import type { AegisConfig, ReadinessDecision, WorkItem, WorkRun } from "../shared/types.js";
+export declare function startPlanRun(params: {
+    config: AegisConfig;
+    item: WorkItem;
+    run: WorkRun;
+    decision: ReadinessDecision;
+}): Promise<void>;
+export declare function startImplementationRun(params: {
+    config: AegisConfig;
+    item: WorkItem;
+    run: WorkRun;
+    approvedBy: string;
+}): Promise<void>;
+//# sourceMappingURL=client.d.ts.map

package/dist-node/agent/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/agent/client.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACX,WAAW,EAIX,iBAAiB,EACjB,QAAQ,EACR,OAAO,EACP,MAAM,oBAAoB,CAAC;AAG5B,wBAAsB,YAAY,CAAC,MAAM,EAAE;IAC1C,MAAM,EAAE,WAAW,CAAC;IACpB,IAAI,EAAE,QAAQ,CAAC;IACf,GAAG,EAAE,OAAO,CAAC;IACb,QAAQ,EAAE,iBAAiB,CAAC;CAC5B,GAAG,OAAO,CAAC,IAAI,CAAC,CA0BhB;AAED,wBAAsB,sBAAsB,CAAC,MAAM,EAAE;IACpD,MAAM,EAAE,WAAW,CAAC;IACpB,IAAI,EAAE,QAAQ,CAAC;IACf,GAAG,EAAE,OAAO,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkChB"}