dsh-web-search-enhanced 0.0.1

package/lib/types/client/index.d.ts

@@ -0,0 +1,11 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { type LocaleKey } from './locales.ts';
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        'settings.webSearchEnhanced': LocaleKey;
+    }
+}
+/** Browser plugin dependencies. */
+export declare const inject: string[];
+/** Register the localized card under Settings -> Plugins -> Plugin configuration. */
+export declare function apply(ctx: Context): void;

package/lib/types/client/locales.d.ts

@@ -0,0 +1,61 @@
+export declare const en: {
+    readonly title: "Web Search Enhanced";
+    readonly description: "Choose the model route and built-in search settings used by web_search.";
+    readonly expand: "Expand";
+    readonly collapse: "Collapse";
+    readonly unsaved: "Unsaved";
+    readonly modelMode: "Model route";
+    readonly modelModeHint: "Use the fixed search route or follow the model and calling protocol of the current session.";
+    readonly configuredMode: "Fixed configuration";
+    readonly currentSessionMode: "Current session model";
+    readonly protocol: "API protocol";
+    readonly protocolHint: "The fixed or fallback route protocol. Follow mode uses the current model protocol when available.";
+    readonly anthropic: "Anthropic Messages v1";
+    readonly responses: "OpenAI Responses API";
+    readonly chat: "OpenAI Chat Completions API";
+    readonly baseURL: "Endpoint base URL";
+    readonly baseURLHint: "The protocol endpoint suffix is appended only when it is not already present.";
+    readonly model: "Model ID";
+    readonly modelHint: "The model used by the fixed route and when no session model is available.";
+    readonly fallbackModel: "Fallback search model";
+    readonly fallbackModelHint: "Optional model used when the current session route cannot be resolved; blank uses Model ID.";
+    readonly apiKeyEnv: "API key environment variable";
+    readonly apiKeyEnvHint: "The fixed and fallback route reads the API key from this credential reference.";
+    readonly apiKey: "API key";
+    readonly apiKeyHint: "Enter a new key to store it securely. The field is cleared after saving.";
+    readonly credentialConfigured: "A credential is configured for this reference.";
+    readonly toolIdentifier: "Internal search identifier";
+    readonly toolHintAnthropic: "Anthropic tool type. Leave blank for web_search_20250305.";
+    readonly toolHintResponses: "Responses built-in tool type. Leave blank for web_search.";
+    readonly toolHintChatOfficial: "Official Chat search models use the fixed web_search_options field.";
+    readonly toolHintChatVendor: "Vendor-specific Chat search options field. Leave blank for web_search_options.";
+    readonly maxTokens: "Max output tokens";
+    readonly maxTokensHint: "Positive integer sent as max_tokens or max_output_tokens for one search request.";
+    readonly maxUses: "Max search uses";
+    readonly maxUsesHint: "Anthropic-only maximum number of server-tool uses in one request.";
+    readonly apiVersion: "Anthropic API version";
+    readonly apiVersionHint: "Value sent in the anthropic-version request header.";
+    readonly chatSearchMode: "Chat search capability";
+    readonly chatSearchModeHint: "Use the official specialized-search-model contract unless the gateway documents a custom options field.";
+    readonly chatOfficial: "Official search model";
+    readonly chatVendor: "Vendor custom options field";
+    readonly searchContextSize: "Search context size";
+    readonly searchContextSizeHint: "Optional OpenAI-compatible context budget.";
+    readonly contextDefault: "Provider default";
+    readonly contextLow: "Low";
+    readonly contextMedium: "Medium";
+    readonly contextHigh: "High";
+    readonly save: "Save";
+    readonly saving: "Saving…";
+    readonly reset: "Reset to Profile";
+    readonly discard: "Discard";
+    readonly readOnly: "This connection cannot persist Host Profile settings.";
+    readonly failed: "The Host rejected the change. Review the fields and try again.";
+    readonly invalidURL: "Enter an absolute HTTP(S) endpoint URL.";
+    readonly invalidRequired: "This field must not be blank.";
+    readonly invalidCredentialRef: "Use a valid environment-variable name such as WEB_SEARCH_ENHANCED_API.";
+    readonly invalidIdentifier: "Use 1–128 identifier characters and start with a letter.";
+    readonly invalidInteger: "Enter a positive integer.";
+};
+export type LocaleKey = keyof typeof en;
+export declare const zh: Record<LocaleKey, string>;

package/lib/types/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Multi-protocol web search provider for DeepSeek Harness.
+ * @module dsh-web-search-enhanced
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import { EnhancedSearchProvider } from './provider.ts';
+import type { ChatSearchMode, ModelMode, ResolvedConfig, SearchContextSize, SearchProtocol } from './protocols.ts';
+/** Provider id selected by the bundled Web Profile patch. */
+export declare const DEFAULT_PROVIDER_ID = "enhanced-search";
+/** Default Anthropic-compatible search endpoint. */
+export declare const DEFAULT_BASE_URL = "https://api.deepseek.com/anthropic/v1";
+/** Default model aligned with DSH's built-in search provider. */
+export declare const DEFAULT_MODEL = "deepseek-v4-flash";
+/** Credential reference owned by this plugin's fixed and fallback routes. */
+export declare const DEFAULT_API_KEY_ENV = "WEB_SEARCH_ENHANCED_API";
+/** Settings namespace paired with the plugin configuration card. */
+export declare const SETTINGS_NAMESPACE: import("@deepseek-ai/dsh-settings").SettingsNamespace;
+/** Cordis plugin name used by loader diagnostics. */
+export declare const name = "web-search-enhanced";
+/** The web seam this provider contributes to. */
+export declare const inject: string[];
+/** Host configuration. Values may be overridden live from the Web Profile settings card. */
+export interface Config {
+    providerId?: string;
+    modelMode?: ModelMode;
+    protocol?: SearchProtocol;
+    baseURL?: string;
+    model?: string;
+    fallbackModel?: string;
+    apiKey?: string;
+    apiKeyEnv?: string;
+    apiVersion?: string;
+    toolIdentifier?: string;
+    maxTokens?: number;
+    maxUses?: number;
+    chatSearchMode?: ChatSearchMode;
+    searchContextSize?: SearchContextSize;
+}
+/** Schema shared by composition defaults and the live settings section. */
+export declare const Config: z<Config>;
+/** Resolve and validate one fixed/fallback route. */
+export declare function resolveConfig(config: Config): ResolvedConfig;
+/**
+ * Resolve the current Session route at search time. The fixed route is also the
+ * fallback route, so a configured fallback remains useful outside an Agent turn.
+ */
+export declare function resolveRuntimeConfig(ctx: Context, config: Config): Promise<ResolvedConfig>;
+/** Construct a fixed-config provider for tests or custom compositions. */
+export declare function createProvider(config?: Config, fetcher?: typeof fetch): EnhancedSearchProvider;
+/** Register the provider and its live Web Profile settings section. */
+export declare function apply(ctx: Context, config: Config): void;
+export { EnhancedSearchProvider } from './provider.ts';
+export type { ChatSearchMode, ModelMode, ResolvedConfig, SearchContextSize, SearchProtocol } from './protocols.ts';

package/lib/types/protocols.d.ts

@@ -0,0 +1,45 @@
+import type { WebSearchResult } from '@deepseek-ai/dsh-web';
+/** Upstream HTTP envelope used for one server-side web search. */
+export type SearchProtocol = 'anthropic-messages' | 'openai-responses' | 'openai-chat-completions';
+/** Select whether the search route is fixed or follows the active model. */
+export type ModelMode = 'configured' | 'current-session';
+/** Search context size accepted by OpenAI-compatible search endpoints. */
+export type SearchContextSize = 'low' | 'medium' | 'high';
+/** Chat Completions search activation: official search-model semantics or an explicit vendor extension. */
+export type ChatSearchMode = 'search-model' | 'vendor-options';
+/** Fully resolved settings captured at one search operation's entry. */
+export interface ResolvedConfig {
+    readonly providerId: string;
+    readonly modelMode: ModelMode;
+    readonly protocol: SearchProtocol;
+    readonly baseURL: string;
+    readonly model: string;
+    readonly fallbackModel: string | undefined;
+    readonly apiKey: string | undefined;
+    readonly apiKeyEnv: string;
+    readonly apiVersion: string;
+    readonly toolIdentifier: string;
+    readonly maxTokens: number;
+    readonly maxUses: number;
+    readonly chatSearchMode: ChatSearchMode;
+    readonly searchContextSize: SearchContextSize | undefined;
+}
+/** Secret-bearing HTTP request produced immediately before dispatch. */
+interface WireRequest {
+    readonly endpoint: string;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: Readonly<Record<string, unknown>>;
+}
+/** Return the protocol-specific built-in search identifier. */
+export declare function defaultToolIdentifier(protocol: SearchProtocol): string;
+/** Build one protocol request from resolved settings and a model-facing search query. */
+export declare function buildWireRequest(config: ResolvedConfig, query: string, apiKey: string): WireRequest;
+/** Parse a protocol response into DSH's provider-neutral search result. */
+export declare function parseSearchResponse(protocol: SearchProtocol, payload: unknown): WebSearchResult;
+/** Parse Anthropic Messages server-tool result blocks and citation snippets. */
+export declare function parseAnthropicResponse(payload: unknown): WebSearchResult;
+/** Parse Responses web_search_call items, message text, and URL annotations. */
+export declare function parseResponsesResponse(payload: unknown): WebSearchResult;
+/** Parse Chat Completions message text and URL citation annotations. */
+export declare function parseChatCompletionsResponse(payload: unknown): WebSearchResult;
+export {};

package/lib/types/provider.d.ts

@@ -0,0 +1,16 @@
+import type { WebSearchProvider, WebSearchRequest, WebSearchResult } from '@deepseek-ai/dsh-web';
+import type { ResolvedConfig } from './protocols.ts';
+/** Multi-protocol search provider. One resolved settings snapshot serves each operation. */
+export declare class EnhancedSearchProvider implements WebSearchProvider {
+    private readonly resolveConfig;
+    private readonly fetcher;
+    private readonly resolveApiKey;
+    /** Stable provider id selected by ctx.web. */
+    readonly id: string;
+    /** Create a provider backed by a dynamic settings resolver. */
+    constructor(resolveConfig: () => ResolvedConfig, fetcher?: typeof fetch, resolveApiKey?: (config: ResolvedConfig) => Promise<string | undefined>);
+    /** Report whether local configuration can attempt a request without network I/O. */
+    available(): boolean;
+    /** Execute one server-side web search and normalize its citations. */
+    search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>;
+}

package/package.json

@@ -0,0 +1,129 @@
+{
+  "name": "dsh-web-search-enhanced",
+  "version": "0.0.1",
+  "description": "Multi-protocol web_search provider for DeepSeek Harness",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0",
+    "dsh": ">=0.1.1-rc.2"
+  },
+  "main": "./lib/index.js",
+  "types": "./lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "lib/client.js.map",
+    "lib/types/**/*.d.ts",
+    "cordis.patch.yml",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-renderer",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-settings-plugins",
+        "@deepseek-ai/dsh-api-remotes"
+      ]
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-credentials": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-launch-environment": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-locale": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings-plugins": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-api-remotes": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-settings": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-web": "^0.1.1-rc.2",
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "react": "^18.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-client-locale": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-runtime": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-renderer": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-settings": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-settings-plugins": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-slots": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-credentials": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-launch-environment": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-locale": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings-plugins": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-api-remotes": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-settings": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-web": "^0.1.1-rc.2",
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "@types/node": "^22.20.0",
+    "@types/react": "~18.3.1",
+    "react": "^18.2.0",
+    "tsdown": "^0.22.2",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  },
+  "keywords": [
+    "deepseek-harness",
+    "dsh-plugin",
+    "web-search",
+    "anthropic",
+    "openai"
+  ],
+  "scripts": {
+    "clean": "node scripts/clean.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "build": "pnpm run clean && tsc -p tsconfig.build.json && tsdown --config tsdown.config.ts",
+    "check": "pnpm run typecheck && pnpm run test && pnpm run build && pnpm run verify:package",
+    "verify:package": "node scripts/verify-package.mjs"
+  }
+}