@cortexkit/aft-pi 0.18.3 → 0.18.4

package/dist/config.d.ts.map

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

package/dist/index.d.ts

@@ -30,10 +30,45 @@
  *   - /aft-status    Status dialog (index states, LSP servers, storage dir)
  */
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { loadAftConfig } from "./config.js";
+/**
+ * Tool surface mirrors opencode-plugin: navigate/delete/move/transform/refactor
+ * are all-only. recommended exposes hoisted + read/safety/import/ast/lsp/conflicts
+ * + experimental search/semantic when enabled.
+ *
+ * Returns the set of AFT tool names that should be registered given the
+ * configured surface + disabled_tools filter. Pi's built-in tools are always
+ * present; registering an AFT tool with the same name replaces them.
+ */
+declare function resolveToolSurface(config: ReturnType<typeof loadAftConfig>): {
+    hoistBash: boolean;
+    hoistRead: boolean;
+    hoistWrite: boolean;
+    hoistEdit: boolean;
+    hoistGrep: boolean;
+    outline: boolean;
+    zoom: boolean;
+    semantic: boolean;
+    navigate: boolean;
+    conflicts: boolean;
+    importTool: boolean;
+    safety: boolean;
+    delete: boolean;
+    move: boolean;
+    astSearch: boolean;
+    astReplace: boolean;
+    lspDiagnostics: boolean;
+    structure: boolean;
+    refactor: boolean;
+};
 /**
  * Pi extension default export.
  *
  * Called once per session. Registers tools, commands, and session shutdown hooks.
  */
 export default function (pi: ExtensionAPI): Promise<void>;
+export declare const __test__: {
+    resolveToolSurface: typeof resolveToolSurface;
+};
+export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AA0LlE;;;;GAIG;AACH,yBAA+B,EAAE,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAuT9D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAQlE,OAAO,EACL,aAAa,EAGd,MAAM,aAAa,CAAC;AAkFrB;;;;;;;;GAQG;AACH,iBAAS,kBAAkB,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,aAAa,CAAC,GAAG;IACrE,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,cAAc,EAAE,OAAO,CAAC;IACxB,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;CACnB,CAiEA;AAED;;;;GAIG;AACH,yBAA+B,EAAE,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA6T9D;AAED,eAAO,MAAM,QAAQ;;CAAyB,CAAC"}

package/dist/index.js

@@ -22107,6 +22107,18 @@ function isWritableMigrationError(errorValue) {
   const code = errorValue?.code;
   return code === "EROFS" || code === "EACCES" || code === "EPERM";
 }
+function extractCommentsForPreservation(content) {
+  const comments = [];
+  const linePattern = /\/\/[^\n]*/g;
+  for (const match of content.match(linePattern) ?? []) {
+    comments.push(match.trim());
+  }
+  const blockPattern = /\/\*[\s\S]*?\*\//g;
+  for (const match of content.match(blockPattern) ?? []) {
+    comments.push(match.replace(/\s+/g, " ").trim());
+  }
+  return comments;
+}
 function ensureRecordAtPath(root, path2) {
   let current = root;
   for (const segment of path2) {
@@ -22165,10 +22177,9 @@ function migrateAftConfigFile(configPath, logger = { log, warn }) {
     if (oldKeys.length === 0) {
       return { migrated: false, oldKeys: [] };
     }
-    const comments = content.match(/^\s*\/\/.*$/gm) ?? [];
     const serialized = `${import_comment_json.stringify(rawConfig, null, 2)}
 `;
-    const preservedComments = comments.filter((comment) => !serialized.includes(comment.trim()));
+    const preservedComments = extractCommentsForPreservation(content).filter((comment) => !serialized.includes(comment.trim()));
     const nextContent = preservedComments.length > 0 ? `${preservedComments.join(`
 `)}
 ${serialized}` : serialized;
@@ -24886,6 +24897,14 @@ class BridgePool {
     }
     return null;
   }
+  getActiveBridgeForRoot(directory) {
+    const key = canonicalKey(directory);
+    const entry = this.bridges.get(key);
+    if (!entry?.bridge.isAlive())
+      return null;
+    entry.lastUsed = Date.now();
+    return entry.bridge;
+  }
   getBridge(directory) {
     const key = canonicalKey(directory);
     const existing = this.bridges.get(key);
@@ -26991,6 +27010,29 @@ function buildOutlineSections(text, theme) {
 `)];
 }
 function buildZoomSections(args, payload, theme) {
+  const batch = asRecord2(payload);
+  if (Array.isArray(batch?.symbols)) {
+    const header = batch.complete === false ? [theme.fg("warning", "Incomplete zoom results")] : [];
+    const items2 = batch.symbols;
+    return [
+      ...header,
+      ...items2.map((item) => {
+        const record2 = asRecord2(item);
+        if (!record2)
+          return theme.fg("muted", "No zoom result available.");
+        const name = asString(record2.name) ?? "(unknown symbol)";
+        if (record2.success === false) {
+          return theme.fg("error", `Symbol "${name}" not found: ${asString(record2.error) ?? "zoom failed"}`);
+        }
+        const content = asString(record2.content);
+        return [
+          `${theme.fg("accent", name)} ${theme.fg("muted", shortenPath(args.filePath))}`,
+          content
+        ].filter(Boolean).join(`
+`);
+      })
+    ];
+  }
   const items = Array.isArray(payload) ? payload : payload ? [payload] : [];
   if (items.length === 0)
     return [theme.fg("muted", "No zoom result available.")];
@@ -27109,9 +27151,13 @@ function registerReadingTools(pi, ctx, surface) {
             const req2 = { file: params.filePath, symbol: sym };
             if (params.contextLines !== undefined)
               req2.context_lines = params.contextLines;
-            return callBridge(bridge, "zoom", req2, extCtx);
+            return callBridge(bridge, "zoom", req2, extCtx).catch((err) => ({
+              success: false,
+              message: err instanceof Error ? err.message : String(err)
+            }));
           }));
-          return textResult(JSON.stringify(results, null, 2));
+          const batch = formatZoomBatchResult(params.symbols, results);
+          return textResult(batch.text, batch);
         }
         const req = { file: params.filePath };
         if (params.symbol)
@@ -27130,6 +27176,40 @@ function registerReadingTools(pi, ctx, surface) {
     });
   }
 }
+function formatZoomBatchResult(symbols, responses) {
+  const entries = symbols.map((name, index) => {
+    const response = responses[index] ?? { success: false, message: "missing zoom response" };
+    if (response.success === false) {
+      const message = typeof response.message === "string" && response.message.length > 0 ? response.message : "zoom failed";
+      return { name, success: false, error: message };
+    }
+    return { name, success: true, content: zoomResponseContent(response) };
+  });
+  const complete = entries.every((entry) => entry.success);
+  const lines = [];
+  if (!complete) {
+    lines.push("Incomplete zoom results: one or more symbols failed.");
+  }
+  for (const entry of entries) {
+    if (entry.success) {
+      lines.push(`Symbol "${entry.name}":
+${entry.content ?? ""}`.trimEnd());
+    } else {
+      lines.push(`Symbol "${entry.name}" not found: ${entry.error ?? "zoom failed"}`);
+    }
+  }
+  return { complete, symbols: entries, text: lines.join(`
+
+`) };
+}
+function zoomResponseContent(response) {
+  if (typeof response.content === "string")
+    return response.content;
+  if (typeof response.text === "string")
+    return response.text;
+  const { success: _success2, ...rest } = response;
+  return JSON.stringify(rest, null, 2);
+}
 function formatOutlineText(response) {
   const text = response.text ?? "";
   const skipped = response.skipped_files;
@@ -27621,6 +27701,83 @@ function validateTransformParams(params) {
   }
 }
 
+// src/workflow-hints.ts
+var HEADING = "## Prefer AFT tools for token efficiency";
+function buildWorkflowHints(opts) {
+  const sections = [];
+  const grepName = opts.hoistBuiltins ? "grep" : "aft_grep";
+  const bashName = opts.hoistBuiltins ? "bash" : "aft_bash";
+  const hasOutline = !opts.absentTools.has("aft_outline");
+  const hasZoom = !opts.absentTools.has("aft_zoom");
+  const hasGrep = opts.toolSurface !== "minimal" && !opts.absentTools.has(grepName);
+  const hasSearch = opts.toolSurface !== "minimal" && opts.semanticEnabled && !opts.absentTools.has("aft_search");
+  const hasNavigate = opts.toolSurface === "all" && !opts.absentTools.has("aft_navigate");
+  const hasBgBash = opts.bashBackgroundEnabled && !opts.absentTools.has(bashName) && !opts.absentTools.has("bash_status");
+  if (hasOutline && hasZoom) {
+    sections.push(`**Web/URL access**: \`aft_outline({ url })\` first for structure, then \`aft_zoom({ url, symbol: "<heading>" })\` for the specific section.`);
+  }
+  if (hasOutline && hasZoom && (hasGrep || hasSearch)) {
+    const locator = hasGrep && hasSearch ? `\`${grepName}\` or \`aft_search\`` : hasGrep ? `\`${grepName}\`` : "`aft_search`";
+    sections.push(`**Code exploration**: ${locator} to locate → \`aft_outline\` for structure → \`aft_zoom\` for symbol(s).`);
+  }
+  if (hasNavigate) {
+    sections.push([
+      "Use `aft_navigate` instead of grep + read chains for relationship questions:",
+      "- `callers` — find all call sites before changing a function signature",
+      "- `impact` — blast radius (which functions/files will need updates)",
+      "- `trace_to` — how execution reaches this code from entry points (routes, exports, main)",
+      "- `trace_data` — follow a value through assignments and parameters across files"
+    ].join(`
+`));
+  }
+  if (hasBgBash) {
+    sections.push(`**Long-running commands** (builds, installs, full test suites): \`${bashName}({ background: true })\` returns immediately with a \`taskId\`. Check progress with \`bash_status({ taskId })\`.`);
+  }
+  if (sections.length === 0) {
+    return null;
+  }
+  return `${HEADING}
+
+${sections.join(`
+
+`)}`;
+}
+function buildHintsFromConfig(config2, absentTools, hoistBuiltins) {
+  return buildWorkflowHints({
+    toolSurface: config2.tool_surface ?? "recommended",
+    hoistBuiltins,
+    semanticEnabled: config2.semantic_search === true,
+    bashBackgroundEnabled: config2.experimental?.bash?.background === true,
+    absentTools
+  });
+}
+function registerWorkflowHints(pi, config2, surface) {
+  const absent = new Set;
+  if (!surface.outline)
+    absent.add("aft_outline");
+  if (!surface.zoom)
+    absent.add("aft_zoom");
+  if (!surface.semantic)
+    absent.add("aft_search");
+  if (!surface.navigate)
+    absent.add("aft_navigate");
+  if (!surface.hoistGrep)
+    absent.add("grep");
+  if (!surface.hoistBash) {
+    absent.add("bash");
+    absent.add("bash_status");
+  }
+  const hintsBlock = buildHintsFromConfig(config2, absent, true);
+  if (!hintsBlock)
+    return;
+  log(`Workflow hints injected (${hintsBlock.length} chars)`);
+  pi.on("before_agent_start", (event) => {
+    return { systemPrompt: `${event.systemPrompt}
+
+${hintsBlock}` };
+  });
+}
+
 // src/index.ts
 var PLUGIN_VERSION = (() => {
   try {
@@ -27666,6 +27823,7 @@ function resolveToolSurface(config2) {
   const allOnly = (name) => ALL_ONLY_TOOLS.has(name) && ok(name);
   if (surface === "minimal") {
     return {
+      hoistBash: ok("bash"),
       hoistRead: false,
       hoistWrite: false,
       hoistEdit: false,
@@ -27687,6 +27845,7 @@ function resolveToolSurface(config2) {
     };
   }
   const base = {
+    hoistBash: ok("bash"),
     hoistRead: ok("read"),
     hoistWrite: ok("write"),
     hoistEdit: ok("edit"),
@@ -27862,7 +28021,7 @@ ${lines}
     sendFeatureAnnouncement(ANNOUNCEMENT_VERSION, ANNOUNCEMENT_FEATURES, storageDir);
   }
   const surface = resolveToolSurface(config2);
-  if (surface.hoistRead) {
+  if (surface.hoistBash) {
     registerBashTool(pi, ctx);
   }
   registerHoistedTools(pi, ctx, surface);
@@ -27899,6 +28058,7 @@ ${lines}
   if (surface.refactor) {
     registerRefactorTool(pi, ctx);
   }
+  registerWorkflowHints(pi, config2, surface);
   registerStatusCommand(pi, ctx);
   pi.on("tool_result", async (event, extCtx) => {
     const content = await appendToolResultBgCompletions({ ctx, directory: extCtx.cwd, sessionID: resolveSessionId(extCtx) }, event.content);
@@ -27937,6 +28097,8 @@ ${lines}
   });
   log(`AFT extension ready (surface=${config2.tool_surface ?? "recommended"})`);
 }
+var __test__ = { resolveToolSurface };
 export {
-  src_default as default
+  src_default as default,
+  __test__
 };

package/dist/pool.d.ts

@@ -22,6 +22,8 @@ export declare class BridgePool {
     constructor(binaryPath: string, options?: PoolOptions, configOverrides?: Record<string, unknown>);
     /** Get any existing alive bridge, preferring the given directory. */
     getAnyActiveBridge(directory: string): BinaryBridge | null;
+    /** Get an alive bridge only when it belongs to the requested directory. */
+    getActiveBridgeForRoot(directory: string): BinaryBridge | null;
     /** Get or create a bridge for the given directory. */
     getBridge(directory: string): BinaryBridge;
     private cleanup;

package/dist/pool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../src/pool.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAY/D,MAAM,WAAW,WAAY,SAAQ,aAAa;IAChD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgC;IACxD,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAC9C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA0B;IAC1D,OAAO,CAAC,YAAY,CAA+C;gBAGjE,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,WAAgB,EACzB,eAAe,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;IAoB/C,qEAAqE;IACrE,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAgB1D,sDAAsD;IACtD,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY;IAiB1C,OAAO,CAAC,OAAO;IAUf,OAAO,CAAC,QAAQ;IAgBV,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAUzB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQnD,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}
+{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../src/pool.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAY/D,MAAM,WAAW,WAAY,SAAQ,aAAa;IAChD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgC;IACxD,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAC9C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA0B;IAC1D,OAAO,CAAC,YAAY,CAA+C;gBAGjE,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,WAAgB,EACzB,eAAe,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;IAoB/C,qEAAqE;IACrE,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAgB1D,2EAA2E;IAC3E,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAQ9D,sDAAsD;IACtD,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY;IAiB1C,OAAO,CAAC,OAAO;IAUf,OAAO,CAAC,QAAQ;IAgBV,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAUzB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQnD,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}

package/dist/tools/reading.d.ts

@@ -21,6 +21,17 @@ export interface ReadingSurface {
     outline: boolean;
     zoom: boolean;
 }
+interface ZoomBatchSymbolResult {
+    name: string;
+    success: boolean;
+    content?: string;
+    error?: string;
+}
+interface ZoomBatchResult {
+    complete: boolean;
+    symbols: ZoomBatchSymbolResult[];
+    text: string;
+}
 /** Exported for renderer unit tests. */
 export declare function buildOutlineSections(text: string, theme: Theme): string[];
 /** Exported for renderer unit tests. */
@@ -34,5 +45,7 @@ export declare function renderZoomCall(args: Static<typeof ZoomParams>, theme: T
 /** Exported for renderer unit tests. */
 export declare function renderZoomResult(result: AgentToolResult<unknown>, args: Static<typeof ZoomParams>, theme: Theme, context: RenderContextLike): import("@mariozechner/pi-tui").Text | import("@mariozechner/pi-tui").Container;
 export declare function registerReadingTools(pi: ExtensionAPI, ctx: PluginContext, surface: ReadingSurface): void;
+/** Exported for regression tests. */
+export declare function formatZoomBatchResult(symbols: string[], responses: Record<string, unknown>[]): ZoomBatchResult;
 export {};
 //# sourceMappingURL=reading.d.ts.map

package/dist/tools/reading.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reading.d.ts","sourceRoot":"","sources":["../../src/tools/reading.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,+BAA+B,CAAC;AAC1F,OAAO,EAAE,KAAK,MAAM,EAAQ,MAAM,mBAAmB,CAAC;AAEtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,EAOL,KAAK,iBAAiB,EAKvB,MAAM,qBAAqB,CAAC;AAE7B,QAAA,MAAM,aAAa;;;;EAYjB,CAAC;AAEH,QAAA,MAAM,UAAU;;;;;EAWd,CAAC;AAEH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;CACf;AAED,wCAAwC;AACxC,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,MAAM,EAAE,CAOzE;AAED,wCAAwC;AACxC,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,CAAC,OAAO,UAAU,CAAC,EAC/B,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,KAAK,GACX,MAAM,EAAE,CA4DV;AAED,wCAAwC;AACxC,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,CAAC,OAAO,aAAa,CAAC,EAClC,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,iBAAiB,uCAU3B;AAED,wCAAwC;AACxC,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,eAAe,CAAC,OAAO,CAAC,EAChC,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,iBAAiB,kFAI3B;AAED,wCAAwC;AACxC,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,CAAC,OAAO,UAAU,CAAC,EAC/B,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,iBAAiB,uCAQ3B;AAED,wCAAwC;AACxC,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,eAAe,CAAC,OAAO,CAAC,EAChC,IAAI,EAAE,MAAM,CAAC,OAAO,UAAU,CAAC,EAC/B,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,iBAAiB,kFAI3B;AAED,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,YAAY,EAChB,GAAG,EAAE,aAAa,EAClB,OAAO,EAAE,cAAc,GACtB,IAAI,CAkHN"}
+{"version":3,"file":"reading.d.ts","sourceRoot":"","sources":["../../src/tools/reading.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,+BAA+B,CAAC;AAC1F,OAAO,EAAE,KAAK,MAAM,EAAQ,MAAM,mBAAmB,CAAC;AAEtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,EAOL,KAAK,iBAAiB,EAKvB,MAAM,qBAAqB,CAAC;AAE7B,QAAA,MAAM,aAAa;;;;EAYjB,CAAC;AAEH,QAAA,MAAM,UAAU;;;;;EAWd,CAAC;AAEH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;CACf;AAED,UAAU,qBAAqB;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,eAAe;IACvB,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,qBAAqB,EAAE,CAAC;IACjC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wCAAwC;AACxC,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,MAAM,EAAE,CAOzE;AAED,wCAAwC;AACxC,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,CAAC,OAAO,UAAU,CAAC,EAC/B,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,KAAK,GACX,MAAM,EAAE,CAuFV;AAED,wCAAwC;AACxC,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,CAAC,OAAO,aAAa,CAAC,EAClC,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,iBAAiB,uCAU3B;AAED,wCAAwC;AACxC,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,eAAe,CAAC,OAAO,CAAC,EAChC,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,iBAAiB,kFAI3B;AAED,wCAAwC;AACxC,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,CAAC,OAAO,UAAU,CAAC,EAC/B,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,iBAAiB,uCAQ3B;AAED,wCAAwC;AACxC,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,eAAe,CAAC,OAAO,CAAC,EAChC,IAAI,EAAE,MAAM,CAAC,OAAO,UAAU,CAAC,EAC/B,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,iBAAiB,kFAI3B;AAED,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,YAAY,EAChB,GAAG,EAAE,aAAa,EAClB,OAAO,EAAE,cAAc,GACtB,IAAI,CAsHN;AAED,qCAAqC;AACrC,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EAAE,EACjB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GACnC,eAAe,CA0BjB"}

package/dist/workflow-hints.d.ts

@@ -0,0 +1,31 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { AftConfig } from "./config.js";
+export interface WorkflowHintsOpts {
+    toolSurface: "minimal" | "recommended" | "all";
+    hoistBuiltins: boolean;
+    semanticEnabled: boolean;
+    bashBackgroundEnabled: boolean;
+    /** Set of tool names KNOWN-ABSENT from the registered surface. */
+    absentTools: Set<string>;
+}
+export declare function buildWorkflowHints(opts: WorkflowHintsOpts): string | null;
+export declare function buildHintsFromConfig(config: AftConfig, absentTools: Set<string>, hoistBuiltins: boolean): string | null;
+interface ToolSurfaceFlags {
+    outline: boolean;
+    zoom: boolean;
+    semantic: boolean;
+    navigate: boolean;
+    hoistGrep: boolean;
+    hoistBash: boolean;
+}
+/**
+ * Register the workflow-hints extension on Pi via `before_agent_start`.
+ *
+ * Pi assembles a fresh system prompt for every turn, then fires
+ * `before_agent_start` with the assembled prompt. Our handler appends the
+ * AFT workflow hints block to that prompt. If multiple extensions return a
+ * `systemPrompt`, Pi chains them — so we always append (never replace).
+ */
+export declare function registerWorkflowHints(pi: ExtensionAPI, config: AftConfig, surface: ToolSurfaceFlags): void;
+export {};
+//# sourceMappingURL=workflow-hints.d.ts.map

package/dist/workflow-hints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-hints.d.ts","sourceRoot":"","sources":["../src/workflow-hints.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAG7C,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,SAAS,GAAG,aAAa,GAAG,KAAK,CAAC;IAC/C,aAAa,EAAE,OAAO,CAAC;IACvB,eAAe,EAAE,OAAO,CAAC;IACzB,qBAAqB,EAAE,OAAO,CAAC;IAC/B,kEAAkE;IAClE,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC1B;AAID,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,GAAG,IAAI,CA8DzE;AAED,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,SAAS,EACjB,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,EACxB,aAAa,EAAE,OAAO,GACrB,MAAM,GAAG,IAAI,CAQf;AAMD,UAAU,gBAAgB;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,YAAY,EAChB,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,gBAAgB,GACxB,IAAI,CA8BN"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cortexkit/aft-pi",
-  "version": "0.18.3",
+  "version": "0.18.4",
   "type": "module",
   "description": "Pi coding agent extension for Agent File Tools (AFT) — tree-sitter and LSP-powered code analysis",
   "main": "dist/index.js",
@@ -28,11 +28,11 @@
     "zod": "^4.1.8"
   },
   "optionalDependencies": {
-    "@cortexkit/aft-darwin-arm64": "0.18.3",
-    "@cortexkit/aft-darwin-x64": "0.18.3",
-    "@cortexkit/aft-linux-arm64": "0.18.3",
-    "@cortexkit/aft-linux-x64": "0.18.3",
-    "@cortexkit/aft-win32-x64": "0.18.3"
+    "@cortexkit/aft-darwin-arm64": "0.18.4",
+    "@cortexkit/aft-darwin-x64": "0.18.4",
+    "@cortexkit/aft-linux-arm64": "0.18.4",
+    "@cortexkit/aft-linux-x64": "0.18.4",
+    "@cortexkit/aft-win32-x64": "0.18.4"
   },
   "devDependencies": {
     "@mariozechner/pi-coding-agent": "*",