@lazyingart/agintiflow 0.9.0 → 0.11.0

package/README.md

@@ -71,6 +71,8 @@ Inside chat, type normal requests such as `write a small Python CLI app with tes
 
 For code edits, AgInTiFlow routes patch/refactor/database-style tasks to DeepSeek v4 pro by default and exposes `apply_patch` as a deterministic workspace tool. It supports exact replacements, Codex-style patch envelopes, and unified diffs, with preflight checks, path guardrails, hashes, and compact per-file diffs. See [docs/patch-tools.md](docs/patch-tools.md).
 
+For larger repositories, use `--profile large-codebase` or choose **Large codebase engineering** in the web UI. The web default stays **Auto**, and Auto now escalates codebase/system/debugging prompts to the same engineering loop when needed. Complex work routes to DeepSeek v4 pro, starts with `inspect_project`, then uses search/read/patch/check loops inspired by Codex, Copilot SDK, Claude Code, Gemini CLI, Qwen, and Claw Code. See [docs/large-codebase-engineering.md](docs/large-codebase-engineering.md).
+
 For raster image work, AgInTiFlow has an optional `image_generation` skill backed by the `generate_image` tool and a local `GRSAI` key. The skill tells DeepSeek when image generation is appropriate; the tool calls GRS AI Nano Banana, saves manifests/images under `artifacts/images`, and sends the result to the canvas. See [docs/auxiliary-image-generation.md](docs/auxiliary-image-generation.md).
 
 Launch the local web UI from an installed package:

package/docs/large-codebase-engineering.md

@@ -0,0 +1,75 @@
+# Large Codebase Engineering
+
+AgInTiFlow now treats large or complicated coding tasks as a different operating mode from short file edits.
+
+## What Was Borrowed
+
+Local agent references informed the design:
+
+- Codex-style editing: read/search first, apply deterministic patches, record diffs and hashes, then run checks.
+- Copilot-style SDK surfaces: structured tools, session persistence, plan/history/workspace APIs, and explicit permission hooks.
+- Claude/Claw-style safety: project-local status, container-first execution, read-only operations by default, and clear failure recovery.
+- Gemini/Qwen-style extensibility: capability discovery through profiles and tools rather than hardcoding one model behavior.
+- Claw-style `doctor` discipline: check health and environment before treating system symptoms as code bugs.
+- Claude/Codex-style context discipline: read instructions, manifests, entry points, and failing tests before touching broad files.
+
+## Skill vs Tool
+
+The `large-codebase` profile is a skill: it changes the model’s engineering behavior. It tells DeepSeek v4 pro to orient first, plan minimally, patch incrementally, and verify.
+
+The `inspect_project` function is a tool: it deterministically scans the workspace and returns:
+
+- top-level files and directories
+- manifest files such as `package.json`, `pyproject.toml`, `Cargo.toml`, and `go.mod`
+- package scripts
+- likely source and test directories
+- language and extension counts
+- recommended files to read next
+
+## Recommended Loop
+
+For complicated tasks, the agent should follow this loop:
+
+1. `inspect_project` to map the repository.
+2. `read_file` on `AGENTS.md`, `README.md`, and manifests.
+3. `search_files` for symbols, tests, errors, routes, or config names.
+4. `read_file` only on the files needed for the change.
+5. `apply_patch` in small coherent batches.
+6. `run_command` for the narrowest relevant check first.
+7. Broaden checks only after the focused check passes.
+
+## CLI And Web Parity
+
+Both CLI and web use the same task profile registry and the same model/tool schemas. Use either:
+
+```bash
+aginti --profile large-codebase "fix the failing tests"
+```
+
+or choose **Large codebase engineering** in the web task-profile dropdown.
+
+Smart routing sends this profile to DeepSeek v4 pro even when the user prompt is short.
+
+## Auto Profile Behavior
+
+The web app still defaults to **Auto**. Auto does not mean weak. When the prompt mentions a large repo, system bug, failing tests, setup, install, migration, or a known language stack, AgInTiFlow adds engineering guidance and raises the step budget automatically.
+
+Examples:
+
+```bash
+aginti "debug this Python project system bug and fix failing tests"
+aginti "fix the Rust workspace build"
+aginti "repair the Docker setup and run the Node tests"
+```
+
+These route to DeepSeek v4 pro when the complexity score is high enough.
+
+## Cross-Language Playbook
+
+AgInTiFlow gives DeepSeek stack-specific reminders without hardcoding a solution:
+
+- JS/TS: inspect package scripts and lockfiles, then run focused `node`, `tsc`, or test commands.
+- Python: inspect `pyproject.toml` or requirements, prefer project-local venv/conda/Docker, then run focused pytest/module checks.
+- Rust/Go/JVM/C/C++: inspect native manifests, format only touched files when possible, and start with narrow build/test targets.
+- R/Stan/LaTeX: keep toolchains project-local or Docker-backed, compile from the right directory, and publish useful artifacts to canvas.
+- System tasks: diagnose first, capture versions/logs, write reversible scripts, use Docker for installs, and avoid silent host-level changes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazyingart/agintiflow",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "type": "module",
   "description": "AgInTiFlow is a resumable Playwright website-control agent with OpenAI-compatible tool calling.",
   "license": "Apache-2.0",

package/public/app.js

@@ -775,6 +775,25 @@ function renderTaskProfiles(selected = "auto") {
   taskProfileField.value = profiles.some((profile) => profile.id === selected) ? selected : "auto";
 }
 
+const COMPLEX_ENGINEERING_HINT = /\b(large|complex|complicated|monorepo|codebase|repository|repo-wide|multi[- ]file|cross[- ]file|architecture|refactor|migration|regression|root cause|failing tests?|fix build|system bug|debug|performance|security)\b/i;
+
+function recommendedMaxStepsForProfile(profile = "auto", goal = "") {
+  if (profile === "large-codebase") return 36;
+  if (profile === "latex") return 30;
+  if (COMPLEX_ENGINEERING_HINT.test(goal || "")) return 36;
+  if (/\b(latex|tex|pdflatex|latexmk|pdf|website|app|docker|system|install|setup|debug)\b/i.test(goal || "")) return 30;
+  return 24;
+}
+
+function ensureRecommendedMaxStepsForCurrentTask() {
+  const maxStepsField = document.querySelector("#maxSteps");
+  const goalField = document.querySelector("#goal");
+  const recommended = recommendedMaxStepsForProfile(taskProfileField?.value || "auto", goalField?.value || "");
+  if (maxStepsField && Number(maxStepsField.value || 0) < recommended) {
+    maxStepsField.value = String(recommended);
+  }
+}
+
 function renderWrapperStatus(wrappers = lastWrappers) {
   lastWrappers = wrappers || [];
   if (lastWrappers.length === 0) {
@@ -1959,7 +1978,10 @@ sandboxModeField.addEventListener("change", updatePackageWarning);
 packageInstallPolicyField.addEventListener("change", updatePackageWarning);
 allowWrapperToolsField.addEventListener("change", () => renderWrapperStatus());
 preferredWrapperField.addEventListener("change", () => renderWrapperStatus());
-taskProfileField?.addEventListener("change", schedulePreferenceSave);
+taskProfileField?.addEventListener("change", () => {
+  ensureRecommendedMaxStepsForCurrentTask();
+  schedulePreferenceSave();
+});
 
 saveApiKeyButton?.addEventListener("click", async () => {
   const provider = setupProviderField.value || "deepseek";
@@ -2035,6 +2057,7 @@ form.addEventListener("submit", async (event) => {
     setLogs(t("goalRequired"), "empty");
     return;
   }
+  ensureRecommendedMaxStepsForCurrentTask();
 
   const payload = {
     ...formPayload(),

package/scripts/smoke-coding-tools.js

@@ -5,6 +5,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { repairModelMessageHistory, runAgent } from "../src/agent-runner.js";
 import { resolveRuntimeConfig } from "../src/config.js";
+import { engineeringGuidanceForTask, recommendedMaxStepsForTask } from "../src/engineering-guidance.js";
 import { selectModelRoute } from "../src/model-routing.js";
 import { SessionStore } from "../src/session-store.js";
 import { executeWorkspaceTool } from "../src/workspace-tools.js";
@@ -86,6 +87,71 @@ try {
     goal: "patch this large codebase and migrate the database tests",
   });
   assert(/pro/i.test(patchRoute.model), "patch/refactor task did not route to DeepSeek pro");
+  const largeProfileRoute = selectModelRoute({
+    routingMode: "smart",
+    provider: "deepseek",
+    goal: "fix this bug",
+    taskProfile: "large-codebase",
+  });
+  assert(/pro/i.test(largeProfileRoute.model), "large-codebase profile did not route to DeepSeek pro");
+  const autoSystemRoute = selectModelRoute({
+    routingMode: "smart",
+    provider: "deepseek",
+    goal: "debug this Python project system bug and fix failing tests",
+    taskProfile: "auto",
+  });
+  assert(/pro/i.test(autoSystemRoute.model), "auto system/code problem did not route to DeepSeek pro");
+  assert(
+    recommendedMaxStepsForTask({
+      goal: "debug this Python project system bug and fix failing tests",
+      taskProfile: "auto",
+      complexityScore: autoSystemRoute.complexityScore,
+    }) >= 36,
+    "auto system/code problem did not get engineering step budget"
+  );
+  const guidance = engineeringGuidanceForTask("debug this Python project system bug and fix failing tests", "auto");
+  assert(guidance.includes("Python:"), "engineering guidance did not include Python stack advice");
+  assert(guidance.includes("System/shell:"), "engineering guidance did not include system stack advice");
+
+  await fs.mkdir(path.join(workspace, "src"), { recursive: true });
+  await fs.mkdir(path.join(workspace, "test"), { recursive: true });
+  await fs.writeFile(
+    path.join(workspace, "package.json"),
+    JSON.stringify(
+      {
+        name: "agintiflow-inspect-smoke",
+        scripts: {
+          test: "node --test test/index.test.js",
+          check: "node --check src/index.js",
+        },
+      },
+      null,
+      2
+    ),
+    "utf8"
+  );
+  await fs.writeFile(path.join(workspace, "src/index.js"), "export function answer() { return 42; }\n", "utf8");
+  await fs.writeFile(path.join(workspace, "test/index.test.js"), "import test from 'node:test';\n", "utf8");
+  const inspected = await executeWorkspaceTool(
+    "inspect_project",
+    { path: ".", maxDepth: 4, limit: 200 },
+    {
+      commandCwd: workspace,
+      allowFileTools: true,
+    }
+  );
+  assert(inspected.ok, "inspect_project failed");
+  assert(inspected.manifestFiles.some((item) => item.path === "package.json"), "inspect_project did not find package.json");
+  assert(inspected.packageScripts.some((item) => item.name === "test"), "inspect_project did not extract package scripts");
+  assert(inspected.sourceDirs.some((item) => item.path === "src"), "inspect_project did not identify src directory");
+  assert(inspected.testFiles.some((item) => item.path === "test/index.test.js"), "inspect_project did not identify test file");
+  assert(inspected.recommendedReads.includes("package.json"), "inspect_project did not recommend package.json");
+
+  const inspectRun = await runMock("Inspect this large codebase and recommend next reads.", "coding-inspect");
+  assert(
+    inspectRun.events.some((event) => event.type === "tool.completed" && event.data?.toolName === "inspect_project"),
+    "mock large-codebase run did not use inspect_project"
+  );
 
   const writeRun = await runMock("Create notes/hello.md with a short coding smoke message.", "coding-write");
   const written = await fs.readFile(path.join(workspace, "notes/hello.md"), "utf8");
@@ -216,6 +282,11 @@ try {
         checks: [
           "deepseek_history_repair",
           "deepseek_pro_patch_route",
+          "large_profile_pro_route",
+          "auto_system_pro_route",
+          "auto_engineering_guidance",
+          "inspect_project",
+          "mock_inspect_project",
           "write_file",
           "duplicate_write_failed",
           "resume_session_write",

package/src/agent-runner.js

@@ -18,6 +18,7 @@ import { executeWorkspaceTool, resolveWorkspacePath, summarizeWorkspaceTools, WO
 import { normalizeCanvasPayload } from "./artifact-tunnel.js";
 import { getTaskProfile } from "./task-profiles.js";
 import { generateImage, listAuxiliarySkills } from "./auxiliary-tools.js";
+import { engineeringGuidanceForTask } from "./engineering-guidance.js";
 
 const exec = promisify(execCallback);
 const BROWSER_TOOLS = new Set(["open_url", "open_workspace_file", "preview_workspace", "click", "type", "scroll", "press", "back"]);
@@ -233,6 +234,7 @@ export function repairModelMessageHistory(state, config = {}) {
 function createInitialState(config, sessionId) {
   const now = new Date().toISOString();
   const taskProfile = getTaskProfile(config.taskProfile);
+  const engineeringGuidance = engineeringGuidanceForTask(config.goal, config.taskProfile);
   return {
     sessionId,
     createdAt: now,
@@ -272,7 +274,7 @@ function createInitialState(config, sessionId) {
               : "A host shell command tool is available under the configured trust policy."
             : "No shell command tool is available.",
           config.allowFileTools
-            ? `Workspace file tools are available in ${config.commandCwd}: list_files, read_file, search_files, write_file, apply_patch, open_workspace_file, and preview_workspace. apply_patch supports exact single-file replacements plus Codex-style/unified multi-file patches; prefer it for source edits after reading/searching the relevant context. Always use workspace-relative paths such as plot_fx.svg or docs/report.tex, never absolute host paths. Secret paths, .git internals, node_modules writes, and huge files are blocked. For generated local websites/pages, use open_workspace_file or preview_workspace instead of starting a localhost server inside Docker.`
+            ? `Workspace file tools are available in ${config.commandCwd}: inspect_project, list_files, read_file, search_files, write_file, apply_patch, open_workspace_file, and preview_workspace. For large or unfamiliar repositories, call inspect_project first, then search/read exact files before editing. apply_patch supports exact single-file replacements plus Codex-style/unified multi-file patches; prefer it for source edits after reading/searching the relevant context. Always use workspace-relative paths such as plot_fx.svg or docs/report.tex, never absolute host paths. Secret paths, .git internals, node_modules writes, and huge files are blocked. For generated local websites/pages, use open_workspace_file or preview_workspace instead of starting a localhost server inside Docker.`
             : "No workspace file tools are available.",
           config.allowWrapperTools
             ? `External coding-agent wrappers are available as advisory tools only. Use the selected wrapper only: ${normalizeWrapperName(config.preferredWrapper)}. Wrapper status: ${wrapperStatusText()}.`
@@ -283,10 +285,11 @@ function createInitialState(config, sessionId) {
                 .join(", ")}. Use generate_image for real raster image/photo/illustration/cover/poster/logo requests when appropriate; if the key is missing, ask the user to run /auxilliary grsai or aginti login grsai.`
             : "Auxiliary skills are disabled for this run.",
           `Task profile: ${taskProfile.label}. ${taskProfile.prompt}`,
+          engineeringGuidance,
           "A frontend canvas/artifacts tunnel exists. Use send_to_canvas when important markdown, diffs, screenshots, images, or workspace files should be highlighted in the UI. It is optional and ordinary final text can still go directly to finish.",
           "For visual-output requests such as draw, plot, graph, chart, diagram, figure, image, or visualization, proactively publish a canvas artifact even when the user does not mention canvas. If workspace file tools are enabled, prefer creating a small SVG or markdown artifact and call send_to_canvas with selected=true.",
-          "Work like a practical coding agent: inspect when useful, patch code with apply_patch, run safe checks when they add confidence, iterate on failures, and keep outputs inside the workspace.",
-          "For large projects, decompose into useful files and milestones, implement a coherent minimal version first, then iterate with checks rather than only describing what you would do.",
+          "Work like a practical coding agent: orient with inspect_project/search/read, patch code with apply_patch, run safe checks when they add confidence, iterate on failures, and keep outputs inside the workspace.",
+          "For large projects, decompose into useful files and milestones, identify entry points/tests/contracts first, implement a coherent minimal version, then iterate with checks rather than only describing what you would do.",
           "For website/app/code/LaTeX/Python/C/shell tasks, create or edit real workspace files, run available build/compile/test commands, and surface artifacts through the canvas when useful.",
           "For research or web-search tasks, use browser tools or safe shell network tools when the current policy allows; cite or save useful sources in workspace notes when the task needs traceability.",
           "Use the canvas tunnel for outputs the user would likely want to inspect visually, such as figures, PDFs, screenshots, images, important markdown, or generated files.",
@@ -310,7 +313,7 @@ function createInitialState(config, sessionId) {
               : `Shell working directory: ${config.commandCwd}`
             : "",
           config.allowFileTools
-            ? `Workspace file tools enabled in: ${config.commandCwd}. Use workspace-relative paths. Use apply_patch for code edits; it accepts exact replacements or Codex-style/unified multi-file patches. Local preview tools available: open_workspace_file and preview_workspace.`
+            ? `Workspace file tools enabled in: ${config.commandCwd}. Use inspect_project first for large/unfamiliar codebases. Use workspace-relative paths. Use apply_patch for code edits; it accepts exact replacements or Codex-style/unified multi-file patches. Local preview tools available: open_workspace_file and preview_workspace.`
             : "",
           config.allowWrapperTools
             ? `Agent wrappers: selected=${normalizeWrapperName(config.preferredWrapper)}; ${wrapperStatusText()}`
@@ -321,9 +324,10 @@ function createInitialState(config, sessionId) {
                 .join(" ")}`
             : "",
           `Task profile: ${taskProfile.label}. ${taskProfile.prompt}`,
+          engineeringGuidance,
           "Canvas/artifacts tunnel: available through send_to_canvas for optional frontend rendering.",
           "Visual-output requests should produce a canvas artifact without requiring the user to ask for canvas explicitly.",
-          "Use file, shell, browser, canvas, and wrapper tools when they are useful; choose the workflow from the user's request.",
+          "Use file, shell, browser, canvas, and wrapper tools when they are useful; choose the workflow from the user's request. For complicated engineering tasks, keep a tight loop: inspect, choose minimal files, patch, run focused checks, repair, then summarize.",
           "Do not stop at a plan when tools can accomplish the request. Continue through implementation, checks, artifact selection, and finish.",
           "Use the configured sandbox and package policy for environment or system-maintenance work.",
         ]
@@ -410,6 +414,7 @@ function applyContinuationPrompt(state, config, observers) {
   if (!config.resume || !config.goal) return;
 
   const taskProfile = getTaskProfile(config.taskProfile);
+  const engineeringGuidance = engineeringGuidanceForTask(config.goal, config.taskProfile);
   ensureChatState(state);
   state.goal = config.goal;
   state.provider = config.provider;
@@ -430,12 +435,13 @@ function applyContinuationPrompt(state, config, observers) {
           : `Shell working directory: ${config.commandCwd}`
         : "",
       config.allowFileTools
-        ? `Workspace file tools enabled in: ${config.commandCwd}. Use workspace-relative paths. For generated local files/sites, use open_workspace_file or preview_workspace.`
+        ? `Workspace file tools enabled in: ${config.commandCwd}. Use inspect_project first for large or unfamiliar codebases, then search/read exact files before editing. Use workspace-relative paths. Use apply_patch for code edits; it accepts exact replacements or Codex-style/unified multi-file patches. For generated local files/sites, use open_workspace_file or preview_workspace.`
         : "",
       config.allowWrapperTools
         ? `Agent wrappers: selected=${normalizeWrapperName(config.preferredWrapper)}; ${wrapperStatusText()}`
         : "",
       `Task profile: ${taskProfile.label}. ${taskProfile.prompt}`,
+      engineeringGuidance,
     ]
       .filter(Boolean)
       .join("\n"),
@@ -631,7 +637,7 @@ async function captureSyntheticSnapshot(store, step, config) {
           : `Shell tool available in: ${config.commandCwd}`
         : "Shell tool disabled.",
       config.allowFileTools
-        ? `Workspace file tools available in: ${config.commandCwd}. Use workspace-relative paths. Use apply_patch for code edits; it supports exact single-file replacement and multi-file Codex-style/unified patches.`
+        ? `Workspace file tools available in: ${config.commandCwd}. Use inspect_project first for large or unfamiliar codebases, then search/read exact files before editing. Use workspace-relative paths. Use apply_patch for code edits; it supports exact single-file replacement and multi-file Codex-style/unified patches.`
         : "Workspace file tools disabled.",
       config.allowWrapperTools
         ? `Agent wrappers available: selected=${normalizeWrapperName(config.preferredWrapper)}; ${wrapperStatusText()}`
@@ -815,6 +821,7 @@ async function executeTool(browserState, toolCall, snapshot, config, store, obse
           await new Promise((resolve) => setTimeout(resolve, Number.isFinite(args.ms) ? Number(args.ms) : 1000));
         }
         break;
+      case "inspect_project":
       case "list_files":
       case "read_file":
       case "search_files":

package/src/cli.js

@@ -15,6 +15,7 @@ import {
   showProjectSession,
 } from "./project.js";
 import { listTaskProfiles } from "./task-profiles.js";
+import { recommendedMaxStepsForTask } from "./engineering-guidance.js";
 import { promptAndSaveDeepSeekKey, promptHidden, shouldPromptForDeepSeek } from "./auth-onboarding.js";
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -256,7 +257,12 @@ function agentDefaults(args) {
     sandboxMode: args.sandboxMode || "docker-workspace",
     packageInstallPolicy: args.packageInstallPolicy || "allow",
     useDockerSandbox: args.useDockerSandbox ?? true,
-    maxSteps: args.maxSteps || (args.latex || args.taskProfile === "latex" ? 30 : 24),
+    maxSteps:
+      args.maxSteps ||
+      recommendedMaxStepsForTask({
+        goal: args.goal || "",
+        taskProfile: args.taskProfile || (args.latex ? "latex" : "auto"),
+      }),
   };
 
   if (defaults.sandboxMode === "host") {

package/src/config.js

@@ -5,6 +5,7 @@ import { normalizePackageInstallPolicy, normalizeSandboxMode } from "./command-p
 import { normalizeWrapperName } from "./tool-wrappers.js";
 import { loadProjectEnv, resolveProjectRoot } from "./project.js";
 import { normalizeTaskProfile } from "./task-profiles.js";
+import { recommendedMaxStepsForTask } from "./engineering-guidance.js";
 
 function parseBoolean(value, fallback) {
   if (value === undefined) return fallback;
@@ -33,14 +34,21 @@ export function resolveRuntimeConfig(args, overrides = {}) {
     process.env.AGENT_PROVIDER ||
     (process.env.DEEPSEEK_API_KEY ? "deepseek" : process.env.OPENAI_API_KEY ? "openai" : "deepseek");
   const routingMode = normalizeRoutingMode(overrides.routingMode || args.routingMode || process.env.AGENT_ROUTING_MODE || "smart");
+  const taskProfile = normalizeTaskProfile(overrides.taskProfile || args.taskProfile || process.env.AGINTI_TASK_PROFILE || "auto");
   const route = selectModelRoute({
     routingMode,
     provider: requestedProvider,
     model: overrides.model || args.model || process.env.LLM_MODEL || "",
     goal: args.goal || "",
+    taskProfile,
   });
 
   const defaults = getProviderDefaults(route.provider);
+  const defaultMaxSteps = recommendedMaxStepsForTask({
+    goal: args.goal || "",
+    taskProfile,
+    complexityScore: route.complexityScore,
+  });
   const packageDir = path.resolve(overrides.packageDir || process.env.AGINTIFLOW_PACKAGE_DIR || baseDir);
   const dockerRequested = parseBoolean(overrides.useDockerSandbox ?? args.useDockerSandbox ?? process.env.USE_DOCKER_SANDBOX, true);
   const requestedSandboxMode =
@@ -56,7 +64,7 @@ export function resolveRuntimeConfig(args, overrides = {}) {
     resume: args.resume || "",
     sessionId: overrides.sessionId || args.sessionId || process.env.SESSION_ID || `web-agent-${crypto.randomUUID()}`,
     routingMode,
-    taskProfile: normalizeTaskProfile(overrides.taskProfile || args.taskProfile || process.env.AGINTI_TASK_PROFILE || "auto"),
+    taskProfile,
     routeReason: route.reason,
     routeComplexityScore: route.complexityScore,
     requestedProvider,
@@ -65,7 +73,7 @@ export function resolveRuntimeConfig(args, overrides = {}) {
     apiKey: overrides.apiKey || defaults.apiKey,
     baseURL: overrides.baseURL || defaults.baseURL,
     model: route.model || defaults.model,
-    maxSteps: parseNumber(overrides.maxSteps ?? args.maxSteps ?? process.env.MAX_STEPS, 24),
+    maxSteps: parseNumber(overrides.maxSteps ?? args.maxSteps ?? process.env.MAX_STEPS, defaultMaxSteps),
     headless: parseBoolean(overrides.headless ?? args.headless ?? process.env.HEADLESS, false),
     allowedDomains: Array.isArray(overrides.allowedDomains)
       ? overrides.allowedDomains

package/src/engineering-guidance.js

@@ -0,0 +1,102 @@
+import { defaultMaxStepsForProfile, normalizeTaskProfile } from "./task-profiles.js";
+
+const LANGUAGE_HINTS = [
+  {
+    id: "javascript-typescript",
+    pattern: /\b(node|npm|pnpm|yarn|bun|javascript|typescript|react|vue|svelte|next\.?js|vite|express)\b/i,
+    text:
+      "JS/TS: inspect package.json and lockfiles, identify package manager, use npm/pnpm/yarn scripts before inventing commands, prefer targeted node --check/tsc/test runs before broad builds.",
+  },
+  {
+    id: "python",
+    pattern: /\b(python|pytest|pip|uv|poetry|conda|venv|jupyter|fastapi|django|flask|pandas|numpy)\b/i,
+    text:
+      "Python: inspect pyproject/requirements, prefer project-local venv/uv/conda or Docker, run python -m pytest or focused module checks, avoid global package installs on host.",
+  },
+  {
+    id: "rust",
+    pattern: /\b(rust|cargo|crate|clippy|rustfmt|tokio|actix)\b/i,
+    text:
+      "Rust: inspect Cargo.toml/workspace crates, run cargo fmt/check/test on the narrowest crate first, preserve Cargo.lock discipline, avoid broad workspace runs until focused checks pass.",
+  },
+  {
+    id: "go",
+    pattern: /\b(golang|go test|go mod|goroutine|gin|grpc)\b/i,
+    text:
+      "Go: inspect go.mod, use go test ./pkg-or-target first, run gofmt on touched files, avoid changing module paths unless required.",
+  },
+  {
+    id: "java-jvm",
+    pattern: /\b(java|kotlin|gradle|maven|spring|junit|jvm)\b/i,
+    text:
+      "JVM: inspect pom.xml/build.gradle/settings.gradle, use focused Maven/Gradle test targets, keep generated build outputs out of source patches.",
+  },
+  {
+    id: "c-cpp",
+    pattern: /\b(c\+\+|cpp|cmake|makefile|gcc|clang|native|segfault|asan|valgrind)\b/i,
+    text:
+      "C/C++: inspect CMake/Make/build scripts, prefer out-of-tree builds, run compile-only or narrow tests first, use sanitizers only when available and safe.",
+  },
+  {
+    id: "shell-system",
+    pattern: /\b(shell|bash|zsh|system|systemd|docker|linux|ubuntu|debian|apt|yum|dnf|brew|service|permission denied|port|network)\b/i,
+    text:
+      "System/shell: diagnose first with read-only commands, capture versions/logs, make reversible scripts, use Docker for installs/toolchains, and only use host-level changes when policy explicitly allows them.",
+  },
+  {
+    id: "r-stats",
+    pattern: /\b(rstats|r language|cmdstanr|stan|renv|tidyverse|shiny)\b/i,
+    text:
+      "R/Stan: inspect renv/DESCRIPTION and project notes, prefer project-local libraries or Docker, validate scripts with non-interactive Rscript commands when available.",
+  },
+  {
+    id: "latex",
+    pattern: /\b(latex|tex|pdflatex|latexmk|bibtex|biber|pdf)\b/i,
+    text:
+      "LaTeX: keep source/figures together, compile from the document directory, run enough passes for refs/bibliography, publish PDF/source artifacts to canvas.",
+  },
+];
+
+const COMPLEX_ENGINEERING_PATTERN =
+  /\b(large|complex|complicated|monorepo|codebase|repository|repo-wide|multi[- ]file|cross[- ]file|architecture|refactor|migration|regression|root cause|failing tests?|fix build|system bug|debug|performance|security)\b/i;
+
+export function engineeringGuidanceForTask(goal = "", taskProfile = "auto") {
+  const normalizedProfile = normalizeTaskProfile(taskProfile);
+  const text = String(goal || "");
+  const matched = LANGUAGE_HINTS.filter((hint) => hint.pattern.test(text));
+  const wantsComplex =
+    normalizedProfile === "large-codebase" ||
+    normalizedProfile === "maintenance" ||
+    COMPLEX_ENGINEERING_PATTERN.test(text) ||
+    text.length > 500;
+
+  if (!wantsComplex && matched.length === 0) return "";
+
+  const lines = [
+    "Engineering operating mode:",
+    "Use the proven coding-agent loop: inspect_project, read instructions/manifests, search exact symbols/errors, patch small coherent batches, run focused checks, repair failures, then summarize changed files and residual risks.",
+    "Keep CLI and web behavior equivalent: use the same workspace, sessions, profiles, file tools, shell policy, Docker mounts, and canvas artifacts.",
+    "For large repositories, preserve context by reading fewer but more relevant files; prefer deterministic tools and diffs over long model memory.",
+    "For system repair, act like a doctor: gather evidence first, avoid silent destructive host changes, prefer Docker or project-local scripts for installs, and make every stronger action explicit in logs.",
+  ];
+
+  if (matched.length > 0) {
+    lines.push("Stack-specific checks:");
+    for (const hint of matched.slice(0, 5)) lines.push(`- ${hint.text}`);
+  }
+
+  return lines.join("\n");
+}
+
+export function recommendedMaxStepsForTask({ goal = "", taskProfile = "auto", complexityScore = 0 } = {}) {
+  const normalizedProfile = normalizeTaskProfile(taskProfile);
+  const profileDefault = defaultMaxStepsForProfile(normalizedProfile);
+  const text = String(goal || "");
+  if (normalizedProfile === "large-codebase" || complexityScore >= 3 || COMPLEX_ENGINEERING_PATTERN.test(text)) {
+    return Math.max(profileDefault, 36);
+  }
+  if (/\b(latex|tex|pdflatex|latexmk|pdf|website|app|docker|system|install|setup|debug)\b/i.test(text)) {
+    return Math.max(profileDefault, 30);
+  }
+  return profileDefault;
+}

package/src/interactive-cli.js

@@ -5,7 +5,8 @@ import { runAgent } from "./agent-runner.js";
 import { loadConfig } from "./config.js";
 import { initProject, listProjectSessions, providerKeyStatus, setProviderKey } from "./project.js";
 import { normalizePackageInstallPolicy, normalizeSandboxMode } from "./command-policy.js";
-import { normalizeTaskProfile } from "./task-profiles.js";
+import { defaultMaxStepsForProfile, normalizeTaskProfile } from "./task-profiles.js";
+import { recommendedMaxStepsForTask } from "./engineering-guidance.js";
 import { promptAndSaveDeepSeekKey, promptHidden, shouldPromptForDeepSeek } from "./auth-onboarding.js";
 
 const useColor = Boolean(input.isTTY && output.isTTY && process.env.AGINTIFLOW_NO_COLOR !== "1");
@@ -439,7 +440,10 @@ function createState(args = {}) {
     preferredWrapper: args.preferredWrapper || "codex",
     taskProfile: normalizeTaskProfile(args.taskProfile || "auto"),
     headless: args.headless ?? false,
-    maxSteps: Number.isFinite(args.maxSteps) && args.maxSteps > 0 ? args.maxSteps : args.latex ? 30 : 24,
+    maxSteps:
+      Number.isFinite(args.maxSteps) && args.maxSteps > 0
+        ? args.maxSteps
+        : defaultMaxStepsForProfile(args.taskProfile || (args.latex ? "latex" : "auto")),
     sessionId: args.resume || "",
   };
 }
@@ -589,6 +593,7 @@ async function handleCommand(line, state, packageDir) {
   }
   if (command === "profile") {
     state.taskProfile = normalizeTaskProfile(value || "auto");
+    state.maxSteps = Math.max(state.maxSteps, defaultMaxStepsForProfile(state.taskProfile));
     printSystemLine(`profile=${state.taskProfile}`);
     return true;
   }
@@ -669,6 +674,13 @@ async function handleCommand(line, state, packageDir) {
 
 async function runPrompt(prompt, state, packageDir) {
   const controller = new AbortController();
+  const runMaxSteps = Math.max(
+    state.maxSteps,
+    recommendedMaxStepsForTask({
+      goal: prompt,
+      taskProfile: state.taskProfile,
+    })
+  );
   const config = loadConfig(
     {
       provider: state.provider,
@@ -684,7 +696,7 @@ async function runPrompt(prompt, state, packageDir) {
       allowDestructive: state.allowDestructive,
       preferredWrapper: state.preferredWrapper,
       taskProfile: state.taskProfile,
-      maxSteps: state.maxSteps,
+      maxSteps: runMaxSteps,
       headless: state.headless,
       resume: state.sessionId,
       goal: prompt,

package/src/model-client.js

@@ -2,6 +2,7 @@ import OpenAI from "openai";
 import { normalizeWrapperName, wrapperStatusText } from "./tool-wrappers.js";
 import { getTaskProfile } from "./task-profiles.js";
 import { listAuxiliarySkills } from "./auxiliary-tools.js";
+import { engineeringGuidanceForTask } from "./engineering-guidance.js";
 
 export function createClient(config) {
   if (config.provider === "mock") {
@@ -81,6 +82,13 @@ function mockPathForGoal(goal = "") {
 function mockWorkspaceToolForGoal(goal = "") {
   const text = String(goal).toLowerCase();
   const targetPath = mockPathForGoal(goal);
+  if (/inspect|map|overview|architecture|large codebase|large repo|repository|repo\b|codebase/.test(text)) {
+    return mockToolCall("inspect_project", {
+      path: ".",
+      maxDepth: 6,
+      limit: 400,
+    });
+  }
   if (/patch|replace|edit/.test(text)) {
     if (/multi|codex|unified|several|multiple/i.test(text)) {
       return mockToolCall("apply_patch", {
@@ -166,6 +174,7 @@ function mockChatResponse(content, toolCalls = []) {
 
 export async function createPlan(client, config, state) {
   const taskProfile = getTaskProfile(config.taskProfile);
+  const engineeringGuidance = engineeringGuidanceForTask(state.goal, config.taskProfile);
   if (client.mock) {
     return [
       "1. Inspect the request and prefer the local shell when available.",
@@ -194,7 +203,7 @@ export async function createPlan(client, config, state) {
             ? `Shell tool is enabled in ${config.commandCwd}. In Docker, this path is mounted as /workspace with persistent /aginti-env and /aginti-cache mounts. Use relative paths or /workspace paths, not absolute host temp paths. Sandbox mode: ${config.sandboxMode}. Package install policy: ${config.packageInstallPolicy}. For npm/pip/conda/venv setup, explain the need and wait for approval unless policy is allow.`
             : "",
           config.allowFileTools
-            ? `Workspace file tools are enabled in ${config.commandCwd}: list_files, read_file, search_files, write_file, apply_patch, open_workspace_file, preview_workspace. apply_patch supports exact single-file replacements and Codex-style/unified multi-file patches; prefer it for edits after reading relevant context. Keep all paths workspace-relative, for example plot_fx.svg or docs/report.tex, and avoid secrets. For generated local HTML/SVG/PDF/static sites, plan to use open_workspace_file or preview_workspace rather than starting a localhost server inside Docker.`
+            ? `Workspace file tools are enabled in ${config.commandCwd}: inspect_project, list_files, read_file, search_files, write_file, apply_patch, open_workspace_file, preview_workspace. For large or unfamiliar repos, plan to call inspect_project first, then search/read exact files. apply_patch supports exact single-file replacements and Codex-style/unified multi-file patches; prefer it for edits after reading relevant context. Keep all paths workspace-relative, for example plot_fx.svg or docs/report.tex, and avoid secrets. For generated local HTML/SVG/PDF/static sites, plan to use open_workspace_file or preview_workspace rather than starting a localhost server inside Docker.`
             : "",
           config.allowWrapperTools
             ? `Agent wrappers are enabled. Use the selected wrapper only: ${normalizeWrapperName(config.preferredWrapper)}. Status: ${wrapperStatusText()}.`
@@ -205,6 +214,7 @@ export async function createPlan(client, config, state) {
                 .join(", ")}. For raster image generation requests, plan to use generate_image when a GRSAI key is available; otherwise ask the user to run /auxilliary grsai or aginti login grsai.`
             : "Auxiliary skills are disabled for this run.",
           `Task profile: ${taskProfile.label}. ${taskProfile.prompt}`,
+          engineeringGuidance,
           "A canvas/artifacts tunnel is available through send_to_canvas. Use it when an output should be highlighted visually, such as screenshots, image files, important markdown, diffs, or generated artifact paths. It is optional for ordinary text answers.",
           "Work like a practical coding agent: inspect when useful, edit with file tools, run safe checks when they add confidence, and keep outputs inside the workspace.",
           "For large apps, websites, LaTeX documents, Python/C/shell projects, or system tasks, plan a coherent minimal implementation, then use tools to create files, run checks, and publish artifacts.",
@@ -414,6 +424,24 @@ export async function requestNextStep(client, config, messages) {
     tools.splice(
       -1,
       0,
+      {
+        type: "function",
+        function: {
+          name: "inspect_project",
+          description:
+            "Build a compact, deterministic map of the workspace for large-codebase work. Returns top-level entries, manifests, source/test directories, package scripts, language counts, and recommended files to read next. Use this before editing an unfamiliar or multi-file repository.",
+          parameters: {
+            type: "object",
+            properties: {
+              path: { type: "string", description: "Workspace-relative directory to inspect. Defaults to ." },
+              maxDepth: { type: "integer", description: "Recursive depth, 1 to 10. Defaults to 6." },
+              limit: { type: "integer", description: "Maximum filesystem entries to inspect." },
+              includeFiles: { type: "boolean", description: "Include a compact file list when needed. Defaults to false." },
+            },
+            additionalProperties: false,
+          },
+        },
+      },
       {
         type: "function",
         function: {
@@ -604,6 +632,11 @@ export async function requestNextStep(client, config, messages) {
         toolPayload.stderr,
         toolPayload.error,
         toolPayload.reason,
+        toolPayload.summary ? `Summary: ${toolPayload.summary}` : "",
+        toolPayload.counts ? `Counts: ${JSON.stringify(toolPayload.counts)}` : "",
+        Array.isArray(toolPayload.recommendedReads) && toolPayload.recommendedReads.length
+          ? `Recommended reads: ${toolPayload.recommendedReads.join(", ")}`
+          : "",
         toolPayload.path ? `Path: ${toolPayload.path}` : "",
         Array.isArray(toolPayload.changes)
           ? toolPayload.changes

package/src/model-routing.js

@@ -9,6 +9,16 @@ const COMPLEXITY_KEYWORDS = [
   "apply_patch",
   "edit",
   "large codebase",
+  "codebase",
+  "monorepo",
+  "repository",
+  "cross-file",
+  "multi file",
+  "large repo",
+  "engineering",
+  "entry point",
+  "regression",
+  "root cause",
   "design",
   "review",
   "migrate",
@@ -19,9 +29,35 @@ const COMPLEXITY_KEYWORDS = [
   "docker",
   "ci",
   "github",
+  "system",
+  "systemd",
+  "permission denied",
+  "install",
+  "setup",
+  "toolchain",
+  "conda",
+  "venv",
+  "kubernetes",
+  "nginx",
+  "postgres",
+  "redis",
+  "segfault",
+  "typescript",
+  "python",
+  "rust",
+  "cargo",
+  "golang",
+  "cmake",
+  "gradle",
+  "maven",
 ];
 
 const COMPLEX_ROUTE_HINTS = [
+  /\b(large|big|complex|complicated)\s+(repo|repository|codebase|project|task)\b/i,
+  /\b(multi[- ]file|cross[- ]file|repo[- ]wide|workspace[- ]wide)\b/i,
+  /\b(root cause|regression|failing tests?|fix the build|make it pass)\b/i,
+  /\b(system bug|system problem|permission denied|service failed|daemon|systemd|toolchain|install|setup)\b/i,
+  /\b(conda|venv|python|node|typescript|rust|cargo|golang|java|gradle|maven|cmake|c\+\+)\b.*\b(project|app|tests?|build|compile|fix)\b/i,
   /\blatex\b/i,
   /\btexlive\b/i,
   /\bpdflatex\b/i,
@@ -102,9 +138,10 @@ export function getModelPresets() {
   };
 }
 
-export function scoreTaskComplexity(goal = "") {
+export function scoreTaskComplexity(goal = "", taskProfile = "auto") {
   const text = String(goal).toLowerCase();
   let score = text.length > 600 ? 2 : text.length > 240 ? 1 : 0;
+  if (["large-codebase", "engineering", "codebase"].includes(String(taskProfile || "").toLowerCase())) score += 3;
   for (const keyword of COMPLEXITY_KEYWORDS) {
     if (text.includes(keyword)) score += 1;
   }
@@ -118,7 +155,7 @@ export function normalizeRoutingMode(value) {
   return ROUTING_MODES.includes(value) ? value : "smart";
 }
 
-export function selectModelRoute({ routingMode = "smart", provider = "deepseek", model = "", goal = "" } = {}) {
+export function selectModelRoute({ routingMode = "smart", provider = "deepseek", model = "", goal = "", taskProfile = "auto" } = {}) {
   const mode = normalizeRoutingMode(routingMode);
   const presets = getModelPresets();
 
@@ -129,7 +166,7 @@ export function selectModelRoute({ routingMode = "smart", provider = "deepseek",
       provider: defaults.provider,
       model: model || defaults.model,
       reason: "Local mock route selected for smoke tests and offline UI/API checks.",
-      complexityScore: scoreTaskComplexity(goal),
+      complexityScore: scoreTaskComplexity(goal, taskProfile),
     };
   }
 
@@ -140,7 +177,7 @@ export function selectModelRoute({ routingMode = "smart", provider = "deepseek",
       provider: defaults.provider,
       model: model || defaults.model,
       reason: "Manual provider/model selection.",
-      complexityScore: scoreTaskComplexity(goal),
+      complexityScore: scoreTaskComplexity(goal, taskProfile),
     };
   }
 
@@ -150,7 +187,7 @@ export function selectModelRoute({ routingMode = "smart", provider = "deepseek",
       provider: presets.complex.provider,
       model: presets.complex.model,
       reason: "Complex route selected explicitly.",
-      complexityScore: scoreTaskComplexity(goal),
+      complexityScore: scoreTaskComplexity(goal, taskProfile),
     };
   }
 
@@ -160,11 +197,11 @@ export function selectModelRoute({ routingMode = "smart", provider = "deepseek",
       provider: presets.fast.provider,
       model: presets.fast.model,
       reason: "Fast route selected explicitly.",
-      complexityScore: scoreTaskComplexity(goal),
+      complexityScore: scoreTaskComplexity(goal, taskProfile),
     };
   }
 
-  const complexityScore = scoreTaskComplexity(goal);
+  const complexityScore = scoreTaskComplexity(goal, taskProfile);
   const selected = complexityScore >= 3 ? presets.complex : presets.fast;
   return {
     routingMode: mode,

package/src/task-profiles.js

@@ -3,15 +3,22 @@ export const TASK_PROFILES = {
     id: "auto",
     label: "Auto",
     prompt:
-      "Infer the task type from the user request. Prefer the smallest safe tool sequence that actually completes the work, preserve workspace files, run useful checks, and summarize what changed.",
-    tools: ["browser", "shell", "files", "canvas"],
+      "Infer the task type from the user request. For short tasks, use the smallest safe tool sequence that completes the work. For codebase, system, debugging, migration, or multi-language tasks, switch into the engineering loop: inspect, read/search exact context, patch incrementally, run focused checks, repair failures, and summarize changed files plus residual risks.",
+    tools: ["browser", "shell", "files", "canvas", "inspect_project"],
   },
   code: {
     id: "code",
     label: "Code writing",
     prompt:
-      "Act like a coding agent: understand the request, edit workspace files, run useful safe checks, iterate on failures, and report changed files and residual risks.",
-    tools: ["files", "shell", "sandbox"],
+      "Act like a coding agent across languages: inspect project manifests and conventions, edit workspace files with patches, run useful focused checks, iterate on failures, and report changed files and residual risks.",
+    tools: ["inspect_project", "files", "shell", "sandbox"],
+  },
+  "large-codebase": {
+    id: "large-codebase",
+    label: "Large codebase engineering",
+    prompt:
+      "For large or complicated engineering work, behave like a senior coding agent: inspect_project first unless the repo is already known, read AGENTS/README/manifests, locate entry points and tests, make a small explicit change plan, patch in coherent batches, run the narrowest relevant checks first, escalate to broader checks when stable, and summarize files changed, checks, tradeoffs, and remaining risks.",
+    tools: ["inspect_project", "search_files", "read_file", "apply_patch", "shell", "sandbox", "canvas"],
   },
   writing: {
     id: "writing",
@@ -80,20 +87,37 @@ export const TASK_PROFILES = {
     id: "maintenance",
     label: "System maintenance",
     prompt:
-      "For system maintenance, diagnose first, use Docker for broad installs when available, and follow the configured trust/package policy for host-level changes.",
-    tools: ["shell", "sandbox", "files"],
+      "For system maintenance and system bugs, diagnose first with read-only evidence, use Docker for broad installs/toolchains when available, generate reversible project-local scripts, follow the configured trust/package policy for host-level changes, and stop with clear next actions if stronger permission is needed.",
+    tools: ["shell", "sandbox", "files", "inspect_project"],
   },
 };
 
+const PROFILE_ALIASES = {
+  large: "large-codebase",
+  codebase: "large-codebase",
+  repo: "large-codebase",
+  repository: "large-codebase",
+  engineering: "large-codebase",
+  engineer: "large-codebase",
+};
+
 export function listTaskProfiles() {
   return Object.values(TASK_PROFILES);
 }
 
 export function normalizeTaskProfile(value = "auto") {
   const key = String(value || "auto").trim().toLowerCase();
+  if (PROFILE_ALIASES[key]) return PROFILE_ALIASES[key];
   return TASK_PROFILES[key] ? key : "auto";
 }
 
 export function getTaskProfile(value = "auto") {
   return TASK_PROFILES[normalizeTaskProfile(value)];
 }
+
+export function defaultMaxStepsForProfile(value = "auto") {
+  const profile = normalizeTaskProfile(value);
+  if (profile === "large-codebase") return 36;
+  if (profile === "latex") return 30;
+  return 24;
+}

package/src/web-db.js

@@ -3,7 +3,7 @@ import path from "node:path";
 import { DatabaseSync } from "node:sqlite";
 import { getModelPresets } from "./model-routing.js";
 
-const PREFERENCES_SCHEMA_VERSION = 4;
+const PREFERENCES_SCHEMA_VERSION = 5;
 
 function defaultPreferences(baseDir) {
   const presets = getModelPresets();
@@ -95,6 +95,9 @@ export class WebDatabase {
         if (!Number.isFinite(Number(parsed.maxSteps)) || Number(parsed.maxSteps) < 24) {
           preferences.maxSteps = 24;
         }
+        if ((parsed.preferencesSchemaVersion || 1) < 5) {
+          preferences.taskProfile = "auto";
+        }
         this.savePreferences(preferences);
       }
       return preferences;

package/src/workspace-tools.js

@@ -3,7 +3,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { redactSensitiveText } from "./redaction.js";
 
-export const WORKSPACE_TOOL_NAMES = ["list_files", "read_file", "search_files", "write_file", "apply_patch"];
+export const WORKSPACE_TOOL_NAMES = ["inspect_project", "list_files", "read_file", "search_files", "write_file", "apply_patch"];
 export const WORKSPACE_WRITE_TOOL_NAMES = ["write_file", "apply_patch"];
 
 const MAX_READ_BYTES = 220_000;
@@ -11,8 +11,51 @@ const MAX_WRITE_BYTES = 220_000;
 const MAX_PATCH_BYTES = 260_000;
 const MAX_LIST_ENTRIES = 360;
 const MAX_SEARCH_RESULTS = 80;
+const MAX_INSPECT_ENTRIES = 1400;
 const DEFAULT_MAX_DEPTH = 4;
-const SKIP_DIRS = new Set([".git", "node_modules", ".sessions"]);
+const SKIP_DIRS = new Set([
+  ".git",
+  ".sessions",
+  ".aginti",
+  "node_modules",
+  "dist",
+  "build",
+  "coverage",
+  ".next",
+  ".nuxt",
+  ".cache",
+  ".venv",
+  "venv",
+  "__pycache__",
+]);
+const IMPORTANT_MANIFESTS = new Set([
+  "package.json",
+  "package-lock.json",
+  "pnpm-lock.yaml",
+  "yarn.lock",
+  "tsconfig.json",
+  "jsconfig.json",
+  "vite.config.js",
+  "vite.config.ts",
+  "next.config.js",
+  "pyproject.toml",
+  "requirements.txt",
+  "requirements-dev.txt",
+  "setup.py",
+  "Pipfile",
+  "Cargo.toml",
+  "go.mod",
+  "pom.xml",
+  "build.gradle",
+  "Makefile",
+  "Dockerfile",
+  "docker-compose.yml",
+  "compose.yml",
+  "README.md",
+  "AGENTS.md",
+]);
+const SOURCE_DIR_NAMES = new Set(["src", "app", "lib", "packages", "apps", "bin", "scripts", "server", "client", "public", "docs"]);
+const TEST_DIR_NAMES = new Set(["test", "tests", "__tests__", "spec", "specs", "e2e"]);
 const SENSITIVE_EXTENSIONS = new Set([".key", ".pem", ".p12", ".pfx", ".crt", ".csr"]);
 const SENSITIVE_BASENAMES = new Set([
   ".env",
@@ -183,10 +226,68 @@ export function summarizeWorkspaceTools(config) {
       maxPatchBytes: MAX_PATCH_BYTES,
       maxListEntries: MAX_LIST_ENTRIES,
       maxSearchResults: MAX_SEARCH_RESULTS,
+      maxInspectEntries: MAX_INSPECT_ENTRIES,
     },
   };
 }
 
+function languageForExtension(ext) {
+  const normalized = String(ext || "").toLowerCase();
+  if ([".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs"].includes(normalized)) return "javascript";
+  if ([".py", ".pyw"].includes(normalized)) return "python";
+  if ([".rs"].includes(normalized)) return "rust";
+  if ([".go"].includes(normalized)) return "go";
+  if ([".java", ".kt", ".scala"].includes(normalized)) return "jvm";
+  if ([".c", ".cc", ".cpp", ".h", ".hpp"].includes(normalized)) return "c-cpp";
+  if ([".sh", ".bash", ".zsh"].includes(normalized)) return "shell";
+  if ([".md", ".mdx", ".rst"].includes(normalized)) return "docs";
+  if ([".json", ".yaml", ".yml", ".toml", ".ini"].includes(normalized)) return "config";
+  if ([".html", ".css", ".scss", ".svg"].includes(normalized)) return "web";
+  return normalized ? normalized.slice(1) : "no-extension";
+}
+
+function isLikelyTest(relativePath) {
+  const normalized = normalizeRelative(relativePath).toLowerCase();
+  const base = path.basename(normalized);
+  return (
+    normalized.split("/").some((segment) => TEST_DIR_NAMES.has(segment)) ||
+    /\.(test|spec)\.[cm]?[jt]sx?$/.test(base) ||
+    /^test_.*\.py$/.test(base) ||
+    /_test\.go$/.test(base) ||
+    /test.*\.rs$/.test(base)
+  );
+}
+
+function sortCounts(map, limit = 16) {
+  return [...map.entries()]
+    .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+    .slice(0, limit)
+    .map(([name, count]) => ({ name, count }));
+}
+
+async function readJsonFileSafe(absolutePath) {
+  try {
+    const stat = await fs.stat(absolutePath);
+    if (!stat.isFile() || stat.size > 120_000) return null;
+    const buffer = await fs.readFile(absolutePath);
+    if (buffer.includes(0)) return null;
+    return JSON.parse(buffer.toString("utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function recommendedReads(summary) {
+  const reads = [];
+  for (const name of ["AGENTS.md", "README.md", "package.json", "pyproject.toml", "Cargo.toml", "go.mod"]) {
+    const match = summary.manifestFiles.find((item) => item.path === name || item.path.endsWith(`/${name}`));
+    if (match) reads.push(match.path);
+  }
+  for (const dir of summary.sourceDirs.slice(0, 4)) reads.push(dir.path);
+  for (const file of summary.testFiles.slice(0, 4)) reads.push(file.path);
+  return [...new Set(reads)].slice(0, 12);
+}
+
 async function fileInfo(absolutePath, root) {
   const stat = await fs.stat(absolutePath);
   return {
@@ -316,6 +417,133 @@ async function searchFiles(config, args) {
   };
 }
 
+async function inspectProject(config, args) {
+  const target = resolveWorkspacePath(config, args.path || ".");
+  const maxDepth = Math.min(Math.max(Number(args.maxDepth) || 6, 1), 10);
+  const limit = Math.min(Math.max(Number(args.limit) || MAX_INSPECT_ENTRIES, 80), MAX_INSPECT_ENTRIES);
+  const includeFiles = Boolean(args.includeFiles);
+  const files = [];
+  const sourceDirs = [];
+  const testFiles = [];
+  const manifestFiles = [];
+  const extensionCounts = new Map();
+  const languageCounts = new Map();
+  const topLevel = [];
+  let fileCount = 0;
+  let dirCount = 0;
+  let totalBytes = 0;
+  let truncated = false;
+
+  async function visit(currentPath, depth = 0) {
+    if (fileCount + dirCount >= limit) {
+      truncated = true;
+      return;
+    }
+
+    const stat = await fs.stat(currentPath).catch(() => null);
+    if (!stat) return;
+    const relativePath = normalizeRelative(path.relative(target.root, currentPath));
+    const segments = pathSegments(relativePath);
+    const base = path.basename(currentPath);
+
+    if (relativePath !== ".") {
+      const policy = pathPolicy("read_file", relativePath);
+      if (!policy.allowed) return;
+      if (segments.some((segment) => SKIP_DIRS.has(segment))) return;
+    }
+
+    if (stat.isDirectory()) {
+      dirCount += 1;
+      if (depth === 1) topLevel.push({ path: relativePath, type: "directory" });
+      if (SOURCE_DIR_NAMES.has(base) || TEST_DIR_NAMES.has(base)) {
+        sourceDirs.push({ path: relativePath, kind: TEST_DIR_NAMES.has(base) ? "tests" : "source" });
+      }
+      if (depth >= maxDepth) return;
+      const children = await fs.readdir(currentPath, { withFileTypes: true }).catch(() => []);
+      children.sort((a, b) => a.name.localeCompare(b.name));
+      for (const child of children) {
+        if (SKIP_DIRS.has(child.name)) continue;
+        await visit(path.join(currentPath, child.name), depth + 1);
+        if (truncated) break;
+      }
+      return;
+    }
+
+    if (!stat.isFile()) return;
+    fileCount += 1;
+    totalBytes += stat.size;
+    const ext = path.extname(base).toLowerCase() || "(none)";
+    extensionCounts.set(ext, (extensionCounts.get(ext) || 0) + 1);
+    const language = languageForExtension(ext);
+    languageCounts.set(language, (languageCounts.get(language) || 0) + 1);
+
+    const item = {
+      path: relativePath,
+      size: stat.size,
+      modifiedAt: stat.mtime.toISOString(),
+    };
+    if (depth === 1) topLevel.push({ path: relativePath, type: "file", size: stat.size });
+    if (IMPORTANT_MANIFESTS.has(base) || base.endsWith(".config.js") || base.endsWith(".config.ts")) {
+      manifestFiles.push(item);
+    }
+    if (isLikelyTest(relativePath)) testFiles.push(item);
+    if (includeFiles) files.push(item);
+  }
+
+  await visit(target.absolutePath, 0);
+
+  const packageJsonPath = path.join(target.absolutePath, "package.json");
+  const packageJson = await readJsonFileSafe(packageJsonPath);
+  const packageScripts =
+    packageJson && packageJson.scripts && typeof packageJson.scripts === "object"
+      ? Object.entries(packageJson.scripts)
+          .slice(0, 30)
+          .map(([name, command]) => ({ name, command: redactSensitiveText(String(command)).slice(0, 220) }))
+      : [];
+  const packageManagers = [
+    manifestFiles.some((item) => item.path.endsWith("pnpm-lock.yaml")) ? "pnpm" : "",
+    manifestFiles.some((item) => item.path.endsWith("yarn.lock")) ? "yarn" : "",
+    manifestFiles.some((item) => item.path.endsWith("package-lock.json")) ? "npm" : "",
+    manifestFiles.some((item) => item.path.endsWith("pyproject.toml")) ? "python/pyproject" : "",
+    manifestFiles.some((item) => item.path.endsWith("Cargo.toml")) ? "cargo" : "",
+    manifestFiles.some((item) => item.path.endsWith("go.mod")) ? "go" : "",
+  ].filter(Boolean);
+
+  const summary = {
+    ok: true,
+    toolName: "inspect_project",
+    path: target.relativePath,
+    root: target.root,
+    summary: `${fileCount} files, ${dirCount} directories, ${sortCounts(languageCounts, 5)
+      .map((item) => `${item.name}:${item.count}`)
+      .join(" ")}`,
+    counts: {
+      files: fileCount,
+      directories: dirCount,
+      totalBytes,
+    },
+    truncated,
+    topLevel: topLevel.slice(0, 80),
+    manifestFiles: manifestFiles.slice(0, 80),
+    sourceDirs: sourceDirs.slice(0, 60),
+    testFiles: testFiles.slice(0, 80),
+    extensionCounts: sortCounts(extensionCounts),
+    languageCounts: sortCounts(languageCounts),
+    packageManagers,
+    packageScripts,
+    recommendedReads: [],
+    engineeringHints: [
+      "Read AGENTS/README/manifests before editing.",
+      "Use search_files to locate symbols and tests, then read exact files.",
+      "Use apply_patch for source edits and run the smallest relevant check first.",
+      "If a change spans modules, patch in small batches and verify after each batch.",
+    ],
+  };
+  summary.recommendedReads = recommendedReads(summary);
+  if (includeFiles) summary.files = files.slice(0, limit);
+  return summary;
+}
+
 function compactDiff(relativePath, beforeText, afterText) {
   const beforeLines = String(beforeText || "").split("\n");
   const afterLines = String(afterText || "").split("\n");
@@ -723,6 +951,8 @@ export async function executeWorkspaceTool(toolName, args, config) {
   }
 
   switch (toolName) {
+    case "inspect_project":
+      return inspectProject(config, args);
     case "list_files":
       return listFiles(config, args);
     case "read_file":