scalix 1.0.0 → 1.2.0

package/dist/grounding-checker.js

@@ -0,0 +1,154 @@
+export const GROUNDING_DEFAULTS = {
+    enabled: true,
+    maxNudges: 1,
+    ungroundedThreshold: 0.5,
+    minClaimsToCheck: 2,
+};
+const TRIVIAL_FILES = new Set([
+    'README.md', 'LICENSE', 'package.json', 'tsconfig.json',
+    'Cargo.toml', 'go.mod', 'Makefile', 'Dockerfile',
+    '.gitignore', '.env', '.env.example',
+]);
+const FILE_PATH_RE = /(?:^|[\s`"'(])([.\w][\w./-]*\/[\w./-]+\.\w{1,10})(?=[\s`"'),.:;]|$)/gm;
+const FUNC_CALL_RE = /\b([a-zA-Z_]\w{2,})\s*\(/g;
+const FUNC_DESC_RE = /\b(?:function|method|def|fn|func|handler|callback)\s+([a-zA-Z_]\w{2,})\b/gi;
+const CLASS_RE = /\b(?:class|interface|type|struct|enum|trait)\s+([A-Z]\w{2,})\b/g;
+const LINE_NUM_RE = /\b(?:line\s+|:)(\d{2,5})\b/gi;
+const IMPORT_RE = /(?:import|from|require)\s*\(?['"]([^'"]+)['"]\)?/g;
+function surroundingContext(text, pos, radius = 60) {
+    const start = Math.max(0, pos - radius);
+    const end = Math.min(text.length, pos + radius);
+    return text.slice(start, end).replace(/\n/g, ' ').trim();
+}
+export function extractCodeClaims(text) {
+    const seen = new Set();
+    const claims = [];
+    function add(type, value, position) {
+        const key = `${type}:${value}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        claims.push({ type, value, context: surroundingContext(text, position), position });
+    }
+    // File paths (must contain a / to avoid single-word matches)
+    for (const m of text.matchAll(FILE_PATH_RE)) {
+        const val = m[1];
+        const basename = val.split('/').pop() || val;
+        if (TRIVIAL_FILES.has(basename) || TRIVIAL_FILES.has(val))
+            continue;
+        add('file_path', val, m.index + m[0].indexOf(val));
+    }
+    // Function calls — foo()
+    for (const m of text.matchAll(FUNC_CALL_RE)) {
+        const name = m[1];
+        if (name.length > 50 || /^(if|for|while|switch|return|new|typeof|catch|throw|await|async|const|let|var|function|class|import|export|from|this|self|true|false|null|undefined|console|process|require|module)$/.test(name))
+            continue;
+        add('function_name', name, m.index);
+    }
+    // Function descriptions — "the handleSubmit function"
+    for (const m of text.matchAll(FUNC_DESC_RE)) {
+        add('function_name', m[1], m.index);
+    }
+    // Class/interface/type names
+    for (const m of text.matchAll(CLASS_RE)) {
+        if (m[1].length > 50)
+            continue;
+        add('class_name', m[1], m.index);
+    }
+    // Line numbers (only >9 to avoid trivial matches)
+    for (const m of text.matchAll(LINE_NUM_RE)) {
+        const num = parseInt(m[1], 10);
+        if (num < 10)
+            continue;
+        add('line_number', m[1], m.index);
+    }
+    // Import references
+    for (const m of text.matchAll(IMPORT_RE)) {
+        if (m[1].startsWith('.')) {
+            add('import', m[1], m.index);
+        }
+    }
+    return claims;
+}
+function buildGroundingCorpus(messages) {
+    const parts = [];
+    for (const m of messages) {
+        if (m.role === 'tool' && m.content) {
+            parts.push(typeof m.content === 'string' ? m.content : JSON.stringify(m.content));
+        }
+        if (m.role === 'assistant' && m.tool_calls) {
+            for (const tc of m.tool_calls) {
+                parts.push(tc.function.arguments);
+            }
+        }
+    }
+    return parts.join('\n');
+}
+export function checkGrounding(claims, messages, threshold = GROUNDING_DEFAULTS.ungroundedThreshold, minClaims = GROUNDING_DEFAULTS.minClaimsToCheck) {
+    if (claims.length === 0) {
+        return { claims, groundedClaims: [], ungroundedClaims: [], groundingRatio: 1, needsVerification: false };
+    }
+    const corpus = buildGroundingCorpus(messages);
+    const corpusLower = corpus.toLowerCase();
+    const grounded = [];
+    const ungrounded = [];
+    for (const claim of claims) {
+        let found = false;
+        switch (claim.type) {
+            case 'file_path': {
+                if (corpus.includes(claim.value)) {
+                    found = true;
+                }
+                else {
+                    const basename = claim.value.split('/').pop();
+                    if (corpus.includes(basename))
+                        found = true;
+                }
+                break;
+            }
+            case 'function_name':
+            case 'class_name':
+            case 'variable_name': {
+                found = corpus.includes(claim.value);
+                break;
+            }
+            case 'line_number': {
+                const escaped = claim.value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+                const linePattern = new RegExp(`(?:^|\\n)\\s*${escaped}\\t|:${escaped}[:\\s]`, 'm');
+                found = linePattern.test(corpus);
+                break;
+            }
+            case 'import': {
+                found = corpus.includes(claim.value);
+                break;
+            }
+            default:
+                found = corpusLower.includes(claim.value.toLowerCase());
+        }
+        if (found)
+            grounded.push(claim);
+        else
+            ungrounded.push(claim);
+    }
+    const ratio = grounded.length / claims.length;
+    const needsVerification = ratio < threshold && ungrounded.length >= minClaims;
+    return { claims, groundedClaims: grounded, ungroundedClaims: ungrounded, groundingRatio: ratio, needsVerification };
+}
+export function formatGroundingNudge(result) {
+    const items = result.ungroundedClaims.slice(0, 5).map((c) => {
+        switch (c.type) {
+            case 'file_path': return `- File "${c.value}" (not read in this conversation)`;
+            case 'function_name': return `- Function "${c.value}" (not seen in any tool output)`;
+            case 'class_name': return `- Type/class "${c.value}" (not seen in any tool output)`;
+            case 'line_number': return `- Line ${c.value} (not verified by reading the file)`;
+            case 'import': return `- Import "${c.value}" (not verified)`;
+            default: return `- "${c.value}" (not verified)`;
+        }
+    });
+    return [
+        '[GROUNDING CHECK] Your response references code elements that were not verified by reading the actual source:',
+        ...items,
+        'Please use read_file, search_files, or find_files to verify these references before presenting them as facts.',
+        'If you are uncertain about a path or name, say so explicitly rather than guessing.',
+    ].join('\n');
+}

package/dist/headless.js

@@ -1,5 +1,6 @@
 import readline from 'node:readline';
 import fs from 'node:fs/promises';
+import path from 'node:path';
 import { execSync } from 'node:child_process';
 import { createAgent } from './agent.js';
 import { defaultTools } from './tools.js';
@@ -8,13 +9,14 @@ import { webTools } from './tools-web.js';
 import { advancedTools } from './tools-advanced.js';
 import { visionTools } from './tools-vision.js';
 import { voiceTools } from './tools-voice.js';
-import { browserTools } from './tools-browser.js';
+import { browserTools, closeBrowser } from './tools-browser.js';
 import { loadMcpServices } from './mcp.js';
 import { costTracker } from './cost-tracker.js';
 import { saveSession, loadSession, listSessions, generateSessionId } from './sessions.js';
 import { logger } from './logger.js';
 import { DEFAULT_MODELS, DEFAULT_INSTRUCTIONS, ENV_API_KEY, ENV_MODEL, ENV_BASE_URL, HEADLESS_DEFAULTS, fetchModelSpecs } from './constants.js';
 import { loadConfig, DEFAULT_LIMITS } from './settings.js';
+import { checkForUpdate, getUpdateBanner } from './update-checker.js';
 import { getModeDescription, PERMISSION_MODES, setSandboxRoot } from './sandbox.js';
 import { collectGitInfo, gitInfoToContext } from './git-context.js';
 import { loadMemory, autoDetectConventions, saveMemory, memoryToContext, addNote, detectCorrection } from './project-memory.js';
@@ -26,15 +28,20 @@ import { hooksSummary } from './hooks.js';
 import { spawnSubAgent, pickCheapestModel } from './sub-agent.js';
 import { createCheckpoint, undoLastCheckpoint, listCheckpoints } from './git-undo.js';
 import { runIpcServer } from './ipc-server.js';
-function shortModel(m) {
+import { AgentRegistry } from './agent-registry.js';
+export function shortModel(m) {
     return m.split('/').pop().replace(/:free$/, '').replace(/-instruct$/, '');
 }
-function parseArgs() {
+export function parseArgs() {
     const args = process.argv.slice(2);
     let mode = 'interactive';
     let prompt;
     let output;
     let format;
+    let permissionMode;
+    let outputSchema;
+    let worktree = false;
+    let worktreeName;
     for (let i = 0; i < args.length; i++) {
         if (args[i] === 'run' && i + 1 < args.length) {
             mode = 'run';
@@ -49,12 +56,32 @@ function parseArgs() {
             format = args[i + 1];
             i++;
         }
+        else if (args[i] === '--output-format' && i + 1 < args.length) {
+            format = args[i + 1];
+            i++;
+        }
+        else if (args[i] === '--output-schema' && i + 1 < args.length) {
+            outputSchema = args[i + 1];
+            format = 'json-schema';
+            i++;
+        }
+        else if (args[i] === '--mode' && i + 1 < args.length) {
+            permissionMode = args[i + 1];
+            i++;
+        }
         else if (args[i] === '--pipe' || args[i] === '-p') {
             mode = 'pipe';
         }
         else if (args[i] === '--ipc') {
             mode = 'ipc';
         }
+        else if (args[i] === '--worktree' || args[i] === '-w') {
+            worktree = true;
+            if (i + 1 < args.length && !args[i + 1].startsWith('-') && args[i + 1] !== 'run') {
+                worktreeName = args[i + 1];
+                i++;
+            }
+        }
         else if (args[i] === '--help' || args[i] === '-h') {
             console.log(`
 Scalix - Headless Mode
@@ -71,7 +98,10 @@ Options:
   --pipe, -p         Read prompt from stdin (for piping)
   --ipc              IPC server mode for VS Code extension integration
   --output <file>    Write result to file instead of stdout
-  --format <fmt>     Output format: text (default), json, patch, markdown
+  --format <fmt>     Output format: text (default), json, json-schema, patch, markdown
+  --output-format    Alias for --format
+  --output-schema    Path to JSON schema file (implies --format json-schema)
+  --worktree, -w     Run in an isolated git worktree (optional: --worktree <name>)
   --help, -h         Show this help
 `);
             process.exit(0);
@@ -80,7 +110,7 @@ Options:
     if (!process.stdin.isTTY && mode === 'interactive') {
         mode = 'pipe';
     }
-    return { mode, prompt, output, format };
+    return { mode, prompt, output, format, permissionMode, outputSchema, worktree, worktreeName };
 }
 async function buildEnhancedInstructions() {
     let base = DEFAULT_INSTRUCTIONS;
@@ -101,7 +131,7 @@ async function buildEnhancedInstructions() {
     const ctx = await buildProjectContext(cwd);
     return contextToInstructions(base, ctx);
 }
-async function runSinglePrompt(prompt, output, format) {
+async function runSinglePrompt(prompt, output, format, outputSchemaPath) {
     const apiKey = process.env[ENV_API_KEY];
     if (!apiKey) {
         console.error('Error: SCALIX_API_KEY is not set.\nSet it via: export SCALIX_API_KEY=sk-...\nOr run the interactive setup: scalix');
@@ -112,6 +142,13 @@ async function runSinglePrompt(prompt, output, format) {
     const baseUrl = process.env[ENV_BASE_URL] || config.baseUrl;
     // Fetch model specs from API (non-blocking — uses built-in/user-defined as fallback)
     fetchModelSpecs(baseUrl, apiKey).catch(() => { });
+    if (!process.env.NO_UPDATE_NOTIFIER && !config.disableUpdateCheck) {
+        checkForUpdate().then(() => {
+            const banner = getUpdateBanner();
+            if (banner)
+                process.stderr.write(banner + '\n');
+        }).catch(() => { });
+    }
     const envModels = process.env[ENV_MODEL]
         ? process.env[ENV_MODEL].split(',').map((m) => m.trim()).filter(Boolean)
         : [];
@@ -126,13 +163,30 @@ async function runSinglePrompt(prompt, output, format) {
     const pluginTools = getPluginTools(plugins);
     const allTools = [...defaultTools, ...extraTools, ...webTools, ...advancedTools, ...visionTools, ...voiceTools, ...browserTools, ...mcpTools, ...pluginTools];
     const instructions = await buildEnhancedInstructions();
+    let outputSchema;
+    if (outputSchemaPath) {
+        try {
+            const schemaContent = await fs.readFile(outputSchemaPath, 'utf-8');
+            const parsed = JSON.parse(schemaContent);
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed) || !parsed.type) {
+                console.error(`Invalid JSON schema: must be an object with a "type" property`);
+                process.exit(1);
+            }
+            outputSchema = parsed;
+        }
+        catch (err) {
+            console.error(`Error loading output schema from ${outputSchemaPath}: ${err.message}`);
+            process.exit(1);
+        }
+    }
+    const outputFormat = (format === 'json' || format === 'json-schema') ? format : undefined;
     const agent = createAgent({
         apiKey,
         baseUrl,
         model: selectedModel,
         instructions,
         tools: allTools,
-        permissionMode: config.permissionMode || 'default',
+        permissionMode: (process.env.SCALIX_PERMISSION_MODE || config.permissionMode || 'default'),
         maxSteps: limits.maxSteps,
         maxMessages: limits.maxMessages,
         contextManager: {
@@ -142,6 +196,10 @@ async function runSinglePrompt(prompt, output, format) {
         },
         instructionLoader: buildEnhancedInstructions,
         autoVerify: true,
+        outputFormat,
+        outputSchema,
+        groundingCheck: true,
+        contextRetrieval: true,
     });
     let fullResponse = '';
     agent.on('stream:end', (text) => { fullResponse = text; });
@@ -167,6 +225,9 @@ async function runSinglePrompt(prompt, output, format) {
                 cost: costTracker.totalCost,
             }, null, 2);
             break;
+        case 'json-schema':
+            formatted = fullResponse;
+            break;
         case 'patch':
             formatted = fullResponse;
             break;
@@ -183,20 +244,27 @@ async function runSinglePrompt(prompt, output, format) {
     else {
         process.stdout.write(formatted + '\n');
     }
+    await closeBrowser();
     process.exit(0);
 }
 async function runPipeMode() {
     const MAX_PIPE_BYTES = 50 * 1024 * 1024;
     const chunks = [];
     let totalBytes = 0;
-    for await (const chunk of process.stdin) {
-        const str = chunk.toString();
-        totalBytes += Buffer.byteLength(str);
-        if (totalBytes > MAX_PIPE_BYTES) {
-            console.error(`Error: Pipe input exceeds ${MAX_PIPE_BYTES / 1024 / 1024}MB limit.`);
-            process.exit(1);
+    try {
+        for await (const chunk of process.stdin) {
+            const str = chunk.toString();
+            totalBytes += Buffer.byteLength(str);
+            if (totalBytes > MAX_PIPE_BYTES) {
+                console.error(`Error: Pipe input exceeds ${MAX_PIPE_BYTES / 1024 / 1024}MB limit.`);
+                process.exit(1);
+            }
+            chunks.push(str);
         }
-        chunks.push(str);
+    }
+    catch (err) {
+        console.error(`Error reading pipe input: ${err.message}`);
+        process.exit(1);
     }
     const prompt = chunks.join('').trim();
     if (!prompt) {
@@ -232,7 +300,14 @@ async function runInteractive() {
         input: process.stdin,
         output: process.stdout,
     });
+    let rlClosed = false;
+    rl.on('close', () => {
+        rlClosed = true;
+        closeBrowser().finally(() => process.exit(0));
+    });
     function askUser(question) {
+        if (rlClosed)
+            return Promise.resolve('/exit');
         return new Promise((resolve) => rl.question(question, resolve));
     }
     const customCmds = await loadCustomCommands(process.cwd());
@@ -242,7 +317,7 @@ async function runInteractive() {
         model: selectedModel,
         instructions,
         tools: allTools,
-        permissionMode: config.permissionMode || 'default',
+        permissionMode: (process.env.SCALIX_PERMISSION_MODE || config.permissionMode || 'default'),
         maxSteps: limits.maxSteps,
         maxMessages: limits.maxMessages,
         contextManager: {
@@ -252,6 +327,8 @@ async function runInteractive() {
         },
         instructionLoader: buildEnhancedInstructions,
         autoVerify: true,
+        groundingCheck: true,
+        contextRetrieval: true,
         confirmToolCall: async (toolName, args) => {
             const preview = typeof args === 'string' ? args : JSON.stringify(args, null, 2);
             console.log(`\n\u26A0  Tool "${toolName}" wants to execute:`);
@@ -307,7 +384,7 @@ async function runInteractive() {
         }
         console.log('Goodbye!');
         rl.close();
-        process.exit(0);
+        closeBrowser().finally(() => process.exit(0));
     }
     process.on('SIGINT', shutdown);
     process.on('SIGTERM', shutdown);
@@ -329,6 +406,7 @@ async function runInteractive() {
             console.log('  /hooks       \u2014 show lifecycle hooks');
             console.log('  /commands    \u2014 show custom commands');
             console.log('  /delegate <t>\u2014 run task with sub-agent');
+            console.log('  /agents      \u2014 show active agents & usage');
             console.log('  /checkpoint  \u2014 create git checkpoint');
             console.log('  /undo        \u2014 undo last checkpoint');
             console.log('  /checkpoints \u2014 list recent checkpoints');
@@ -488,6 +566,22 @@ async function runInteractive() {
             }
             return true;
         }
+        if (cmd === '/agents') {
+            const registry = AgentRegistry.getInstance();
+            const summary = registry.getUsageSummary();
+            const tree = registry.getAgentTree();
+            console.log(`\nActive: ${summary.activeCount} | Completed: ${summary.completedCount} | Failed: ${summary.failedCount}`);
+            console.log(`Total tokens: ${summary.totalTokens.toLocaleString()}`);
+            if (tree && tree !== '(no agents)') {
+                console.log('\nAgent tree:');
+                console.log(tree);
+            }
+            else {
+                console.log('No agents have been spawned yet.');
+            }
+            console.log('');
+            return true;
+        }
         if (cmd === '/checkpoint') {
             const label = input.slice(12).trim() || undefined;
             const hash = await createCheckpoint(process.cwd(), label);
@@ -539,7 +633,7 @@ async function runInteractive() {
             return true;
         }
         if (cmd === '/git') {
-            const gitInfo = collectGitInfo(process.cwd());
+            const gitInfo = await collectGitInfo(process.cwd());
             if (!gitInfo.isRepo) {
                 console.log('\nNot a git repository.\n');
             }
@@ -630,14 +724,46 @@ async function runInteractive() {
 }
 async function main() {
     setSandboxRoot(process.cwd());
-    const { mode, prompt, output, format } = parseArgs();
+    const { mode, prompt, output, format, permissionMode: cliPermissionMode, outputSchema, worktree, worktreeName } = parseArgs();
+    if (cliPermissionMode) {
+        process.env.SCALIX_PERMISSION_MODE = cliPermissionMode;
+    }
+    // Set up worktree isolation if requested
+    let worktreeInfo = null;
+    if (worktree) {
+        const { createWorktree, removeWorktree } = await import('./worktree.js');
+        const name = worktreeName || `session-${Date.now().toString(36)}`;
+        try {
+            worktreeInfo = await createWorktree(name, process.cwd());
+            process.chdir(worktreeInfo.path);
+            setSandboxRoot(worktreeInfo.path);
+            console.log(`Working in isolated worktree: ${worktreeInfo.branch} → ${worktreeInfo.path}`);
+        }
+        catch (err) {
+            console.error(`Failed to create worktree: ${err.message}`);
+            process.exit(1);
+        }
+        const cleanup = async () => {
+            if (worktreeInfo) {
+                try {
+                    const origCwd = process.env.SCALIX_ORIGINAL_CWD || process.cwd();
+                    process.chdir(path.dirname(worktreeInfo.path));
+                    await removeWorktree(worktreeInfo, path.dirname(path.dirname(worktreeInfo.path)));
+                }
+                catch { }
+            }
+        };
+        process.on('exit', () => { cleanup().catch(() => { }); });
+        process.on('SIGINT', () => { cleanup().then(() => process.exit(0)).catch(() => process.exit(1)); });
+        process.env.SCALIX_ORIGINAL_CWD = process.cwd();
+    }
     switch (mode) {
         case 'run':
             if (!prompt) {
                 console.error('Error: No prompt provided. Usage: scalix run "your prompt"');
                 process.exit(1);
             }
-            await runSinglePrompt(prompt, output, format);
+            await runSinglePrompt(prompt, output, format, outputSchema);
             break;
         case 'pipe':
             await runPipeMode();
@@ -651,4 +777,7 @@ async function main() {
             break;
     }
 }
-main().catch(console.error);
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});