@howaboua/pi-better-skills-tool 0.0.9 → 0.0.11

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.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,16 @@
1
1
  # @howaboua/pi-better-skills-tool
2
2
 
3
+ ## 0.0.11
4
+
5
+ - - Skills help and catalog results now explain reference-only reads and batching skill bodies with references.
6
+ - Invalid Code and Notebook calls now show no-argument discovery syntax.
7
+ - GPT-mode catalog help uses denser guidance.
8
+ - Skill results include structured read receipts for usage tracking, distinguishing references and continuation pages.
9
+
10
+ ## 0.0.10
11
+
12
+ - Use consistent skill discovery across native, Code and Notebook modes, with compact help in PCC GPT prompt mode.
13
+
3
14
  ## 0.0.9
4
15
 
5
16
  - Skills discovery and invalid-input errors now show the JavaScript string-call syntax.
package/README.md CHANGED
@@ -8,7 +8,7 @@ Progressive skill discovery for Pi, Code Mode and Notebook Mode. The `skills` to
8
8
  pi install npm:@howaboua/pi-better-skills-tool
9
9
  ```
10
10
 
11
- Requires Pi 1.0.0 or newer. Install `@howaboua/pi-codex-conversion` 3.0.43 or newer too for Code Mode and Notebook Mode. The extension remains a normal Pi tool when Codex conversion is absent.
11
+ Requires Pi 1.0.0 or newer. Install `@howaboua/pi-codex-conversion` 3.0.52 or newer too for Code Mode and Notebook Mode. The extension remains a normal Pi tool when Codex conversion is absent.
12
12
 
13
13
  ## Start Pi normally
14
14
 
@@ -38,5 +38,3 @@ Separate independent `read` or `list` commands with `;`. Each group resolves ref
38
38
  Results stay within 48 KiB of UTF-8 text. Larger results include an `Incomplete` marker and an exact continuation command ending in `--offset <byte>`. Run that command to retrieve the next part. Continuations are stateless and re-read the catalog, so restart the original command if skill files change between calls. Normalized commands, excluding the offset suffix, are limited to 4 KiB to keep continuation instructions within the result budget.
39
39
 
40
40
  Remove or disable any legacy `codex-conversion-custom-tools/skills.toml` after installing this extension. Keeping both definitions gives Code Mode two tools named `skills`, which it rejects.
41
-
42
- The Code Mode surface is freeform because its input is already a compact routed command. It does not add a provider grammar. Code Mode's outer `exec` grammar remains the only constrained grammar involved.
package/biome.json CHANGED
@@ -1,5 +1,5 @@
1
1
  {
2
- "$schema": "https://biomejs.dev/schemas/2.5.10/schema.json",
2
+ "$schema": "https://biomejs.dev/schemas/2.5.15/schema.json",
3
3
  "vcs": {
4
4
  "enabled": true,
5
5
  "clientKind": "git",
package/index.ts CHANGED
@@ -35,8 +35,34 @@ export default async function skillsExtension(pi: ExtensionAPI): Promise<void> {
35
35
  );
36
36
  }
37
37
  });
38
- const tool = createSkillsTool({ getLoadedSkills: () => loadedSkills });
38
+ let gpt = false;
39
+ const tool = createSkillsTool({
40
+ getLoadedSkills: () => loadedSkills,
41
+ isGpt: () => gpt,
42
+ });
39
43
  pi.registerTool(tool);
44
+ try {
45
+ const { registerGptPromptMode } = await import(
46
+ "@howaboua/pi-codex-conversion/prompt-mode"
47
+ );
48
+ registerGptPromptMode(pi, (active) => {
49
+ gpt = active;
50
+ return [tool];
51
+ });
52
+ } catch (error) {
53
+ if (
54
+ !(error instanceof Error) ||
55
+ !("code" in error) ||
56
+ ![
57
+ "ERR_MODULE_NOT_FOUND",
58
+ "MODULE_NOT_FOUND",
59
+ "ERR_PACKAGE_PATH_NOT_EXPORTED",
60
+ ].includes(String(error.code)) ||
61
+ !error.message.includes(CODE_MODE_PACKAGE)
62
+ )
63
+ throw error;
64
+ }
65
+
40
66
  const registration = await registerSkillsInCodeMode(pi, tool);
41
67
  pi.on("session_shutdown", () => {
42
68
  registration?.unregister();
@@ -56,7 +82,7 @@ async function registerSkillsInCodeMode(
56
82
  adaptToolForCodeMode(tool, {
57
83
  kind: "freeform",
58
84
  prepareInput: prepareSkillsCodeModeInput,
59
- usage: "await tools.skills() // discovery",
85
+ discovery: "help",
60
86
  }),
61
87
  ]);
62
88
  } catch (error) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@howaboua/pi-better-skills-tool",
3
- "version": "0.0.9",
3
+ "version": "0.0.11",
4
4
  "description": "Progressive skill discovery for Pi, Code Mode and Notebook Mode.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -39,7 +39,7 @@
39
39
  "pack:dry": "npm pack --dry-run"
40
40
  },
41
41
  "peerDependencies": {
42
- "@howaboua/pi-codex-conversion": ">=3.0.49",
42
+ "@howaboua/pi-codex-conversion": ">=4.0.3",
43
43
  "@earendil-works/pi-coding-agent": ">=1.0.0",
44
44
  "@earendil-works/pi-tui": ">=1.0.0",
45
45
  "typebox": "*"
@@ -50,12 +50,12 @@
50
50
  }
51
51
  },
52
52
  "devDependencies": {
53
- "@howaboua/pi-codex-conversion": "3.0.49",
54
- "@biomejs/biome": "^2.5.10",
55
- "@earendil-works/pi-coding-agent": "1.1.0",
56
- "@earendil-works/pi-tui": "1.1.0",
57
- "@types/node": "^26.2.0",
58
- "typebox": "1.3.18",
53
+ "@howaboua/pi-codex-conversion": "4.0.3",
54
+ "@biomejs/biome": "^2.5.15",
55
+ "@earendil-works/pi-coding-agent": "1.3.0",
56
+ "@earendil-works/pi-tui": "1.3.0",
57
+ "@types/node": "^26.6.5",
58
+ "typebox": "1.3.37",
59
59
  "typescript": "^7.0.2"
60
60
  },
61
61
  "pi": {
package/src/catalog.ts CHANGED
@@ -6,7 +6,7 @@ import {
6
6
  discoverVisibleSkills,
7
7
  type LoadedSkill,
8
8
  } from "./discovery.js";
9
- import { readSkillPackage } from "./skill-package.js";
9
+ import { readSkillPackage, type SkillReadOutput } from "./skill-package.js";
10
10
 
11
11
  export type { LoadedSkill } from "./discovery.js";
12
12
  export { defaultSessionSkillsDir, defaultSkillsDir } from "./discovery.js";
@@ -14,6 +14,10 @@ export { defaultSessionSkillsDir, defaultSkillsDir } from "./discovery.js";
14
14
  const MAX_OUTPUT_BYTES = 48 * 1024;
15
15
  // Leave room for an exact continuation command inside the output budget.
16
16
  const MAX_COMMAND_BYTES = 4 * 1024;
17
+ const READ_HELP =
18
+ "Reference-only selectors omit the initial skill body. To read a body plus references, use separate commands: read skill; read other/references/topic";
19
+ const GPT_READ_HELP =
20
+ "Reference-only selectors→no initial skill body; body+refs→separate commands: read skill; read other/references/topic";
17
21
 
18
22
  type SkillRequest =
19
23
  | { action: "help" }
@@ -133,7 +137,8 @@ function formatSkillList(
133
137
  return lines.join("\n");
134
138
  }
135
139
 
136
- function boundedOutput(output: string, request: SkillsRequest): string {
140
+ function boundedOutput(result: SkillReadOutput, request: SkillsRequest) {
141
+ const { output, reads } = result;
137
142
  const bytes = Buffer.from(output);
138
143
  const { offset } = request;
139
144
  if (offset > bytes.length || (offset > 0 && offset === bytes.length))
@@ -142,14 +147,31 @@ function boundedOutput(output: string, request: SkillsRequest): string {
142
147
  );
143
148
  if (offset < bytes.length && ((bytes[offset] ?? 0) & 0xc0) === 0x80)
144
149
  throw new Error(`--offset ${offset} splits a UTF-8 character`);
150
+ const page = (output: string, end: number) => ({
151
+ output,
152
+ skillReads: {
153
+ version: 1 as const,
154
+ // Only exposed body bytes count, not labels, path inventories or footers.
155
+ reads: reads
156
+ .filter(
157
+ (span) =>
158
+ span.start < span.end && span.start < end && span.end > offset,
159
+ )
160
+ .map(({ read }) => read),
161
+ continuation: offset > 0,
162
+ },
163
+ });
145
164
  if (bytes.length - offset <= MAX_OUTPUT_BYTES)
146
- return offset === 0 ? output : bytes.subarray(offset).toString("utf8");
165
+ return page(
166
+ offset === 0 ? output : bytes.subarray(offset).toString("utf8"),
167
+ bytes.length,
168
+ );
147
169
  const command = formatCommand(request.commands);
148
170
  const footer = (end: number) =>
149
171
  `\n\n---\nIncomplete: bytes ${offset}-${end} of ${bytes.length}. Continue with command:\n${command} --offset ${end}`;
150
172
  let end = offset + MAX_OUTPUT_BYTES - Buffer.byteLength(footer(bytes.length));
151
173
  while (((bytes[end] ?? 0) & 0xc0) === 0x80) end--;
152
- return bytes.subarray(offset, end).toString("utf8") + footer(end);
174
+ return page(bytes.subarray(offset, end).toString("utf8") + footer(end), end);
153
175
  }
154
176
 
155
177
  export function runSkills(
@@ -159,19 +181,34 @@ export function runSkills(
159
181
  ? defaultSessionSkillsDir()
160
182
  : undefined,
161
183
  loadedSkills: readonly LoadedSkill[] = [],
162
- ): string {
184
+ gpt = false,
185
+ ) {
163
186
  const request = parseRequest(input);
164
187
  const skills = discoverVisibleSkills(globalRoot, sessionRoot, loadedSkills);
165
- return boundedOutput(
166
- request.commands
167
- .map((command) =>
188
+ const result: SkillReadOutput = { output: "", reads: [] };
189
+ for (const [index, command] of request.commands.entries()) {
190
+ if (index) result.output += "\n\n";
191
+ if (command.action === "read") {
192
+ const selected = readSkillPackage(
193
+ skills,
194
+ command.name,
195
+ command.selectors,
196
+ );
197
+ const start = Buffer.byteLength(result.output);
198
+ result.output += selected.output;
199
+ result.reads.push(
200
+ ...selected.reads.map((span) => ({
201
+ read: span.read,
202
+ start: start + span.start,
203
+ end: start + span.end,
204
+ })),
205
+ );
206
+ } else {
207
+ result.output +=
168
208
  command.action === "help"
169
- ? `Commands: list [category...] | read <skill> [skill-or-reference...] | help. Join commands with ;\nJS: tools.skills("read <skill>")\n\n${formatSkillList(skills)}`
170
- : command.action === "list"
171
- ? formatSkillList(skills, command.categories)
172
- : readSkillPackage(skills, command.name, command.selectors),
173
- )
174
- .join("\n\n"),
175
- request,
176
- );
209
+ ? `${gpt ? 'list [category...] | read <skill> [skill-or-reference...] | help; separator ;\nJS: tools.skills("read <skill>")' : 'Commands: list [category...] | read <skill> [skill-or-reference...] | help. Join commands with ;\nJS: tools.skills("read <skill>")'}\n${gpt ? GPT_READ_HELP : READ_HELP}\n\n${formatSkillList(skills)}`
210
+ : `${gpt ? GPT_READ_HELP : READ_HELP}\n\n${formatSkillList(skills, command.categories)}`;
211
+ }
212
+ }
213
+ return boundedOutput(result, request);
177
214
  }
@@ -1,3 +1,4 @@
1
+ import { Buffer } from "node:buffer";
1
2
  import { readFileSync, realpathSync, statSync } from "node:fs";
2
3
  import { isAbsolute, join, relative, resolve, sep } from "node:path";
3
4
  import {
@@ -135,10 +136,6 @@ function formatSkillPaths(skill: CatalogSkill): string {
135
136
  return `---\nSkill paths (${paths.length}):\n${paths.map((path) => `- ${path}`).join("\n")}`;
136
137
  }
137
138
 
138
- function formatSkill(skill: CatalogSkill): string {
139
- return `${skill.body}\n\n${formatSkillPaths(skill)}`;
140
- }
141
-
142
139
  function referenceFiles(skill: CatalogSkill): string[] {
143
140
  const root = resolve(skill.directory, "references");
144
141
  return packageFiles(skill).filter(
@@ -279,51 +276,59 @@ function deduplicateSelections(selections: ReadSelection[]): ReadSelection[] {
279
276
  });
280
277
  }
281
278
 
282
- function formatReferences(selected: ReferenceSelection[]): string {
283
- const oneSkill = new Set(selected.map(({ skill }) => skill.name)).size === 1;
284
- const withContent = selected.map((selection) => ({
285
- ...selection,
286
- content: readFileSync(selection.path, "utf8").trim(),
287
- }));
288
- const content =
289
- withContent.length === 1
290
- ? (withContent[0]?.content ?? "")
291
- : withContent
292
- .map(({ skill, reference, content: body }) => {
293
- const label = oneSkill
294
- ? reference
295
- : `${skill.name}/references/${reference}`;
296
- return `--- ${label} ---\n${body}`;
297
- })
298
- .join("\n\n");
299
- return `${content}\n\n---\nSources:\n${withContent.map(({ path }) => `- ${path}`).join("\n")}`;
279
+ interface SkillRead {
280
+ name: string;
281
+ skillPath: string;
282
+ path: string;
283
+ kind: "skill" | "reference";
300
284
  }
301
285
 
302
- function formatMixedSelections(selections: ReadSelection[]): string {
303
- const content = selections
304
- .map((selection) => {
305
- if (selection.kind === "skill") {
306
- return `--- ${selection.skill.name} ---\n${formatSkill(selection.skill)}`;
307
- }
308
- return `--- ${selection.skill.name}/references/${selection.reference} ---\n${readFileSync(selection.path, "utf8").trim()}`;
309
- })
310
- .join("\n\n");
311
- const sources = selections
312
- .filter(
313
- (selection): selection is ReferenceSelection =>
314
- selection.kind === "reference",
315
- )
316
- .map(({ path }) => `- ${path}`);
317
- return sources.length
318
- ? `${content}\n\n---\nSources:\n${sources.join("\n")}`
319
- : content;
286
+ export interface SkillReadOutput {
287
+ output: string;
288
+ reads: { read: SkillRead; start: number; end: number }[];
289
+ }
290
+
291
+ function formatSelections(selections: ReadSelection[]): SkillReadOutput {
292
+ const referencesOnly = selections.every(({ kind }) => kind === "reference");
293
+ const oneSkill =
294
+ new Set(selections.map(({ skill }) => skill.name)).size === 1;
295
+ const result: SkillReadOutput = { output: "", reads: [] };
296
+ const sources: string[] = [];
297
+ for (const selection of selections) {
298
+ if (result.reads.length) result.output += "\n\n";
299
+ const { skill, kind } = selection;
300
+ const path = kind === "skill" ? skill.path : selection.path;
301
+ const body =
302
+ kind === "skill" ? skill.body : readFileSync(path, "utf8").trim();
303
+ if (selections.length > 1) {
304
+ const label =
305
+ kind === "skill"
306
+ ? skill.name
307
+ : referencesOnly && oneSkill
308
+ ? selection.reference
309
+ : `${skill.name}/references/${selection.reference}`;
310
+ result.output += `--- ${label} ---\n`;
311
+ }
312
+ const start = Buffer.byteLength(result.output);
313
+ result.output += body;
314
+ result.reads.push({
315
+ read: { name: skill.name, skillPath: skill.path, path, kind },
316
+ start,
317
+ end: Buffer.byteLength(result.output),
318
+ });
319
+ if (kind === "skill") result.output += `\n\n${formatSkillPaths(skill)}`;
320
+ else sources.push(`- ${path}`);
321
+ }
322
+ if (sources.length)
323
+ result.output += `\n\n---\nSources:\n${sources.join("\n")}`;
324
+ return result;
320
325
  }
321
326
 
322
327
  export function readSkillPackage(
323
328
  skills: CatalogSkill[],
324
329
  name: string,
325
330
  selectors: string[],
326
- ): string {
331
+ ): SkillReadOutput {
327
332
  const catalog: ReferenceCatalog = new Map();
328
333
  const primary = resolvePrimarySelection(skills, name, catalog);
329
334
  let selectedSkill = primary.skill;
@@ -346,16 +351,5 @@ export function readSkillPackage(
346
351
  ? additional
347
352
  : [primary, ...additional],
348
353
  );
349
- if (selections.length === 1) {
350
- const selection = selections[0] as ReadSelection;
351
- return selection.kind === "skill"
352
- ? formatSkill(selection.skill)
353
- : formatReferences([selection]);
354
- }
355
- return selections.every(
356
- (selection): selection is ReferenceSelection =>
357
- selection.kind === "reference",
358
- )
359
- ? formatReferences(selections)
360
- : formatMixedSelections(selections);
354
+ return formatSelections(selections);
361
355
  }
package/src/tool.ts CHANGED
@@ -10,7 +10,7 @@ import {
10
10
 
11
11
  const SkillsParameters = Type.Object(
12
12
  {
13
- command: Type.Optional(Type.String({ description: "Omit for discovery" })),
13
+ command: Type.Optional(Type.String({ description: "help, list or read" })),
14
14
  },
15
15
  { additionalProperties: false },
16
16
  );
@@ -18,6 +18,7 @@ const SkillsParameters = Type.Object(
18
18
  type SkillsParameters = Static<typeof SkillsParameters>;
19
19
 
20
20
  export interface SkillsToolOptions {
21
+ isGpt?(): boolean;
21
22
  globalRoot?: string;
22
23
  getLoadedSkills?(): readonly LoadedSkill[];
23
24
  }
@@ -25,7 +26,9 @@ export interface SkillsToolOptions {
25
26
  export function prepareSkillsCodeModeInput(input: unknown): SkillsParameters {
26
27
  if (input === undefined) return {};
27
28
  if (typeof input !== "string")
28
- throw new Error('Expected string: tools.skills("read <skill>")');
29
+ throw new Error(
30
+ 'Expected a string command or no arguments: tools.skills() for discovery, tools.skills("read <skill>") to read',
31
+ );
29
32
  return { command: input };
30
33
  }
31
34
 
@@ -39,15 +42,16 @@ export function createSkillsTool(options: SkillsToolOptions = {}) {
39
42
  ],
40
43
  parameters: SkillsParameters,
41
44
  async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
42
- const output = runSkills(
45
+ const { output, skillReads } = runSkills(
43
46
  params.command ?? "",
44
47
  options.globalRoot ?? defaultSkillsDir(),
45
48
  defaultSessionSkillsDir(ctx.cwd),
46
49
  options.getLoadedSkills?.() ?? [],
50
+ options.isGpt?.() ?? false,
47
51
  );
48
52
  return {
49
53
  content: [{ type: "text", text: output }],
50
- details: {},
54
+ details: { skillReads },
51
55
  };
52
56
  },
53
57
  });