@deepthonk/providers 0.1.0 → 0.1.2

package/README.md

@@ -6,7 +6,7 @@ DeepThonk implements the OpenDeepThink algorithm (Zhou et al., 2026, [arXiv:2605
 
 DeepThonk runs a population of candidate answers through pairwise judging, Bradley-Terry ranking, critique-guided mutation, elite preservation, and a final dense ranking pass. The CLI and MCP server both call the same TypeScript core engine.
 
-**Designed for agents.** Every algorithm dimension — population shape (`n`, `k`, `t`, `m`), regularization (`lambda`), per-phase temperatures, prompt style, and per-phase prompt templates — is reachable inline through MCP arguments and CLI flags. No filesystem detours required. Every intermediate artifact (candidates, comparisons, scores, per-call usage, status) is exposed as a streaming MCP resource so an agent can inspect any step. See [Customization](https://github.com/linxule/deepthonk/blob/main/docs/customization.md) for the full agent-composable surface.
+**Designed for agents.** Every algorithm dimension — population shape (`n`, `k`, `t`, `m`), regularization (`lambda`), per-phase temperatures, prompt style, and per-phase prompt templates — is reachable inline through MCP arguments and CLI flags. CLI can load prompt files with `--prompts` or inline JSON with `--prompts-json`; MCP accepts inline structured prompt args. Every intermediate artifact (config, candidates, populations, comparisons, scores, per-call usage, status) is exposed as an MCP resource so an agent can inspect any step. See [Customization](https://github.com/linxule/deepthonk/blob/main/docs/customization.md) for the full agent-composable surface.
 
 Use it for hard, verifiable reasoning, coding, planning, and synthesis where breadth plus judgment can beat one expensive single shot. Avoid it for highly subjective tasks where judge noise dominates.
 
@@ -111,6 +111,8 @@ The MCP server exposes the same engine the CLI runs. Once wired into an MCP host
 
 Provider API keys come from the host process's environment, not from DeepThonk's config alone. Each host handles env passthrough slightly differently — see the concrete patterns below.
 
+MCP Sampling is supported as `provider: "sampling"` when the connected host advertises the MCP sampling capability. Sampling is not available from standalone CLI runs; use `deepseek`, `openrouter`, or `openai-compatible` there.
+
 ### Claude Code
 
 ```bash
@@ -198,7 +200,9 @@ All tools accept inline provider/model fields, or `config_path` pointing at a De
 
 - `deepthonk://runs` — JSON index of all runs in `runs/`.
 - `deepthonk://runs/{run_id}/summary` — run summary (JSON).
-- `deepthonk://runs/{run_id}/{candidates|comparisons|scores|trace}` — per-phase NDJSON.
+- `deepthonk://runs/{run_id}/config` — redacted run config (JSON).
+- `deepthonk://runs/{run_id}/{candidates|comparisons|scores|usage|trace}` — per-phase and per-call NDJSON.
+- `deepthonk://runs/{run_id}/population/{generation}` — population snapshot for a generation (JSON).
 - `deepthonk://runs/{run_id}/{winner|final}` — text artifacts.
 - `deepthonk://runs/{run_id}/status` — run state (JSON).
 - `deepthonk://jobs/{job_id}/{status|result}?run_dir=...` — job-scoped lookup; the `run_dir` query param is required.
@@ -209,7 +213,7 @@ Four templates mirror the core loop: `deepthonk/generate`, `deepthonk/compare`,
 
 ### Limits
 
-MCP Sampling is deferred and not exposed as a provider mode — direct provider mode is the only option in v0.1. `deepthonk.resume` reports trace state and safe phase boundaries but does not replay interrupted runs. The HTTP transport is loopback-only by design.
+`deepthonk.resume` reports trace state and safe phase boundaries but does not replay interrupted runs. The HTTP transport is loopback-only by design. MCP Sampling depends on the host's sampling implementation; model hints are preferences, token usage may be unavailable, and sampling concurrency is capped at 4.
 
 ## Customization
 
@@ -218,7 +222,7 @@ Every algorithm dimension is reachable through MCP arguments and CLI flags:
 - **Population shape**: `n`, `k`, `t`, `m` — override profile defaults inline.
 - **Algorithm constants**: `lambda`, `sample_temperature`, `mutate_temperature`, `judge_temperature`.
 - **Prompt style**: `general` or `paper-programming`.
-- **Per-phase prompt templates**: override `generate`, `compare`, `mutate`, or `finalize` with custom system/user templates and variable substitution (`{task}`, `{rubric}`, `{candidate}`, `{candidateA}`, `{candidateB}`, `{critique}`). Unknown variables throw a fail-fast error at run-start.
+- **Per-phase prompt templates**: override `generate`, `compare`, `mutate`, or `finalize` with custom system/user templates and variable substitution (`{task}`, `{rubric}`, `{candidate}`, `{candidateA}`, `{candidateB}`, `{critique}`). CLI supports `--prompts <yaml>` and `--prompts-json <json>`; MCP supports inline `prompts`. Unknown variables throw a fail-fast error at run-start.
 - **Concurrency**: per-phase caps for `generate`, `judge`, `mutate`.
 
 Example agent call (MCP), no YAML file required:
@@ -237,9 +241,11 @@ Example agent call (MCP), no YAML file required:
 }
 ```
 
-CLI accepts the same surface, except prompt overrides are loaded from a YAML file via `--prompts <yaml>` (shell-quoting multi-line templates is hostile). MCP and CLI both merge over any `--config`/`config_path` YAML defaults.
+CLI accepts the same surface. Use `--prompts <yaml>` for reusable prompt files or `--prompts-json <json>` for one-off inline overrides. MCP and CLI both merge over any `--config`/`config_path` YAML defaults.
+
+Save reusable bundles as **named profiles** at `~/.config/deepthonk/profiles/<name>.yaml` and load them with `--profile-name <name>` (CLI) or `profile_name: "<name>"` (MCP). A named profile is a standalone bundle that replaces the main config file for that run; CLI flags and MCP inline arguments still override fields inside it. See `examples/profiles/legal-drafting.yaml` for the shape. The [Customization guide](https://github.com/linxule/deepthonk/blob/main/docs/customization.md#managing-named-profiles) covers listing, showing, saving, and deleting named profiles from both CLI and MCP.
 
-See the [Customization guide](https://github.com/linxule/deepthonk/blob/main/docs/customization.md) for the complete variable contract, the compare-phase JSON safety rule, and three worked examples. Per-role provider routing (`providers.judge.provider = openrouter`) and per-model pricing remain YAML-only — they're nested structured config, not inline ergonomics.
+See the [Customization guide](https://github.com/linxule/deepthonk/blob/main/docs/customization.md) for the complete variable contract, the compare-phase JSON safety rule, the named-profile schema, and three worked examples. Per-role provider routing (`providers.judge.provider = openrouter`) and per-model pricing remain YAML-only — they're nested structured config, not inline ergonomics.
 
 ## Trace Files
 
@@ -280,7 +286,7 @@ This repository is source-only. Generated run traces, paper notes, build output,
 Known limits for this release:
 
 - Conservative resume reports trace state and safe phase boundaries, but does not replay interrupted runs yet.
-- MCP Sampling is deferred until there is a real host-backed Sampling driver.
+- MCP Sampling is MCP-host-only. Standalone CLI runs need a direct provider.
 - `maxUsd` requires known model pricing; add explicit prices in YAML for custom providers and model IDs. Optional fields `longContextThresholdTokens`, `inputUsdPerMillionLong`, and `outputUsdPerMillionLong` enable tiered pricing for models with a long-context surcharge (e.g., Gemini at 200K input tokens). Cache hit/miss rates remain flat.
 
 ## Acknowledgments

package/dist/defaults.d.ts

@@ -1,3 +1,4 @@
+import type { SamplingTransport } from "./sampling.js";
 import type { ProviderConfig, ProviderRole, RoleProviderConfig } from "./types.js";
 export type DirectProviderName = "fake" | "openai-compatible" | "deepseek" | "openrouter";
 export interface ProviderModelOverrides {
@@ -14,6 +15,7 @@ export interface ProviderConfigOptions {
     models?: ProviderModelOverrides;
     retry?: ProviderConfig["retry"];
     supportsJsonMode?: boolean;
+    samplingTransport?: SamplingTransport;
     roleProviders?: Partial<Record<ProviderRole, Partial<Omit<RoleProviderConfig, "model">> & {
         model?: string;
     }>>;

package/dist/defaults.js

@@ -16,6 +16,7 @@ export function resolveProviderConfig(options) {
         models,
         retry: options.retry,
         supportsJsonMode: options.supportsJsonMode,
+        samplingTransport: options.samplingTransport,
         roleProviders: resolveRoleProviders(options.provider, models, options.roleProviders, options.retry)
     };
 }
@@ -26,6 +27,8 @@ export function defaultModel(provider, role) {
         return role === "judge" ? "deepseek-v4-pro" : "deepseek-v4-flash";
     if (provider === "fake")
         return "fake-model";
+    if (provider === "sampling")
+        return "sampling";
     if (provider === "openrouter")
         return "openrouter/auto";
     return role === "judge" ? "provider/model-large" : "provider/model-small";

package/dist/defaults.js.map

@@ -1 +1 @@
-{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"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"}

package/dist/env.d.ts

@@ -0,0 +1,3 @@
+export declare const defaultConfigPath: string;
+export declare const defaultEnvPath: string;
+export declare function loadDeepThonkEnv(path?: string): Promise<void>;

package/dist/env.js

@@ -0,0 +1,36 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+export const defaultConfigPath = join(homedir(), ".config", "deepthonk", "config.yaml");
+export const defaultEnvPath = join(dirname(defaultConfigPath), "env");
+export async function loadDeepThonkEnv(path = process.env.DEEPTHONK_ENV ?? defaultEnvPath) {
+    if (!existsSync(path))
+        return;
+    const text = await readFile(path, "utf8");
+    for (const line of text.split("\n")) {
+        const parsed = parseEnvLine(line);
+        if (!parsed)
+            continue;
+        const [key, value] = parsed;
+        if (process.env[key] === undefined || process.env[key] === "")
+            process.env[key] = value;
+    }
+}
+function parseEnvLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#"))
+        return undefined;
+    const match = trimmed.match(/^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+    if (!match)
+        return undefined;
+    return [match[1], unquoteEnvValue(match[2].trim())];
+}
+function unquoteEnvValue(value) {
+    if ((value.startsWith("'") && value.endsWith("'")) || (value.startsWith('"') && value.endsWith('"'))) {
+        const inner = value.slice(1, -1);
+        return value.startsWith("'") ? inner.replace(/'\\''/g, "'") : inner.replace(/\\"/g, '"').replace(/\\\\/g, "\\");
+    }
+    return value;
+}
+//# sourceMappingURL=env.js.map

package/dist/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAE1C,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,WAAW,EAAE,aAAa,CAAC,CAAC;AACxF,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,CAAC,OAAO,CAAC,iBAAiB,CAAC,EAAE,KAAK,CAAC,CAAC;AAEtE,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,cAAc;IACvF,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO;IAC9B,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC1C,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;QAClC,IAAI,CAAC,MAAM;YAAE,SAAS;QACtB,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,MAAM,CAAC;QAC5B,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,SAAS,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE;YAAE,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IAC1F,CAAC;AACH,CAAC;AAED,SAAS,YAAY,CAAC,IAAY;IAChC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAC5B,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAC1D,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,+CAA+C,CAAC,CAAC;IAC7E,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;AACtD,CAAC;AAED,SAAS,eAAe,CAAC,KAAa;IACpC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;QACrG,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QACjC,OAAO,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAClH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/index.d.ts

@@ -1,6 +1,10 @@
 export * from "./fake.js";
 export * from "./defaults.js";
+export * from "./env.js";
+export * from "./jsonExtract.js";
+export * from "./profileRegistry.js";
 export * from "./openaiCompatible.js";
 export * from "./pricing.js";
 export * from "./registry.js";
+export * from "./sampling.js";
 export * from "./types.js";

package/dist/index.js

@@ -1,7 +1,11 @@
 export * from "./fake.js";
 export * from "./defaults.js";
+export * from "./env.js";
+export * from "./jsonExtract.js";
+export * from "./profileRegistry.js";
 export * from "./openaiCompatible.js";
 export * from "./pricing.js";
 export * from "./registry.js";
+export * from "./sampling.js";
 export * from "./types.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC"}

package/dist/jsonExtract.d.ts

@@ -0,0 +1,3 @@
+export declare const MAX_EXTRACTION_BYTES = 131072;
+export declare function extractJsonObjectText(text: string): string;
+export declare function extractJsonObject(text: string): unknown;

package/dist/jsonExtract.js

@@ -0,0 +1,35 @@
+import { JsonParseError } from "@deepthonk/core";
+export const MAX_EXTRACTION_BYTES = 131_072;
+export function extractJsonObjectText(text) {
+    if (text.length > MAX_EXTRACTION_BYTES) {
+        throw new JsonParseError(`Response text exceeds ${MAX_EXTRACTION_BYTES}-byte JSON extraction cap; refusing to parse.`);
+    }
+    const trimmed = text.trim();
+    const candidates = [trimmed, extractFence(trimmed), extractBalancedObject(trimmed)].filter((candidate) => Boolean(candidate));
+    for (const candidate of candidates) {
+        try {
+            const parsed = JSON.parse(candidate);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
+                return candidate;
+        }
+        catch {
+            // Try the next extraction strategy.
+        }
+    }
+    throw new JsonParseError("Model output did not contain a valid JSON object.");
+}
+export function extractJsonObject(text) {
+    return JSON.parse(extractJsonObjectText(text));
+}
+function extractFence(text) {
+    const match = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
+    return match?.[1]?.trim();
+}
+function extractBalancedObject(text) {
+    const start = text.indexOf("{");
+    const end = text.lastIndexOf("}");
+    if (start === -1 || end === -1 || end <= start)
+        return undefined;
+    return text.slice(start, end + 1);
+}
+//# sourceMappingURL=jsonExtract.js.map

package/dist/jsonExtract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonExtract.js","sourceRoot":"","sources":["../src/jsonExtract.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD,MAAM,CAAC,MAAM,oBAAoB,GAAG,OAAO,CAAC;AAE5C,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,IAAI,IAAI,CAAC,MAAM,GAAG,oBAAoB,EAAE,CAAC;QACvC,MAAM,IAAI,cAAc,CAAC,yBAAyB,oBAAoB,+CAA+C,CAAC,CAAC;IACzH,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAC5B,MAAM,UAAU,GAAG,CAAC,OAAO,EAAE,YAAY,CAAC,OAAO,CAAC,EAAE,qBAAqB,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CACxF,CAAC,SAAS,EAAuB,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,CACvD,CAAC;IACF,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;YACrC,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;gBAAE,OAAO,SAAS,CAAC;QACvF,CAAC;QAAC,MAAM,CAAC;YACP,oCAAoC;QACtC,CAAC;IACH,CAAC;IACD,MAAM,IAAI,cAAc,CAAC,mDAAmD,CAAC,CAAC;AAChF,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,OAAO,IAAI,CAAC,KAAK,CAAC,qBAAqB,CAAC,IAAI,CAAC,CAAC,CAAC;AACjD,CAAC;AAED,SAAS,YAAY,CAAC,IAAY;IAChC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,+BAA+B,CAAC,CAAC;IAC1D,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;AAC5B,CAAC;AAED,SAAS,qBAAqB,CAAC,IAAY;IACzC,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAChC,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,KAAK,KAAK,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC,CAAC,IAAI,GAAG,IAAI,KAAK;QAAE,OAAO,SAAS,CAAC;IACjE,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC;AACpC,CAAC"}

package/dist/profileRegistry.d.ts

@@ -0,0 +1,34 @@
+export declare const NAMED_PROFILE_NAME_RE: RegExp;
+export declare const RAW_API_KEY_RE: RegExp;
+export declare const SECRET_KEY_RE: RegExp;
+export interface NamedProfileBundle {
+    profile?: "quick" | "balanced" | "paper";
+    prompt_style?: "general" | "paper-programming";
+    provider?: string;
+    base_url?: string;
+    api_key_env?: string;
+    models?: {
+        generator?: string;
+        mutator?: string;
+        judge?: string;
+        finalizer?: string;
+    };
+    providers?: Record<string, unknown>;
+    algorithm?: Record<string, unknown>;
+    prompts?: Record<string, {
+        system?: string;
+        user?: string;
+    }>;
+    budget?: unknown;
+    concurrency?: unknown;
+    retry?: unknown;
+    output?: unknown;
+    [key: string]: unknown;
+}
+export declare function profilesDir(): string;
+export declare function profilePath(name: string): string;
+export declare function listProfiles(): Promise<string[]>;
+export declare function loadNamedProfile(name: string): Promise<NamedProfileBundle>;
+export declare function validateNamedProfileBundle(bundle: NamedProfileBundle, name?: string): void;
+export declare function rejectRawApiKeyFields(value: unknown, name?: string): void;
+export declare function rejectAllSecretShapedFields(value: unknown, name?: string): void;

package/dist/profileRegistry.js

@@ -0,0 +1,139 @@
+import { existsSync } from "node:fs";
+import { readFile, readdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import YAML from "yaml";
+import { ConfigError } from "@deepthonk/core";
+import { defaultConfigPath } from "./env.js";
+export const NAMED_PROFILE_NAME_RE = /^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/;
+export const RAW_API_KEY_RE = /^api[_-]?key$/i;
+export const SECRET_KEY_RE = /^(api[_-]?key|token|secret|password|authorization|bearer|cookie|credential)$/i;
+const SECRET_KEY_FIX = "Remove raw secret fields from the profile. Rejected key shapes: api_key/api-key, token, secret, password, authorization, bearer, cookie, credential. Use api_key_env to reference an environment variable name instead.";
+export function profilesDir() {
+    return process.env.DEEPTHONK_PROFILES_DIR ?? join(dirname(defaultConfigPath), "profiles");
+}
+export function profilePath(name) {
+    return join(profilesDir(), `${name}.yaml`);
+}
+export async function listProfiles() {
+    const dir = profilesDir();
+    if (!existsSync(dir))
+        return [];
+    const entries = await readdir(dir, { withFileTypes: true });
+    return entries
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".yaml"))
+        .map((entry) => entry.name.replace(/\.yaml$/, ""))
+        .sort();
+}
+export async function loadNamedProfile(name) {
+    validateProfileName(name);
+    const path = profilePath(name);
+    if (!existsSync(path)) {
+        const available = await listProfiles();
+        const availableHint = available.length ? `Available profiles: ${available.join(", ")}.` : `No saved profiles yet in ${profilesDir()}.`;
+        throw new ConfigError(`Named profile '${name}' not found at ${path}. ${availableHint}`, {
+            code: "config.profile_not_found",
+            retryable: false,
+            fix: `Create ${path} with at least { provider, prompt_style, models.{generator,mutator,judge} } and either profile or algorithm fields. See docs/customization.md for the schema.`
+        });
+    }
+    let parsed;
+    try {
+        parsed = YAML.parse(await readFile(path, "utf8"));
+    }
+    catch (error) {
+        throw new ConfigError(`Named profile '${name}' is not valid YAML: ${error.message}`, {
+            code: "config.profile_invalid_yaml",
+            retryable: false,
+            fix: `Fix YAML syntax in ${path}.`
+        });
+    }
+    const config = validateNamedProfileValue(parsed, name);
+    return config;
+}
+export function validateNamedProfileBundle(bundle, name = "profile") {
+    validateNamedProfileValue(bundle, name);
+}
+function validateProfileName(name) {
+    if (!NAMED_PROFILE_NAME_RE.test(name)) {
+        throw new ConfigError(`Invalid profile name '${name}'. Names must start with a letter and contain only letters, digits, hyphens, and underscores (max 64 chars).`, {
+            code: "config.profile_invalid_name",
+            retryable: false,
+            fix: "Rename the profile to match /^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/."
+        });
+    }
+}
+function validateRequiredFields(config, name) {
+    const missing = [];
+    if (!config.profile && !config.algorithm)
+        missing.push("profile (built-in name) or algorithm (block)");
+    if (!config.prompt_style)
+        missing.push("prompt_style");
+    if (!config.provider)
+        missing.push("provider");
+    if (!config.models?.generator)
+        missing.push("models.generator");
+    if (!config.models?.mutator)
+        missing.push("models.mutator");
+    if (!config.models?.judge)
+        missing.push("models.judge");
+    if (missing.length > 0) {
+        throw new ConfigError(`Named profile '${name}' is missing required fields: ${missing.join(", ")}.`, {
+            code: "config.profile_missing_fields",
+            retryable: false,
+            fix: "Standalone named profiles must declare the algorithm shape (profile or algorithm block), prompt_style, provider, and at least generator/mutator/judge models. See docs/customization.md."
+        });
+    }
+}
+function validateNamedProfileValue(value, name) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new ConfigError(`Named profile '${name}' must be a YAML mapping at the top level.`, {
+            code: "config.profile_invalid_shape",
+            retryable: false,
+            fix: `Top-level YAML should have keys like provider, prompt_style, models, algorithm.`
+        });
+    }
+    const config = value;
+    rejectRawApiKeyFields(config, name);
+    validateRequiredFields(config, name);
+    return config;
+}
+export function rejectRawApiKeyFields(value, name = "profile") {
+    rejectMatchingProfileKeys(value, RAW_API_KEY_RE, "config.profile_raw_api_key", (key, path) => ({
+        message: `Named profile '${name}' must not contain a raw '${key}' value at ${path}.`,
+        fix: "Use api_key_env to reference an environment variable name instead. Raw secrets must not be written to profile files."
+    }));
+}
+export function rejectAllSecretShapedFields(value, name = "profile") {
+    rejectMatchingProfileKeys(value, SECRET_KEY_RE, "config.profile_raw_secret", (key, path) => ({
+        message: `Named profile '${name}' must not contain a raw secret-shaped '${key}' value at ${path}.`,
+        fix: SECRET_KEY_FIX
+    }));
+}
+function rejectMatchingProfileKeys(value, keyPattern, code, describe) {
+    const seen = new WeakSet();
+    const visit = (current, path) => {
+        if (!current || typeof current !== "object")
+            return;
+        if (seen.has(current))
+            return;
+        seen.add(current);
+        if (Array.isArray(current)) {
+            current.forEach((item, index) => visit(item, `${path}[${index}]`));
+            return;
+        }
+        for (const [key, inner] of Object.entries(current)) {
+            const childPath = path ? `${path}.${key}` : key;
+            if (keyPattern.test(key)) {
+                const description = describe(key, childPath);
+                throw new ConfigError(description.message, {
+                    code,
+                    retryable: false,
+                    fix: description.fix
+                });
+            }
+            visit(inner, childPath);
+        }
+    };
+    visit(value, "");
+}
+//# sourceMappingURL=profileRegistry.js.map

package/dist/profileRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profileRegistry.js","sourceRoot":"","sources":["../src/profileRegistry.ts"],"names":[],"mappings":"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"}

package/dist/registry.js

@@ -1,6 +1,7 @@
 import { FakeDriver } from "./fake.js";
 import { createDeepSeekDriver, OpenAiCompatibleDriver } from "./openaiCompatible.js";
-import { ProviderError } from "@deepthonk/core";
+import { ConfigError, ProviderError } from "@deepthonk/core";
+import { SamplingDriver } from "./sampling.js";
 export function createDriver(config) {
     const baseDriver = createSingleDriver({ ...config, roleProviders: undefined });
     if (config.roleProviders)
@@ -10,6 +11,19 @@ export function createDriver(config) {
 function createSingleDriver(config) {
     if (config.provider === "fake")
         return new FakeDriver();
+    if (config.provider === "sampling") {
+        if (!config.samplingTransport) {
+            throw new ConfigError("MCP Sampling provider requires running as an MCP server. Use a direct provider mode (deepseek, openrouter, openai-compatible) for CLI runs.", {
+                code: "provider.sampling_requires_mcp",
+                retryable: false,
+                fix: "Run DeepThonk through an MCP host that advertises sampling, or choose a direct provider for CLI runs."
+            });
+        }
+        return new SamplingDriver(config.samplingTransport, {
+            ...config,
+            requestTimeoutMs: config.retry?.requestTimeoutMs ?? config.requestTimeoutMs
+        });
+    }
     if (config.provider === "deepseek")
         return createDeepSeekDriver(config);
     if (config.provider === "openai-compatible")

package/dist/registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"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"}

package/dist/sampling.d.ts

@@ -0,0 +1,25 @@
+import { type CompareInput, type FinalizeInput, type GenerateInput, type ModelDriver, type ModelTextResult, type MutateInput } from "@deepthonk/core";
+import type { RequestOptions } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import type { CreateMessageRequestParamsBase, CreateMessageResult, ModelPreferences } from "@modelcontextprotocol/sdk/types.js";
+export interface SamplingDriverConfig {
+    modelHints?: string[];
+    costPriority?: number;
+    speedPriority?: number;
+    intelligencePriority?: number;
+    includeRawOutputs?: boolean;
+    requestTimeoutMs?: number;
+}
+export type SamplingTransport = (params: CreateMessageRequestParamsBase, options?: RequestOptions) => Promise<CreateMessageResult>;
+export declare class SamplingDriver implements ModelDriver {
+    private readonly createMessage;
+    private readonly config;
+    readonly maxConcurrency = 4;
+    constructor(createMessage: SamplingTransport, config?: SamplingDriverConfig);
+    generate(input: GenerateInput): Promise<ModelTextResult>;
+    compare(input: CompareInput): Promise<ModelTextResult>;
+    mutate(input: MutateInput): Promise<ModelTextResult>;
+    finalize(input: FinalizeInput): Promise<ModelTextResult>;
+    private sample;
+    private callCreateMessage;
+}
+export declare function buildModelPreferences(roleModel: string | undefined, config: SamplingDriverConfig): ModelPreferences | undefined;

package/dist/sampling.js

@@ -0,0 +1,159 @@
+import { ProviderError } from "@deepthonk/core";
+import { extractJsonObjectText } from "./jsonExtract.js";
+const DEFAULT_SAMPLING_TIMEOUT_MS = 60_000;
+export class SamplingDriver {
+    createMessage;
+    config;
+    maxConcurrency = 4;
+    constructor(createMessage, config = {}) {
+        this.createMessage = createMessage;
+        this.config = config;
+    }
+    async generate(input) {
+        return this.sample(input.model, input.temperature, promptMessages(input.prompt));
+    }
+    async compare(input) {
+        const result = await this.sample(input.model, input.temperature, promptMessages(input.prompt));
+        return { ...result, text: extractJsonTextOrOriginal(result.text) };
+    }
+    async mutate(input) {
+        return this.sample(input.model, input.temperature, promptMessages(input.prompt));
+    }
+    async finalize(input) {
+        return this.sample(input.model, 0.2, promptMessages(input.prompt));
+    }
+    async sample(model, temperature, prompt) {
+        const started = Date.now();
+        const result = await this.callCreateMessage({
+            messages: prompt.user.trim()
+                ? [
+                    {
+                        role: "user",
+                        content: {
+                            type: "text",
+                            text: prompt.user
+                        }
+                    }
+                ]
+                : [],
+            systemPrompt: prompt.system.trim() ? prompt.system : undefined,
+            modelPreferences: buildModelPreferences(model, this.config),
+            includeContext: "none",
+            temperature,
+            maxTokens: 4096
+        });
+        if (result.stopReason === "maxTokens") {
+            throw new ProviderError("MCP Sampling response was truncated by maxTokens.", {
+                code: "provider.output_truncated",
+                retryable: false,
+                fix: "Use a smaller prompt, a host model with larger output support, or reduce answer length."
+            });
+        }
+        const text = textContent(result);
+        return {
+            text,
+            model: result.model ?? model,
+            provider: "sampling",
+            usage: {
+                inputTokens: undefined,
+                outputTokens: undefined
+            },
+            latencyMs: Date.now() - started,
+            retryCount: 0,
+            raw: this.config.includeRawOutputs ? result : undefined
+        };
+    }
+    async callCreateMessage(params) {
+        const timeoutMs = this.config.requestTimeoutMs ?? DEFAULT_SAMPLING_TIMEOUT_MS;
+        try {
+            return await callWithTimeout(this.createMessage, params, timeoutMs);
+        }
+        catch (error) {
+            if (error instanceof SamplingTimeoutError) {
+                throw new ProviderError(`MCP Sampling request timed out after ${error.timeoutMs}ms.`, {
+                    code: "provider.sampling_timeout",
+                    retryable: false,
+                    fix: "Increase retry.requestTimeoutMs, switch to a direct provider, or check the MCP host responsiveness. Use 'deepthonk resume <run-dir> --continue' to retry an interrupted run."
+                });
+            }
+            throw new ProviderError(`MCP Sampling request failed: ${error instanceof Error ? error.message : String(error)}`, {
+                code: "provider.sampling_request_failed",
+                retryable: false,
+                fix: "The MCP host refused or errored the sampling request. Use 'deepthonk resume <run-dir> --continue' to retry an interrupted run, or switch to a direct provider."
+            });
+        }
+    }
+}
+class SamplingTimeoutError extends Error {
+    timeoutMs;
+    constructor(timeoutMs) {
+        super(`MCP Sampling request timed out after ${timeoutMs}ms.`);
+        this.timeoutMs = timeoutMs;
+        this.name = "SamplingTimeoutError";
+    }
+}
+async function callWithTimeout(fn, params, timeoutMs) {
+    const controller = new AbortController();
+    let timer;
+    const timeoutPromise = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            controller.abort();
+            reject(new SamplingTimeoutError(timeoutMs));
+        }, timeoutMs);
+    });
+    try {
+        return await Promise.race([fn(params, { signal: controller.signal, timeout: timeoutMs }), timeoutPromise]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+export function buildModelPreferences(roleModel, config) {
+    const hintNames = uniqueNonEmpty([roleModel, ...(config.modelHints ?? [])]);
+    const preferences = {};
+    if (hintNames.length > 0)
+        preferences.hints = hintNames.map((name) => ({ name }));
+    if (config.costPriority !== undefined)
+        preferences.costPriority = config.costPriority;
+    if (config.speedPriority !== undefined)
+        preferences.speedPriority = config.speedPriority;
+    if (config.intelligencePriority !== undefined)
+        preferences.intelligencePriority = config.intelligencePriority;
+    return Object.keys(preferences).length > 0 ? preferences : undefined;
+}
+function promptMessages(prompt) {
+    if (!prompt)
+        throw new ProviderError("Core did not provide prompt messages.");
+    return prompt;
+}
+function textContent(result) {
+    if (result.content.type === "text")
+        return result.content.text;
+    throw new ProviderError(`MCP Sampling returned unsupported ${result.content.type} content.`, {
+        code: "provider.sampling_non_text_response",
+        retryable: false,
+        fix: "Use an MCP client/model that can return text content for sampling requests."
+    });
+}
+function extractJsonTextOrOriginal(text) {
+    try {
+        return extractJsonObjectText(text);
+    }
+    catch {
+        return text;
+    }
+}
+function uniqueNonEmpty(values) {
+    const seen = new Set();
+    const unique = [];
+    for (const value of values) {
+        const trimmed = value?.trim();
+        if (!trimmed || seen.has(trimmed))
+            continue;
+        seen.add(trimmed);
+        unique.push(trimmed);
+    }
+    return unique;
+}
+//# sourceMappingURL=sampling.js.map

package/dist/sampling.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampling.js","sourceRoot":"","sources":["../src/sampling.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { SamplingDriverConfig, SamplingTransport } from "./sampling.js";
 export type { CompareInput, FinalizeInput, GenerateInput, ModelDriver, ModelTextResult, MutateInput } from "@deepthonk/core";
 export type ProviderRole = "generator" | "mutator" | "judge" | "finalizer";
 export interface RoleProviderConfig {
@@ -12,11 +13,12 @@ export interface RoleProviderConfig {
     };
     supportsJsonMode?: boolean;
 }
-export interface ProviderConfig {
+export interface BaseProviderConfig extends SamplingDriverConfig {
     provider: "fake" | "openai-compatible" | "deepseek" | string;
     baseUrl?: string;
     apiKeyEnv?: string;
     apiKey?: string;
+    samplingTransport?: SamplingTransport;
     models: {
         generator: string;
         mutator: string;
@@ -30,3 +32,8 @@ export interface ProviderConfig {
     supportsJsonMode?: boolean;
     roleProviders?: Partial<Record<ProviderRole, RoleProviderConfig>>;
 }
+export type SamplingProviderConfig = BaseProviderConfig & SamplingDriverConfig & {
+    provider: "sampling";
+    samplingTransport?: SamplingTransport;
+};
+export type ProviderConfig = BaseProviderConfig | SamplingProviderConfig;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepthonk/providers",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Provider drivers and routing for DeepThonk.",
   "license": "MIT",
   "author": "Xule Lin",
@@ -32,8 +32,9 @@
     "directory": "packages/providers"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^3.25.28",
-    "@deepthonk/core": "0.1.0"
+    "@deepthonk/core": "0.1.2"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",