agentxl 1.0.0 → 1.1.2

package/dist/agent/session.js

@@ -7,8 +7,10 @@
 import { join } from "path";
 import { homedir } from "os";
 import { existsSync } from "fs";
-import { createAgentSession, AuthStorage, ModelRegistry, SessionManager, SettingsManager, } from "@mariozechner/pi-coding-agent";
+import { createAgentSession, createReadOnlyTools, createBashTool, AuthStorage, DefaultResourceLoader, ModelRegistry, SessionManager, SettingsManager, } from "@mariozechner/pi-coding-agent";
 import { getDefaultModel } from "./models.js";
+import { excelTool } from "./tools/excel.js";
+import { AGENTXL_SYSTEM_PROMPT } from "./prompt/system-prompt.js";
 // ---------------------------------------------------------------------------
 // Paths
 // ---------------------------------------------------------------------------
@@ -31,10 +33,12 @@ function resolveAuthPath() {
 // ---------------------------------------------------------------------------
 // Singletons — rebuilt on resetSession() to pick up auth changes
 // ---------------------------------------------------------------------------
-let authStorage = new AuthStorage(resolveAuthPath());
+let authStorage = AuthStorage.create(resolveAuthPath());
 let modelRegistry = new ModelRegistry(authStorage);
 /** Active agent session (null until first prompt) */
 let currentSession = null;
+/** The cwd the current session was created with */
+let currentSessionCwd = null;
 /** Provider selected for the active session */
 let selectedProvider = null;
 // ---------------------------------------------------------------------------
@@ -45,7 +49,7 @@ let selectedProvider = null;
  * Called by resetSession() so runtime auth changes are picked up.
  */
 function rebuildAuth() {
-    authStorage = new AuthStorage(resolveAuthPath());
+    authStorage = AuthStorage.create(resolveAuthPath());
     modelRegistry = new ModelRegistry(authStorage);
     selectedProvider = null;
 }
@@ -54,42 +58,75 @@ function rebuildAuth() {
 // ---------------------------------------------------------------------------
 /**
  * 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 async function initSession() {
+export async function initSession(cwd) {
     // Refresh to pick up any new keys
     modelRegistry.refresh();
-    const model = getDefaultModel(modelRegistry);
+    const effectiveCwd = cwd || process.cwd();
+    const model = getDefaultModel(modelRegistry, effectiveCwd);
     if (!model) {
         throw new Error("No model available. Run 'agentxl login' to set up authentication " +
             "(API key or subscription).");
     }
     // Track the selected provider
     selectedProvider = model.provider;
+    const readOnly = createReadOnlyTools(effectiveCwd);
+    const bash = createBashTool(effectiveCwd);
+    const tools = [...readOnly, bash];
+    const settingsManager = SettingsManager.inMemory({
+        compaction: { enabled: true },
+    });
+    // Build a ResourceLoader that appends AgentXL's behavioral rules
+    // on top of Pi's built-in system prompt (tool docs, skills, AGENTS.md).
+    const resourceLoader = new DefaultResourceLoader({
+        cwd: effectiveCwd,
+        settingsManager,
+        appendSystemPrompt: AGENTXL_SYSTEM_PROMPT,
+        noExtensions: true,
+        noSkills: true,
+        noPromptTemplates: true,
+        noThemes: true,
+    });
+    await resourceLoader.reload();
     const { session } = await createAgentSession({
         model,
+        cwd: effectiveCwd,
         thinkingLevel: "medium",
-        tools: [], // No built-in tools (read/bash/edit/write)
-        customTools: [], // Excel tools come in Module 2
+        tools, // read, grep, find, ls, bash — pointed at linked folder
+        customTools: [excelTool], // Single Excel tool — agent writes Office.js code
+        resourceLoader, // Pi base prompt + AgentXL append
         sessionManager: SessionManager.inMemory(),
-        settingsManager: SettingsManager.inMemory({
-            compaction: { enabled: false },
-        }),
+        settingsManager,
         authStorage,
         modelRegistry,
     });
     currentSession = session;
+    currentSessionCwd = effectiveCwd;
     return session;
 }
 /**
  * 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 async function getSession() {
+export async function getSession(cwd) {
+    const effectiveCwd = cwd || process.cwd();
+    // Recreate session if the working directory changed
+    if (currentSession && currentSessionCwd !== effectiveCwd) {
+        currentSession.dispose();
+        currentSession = null;
+        currentSessionCwd = null;
+    }
     if (currentSession) {
         return currentSession;
     }
-    return initSession();
+    return initSession(effectiveCwd);
 }
 /**
  * Check if any provider has auth configured.
@@ -111,7 +148,7 @@ export function getAuthProvider() {
         return selectedProvider;
     // No session yet — preview what getDefaultModel() would pick
     modelRegistry.refresh();
-    const model = getDefaultModel(modelRegistry);
+    const model = getDefaultModel(modelRegistry, currentSessionCwd ?? process.cwd());
     return model?.provider ?? null;
 }
 /**
@@ -123,6 +160,7 @@ export function resetSession() {
     if (currentSession) {
         currentSession.dispose();
         currentSession = null;
+        currentSessionCwd = null;
     }
     rebuildAuth();
 }

package/dist/agent/session.js.map

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

package/dist/agent/tools/excel.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Single Excel custom tool — the agent writes Office.js code,
+ * the taskpane executes it in the active workbook.
+ *
+ * This replaces the 10-tool approach with one flexible tool:
+ * the agent has full Office.js API access and gets real results back.
+ */
+import type { ToolDefinition } from "@mariozechner/pi-coding-agent";
+/**
+ * The `excel` tool definition.
+ *
+ * The agent sends Office.js code that runs inside:
+ *   Excel.run(async (context) => { <code here> })
+ *
+ * The code has access to `context` (the Excel RequestContext).
+ * It should return a value — the return value is sent back to the agent.
+ *
+ * Common patterns the agent should use:
+ * - Read:  context.workbook.worksheets.getActiveWorksheet().getRange("A1:D10").load("values"); await context.sync(); return range.values;
+ * - Write: context.workbook.worksheets.getActiveWorksheet().getRange("A1").values = [["Hello"]]; await context.sync();
+ * - Chart: const sheet = context.workbook.worksheets.getActiveWorksheet(); const chart = sheet.charts.add("ColumnClustered", sheet.getRange("A1:B5")); await context.sync();
+ */
+export declare const excelTool: ToolDefinition;
+//# sourceMappingURL=excel.d.ts.map

package/dist/agent/tools/excel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"excel.d.ts","sourceRoot":"","sources":["../../../src/agent/tools/excel.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAEpE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,SAAS,EAAE,cA8GvB,CAAC"}

package/dist/agent/tools/excel.js

@@ -0,0 +1,132 @@
+/**
+ * Single Excel custom tool — the agent writes Office.js code,
+ * the taskpane executes it in the active workbook.
+ *
+ * This replaces the 10-tool approach with one flexible tool:
+ * the agent has full Office.js API access and gets real results back.
+ */
+import { Type } from "@sinclair/typebox";
+import { registerPendingExecution } from "../../server/excel-bridge.js";
+/**
+ * The `excel` tool definition.
+ *
+ * The agent sends Office.js code that runs inside:
+ *   Excel.run(async (context) => { <code here> })
+ *
+ * The code has access to `context` (the Excel RequestContext).
+ * It should return a value — the return value is sent back to the agent.
+ *
+ * Common patterns the agent should use:
+ * - Read:  context.workbook.worksheets.getActiveWorksheet().getRange("A1:D10").load("values"); await context.sync(); return range.values;
+ * - Write: context.workbook.worksheets.getActiveWorksheet().getRange("A1").values = [["Hello"]]; await context.sync();
+ * - Chart: const sheet = context.workbook.worksheets.getActiveWorksheet(); const chart = sheet.charts.add("ColumnClustered", sheet.getRange("A1:B5")); await context.sync();
+ */
+export const excelTool = {
+    name: "excel",
+    label: "Excel",
+    description: `Execute Office.js code in the user's active Excel workbook.
+
+The code runs inside Excel.run(async (context) => { ... }).
+You have access to \`context\` (Excel.RequestContext).
+
+IMPORTANT RULES:
+- Always call \`await context.sync()\` after loading properties or making changes.
+- To read properties, call \`.load("propertyName")\` then \`await context.sync()\` before accessing.
+- Return a value to send results back (e.g., cell values, sheet names).
+- For writes, return a confirmation string describing what was written.
+- Do NOT use \`range.note\` or \`cell.note\` for citations/comments. In this runtime, use \`worksheet.comments.add(cellAddress, content)\`.
+
+COMMON PATTERNS:
+
+Read cell values:
+\`\`\`
+const range = context.workbook.worksheets.getActiveWorksheet().getRange("A1:D10");
+range.load("values");
+await context.sync();
+return range.values;
+\`\`\`
+
+Write values:
+\`\`\`
+const sheet = context.workbook.worksheets.getActiveWorksheet();
+sheet.getRange("A1").values = [["Revenue", "Q1", "Q2"], [100, 200, 300]];
+await context.sync();
+return "Wrote 2 rows to A1:C2";
+\`\`\`
+
+Add or replace a citation comment:
+\`\`\`
+const sheet = context.workbook.worksheets.getActiveWorksheet();
+const address = "B5";
+try {
+  sheet.comments.getItemByCell(address).delete();
+  await context.sync();
+} catch {}
+sheet.comments.add(address, "📄 Source: Lease.pdf\n📑 Page: 14\n💬 ...quoted excerpt...\n🤖 Extracted by AgentXL");
+await context.sync();
+return "Added citation comment to B5";
+\`\`\`
+
+Get all sheet names:
+\`\`\`
+const sheets = context.workbook.worksheets;
+sheets.load("items/name");
+await context.sync();
+return sheets.items.map(s => s.name);
+\`\`\`
+
+Create a chart:
+\`\`\`
+const sheet = context.workbook.worksheets.getActiveWorksheet();
+const chart = sheet.charts.add("ColumnClustered", sheet.getRange("A1:B5"), "Auto");
+chart.title.text = "Sales";
+await context.sync();
+return "Created column chart from A1:B5";
+\`\`\`
+
+Format cells:
+\`\`\`
+const range = context.workbook.worksheets.getActiveWorksheet().getRange("A1:D1");
+range.format.font.bold = true;
+range.format.fill.color = "#4472C4";
+range.format.font.color = "#FFFFFF";
+await context.sync();
+return "Formatted header row A1:D1";
+\`\`\`
+
+Add a worksheet:
+\`\`\`
+const sheet = context.workbook.worksheets.add("Summary");
+sheet.activate();
+await context.sync();
+return "Added and activated worksheet 'Summary'";
+\`\`\``,
+    parameters: Type.Object({
+        code: Type.String({
+            description: "Office.js code to execute inside Excel.run(async (context) => { ... }). " +
+                "Has access to `context` (Excel.RequestContext). Return a value to get results back.",
+        }),
+        description: Type.String({
+            description: "Brief human-readable description of what this code does (shown in UI).",
+        }),
+    }),
+    execute: async (toolCallId, params) => {
+        // The actual execution happens in the taskpane via Office.js.
+        // We register a pending execution and wait for the taskpane to
+        // POST the result back to /api/excel/result.
+        try {
+            const result = await registerPendingExecution(toolCallId);
+            return {
+                content: [{ type: "text", text: typeof result === "string" ? result : JSON.stringify(result) }],
+                details: {},
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }],
+                details: {},
+            };
+        }
+    },
+};
+//# sourceMappingURL=excel.js.map

package/dist/agent/tools/excel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"excel.js","sourceRoot":"","sources":["../../../src/agent/tools/excel.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AACzC,OAAO,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AAGxE;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,SAAS,GAAmB;IACvC,IAAI,EAAE,OAAO;IACb,KAAK,EAAE,OAAO;IACd,WAAW,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4ER;IAEL,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC;QACtB,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC;YAChB,WAAW,EACT,0EAA0E;gBAC1E,qFAAqF;SACxF,CAAC;QACF,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC;YACvB,WAAW,EACT,wEAAwE;SAC3E,CAAC;KACH,CAAC;IAEF,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,EAAE;QACpC,8DAA8D;QAC9D,+DAA+D;QAC/D,6CAA6C;QAC7C,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,wBAAwB,CAAC,UAAU,CAAC,CAAC;YAC1D,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;gBACxG,OAAO,EAAE,EAAE;aACZ,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,UAAU,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;gBACxG,OAAO,EAAE,EAAE;aACZ,CAAC;QACJ,CAAC;IACH,CAAC;CACF,CAAC"}

package/dist/server/document-converter.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Document pre-converter — converts binary documents to readable Markdown.
+ *
+ * Runs at scan time (or on demand). Cached converted files live alongside
+ * the source files in a `.agentxl-cache/` directory inside the linked folder.
+ *
+ * PDF conversion strategy:
+ * 1. Try pdf-parse (fast, local, free) — extracts embedded text
+ * 2. Check if extracted text is meaningful (chars-per-page heuristic)
+ * 3. If scanned/image PDF → fall back to Mistral OCR API
+ *
+ * XLSX and DOCX are NOT pre-converted — the agent writes extraction code
+ * at runtime via bash, which is more powerful for structured data.
+ */
+import type { FolderInventory } from "./folder-scanner.js";
+/**
+ * Minimum average characters per page to consider text extraction successful.
+ * Below this threshold, the PDF is likely scanned/image-based and needs OCR.
+ */
+declare const MIN_CHARS_PER_PAGE = 50;
+/**
+ * Check if extracted text is meaningful (not just whitespace/control chars).
+ * Scanned PDFs often return empty or near-empty text.
+ */
+declare function isTextMeaningful(text: string, pageCount: number): boolean;
+interface OcrConfig {
+    provider: "azure-mistral" | "mistral";
+    endpoint?: string;
+    apiKey: string;
+}
+/**
+ * Detect which OCR provider is available.
+ * Priority: Azure Mistral (enterprise) → direct Mistral → null
+ */
+declare function getOcrConfig(): OcrConfig | null;
+export interface ConversionResult {
+    /** Number of PDFs converted via text extraction */
+    converted: number;
+    /** Number of PDFs converted via Mistral OCR */
+    ocrConverted: number;
+    /** Number already cached (skipped) */
+    cached: number;
+    /** Number that failed */
+    failed: number;
+    /** Error messages for failures */
+    errors: string[];
+}
+/**
+ * Pre-convert all PDFs in an inventory to Markdown.
+ * Skips files where the cache is still valid (source not modified).
+ *
+ * @param inventory - Folder inventory from scanner
+ * @returns Summary of conversion results
+ */
+export declare function convertDocuments(inventory: FolderInventory): Promise<ConversionResult>;
+/**
+ * Get the markdown path for a source file, if it has been converted.
+ * Returns null if no cached conversion exists.
+ */
+export declare function getConvertedPath(folderRoot: string, relativePath: string): string | null;
+/**
+ * Build a list of converted markdown files for agent context.
+ * Returns entries like: `invoice.pdf → .agentxl-cache/invoice.pdf.md`
+ */
+export declare function listConvertedFiles(inventory: FolderInventory): Array<{
+    source: string;
+    converted: string;
+}>;
+export { isTextMeaningful, getOcrConfig, MIN_CHARS_PER_PAGE };
+export type { OcrConfig };
+//# sourceMappingURL=document-converter.d.ts.map

package/dist/server/document-converter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-converter.d.ts","sourceRoot":"","sources":["../../src/server/document-converter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAK3D;;;GAGG;AACH,QAAA,MAAM,kBAAkB,KAAK,CAAC;AAiD9B;;;GAGG;AACH,iBAAS,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAQlE;AAMD,UAAU,SAAS;IACjB,QAAQ,EAAE,eAAe,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,iBAAS,YAAY,IAAI,SAAS,GAAG,IAAI,CAexC;AAiPD,MAAM,WAAW,gBAAgB;IAC/B,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,YAAY,EAAE,MAAM,CAAC;IACrB,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,yBAAyB;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,eAAe,GACzB,OAAO,CAAC,gBAAgB,CAAC,CAkD3B;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,GACnB,MAAM,GAAG,IAAI,CAGf;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,eAAe,GACzB,KAAK,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAiB9C;AAGD,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,kBAAkB,EAAE,CAAC;AAC9D,YAAY,EAAE,SAAS,EAAE,CAAC"}