aura-code 0.3.0

package/dist/orchestration/specialist-prompts.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REVIEWER_SYSTEM_PROMPT = exports.RESEARCHER_SYSTEM_PROMPT = void 0;
+exports.CODER_CONTEXT_TEMPLATE = CODER_CONTEXT_TEMPLATE;
+// ─────────────────────────────────────────────────────────────────────────────
+// Researcher system prompt
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * System prompt for the researcher specialist.
+ * The researcher is read-only: it gathers context, identifies patterns, and
+ * produces structured summaries. It must never write or modify files.
+ */
+exports.RESEARCHER_SYSTEM_PROMPT = `You are the Research specialist for Aura — a multi-agent coding system.
+
+## Your role
+You gather context, read code, and produce structured analysis. You have only
+read-only tools. You never create, edit, or delete files.
+
+## Your process
+1. READ everything relevant to the task — do not guess or assume.
+2. FOLLOW import chains and dependency graphs to understand relationships.
+3. IDENTIFY patterns, conventions, and constraints in the codebase.
+4. OUTPUT a structured summary in the exact format below.
+
+## Output format
+After you have gathered sufficient information, ouput ONLY the following
+structured summary. No markdown fences, no extra prose — just the raw sections:
+
+---
+KEY FILES FOUND
+- path/to/file.ts — brief description of what it contains and why it matters
+- path/to/another.ts — brief description
+...
+
+IMPORTANT PATTERNS
+- pattern description (e.g. "all middleware exports a factory function")
+...
+
+DEPENDENCIES DISCOVERED
+- file-a.ts depends on file-b.ts (via import of X)
+- external: package-name (used in N files)
+...
+
+RISKS IDENTIFIED
+- risk description (e.g. "auth.ts has no error boundaries on line 42")
+...
+
+---
+
+## Rules
+- NEVER write, edit, or delete files.
+- Always read files before reporting on them.
+- If a file is large, use line ranges to focus on the relevant sections.
+- Prefer search_code to find patterns across the codebase.
+- If you cannot find enough information, say so explicitly rather than guessing.
+- Keep your analysis focused on the task at hand — don't wander.
+- Spend at most 2 turns reading/gathering, then produce your summary.`;
+// ─────────────────────────────────────────────────────────────────────────────
+// Reviewer system prompt
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * System prompt for the reviewer specialist.
+ * The reviewer checks correctness, security, style, and test coverage. It is
+ * read-only and MUST output issues in a structured JSON format.
+ */
+exports.REVIEWER_SYSTEM_PROMPT = `You are the Review specialist for Aura — a multi-agent coding system.
+
+## Your role
+You review code changes for correctness, security, test coverage, and style
+consistency. You have only read-only tools. You never create, edit, or delete files.
+
+## Your process
+1. READ the files that were modified — check the diff with git_diff.
+2. READ related files that may be impacted.
+3. CHECK for:
+   - Correctness: logic errors, edge cases, off-by-one errors.
+   - Security: injection risks, leaked secrets, unsafe input handling.
+   - Test coverage: are new paths tested? Do existing tests still pass?
+   - Style consistency: does the change follow existing conventions?
+4. OUTPUT a structured issues list.
+
+## Output format
+After you have completed your review, output ONLY a valid JSON object:
+
+{
+  "issues": [
+    {
+      "severity": "critical" | "major" | "minor",
+      "description": "What the issue is",
+      "location": "file.ts:line-number"
+    }
+  ]
+}
+
+If you find no issues, output exactly:
+{ "issues": [] }
+and then clearly state: "No issues found."
+
+## Severity guide
+- critical — security vulnerability, data loss, or crash-on-start
+- major    — incorrect behaviour, missing error handling, broken test
+- minor    — style drift, missing comment, unnecessary verbosity
+
+## Rules
+- NEVER write, edit, or delete files.
+- Never approve code that introduces security vulnerabilities.
+- If you find a critical issue, state it first and be explicit about the risk.
+- Do not flag issues you cannot verify — if unsure, omit it rather than misattribute.
+- Each issue must include a specific file path and line number.`;
+// ─────────────────────────────────────────────────────────────────────────────
+// Coder context template
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Builds the context block injected into the coder's task description.
+ * Includes step-specific scope, relevant memory from prior steps, and an
+ * explicit instruction to stay focused on the assigned task.
+ */
+function CODER_CONTEXT_TEMPLATE(step, memory) {
+    const lines = [];
+    lines.push('## Step context');
+    lines.push(`Step id: ${step.id}`);
+    lines.push(`Scope: ${step.context}`);
+    if (memory.length > 0) {
+        lines.push('');
+        lines.push('## Relevant findings from previous steps');
+        for (const entry of memory) {
+            if (entry.stepId === step.id)
+                continue; // skip own output
+            // Only include memory entries that seem relevant — all entries are fair game
+            // since the orchestrator already filtered them.
+            lines.push(`[${entry.key}] ${entry.value.slice(0, 300)}`);
+        }
+    }
+    lines.push('');
+    lines.push('## Instructions');
+    lines.push('Only touch files relevant to this specific task. Do not refactor');
+    lines.push('unrelated code. Do not modify files from previous steps unless the');
+    lines.push('task explicitly requires it. After implementing, verify with run_tests.');
+    lines.push('');
+    lines.push(`Task: ${step.task}`);
+    return lines.join('\n');
+}
+//# sourceMappingURL=specialist-prompts.js.map

package/dist/orchestration/specialist-prompts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"specialist-prompts.js","sourceRoot":"","sources":["../../src/orchestration/specialist-prompts.ts"],"names":[],"mappings":";;;AAwHA,wDA8BC;AApJD,gFAAgF;AAChF,2BAA2B;AAC3B,gFAAgF;AAEhF;;;;GAIG;AACU,QAAA,wBAAwB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sEA4C8B,CAAC;AAEvE,gFAAgF;AAChF,yBAAyB;AACzB,gFAAgF;AAEhF;;;;GAIG;AACU,QAAA,sBAAsB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gEA2C0B,CAAC;AAEjE,gFAAgF;AAChF,yBAAyB;AACzB,gFAAgF;AAEhF;;;;GAIG;AACH,SAAgB,sBAAsB,CACpC,IAAc,EACd,MAA6B;IAE7B,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,KAAK,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;IAC9B,KAAK,CAAC,IAAI,CAAC,YAAY,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;IAClC,KAAK,CAAC,IAAI,CAAC,UAAU,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;IAErC,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,0CAA0C,CAAC,CAAC;QACvD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,IAAI,KAAK,CAAC,MAAM,KAAK,IAAI,CAAC,EAAE;gBAAE,SAAS,CAAC,kBAAkB;YAC1D,6EAA6E;YAC7E,gDAAgD;YAChD,KAAK,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,GAAG,KAAK,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;QAC5D,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;IAC9B,KAAK,CAAC,IAAI,CAAC,kEAAkE,CAAC,CAAC;IAC/E,KAAK,CAAC,IAAI,CAAC,oEAAoE,CAAC,CAAC;IACjF,KAAK,CAAC,IAAI,CAAC,yEAAyE,CAAC,CAAC;IACtF,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IAEjC,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/orchestration/specialists.d.ts

@@ -0,0 +1,66 @@
+import type { LLMProvider } from '../providers/types.js';
+import type { ProjectContext } from '../agent/context.js';
+import type { PlanStep, OrchestrationMemory } from './types.js';
+import type { ProjectPerception } from '../perception/types.js';
+import type { Display } from '../cli/display.js';
+/** Configuration passed to every specialist invocation. */
+export interface SpecialistOptions {
+    /** LLM provider used for this step. */
+    provider: LLMProvider;
+    /** Loaded project context. */
+    context: ProjectContext;
+    /** Optional perception snapshot for context-aware execution. */
+    perception?: ProjectPerception;
+    /** The plan step to execute. */
+    step: PlanStep;
+    /** Memory entries from previously completed steps. */
+    memory: OrchestrationMemory[];
+    /** Display interface for progress output. */
+    display: Display;
+    /** Optional abort signal for cancellation. */
+    signal?: AbortSignal;
+}
+/** Structured result returned by every specialist. */
+export interface SpecialistResult {
+    /** The specialist's output — research summary, review result, or implementation log. */
+    result: string;
+    /** Whether the step completed successfully. */
+    success: boolean;
+    /** Total tokens consumed (input + output). */
+    tokensUsed: number;
+    /** Wall-clock duration of the step in milliseconds. */
+    durationMs: number;
+    /** id of the PlanStep this result corresponds to. */
+    stepId: string;
+}
+/**
+ * Execute a research step.
+ * Runs within read-only permissions so the agent cannot create, edit, or
+ * delete files. The researcher system prompt is prepended to the task so
+ * the agent follows the structured output format.
+ */
+export declare function runResearcher(opts: SpecialistOptions): Promise<SpecialistResult>;
+/**
+ * Execute a review step.
+ * Runs within read-only permissions so the agent cannot create, edit, or
+ * delete files. The reviewer system prompt is prepended to the task so
+ * the agent follows the structured issues format.
+ */
+export declare function runReviewer(opts: SpecialistOptions): Promise<SpecialistResult>;
+/**
+ * Execute a coding step.
+ * The coder has full tool access (normal permissions). Step context and
+ * relevant memory are injected into the task description via
+ * `CODER_CONTEXT_TEMPLATE`.
+ */
+export declare function runCoder(opts: SpecialistOptions): Promise<SpecialistResult>;
+/**
+ * Dispatches to the correct specialist based on `step.specialist`.
+ * - `researcher` → runResearcher
+ * - `reviewer`   → runReviewer
+ * - `coder`      → runCoder
+ * - `planner`    → runResearcher (read-only planning, same constraints)
+ *
+ * Catches all errors and returns an error message as the result. Never throws.
+ */
+export declare function runSpecialist(opts: SpecialistOptions): Promise<SpecialistResult>;

package/dist/orchestration/specialists.js

@@ -0,0 +1,175 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runResearcher = runResearcher;
+exports.runReviewer = runReviewer;
+exports.runCoder = runCoder;
+exports.runSpecialist = runSpecialist;
+const loop_js_1 = require("../agent/loop.js");
+const permissions_js_1 = require("../safety/permissions.js");
+const specialist_prompts_js_1 = require("./specialist-prompts.js");
+const defaults_js_1 = require("../config/defaults.js");
+// ─────────────────────────────────────────────────────────────────────────────
+// runResearcher
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Execute a research step.
+ * Runs within read-only permissions so the agent cannot create, edit, or
+ * delete files. The researcher system prompt is prepended to the task so
+ * the agent follows the structured output format.
+ */
+async function runResearcher(opts) {
+    const start = Date.now();
+    const task = `${specialist_prompts_js_1.RESEARCHER_SYSTEM_PROMPT}\n\n---\n\n${buildTask(opts)}`;
+    try {
+        const result = await (0, loop_js_1.runAgentLoop)({
+            provider: opts.provider,
+            task,
+            context: opts.context,
+            permissions: new permissions_js_1.PermissionSystem('read-only'),
+            display: opts.display,
+            maxTurns: 10,
+            pricingModel: opts.provider.model,
+        });
+        return {
+            result: result.summary,
+            success: result.success,
+            tokensUsed: result.usage.totalTokens,
+            durationMs: Date.now() - start,
+            stepId: opts.step.id,
+        };
+    }
+    catch (e) {
+        return failResult(opts.step.id, `Research error: ${String(e)}`, Date.now() - start);
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// runReviewer
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Execute a review step.
+ * Runs within read-only permissions so the agent cannot create, edit, or
+ * delete files. The reviewer system prompt is prepended to the task so
+ * the agent follows the structured issues format.
+ */
+async function runReviewer(opts) {
+    const start = Date.now();
+    const task = `${specialist_prompts_js_1.REVIEWER_SYSTEM_PROMPT}\n\n---\n\n${buildTask(opts)}`;
+    try {
+        const result = await (0, loop_js_1.runAgentLoop)({
+            provider: opts.provider,
+            task,
+            context: opts.context,
+            permissions: new permissions_js_1.PermissionSystem('read-only'),
+            display: opts.display,
+            maxTurns: 10,
+            pricingModel: opts.provider.model,
+        });
+        return {
+            result: result.summary,
+            success: result.success,
+            tokensUsed: result.usage.totalTokens,
+            durationMs: Date.now() - start,
+            stepId: opts.step.id,
+        };
+    }
+    catch (e) {
+        return failResult(opts.step.id, `Review error: ${String(e)}`, Date.now() - start);
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// runCoder
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Execute a coding step.
+ * The coder has full tool access (normal permissions). Step context and
+ * relevant memory are injected into the task description via
+ * `CODER_CONTEXT_TEMPLATE`.
+ */
+async function runCoder(opts) {
+    const start = Date.now();
+    const task = (0, specialist_prompts_js_1.CODER_CONTEXT_TEMPLATE)(opts.step, opts.memory);
+    try {
+        const result = await (0, loop_js_1.runAgentLoop)({
+            provider: opts.provider,
+            task,
+            context: opts.context,
+            permissions: new permissions_js_1.PermissionSystem('normal'),
+            display: opts.display,
+            maxTurns: defaults_js_1.DEFAULTS.maxTurns,
+            pricingModel: opts.provider.model,
+        });
+        return {
+            result: result.summary,
+            success: result.success,
+            tokensUsed: result.usage.totalTokens,
+            durationMs: Date.now() - start,
+            stepId: opts.step.id,
+        };
+    }
+    catch (e) {
+        return failResult(opts.step.id, `Coder error: ${String(e)}`, Date.now() - start);
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// runSpecialist — dispatcher
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Dispatches to the correct specialist based on `step.specialist`.
+ * - `researcher` → runResearcher
+ * - `reviewer`   → runReviewer
+ * - `coder`      → runCoder
+ * - `planner`    → runResearcher (read-only planning, same constraints)
+ *
+ * Catches all errors and returns an error message as the result. Never throws.
+ */
+async function runSpecialist(opts) {
+    try {
+        switch (opts.step.specialist) {
+            case 'researcher':
+                return await runResearcher(opts);
+            case 'reviewer':
+                return await runReviewer(opts);
+            case 'coder':
+                return await runCoder(opts);
+            case 'planner':
+                return await runResearcher(opts);
+            default:
+                return failResult(opts.step.id, `Unknown specialist type: ${opts.step.specialist}`, 0);
+        }
+    }
+    catch (e) {
+        return failResult(opts.step.id, `Specialist error (${opts.step.specialist}): ${String(e)}`, 0);
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Internal helpers
+// ─────────────────────────────────────────────────────────────────────────────
+function buildTask(opts) {
+    const lines = [];
+    lines.push(`Task: ${opts.step.task}`);
+    if (opts.step.context) {
+        lines.push('');
+        lines.push('Context:');
+        lines.push(opts.step.context);
+    }
+    if (opts.memory.length > 0) {
+        lines.push('');
+        lines.push('Relevant findings from previous steps:');
+        for (const entry of opts.memory) {
+            if (entry.stepId === opts.step.id)
+                continue;
+            lines.push(`  [${entry.key}] ${entry.value.slice(0, 300)}`);
+        }
+    }
+    return lines.join('\n');
+}
+function failResult(stepId, message, durationMs) {
+    return {
+        result: message,
+        success: false,
+        tokensUsed: 0,
+        durationMs,
+        stepId,
+    };
+}
+//# sourceMappingURL=specialists.js.map

package/dist/orchestration/specialists.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"specialists.js","sourceRoot":"","sources":["../../src/orchestration/specialists.ts"],"names":[],"mappings":"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"}

package/dist/orchestration/types.d.ts

@@ -0,0 +1,82 @@
+/** A single unit of work assigned to one specialist agent. */
+export interface PlanStep {
+    /** Stable unique identifier for this step within the plan. */
+    id: string;
+    /**
+     * Which specialist role executes this step.
+     * - `researcher` — gathers context, reads files, queries perception graph
+     * - `coder`      — writes or modifies source files
+     * - `reviewer`   — validates correctness, style, and constraints
+     * - `planner`    — decomposes sub-goals when the original plan needs revision
+     */
+    specialist: 'researcher' | 'coder' | 'reviewer' | 'planner';
+    /** Human-readable description of what this step must accomplish. */
+    task: string;
+    /** Relevant background injected into the specialist's system prompt. */
+    context: string;
+    /** ids of steps that must reach `done` before this step may start. */
+    dependsOn: string[];
+    /** Output produced by the specialist once the step finishes. */
+    result?: string;
+    /**
+     * Lifecycle state of this step.
+     * - `waiting`  — blocked on `dependsOn`
+     * - `running`  — currently executing
+     * - `done`     — completed successfully
+     * - `failed`   — terminated with an error
+     * - `skipped`  — bypassed because a dependency failed
+     */
+    status: 'waiting' | 'running' | 'done' | 'failed' | 'skipped';
+    /** Total tokens consumed by the specialist during this step. */
+    tokensUsed?: number;
+    /** Wall-clock time the step took to complete, in milliseconds. */
+    durationMs?: number;
+}
+/** A decomposed, ordered work plan produced by the orchestrator for a goal. */
+export interface ExecutionPlan {
+    /** Unique identifier for this plan (used as the on-disk filename). */
+    id: string;
+    /** The original user goal that triggered plan creation. */
+    goal: string;
+    /** Ordered list of steps; may be executed concurrently where deps allow. */
+    steps: PlanStep[];
+    /**
+     * Lifecycle state of the overall plan.
+     * - `pending`  — created but not yet started
+     * - `running`  — at least one step is executing
+     * - `done`     — all steps reached `done`
+     * - `failed`   — a step failed and execution halted
+     * - `aborted`  — cancelled by the user or a safety guard
+     */
+    status: 'pending' | 'running' | 'done' | 'failed' | 'aborted';
+    /** Unix timestamp (ms) when this plan was created. */
+    created: number;
+    /** Unix timestamp (ms) when the plan reached a terminal state. */
+    completed?: number;
+    /** Aggregate token count across all steps. */
+    totalTokens?: number;
+    /** Final summary written by the orchestrator after all steps finish. */
+    outcome?: string;
+}
+/** A single key-value fact persisted to the project's orchestration memory. */
+export interface OrchestrationMemory {
+    /** Logical key used to retrieve this entry later (e.g. "auth_strategy"). */
+    key: string;
+    /** The remembered value — free-form string, may be serialised JSON. */
+    value: string;
+    /** id of the PlanStep that wrote this entry. */
+    stepId: string;
+    /** Unix timestamp (ms) when this entry was written. */
+    timestamp: number;
+}
+/** Output of the orchestrator's routing pass for an incoming goal. */
+export interface RouterDecision {
+    /** Whether the goal should be decomposed into a multi-step plan. */
+    shouldDecompose: boolean;
+    /** Explanation of why the router reached this decision. */
+    reason: string;
+    /** Router's confidence in the decision, in [0, 1]. */
+    confidence: number;
+    /** Rough number of steps the router expects the plan will contain. */
+    estimatedSteps?: number;
+}

package/dist/orchestration/types.js

@@ -0,0 +1,6 @@
+"use strict";
+// ─────────────────────────────────────────────────────────────────────────────
+// Execution plan steps
+// ─────────────────────────────────────────────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/orchestration/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/orchestration/types.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,uBAAuB;AACvB,gFAAgF"}

package/dist/perception/extractor.d.ts

@@ -0,0 +1,7 @@
+import type { ProjectPerception } from './types.js';
+/**
+ * Walk the project at `projectRoot` and build a full ProjectPerception snapshot.
+ * Reads the directory tree, parses imports and comments from every .ts/.js file,
+ * and extracts auxiliary information from README, CHANGELOG, config files, etc.
+ */
+export declare function extractPerception(projectRoot: string): Promise<ProjectPerception>;