@fro.bot/systematic 3.27.1 → 3.28.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.
Files changed (36) hide show
  1. package/ATTRIBUTIONS.md +2 -2
  2. package/HARNESSES.md +24 -11
  3. package/agents/research/learnings-researcher.md +49 -9
  4. package/dist/claude-code-search.d.ts +30 -0
  5. package/dist/claude-code-validator-bin.d.ts +17 -0
  6. package/dist/cli.d.ts +18 -0
  7. package/dist/cli.js +335 -108
  8. package/dist/{index-608preny.js → index-9chxhh5j.js} +1120 -72
  9. package/dist/index.js +204 -8
  10. package/dist/lib/agent-resolver.d.ts +8 -2
  11. package/dist/lib/asset-plan.d.ts +23 -1
  12. package/dist/lib/config-protected-fields.d.ts +1 -1
  13. package/dist/lib/config-schema.d.ts +6 -0
  14. package/dist/lib/config.d.ts +13 -0
  15. package/dist/lib/main-module.d.ts +30 -0
  16. package/dist/lib/opencode-v2-commands.d.ts +4 -3
  17. package/dist/lib/opencode-v2-skills.d.ts +12 -2
  18. package/dist/lib/opencode-v2.d.ts +1 -0
  19. package/dist/lib/pi-delegate-session.d.ts +3 -1
  20. package/dist/lib/pi-delegate-tool.d.ts +12 -1
  21. package/dist/lib/search-cli.d.ts +52 -0
  22. package/dist/lib/search-core.d.ts +128 -0
  23. package/dist/lib/search-corpus.d.ts +105 -0
  24. package/dist/lib/search-lexical.d.ts +136 -0
  25. package/dist/lib/search-render.d.ts +69 -0
  26. package/dist/lib/search-tool.d.ts +53 -0
  27. package/dist/lib/search-user-config.d.ts +96 -0
  28. package/dist/pi.js +1155 -77
  29. package/package.json +3 -3
  30. package/skills/ce-review/SKILL.md +1 -1
  31. package/skills/ce-review/references/review-output-template.md +1 -1
  32. package/skills/ce-review/scripts/validate-review.mjs +1 -3
  33. package/skills/using-systematic/references/claude-code-profile.md +1 -0
  34. package/skills/using-systematic/references/opencode-profile.md +1 -0
  35. package/skills/using-systematic/references/opencode-v2-profile.md +1 -0
  36. package/skills/using-systematic/references/pi-profile.md +1 -0
package/dist/index.js CHANGED
@@ -2,6 +2,7 @@
2
2
  import {
3
3
  parseFrontmatter,
4
4
  string,
5
+ number,
5
6
  AgentOverlaySchema,
6
7
  CategoryOverlaySchema,
7
8
  isRecord,
@@ -16,8 +17,15 @@ import {
16
17
  findCommandsInDir,
17
18
  extractCommandFrontmatter,
18
19
  findSkillsInDir,
19
- discoverSkills
20
- } from "./index-608preny.js";
20
+ discoverSkills,
21
+ SEARCH_TOOL_NAME,
22
+ SEARCH_ARGS,
23
+ SEARCH_TOOL_DESCRIPTION,
24
+ SEARCH_ARG_DESCRIPTIONS,
25
+ SEARCH_NOTICES,
26
+ SEARCH_CONFIG_UNREADABLE_NOTE,
27
+ runSearch
28
+ } from "./index-9chxhh5j.js";
21
29
 
22
30
  // src/index.ts
23
31
  import path8 from "path";
@@ -670,8 +678,17 @@ function loadDiscoveredSkillAsCommand(skill) {
670
678
  description
671
679
  };
672
680
  }
681
+ function declaredRoutingOf(skill) {
682
+ const { agent, model, subtask } = skill.frontmatter;
683
+ return {
684
+ ...agent === undefined ? {} : { agent },
685
+ ...model === undefined ? {} : { model },
686
+ ...subtask === undefined ? {} : { subtask }
687
+ };
688
+ }
673
689
  function collectDiscoveredSkillsAsCommands(startDir, homeDir, configDir, opencodeConfigDirOverride, disabledCommands) {
674
690
  const commands = {};
691
+ const routing = {};
675
692
  let discovered;
676
693
  try {
677
694
  discovered = discoverSkills({
@@ -681,7 +698,7 @@ function collectDiscoveredSkillsAsCommands(startDir, homeDir, configDir, opencod
681
698
  opencodeConfigDirOverride
682
699
  });
683
700
  } catch {
684
- return commands;
701
+ return { commands, routing };
685
702
  }
686
703
  for (const skill of discovered) {
687
704
  if (skill.frontmatter.userInvocable === false)
@@ -690,9 +707,12 @@ function collectDiscoveredSkillsAsCommands(startDir, homeDir, configDir, opencod
690
707
  continue;
691
708
  try {
692
709
  commands[skill.name] = loadDiscoveredSkillAsCommand(skill);
710
+ const declared = declaredRoutingOf(skill);
711
+ if (Object.keys(declared).length > 0)
712
+ routing[skill.name] = declared;
693
713
  } catch {}
694
714
  }
695
- return commands;
715
+ return { commands, routing };
696
716
  }
697
717
  function collectEnabledSkillNames(dir, disabledSkills) {
698
718
  const disabledSet = new Set(disabledSkills);
@@ -713,7 +733,7 @@ function buildAssetPlan(input) {
713
733
  const resolvedOverlays = resolveAgentOverlaySet(validatedOverlays);
714
734
  const agents = collectAgents(bundledAgentsDir, config.disabled_agents, nativeAgentNames, resolvedOverlays, overlays);
715
735
  const bundledCommands = collectCommands(input.bundledCommandsDir, config.disabled_commands);
716
- const discoveredSkillCommands = config.skills_as_commands !== false ? collectDiscoveredSkillsAsCommands(input.directory, input.homeDir, input.opencodeConfigDir, input.opencodeConfigDirOverride, config.disabled_commands) : {};
736
+ const discovered = config.skills_as_commands !== false ? collectDiscoveredSkillsAsCommands(input.directory, input.homeDir, input.opencodeConfigDir, input.opencodeConfigDirOverride, config.disabled_commands) : { commands: {}, routing: {} };
717
737
  return {
718
738
  skillsDir: bundledSkillsDir,
719
739
  enabledSkills,
@@ -721,8 +741,9 @@ function buildAssetPlan(input) {
721
741
  commands: {
722
742
  ...bundledCommands,
723
743
  ...skillCommands,
724
- ...discoveredSkillCommands
725
- }
744
+ ...discovered.commands
745
+ },
746
+ discoveredRouting: discovered.routing
726
747
  };
727
748
  }
728
749
 
@@ -793,11 +814,71 @@ function toV1AgentConfig(planned) {
793
814
  }
794
815
  return result;
795
816
  }
817
+ var OPENCODE_V1_BUILT_IN_AGENTS = [
818
+ "build",
819
+ "plan",
820
+ "general",
821
+ "explore"
822
+ ];
823
+ function knownAgentNames(agents) {
824
+ const known = new Set(OPENCODE_V1_BUILT_IN_AGENTS);
825
+ for (const [name, agent] of Object.entries(agents ?? {})) {
826
+ if (agent?.disable === true)
827
+ known.delete(name);
828
+ else
829
+ known.add(name);
830
+ }
831
+ return known;
832
+ }
833
+ function agentProblem(agent, isSubtask, known) {
834
+ if (!isSubtask) {
835
+ return `sets agent "${agent}" but does not run as a subtask (context: fork or subtask: true)`;
836
+ }
837
+ return known.has(agent) ? undefined : `sets agent "${agent}", which is not an OpenCode agent`;
838
+ }
839
+ function modelProblem(model) {
840
+ const slash = model.indexOf("/");
841
+ return slash > 0 && slash < model.length - 1 ? undefined : `sets model "${model}", which is not in provider/model form`;
842
+ }
843
+ var IGNORED_ROUTING_HINT = "it is ignored. Write an OpenCode command to route it.";
844
+ function applyDiscoveredRouting(config, plan, reported) {
845
+ const known = knownAgentNames(config.agent);
846
+ const drop = (name, field, reason) => {
847
+ const key = `${name}\x00${field}`;
848
+ if (reported.has(key))
849
+ return;
850
+ reported.add(key);
851
+ console.warn(`[systematic] skill "${name}" ${reason}; ${IGNORED_ROUTING_HINT}`);
852
+ };
853
+ for (const [name, declared] of Object.entries(plan.discoveredRouting)) {
854
+ const command = config.command?.[name];
855
+ if (command === undefined || command !== plan.commands[name])
856
+ continue;
857
+ const { agent, model, subtask } = declared;
858
+ if (agent !== undefined) {
859
+ const problem = agentProblem(agent, subtask === true, known);
860
+ if (problem === undefined)
861
+ command.agent = agent;
862
+ else
863
+ drop(name, "agent", problem);
864
+ }
865
+ if (model !== undefined) {
866
+ const problem = modelProblem(model);
867
+ if (problem === undefined)
868
+ command.model = model;
869
+ else
870
+ drop(name, "model", problem);
871
+ }
872
+ if (subtask !== undefined)
873
+ command.subtask = subtask;
874
+ }
875
+ }
796
876
  function createConfigHandler(deps) {
797
877
  const { directory, bundledSkillsDir, bundledAgentsDir, bundledCommandsDir } = deps;
798
878
  const homeDir = deps.homeDir ?? os2.homedir();
799
879
  const opencodeConfigDir = deps.opencodeConfigDir ?? path4.join(homeDir, ".config/opencode");
800
880
  const opencodeConfigDirOverride = process.env.OPENCODE_CONFIG_DIR?.trim() ? process.env.OPENCODE_CONFIG_DIR : undefined;
881
+ const reportedRouting = new Set;
801
882
  return async (config) => {
802
883
  const { config: systematicConfig, overlays } = loadConfigWithSources(directory);
803
884
  const existingAgents = { ...config.agent ?? {} };
@@ -822,6 +903,7 @@ function createConfigHandler(deps) {
822
903
  const bundledAgentKeys = new Set(Object.keys(bundledAgents));
823
904
  config.agent = mergeSystematicEntries(existingAgents, bundledAgents, (key, agent) => bundledAgentKeys.has(key) && isSystematicAgentConfig(agent));
824
905
  config.command = mergeSystematicEntries(existingCommands, plan.commands, (_key, command) => isSystematicCommandConfig(command));
906
+ applyDiscoveredRouting(config, plan, reportedRouting);
825
907
  registerSkillsPaths(config, plan.skillsDir);
826
908
  denyDisabledSkills(config, systematicConfig.disabled_skills);
827
909
  };
@@ -896,6 +978,104 @@ function normalizePath(path) {
896
978
  return path.replaceAll("\\", "/").replace(/\/+$/u, "");
897
979
  }
898
980
 
981
+ // src/lib/search-tool.ts
982
+ function isSearchEnabled(settings) {
983
+ return settings?.enabled !== false;
984
+ }
985
+ async function executeSearch(args, startDir, settings, unreadable) {
986
+ try {
987
+ if (startDir === undefined)
988
+ return SEARCH_NOTICES.noProject;
989
+ const record = isRecord(args) ? args : {};
990
+ const response = await runSearch({
991
+ query: record[SEARCH_ARGS.query],
992
+ kind: record[SEARCH_ARGS.kind],
993
+ limit: record[SEARCH_ARGS.limit]
994
+ }, {
995
+ startDir,
996
+ settings,
997
+ ...unreadable === true && { notes: [SEARCH_CONFIG_UNREADABLE_NOTE] }
998
+ });
999
+ return response.text;
1000
+ } catch {
1001
+ return SEARCH_NOTICES.failed;
1002
+ }
1003
+ }
1004
+ function usableDirectory(value) {
1005
+ return typeof value === "string" && value.length > 0 ? value : undefined;
1006
+ }
1007
+ function createSearchTool(options) {
1008
+ const { settings, unreadable } = options;
1009
+ return {
1010
+ description: SEARCH_TOOL_DESCRIPTION,
1011
+ args: {
1012
+ [SEARCH_ARGS.query]: string().describe(SEARCH_ARG_DESCRIPTIONS.query),
1013
+ [SEARCH_ARGS.kind]: string().optional().describe(SEARCH_ARG_DESCRIPTIONS.kind),
1014
+ [SEARCH_ARGS.limit]: number().int().optional().describe(SEARCH_ARG_DESCRIPTIONS.limit)
1015
+ },
1016
+ async execute(args, context) {
1017
+ return executeSearch(args, usableDirectory(context.directory), settings, unreadable);
1018
+ }
1019
+ };
1020
+ }
1021
+ var V2_INPUT_SCHEMA = {
1022
+ type: "object",
1023
+ properties: {
1024
+ [SEARCH_ARGS.query]: {
1025
+ type: "string",
1026
+ description: SEARCH_ARG_DESCRIPTIONS.query
1027
+ },
1028
+ [SEARCH_ARGS.kind]: {
1029
+ type: "string",
1030
+ description: SEARCH_ARG_DESCRIPTIONS.kind
1031
+ },
1032
+ [SEARCH_ARGS.limit]: {
1033
+ type: "integer",
1034
+ description: SEARCH_ARG_DESCRIPTIONS.limit
1035
+ }
1036
+ },
1037
+ required: [SEARCH_ARGS.query],
1038
+ additionalProperties: false
1039
+ };
1040
+ function createV2SearchTool(ctx, settings, unreadable) {
1041
+ return {
1042
+ name: SEARCH_TOOL_NAME,
1043
+ description: SEARCH_TOOL_DESCRIPTION,
1044
+ input: V2_INPUT_SCHEMA,
1045
+ options: { codemode: false },
1046
+ async execute(input) {
1047
+ const startDir = usableDirectory(ctx.location?.directory);
1048
+ return {
1049
+ content: await executeSearch(input, startDir, settings, unreadable),
1050
+ metadata: {}
1051
+ };
1052
+ }
1053
+ };
1054
+ }
1055
+ var installSearch = async ({
1056
+ ctx,
1057
+ snapshot,
1058
+ guard,
1059
+ report
1060
+ }) => {
1061
+ const settings = snapshot.config.search;
1062
+ const unreadable = snapshot.config.searchUnreadable;
1063
+ if (!isSearchEnabled(settings))
1064
+ return;
1065
+ const reported = new Set;
1066
+ const toolTransform = guard.sync("search tool transform", (editor) => {
1067
+ if (editor.get(SEARCH_TOOL_NAME) !== undefined) {
1068
+ if (!reported.has(SEARCH_TOOL_NAME)) {
1069
+ reported.add(SEARCH_TOOL_NAME);
1070
+ report(`tool "${SEARCH_TOOL_NAME}" is already registered by another plugin; not registering the bundled one`);
1071
+ }
1072
+ return;
1073
+ }
1074
+ editor.add(createV2SearchTool(ctx, settings, unreadable));
1075
+ });
1076
+ await guard.async("search tool registration", () => ctx.tool.transform(toolTransform))();
1077
+ };
1078
+
899
1079
  // src/lib/skill-resolver.ts
900
1080
  import fs5 from "fs";
901
1081
  import path5 from "path";
@@ -1274,7 +1454,13 @@ var createOpenCodeV1Hooks = async ({ client, directory }, { packageRoot }) => {
1274
1454
  bundledSkillsDir,
1275
1455
  disabledSkills: config.disabled_skills,
1276
1456
  outputStore: skillOutputStore
1277
- })
1457
+ }),
1458
+ ...isSearchEnabled(config.search) && {
1459
+ systematic_search: createSearchTool({
1460
+ settings: config.search,
1461
+ unreadable: config.searchUnreadable
1462
+ })
1463
+ }
1278
1464
  },
1279
1465
  "tool.execute.after": async (input, output) => {
1280
1466
  try {
@@ -1427,6 +1613,10 @@ function declaredRouting(planned) {
1427
1613
  function refusalMessage(name, field) {
1428
1614
  return `Systematic command "${name}" declares ${field}, which OpenCode v2 plugin commands cannot route. Define it as an OpenCode command in Markdown or JSON to choose its agent or model.`;
1429
1615
  }
1616
+ function ignoredRoutingMessage(name, declared) {
1617
+ const fields = ["agent", "model", "subtask"].filter((field) => declared[field] !== undefined);
1618
+ return `skill "${name}" declares ${fields.join(", ")}, which OpenCode v2 plugin commands cannot route; it is ignored and the skill runs as it is. Write an OpenCode command in Markdown or JSON to route it.`;
1619
+ }
1430
1620
  async function submit(runtime, planned, invocation) {
1431
1621
  const text = substituteSkillArguments(planned.template, invocation.prompt.text);
1432
1622
  const { files, agents, skills } = invocation.prompt;
@@ -1476,6 +1666,10 @@ var installCommands = async ({
1476
1666
  guard.sync(`command "${name}"`, () => {
1477
1667
  editor.add(buildCommand(runtime, name, planned));
1478
1668
  })();
1669
+ const declared = snapshot.plan.discoveredRouting[name];
1670
+ if (declared !== undefined) {
1671
+ reportOnce(runtime, `ignored-routing:${name}`, ignoredRoutingMessage(name, declared));
1672
+ }
1479
1673
  }
1480
1674
  });
1481
1675
  await guard.async("command registration", () => ctx.command.transform(transform))();
@@ -1774,12 +1968,14 @@ var installAgents = async ({ ctx, snapshot, guard }) => {
1774
1968
  var DEFAULT_INSTALLERS = {
1775
1969
  agents: installAgents,
1776
1970
  skills: installSkills,
1971
+ search: installSearch,
1777
1972
  commands: installCommands,
1778
1973
  bootstrap: installBootstrap
1779
1974
  };
1780
1975
  var INSTALLER_ORDER = [
1781
1976
  "agents",
1782
1977
  "skills",
1978
+ "search",
1783
1979
  "commands",
1784
1980
  "bootstrap"
1785
1981
  ];
@@ -25,8 +25,14 @@ export declare function resolveAgent(catalog: AgentCatalogEntry[], name: string)
25
25
  * tool's description/parameter hint text. Stable ordering (catalog is pre-sorted).
26
26
  */
27
27
  export declare function renderAgentCatalogCompact(catalog: AgentCatalogEntry[]): string;
28
- /** Pi built-in read-only tool names used as the default allowlist. */
29
- export declare const DEFAULT_READONLY_TOOLS: readonly ['read', 'grep', 'find', 'ls'];
28
+ /**
29
+ * The default delegate allowlist: Pi's built-in read-only tool names plus
30
+ * `systematic_search`, the one read-only parent tool a delegate may call.
31
+ * `systematic_search` is not a Pi built-in. It is active in a delegate only
32
+ * when `src/pi.ts` also passes its definition as a custom tool, and a name
33
+ * with no definition is inert.
34
+ */
35
+ export declare const DEFAULT_READONLY_TOOLS: readonly ['read', 'grep', 'find', 'ls', "systematic_search"];
30
36
  export interface ResolvedToolAllowlist {
31
37
  tools: string[];
32
38
  }
@@ -60,6 +60,17 @@ export interface PlannedCommand {
60
60
  model?: string;
61
61
  subtask?: boolean;
62
62
  }
63
+ /**
64
+ * Routing fields a discovered skill declared in its frontmatter, as written.
65
+ * Discovered skills are the user's own and are often written for other agent
66
+ * harnesses, so the values are not trusted: each host decides what to do with
67
+ * them.
68
+ */
69
+ export interface DeclaredRouting {
70
+ agent?: string;
71
+ model?: string;
72
+ subtask?: boolean;
73
+ }
63
74
  export interface AssetPlan {
64
75
  /** Bundled skills directory, for hosts that register it for native discovery. */
65
76
  skillsDir: string;
@@ -67,8 +78,19 @@ export interface AssetPlan {
67
78
  enabledSkills: readonly string[];
68
79
  /** Agents keyed by emitted agent name, in discovery order. */
69
80
  agents: Record<string, PlannedAgent>;
70
- /** Commands keyed by emitted command name: bundled commands, then skills, then discovered skills. */
81
+ /**
82
+ * Commands keyed by emitted command name: bundled commands, then skills,
83
+ * then discovered skills. A discovered command never carries `agent`,
84
+ * `model` or `subtask`; see `discoveredRouting`.
85
+ */
71
86
  commands: Record<string, PlannedCommand>;
87
+ /**
88
+ * What each discovered skill declared, keyed by its command name. Only
89
+ * skills that declare at least one routing field, and whose command is in
90
+ * `commands`, are listed. A host that can route validates these and applies
91
+ * what is valid; a host that cannot reports them.
92
+ */
93
+ discoveredRouting: Record<string, DeclaredRouting>;
72
94
  }
73
95
  export interface AssetPlanInput {
74
96
  /** Loaded Systematic config. The builder reads only the disabled lists and `skills_as_commands`. */
@@ -18,5 +18,5 @@
18
18
  * reason it exists as a separate file rather than living directly in
19
19
  * `config.ts`.
20
20
  */
21
- export declare const CONFIG_PROTECTED_FIELD_PATHS: readonly ['profiles', 'allow_project_profiles', 'agents.*.model', 'agents.*.permission', 'agents.*.skills', 'agents.*.variant', 'agents.*.opencode', 'agents.*.pi', 'categories.*.model', 'categories.*.permission', 'categories.*.skills', 'categories.*.variant', 'categories.*.opencode', 'categories.*.pi'];
21
+ export declare const CONFIG_PROTECTED_FIELD_PATHS: readonly ['profiles', 'allow_project_profiles', 'search', 'agents.*.model', 'agents.*.permission', 'agents.*.skills', 'agents.*.variant', 'agents.*.opencode', 'agents.*.pi', 'categories.*.model', 'categories.*.permission', 'categories.*.skills', 'categories.*.variant', 'categories.*.opencode', 'categories.*.pi'];
22
22
  export type ConfigProtectedFieldPath = (typeof CONFIG_PROTECTED_FIELD_PATHS)[number];
@@ -385,6 +385,9 @@ export declare function createSystematicConfigSchema(opts: SystematicConfigSchem
385
385
  }, z.core.$strict>>>;
386
386
  profile: z.ZodOptional<z.ZodNullable<z.ZodString>>;
387
387
  allow_project_profiles: z.ZodDefault<z.ZodBoolean>;
388
+ search: z.ZodOptional<z.ZodObject<{
389
+ enabled: z.ZodOptional<z.ZodBoolean>;
390
+ }, z.core.$strict>>;
388
391
  disabled_skills: z.ZodDefault<z.ZodArray<z.ZodEnum<{
389
392
  [x: string]: string;
390
393
  }>>>;
@@ -580,6 +583,9 @@ export declare const SystematicConfigSchema: z.ZodObject<{
580
583
  }, z.core.$strict>>>;
581
584
  profile: z.ZodOptional<z.ZodNullable<z.ZodString>>;
582
585
  allow_project_profiles: z.ZodDefault<z.ZodBoolean>;
586
+ search: z.ZodOptional<z.ZodObject<{
587
+ enabled: z.ZodOptional<z.ZodBoolean>;
588
+ }, z.core.$strict>>;
583
589
  disabled_skills: z.ZodDefault<z.ZodArray<z.ZodEnum<{
584
590
  [x: string]: string;
585
591
  }>>>;
@@ -1,5 +1,6 @@
1
1
  import { CONFIG_PROTECTED_FIELD_PATHS, type ConfigProtectedFieldPath } from './config-protected-fields.js';
2
2
  import { type RoutingTarget } from './routing-resolver.js';
3
+ import type { SearchSettings } from './search-core.js';
3
4
  export interface BootstrapConfig {
4
5
  enabled: boolean;
5
6
  file?: string;
@@ -172,6 +173,18 @@ export interface SystematicConfig {
172
173
  pi_subagents?: PiSubagentsOverlayMap;
173
174
  skills_as_commands: boolean;
174
175
  allow_project_profiles: boolean;
176
+ /**
177
+ * Merged `search` settings from user and custom config only. Absent when
178
+ * neither defines one: there is no default, and the core applies its own at
179
+ * use time.
180
+ */
181
+ search?: SearchSettings;
182
+ /**
183
+ * Set (to `true`) when a user or custom `search` block, or its file, could
184
+ * not be read. That block is ignored and search results carry a
185
+ * `config unreadable` note. Absent otherwise.
186
+ */
187
+ searchUnreadable?: boolean;
175
188
  }
176
189
  export declare const DEFAULT_CONFIG: SystematicConfig;
177
190
  /**
@@ -0,0 +1,30 @@
1
+ /**
2
+ * The direct-execution guard shared by `src/cli.ts`, `src/claude-code-validator-bin.ts`
3
+ * and the `systematic-search` bin.
4
+ *
5
+ * It replaces `import.meta.main`, which Node only gained in 24.2. A module that
6
+ * runs under Node 20 or 22 would see `undefined` and never self-execute. The
7
+ * guard compares the realpath of `argv[1]` with the realpath of the module, so
8
+ * it holds when the file is reached through a symlink (the npm `.bin` link, a
9
+ * macOS `/var` to `/private/var` temp path) or a relative path.
10
+ *
11
+ * Fail-closed: when either side is missing or cannot be resolved the answer is
12
+ * `false`, so importing the module for tests or tooling runs nothing.
13
+ *
14
+ * The caller passes its own `import.meta.url`. This module cannot read it: in a
15
+ * bundle with code splitting this file may live in a shared chunk, and its URL
16
+ * would then name the chunk and never the entry.
17
+ *
18
+ * `src/ce-review-validator.ts` keeps its own copy on purpose. It feeds a
19
+ * committed bundle, and keeping it self-contained keeps that bundle's digest
20
+ * independent of this file.
21
+ */
22
+ /**
23
+ * Whether the module at `moduleUrl` is the process entry point.
24
+ *
25
+ * @param moduleUrl The caller's `import.meta.url`.
26
+ * @param argv The process argument vector. Defaults to `process.argv`; the
27
+ * entry script is `argv[1]`. A vector with no `argv[1]` (a REPL, `node -e`)
28
+ * is never a main module.
29
+ */
30
+ export declare function isMainModule(moduleUrl: string, argv?: readonly string[]): boolean;
@@ -13,9 +13,10 @@ import type { V2Installer } from './opencode-v2.js';
13
13
  *
14
14
  * It does not route. A v2 plugin command cannot choose an agent or a model for
15
15
  * its prompt, and switching the session around the turn leaves the user's
16
- * session changed. A command that declares `agent`, `model` or `subtask` is
17
- * refused with a message instead; OpenCode commands written in Markdown or JSON
18
- * can do that routing.
16
+ * session changed. A bundled command that declares `agent`, `model` or
17
+ * `subtask` is refused with a message instead; OpenCode commands written in
18
+ * Markdown or JSON can do that routing. A discovered skill is never refused: its
19
+ * routing fields are dropped with a note and it runs on the invoking session.
19
20
  */
20
21
  type CommandEditor = Parameters<Parameters<Plugin.Context['command']['transform']>[0]>[0];
21
22
  export type V2CommandDefinition = Parameters<CommandEditor['add']>[0];
@@ -1,5 +1,5 @@
1
1
  import type { V2Installer } from './opencode-v2.js';
2
- import { type SkillOutputStore, type SkillToolDescriptor } from './skill-tool.js';
2
+ import { type SkillOutputStore } from './skill-tool.js';
3
3
  /**
4
4
  * Skills on OpenCode v2: the enabled bundled skills are registered with the
5
5
  * host so its native `skill` tool and `<available_skills>` list see them, and
@@ -31,10 +31,20 @@ export interface V2ToolContext {
31
31
  id: string;
32
32
  progress(update: Record<string, unknown>): Promise<void>;
33
33
  }
34
+ /** The JSON Schema shape of a tool's input: an object of described properties. */
35
+ export type V2ToolInputSchema = {
36
+ type: 'object';
37
+ properties: Record<string, {
38
+ type: string;
39
+ description: string;
40
+ }>;
41
+ required: readonly string[];
42
+ additionalProperties: false;
43
+ };
34
44
  export interface V2ToolDefinition {
35
45
  name: string;
36
46
  description: string;
37
- input: SkillToolDescriptor['input'];
47
+ input: V2ToolInputSchema;
38
48
  options: {
39
49
  codemode: false;
40
50
  };
@@ -32,6 +32,7 @@ export type V2Installer = (input: V2InstallInput) => Promise<void> | void;
32
32
  export interface V2Installers {
33
33
  agents: V2Installer;
34
34
  skills: V2Installer;
35
+ search: V2Installer;
35
36
  commands: V2Installer;
36
37
  bootstrap: V2Installer;
37
38
  }
@@ -1,5 +1,5 @@
1
1
  /** Real Pi session-construction for `systematic_delegate`. `noExtensions: true` is the structural depth-1 boundary preventing the child from re-registering `systematic_delegate` or any project/user extension. */
2
- import type { CreateAgentSessionOptions, CreateAgentSessionResult, ResourceLoader } from '@earendil-works/pi-coding-agent';
2
+ import type { CreateAgentSessionOptions, CreateAgentSessionResult, ResourceLoader, ToolDefinition } from '@earendil-works/pi-coding-agent';
3
3
  import { DefaultResourceLoader, SessionManager } from '@earendil-works/pi-coding-agent';
4
4
  /** `DefaultResourceLoaderOptions` is not exported by the package, so it's derived from the constructor's parameter type. */
5
5
  type DefaultResourceLoaderOptions = ConstructorParameters<typeof DefaultResourceLoader>[0];
@@ -25,6 +25,8 @@ export declare function buildDelegateAgentSessionOptions(options: {
25
25
  /** Omitted (not `undefined`-valued) when unset, so the child inherits Pi's default thinking level instead of an explicit `undefined` overriding it. */
26
26
  thinkingLevel?: CreateAgentSessionOptions['thinkingLevel'];
27
27
  allowedToolNames: string[];
28
+ /** Definitions the child may call. A definition is active only when its name is also in `allowedToolNames`. */
29
+ customTools: ToolDefinition[];
28
30
  resourceLoader: ResourceLoader;
29
31
  sessionManager: ReturnType<typeof SessionManager.inMemory>;
30
32
  }): CreateAgentSessionOptions;
@@ -13,7 +13,7 @@ export type DelegateParentModel = NonNullable<ExtensionContext['model']>;
13
13
  /**
14
14
  * Derived from the pinned Pi SDK's own `CreateAgentSessionOptions` type
15
15
  * (`'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'` as of
16
- * @earendil-works/pi-coding-agent@0.83.0) rather than hand-declared, so a
16
+ * @earendil-works/pi-coding-agent@1.4.0) rather than hand-declared, so a
17
17
  * future SDK bump that changes the union surfaces as a type error here
18
18
  * instead of silently drifting. Value-for-value identical to Systematic's
19
19
  * own `piSubagentsThinkingSchema` enum in config-schema.ts today — see
@@ -42,10 +42,21 @@ export type CreateDelegateSession = (options: {
42
42
  cwd: string;
43
43
  systemPromptOverride: string;
44
44
  allowedToolNames: string[];
45
+ /**
46
+ * Parent-supplied tool definitions the child may call. A definition is active
47
+ * only when its name is also in `allowedToolNames`. Omitted means none.
48
+ */
49
+ customTools?: ToolDefinition[];
45
50
  }) => Promise<DelegateSessionLike>;
46
51
  export interface PiDelegateToolDeps {
47
52
  catalog: AgentCatalogEntry[];
48
53
  createDelegateSession: CreateDelegateSession;
54
+ /**
55
+ * Tool definitions delegates may call, in addition to Pi's built-ins. Today
56
+ * `src/pi.ts` supplies the one shared `systematic_search` definition, or
57
+ * nothing when search is disabled. Nothing else from the parent passes.
58
+ */
59
+ customTools?: ToolDefinition[];
49
60
  /**
50
61
  * Merged agent/category routing overlays from `loadConfigWithSources`'s
51
62
  * `overlays` field. Omit for a config-neutral tool — routing then always
@@ -0,0 +1,52 @@
1
+ /**
2
+ * The command-line adapter for durable-output search, shared by
3
+ * `systematic search` (`src/cli.ts`) and the `systematic-search` plugin
4
+ * bin. Like the tool adapters it does host I/O only: parse flags, pick the
5
+ * start directory, hand the settings to `runSearch`, and map the response to
6
+ * an exit code. Every byte of a search result is the core's text.
7
+ *
8
+ * It never loads config itself. The caller injects a settings loader, so
9
+ * `cli.ts` can use the full loader (project config included, with its strip
10
+ * warnings) and the bin can use the user-level reader alone.
11
+ *
12
+ * Exit codes: 0 for results, no hits and disabled; 1 for an unexpected
13
+ * failure; 2 for usage errors. There is no `--json`.
14
+ *
15
+ * Import rule: this module is bundled into the `systematic-search` bin, so it
16
+ * may import only `search-core.ts` and node builtins.
17
+ */
18
+ import { type SearchSettings } from './search-core.js';
19
+ /**
20
+ * The usage text for one surface. `commandName` is what that surface's users
21
+ * type (`systematic search` or `systematic-search`), so the text never tells a
22
+ * bin user to run a command they may not have.
23
+ */
24
+ export declare function searchCliUsage(commandName: string): string;
25
+ /** What `search.enabled: false` prints. The researcher falls back to grep on it. */
26
+ export declare const SEARCH_CLI_DISABLED_NOTICE = "Search is disabled (search.enabled is false in your Systematic config), so there is nothing to search.";
27
+ /** What a settings loader returns. The bin's user-level reader returns the same shape. */
28
+ export interface SearchCliSettingsLoad {
29
+ readonly settings?: SearchSettings | undefined;
30
+ /** Printed to stderr, one per line, before the search runs. */
31
+ readonly warnings: readonly string[];
32
+ /** A source could not be read: its settings were ignored and results carry a `config unreadable` note. */
33
+ readonly unreadable: boolean;
34
+ }
35
+ /** Receives the absolute start directory. A loader that does not need it ignores it. */
36
+ export type SearchCliSettingsLoader = (startDir: string) => SearchCliSettingsLoad;
37
+ export interface SearchCliOptions {
38
+ /** The arguments after the `search` command: query words and flags. */
39
+ readonly argv: readonly string[];
40
+ readonly cwd?: string;
41
+ /** The command the usage text names: `systematic search` or `systematic-search`. */
42
+ readonly usageName: string;
43
+ readonly loadSettings: SearchCliSettingsLoader;
44
+ readonly outputSink?: (message: string) => void;
45
+ readonly errorSink?: (message: string) => void;
46
+ }
47
+ /**
48
+ * Run `systematic search`. Flag parse errors are decided first, before any
49
+ * settings are loaded; a request the core rejects (an empty query, a bad
50
+ * `--limit`) is decided after, so a disabled search says so first. Returns the process exit code and never throws.
51
+ */
52
+ export declare function runSearchCli(options: SearchCliOptions): Promise<number>;