agentxl 1.0.0 → 1.1.2

package/bin/agentxl.js

@@ -5,14 +5,18 @@ import { resolve, join, dirname } from "path";
 import { fileURLToPath } from "url";
 import { homedir } from "os";
 import { createInterface } from "readline";
+import { config as loadDotenv } from "dotenv";
+
+// Load .env from project root (before any other imports)
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const projectRoot = resolve(__dirname, "..");
+loadDotenv({ path: join(projectRoot, ".env") });
 
 // ---------------------------------------------------------------------------
 // Package info
 // ---------------------------------------------------------------------------
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
 const pkgPath = join(__dirname, "..", "package.json");
 const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
 const VERSION = pkg.version;
@@ -91,19 +95,18 @@ async function checkAuth() {
   const piAuthPath = join(homedir(), ".pi", "agent", "auth.json");
   const agentxlAuthPath = join(homedir(), ".agentxl", "auth.json");
   const authPath = existsSync(piAuthPath) ? piAuthPath : agentxlAuthPath;
-  const authStorage = new AuthStorage(authPath);
+  const authStorage = AuthStorage.create(authPath);
 
   return authStorage.list().length > 0;
 }
 
 async function runAuthFlow() {
   const { AuthStorage } = await import("@mariozechner/pi-coding-agent");
-  const { getOAuthProviders } = await import("@mariozechner/pi-ai");
 
   const piAuthPath = join(homedir(), ".pi", "agent", "auth.json");
   const agentxlAuthPath = join(homedir(), ".agentxl", "auth.json");
   const authPath = existsSync(piAuthPath) ? piAuthPath : agentxlAuthPath;
-  const authStorage = new AuthStorage(authPath);
+  const authStorage = AuthStorage.create(authPath);
 
   // Check if already authenticated
   if (authStorage.list().length > 0) {
@@ -130,7 +133,7 @@ async function runAuthFlow() {
 `);
 
   // Build choices — OAuth providers + API key
-  const oauthProviders = getOAuthProviders();
+  const oauthProviders = authStorage.getOAuthProviders();
   const choices = [];
   for (const p of oauthProviders) {
     choices.push({ type: "oauth", id: p.id, name: p.name, provider: p });
@@ -254,14 +257,16 @@ async function start() {
 `);
 
   // ── Step 1: Load modules ───────────────────────────────────────────────
-  let ensureCerts, startServer, stopServer, setVerbose;
+  let ensureCerts, startServer, stopServer, setVerbose, getFolderPickerStrategy;
   try {
     const certs = await import("../dist/server/certs.js");
     const server = await import("../dist/server/index.js");
+    const picker = await import("../dist/server/folder-picker.js");
     ensureCerts = certs.ensureCerts;
     startServer = server.startServer;
     stopServer = server.stopServer;
     setVerbose = server.setVerbose;
+    getFolderPickerStrategy = picker.getFolderPickerStrategy;
   } catch (err) {
     step("❌", "Could not load AgentXL server modules");
     console.error("     Run 'npm run build' first to compile TypeScript.");
@@ -293,6 +298,37 @@ async function start() {
     process.exit(1);
   }
 
+  // ── Step 5: OCR status ─────────────────────────────────────────────────
+  if (process.env.AZURE_MISTRAL_ENDPOINT && process.env.AZURE_MISTRAL_API_KEY) {
+    step("✅", "OCR ready (Azure Mistral)");
+  } else if (process.env.MISTRAL_API_KEY) {
+    step("✅", "OCR ready (Mistral direct)");
+  } else {
+    step("ℹ️", "OCR not configured — scanned PDFs won't be readable");
+    step("  ", "Set AZURE_MISTRAL_ENDPOINT + AZURE_MISTRAL_API_KEY in .env");
+  }
+
+  // ── Step 6: Folder picker strategy ────────────────────────────────────
+  const pickerStrategy = getFolderPickerStrategy();
+  const pickerLabels = {
+    "native-helper": "Native folder picker helper",
+    "powershell": "PowerShell folder picker (fallback)",
+    "osascript": "macOS folder picker (osascript)",
+    "manual-only": "Manual path entry only",
+  };
+  const pickerLabel = pickerLabels[pickerStrategy.method] || pickerStrategy.method;
+  if (pickerStrategy.method === "native-helper") {
+    step("✅", `Folder picker: ${pickerLabel}`);
+  } else if (pickerStrategy.method === "powershell" || pickerStrategy.method === "osascript") {
+    step("⚠️", `Folder picker: ${pickerLabel}`);
+    if (pickerStrategy.platform === "win32") {
+      step("  ", "Build the native helper for a better experience:");
+      step("  ", "  npm run build:folder-picker:win");
+    }
+  } else {
+    step("ℹ️", `Folder picker: ${pickerLabel}`);
+  }
+
   // ── Post-start guidance ────────────────────────────────────────────────
   const manifestPath = resolve(__dirname, "..", "manifest", "manifest.xml");
   const manifestExists = existsSync(manifestPath);

package/dist/agent/models.d.ts

@@ -1,21 +1,21 @@
 /**
- * Default model selection per provider.
+ * Default model selection.
  *
- * Checks providers in order: Anthropic → OpenRouter → OpenAI.
- * Prefers subscriptions (OAuth) over API keys — subscriptions are already paid for.
- * Returns the first model that has auth configured.
+ * First honors the model configured in Pi settings (`defaultProvider` /
+ * `defaultModel`), then falls back to AgentXL's built-in preference order.
  */
 import type { Model, Api } from "@mariozechner/pi-ai";
-import type { ModelRegistry } from "@mariozechner/pi-coding-agent";
+import { type ModelRegistry } from "@mariozechner/pi-coding-agent";
 /**
  * Get the best available model based on configured auth.
  *
  * Priority:
- * 1. Subscriptions (OAuth) — Anthropic, OpenAI Codex (already paid for)
- * 2. API keys — OpenRouter, OpenAI, etc.
+ * 1. Pi settings (`defaultProvider` / `defaultModel`) if that model is available
+ * 2. Subscriptions (OAuth) from AgentXL's preferred fallback list
+ * 3. API keys from AgentXL's preferred fallback list
+ * 4. First available authenticated model
  *
- * Within each tier, checks PREFERRED_MODELS in order.
  * Returns null if no provider has auth configured.
  */
-export declare function getDefaultModel(modelRegistry: ModelRegistry): Model<Api> | null;
+export declare function getDefaultModel(modelRegistry: ModelRegistry, cwd?: string): Model<Api> | null;
 //# sourceMappingURL=models.d.ts.map

package/dist/agent/models.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../../src/agent/models.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAUnE;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,aAAa,EAAE,aAAa,GAC3B,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI,CAsBnB"}
+{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../../src/agent/models.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAmB,KAAK,aAAa,EAAE,MAAM,+BAA+B,CAAC;AA8BpF;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,aAAa,EAAE,aAAa,EAC5B,GAAG,CAAC,EAAE,MAAM,GACX,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI,CAyCnB"}

package/dist/agent/models.js

@@ -1,10 +1,10 @@
 /**
- * Default model selection per provider.
+ * Default model selection.
  *
- * Checks providers in order: Anthropic → OpenRouter → OpenAI.
- * Prefers subscriptions (OAuth) over API keys — subscriptions are already paid for.
- * Returns the first model that has auth configured.
+ * First honors the model configured in Pi settings (`defaultProvider` /
+ * `defaultModel`), then falls back to AgentXL's built-in preference order.
  */
+import { SettingsManager } from "@mariozechner/pi-coding-agent";
 /** Provider → preferred model ID, checked in priority order. */
 const PREFERRED_MODELS = [
     { provider: "anthropic", modelId: "claude-sonnet-4-20250514" },
@@ -12,21 +12,57 @@ const PREFERRED_MODELS = [
     { provider: "openrouter", modelId: "anthropic/claude-sonnet-4" },
     { provider: "openai", modelId: "gpt-4o" },
 ];
+/** Read the user's configured default model from Pi settings, if available. */
+function getConfiguredModelPreference(cwd) {
+    try {
+        const settings = SettingsManager.create(cwd || process.cwd());
+        const provider = settings.getDefaultProvider()?.trim();
+        const modelId = settings.getDefaultModel()?.trim();
+        if (!provider && !modelId)
+            return null;
+        return {
+            provider: provider || undefined,
+            modelId: modelId || undefined,
+        };
+    }
+    catch {
+        // Invalid/missing settings should not break model resolution.
+        return null;
+    }
+}
 /**
  * Get the best available model based on configured auth.
  *
  * Priority:
- * 1. Subscriptions (OAuth) — Anthropic, OpenAI Codex (already paid for)
- * 2. API keys — OpenRouter, OpenAI, etc.
+ * 1. Pi settings (`defaultProvider` / `defaultModel`) if that model is available
+ * 2. Subscriptions (OAuth) from AgentXL's preferred fallback list
+ * 3. API keys from AgentXL's preferred fallback list
+ * 4. First available authenticated model
  *
- * Within each tier, checks PREFERRED_MODELS in order.
  * Returns null if no provider has auth configured.
  */
-export function getDefaultModel(modelRegistry) {
+export function getDefaultModel(modelRegistry, cwd) {
     // Only consider models that have auth configured
     const available = modelRegistry.getAvailable();
     if (available.length === 0)
         return null;
+    // First honor Pi's configured default model/provider when possible.
+    const configured = getConfiguredModelPreference(cwd);
+    if (configured?.provider && configured?.modelId) {
+        const exact = available.find((m) => m.provider === configured.provider && m.id === configured.modelId);
+        if (exact)
+            return exact;
+    }
+    if (configured?.modelId) {
+        const byId = available.find((m) => m.id === configured.modelId);
+        if (byId)
+            return byId;
+    }
+    if (configured?.provider) {
+        const byProvider = available.find((m) => m.provider === configured.provider);
+        if (byProvider)
+            return byProvider;
+    }
     // Split into OAuth (subscriptions) vs API key models
     const oauthModels = available.filter((m) => modelRegistry.isUsingOAuth(m));
     const apiKeyModels = available.filter((m) => !modelRegistry.isUsingOAuth(m));

package/dist/agent/models.js.map

@@ -1 +1 @@
-{"version":3,"file":"models.js","sourceRoot":"","sources":["../../src/agent/models.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,gEAAgE;AAChE,MAAM,gBAAgB,GAAiD;IACrE,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,0BAA0B,EAAE;IAC9D,EAAE,QAAQ,EAAE,cAAc,EAAE,OAAO,EAAE,SAAS,EAAE;IAChD,EAAE,QAAQ,EAAE,YAAY,EAAE,OAAO,EAAE,2BAA2B,EAAE;IAChE,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE;CAC1C,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAC7B,aAA4B;IAE5B,iDAAiD;IACjD,MAAM,SAAS,GAAG,aAAa,CAAC,YAAY,EAAE,CAAC;IAC/C,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAExC,qDAAqD;IACrD,MAAM,WAAW,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3E,MAAM,YAAY,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;IAE7E,8DAA8D;IAC9D,KAAK,MAAM,IAAI,IAAI,CAAC,WAAW,EAAE,YAAY,CAAC,EAAE,CAAC;QAC/C,KAAK,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,gBAAgB,EAAE,CAAC;YACrD,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CACrB,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,QAAQ,IAAI,CAAC,CAAC,EAAE,KAAK,OAAO,CACnD,CAAC;YACF,IAAI,KAAK;gBAAE,OAAO,KAAK,CAAC;QAC1B,CAAC;IACH,CAAC;IAED,wDAAwD;IACxD,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC;IAClD,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC;AACtB,CAAC"}
+{"version":3,"file":"models.js","sourceRoot":"","sources":["../../src/agent/models.ts"],"names":[],"mappings":"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"}

package/dist/agent/prompt/folder-context.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Build the per-message folder context block.
+ *
+ * This block is prepended to every user message and tells the agent:
+ *   - Which folder is linked
+ *   - What files are available (with sizes)
+ *   - Which PDFs have been pre-converted to markdown
+ *   - How to access XLSX / DOCX files (binary → code)
+ *   - How to access text / CSV / MD files (read tool)
+ *
+ * Behavioral rules (citation format, review-before-write, extraction
+ * workflow) live in the system prompt — see ./system-prompt.ts.
+ * This module is file-inventory only.
+ */
+import type { FolderInventory } from "../../server/folder-scanner.js";
+/** Max supported files to list individually in context. */
+export declare const MAX_FILES_IN_CONTEXT = 50;
+/** Format file size for human-readable display. */
+export declare function formatFileSize(bytes: number): string;
+/**
+ * Build a folder context block to prepend to the agent message.
+ * Contains only the file inventory and access instructions — no
+ * behavioral rules (those are in the system prompt).
+ */
+export declare function buildFolderContext(folderPath: string, inventory: FolderInventory): string;
+//# sourceMappingURL=folder-context.d.ts.map

package/dist/agent/prompt/folder-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"folder-context.d.ts","sourceRoot":"","sources":["../../../src/agent/prompt/folder-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAGtE,2DAA2D;AAC3D,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC,mDAAmD;AACnD,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIpD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,eAAe,GACzB,MAAM,CA4GR"}

package/dist/agent/prompt/folder-context.js

@@ -0,0 +1,105 @@
+/**
+ * Build the per-message folder context block.
+ *
+ * This block is prepended to every user message and tells the agent:
+ *   - Which folder is linked
+ *   - What files are available (with sizes)
+ *   - Which PDFs have been pre-converted to markdown
+ *   - How to access XLSX / DOCX files (binary → code)
+ *   - How to access text / CSV / MD files (read tool)
+ *
+ * Behavioral rules (citation format, review-before-write, extraction
+ * workflow) live in the system prompt — see ./system-prompt.ts.
+ * This module is file-inventory only.
+ */
+import { listConvertedFiles } from "../../server/document-converter.js";
+/** Max supported files to list individually in context. */
+export const MAX_FILES_IN_CONTEXT = 50;
+/** Format file size for human-readable display. */
+export function formatFileSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${Math.round(bytes / 1024)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+/**
+ * Build a folder context block to prepend to the agent message.
+ * Contains only the file inventory and access instructions — no
+ * behavioral rules (those are in the system prompt).
+ */
+export function buildFolderContext(folderPath, inventory) {
+    const lines = [];
+    lines.push("[AgentXL — Linked Folder]");
+    lines.push("");
+    lines.push(`Folder: ${folderPath}`);
+    lines.push(`${inventory.supportedFiles} supported file${inventory.supportedFiles !== 1 ? "s" : ""}, ${inventory.totalFiles} total`);
+    lines.push("");
+    lines.push("IMPORTANT: All file paths MUST be absolute paths under this folder.");
+    // ── Supported files ────────────────────────────────────────────────────
+    const supported = inventory.files.filter((f) => f.supported);
+    const unsupported = inventory.files.filter((f) => !f.supported);
+    if (supported.length > 0) {
+        lines.push("");
+        lines.push("Supported files:");
+        const shown = supported.slice(0, MAX_FILES_IN_CONTEXT);
+        for (const f of shown) {
+            lines.push(`- ${f.relativePath} (${formatFileSize(f.sizeBytes)})`);
+        }
+        if (supported.length > MAX_FILES_IN_CONTEXT) {
+            lines.push(`  ... and ${supported.length - MAX_FILES_IN_CONTEXT} more supported files`);
+        }
+    }
+    if (unsupported.length > 0) {
+        lines.push("");
+        const unsupportedNames = unsupported
+            .slice(0, 10)
+            .map((f) => f.name)
+            .join(", ");
+        const suffix = unsupported.length > 10
+            ? ` and ${unsupported.length - 10} more`
+            : "";
+        lines.push(`Unsupported files (cannot read): ${unsupportedNames}${suffix}`);
+    }
+    // ── PDF conversions ────────────────────────────────────────────────────
+    const conversions = listConvertedFiles(inventory);
+    if (conversions.length > 0) {
+        lines.push("");
+        lines.push("📄 PDF files (pre-converted to Markdown):");
+        lines.push("Read the .md version, NOT the raw PDF.");
+        for (const c of conversions) {
+            lines.push(`- ${c.source} → READ: "${folderPath}/${c.converted}"`);
+        }
+    }
+    // ── XLSX handling ──────────────────────────────────────────────────────
+    const xlsxFiles = supported.filter((f) => f.extension === ".xlsx" || f.extension === ".xls");
+    if (xlsxFiles.length > 0) {
+        lines.push("");
+        lines.push("📊 Excel files — do NOT read with the read tool (binary).");
+        lines.push("Use bash + xlsx npm package:");
+        lines.push("```");
+        lines.push(`node -e "const XLSX = require('xlsx'); const wb = XLSX.readFile('${xlsxFiles[0].absolutePath}'); const ws = wb.Sheets[wb.SheetNames[0]]; console.log(JSON.stringify(XLSX.utils.sheet_to_json(ws), null, 2));"`);
+        lines.push("```");
+    }
+    // ── DOCX handling ──────────────────────────────────────────────────────
+    const docxFiles = supported.filter((f) => f.extension === ".docx" || f.extension === ".doc");
+    if (docxFiles.length > 0) {
+        lines.push("");
+        lines.push("📝 Word files — do NOT read with the read tool (binary).");
+        lines.push("Use bash + mammoth npm package:");
+        lines.push("```");
+        lines.push(`node -e "const mammoth = require('mammoth'); mammoth.convertToMarkdown({path: '${docxFiles[0].absolutePath}'}).then(r => console.log(r.value));"`);
+        lines.push("```");
+    }
+    // ── Quick access examples ──────────────────────────────────────────────
+    lines.push("");
+    lines.push("File access:");
+    lines.push(`- List: ls "${folderPath}"`);
+    const textExample = supported.find((f) => ![".pdf", ".xlsx", ".xls", ".docx", ".doc"].includes(f.extension));
+    if (textExample) {
+        lines.push(`- Read text file: read "${textExample.absolutePath}"`);
+    }
+    lines.push(`- Search: grep with path "${folderPath}"`);
+    return lines.join("\n");
+}
+//# sourceMappingURL=folder-context.js.map

package/dist/agent/prompt/folder-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"folder-context.js","sourceRoot":"","sources":["../../../src/agent/prompt/folder-context.ts"],"names":[],"mappings":"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"}

package/dist/agent/prompt/system-prompt.d.ts

@@ -0,0 +1,21 @@
+/**
+ * AgentXL system prompt — appended on top of Pi's built-in system prompt.
+ *
+ * This is the behavioral layer that makes the agent act like a
+ * document-to-Excel agent with show-your-work traceability.
+ *
+ * Pi's base prompt handles:
+ *   - tool descriptions (read, bash, edit, write, custom tools)
+ *   - tool usage guidelines
+ *   - skills, context files, AGENTS.md
+ *   - date/time, cwd
+ *
+ * This prompt adds:
+ *   - AgentXL identity and workflow rules
+ *   - Show-your-work traceability (not a permission gate)
+ *   - Citation format and traceability rules
+ *   - Excel comment API guidance (no .note)
+ *   - _AgentXL_Sources audit sheet spec
+ */
+export declare const AGENTXL_SYSTEM_PROMPT: string;
+//# sourceMappingURL=system-prompt.d.ts.map

package/dist/agent/prompt/system-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-prompt.d.ts","sourceRoot":"","sources":["../../../src/agent/prompt/system-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAMH,eAAO,MAAM,qBAAqB,QA0G1B,CAAC"}

package/dist/agent/prompt/system-prompt.js

@@ -0,0 +1,130 @@
+/**
+ * AgentXL system prompt — appended on top of Pi's built-in system prompt.
+ *
+ * This is the behavioral layer that makes the agent act like a
+ * document-to-Excel agent with show-your-work traceability.
+ *
+ * Pi's base prompt handles:
+ *   - tool descriptions (read, bash, edit, write, custom tools)
+ *   - tool usage guidelines
+ *   - skills, context files, AGENTS.md
+ *   - date/time, cwd
+ *
+ * This prompt adds:
+ *   - AgentXL identity and workflow rules
+ *   - Show-your-work traceability (not a permission gate)
+ *   - Citation format and traceability rules
+ *   - Excel comment API guidance (no .note)
+ *   - _AgentXL_Sources audit sheet spec
+ */
+// ---------------------------------------------------------------------------
+// Core identity + behavioral rules (set once per session via appendSystemPrompt)
+// ---------------------------------------------------------------------------
+export const AGENTXL_SYSTEM_PROMPT = `
+# AgentXL — Document-to-Excel Agent
+
+You are AgentXL, a document-to-Excel agent. You help users turn source
+documents into traceable Excel workpapers. You are NOT a generic
+spreadsheet chatbot.
+
+## Core Principle
+
+**Documents are the source. Excel is the destination.**
+
+Every value you write into Excel must be grounded in evidence from the
+user's linked document folder. If you cannot find evidence, say so.
+Do not fabricate data.
+
+## Show Your Work
+
+When you write values into Excel, always show the user what you found
+and where it came from — in your response text, not as a separate
+permission step.
+
+For every value you write, your response should include:
+- The value
+- Which source file it came from (with page or location)
+- Whether it was directly quoted or inferred
+
+Then write the values with citation comments and Sources entries.
+Do NOT ask for permission before writing — just show the traceability
+so the user can verify after the fact. The citations on the cells and
+the _AgentXL_Sources sheet are the review mechanism, not a confirmation
+dialog.
+
+## Citation Format
+
+Every value written to Excel must have:
+
+### A. An Excel comment on the cell
+Use \`worksheet.comments.add(cellAddress, content)\`.
+Do NOT use \`cell.note\`, \`range.note\`, or \`.note =\` — these do not
+work in this Office.js runtime.
+
+Comment format:
+\`\`\`
+📄 Source: <filename>
+📑 Page: <page number or location>
+💬 "<~150 char excerpt with the value in context>"
+🤖 Extracted by AgentXL
+\`\`\`
+
+For inferred values:
+\`\`\`
+⚠️ Inferred — no direct source citation
+💬 Reasoning: <why you inferred this value>
+🤖 Extracted by AgentXL
+\`\`\`
+
+Always delete any existing comment before adding a new one:
+\`\`\`javascript
+try { sheet.comments.getItemByCell(address).delete(); await context.sync(); } catch {}
+sheet.comments.add(address, content);
+\`\`\`
+
+### B. A row in the _AgentXL_Sources audit sheet
+After writing values, append citation records to \`_AgentXL_Sources\`.
+Create the sheet if it doesn't exist (headers: Target Sheet, Target Cell,
+Value, Source File, Page, Excerpt, Timestamp).
+This sheet is APPEND-ONLY — never delete existing rows.
+
+## Extraction Workflow
+
+When extracting data from documents:
+
+1. **Read / search the source files** — use read, grep, or bash scripts
+   to find the relevant data. For PDFs that have been pre-converted to
+   markdown, read the \`.md\` version from \`.agentxl-cache/\`.
+
+2. **Structure the findings** — organize extracted values with their
+   source citations (file, page, excerpt).
+
+3. **Show your work** — in your response, show what you found and where
+   each value came from. Clearly distinguish between directly-quoted
+   values and inferred values.
+
+4. **Write to Excel with citations** — write values + comments + Sources
+   entries in a single Excel tool call when possible.
+
+## File Access Rules
+
+- All file paths MUST be absolute paths under the linked folder.
+- Do NOT use relative paths or ".".
+- For .xlsx/.xls files: use bash with the \`xlsx\` npm package (already installed).
+- For .docx/.doc files: use bash with the \`mammoth\` npm package (already installed).
+- For .pdf files: read the pre-converted markdown from \`.agentxl-cache/\` if available.
+
+## Page Number Detection
+
+- PDF markdown files use \`---\` as page separators. Count separators before the match.
+- For XLSX: use sheet name + cell reference as the "page".
+- For DOCX: use the nearest section heading as the "page".
+
+## Excerpt Capture
+
+- Find the match position in the source text.
+- Take ~75 characters before and ~75 characters after.
+- Trim to word boundaries.
+- Prefix/suffix with "..." if truncated.
+`.trim();
+//# sourceMappingURL=system-prompt.js.map

package/dist/agent/prompt/system-prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-prompt.js","sourceRoot":"","sources":["../../../src/agent/prompt/system-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,8EAA8E;AAC9E,iFAAiF;AACjF,8EAA8E;AAE9E,MAAM,CAAC,MAAM,qBAAqB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0GpC,CAAC,IAAI,EAAE,CAAC"}

package/dist/agent/session.d.ts

@@ -9,14 +9,20 @@ declare let authStorage: AuthStorage;
 declare let modelRegistry: ModelRegistry;
 /**
  * Initialize a new agent session.
- * Picks the best available model, creates a Pi SDK session with no built-in
- * tools (Excel-only agent — custom tools come in Module 2).
+ * Picks the best available model, creates a Pi SDK session with read-only
+ * tools pointed at the given working directory (linked folder).
+ *
+ * @param cwd - Working directory for file tools. Defaults to process.cwd().
  */
-export declare function initSession(): Promise<AgentSession>;
+export declare function initSession(cwd?: string): Promise<AgentSession>;
 /**
  * Get the current session, or create one if none exists.
+ * If `cwd` is provided and differs from the current session's cwd,
+ * the session is recreated so file tools point to the correct folder.
+ *
+ * @param cwd - Working directory for file tools (linked folder path).
  */
-export declare function getSession(): Promise<AgentSession>;
+export declare function getSession(cwd?: string): Promise<AgentSession>;
 /**
  * Check if any provider has auth configured.
  * Fast check — does not refresh OAuth tokens.

package/dist/agent/session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/agent/session.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAEL,WAAW,EACX,aAAa,EAGb,KAAK,YAAY,EAClB,MAAM,+BAA+B,CAAC;AA2BvC,QAAA,IAAI,WAAW,aAAqC,CAAC;AACrD,QAAA,IAAI,aAAa,eAAiC,CAAC;AA0BnD;;;;GAIG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC,YAAY,CAAC,CA8BzD;AAED;;GAEG;AACH,wBAAsB,UAAU,IAAI,OAAO,CAAC,YAAY,CAAC,CAKxD;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAIzC;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,MAAM,GAAG,IAAI,CAQ/C;AAED;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,IAAI,CAMnC;AAED;;;GAGG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAQlD;AAGD,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,CAAC"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/agent/session.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAIL,WAAW,EAEX,aAAa,EAGb,KAAK,YAAY,EAClB,MAAM,+BAA+B,CAAC;AA6BvC,QAAA,IAAI,WAAW,aAAwC,CAAC;AACxD,QAAA,IAAI,aAAa,eAAiC,CAAC;AA6BnD;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAoDrE;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAcpE;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAIzC;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,MAAM,GAAG,IAAI,CAQ/C;AAED;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,IAAI,CAOnC;AAED;;;GAGG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAQlD;AAGD,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,CAAC"}