@aliou/pi-linkup 0.3.1 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @aliou/pi-linkup
 
+## 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
+
+- 052fc2b: Add fast mode support to linkup_web_search tool. The depth parameter now accepts "fast", "standard", or "deep" modes:
+  - fast: Sub-second latency using pre-indexed atoms of information
+  - standard: Single iteration retrieval, balanced speed/depth (default)
+  - deep: Up to 10 iterations with chain-of-thought reasoning
+
+### Patch Changes
+
+- a238ba7: Add User-Agent header to all Linkup API requests for attribution.
+
 ## 0.3.1
 
 ### Patch Changes

package/README.md

@@ -2,6 +2,8 @@
 
 Web search and content fetching extension for [Pi](https://buildwithpi.ai/) using the [Linkup API](https://linkup.so).
 
+
+
 ## Features
 
 - `linkup_web_search` - Search the web, get relevant sources with content
@@ -9,6 +11,10 @@ Web search and content fetching extension for [Pi](https://buildwithpi.ai/) usin
 - `linkup_web_fetch` - Extract clean markdown from URLs
 - `/linkup:balance` - Check API credit balance
 
+
+https://github.com/user-attachments/assets/a0f131a4-d57c-4162-aeb5-ffc1a0a8d7ff
+
+
 ## Installation
 
 ### Get API Key

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliou/pi-linkup",
-  "version": "0.3.1",
+  "version": "0.6.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/aliou/pi-linkup"
@@ -17,11 +17,16 @@
     ],
     "video": "https://assets.aliou.me/pi-extensions/demos/pi-linkup.mp4"
   },
+  "peerDependencies": {
+    "@mariozechner/pi-ai": ">=0.52.7",
+    "@mariozechner/pi-coding-agent": ">=0.52.7"
+  },
   "devDependencies": {
+    "@aliou/pi-utils-settings": "^0.2.1",
     "@biomejs/biome": "^2.3.13",
     "@changesets/cli": "^2.27.11",
-    "@mariozechner/pi-coding-agent": "0.51.0",
-    "@mariozechner/pi-tui": "0.51.0",
+    "@mariozechner/pi-coding-agent": "0.52.7",
+    "@mariozechner/pi-tui": "0.52.7",
     "@sinclair/typebox": "^0.34.48",
     "@types/node": "^25.0.10",
     "husky": "^9.1.7",

package/skills/linkup/SKILL.md

@@ -14,11 +14,14 @@ Web search and content fetching tools powered by Linkup API.
 Search the web and get sources with content snippets.
 
 ```
-linkup_web_search(query: string, deep?: boolean)
+linkup_web_search(query: string, depth?: "fast" | "standard" | "deep")
 ```
 
 - `query`: Be specific and detailed. Include context like dates, locations, company names.
-- `deep`: Use for complex research requiring multiple searches. Default: false (faster).
+- `depth`: Search depth mode. Default: "standard".
+  - `fast`: Sub-second latency, uses pre-indexed "atoms of information". Best for quick facts and simple lookups.
+  - `standard`: Single iteration retrieval. Balanced speed and depth for most queries.
+  - `deep`: Up to 10 iterations with chain-of-thought reasoning. Best for complex multi-step research (slower).
 
 **Use when:** Discovering information across multiple sources, researching topics, comparing perspectives.
 
@@ -27,9 +30,12 @@ linkup_web_search(query: string, deep?: boolean)
 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
@@ -68,18 +74,23 @@ linkup_web_fetch(url: string, renderJs?: boolean)
 - Location: "French company Total", "US market"
 - Specifics: company names, version numbers, exact terms
 
-## When to Use Deep Mode
+## Depth Mode Selection
+
+**Fast:** Sub-second responses for quick facts, simple lookups, known facts.
 
-**Standard (default):** Simple questions, quick lookups, known topics.
+**Standard (default):** Single iteration, balanced speed/depth for most queries.
 
 **Deep:** Complex research, multi-step queries, comprehensive coverage needed.
 
 ```
-// Standard - one search is enough
-linkup_web_search("Node.js 22 release date")
+// Fast - instant facts, sub-second
+linkup_web_search("Node.js 22 release date", depth: "fast")
+
+// Standard - balanced, one search iteration
+linkup_web_search("React useEffect cleanup best practices")
 
-// Deep - needs multiple searches
-linkup_web_search("comparison of Rust web frameworks performance benchmarks 2025", deep: true)
+// Deep - complex research, multiple iterations
+linkup_web_search("comparison of Rust web frameworks performance benchmarks 2025", depth: "deep")
 ```
 
 ## Common Patterns

package/src/client.ts

@@ -1,3 +1,6 @@
+import { StringEnum } from "@mariozechner/pi-ai";
+import packageJson from "../package.json" with { type: "json" };
+
 import type {
   LinkupBalanceResponse,
   LinkupErrorResponse,
@@ -8,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;
 
@@ -24,6 +34,7 @@ export class LinkupClient {
       headers: {
         Authorization: `Bearer ${this.apiKey}`,
         "Content-Type": "application/json",
+        "User-Agent": `pi-linkup/${packageJson.version} (+https://github.com/aliou/pi-linkup)`,
         ...options.headers,
       },
     });
@@ -41,7 +52,7 @@ export class LinkupClient {
 
   async search(params: {
     query: string;
-    depth: "standard" | "deep";
+    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,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 { LinkupSearchResponse, LinkupSearchResult } from "../types";
 
 interface WebSearchDetails {
@@ -22,12 +22,7 @@ export function registerWebSearchTool(pi: ExtensionAPI) {
         description:
           "The search query. Be specific and detailed for best results.",
       }),
-      deep: Type.Optional(
-        Type.Boolean({
-          description:
-            "Use deep search for comprehensive results (slower). Default: false (standard search).",
-        }),
-      ),
+      depth: Type.Optional(SearchDepth),
     }),
 
     async execute(_toolCallId, params, _signal, onUpdate, _ctx) {
@@ -38,7 +33,7 @@ export function registerWebSearchTool(pi: ExtensionAPI) {
           content: [
             {
               type: "text",
-              text: `Searching${params.deep ? " (deep mode)" : ""}...`,
+              text: `Searching${params.depth && params.depth !== "standard" ? ` (${params.depth} mode)` : ""}...`,
             },
           ],
           details: {},
@@ -46,7 +41,7 @@ export function registerWebSearchTool(pi: ExtensionAPI) {
 
         const response = (await client.search({
           query: params.query,
-          depth: params.deep ? "deep" : "standard",
+          depth: (params.depth ?? "standard") as SearchDepthType,
           outputType: "searchResults",
         })) as LinkupSearchResponse;
 
@@ -77,8 +72,8 @@ export function registerWebSearchTool(pi: ExtensionAPI) {
     renderCall(args, theme) {
       let text = theme.fg("toolTitle", theme.bold("Linkup: WebSearch "));
       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);
     },