@theokit/sdk-tools 0.7.0 → 0.8.0

package/dist/index.d.cts

@@ -272,8 +272,14 @@ interface RepoMapOptions {
     /** Max directory depth to descend. Default 4. */
     maxDepth?: number;
 }
+interface EnvContextOptions {
+    /** Injectable clock for the date line (deterministic tests). Default `new Date()`. */
+    now?: Date;
+    /** Path to the git `HEAD` file. Default `<cwd>/.git/HEAD`. */
+    gitHeadPath?: string;
+}
 /** Render a portable `<env>` orientation block. Never throws. */
-declare function buildEnvContext(cwd: string): string;
+declare function buildEnvContext(cwd: string, opts?: EnvContextOptions): string;
 /** Render a char-bounded, depth-limited directory tree. Never throws. */
 declare function buildRepoMap(cwd: string, opts?: RepoMapOptions): string;
 
@@ -792,12 +798,12 @@ declare function createWebSearchTool(opts: CreateWebSearchToolOptions): CustomTo
  * the required auth header. Zero new dependencies. Design: blueprint m3-websearch-adapter.
  */
 
-type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+type FetchLike$1 = (url: string, init?: RequestInit) => Promise<Response>;
 interface CreateBraveWebSearchAdapterOptions {
     /** Brave API key. Defaults to `process.env.BRAVE_API_KEY`. */
     apiKey?: string;
     /** Injectable fetch (default `globalThis.fetch`) — set in tests for offline runs. */
-    fetchImpl?: FetchLike;
+    fetchImpl?: FetchLike$1;
     /** Override the Brave endpoint (self-host / test). */
     endpoint?: string;
 }
@@ -807,6 +813,42 @@ interface CreateBraveWebSearchAdapterOptions {
  */
 declare function createBraveWebSearchAdapter(opts?: CreateBraveWebSearchAdapterOptions): WebSearchCallback;
 
+/**
+ * Generic HTTP web-search adapter for `createWebSearchTool` (RADAR #92.d).
+ *
+ * `createGenericHttpSearchAdapter()` returns a `WebSearchCallback` that queries
+ * an arbitrary HTTP search endpoint keyed by env vars:
+ *   - `THEOKIT_SEARCH_API_URL` — endpoint returning `{ results: [{title,url,snippet}] }`
+ *   - `THEOKIT_SEARCH_API_KEY` — bearer token
+ *
+ * Request shape: `GET {endpoint}?q={query}&n={maxResults}` with
+ * `Authorization: Bearer {apiKey}`. Both values may be passed explicitly (params
+ * win over env). Unlike the Brave adapter (which fails early — fixed host, fixed
+ * auth), this one is provider-agnostic and **degrades gracefully**: when
+ * unconfigured OR on any network/parse failure it returns `[]` and never throws
+ * into the agent turn. A recurring empty result is a provider-config issue, not
+ * an agent bug. `fetchImpl` is injectable (default `globalThis.fetch`) for
+ * offline tests. Zero new dependencies.
+ *
+ * Promoted from theocode's `server/lib/web-search.ts` (`createSearchProvider`),
+ * re-keyed to neutral `THEOKIT_*` env vars.
+ */
+
+type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+interface CreateGenericHttpSearchAdapterOptions {
+    /** Bearer token. Defaults to `process.env.THEOKIT_SEARCH_API_KEY`. */
+    apiKey?: string;
+    /** Search endpoint URL. Defaults to `process.env.THEOKIT_SEARCH_API_URL`. */
+    endpoint?: string;
+    /** Injectable fetch (default `globalThis.fetch`) — set in tests for offline runs. */
+    fetchImpl?: FetchLike;
+}
+/**
+ * Build a `WebSearchCallback` backed by a generic HTTP search endpoint. Returns
+ * `[]` (graceful no-op) when unconfigured or on any failure — never throws.
+ */
+declare function createGenericHttpSearchAdapter(opts?: CreateGenericHttpSearchAdapterOptions): WebSearchCallback;
+
 /**
  * `write_file` — built-in tool for coding agents.
  *
@@ -826,4 +868,4 @@ interface CreateWriteFileToolOptions {
 }
 declare function createWriteFileTool(opts: CreateWriteFileToolOptions): CustomTool;
 
-export { CatastrophicCommandError, type CommandPolicy, type CreateApplyPatchToolOptions, type CreateBraveWebSearchAdapterOptions, type CreateEditFileToolOptions, type CreateGitDiffToolOptions, type CreateGlobToolOptions, type CreateListDirToolOptions, type CreateReadFileToolOptions, type CreateRunVitestToolOptions, type CreateSearchTextToolOptions, type CreateShellToolOptions, type CreateWebFetchToolOptions, type CreateWebSearchToolOptions, type CreateWriteFileToolOptions, DEFAULT_TOOL_GUIDANCE, type PlanModeTool, type PlanModeToolOptions, type PlanModeToolWithStore, type PlanNode, type QuestionTool, type QuestionToolOptions, RedirectBlockedError, type RepoMapOptions, type ResolveAndScreenOptions, type ScreenedFetchOptions, type SessionArtifactStore, type SessionArtifactStoreOptions, SsrfBlockedError, type TodoItem, type TodolistTool, type ToolGuidanceMap, type TruncationOptions, type TruncationResult, type VitestSummary, type WebSearchCallback, type WebSearchResult, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createEditFileTool, createGitDiffTool, createGlobTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withShellExitGuidance, withToolResultGuidance };
+export { CatastrophicCommandError, type CommandPolicy, type CreateApplyPatchToolOptions, type CreateBraveWebSearchAdapterOptions, type CreateEditFileToolOptions, type CreateGenericHttpSearchAdapterOptions, type CreateGitDiffToolOptions, type CreateGlobToolOptions, type CreateListDirToolOptions, type CreateReadFileToolOptions, type CreateRunVitestToolOptions, type CreateSearchTextToolOptions, type CreateShellToolOptions, type CreateWebFetchToolOptions, type CreateWebSearchToolOptions, type CreateWriteFileToolOptions, DEFAULT_TOOL_GUIDANCE, type EnvContextOptions, type PlanModeTool, type PlanModeToolOptions, type PlanModeToolWithStore, type PlanNode, type QuestionTool, type QuestionToolOptions, RedirectBlockedError, type RepoMapOptions, type ResolveAndScreenOptions, type ScreenedFetchOptions, type SessionArtifactStore, type SessionArtifactStoreOptions, SsrfBlockedError, type TodoItem, type TodolistTool, type ToolGuidanceMap, type TruncationOptions, type TruncationResult, type VitestSummary, type WebSearchCallback, type WebSearchResult, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGlobTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withShellExitGuidance, withToolResultGuidance };

package/dist/index.d.ts

@@ -272,8 +272,14 @@ interface RepoMapOptions {
     /** Max directory depth to descend. Default 4. */
     maxDepth?: number;
 }
+interface EnvContextOptions {
+    /** Injectable clock for the date line (deterministic tests). Default `new Date()`. */
+    now?: Date;
+    /** Path to the git `HEAD` file. Default `<cwd>/.git/HEAD`. */
+    gitHeadPath?: string;
+}
 /** Render a portable `<env>` orientation block. Never throws. */
-declare function buildEnvContext(cwd: string): string;
+declare function buildEnvContext(cwd: string, opts?: EnvContextOptions): string;
 /** Render a char-bounded, depth-limited directory tree. Never throws. */
 declare function buildRepoMap(cwd: string, opts?: RepoMapOptions): string;
 
@@ -792,12 +798,12 @@ declare function createWebSearchTool(opts: CreateWebSearchToolOptions): CustomTo
  * the required auth header. Zero new dependencies. Design: blueprint m3-websearch-adapter.
  */
 
-type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+type FetchLike$1 = (url: string, init?: RequestInit) => Promise<Response>;
 interface CreateBraveWebSearchAdapterOptions {
     /** Brave API key. Defaults to `process.env.BRAVE_API_KEY`. */
     apiKey?: string;
     /** Injectable fetch (default `globalThis.fetch`) — set in tests for offline runs. */
-    fetchImpl?: FetchLike;
+    fetchImpl?: FetchLike$1;
     /** Override the Brave endpoint (self-host / test). */
     endpoint?: string;
 }
@@ -807,6 +813,42 @@ interface CreateBraveWebSearchAdapterOptions {
  */
 declare function createBraveWebSearchAdapter(opts?: CreateBraveWebSearchAdapterOptions): WebSearchCallback;
 
+/**
+ * Generic HTTP web-search adapter for `createWebSearchTool` (RADAR #92.d).
+ *
+ * `createGenericHttpSearchAdapter()` returns a `WebSearchCallback` that queries
+ * an arbitrary HTTP search endpoint keyed by env vars:
+ *   - `THEOKIT_SEARCH_API_URL` — endpoint returning `{ results: [{title,url,snippet}] }`
+ *   - `THEOKIT_SEARCH_API_KEY` — bearer token
+ *
+ * Request shape: `GET {endpoint}?q={query}&n={maxResults}` with
+ * `Authorization: Bearer {apiKey}`. Both values may be passed explicitly (params
+ * win over env). Unlike the Brave adapter (which fails early — fixed host, fixed
+ * auth), this one is provider-agnostic and **degrades gracefully**: when
+ * unconfigured OR on any network/parse failure it returns `[]` and never throws
+ * into the agent turn. A recurring empty result is a provider-config issue, not
+ * an agent bug. `fetchImpl` is injectable (default `globalThis.fetch`) for
+ * offline tests. Zero new dependencies.
+ *
+ * Promoted from theocode's `server/lib/web-search.ts` (`createSearchProvider`),
+ * re-keyed to neutral `THEOKIT_*` env vars.
+ */
+
+type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+interface CreateGenericHttpSearchAdapterOptions {
+    /** Bearer token. Defaults to `process.env.THEOKIT_SEARCH_API_KEY`. */
+    apiKey?: string;
+    /** Search endpoint URL. Defaults to `process.env.THEOKIT_SEARCH_API_URL`. */
+    endpoint?: string;
+    /** Injectable fetch (default `globalThis.fetch`) — set in tests for offline runs. */
+    fetchImpl?: FetchLike;
+}
+/**
+ * Build a `WebSearchCallback` backed by a generic HTTP search endpoint. Returns
+ * `[]` (graceful no-op) when unconfigured or on any failure — never throws.
+ */
+declare function createGenericHttpSearchAdapter(opts?: CreateGenericHttpSearchAdapterOptions): WebSearchCallback;
+
 /**
  * `write_file` — built-in tool for coding agents.
  *
@@ -826,4 +868,4 @@ interface CreateWriteFileToolOptions {
 }
 declare function createWriteFileTool(opts: CreateWriteFileToolOptions): CustomTool;
 
-export { CatastrophicCommandError, type CommandPolicy, type CreateApplyPatchToolOptions, type CreateBraveWebSearchAdapterOptions, type CreateEditFileToolOptions, type CreateGitDiffToolOptions, type CreateGlobToolOptions, type CreateListDirToolOptions, type CreateReadFileToolOptions, type CreateRunVitestToolOptions, type CreateSearchTextToolOptions, type CreateShellToolOptions, type CreateWebFetchToolOptions, type CreateWebSearchToolOptions, type CreateWriteFileToolOptions, DEFAULT_TOOL_GUIDANCE, type PlanModeTool, type PlanModeToolOptions, type PlanModeToolWithStore, type PlanNode, type QuestionTool, type QuestionToolOptions, RedirectBlockedError, type RepoMapOptions, type ResolveAndScreenOptions, type ScreenedFetchOptions, type SessionArtifactStore, type SessionArtifactStoreOptions, SsrfBlockedError, type TodoItem, type TodolistTool, type ToolGuidanceMap, type TruncationOptions, type TruncationResult, type VitestSummary, type WebSearchCallback, type WebSearchResult, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createEditFileTool, createGitDiffTool, createGlobTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withShellExitGuidance, withToolResultGuidance };
+export { CatastrophicCommandError, type CommandPolicy, type CreateApplyPatchToolOptions, type CreateBraveWebSearchAdapterOptions, type CreateEditFileToolOptions, type CreateGenericHttpSearchAdapterOptions, type CreateGitDiffToolOptions, type CreateGlobToolOptions, type CreateListDirToolOptions, type CreateReadFileToolOptions, type CreateRunVitestToolOptions, type CreateSearchTextToolOptions, type CreateShellToolOptions, type CreateWebFetchToolOptions, type CreateWebSearchToolOptions, type CreateWriteFileToolOptions, DEFAULT_TOOL_GUIDANCE, type EnvContextOptions, type PlanModeTool, type PlanModeToolOptions, type PlanModeToolWithStore, type PlanNode, type QuestionTool, type QuestionToolOptions, RedirectBlockedError, type RepoMapOptions, type ResolveAndScreenOptions, type ScreenedFetchOptions, type SessionArtifactStore, type SessionArtifactStoreOptions, SsrfBlockedError, type TodoItem, type TodolistTool, type ToolGuidanceMap, type TruncationOptions, type TruncationResult, type VitestSummary, type WebSearchCallback, type WebSearchResult, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGlobTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withShellExitGuidance, withToolResultGuidance };

package/dist/index.js

@@ -885,15 +885,26 @@ function safeReadHead(p, n) {
     return "";
   }
 }
-function buildEnvContext(cwd) {
+function gitBranch(headPath) {
+  try {
+    const head = readFileSync(headPath, "utf-8").trim();
+    const match = head.match(/^ref:\s*refs\/heads\/(.+)$/);
+    return match ? match[1] : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function buildEnvContext(cwd, opts = {}) {
   const lines = [
     "<env>",
     `  Working directory: ${cwd}`,
     `  Platform: ${process.platform} (${process.arch})`,
     `  Node: ${process.version}`,
-    `  Is git repo: ${safeExists(join(cwd, ".git")) ? "yes" : "no"}`,
-    `  Today's date: ${(/* @__PURE__ */ new Date()).toDateString()}`
+    `  Is git repo: ${safeExists(join(cwd, ".git")) ? "yes" : "no"}`
   ];
+  const branch = gitBranch(opts.gitHeadPath ?? join(cwd, ".git", "HEAD"));
+  if (branch) lines.push(`  Branch: ${branch}`);
+  lines.push(`  Today's date: ${(opts.now ?? /* @__PURE__ */ new Date()).toDateString()}`);
   const docs = PROJECT_DOCS.filter((d) => safeExists(join(cwd, d)));
   if (docs.length > 0) {
     lines.push(`  Project docs: ${docs.join(", ")}`);
@@ -1932,6 +1943,29 @@ function createBraveWebSearchAdapter(opts = {}) {
     }));
   };
 }
+
+// src/web-search-http.ts
+function createGenericHttpSearchAdapter(opts = {}) {
+  const apiKey = opts.apiKey ?? process.env.THEOKIT_SEARCH_API_KEY;
+  const endpoint = opts.endpoint ?? process.env.THEOKIT_SEARCH_API_URL;
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+  return async (query, maxResults) => {
+    if (!apiKey || !endpoint) return [];
+    try {
+      const url = `${endpoint}?q=${encodeURIComponent(query)}&n=${maxResults}`;
+      const res = await fetchImpl(url, { headers: { Authorization: `Bearer ${apiKey}` } });
+      if (!res.ok) return [];
+      const data = await res.json();
+      return (data?.results ?? []).slice(0, maxResults).map((r) => ({
+        title: String(r?.title ?? ""),
+        url: String(r?.url ?? ""),
+        snippet: String(r?.snippet ?? "")
+      }));
+    } catch {
+      return [];
+    }
+  };
+}
 var BINARY_PROBE_BYTES3 = 8 * 1024;
 function createWriteFileTool(opts) {
   const { projectRoot } = opts;
@@ -1988,6 +2022,6 @@ async function isBinaryFile(absolutePath) {
   }
 }
 
-export { CatastrophicCommandError, DEFAULT_TOOL_GUIDANCE, RedirectBlockedError, SsrfBlockedError, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createEditFileTool, createGitDiffTool, createGlobTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withShellExitGuidance, withToolResultGuidance };
+export { CatastrophicCommandError, DEFAULT_TOOL_GUIDANCE, RedirectBlockedError, SsrfBlockedError, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGlobTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withShellExitGuidance, withToolResultGuidance };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map