deepseek-web-retrieval 0.4.0 → 0.5.1

package/src/installer/state.ts

@@ -1,20 +1,91 @@
-import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs"
-import { join } from "node:path"
-import { stateDir } from "./paths"
-import type { FsRoots, InstallerInput, InstallRecord } from "./types"
+import { existsSync, lstatSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { z } from "zod/v4";
+import { stateDir } from "./paths";
+import { atomicWrite } from "./persistence";
+import type { FsRoots, InstallerInput, InstallRecord } from "./types";
 
 export function statePathFor(input: InstallerInput): string {
-  return join(stateDir(input, input.scope), `install.${input.host}.json`)
+  return join(stateDir(input, input.scope), `install.${input.host}.json`);
 }
 
-export function readRecord(input: InstallerInput): InstallRecord | undefined {
-  const file = statePathFor(input)
-  if (!existsSync(file)) return undefined
+const keyPath = z.array(z.string().min(1)).min(1);
+const tier = z.enum(["optional", "preferred", "forced", "off"]);
+const operation = z.discriminatedUnion("op", [
+  z.object({ op: z.literal("set"), path: keyPath, applied: z.unknown(), previous: z.unknown().optional() }),
+  z.object({
+    op: z.literal("append-array"),
+    path: keyPath,
+    applied: z.array(z.unknown()),
+    previous: z.unknown().optional(),
+  }),
+]);
+const recordSchema = z.object({
+  version: z.literal(1),
+  host: z.enum(["opencode", "pi", "codex"]),
+  scope: z.enum(["global", "project"]),
+  tiers: z.object({ search: tier, fetch: tier }),
+  createdAt: z.string().refine((value) => Number.isFinite(Date.parse(value))),
+  files: z.array(
+    z.object({
+      file: z.string().refine(isAbsolute),
+      format: z.enum(["json", "toml", "rules"]),
+      created: z.boolean(),
+      shared: z.literal(true).optional(),
+      ops: z.array(operation),
+      blockApplied: z.string().optional(),
+      createdParents: z.array(keyPath).optional(),
+    }),
+  ),
+});
+
+export class InstallRecordError extends Error {
+  constructor(
+    readonly file: string,
+    readonly kind: "unreadable" | "invalid",
+    detail: string,
+  ) {
+    super(
+      `${kind === "invalid" ? "Invalid install record" : "Cannot read install record"} at ${file} (${detail}). ` +
+        "Restore a valid record from backup or repair its permissions before retrying; configuration was not changed. Do not delete undo state to bypass this check.",
+    );
+    this.name = "InstallRecordError";
+  }
+}
+
+function readRecordFile(file: string, host: string, scope: string): InstallRecord | undefined {
+  let text: string;
   try {
-    return JSON.parse(readFileSync(file, "utf8")) as InstallRecord
+    text = readFileSync(file, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      try {
+        lstatSync(file);
+      } catch (statError) {
+        if ((statError as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+      }
+    }
+    throw new InstallRecordError(file, "unreadable", (error as NodeJS.ErrnoException).code ?? "read failed");
+  }
+  let value: unknown;
+  try {
+    value = JSON.parse(text);
   } catch {
-    return undefined
+    throw new InstallRecordError(file, "invalid", "malformed JSON");
+  }
+  const result = recordSchema.safeParse(value);
+  if (!result.success) {
+    // Never include snapshot values in diagnostics: they may contain private configuration.
+    throw new InstallRecordError(file, "invalid", "unsupported version or malformed record structure");
   }
+  if (result.data.host !== host || result.data.scope !== scope) {
+    throw new InstallRecordError(file, "invalid", "host or scope does not match its location");
+  }
+  return result.data as InstallRecord;
+}
+
+export function readRecord(input: InstallerInput): InstallRecord | undefined {
+  return readRecordFile(statePathFor(input), input.host, input.scope);
 }
 
 /**
@@ -22,10 +93,10 @@ export function readRecord(input: InstallerInput): InstallRecord | undefined {
  * same host: returns the subset of `files` the record at the other scope claims.
  */
 export function claimedByOtherScope(input: InstallerInput, files: readonly string[]): string[] {
-  const other = input.scope === "global" ? "project" : "global"
-  const record = readRecord({ ...input, scope: other })
-  if (record === undefined) return []
-  return files.filter((file) => record.files.some((candidate) => candidate.file === file))
+  const other = input.scope === "global" ? "project" : "global";
+  const record = readRecord({ ...input, scope: other });
+  if (record === undefined) return [];
+  return files.filter((file) => record.files.some((candidate) => candidate.file === file));
 }
 
 /**
@@ -33,31 +104,45 @@ export function claimedByOtherScope(input: InstallerInput, files: readonly strin
  * owner-only permissions regardless of umask.
  */
 export function writeRecord(input: InstallerInput, record: InstallRecord): void {
-  const file = statePathFor(input)
-  mkdirSync(join(file, ".."), { recursive: true })
-  writeFileSync(file, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 })
-  chmodSync(file, 0o600)
+  const file = statePathFor(input);
+  atomicWrite(file, `${JSON.stringify(record, null, 2)}\n`, 0o600);
+}
+
+/** Entries a previous init appended at the given path, across its recorded files. */
+export function appendedByPrevious(record: InstallRecord | undefined, path: readonly string[]): readonly unknown[] {
+  if (record === undefined) return [];
+  const entries: unknown[] = [];
+  for (const file of record.files) {
+    for (const op of file.ops) {
+      if (op.op !== "append-array" || op.path.join("\u0000") !== path.join("\u0000")) continue;
+      if (Array.isArray(op.applied)) entries.push(...op.applied);
+    }
+  }
+  return entries;
 }
 
 export function deleteRecord(input: InstallerInput): void {
-  const file = statePathFor(input)
-  if (existsSync(file)) rmSync(file)
+  const file = statePathFor(input);
+  if (existsSync(file)) rmSync(file);
 }
 
 /** Lists install records found in both scope locations for the given roots. */
 export function listRecords(roots: FsRoots): InstallRecord[] {
-  const records: InstallRecord[] = []
+  const records: InstallRecord[] = [];
   for (const scope of ["global", "project"] as const) {
-    const dir = stateDir(roots, scope)
-    if (!existsSync(dir)) continue
-    for (const name of readdirSync(dir)) {
-      if (!name.startsWith("install.") || !name.endsWith(".json")) continue
-      try {
-        records.push(JSON.parse(readFileSync(join(dir, name), "utf8")) as InstallRecord)
-      } catch {
-        // Unreadable records are skipped; uninstall reports them as absent.
-      }
+    const dir = stateDir(roots, scope);
+    let names: string[];
+    try {
+      names = readdirSync(dir);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") continue;
+      throw new InstallRecordError(dir, "unreadable", (error as NodeJS.ErrnoException).code ?? "list failed");
+    }
+    for (const name of names) {
+      if (!name.startsWith("install.") || !name.endsWith(".json")) continue;
+      const record = readRecordFile(join(dir, name), name.slice("install.".length, -".json".length), scope);
+      if (record !== undefined) records.push(record);
     }
   }
-  return records
+  return records;
 }

package/src/installer/types.ts

@@ -1,126 +1,144 @@
 /** Hosts the installer supports. */
-export type HostName = "opencode" | "pi" | "codex"
+export type HostName = "opencode" | "pi" | "codex";
 
 /** Install scope, a first-class user choice. */
-export type Scope = "project" | "global"
+export type Scope = "project" | "global";
 
 /**
  * The filesystem roots path resolution needs; InstallerInput satisfies this structurally.
  * Each host module owns the mapping from an input to its config and rules files.
  */
 export interface FsRoots {
-  readonly home: string
-  readonly cwd: string
+  readonly home: string;
+  readonly cwd: string;
   /** Explicit config home; the CLI edge resolves XDG once and passes it down. */
-  readonly configHome?: string
+  readonly configHome?: string;
 }
 
 /** The files a host edit touches for a given scope. */
 export interface HostPaths {
   /** Main host config file the installer edits. */
-  readonly config: string
+  readonly config: string;
   /** Rules file receiving the marked block for the preferred tier. */
-  readonly rules: string
+  readonly rules: string;
 }
 
 /** Control tier per capability; "off" skips the tool entirely. */
-export type Tier = "optional" | "preferred" | "forced" | "off"
+export type Tier = "optional" | "preferred" | "forced" | "off";
 
 /** Everything the installer needs to build a plan. */
 export interface InstallerInput {
-  readonly host: HostName
-  readonly scope: Scope
-  readonly search: Tier
-  readonly fetch: Tier
+  readonly host: HostName;
+  readonly scope: Scope;
+  readonly search: Tier;
+  readonly fetch: Tier;
   /** npm package reference written into host config; defaults to the published name. */
-  readonly packageRef: string
-  readonly home: string
-  readonly cwd: string
-  readonly configHome?: string
+  readonly packageRef: string;
+  readonly home: string;
+  readonly cwd: string;
+  readonly configHome?: string;
+  /**
+   * Integration mechanism for hosts with more than one (Pi: the native
+   * extension, or the MCP server). Undefined means the host's default path.
+   */
+  readonly path?: "extension" | "mcp";
+  /**
+   * The host CLI's version probed at the CLI edge (for drift notes); undefined
+   * means the probe was not attempted or could not read a version.
+   */
+  readonly hostVersion?: string;
 }
 
 /** A mutation on a parsed config object, addressed by a dotted path. */
 export interface ConfigOp {
-  readonly op: "set" | "append-array"
-  readonly path: readonly string[]
-  readonly value?: unknown
-  readonly entries?: readonly unknown[]
+  readonly op: "set" | "append-array";
+  readonly path: readonly string[];
+  readonly value?: unknown;
+  readonly entries?: readonly unknown[];
   /** Plan-preview metadata: the value the set replaces (undefined when absent). */
-  readonly previous?: unknown
+  readonly previous?: unknown;
   /** Plan-preview metadata: entries already present at an append-array path. */
-  readonly existingCount?: number
+  readonly existingCount?: number;
 }
 
 /** A JSON file edit: comment-preserving ops on JSONC text. */
 export interface JsonEdit {
-  readonly file: string
-  readonly format: "json"
-  readonly ops: readonly ConfigOp[]
+  readonly file: string;
+  readonly format: "json";
+  readonly ops: readonly ConfigOp[];
+  /** The host maps multiple install locations onto this one config file. */
+  readonly shared?: true;
 }
 
 /** A TOML file edit: ops on the parsed value, serialized on write. */
 export interface TomlEdit {
-  readonly file: string
-  readonly format: "toml"
-  readonly ops: readonly ConfigOp[]
+  readonly file: string;
+  readonly format: "toml";
+  readonly ops: readonly ConfigOp[];
+  /** The host maps multiple install locations onto this one config file. */
+  readonly shared?: true;
 }
 
 /** A rules file edit: upserts the host's marked block; it carries no ops. */
 export interface RulesEdit {
-  readonly file: string
-  readonly format: "rules"
-  readonly block: string
+  readonly file: string;
+  readonly format: "rules";
+  readonly block: string;
 }
 
 /** One file the plan touches, discriminated by config format. */
-export type FileEdit = JsonEdit | TomlEdit | RulesEdit
+export type FileEdit = JsonEdit | TomlEdit | RulesEdit;
 
 /** A plan that refuses to proceed (for example a structurally unavailable tier). */
 export interface PlanError {
-  readonly message: string
+  readonly message: string;
 }
 
 export interface InstallPlan {
-  readonly host: HostName
-  readonly scope: Scope
-  readonly tiers: { readonly search: Tier; readonly fetch: Tier }
-  readonly edits: readonly FileEdit[]
-  readonly notes: readonly string[]
-  readonly errors: readonly PlanError[]
+  /** Plan-time undo state; apply rejects a plan superseded by another operation. */
+  readonly previousRecord?: InstallRecord;
+  readonly host: HostName;
+  readonly scope: Scope;
+  readonly tiers: { readonly search: Tier; readonly fetch: Tier };
+  readonly edits: readonly FileEdit[];
+  readonly notes: readonly string[];
+  readonly errors: readonly PlanError[];
   /**
    * Artifacts from a previous init that this plan no longer wants (for example the
    * web_search kill switch after a forced → optional tier change). They are shown in
    * the plan, reverted during apply, and then gone from the record — so uninstall
    * still restores exactly what this install applied.
    */
-  readonly reverts?: readonly RecordedFile[]
+  readonly reverts?: readonly RecordedFile[];
 }
 
 /** An op as it was actually applied, with the previous value for surgical undo. */
 export interface RecordedOp {
-  readonly op: "set" | "append-array"
-  readonly path: readonly string[]
-  readonly applied: unknown
-  readonly previous: unknown
+  readonly op: "set" | "append-array";
+  readonly path: readonly string[];
+  readonly applied: unknown;
+  readonly previous: unknown;
 }
 
 /** A file as it was actually written, for surgical uninstall. */
 export interface RecordedFile {
-  readonly file: string
-  readonly format: "json" | "toml" | "rules"
-  readonly created: boolean
-  readonly ops: readonly RecordedOp[]
-  readonly blockApplied?: string
+  readonly file: string;
+  readonly format: "json" | "toml" | "rules";
+  readonly created: boolean;
+  /** Shared config ownership must be discoverable from every project. */
+  readonly shared?: true;
+  readonly ops: readonly RecordedOp[];
+  readonly blockApplied?: string;
   /** Path prefixes the apply step had to create; uninstall removes them when left empty. */
-  readonly createdParents?: readonly (readonly string[])[]
+  readonly createdParents?: readonly (readonly string[])[];
 }
 
 /** Persisted install state; one record per host and scope. */
 export interface InstallRecord {
-  readonly version: 1
-  readonly host: HostName
-  readonly scope: Scope
-  readonly tiers: { readonly search: Tier; readonly fetch: Tier }
-  readonly createdAt: string
-  readonly files: readonly RecordedFile[]
+  readonly version: 1;
+  readonly host: HostName;
+  readonly scope: Scope;
+  readonly tiers: { readonly search: Tier; readonly fetch: Tier };
+  readonly createdAt: string;
+  readonly files: readonly RecordedFile[];
 }

package/src/installer/uninstall.ts

@@ -1,7 +1,10 @@
-import { stateDir } from "./paths"
-import { pruneEmptyDir, revertRecordedFile } from "./revert"
-import { claimedByOtherScope, deleteRecord, readRecord } from "./state"
-import type { InstallerInput } from "./types"
+import { codecFor } from "./formats";
+import { withOperationLock } from "./operation-lock";
+import { assertFileOwnership, releaseFileOwnership } from "./ownership";
+import { stateDir } from "./paths";
+import { pruneEmptyDir, revertRecordedFile } from "./revert";
+import { claimedByOtherScope, deleteRecord, readRecord, statePathFor } from "./state";
+import type { InstallerInput, InstallRecord } from "./types";
 
 /**
  * Reverses exactly what the plan applied: overwritten values restore their
@@ -10,24 +13,44 @@ import type { InstallerInput } from "./types"
  * rules blocks are removed, and files the installer created are deleted.
  */
 export function uninstall(input: InstallerInput): string[] {
-  const record = readRecord(input)
-  if (record === undefined) {
-    throw new Error(`No ${input.host} install is recorded for the ${input.scope} scope.`)
-  }
-  const other = input.scope === "global" ? "project" : "global"
-  const overlap = claimedByOtherScope(input, record.files.map((file) => file.file))
+  return withOperationLock([statePathFor(input)], () => {
+    const record = readRecord(input);
+    if (record === undefined) {
+      throw new Error(`No ${input.host} install is recorded for the ${input.scope} scope.`);
+    }
+    return withOperationLock(
+      record.files.map((file) => file.file),
+      () => uninstallLocked(input, record),
+    );
+  });
+}
+
+function uninstallLocked(input: InstallerInput, record: InstallRecord): string[] {
+  assertFileOwnership(input, record.files);
+  const other = input.scope === "global" ? "project" : "global";
+  const overlap = claimedByOtherScope(
+    input,
+    record.files.map((file) => file.file),
+  );
   if (overlap.length > 0) {
     throw new Error(
       `A ${input.host} install is also recorded at the ${other} scope and claims the same file(s): ${overlap.join(", ")}. ` +
         `Uninstall the ${other}-scope install first so this rollback cannot clobber its entries.`,
-    )
+    );
+  }
+  const lines: string[] = [];
+  // Validate all rules before reverting any file, retaining the record on refusal.
+  for (const file of record.files) {
+    if (file.format !== "rules") continue;
+    const loaded = codecFor("rules", record.host).load(file.file);
+    if (loaded.parseError) throw new Error(`${file.file}: ${loaded.parseError}`);
   }
-  const lines: string[] = []
   for (const file of [...record.files].reverse()) {
-    lines.push(...revertRecordedFile(file, record.host, { label: "", whole: true }))
+    lines.push(...revertRecordedFile(file, record.host, { label: "", whole: true }));
   }
-  deleteRecord(input)
-  pruneEmptyDir(stateDir(input, input.scope))
-  lines.push(`removed install record (${input.host}, ${input.scope})`)
-  return lines
+  deleteRecord(input);
+  releaseFileOwnership(input, record.files);
+  pruneEmptyDir(stateDir(input, input.scope));
+  lines.push(`removed install record (${input.host}, ${input.scope})`);
+  return lines;
 }

package/src/mcp/auth.ts

@@ -1,13 +1,12 @@
-import { API_KEY_ENV } from "../core/constants"
-import { apiKeyFromEnv } from "../core/auth"
-import type { Env } from "./config"
+import { apiKeyFromEnv } from "../core/auth";
+import { API_KEY_ENV } from "../core/constants";
+import type { Env } from "../core/env";
 
-export const MISSING_API_KEY_MESSAGE =
-  `DeepSeek API key not found. Set ${API_KEY_ENV} in the MCP server's env configuration.`
+export const MISSING_API_KEY_MESSAGE = `DeepSeek API key not found. Set ${API_KEY_ENV} in the MCP server's env configuration.`;
 
 /** Resolves the API key from the environment or fails with shared guidance. */
 export function requireApiKey(env: Env): string {
-  const apiKey = apiKeyFromEnv(env)
-  if (!apiKey) throw new Error(MISSING_API_KEY_MESSAGE)
-  return apiKey
+  const apiKey = apiKeyFromEnv(env);
+  if (!apiKey) throw new Error(MISSING_API_KEY_MESSAGE);
+  return apiKey;
 }

package/src/mcp/cli.ts

@@ -1,39 +1,57 @@
 #!/usr/bin/env node
-import { serveStdio } from "@modelcontextprotocol/server/stdio"
-import { apiKeyFromEnv } from "../core/auth"
-import { MISSING_API_KEY_MESSAGE } from "./auth"
-import { resolveEnvOptions } from "./config"
-import { createDeepSeekServer, servePrecheck } from "./server"
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { apiKeyFromEnv } from "../core/auth";
+import { resolveEnvOptions } from "../core/env";
+import { MISSING_API_KEY_MESSAGE } from "./auth";
+import { isJsonReplacingClient } from "./client";
+import { createDeepSeekServer, servePrecheck } from "./server";
 
 // Installer subcommands run before the server path; MCP clients spawn this bin
 // with no arguments, so the default stdio behavior is unchanged.
-const subcommand = process.argv[2]
+const subcommand = process.argv[2];
 if (subcommand === "init" || subcommand === "uninstall" || subcommand === "list") {
-  const { runInstallerCli } = await import("../installer/cli")
-  process.exit(await runInstallerCli(process.argv.slice(2)))
+  const { runInstallerCli } = await import("../installer/cli");
+  process.exit(await runInstallerCli(process.argv.slice(2)));
 }
 
 // stdout is the JSON-RPC channel; all diagnostics must go to stderr.
-const env = process.env
+const env = process.env;
 if (!apiKeyFromEnv(env)) {
-  console.error(MISSING_API_KEY_MESSAGE)
-  process.exit(1)
+  console.error(MISSING_API_KEY_MESSAGE);
+  process.exit(1);
 }
 
-const config = resolveEnvOptions(env)
-const precheck = servePrecheck(config)
+const config = resolveEnvOptions(env);
+const precheck = servePrecheck(config);
 if (precheck) {
-  console.error(precheck)
-  process.exit(1)
+  console.error(precheck);
+  process.exit(1);
 }
-const handle = serveStdio(() => createDeepSeekServer(config, env))
+const handle = serveStdio(() => {
+  const server = createDeepSeekServer(config, env);
+  // Fires after the handshake-era initialize exchange (the stateless era opens
+  // differently and simply never logs). One stderr line so a human run shows
+  // which client connected and whether text-only shaping kicked in; if a host
+  // renames its clientInfo, this line is where the regression becomes visible.
+  server.server.oninitialized = () => {
+    const info = server.server.getClientVersion();
+    if (info === undefined) return;
+    console.error(
+      `mcp client: ${info.name} ${info.version ?? "unknown"} — ` +
+        (isJsonReplacingClient(info.name)
+          ? "text-only results (this client replaces content with serialized structuredContent)"
+          : "text + structuredContent results"),
+    );
+  };
+  return server;
+});
 const tools = [
   config.search.enabled ? `search (max ${config.search.maxResults} results)` : null,
   config.fetch.enabled ? `fetch (max ${config.fetch.maxChars} chars)` : null,
 ]
   .filter(Boolean)
-  .join(", ")
-console.error(`deepseek-web-retrieval MCP server on stdio (${tools})`)
+  .join(", ");
+console.error(`deepseek-web-retrieval MCP server on stdio (${tools})`);
 
-process.on("SIGINT", () => void handle.close())
-process.on("SIGTERM", () => void handle.close())
+process.on("SIGINT", () => void handle.close());
+process.on("SIGTERM", () => void handle.close());

package/src/mcp/client.ts

@@ -0,0 +1,35 @@
+import type { McpServer, ServerContext } from "@modelcontextprotocol/server";
+import { CLIENT_INFO_META_KEY } from "@modelcontextprotocol/server";
+
+/**
+ * Clients that discard a result's content blocks and hand the model the serialized
+ * `structuredContent` JSON instead. For these the server omits `structuredContent`
+ * so the model reads the text blocks. The declared names are research facts —
+ * docs/agents/codex.md records where codex-mcp-client comes from.
+ */
+const JSON_REPLACING_CLIENT_NAMES = new Set(["codex-mcp-client"]);
+
+/**
+ * The connected client's declared name. The per-request envelope comes first (the
+ * 2026-07-28 era, where clientInfo is a SHOULD, not a MUST); the initialize-scoped
+ * accessor covers the handshake era and is backfilled per request on modern
+ * connections, so it works as the fallback for both.
+ */
+export function clientNameOf(server: McpServer, ctx: ServerContext): string | undefined {
+  const envelope = ctx.mcpReq.envelope as Record<string, unknown> | undefined;
+  const name = envelope?.[CLIENT_INFO_META_KEY];
+  if (typeof name === "object" && name !== null && "name" in name && typeof name.name === "string") {
+    return name.name;
+  }
+  return server.server.getClientVersion()?.name;
+}
+
+/** True when a client declaring this name would replace text content with serialized JSON. */
+export function isJsonReplacingClient(name: string | undefined): boolean {
+  return name !== undefined && JSON_REPLACING_CLIENT_NAMES.has(name);
+}
+
+/** True when the connected client would replace text content with serialized JSON. */
+export function omitStructuredContent(server: McpServer, ctx: ServerContext): boolean {
+  return isJsonReplacingClient(clientNameOf(server, ctx));
+}