@lazyingart/agintiflow 0.9.0 → 0.10.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. This 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,49 @@
+# 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.
+
+## 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazyingart/agintiflow",
-  "version": "0.9.0",
+  "version": "0.10.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,12 @@ function renderTaskProfiles(selected = "auto") {
   taskProfileField.value = profiles.some((profile) => profile.id === selected) ? selected : "auto";
 }
 
+function recommendedMaxStepsForProfile(profile = "auto") {
+  if (profile === "large-codebase") return 36;
+  if (profile === "latex") return 30;
+  return 24;
+}
+
 function renderWrapperStatus(wrappers = lastWrappers) {
   lastWrappers = wrappers || [];
   if (lastWrappers.length === 0) {
@@ -1959,7 +1965,14 @@ sandboxModeField.addEventListener("change", updatePackageWarning);
 packageInstallPolicyField.addEventListener("change", updatePackageWarning);
 allowWrapperToolsField.addEventListener("change", () => renderWrapperStatus());
 preferredWrapperField.addEventListener("change", () => renderWrapperStatus());
-taskProfileField?.addEventListener("change", schedulePreferenceSave);
+taskProfileField?.addEventListener("change", () => {
+  const maxStepsField = document.querySelector("#maxSteps");
+  const recommended = recommendedMaxStepsForProfile(taskProfileField.value);
+  if (maxStepsField && Number(maxStepsField.value || 0) < recommended) {
+    maxStepsField.value = String(recommended);
+  }
+  schedulePreferenceSave();
+});
 
 saveApiKeyButton?.addEventListener("click", async () => {
   const provider = setupProviderField.value || "deepseek";

package/scripts/smoke-coding-tools.js

@@ -86,6 +86,53 @@ 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");
+
+  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 +263,9 @@ try {
         checks: [
           "deepseek_history_repair",
           "deepseek_pro_patch_route",
+          "large_profile_pro_route",
+          "inspect_project",
+          "mock_inspect_project",
           "write_file",
           "duplicate_write_failed",
           "resume_session_write",

package/src/agent-runner.js

@@ -272,7 +272,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()}.`
@@ -285,8 +285,8 @@ function createInitialState(config, sessionId) {
           `Task profile: ${taskProfile.label}. ${taskProfile.prompt}`,
           "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 +310,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()}`
@@ -323,7 +323,7 @@ function createInitialState(config, sessionId) {
           `Task profile: ${taskProfile.label}. ${taskProfile.prompt}`,
           "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.",
         ]
@@ -430,7 +430,7 @@ 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()}`
@@ -631,7 +631,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 +815,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

@@ -14,7 +14,7 @@ import {
   setProviderKey,
   showProjectSession,
 } from "./project.js";
-import { listTaskProfiles } from "./task-profiles.js";
+import { defaultMaxStepsForProfile, listTaskProfiles } from "./task-profiles.js";
 import { promptAndSaveDeepSeekKey, promptHidden, shouldPromptForDeepSeek } from "./auth-onboarding.js";
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -256,7 +256,7 @@ 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 || defaultMaxStepsForProfile(args.taskProfile || (args.latex ? "latex" : "auto")),
   };
 
   if (defaults.sandboxMode === "host") {

package/src/config.js

@@ -4,7 +4,7 @@ import { getProviderDefaults, normalizeRoutingMode, selectModelRoute } from "./m
 import { normalizePackageInstallPolicy, normalizeSandboxMode } from "./command-policy.js";
 import { normalizeWrapperName } from "./tool-wrappers.js";
 import { loadProjectEnv, resolveProjectRoot } from "./project.js";
-import { normalizeTaskProfile } from "./task-profiles.js";
+import { defaultMaxStepsForProfile, normalizeTaskProfile } from "./task-profiles.js";
 
 function parseBoolean(value, fallback) {
   if (value === undefined) return fallback;
@@ -33,11 +33,13 @@ 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);
@@ -56,7 +58,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 +67,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, defaultMaxStepsForProfile(taskProfile)),
     headless: parseBoolean(overrides.headless ?? args.headless ?? process.env.HEADLESS, false),
     allowedDomains: Array.isArray(overrides.allowedDomains)
       ? overrides.allowedDomains

package/src/interactive-cli.js

@@ -5,7 +5,7 @@ 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 { promptAndSaveDeepSeekKey, promptHidden, shouldPromptForDeepSeek } from "./auth-onboarding.js";
 
 const useColor = Boolean(input.isTTY && output.isTTY && process.env.AGINTIFLOW_NO_COLOR !== "1");
@@ -439,7 +439,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 +592,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;
   }

package/src/model-client.js

@@ -81,6 +81,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", {
@@ -194,7 +201,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()}.`
@@ -414,6 +421,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 +629,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",
@@ -22,6 +32,9 @@ const COMPLEXITY_KEYWORDS = [
 ];
 
 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,
   /\blatex\b/i,
   /\btexlive\b/i,
   /\bpdflatex\b/i,
@@ -102,9 +115,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 +132,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 +143,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 +154,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 +164,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 +174,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

@@ -13,6 +13,13 @@ export const TASK_PROFILES = {
       "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"],
   },
+  "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",
     label: "Book/script writing",
@@ -85,15 +92,32 @@ export const TASK_PROFILES = {
   },
 };
 
+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/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":