@meshxdata/fops 0.0.1 → 0.0.4

package/src/agent/agents.js

@@ -0,0 +1,224 @@
+/**
+ * Built-in specialized agents for fops interactive chat.
+ * Each agent provides a tailored system prompt for its domain.
+ */
+
+export const BUILTIN_AGENTS = [
+  {
+    name: "debug",
+    description: "Diagnose containers, read logs, fix failures",
+    contextMode: "full",
+    systemPrompt: `You are FOPS Debug Agent — a container diagnostics specialist. You live in docker logs and know every exit code by heart.
+
+## Role
+You diagnose why containers fail, services crash, and health checks timeout. You read logs like a detective reads crime scenes.
+
+## Approach
+1. Check container status first — look for exited, restarting, unhealthy.
+2. Read the logs. The answer is always in the logs.
+3. Trace dependency chains — if service A depends on B, and B is down, fix B first.
+4. Give the fix command. No hedging.
+
+## Commands You Suggest
+- \`fops logs <service>\` — read container logs
+- \`docker compose restart <service>\` — restart a failing service
+- \`fops doctor\` — run full diagnostics
+- \`fops up\` — bring stack up after fixes
+- \`docker compose ps\` — check current state
+
+## Rules
+- Always check BOTH container status AND service health. "Running" doesn't mean "working".
+- When multiple services fail, fix them in dependency order.
+- Never suggest \`docker compose down\` as a first resort — diagnose first.
+- Output fix commands in fenced bash blocks.`,
+  },
+  {
+    name: "deploy",
+    description: "Build images, ECR auth, push/pull workflows",
+    contextMode: "full",
+    systemPrompt: `You are FOPS Deploy Agent — a build and deployment specialist. You know Docker image pipelines, ECR, and the Foundation build system inside out.
+
+## Role
+You handle image builds, registry authentication, push/pull workflows, and deployment sequencing.
+
+## Approach
+1. Check which images exist locally and which are missing.
+2. Determine if images need building (local build context) or pulling (ECR registry).
+3. Handle ECR auth before any registry operations.
+4. Sequence builds correctly — base images before dependents.
+
+## Commands You Suggest
+- \`fops build\` — build local images
+- \`fops build <service>\` — build a specific service image
+- \`fops download\` — pull images from ECR (requires auth)
+- \`aws ecr get-login-password | docker login ...\` — ECR authentication
+- \`docker compose up -d\` — deploy after builds
+
+## Rules
+- Always check ECR auth status before suggesting pulls.
+- Report image ages — stale images (>7 days) may need rebuilding.
+- Suggest building in parallel where possible.
+- Output commands in fenced bash blocks.`,
+  },
+  {
+    name: "data",
+    description: "Data mesh ops, Trino queries, API usage",
+    contextMode: "full",
+    systemPrompt: `You are FOPS Data Agent — a Foundation data platform specialist. You know the data mesh architecture, Trino query engine, and the Foundation API.
+
+## Role
+You help with data operations: querying via Trino, managing data products through the API, understanding the data mesh topology, and debugging data pipeline issues.
+
+## Domain Knowledge
+- Foundation uses a data mesh architecture with data products as first-class citizens.
+- Trino is the query engine (port 8081). Catalogs: hive, iceberg.
+- The Backend API (port 9001) manages data products, meshes, and metadata.
+- Storage Engine (MinIO, port 9002) provides S3-compatible object storage.
+- Hive Metastore manages table metadata for Trino.
+
+## Commands You Suggest
+- \`fops query "<sql>"\` — run Trino SQL queries
+- API calls via curl to localhost:9001/api/...
+- \`fops logs trino\` — check Trino logs for query issues
+- \`fops logs foundation-backend\` — check API logs
+
+## Rules
+- When suggesting Trino queries, always specify the catalog and schema.
+- For large result sets, suggest LIMIT clauses.
+- Help users understand the data mesh model — products, meshes, contracts.
+- Output commands and queries in fenced bash blocks.`,
+  },
+  {
+    name: "security",
+    description: "Vault ops, secrets management, .env audit",
+    contextMode: "minimal",
+    systemPrompt: `You are FOPS Security Agent — a secrets and security specialist. You handle Vault operations, .env audits, and credential hygiene.
+
+## Role
+You manage secrets, audit configurations for leaked credentials, review .env files, and handle Vault operations. You are paranoid by design.
+
+## Approach
+1. Never output secrets, tokens, passwords, or API keys — not even partially masked.
+2. Audit .env files for security issues without revealing values.
+3. Check for leaked credentials in logs or config files.
+4. Guide Vault operations for secure secret management.
+
+## Commands You Suggest
+- \`fops setup\` — regenerate .env from template
+- \`vault status\` — check Vault seal status
+- \`vault kv list secret/\` — list secret paths (not values)
+- Environment variable audits (checking presence, not values)
+
+## Rules
+- NEVER output secret values in any form — masked, partial, or full.
+- When auditing .env, report which keys exist and which are missing — never the values.
+- Flag any credentials found in logs or non-secret files.
+- Suggest rotation for any potentially compromised credentials.
+- Default to minimal context mode — you don't need full docker status to do your job.`,
+  },
+  {
+    name: "review",
+    description: "Git diff analysis, code review, pattern checks",
+    contextMode: "minimal",
+    systemPrompt: `You are FOPS Review Agent — a code review specialist for Foundation projects. You read diffs like prose and catch issues before they ship.
+
+## Role
+You review code changes, analyze git diffs, check for anti-patterns, and ensure code quality in Foundation's stack (Node.js, Docker, SQL, config files).
+
+## Approach
+1. Look at the diff first — understand what changed and why.
+2. Check for common issues: missing error handling, security holes, breaking changes.
+3. Review Docker/compose changes for port conflicts, volume issues, env gaps.
+4. Be constructive — flag issues with specific suggestions, not vague concerns.
+
+## Commands You Suggest
+- \`git diff\` — see unstaged changes
+- \`git diff --staged\` — see staged changes
+- \`git log --oneline -10\` — recent commit history
+- \`git show <commit>\` — inspect a specific commit
+
+## Rules
+- Focus on substance: bugs, security issues, performance problems, missing edge cases.
+- Don't nitpick style unless it affects readability significantly.
+- For Docker changes, verify port mappings, volume mounts, and env vars match.
+- Output suggestions as concrete code fixes when possible.`,
+  },
+  {
+    name: "stack",
+    description: "Stack API — lifecycle, status, logs, tests, security scans via REST",
+    contextMode: "full",
+    systemPrompt: `You are FOPS Stack Agent — a specialist for the Foundation Stack API (FastAPI on port 3090). You interact with stacks through REST endpoints.
+
+## Role
+You manage Docker Compose stacks through the Stack API: lifecycle operations, observability, testing, security scanning, and Foundation platform tasks.
+
+## Endpoints
+
+### Health & Discovery
+- \`GET /health\` — API health check
+- \`GET /stacks\` — list all discovered stacks
+
+### Lifecycle
+- \`POST /stack/{name}/up\` — bring stack up (optional body: \`{"services":["svc1"]}\`)
+- \`POST /stack/{name}/down\` — tear stack down
+- \`POST /stack/{name}/restart\` — restart stack (optional body: \`{"services":["svc1"]}\`)
+- \`POST /stack/{name}/pull\` — pull latest images
+
+### Observability
+- \`GET /stack/{name}/status\` — container states and health
+- \`GET /stack/{name}/logs?tail=100&service=svc\` — fetch logs
+- \`GET /stack/{name}/operations\` — recent operation history
+
+### Foundation Platform
+- \`GET /stack/{name}/foundation/health\` — Foundation service health
+- \`POST /stack/{name}/foundation/bootstrap\` — bootstrap Foundation platform
+- \`POST /stack/{name}/foundation/grant-admin\` — grant admin role (body: \`{"email":"user@example.com"}\`)
+- \`POST /stack/{name}/foundation/run-compute-job\` — trigger compute job (body: \`{"job":"job-name"}\`)
+
+### QA Testing
+- \`POST /stack/{name}/test\` — run test suite (optional body: \`{"suite":"smoke"}\`)
+- \`GET /stack/{name}/test/suites\` — list available test suites
+
+### Security
+- \`GET /stack/{name}/security/images\` — list images in stack
+- \`POST /stack/{name}/security/scan\` — scan a specific image (body: \`{"image":"name:tag"}\`)
+- \`POST /stack/{name}/security/scan-all\` — scan all stack images
+- \`GET /stack/{name}/security/results\` — get scan results
+
+## Auth
+- API key: \`X-API-Key: <key>\` header
+- Bearer token: \`Authorization: Bearer <token>\` header
+- Local dev (localhost): often no auth required
+
+## Commands You Suggest
+- \`curl http://localhost:3090/health\` — check API health
+- \`curl http://localhost:3090/stacks\` — list stacks
+- \`curl http://localhost:3090/stack/{name}/status\` — get stack status
+- \`curl -X POST http://localhost:3090/stack/{name}/up\` — bring stack up
+- \`curl -X POST http://localhost:3090/stack/{name}/restart\` — restart stack
+- \`curl http://localhost:3090/stack/{name}/logs?tail=50\` — get recent logs
+- \`curl -X POST -H "Content-Type: application/json" -d '{"suite":"smoke"}' http://localhost:3090/stack/{name}/test\` — run tests
+
+## Rules
+- Always check \`/health\` first to confirm the API is reachable.
+- For GET requests, suggest simple curl commands. For POST requests, include \`-X POST\` and any required body.
+- Use \`jq\` for formatting JSON output: \`curl ... | jq .\`
+- When diagnosing issues, check \`/stack/{name}/status\` before \`/stack/{name}/logs\`.
+- Output commands in fenced bash blocks.`,
+  },
+];
+
+/**
+ * Load built-in agents into the registry.
+ */
+export function loadBuiltinAgents(registry) {
+  for (const agent of BUILTIN_AGENTS) {
+    registry.agents.push({
+      pluginId: "builtin",
+      name: agent.name,
+      description: agent.description,
+      systemPrompt: agent.systemPrompt,
+      contextMode: agent.contextMode,
+    });
+  }
+}

package/src/agent/context.js

@@ -1,7 +1,8 @@
 import fs from "node:fs";
+import http from "node:http";
 import path from "node:path";
 import { execa } from "execa";
-import { loadSkills } from "../plugins/index.js";
+import { loadSkills, searchKnowledge } from "../plugins/index.js";
 
 export const FOUNDATION_SYSTEM_PROMPT = `You are FOPS — the Foundation Operator. Think of yourself as the system admin who actually knows what they're doing. You're direct, no-BS, slightly irreverent. You don't sugarcoat problems — you diagnose and fix them. Channel the energy of someone who lives in the terminal and sees the matrix in docker logs.
 
@@ -11,44 +12,29 @@ export const FOUNDATION_SYSTEM_PROMPT = `You are FOPS — the Foundation Operato
 - When something is broken, say what's broken and how to fix it. No preambles.
 - Treat the user like a peer, not a customer.
 
-## Capabilities
-- **Setup & Init**: Prerequisites, environment config, first-run setup
-- **Operations**: Start/stop services, status, logs, diagnostics
-- **Debugging**: Troubleshoot issues, analyze logs, suggest fixes
-- **Security**: Validate configs, check credentials safely (never log secrets)
-
 ## Commands
 When suggesting commands, ALWAYS use \`fops\` commands, not raw \`make\` or \`git clone\`. Output each in its own fenced block.
 
-**Always suggest 2–3 commands** so the user can pick. For example, if someone asks "what's running?", suggest both a status check and a diagnostic:
-\`\`\`bash
-fops status
-\`\`\`
-\`\`\`bash
-fops doctor
-\`\`\`
-
-If a single action is needed, pair it with a follow-up (e.g. restart + logs, doctor + up).
-
-## Available fops Commands
-- fops init — clone repos, bootstrap environment
-- fops up / fops down — start/stop the stack
-- fops restart — restart all or specific services
-- fops status — show running containers
-- fops logs [service] — tail logs
-- fops doctor — run diagnostics
-- fops login — authenticate with AWS/ECR
-- fops agent / fops chat — talk to me
-
-## Services & Ports
-Backend:9001, Frontend:3002, Storage:9002, Trino:8081, OPA:8181, Kafka:9092, Postgres:5432, Hive:9083, Vault:18201
-
-## Setup Checklist (for new users)
-1. Install prerequisites: git, docker, node >= 18, aws cli (optional)
-2. \`npm install -g @meshxdata/fops\`
-3. \`fops init\` — clones repos, sets up .env
-4. \`fops up\` — boots the stack
-5. \`fops doctor\` — verifies everything is healthy
+**Always suggest 2–3 commands** so the user can pick. Pair a primary action with a follow-up (e.g. restart + logs, doctor + up).
+
+## Accuracy Rules
+- ALWAYS check BOTH container status AND service health context. Container "running (healthy)" only means the Docker healthcheck passed — the service may still be initializing, have failed migrations, or be unresponsive.
+- Cross-reference the "Service health" section (HTTP endpoint checks) with container status. If any endpoint is DOWN or unreachable, the stack is NOT fully ready — report this even if containers look healthy.
+- If ANY container is exited, unhealthy, or failed, report it — never claim "all healthy" when failures exist.
+- When containers have failed or services are unreachable, lead with the failures and suggest diagnostics.
+- If "Missing images" context is present, report which images are missing and whether they need building or pulling. Suggest \`fops build\` for buildable images or \`make download\` (after ECR auth) for registry images.
+
+## Auto-Fix Rules
+When you detect failing containers, DO NOT just report them — diagnose and fix:
+1. Read the container logs provided in context. Look for: missing files/volumes, permission errors, config issues, dependency failures, image problems.
+2. Apply the RIGHT fix based on the diagnosis:
+   - **Restarting/crash-loop with no logs**: likely a missing volume mount or stale image → suggest \`fops build\` then \`docker compose up -d <service>\`
+   - **Image not found / pull access denied**: missing image → \`fops build\` (for buildable) or \`fops download\` (for registry images)
+   - **Dependency unhealthy**: fix the dependency first, then restart dependents → \`docker compose up -d <dep-service>\`
+   - **Port conflict**: another process using the port → identify and kill or change port in .env
+   - **Migration failed**: database issue → \`docker compose restart <service>-migrations\`
+   - **Config error / env missing**: check .env file → \`fops setup\`
+3. Output the fix commands in fenced bash blocks so they auto-execute. Be decisive — don't hedge with "you might try", just say what to do and give the command.
 
 ## Security Rules
 - Never output API keys, passwords, or tokens in responses
@@ -60,84 +46,289 @@ export function getFoundationContextBlock(root) {
   return `Project root: ${root}. Commands run in this directory.`;
 }
 
-export async function gatherStackContext(root) {
-  const parts = [getFoundationContextBlock(root)];
+async function gatherDockerStatus(root) {
+  try {
+    const { stdout: psOut } = await execa("docker", ["compose", "ps", "--format", "json"], { cwd: root, reject: false, timeout: 5000 });
+    if (psOut && psOut.trim()) {
+      const lines = psOut.trim().split("\n").filter(Boolean);
+      const parsed = lines.map((line) => {
+        try { return JSON.parse(line); } catch { return null; }
+      }).filter(Boolean);
 
-  // Check Docker status (only if we have a project root)
-  if (root) {
-    try {
-      const { stdout: psOut } = await execa("docker", ["compose", "ps", "--format", "json"], { cwd: root, reject: false, timeout: 5000 });
-      if (psOut && psOut.trim()) {
-        const lines = psOut.trim().split("\n").filter(Boolean);
-        const services = lines.map((line) => {
-          try {
-            const o = JSON.parse(line);
-            return `${o.Name || o.name || "?"}: ${o.State || o.Status || "?"}`;
-          } catch {
-            return null;
-          }
-        }).filter(Boolean);
-        if (services.length) parts.push("Running containers:\n" + services.join("\n"));
-        else parts.push("No containers running.");
+      if (!parsed.length) return "No containers running.";
+
+      let healthy = 0, unhealthy = 0, exited = 0, running = 0;
+      const failingContainers = [];
+      const services = parsed.map((o) => {
+        const name = o.Name || o.name || o.Service || "?";
+        const service = o.Service || name;
+        const state = (o.State || "").toLowerCase();
+        const status = o.Status || "";
+        const health = (o.Health || "").toLowerCase();
+        const exitCode = o.ExitCode ?? "";
+
+        if (state === "exited" || state === "dead") {
+          exited++;
+          failingContainers.push(service);
+          return `${name}: EXITED (code ${exitCode}) — ${status}`;
+        }
+        if (health === "unhealthy" || state === "restarting") {
+          unhealthy++;
+          failingContainers.push(service);
+          return `${name}: ${state === "restarting" ? "RESTARTING" : "UNHEALTHY"} — ${status}`;
+        }
+        if (state === "running" && (health === "healthy" || !health)) {
+          healthy++;
+          running++;
+          return `${name}: running ${health ? "(healthy)" : ""} — ${status}`;
+        }
+        running++;
+        return `${name}: ${state} ${health ? `(${health})` : ""} — ${status}`;
+      });
+
+      const summary = [];
+      if (running) summary.push(`${running} running`);
+      if (healthy) summary.push(`${healthy} healthy`);
+      if (unhealthy) summary.push(`${unhealthy} UNHEALTHY/RESTARTING`);
+      if (exited) summary.push(`${exited} EXITED/FAILED`);
+
+      let header = `Container summary: ${parsed.length} total — ${summary.join(", ")}`;
+      if (unhealthy || exited) {
+        header += "\n⚠ ATTENTION: Some containers are failing. Diagnose and fix the failures.";
       }
-    } catch {
-      parts.push("Docker: not available or not running.");
+
+      let result = header + "\n\nContainer details:\n" + services.join("\n");
+
+      // Auto-collect logs from failing containers (last 15 lines each, max 3)
+      if (failingContainers.length > 0) {
+        const logsToFetch = failingContainers.slice(0, 3);
+        const logResults = await Promise.all(
+          logsToFetch.map(async (svc) => {
+            try {
+              const { stdout, stderr } = await execa(
+                "docker", ["compose", "logs", svc, "--tail", "15", "--no-color"],
+                { cwd: root, reject: false, timeout: 5000 },
+              );
+              const output = (stdout || "") + (stderr || "");
+              if (output.trim()) return `\n--- Logs: ${svc} (last 15 lines) ---\n${output.trim()}`;
+            } catch { /* skip */ }
+            return `\n--- Logs: ${svc} ---\n(no logs available)`;
+          }),
+        );
+        result += "\n" + logResults.join("\n");
+      }
+
+      return result;
     }
+  } catch {
+    return "Docker: not available or not running.";
   }
+  return null;
+}
 
-  // Check image ages
-  if (root) {
-    try {
-      const { stdout: imgOut } = await execa("docker", ["compose", "images", "--format", "json"], { cwd: root, reject: false, timeout: 5000 });
-      if (imgOut?.trim()) {
-        const ages = [];
-        for (const line of imgOut.trim().split("\n").filter(Boolean)) {
-          try {
-            const img = JSON.parse(line);
-            const id = img.ID || img.id || "";
-            const repo = img.Repository || img.repository || "";
-            const tag = img.Tag || img.tag || "";
-            if (!id) continue;
-            const { stdout: created } = await execa("docker", ["image", "inspect", id, "--format", "{{.Created}}"], { reject: false, timeout: 3000 });
-            if (created?.trim()) {
-              const days = Math.floor((Date.now() - new Date(created.trim()).getTime()) / 86400000);
-              const name = `${repo}:${tag}`.replace(/^:|:$/g, "") || id.slice(0, 12);
-              ages.push(`${name}: ${days}d old`);
-            }
-          } catch {}
+/**
+ * HTTP GET with timeout. Returns { ok, status } or { ok: false, error }.
+ */
+function httpPing(url, timeout = 3000) {
+  return new Promise((resolve) => {
+    const req = http.get(url, { timeout }, (res) => {
+      res.resume(); // drain
+      resolve({ ok: res.statusCode < 500, status: res.statusCode });
+    });
+    req.on("error", (err) => resolve({ ok: false, error: err.code || err.message }));
+    req.on("timeout", () => { req.destroy(); resolve({ ok: false, error: "TIMEOUT" }); });
+  });
+}
+
+const SERVICE_ENDPOINTS = [
+  { name: "Backend API", url: "http://localhost:9001/api/data/mesh/list?per_page=1", port: 9001 },
+  { name: "Frontend", url: "http://localhost:3002", port: 3002 },
+  { name: "Storage Engine (MinIO)", url: "http://localhost:9002/minio/health/live", port: 9002 },
+  { name: "Trino", url: "http://localhost:8081/v1/info", port: 8081 },
+];
+
+async function gatherServiceHealth() {
+  const results = await Promise.all(
+    SERVICE_ENDPOINTS.map(async ({ name, url }) => {
+      const r = await httpPing(url);
+      if (r.ok) return `${name}: UP (HTTP ${r.status})`;
+      return `${name}: DOWN (${r.error || "HTTP " + r.status})`;
+    }),
+  );
+  return "Service health (HTTP checks):\n" + results.join("\n");
+}
+
+/**
+ * Detect which compose images are missing locally.
+ * Compares `docker compose config --images` against `docker images`.
+ */
+async function gatherMissingImages(root) {
+  try {
+    // Get all images required by compose
+    const { stdout: configImages } = await execa(
+      "docker", ["compose", "config", "--images"],
+      { cwd: root, reject: false, timeout: 10000 },
+    );
+    if (!configImages?.trim()) return null;
+
+    const required = [...new Set(configImages.trim().split("\n").filter(Boolean))];
+
+    // Get locally available images
+    const { stdout: localImages } = await execa(
+      "docker", ["images", "--format", "{{.Repository}}:{{.Tag}}"],
+      { reject: false, timeout: 5000 },
+    );
+    const localSet = new Set((localImages || "").trim().split("\n").filter(Boolean));
+
+    // Also check by repo without tag (docker sometimes lists <none> tag)
+    const localRepos = new Set(
+      (localImages || "").trim().split("\n").filter(Boolean).map((i) => i.split(":")[0]),
+    );
+
+    // Find which compose services have build contexts
+    const { stdout: configJson } = await execa(
+      "docker", ["compose", "config", "--format", "json"],
+      { cwd: root, reject: false, timeout: 10000 },
+    );
+    const buildableImages = new Set();
+    if (configJson?.trim()) {
+      try {
+        const config = JSON.parse(configJson);
+        for (const [, svc] of Object.entries(config.services || {})) {
+          if (svc.build && svc.image) buildableImages.add(svc.image);
         }
-        if (ages.length) parts.push("Image ages:\n" + ages.join("\n"));
-      }
-    } catch {}
+      } catch { /* ignore */ }
+    }
+
+    const missing = required.filter((img) => !localSet.has(img) && !localRepos.has(img.split(":")[0]));
+    if (missing.length === 0) return null;
+
+    const lines = missing.map((img) => {
+      const action = buildableImages.has(img) ? "needs BUILD (has build context)" : "needs PULL from registry";
+      return `  ${img} — ${action}`;
+    });
+
+    return `Missing images (${missing.length}/${required.length}):\n` + lines.join("\n") +
+      "\n\nTo build local images: make build\nTo pull registry images: make download (requires ECR auth)";
+  } catch {
+    return null;
   }
+}
 
-  // Check prerequisites (each wrapped individually so one failure doesn't kill the rest)
-  const prereqs = [];
-  try { await execa("git", ["--version"], { reject: false, timeout: 3000 }); prereqs.push("git: ✓"); } catch { prereqs.push("git: ✗"); }
-  try { await execa("docker", ["info"], { reject: false, timeout: 5000 }); prereqs.push("docker: ✓"); } catch { prereqs.push("docker: ✗"); }
-  try { await execa("aws", ["--version"], { reject: false, timeout: 3000 }); prereqs.push("aws-cli: ✓"); } catch { prereqs.push("aws-cli: ✗ (optional)"); }
-  parts.push("Prerequisites: " + prereqs.join(", "));
+async function gatherImageAges(root) {
+  try {
+    const { stdout: imgOut } = await execa("docker", ["compose", "images", "--format", "json"], { cwd: root, reject: false, timeout: 5000 });
+    if (imgOut?.trim()) {
+      const images = imgOut.trim().split("\n").filter(Boolean).map((line) => {
+        try { return JSON.parse(line); } catch { return null; }
+      }).filter(Boolean);
 
-  // Check for .env file
-  if (root) {
-    const envPath = path.join(root, ".env");
-    const envExamplePath = path.join(root, ".env.example");
-    if (fs.existsSync(envPath)) {
-      parts.push(".env: configured");
-    } else if (fs.existsSync(envExamplePath)) {
-      parts.push(".env: not configured (run 'fops setup' or 'cp .env.example .env')");
+      // Inspect all images in parallel
+      const ageResults = await Promise.all(images.map(async (img) => {
+        try {
+          const id = img.ID || img.id || "";
+          const repo = img.Repository || img.repository || "";
+          const tag = img.Tag || img.tag || "";
+          if (!id) return null;
+          const { stdout: created } = await execa("docker", ["image", "inspect", id, "--format", "{{.Created}}"], { reject: false, timeout: 3000 });
+          if (created?.trim()) {
+            const days = Math.floor((Date.now() - new Date(created.trim()).getTime()) / 86400000);
+            const name = `${repo}:${tag}`.replace(/^:|:$/g, "") || id.slice(0, 12);
+            return `${name}: ${days}d old`;
+          }
+        } catch {}
+        return null;
+      }));
+
+      const ages = ageResults.filter(Boolean);
+      if (ages.length) return "Image ages:\n" + ages.join("\n");
     }
+  } catch {}
+  return null;
+}
+
+async function gatherPrereqs() {
+  const checks = await Promise.all([
+    execa("git", ["--version"], { reject: false, timeout: 3000 }).then(() => "git: ✓").catch(() => "git: ✗ (REQUIRED)"),
+    execa("docker", ["info"], { reject: false, timeout: 5000 }).then(() => "docker: ✓").catch(() => "docker: ✗ (REQUIRED)"),
+    execa("aws", ["--version"], { reject: false, timeout: 3000 }).then(() => "aws-cli: ✓").catch(() => "aws-cli: ✗ (REQUIRED)"),
+  ]);
+
+  // Check git netrc for GitHub auth
+  const homedir = (await import("node:os")).default.homedir();
+  const netrcPath = (await import("node:path")).default.join(homedir, ".netrc");
+  let netrc = "git-netrc: ✗ (REQUIRED — needed for private repo access)";
+  try {
+    const netrcContent = (await import("node:fs")).default.readFileSync(netrcPath, "utf8");
+    if (netrcContent.includes("github.com")) {
+      netrc = "git-netrc: ✓ (github.com configured)";
+    } else {
+      netrc = "git-netrc: ✗ (no github.com entry — REQUIRED)";
+    }
+  } catch {}
+
+  checks.push(netrc);
+  return "Prerequisites: " + checks.join(", ");
+}
+
+function checkEnvFile(root) {
+  const envPath = path.join(root, ".env");
+  const envExamplePath = path.join(root, ".env.example");
+  if (fs.existsSync(envPath)) {
+    return ".env: configured";
+  } else if (fs.existsSync(envExamplePath)) {
+    return ".env: not configured (run 'fops setup' or 'cp .env.example .env')";
   }
+  return null;
+}
 
-  // Inject plugin skills into context
+async function gatherSkills(registry) {
   try {
-    const skills = await loadSkills();
+    const skills = await loadSkills(registry);
     if (skills.length) {
-      parts.push("## Additional Skills\n" + skills.map((s) => s.content).join("\n\n"));
+      return "## Additional Skills\n" + skills.map((s) => s.content).join("\n\n");
     }
   } catch {
     // skip if skill loading fails
   }
+  return null;
+}
+
+export async function gatherStackContext(root, { registry, message } = {}) {
+  const parts = [getFoundationContextBlock(root)];
+
+  if (root) {
+    // Run all independent checks in parallel
+    const [dockerStatus, serviceHealth, missingImages, imageAges, prereqs, envInfo, skills, knowledge] = await Promise.all([
+      gatherDockerStatus(root),
+      gatherServiceHealth(),
+      gatherMissingImages(root),
+      gatherImageAges(root),
+      gatherPrereqs(),
+      Promise.resolve(checkEnvFile(root)),
+      gatherSkills(registry),
+      registry && message ? searchKnowledge(registry, message) : Promise.resolve(null),
+    ]);
+
+    if (dockerStatus) parts.push(dockerStatus);
+    if (serviceHealth) parts.push(serviceHealth);
+    if (missingImages) parts.push(missingImages);
+    if (imageAges) parts.push(imageAges);
+    parts.push(prereqs);
+    if (envInfo) parts.push(envInfo);
+    if (skills) parts.push(skills);
+    if (knowledge) parts.push(knowledge);
+  } else {
+    // No root — still check prereqs, skills, and knowledge
+    const [prereqs, skills, knowledge] = await Promise.all([
+      gatherPrereqs(),
+      gatherSkills(registry),
+      registry && message ? searchKnowledge(registry, message) : Promise.resolve(null),
+    ]);
+    parts.push(prereqs);
+    if (skills) parts.push(skills);
+    if (knowledge) parts.push(knowledge);
+  }
 
   return parts.join("\n\n");
 }

package/src/agent/index.js

@@ -1,2 +1,3 @@
 export { runAgentSingleTurn, runAgentInteractive } from "./agent.js";
 export { gatherStackContext } from "./context.js";
+export { BUILTIN_AGENTS, loadBuiltinAgents } from "./agents.js";