@cad0p/pi-napkin 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -157,7 +157,7 @@ export default function (pi: ExtensionAPI) {
157
157
  "## Napkin vault context\n" +
158
158
  "You have access to a napkin vault (Obsidian-compatible knowledge base). " +
159
159
  "Here is the vault overview. Use the kb_search tool to find specific content, " +
160
- "and the kb_read tool to read files.\n\n" +
160
+ "kb_read to read files, and kb_outline to see file structure.\n\n" +
161
161
  overview,
162
162
  true,
163
163
  );
@@ -197,31 +197,64 @@ export default function (pi: ExtensionAPI) {
197
197
  promptSnippet: "Search the napkin vault for notes by keyword or topic",
198
198
  parameters: Type.Object({
199
199
  query: Type.String({ description: "Search query" }),
200
+ page: Type.Optional(
201
+ Type.Number({
202
+ description:
203
+ "Page number (1-based). Pass page+1 when the previous result says to continue.",
204
+ }),
205
+ ),
200
206
  }),
201
207
  async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
202
208
  const n = getNapkin(ctx.cwd);
203
- const results = n.search(params.query);
209
+ const page = params.page ?? 1;
210
+ const res = n.searchPaginated(params.query, { page });
204
211
 
205
- if (results.length === 0) {
212
+ if (res.results.length === 0) {
206
213
  return {
207
214
  content: [{ type: "text", text: "No results found." }],
208
- details: { results: [] },
215
+ details: { results: [], page },
209
216
  };
210
217
  }
211
218
 
212
- const text = results
219
+ // Vault notes often store whole paragraphs on a single source line, so
220
+ // match-only snippets can still be 700+ chars. Cap per-file snippet
221
+ // count and per-line length; full context stays reachable via kb_read.
222
+ const MAX_SNIPPETS_PER_FILE = 5;
223
+ const MAX_SNIPPET_LINE_CHARS = 200;
224
+ let text = res.results
213
225
  .map((r) => {
214
226
  let entry = `**${r.file}**`;
215
- if (r.snippets && r.snippets.length > 0) {
216
- entry += `\n${r.snippets.map((s) => ` ${s.text}`).join("\n")}`;
227
+ const snips = r.snippets ?? [];
228
+ if (snips.length > 0) {
229
+ const shown = snips.slice(0, MAX_SNIPPETS_PER_FILE);
230
+ entry += `\n${shown
231
+ .map((s) => {
232
+ const line =
233
+ s.text.length > MAX_SNIPPET_LINE_CHARS
234
+ ? `${s.text.slice(0, MAX_SNIPPET_LINE_CHARS)}…`
235
+ : s.text;
236
+ return ` ${line}`;
237
+ })
238
+ .join("\n")}`;
239
+ if (snips.length > MAX_SNIPPETS_PER_FILE) {
240
+ entry += `\n … (+${snips.length - MAX_SNIPPETS_PER_FILE} more matches — use kb_read for full context)`;
241
+ }
217
242
  }
218
243
  return entry;
219
244
  })
220
245
  .join("\n\n");
221
246
 
247
+ if (page < res.totalPages) {
248
+ text += `\n\n[Page ${page} of ${res.totalPages}. Use kb_search with page ${page + 1} to continue.]`;
249
+ }
250
+
251
+ text +=
252
+ "\n\nHINT: Use kb_read <file> to open a full file. " +
253
+ "Use kb_outline <file> to see its structure.";
254
+
222
255
  return {
223
256
  content: [{ type: "text", text }],
224
- details: { results },
257
+ details: { results: res.results, page, totalPages: res.totalPages },
225
258
  };
226
259
  },
227
260
  renderResult(result, options, theme, context) {
@@ -239,10 +272,21 @@ export default function (pi: ExtensionAPI) {
239
272
  promptSnippet: "Read a note from the napkin vault by name or path",
240
273
  parameters: Type.Object({
241
274
  file: Type.String({ description: "File name or path to read" }),
275
+ section: Type.Optional(
276
+ Type.String({
277
+ description: "Heading to extract (exact text without # prefix)",
278
+ }),
279
+ ),
280
+ page: Type.Optional(
281
+ Type.Number({ description: "Page number for paginated output" }),
282
+ ),
242
283
  }),
243
284
  async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
244
285
  const n = getNapkin(ctx.cwd);
245
- const result = n.read(params.file);
286
+ const result = n.read(params.file, {
287
+ section: params.section,
288
+ page: params.page,
289
+ });
246
290
 
247
291
  return {
248
292
  content: [{ type: "text", text: result.content }],
@@ -256,4 +300,53 @@ export default function (pi: ExtensionAPI) {
256
300
  return t;
257
301
  },
258
302
  });
303
+
304
+ pi.registerTool({
305
+ name: "kb_outline",
306
+ label: "KB Outline",
307
+ description: "List headings in a knowledge base file",
308
+ promptSnippet:
309
+ "List headings in a napkin vault note to understand its structure",
310
+ parameters: Type.Object({
311
+ file: Type.String({ description: "File name or path" }),
312
+ }),
313
+ async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
314
+ const n = getNapkin(ctx.cwd);
315
+ let headings: { level: number; text: string; line: number }[];
316
+ try {
317
+ headings = n.outline(params.file);
318
+ } catch (e: unknown) {
319
+ return {
320
+ content: [{ type: "text", text: (e as Error).message }],
321
+ details: { headings: [] },
322
+ };
323
+ }
324
+
325
+ // outline() doesn't return the resolved path and bare note names can
326
+ // resolve into subfolders, so probe a 1-byte read which returns the
327
+ // resolved path. Fall back to the naive join if resolution fails.
328
+ let absPath = path.join(n.vault.contentPath, params.file);
329
+ try {
330
+ absPath = n.read(params.file, { page: 1, pageSize: 1 }).path;
331
+ } catch {
332
+ // keep the join fallback
333
+ }
334
+
335
+ const lines = [`File: ${absPath}`];
336
+ for (const h of headings) {
337
+ lines.push(`${"#".repeat(h.level)} ${h.text}`);
338
+ }
339
+
340
+ return {
341
+ content: [{ type: "text", text: lines.join("\n") }],
342
+ details: { path: absPath, headings },
343
+ };
344
+ },
345
+ renderResult(result, options, theme, context) {
346
+ const t =
347
+ (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
348
+ t.setText(formatKbResult(result, options, theme, 15));
349
+ return t;
350
+ },
351
+ });
259
352
  }
package/package.json CHANGED
@@ -1,9 +1,8 @@
1
1
  {
2
2
  "name": "@cad0p/pi-napkin",
3
- "version": "0.4.0",
3
+ "version": "0.5.0",
4
4
  "description": "📜 Napkin integration for pi — vault context, knowledge tools, and automatic distillation with git-worktree concurrency safety",
5
5
  "type": "module",
6
- "packageManager": "pnpm@11.10.0",
7
6
  "publishConfig": {
8
7
  "access": "public",
9
8
  "registry": "https://registry.npmjs.org"
@@ -65,7 +64,7 @@
65
64
  "vitest": "^2.1.0"
66
65
  },
67
66
  "dependencies": {
68
- "@cad0p/napkin": "^0.10.0"
67
+ "@cad0p/napkin": "^0.11.0"
69
68
  },
70
69
  "peerDependencies": {
71
70
  "@earendil-works/pi-coding-agent": ">=0.74.0",