vigthoria-cli 1.11.12 → 1.11.18

package/dist/utils/api.js

@@ -12,6 +12,8 @@ import WebSocket from 'ws';
 import { buildSemanticContext } from './context-ranker.js';
 import { getChangedFiles } from './workspace-cache.js';
 import { isSubstantiveAgentAnswer, isToolEvidenceStubAnswer } from './agentRunOutcome.js';
+import { joinV3WorkspacePath, normalizeV3WorkspaceRelativePath } from './v3-workspace-path.js';
+import { buildExecutionHints, isPlannerBuildTask, resolvePlannerAgentTimeoutMs } from './requestIntent.js';
 export const VIGTHORIA_HUB_CREDITS_URL = 'https://hub.vigthoria.io/credits';
 export const VIGTHORIA_SERVER_TEMPORARILY_UNAVAILABLE_MESSAGE = 'Vigthoria Server is temporarily not available. Please try again later. If the issue persists, please contact support.';
 export class CLIError extends Error {
@@ -396,6 +398,7 @@ export class APIClient {
             this.ws = null;
         }
     }
+    /** Exposed for Balanced 4B agent routing (local inference :8016). */
     getSelfHostedModelsApiUrl() {
         const configuredUrl = process.env.VIGTHORIA_SELF_HOSTED_MODELS_API_URL
             || this.config.get('selfHostedModelsApiUrl');
@@ -1446,6 +1449,25 @@ export class APIClient {
         // files are provided inline in localWorkspaceSummary.workspaceFiles.
         const effectiveWorkspacePath = serverWorkspacePath || null;
         const needsHydration = !serverWorkspacePath && !!localWorkspacePath;
+        const agentTaskType = resolvedContext.agentTaskType || 'general';
+        const rawPrompt = resolvedContext.rawPrompt || resolvedContext.prompt || '';
+        const executionHints = (resolvedContext.executionHints && typeof resolvedContext.executionHints === 'object')
+            ? { ...resolvedContext.executionHints }
+            : buildExecutionHints(agentTaskType, rawPrompt, {
+                fastPath: resolvedContext.fastPath,
+            });
+        if (!executionHints.task_kind) {
+            executionHints.task_kind = agentTaskType;
+        }
+        if (!executionHints.classify_from) {
+            executionHints.classify_from = rawPrompt;
+        }
+        if (resolvedContext.workflowType === 'analysis_only' || resolvedContext.workflowType === 'full') {
+            executionHints.workflow_type = resolvedContext.workflowType;
+            if (resolvedContext.workflowType === 'analysis_only') {
+                executionHints.requires_file_changes = false;
+            }
+        }
         const payload = {
             workspace: this.buildPublicWorkspaceDescriptor(resolvedContext.workspace, {
                 localWorkspacePath,
@@ -1453,16 +1475,11 @@ export class APIClient {
             }),
             activeFile: resolvedContext.activeFile || null,
             history: resolvedContext.history || [],
-            agentTaskType: resolvedContext.agentTaskType || 'general',
-            rawPrompt: resolvedContext.rawPrompt || resolvedContext.prompt || '',
+            agentTaskType,
+            workflowType: executionHints.workflow_type,
+            rawPrompt,
             contextualPrompt: resolvedContext.contextualPrompt || '',
-            executionHints: {
-                task_kind: resolvedContext.agentTaskType || 'general',
-                requires_file_changes: resolvedContext.agentTaskType === 'analysis' || resolvedContext.agentTaskType === 'verification'
-                    ? false
-                    : undefined,
-                classify_from: resolvedContext.rawPrompt || resolvedContext.prompt || '',
-            },
+            executionHints,
             model: resolvedModel,
             requestedModel,
             requestedModelResolved: resolvedModel,
@@ -1523,6 +1540,9 @@ export class APIClient {
         let json = JSON.stringify(payload);
         if (json.length <= LIMIT)
             return json;
+        if (!/^(1|true|yes)$/i.test(String(process.env.VIGTHORIA_QUIET_CONTEXT_COMPACTION || ''))) {
+            process.stderr.write(`Workspace context is large - sent a focused summary (${Math.round(LIMIT / 1000)}k limit).\n`);
+        }
         if (process.env.DEBUG || process.env.VIGTHORIA_DEBUG) {
             process.stderr.write(`[context] Payload ${json.length} chars exceeds ${LIMIT} limit, compacting...\n`);
         }
@@ -1651,6 +1671,25 @@ export class APIClient {
         const localWorkspaceRef = localWorkspaceName ? `vigthoria://local-workspace/${localWorkspaceName}` : null;
         const rawBrain = resolvedContext.vigthoriaBrain || resolvedContext.vigthoria_brain || null;
         const dedupedBrain = rawBrain ? this.dedupeBrainPayload(rawBrain) : null;
+        const agentTaskType = resolvedContext.agentTaskType || 'general';
+        const rawPrompt = resolvedContext.rawPrompt || resolvedContext.prompt || '';
+        const executionHints = (resolvedContext.executionHints && typeof resolvedContext.executionHints === 'object')
+            ? { ...resolvedContext.executionHints }
+            : buildExecutionHints(agentTaskType, rawPrompt, {
+                fastPath: resolvedContext.fastPath,
+            });
+        if (!executionHints.task_kind) {
+            executionHints.task_kind = agentTaskType;
+        }
+        if (!executionHints.classify_from) {
+            executionHints.classify_from = rawPrompt;
+        }
+        if (resolvedContext.workflowType === 'analysis_only' || resolvedContext.workflowType === 'full') {
+            executionHints.workflow_type = resolvedContext.workflowType;
+            if (resolvedContext.workflowType === 'analysis_only') {
+                executionHints.requires_file_changes = false;
+            }
+        }
         return JSON.stringify({
             workspace: this.buildPublicWorkspaceDescriptor(resolvedContext.workspace, {
                 localWorkspacePath: targetPath,
@@ -1658,16 +1697,11 @@ export class APIClient {
             }),
             activeFile: resolvedContext.activeFile || null,
             history: resolvedContext.history || [],
-            agentTaskType: resolvedContext.agentTaskType || 'general',
-            rawPrompt: resolvedContext.rawPrompt || resolvedContext.prompt || '',
+            agentTaskType,
+            workflowType: executionHints.workflow_type,
+            rawPrompt,
             contextualPrompt: resolvedContext.contextualPrompt || '',
-            executionHints: {
-                task_kind: resolvedContext.agentTaskType || 'general',
-                requires_file_changes: resolvedContext.agentTaskType === 'analysis' || resolvedContext.agentTaskType === 'verification'
-                    ? false
-                    : undefined,
-                classify_from: resolvedContext.rawPrompt || resolvedContext.prompt || '',
-            },
+            executionHints,
             executionSurface: resolvedContext.executionSurface || 'cli',
             clientSurface: resolvedContext.clientSurface || 'cli',
             localMachineCapable: resolvedContext.localMachineCapable !== false,
@@ -2660,7 +2694,7 @@ menu {
         if (!relativePath && String(rawPath || '.').trim() !== '.') {
             return null;
         }
-        const absolutePath = path.resolve(rootPath, relativePath || '.');
+        const absolutePath = relativePath ? joinV3WorkspacePath(rootPath, relativePath) : path.resolve(rootPath);
         const resolvedRoot = path.resolve(rootPath);
         if (absolutePath !== resolvedRoot && !absolutePath.startsWith(resolvedRoot + path.sep)) {
             return null;
@@ -2864,7 +2898,7 @@ menu {
         if (!relativePath) {
             return false;
         }
-        const absolutePath = path.resolve(rootPath, relativePath);
+        const absolutePath = joinV3WorkspacePath(rootPath, relativePath);
         const resolvedRoot = path.resolve(rootPath);
         if (absolutePath !== resolvedRoot && !absolutePath.startsWith(resolvedRoot + path.sep)) {
             this.logger.warn(`Refusing to write V3 file outside workspace: ${rawPath}`);
@@ -2891,7 +2925,7 @@ menu {
         if (!relativePath) {
             return false;
         }
-        const absolutePath = path.resolve(rootPath, relativePath);
+        const absolutePath = joinV3WorkspacePath(rootPath, relativePath);
         const resolvedRoot = path.resolve(rootPath);
         if (absolutePath !== resolvedRoot && !absolutePath.startsWith(resolvedRoot + path.sep)) {
             this.logger.warn(`Refusing to delete V3 file outside workspace: ${rawPath}`);
@@ -2935,56 +2969,7 @@ menu {
         }
     }
     normalizeAgentWorkspaceRelativePath(rawPath, rootPath) {
-        const input = String(rawPath || '').trim().replace(/\\/g, '/').replace(/^\.\//, '');
-        if (!input) {
-            return '';
-        }
-        const safeRelative = (candidate) => {
-            const stripped = String(candidate || '').replace(/^\/+/, '');
-            if (!stripped || /^[a-zA-Z]:\//.test(stripped)) {
-                return '';
-            }
-            const normalized = path.posix.normalize(stripped);
-            if (!normalized || normalized === '.' || normalized === '..' || normalized.startsWith('../') || path.posix.isAbsolute(normalized)) {
-                return '';
-            }
-            return normalized;
-        };
-        const internalWorkspacePatterns = [
-            /^\/?var\/www\/\.vigthoria\/v3-temp\/vig-remote-[^/]+\/(.+)$/i,
-            /^\.vigthoria\/v3-temp\/vig-remote-[^/]+\/(.+)$/i,
-            /^\/?tmp\/vig-remote(?:-server)?-[^/]+\/(.+)$/i,
-            /^\/?tmp\/vig-fork-[^/]+\/(.+)$/i,
-            /^\/?home\/user\/(.+)$/i,
-            /^\/?root\/(.+)$/i,
-        ];
-        for (const pattern of internalWorkspacePatterns) {
-            const match = input.match(pattern);
-            if (match && match[1]) {
-                return safeRelative(match[1]);
-            }
-        }
-        const normalizedRoot = String(rootPath || '').trim().replace(/\\/g, '/').replace(/\/+$/g, '');
-        if (normalizedRoot) {
-            const rootNoLeadingSlash = normalizedRoot.replace(/^\//, '');
-            const rootBase = path.posix.basename(normalizedRoot);
-            const prefixes = [
-                `${normalizedRoot}/`,
-                `${rootNoLeadingSlash}/`,
-                `${rootBase}/`,
-            ];
-            for (const prefix of prefixes) {
-                if (input.startsWith(prefix)) {
-                    return safeRelative(input.slice(prefix.length));
-                }
-            }
-            const embeddedRoot = `/${rootBase}/`;
-            const embeddedIndex = input.indexOf(embeddedRoot);
-            if (embeddedIndex >= 0) {
-                return safeRelative(input.slice(embeddedIndex + embeddedRoot.length));
-            }
-        }
-        return safeRelative(input);
+        return normalizeV3WorkspaceRelativePath(rawPath, rootPath);
     }
     async ensureAgentFrontendPolish(message = '', context = {}) {
         const rootPath = this.resolveAgentTargetPath(context);
@@ -3542,7 +3527,15 @@ document.addEventListener('DOMContentLoaded', () => {
         this.activeV3StreamedFiles = streamedFiles;
         this.activeV3StreamContext = context;
         context.__v3StreamedFiles = streamedFiles;
-        const idleTimeoutMs = context.agentIdleTimeoutMs || DEFAULT_V3_AGENT_IDLE_TIMEOUT_MS;
+        const idleTimeoutMs = (() => {
+            const base = context.agentIdleTimeoutMs || DEFAULT_V3_AGENT_IDLE_TIMEOUT_MS;
+            if (isPlannerBuildTask(String(context.agentTaskType || ''), String(context.rawPrompt || ''))) {
+                const raw = process.env.VIGTHORIA_AGENT_PLANNER_IDLE_TIMEOUT_MS || '300000';
+                const extended = Number.parseInt(raw, 10);
+                return Math.max(base, Number.isFinite(extended) && extended > 0 ? extended : 300000);
+            }
+            return base;
+        })();
         try {
             while (true) {
                 let chunk;
@@ -3562,6 +3555,9 @@ document.addEventListener('DOMContentLoaded', () => {
                             chunk = result;
                             break;
                         }
+                        if (this.pendingV3ClientToolTasks.size > 0) {
+                            continue;
+                        }
                         if (this.hasAgentWorkspaceOutput(context)) {
                             const stalledError = new Error('V3 agent stream stalled after writing workspace output');
                             stalledError.name = 'AbortError';
@@ -3748,7 +3744,9 @@ document.addEventListener('DOMContentLoaded', () => {
             && context.localMachineCapable !== false;
         const rescueEligibleSaaS = preferLocalV3
             && /(saas|dashboard|analytics|billing|team management|activity feed|login screen)/i.test(message);
-        const timeoutMs = baseTimeoutMs > 0 && rescueEligibleSaaS ? Math.min(baseTimeoutMs, 210000) : baseTimeoutMs;
+        const timeoutMs = rescueEligibleSaaS
+            ? Math.min(resolvePlannerAgentTimeoutMs(baseTimeoutMs, String(executionContext.agentTaskType || ''), String(executionContext.rawPrompt || message || '')), 210000)
+            : resolvePlannerAgentTimeoutMs(baseTimeoutMs, String(executionContext.agentTaskType || ''), String(executionContext.rawPrompt || message || ''));
         const maxAttempts = preferLocalV3 ? 2 : 1;
         let lastErrors = [];
         for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {

package/dist/utils/fastAgentRouter.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Vigthoria Balanced 4B — fast agent path classifier (~0.7–2s on local inference :8016).
+ * Regex/trivial detection always wins; LLM router refines ambiguous build prompts only.
+ */
+export type AgentRoutePath = 'template-instant' | 'v3-agent' | 'analysis-only';
+export interface BalancedRouterJson {
+    path?: string;
+    task_kind?: string;
+    taskKind?: string;
+    fast_path?: string | null;
+    fastPath?: string | null;
+    confidence?: number;
+    reason?: string;
+}
+export interface BalancedRouterResult {
+    ok: boolean;
+    raw?: string;
+    parsed?: BalancedRouterJson;
+    latencyMs?: number;
+    model?: string;
+    endpoint?: string;
+    error?: string;
+}
+export declare function parseBalancedRouterJson(raw: string): BalancedRouterJson | null;
+/**
+ * Inference bases for Balanced 4B routing only.
+ * Local developer machines must opt in (env) — avoids ~1.5s localhost probe on every Windows turn.
+ */
+export declare function getInferenceRouterBaseUrls(selfHostedUrl: string | null): string[];
+export declare function isFastInferenceRouterAvailable(selfHostedUrl: string | null, timeoutMs?: number): Promise<boolean>;
+export declare function routeWithBalanced4b(prompt: string, selfHostedUrl: string | null, options?: {
+    timeoutMs?: number;
+}): Promise<BalancedRouterResult>;
+export declare function shouldUseBalancedRouter(prompt: string, regexTaskKind?: string): boolean;

package/dist/utils/fastAgentRouter.js

@@ -0,0 +1,171 @@
+/**
+ * Vigthoria Balanced 4B — fast agent path classifier (~0.7–2s on local inference :8016).
+ * Regex/trivial detection always wins; LLM router refines ambiguous build prompts only.
+ */
+const ROUTER_SYSTEM = `You are Vigthoria Agent Router. Reply with ONE JSON object only. No markdown, no HTML, no code fences.
+
+Paths:
+- template-instant: single trivial HTML page (hello world, one popup, simple static site) — use Template Service
+- v3-agent: multi-file builds, games, refactors, complex implementation
+- analysis-only: read-only review/audit/explain, no workspace writes
+
+task_kind: web-build | game-build | implementation | analysis | debugging
+fast_path: "template-instant" or null
+
+Example: {"path":"template-instant","task_kind":"web-build","fast_path":"template-instant","confidence":0.95,"reason":"trivial html popup page"}`;
+const INFERENCE_MODEL_IDS = [
+    'vigthoria-balanced-4b',
+    'vigthoria-v3-balanced-4b',
+];
+function normalizePath(value) {
+    const p = String(value || '').trim().toLowerCase();
+    if (p === 'template-instant' || p === 'template' || p === 'html-template') {
+        return 'template-instant';
+    }
+    if (p === 'analysis-only' || p === 'analysis') {
+        return 'analysis-only';
+    }
+    if (p === 'v3-agent' || p === 'v3' || p === 'agent') {
+        return 'v3-agent';
+    }
+    return null;
+}
+export function parseBalancedRouterJson(raw) {
+    const text = String(raw || '').trim();
+    if (!text)
+        return null;
+    const start = text.indexOf('{');
+    if (start < 0)
+        return null;
+    let depth = 0;
+    for (let i = start; i < text.length; i += 1) {
+        if (text[i] === '{')
+            depth += 1;
+        if (text[i] === '}') {
+            depth -= 1;
+            if (depth === 0) {
+                try {
+                    return JSON.parse(text.slice(start, i + 1));
+                }
+                catch {
+                    return null;
+                }
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Inference bases for Balanced 4B routing only.
+ * Local developer machines must opt in (env) — avoids ~1.5s localhost probe on every Windows turn.
+ */
+export function getInferenceRouterBaseUrls(selfHostedUrl) {
+    const urls = [
+        process.env.VIGTHORIA_INFERENCE_URL,
+        process.env.VIGTHORIA_SELF_HOSTED_MODELS_API_URL,
+        selfHostedUrl,
+    ].filter(Boolean).map((u) => String(u).replace(/\/$/, ''));
+    const allowLocalhost = process.env.VIGTHORIA_ENABLE_LOCAL_INFERENCE_ROUTER === '1'
+        || process.env.VIGTHORIA_AGENT_LLM_ROUTER === '1'
+        || process.platform === 'linux';
+    if (allowLocalhost) {
+        urls.push('http://127.0.0.1:8016');
+    }
+    return [...new Set(urls)];
+}
+let inferenceHealthCache = null;
+export async function isFastInferenceRouterAvailable(selfHostedUrl, timeoutMs = 400) {
+    if (process.env.VIGTHORIA_AGENT_LLM_ROUTER === '0') {
+        return false;
+    }
+    const now = Date.now();
+    if (inferenceHealthCache && now - inferenceHealthCache.checkedAt < 60_000) {
+        return inferenceHealthCache.ok;
+    }
+    for (const base of getInferenceRouterBaseUrls(selfHostedUrl)) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const response = await fetch(`${base}/health`, { signal: controller.signal });
+            clearTimeout(timer);
+            if (response.ok) {
+                inferenceHealthCache = { ok: true, checkedAt: now };
+                return true;
+            }
+        }
+        catch {
+            clearTimeout(timer);
+        }
+    }
+    inferenceHealthCache = { ok: false, checkedAt: now };
+    return false;
+}
+export async function routeWithBalanced4b(prompt, selfHostedUrl, options = {}) {
+    const timeoutMs = options.timeoutMs ?? Number.parseInt(process.env.VIGTHORIA_AGENT_ROUTER_TIMEOUT_MS || '8000', 10);
+    const bases = getInferenceRouterBaseUrls(selfHostedUrl);
+    let lastError = 'Inference router unreachable';
+    for (const base of bases) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        const started = Date.now();
+        for (const model of INFERENCE_MODEL_IDS) {
+            try {
+                const response = await fetch(`${base}/v1/chat/completions`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        model,
+                        messages: [
+                            { role: 'system', content: ROUTER_SYSTEM },
+                            { role: 'user', content: String(prompt || '').slice(0, 1200) },
+                        ],
+                        max_tokens: 96,
+                        temperature: 0,
+                        stream: false,
+                    }),
+                    signal: controller.signal,
+                });
+                clearTimeout(timer);
+                const payload = await response.json().catch(() => null);
+                if (!response.ok) {
+                    lastError = `HTTP ${response.status} from ${base}`;
+                    continue;
+                }
+                const raw = payload?.choices?.[0]?.message?.content || '';
+                const parsed = parseBalancedRouterJson(raw);
+                if (!parsed) {
+                    lastError = 'Router returned non-JSON';
+                    continue;
+                }
+                return {
+                    ok: true,
+                    raw,
+                    parsed,
+                    latencyMs: Date.now() - started,
+                    model,
+                    endpoint: base,
+                };
+            }
+            catch (err) {
+                lastError = err instanceof Error ? err.message : String(err);
+            }
+        }
+        clearTimeout(timer);
+    }
+    return { ok: false, error: lastError };
+}
+export function shouldUseBalancedRouter(prompt, regexTaskKind = '') {
+    if (process.env.VIGTHORIA_AGENT_LLM_ROUTER === '0') {
+        return false;
+    }
+    const kind = String(regexTaskKind || '').toLowerCase();
+    // Regex already resolved clear build families — LLM must not override (e.g. landing → implementation).
+    if (kind === 'web-build' || kind === 'game-build') {
+        return false;
+    }
+    const text = String(prompt || '').trim();
+    if (text.length > 700 || text.length < 12) {
+        return false;
+    }
+    return true;
+}

package/dist/utils/requestIntent.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared prompt intent detection for CLI routing, V3 hints, and rescue gating.
+ * Keep aligned with V3-Code-Agent/agent.py _classify_request heuristics.
+ */
+/** Strip CLI-appended platform / mode shaping so it cannot flip quality profiles. */
+export declare function stripExecutionShaping(prompt: string): string;
+export declare function hasBuildVerb(prompt: string): boolean;
+export declare function hasArtifactNoun(prompt: string): boolean;
+export declare function hasGameIntent(prompt: string): boolean;
+export declare function isContinueOrRetryPrompt(prompt: string): boolean;
+export declare function hasWebPageIntent(prompt: string): boolean;
+export declare function isTrivialHtmlPageRequest(prompt: string): boolean;
+export declare function hasCloneBuildIntent(prompt: string): boolean;
+export declare function hasExplicitWriteIntent(prompt: string): boolean;
+export declare function taskRequiresWorkspaceChanges(prompt: string): boolean;
+export declare function hasAnalyzeAndBuildIntent(prompt: string): boolean;
+export declare function inferAgentTaskType(prompt: string): string;
+export declare function shouldSkipAnalysisRescue(liveOutcome: {
+    tasksTotal?: number;
+    changedFileCount?: number;
+    requiresWorkspaceChanges?: boolean;
+}): boolean;
+export declare function isPlannerBuildTask(agentTaskType: string, prompt: string): boolean;
+export declare function resolvePlannerAgentTimeoutMs(baseTimeoutMs: number, agentTaskType: string, prompt: string): number;
+/** V3 workflow mode: suppress write path when the user did not ask for file changes. */
+export declare function resolveWorkflowType(agentTaskType: string, prompt: string): 'analysis_only' | 'full';
+export declare function buildExecutionHints(agentTaskType: string, prompt: string, options?: {
+    fastPath?: string;
+}): {
+    task_kind: string;
+    requires_file_changes: boolean | undefined;
+    classify_from: string;
+    workflow_type: 'analysis_only' | 'full';
+    fast_path?: string;
+};

package/dist/utils/requestIntent.js

@@ -0,0 +1,188 @@
+/**
+ * Shared prompt intent detection for CLI routing, V3 hints, and rescue gating.
+ * Keep aligned with V3-Code-Agent/agent.py _classify_request heuristics.
+ */
+const CLI_SHAPING_BLOCK = /(?:^|\n\n)Platform:\s*(?:Windows|macOS|Linux)\.[\s\S]*?(?=\n\n[A-Z][^\n]{0,40}:|\s*$)/i;
+const READONLY_SHAPING_BLOCK = /(?:^|\n\n)(?:Read-only analysis mode is active\.|Diagnostic mode is active\.)[\s\S]*?(?=\n\n[A-Z][^\n]{0,40}:|\s*$)/i;
+const BUILD_VERBS = /\b(build|create|make|implement|complete|fix|repair|edit|modify|write|generate|add|finish|scaffold|develop|update|change|refactor|let's|let us|we need|we should|erstelle|erstellen|schreib|schreibe|bearbeite)\b/i;
+const ARTIFACT_NOUNS = /\b(file|files|project|game|spiel|app|website|html5|frontend|component|feature|code|workspace|repo|clone|replica|remake|page|site|canvas|sprite|level|levels|enemy|enemies|character|npc|world|scene|script|module|api|database|config|landing|dashboard|platformer|arcade|playable|collectible|scoreboard|leaderboard|pitfall|pacman|rogue|html|css|javascript|typescript)\b/i;
+/** Canvas/playable games only — bare "html5" or "website" must NOT match. */
+const GAME_INTENT = /\b(game|spiel|playable|html5\s+(?:game|canvas)|html5\s+game|canvas\s+game|game\s+canvas|arcade|platformer|side[- ]?scroller|pitfall|pac[- ]?man|tetris|snake|breakout|pong|roguelike|metroidvania|tower\s+defense|clone\s+of\s+(?:a\s+)?(?:game|pitfall|pac|mario|zelda|arcade)|gameplay|collectible|boss\s+fight|level\s+design|sprite\s+sheet|wild\s+(?:boar|pig|forest)|forest\s+pig)\b/i;
+const WEB_PAGE_INTENT = /\b(website|web\s*site|webpage|web\s*page|landing\s+page|home\s*page|index\.html|html\s+page|static\s+page|single\s+page|popup|alert|modal|hello\s+world)\b/i;
+const CLONE_BUILD = /\bclone\s+of\b|\b(build|create|make)\s+(?:a|an|the|us|me)?\s*(?:clone|replica|remake|port)\b/i;
+const READ_ONLY_INTENT = /\b(analy[sz]e|analyse|analysis|audit|review|inspect|proof|understand|summari[sz]e|scan|read[\s-]?only|where we left|what is|how does|show me|tell me|identify\s+gaps?|gap\s+analysis|production\s+blockers?)\b/i;
+const EXPLICIT_WRITE_VERBS = /\b(implement|write|edit|modify|update|fix|repair|create|build|generate|scaffold|deploy|refactor|develop|integrate)\b/i;
+const TRIVIAL_HTML_PAGE = /\b(hello\s*world|simple\s+(?:html|web|page|site)|html5\s+website|html\s+5\s+website|popup|alert\s*\(|show\s+a\s+popup|one\s+page|single\s+html)\b/i;
+/** Strip CLI-appended platform / mode shaping so it cannot flip quality profiles. */
+export function stripExecutionShaping(prompt) {
+    return String(prompt || '')
+        .replace(CLI_SHAPING_BLOCK, '')
+        .replace(READONLY_SHAPING_BLOCK, '')
+        .trim();
+}
+export function hasBuildVerb(prompt) {
+    return BUILD_VERBS.test(stripExecutionShaping(prompt));
+}
+export function hasArtifactNoun(prompt) {
+    return ARTIFACT_NOUNS.test(stripExecutionShaping(prompt));
+}
+/** Game clones require a game target — generic "clone of X" must not imply game-build. */
+const GAME_CLONE_TARGET = /\bclone\s+of\s+(?:a\s+)?(?:the\s+)?(?:game|pitfall|pac[- ]?man|mario|zelda|tetris|snake|arcade|spiel)\b/i;
+export function hasGameIntent(prompt) {
+    const text = stripExecutionShaping(prompt);
+    if (GAME_INTENT.test(text)) {
+        return true;
+    }
+    if (GAME_CLONE_TARGET.test(text)) {
+        return true;
+    }
+    if (CLONE_BUILD.test(text) && /\b(game|spiel|pitfall|pacman|arcade|platformer|playable|canvas)\b/i.test(text)) {
+        return true;
+    }
+    return false;
+}
+export function isContinueOrRetryPrompt(prompt) {
+    const text = stripExecutionShaping(prompt).toLowerCase();
+    return /\b(continue\s+(?:the\s+)?(?:previous|last|current)\s+(?:agent\s+)?run|\/retry|\/continue|resume\s+(?:the\s+)?(?:failed|unfinished)|planner\s+produced\s+\d+\s+execution\s+tasks)\b/i.test(text);
+}
+export function hasWebPageIntent(prompt) {
+    const text = stripExecutionShaping(prompt);
+    return WEB_PAGE_INTENT.test(text) || /\bhtml5\s+website\b/i.test(text);
+}
+export function isTrivialHtmlPageRequest(prompt) {
+    const text = stripExecutionShaping(prompt);
+    if (isContinueOrRetryPrompt(prompt)) {
+        return false;
+    }
+    if (!hasBuildVerb(prompt) && !/\b(write|create|make|show)\b/i.test(text)) {
+        return false;
+    }
+    if (hasGameIntent(prompt)) {
+        return false;
+    }
+    if (text.length > 420) {
+        return false;
+    }
+    if (/\b(multi[- ]?page|full\s+saas|dashboard|e[\s-]?commerce|auth|database|backend|api|microservice)\b/i.test(text)) {
+        return false;
+    }
+    return TRIVIAL_HTML_PAGE.test(text)
+        || (hasWebPageIntent(prompt) && /\b(html5|html5\s+website|website|popup|hello\s*world)\b/i.test(text));
+}
+export function hasCloneBuildIntent(prompt) {
+    return CLONE_BUILD.test(stripExecutionShaping(prompt)) && hasBuildVerb(prompt);
+}
+export function hasExplicitWriteIntent(prompt) {
+    const text = stripExecutionShaping(prompt);
+    return (BUILD_VERBS.test(text) && ARTIFACT_NOUNS.test(text))
+        || hasCloneBuildIntent(prompt)
+        || (BUILD_VERBS.test(text) && hasGameIntent(prompt));
+}
+export function taskRequiresWorkspaceChanges(prompt) {
+    const text = String(prompt || '').trim();
+    const shaped = stripExecutionShaping(text);
+    const readOnlyIntent = READ_ONLY_INTENT.test(shaped);
+    const explicitWriteIntent = hasExplicitWriteIntent(text);
+    if (readOnlyIntent && !explicitWriteIntent) {
+        return false;
+    }
+    return explicitWriteIntent;
+}
+export function hasAnalyzeAndBuildIntent(prompt) {
+    const text = stripExecutionShaping(prompt);
+    return /\b(analy[sz]e|analyse)\b/i.test(text)
+        && /\b(complete|finish|fix|implement|build|repair|missing\s+elements?)\b/i.test(text)
+        && hasExplicitWriteIntent(prompt);
+}
+export function inferAgentTaskType(prompt) {
+    const text = stripExecutionShaping(prompt);
+    if (hasAnalyzeAndBuildIntent(prompt)) {
+        if (hasGameIntent(prompt)) {
+            return 'game-build';
+        }
+        if (hasWebPageIntent(prompt)) {
+            return 'web-build';
+        }
+        return 'implementation';
+    }
+    if (/\b(inspect|analyze|analyse|audit|review|find|diagnose|debug|trace|compare|diff|check|investigate)\b/i.test(text)
+        && !hasExplicitWriteIntent(prompt)) {
+        return 'debugging';
+    }
+    if (/\b(analy[sz]e|analyse|audit|review|inspect|identify\s+gaps?|gap\s+analysis|production\s+blockers?|read[\s-]?only)\b/i.test(text)
+        && !hasExplicitWriteIntent(prompt)) {
+        return 'analysis';
+    }
+    if (hasBuildVerb(prompt) && !/\b(analy[sz]e|analyse|audit|review|inspect)\b/i.test(text)) {
+        if (hasGameIntent(prompt)) {
+            return 'game-build';
+        }
+        if (hasWebPageIntent(prompt)) {
+            return 'web-build';
+        }
+        return 'implementation';
+    }
+    return 'analysis';
+}
+export function shouldSkipAnalysisRescue(liveOutcome) {
+    if (liveOutcome.requiresWorkspaceChanges) {
+        return true;
+    }
+    if ((liveOutcome.tasksTotal || 0) > 0) {
+        return true;
+    }
+    if ((liveOutcome.changedFileCount || 0) > 0) {
+        return true;
+    }
+    return false;
+}
+export function isPlannerBuildTask(agentTaskType, prompt) {
+    const kind = String(agentTaskType || '').toLowerCase();
+    if (isTrivialHtmlPageRequest(prompt)) {
+        return false;
+    }
+    if (/^(game-build|web-build|implementation|build|repair|refactor-build)$/.test(kind)) {
+        return true;
+    }
+    return hasExplicitWriteIntent(prompt) && !READ_ONLY_INTENT.test(stripExecutionShaping(prompt));
+}
+export function resolvePlannerAgentTimeoutMs(baseTimeoutMs, agentTaskType, prompt) {
+    if (!isPlannerBuildTask(agentTaskType, prompt)) {
+        return baseTimeoutMs;
+    }
+    const raw = process.env.VIGTHORIA_AGENT_PLANNER_TIMEOUT_MS || process.env.V3_AGENT_PLANNER_TIMEOUT_MS || '900000';
+    const extended = Number.parseInt(raw, 10);
+    const floor = Number.isFinite(extended) && extended > 0 ? extended : 900000;
+    return Math.max(baseTimeoutMs, floor);
+}
+/** V3 workflow mode: suppress write path when the user did not ask for file changes. */
+export function resolveWorkflowType(agentTaskType, prompt) {
+    if (hasAnalyzeAndBuildIntent(prompt)) {
+        return 'full';
+    }
+    if (!taskRequiresWorkspaceChanges(prompt)) {
+        return 'analysis_only';
+    }
+    const kind = String(agentTaskType || '').toLowerCase();
+    if (kind === 'analysis' || kind === 'debugging' || kind === 'verification') {
+        return 'analysis_only';
+    }
+    return 'full';
+}
+export function buildExecutionHints(agentTaskType, prompt, options = {}) {
+    const workflowType = resolveWorkflowType(agentTaskType, prompt);
+    const kind = String(agentTaskType || 'general').toLowerCase();
+    const hints = {
+        task_kind: kind,
+        requires_file_changes: workflowType === 'analysis_only' ? false : undefined,
+        classify_from: String(prompt || ''),
+        workflow_type: workflowType,
+    };
+    if (options.fastPath) {
+        hints.fast_path = options.fastPath;
+    }
+    else if (isTrivialHtmlPageRequest(prompt)) {
+        hints.fast_path = 'template-instant';
+    }
+    return hints;
+}