@aliou/pi-linkup 0.4.0 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @aliou/pi-linkup
 
+## 0.6.1
+
+### Patch Changes
+
+- d45c015: fix: move @aliou/pi-utils-settings from devDependencies to dependencies
+
+## 0.6.0
+
+### Minor Changes
+
+- e9fdef1: Replace `deep` boolean with `depth` enum on web-answer tool for consistency with web-search
+
+## 0.5.0
+
+### Minor Changes
+
+- 89a92f3: Add configurable system prompt guidance setting via /linkup:settings
+
 ## 0.4.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliou/pi-linkup",
-  "version": "0.4.0",
+  "version": "0.6.1",
   "repository": {
     "type": "git",
     "url": "https://github.com/aliou/pi-linkup"
@@ -17,9 +17,12 @@
     ],
     "video": "https://assets.aliou.me/pi-extensions/demos/pi-linkup.mp4"
   },
+  "dependencies": {
+    "@aliou/pi-utils-settings": "^0.2.1"
+  },
   "peerDependencies": {
-    "@mariozechner/pi-coding-agent": ">=0.52.7",
-    "@mariozechner/pi-ai": ">=0.52.7"
+    "@mariozechner/pi-ai": ">=0.52.7",
+    "@mariozechner/pi-coding-agent": ">=0.52.7"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.3.13",

package/skills/linkup/SKILL.md

@@ -30,9 +30,12 @@ linkup_web_search(query: string, depth?: "fast" | "standard" | "deep")
 Get a synthesized answer with source citations.
 
 ```
-linkup_web_answer(query: string, deep?: boolean)
+linkup_web_answer(query: string, depth?: "fast" | "standard" | "deep")
 ```
 
+- `query`: Be specific and detailed.
+- `depth`: Same depth modes as `linkup_web_search`. Default: "standard".
+
 **Use when:** Need a direct answer to a specific question, quick facts with citations.
 
 ### linkup_web_fetch

package/src/client.ts

@@ -1,3 +1,4 @@
+import { StringEnum } from "@mariozechner/pi-ai";
 import packageJson from "../package.json" with { type: "json" };
 
 import type {
@@ -10,6 +11,13 @@ import type {
 
 const BASE_URL = "https://api.linkup.so/v1";
 
+export const SearchDepth = StringEnum(["fast", "standard", "deep"], {
+  description:
+    "Search depth: 'fast' for sub-second quick facts, 'standard' (default) for balanced speed/depth, 'deep' for comprehensive multi-step research (slower).",
+});
+
+export type SearchDepthType = "fast" | "standard" | "deep";
+
 export class LinkupClient {
   private apiKey: string;
 
@@ -44,7 +52,7 @@ export class LinkupClient {
 
   async search(params: {
     query: string;
-    depth: "standard" | "deep" | "fast";
+    depth: SearchDepthType;
     outputType: "searchResults" | "sourcedAnswer";
   }): Promise<LinkupSearchResponse | LinkupSourcedAnswerResponse> {
     return this.request("/search", {

package/src/commands/settings.ts

@@ -0,0 +1,43 @@
+import {
+  registerSettingsCommand,
+  type SettingsSection,
+} from "@aliou/pi-utils-settings";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import {
+  configLoader,
+  type LinkupConfig,
+  type ResolvedLinkupConfig,
+} from "../config";
+
+export function registerLinkupSettings(pi: ExtensionAPI): void {
+  registerSettingsCommand<LinkupConfig, ResolvedLinkupConfig>(pi, {
+    commandName: "linkup:settings",
+    commandDescription: "Configure Linkup extension settings",
+    title: "Linkup Settings",
+    configStore: configLoader,
+    buildSections: (
+      tabConfig: LinkupConfig | null,
+      resolved: ResolvedLinkupConfig,
+    ): SettingsSection[] => {
+      return [
+        {
+          label: "System Prompt",
+          items: [
+            {
+              id: "systemPromptGuidance",
+              label: "Append search guidance",
+              description:
+                "Add Linkup usage guidance to the system prompt so the model knows when and how to use web search and fetch tools",
+              currentValue:
+                (tabConfig?.systemPromptGuidance ??
+                resolved.systemPromptGuidance)
+                  ? "enabled"
+                  : "disabled",
+              values: ["enabled", "disabled"],
+            },
+          ],
+        },
+      ];
+    },
+  });
+}

package/src/config.ts

@@ -0,0 +1,25 @@
+import { ConfigLoader } from "@aliou/pi-utils-settings";
+
+/**
+ * Raw config shape (what gets saved to disk).
+ * All fields optional -- only overrides are stored.
+ */
+export interface LinkupConfig {
+  systemPromptGuidance?: boolean;
+}
+
+/**
+ * Resolved config (defaults merged in).
+ */
+export interface ResolvedLinkupConfig {
+  systemPromptGuidance: boolean;
+}
+
+const DEFAULTS: ResolvedLinkupConfig = {
+  systemPromptGuidance: false,
+};
+
+export const configLoader = new ConfigLoader<
+  LinkupConfig,
+  ResolvedLinkupConfig
+>("pi-linkup", DEFAULTS);

package/src/guidance.ts

@@ -0,0 +1,28 @@
+/**
+ * System prompt guidance for Linkup tools.
+ * Appended to the system prompt when the setting is enabled.
+ */
+export const LINKUP_GUIDANCE = `
+## Linkup
+
+Use the Linkup tools for web search and content fetching. Three tools are available: linkup_web_search (discovery), linkup_web_answer (direct answers), linkup_web_fetch (URL content extraction).
+
+**Tool selection:**
+- Find information across sources: \`linkup_web_search\`
+- Get a direct answer with sources: \`linkup_web_answer\`
+- Read content from a known URL: \`linkup_web_fetch\`
+
+**Search depth modes (linkup_web_search, linkup_web_answer):**
+- \`fast\`: Sub-second, pre-indexed facts. Use for quick lookups.
+- \`standard\` (default): Single iteration, balanced speed/depth.
+- \`deep\`: Multi-iteration with chain-of-thought. Use for complex research.
+
+**Query tips:**
+- Be specific: "Microsoft fiscal year 2024 total revenue" not "Microsoft revenue"
+- Add context: dates, version numbers, company names, locations
+
+**Common patterns:**
+1. Research: \`linkup_web_search\` to discover, then \`linkup_web_fetch\` on promising URLs
+2. Quick facts: \`linkup_web_answer\` for direct answer with citations
+3. Documentation: \`linkup_web_fetch\` on known URL (set \`renderJs: false\` for static pages)
+`;

package/src/hooks/index.ts

@@ -0,0 +1 @@
+export { registerGuidance } from "./system-prompt";

package/src/hooks/system-prompt.ts

@@ -0,0 +1,17 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { configLoader } from "../config";
+import { LINKUP_GUIDANCE } from "../guidance";
+
+/**
+ * Register the system prompt hook to inject Linkup guidance when enabled.
+ */
+export function registerGuidance(pi: ExtensionAPI) {
+  pi.on("before_agent_start", async (event) => {
+    const config = configLoader.getConfig();
+    if (!config.systemPromptGuidance) return;
+
+    return {
+      systemPrompt: `${event.systemPrompt}\n${LINKUP_GUIDANCE}`,
+    };
+  });
+}

package/src/index.ts

@@ -1,11 +1,14 @@
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { registerBalanceCommand } from "./commands/balance";
+import { registerLinkupSettings } from "./commands/settings";
 import { registerRenderers } from "./components";
+import { configLoader } from "./config";
+import { registerGuidance } from "./hooks";
 import { registerWebAnswerTool } from "./tools/web-answer";
 import { registerWebFetchTool } from "./tools/web-fetch";
 import { registerWebSearchTool } from "./tools/web-search";
 
-export default function (pi: ExtensionAPI) {
+export default async function (pi: ExtensionAPI) {
   const hasApiKey = !!process.env.LINKUP_API_KEY;
 
   if (!hasApiKey) {
@@ -24,6 +27,9 @@ export default function (pi: ExtensionAPI) {
     return;
   }
 
+  // Load config
+  await configLoader.load();
+
   // Register tools
   registerWebSearchTool(pi);
   registerWebAnswerTool(pi);
@@ -31,7 +37,11 @@ export default function (pi: ExtensionAPI) {
 
   // Register commands
   registerBalanceCommand(pi);
+  registerLinkupSettings(pi);
 
   // Register renderers
   registerRenderers(pi);
+
+  // Register hooks
+  registerGuidance(pi);
 }

package/src/tools/web-answer.ts

@@ -1,7 +1,7 @@
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { Text } from "@mariozechner/pi-tui";
 import { Type } from "@sinclair/typebox";
-import { getClient } from "../client";
+import { getClient, SearchDepth, type SearchDepthType } from "../client";
 import type { LinkupSource, LinkupSourcedAnswerResponse } from "../types";
 
 interface WebAnswerDetails {
@@ -23,12 +23,7 @@ export function registerWebAnswerTool(pi: ExtensionAPI) {
         description:
           "The question to answer. Be specific and detailed for best results.",
       }),
-      deep: Type.Optional(
-        Type.Boolean({
-          description:
-            "Use deep search for more comprehensive answer (slower). Default: false (standard search).",
-        }),
-      ),
+      depth: Type.Optional(SearchDepth),
     }),
 
     async execute(_toolCallId, params, _signal, onUpdate, _ctx) {
@@ -39,7 +34,7 @@ export function registerWebAnswerTool(pi: ExtensionAPI) {
           content: [
             {
               type: "text",
-              text: `Searching for answer${params.deep ? " (deep mode)" : ""}...`,
+              text: `Searching for answer${params.depth && params.depth !== "standard" ? ` (${params.depth} mode)` : ""}...`,
             },
           ],
           details: {},
@@ -47,7 +42,7 @@ export function registerWebAnswerTool(pi: ExtensionAPI) {
 
         const response = (await client.search({
           query: params.query,
-          depth: params.deep ? "deep" : "standard",
+          depth: (params.depth ?? "standard") as SearchDepthType,
           outputType: "sourcedAnswer",
         })) as LinkupSourcedAnswerResponse;
 
@@ -81,8 +76,8 @@ export function registerWebAnswerTool(pi: ExtensionAPI) {
     renderCall(args, theme) {
       let text = theme.fg("toolTitle", theme.bold("Linkup: WebAnswer "));
       text += theme.fg("accent", `"${args.query}"`);
-      if (args.deep) {
-        text += theme.fg("dim", " (deep)");
+      if (args.depth && args.depth !== "standard") {
+        text += theme.fg("dim", ` (${args.depth})`);
       }
       return new Text(text, 0, 0);
     },

package/src/tools/web-search.ts

@@ -1,8 +1,7 @@
-import { StringEnum } from "@mariozechner/pi-ai";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { Text } from "@mariozechner/pi-tui";
 import { Type } from "@sinclair/typebox";
-import { getClient } from "../client";
+import { getClient, SearchDepth, type SearchDepthType } from "../client";
 import type { LinkupSearchResponse, LinkupSearchResult } from "../types";
 
 interface WebSearchDetails {
@@ -23,12 +22,7 @@ export function registerWebSearchTool(pi: ExtensionAPI) {
         description:
           "The search query. Be specific and detailed for best results.",
       }),
-      depth: Type.Optional(
-        StringEnum(["deep", "standard", "fast"], {
-          description:
-            "Search depth: 'fast' for sub-second quick facts, 'standard' (default) for balanced speed/depth, 'deep' for comprehensive multi-step research (slower).",
-        }),
-      ),
+      depth: Type.Optional(SearchDepth),
     }),
 
     async execute(_toolCallId, params, _signal, onUpdate, _ctx) {
@@ -47,7 +41,7 @@ export function registerWebSearchTool(pi: ExtensionAPI) {
 
         const response = (await client.search({
           query: params.query,
-          depth: (params.depth ?? "standard") as "standard" | "deep" | "fast",
+          depth: (params.depth ?? "standard") as SearchDepthType,
           outputType: "searchResults",
         })) as LinkupSearchResponse;