@arcfold/dsh 0.0.0-stage → 0.4.0

package/src/deepseek-receipt.mjs

@@ -0,0 +1,97 @@
+import { createParser } from 'eventsource-parser';
+import { DomainError, jsonClone } from './store.mjs';
+
+const invalid = () => new DomainError('invalid_provider_receipt', 'The original Messages receipt is incomplete or inconsistent.', 409);
+const count = value => Number.isSafeInteger(value) && value >= 0;
+
+/** Billing only. Official DSH remains the sole translator of answer/tool content. */
+export function messagesUsage(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw invalid();
+  for (const key of ['input_tokens', 'output_tokens', 'cache_read_input_tokens', 'cache_creation_input_tokens'])
+    if (!count(raw[key])) throw invalid();
+  // There is no verified tariff for cache creation in this supported route.
+  if (raw.cache_creation_input_tokens !== 0) throw invalid();
+  const promptTokens = raw.input_tokens + raw.cache_read_input_tokens;
+  if (!count(promptTokens)) throw invalid();
+  return { promptTokens, completionTokens: raw.output_tokens, cachedTokens: raw.cache_read_input_tokens };
+}
+
+export class MessagesReceipt {
+  constructor() {
+    this.decoder = new TextDecoder('utf-8', { fatal: true });
+    this.started = false; this.stopped = false; this.finalUsage = null;
+    this.stopReason = null; this.messageId = null; this.model = null;
+    this.lineParts = []; this.skipLf = false;
+    this.parser = createParser({
+      onError: () => { throw invalid(); },
+      onEvent: event => this.event(event),
+    });
+  }
+
+  event(event) {
+    let value;
+    try { value = JSON.parse(event.data); } catch { throw invalid(); }
+    if (!value || typeof value !== 'object' || typeof value.type !== 'string' ||
+        event.event && event.event !== value.type || this.stopped) throw invalid();
+    if (value.type === 'ping') return;
+    if (value.type === 'message_start') {
+      if (this.started || typeof value.message?.id !== 'string' || !value.message.id ||
+          typeof value.message?.model !== 'string' || !value.message.model) throw invalid();
+      this.started = true; this.messageId = value.message.id; this.model = value.message.model;
+      return;
+    }
+    if (!this.started) throw invalid();
+    if (value.type === 'message_delta') {
+      if (this.stopReason !== null) throw invalid();
+      if (value.delta?.stop_reason != null) {
+        if (typeof value.delta.stop_reason !== 'string' || !value.delta.stop_reason) throw invalid();
+        messagesUsage(value.usage);
+        this.finalUsage = jsonClone(value.usage); this.stopReason = value.delta.stop_reason;
+      }
+      return;
+    }
+    if (value.type === 'message_stop') {
+      if (!this.finalUsage || this.stopReason === null) throw invalid();
+      this.stopped = true; return;
+    }
+    if (!['content_block_start', 'content_block_delta', 'content_block_stop'].includes(value.type)) throw invalid();
+    if (this.stopReason !== null) throw invalid();
+  }
+
+  // Feed complete lines to the official SSE framer so its terminal callback
+  // identifies the exact boundary, even when a network chunk has extra bytes.
+  // After that boundary our supported protocol permits whitespace only.
+  feedText(fragment) {
+    if (this.stopped) {
+      if (!/^[ \t\r\n]*$/.test(fragment)) throw invalid();
+      return;
+    }
+    let start = 0;
+    for (let index = 0; index < fragment.length; index++) {
+      const character = fragment[index];
+      if (this.skipLf) {
+        this.skipLf = false;
+        if (character === '\n') { start = index + 1; continue; }
+      }
+      if (character !== '\r' && character !== '\n') continue;
+      this.lineParts.push(fragment.slice(start, index));
+      const line = this.lineParts.join(''); this.lineParts = [];
+      this.parser.feed(line + '\n');
+      start = index + 1; this.skipLf = character === '\r';
+      if (this.stopped) {
+        if (!/^[ \t\r\n]*$/.test(fragment.slice(start))) throw invalid();
+        return;
+      }
+    }
+    if (start < fragment.length) this.lineParts.push(fragment.slice(start));
+  }
+
+  push(bytes) { this.feedText(this.decoder.decode(bytes, { stream: true })); }
+
+  finish() {
+    this.feedText(this.decoder.decode());
+    if (!this.started || !this.stopped || !this.finalUsage) throw invalid();
+    return { messageId: this.messageId, model: this.model, stopReason: this.stopReason,
+      rawUsage: this.finalUsage, usage: messagesUsage(this.finalUsage) };
+  }
+}

package/src/deepseek-transport.mjs

@@ -0,0 +1,97 @@
+import { MeteredTransport, fail, object, positive, text, keys, hash } from './metered-transport.mjs';
+import { MessagesReceipt } from './deepseek-receipt.mjs';
+const OFFICIAL = 'https://api.deepseek.com/anthropic/v1/messages';
+const VERSION = 'arcfold-messages-transport-v1';
+function wireBlocks(blocks, nested = false) {
+  if (!Array.isArray(blocks)) throw fail('unsupported_model_content', 'Messages content must be an array.');
+  for (const block of blocks) {
+    if (block?.type === 'text') {
+      keys(block, ['type', 'text']);
+      if (!text(block.text)) throw fail('unsupported_model_content', 'Text content is invalid.');
+    } else if (!nested && block?.type === 'thinking') {
+      keys(block, ['type', 'thinking', 'signature']);
+      if (!text(block.thinking) || block.signature !== undefined && !text(block.signature))
+        throw fail('unsupported_model_content', 'Thinking content is invalid.');
+    } else if (!nested && block?.type === 'tool_use') {
+      keys(block, ['type', 'id', 'name', 'input']);
+      if (!text(block.id) || !text(block.name) || !object(block.input))
+        throw fail('unsupported_model_content', 'Client tool input is invalid.');
+    } else if (!nested && block?.type === 'tool_result') {
+      keys(block, ['type', 'tool_use_id', 'content', 'is_error']);
+      if (!text(block.tool_use_id) || block.is_error !== undefined && typeof block.is_error !== 'boolean')
+        throw fail('unsupported_model_content', 'Client tool result is invalid.');
+      wireBlocks(block.content, true);
+    } else if (!nested && ['tool_addition', 'tool_removal'].includes(block?.type)) {
+      keys(block, ['type', 'tool']); keys(block.tool, ['type', 'name']);
+      if (block.tool.type !== 'tool_reference' || !text(block.tool.name))
+        throw fail('unsupported_model_content', 'Client tool update is invalid.');
+    } else throw fail('unsupported_model_content', 'Images, uploads and server tools are not supported.');
+  }
+}
+
+const protocol = Object.freeze({
+  version: VERSION, endpoint: OFFICIAL,
+  validateEndpoint(endpoint, allowLocalTestEndpoint) {
+    const target = new URL(endpoint);
+    const local = allowLocalTestEndpoint === true && target.protocol === 'http:' &&
+      target.hostname === '127.0.0.1' && target.port && target.pathname === '/anthropic/v1/messages';
+    if (endpoint !== OFFICIAL && !local || target.username || target.password || target.search || target.hash)
+      throw fail('invalid_transport_configuration', 'Only the fixed official Messages endpoint is supported.');
+  },
+  validatePolicies(modelPolicies) {
+    for (const policy of Object.values(modelPolicies)) {
+      if (!object(policy) || !positive(policy.contextWindow) || !positive(policy.maxOutputTokens) ||
+          !object(policy.prices) || !text(policy.priceVersion) || !policy.priceVersion ||
+          !Array.isArray(policy.reasoningEfforts) || !policy.reasoningEfforts.length ||
+          policy.reasoningEfforts.some(effort => !['off', 'low', 'high', 'max'].includes(effort)) ||
+          policy.requestMaxTokens !== undefined && (!positive(policy.requestMaxTokens) || policy.requestMaxTokens > policy.maxOutputTokens))
+        throw fail('invalid_transport_configuration', 'Model accounting bounds must be explicitly frozen.');
+    }
+  },
+  createReceipt: () => new MessagesReceipt(),
+  reservationSpec: fixed => ({ maxOutputTokens: fixed.policy.maxOutputTokens,
+    inputTokenCeiling: fixed.policy.contextWindow, prices: fixed.policy.prices }),
+});
+export class DeepSeekTransport extends MeteredTransport {
+  constructor(options = {}) { super({ ...options, protocol }); }
+  validateWire(fixed, url, init) {
+    if (url !== this.endpoint || init?.method !== 'POST' || init.redirect !== 'error' || typeof init.body !== 'string')
+      throw fail('invalid_wire_request', 'Only the frozen single Messages POST is permitted.');
+    if (Buffer.byteLength(init.body) > this.maxRequestBytes) throw fail('request_too_large', 'Request evidence capacity exceeded.');
+    let body;
+    try { body = JSON.parse(init.body); } catch { throw fail('invalid_wire_request', 'Messages body must be JSON.'); }
+    keys(body, ['model', 'stream', 'max_tokens', 'messages', 'system', 'thinking', 'output_config', 'temperature', 'stop_sequences', 'tools']);
+    if (body.model !== fixed.model || body.stream !== true || body.max_tokens !== fixed.maxTokens ||
+        !Array.isArray(body.messages) || !body.messages.length || body.system !== undefined && !text(body.system))
+      throw fail('wire_configuration_changed', 'Serialized route and token limit differ from the frozen request.');
+    keys(body.thinking, ['type']);
+    if (body.thinking.type !== (fixed.reasoningEffort === 'off' ? 'disabled' : 'enabled'))
+      throw fail('wire_configuration_changed', 'Serialized reasoning differs from the frozen request.');
+    if (fixed.reasoningEffort === 'off') {
+      if (body.output_config !== undefined) throw fail('wire_configuration_changed', 'Disabled thinking cannot add an effort.');
+    } else {
+      keys(body.output_config, ['effort']);
+      if (body.output_config.effort !== fixed.reasoningEffort) throw fail('wire_configuration_changed', 'Serialized effort changed.');
+    }
+    for (const message of body.messages) {
+      keys(message, ['role', 'content']);
+      if (!['user', 'assistant', 'system'].includes(message.role)) throw fail('unsupported_model_content', 'Unsupported Messages role.');
+      wireBlocks(message.content);
+    }
+    if (body.tools !== undefined) {
+      if (!Array.isArray(body.tools)) throw fail('unsupported_model_content', 'Client tools must be an array.');
+      for (const tool of body.tools) {
+        keys(tool, ['name', 'description', 'input_schema', 'defer_loading']);
+        if (!text(tool.name) || !text(tool.description) || !object(tool.input_schema) ||
+            tool.defer_loading !== undefined && tool.defer_loading !== true)
+          throw fail('unsupported_model_content', 'Only client tools are allowed.');
+      }
+    }
+    const headers = new Headers(init.headers);
+    if (!headers.get('authorization') && !headers.get('x-api-key')) throw fail('missing_provider_auth', 'Provider authentication is required.');
+    if (headers.has('host') && headers.get('host') !== new URL(url).host)
+      throw fail('invalid_wire_request', 'The HTTP host cannot override the fixed endpoint.');
+    return { body, headers: Object.fromEntries(headers), serialized: init.body, bodyHash: hash(init.body) };
+  }
+
+}

package/src/desktop/adapter.mjs

@@ -0,0 +1,16 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+
+// An exact copy of the audited upstream package with the existing transport
+// seam applied. This is owned by Arcfold; it never patches Desktop's packages.
+const url = new URL('./vendor/deepseek-0.2.2-rc.1.mjs', import.meta.url);
+const expected = 'fc27ceacbed59c8d32100f3aa41cf79e1acab403ac0bc12b0e7f807a6274c752';
+export async function loadDesktopDeepSeekAdapter() {
+  const actual = createHash('sha256').update(readFileSync(url)).digest('hex');
+  if (actual !== expected) throw new Error('The private Desktop DeepSeek adapter does not match its audited source');
+  const adapter = await import(url.href);
+  if (adapter.registerDeepSeekProvider?.transportSeam !== 'deepseek-messages-create-transport-v1' ||
+      typeof adapter.DeepSeekAdapter !== 'function' || typeof adapter.catalogModelInfo !== 'function')
+    throw new Error('The private Desktop DeepSeek adapter lacks the required transport interface');
+  return adapter;
+}

package/src/desktop/bootstrap.mjs

@@ -0,0 +1,84 @@
+import { readFileSync, realpathSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isDeepStrictEqual } from 'node:util';
+import { resolveDshHome } from '@deepseek-ai/dsh-home-paths';
+import { isBundledDesktopPython, prepareBundledDesktopPython } from './python-runtime.mjs';
+import { createDesktopSetup } from './setup-service.mjs';
+
+export const name = 'arcfold-desktop-bootstrap';
+export const inject = ['loader'];
+const same = (a, b) => isDeepStrictEqual(a, b, true);
+
+export async function activateDesktop(ctx, result, { home, previousPython } = {}) {
+  const all = [...ctx.loader.entries()];
+  const one = id => {
+    const matches = all.filter(row => row.options.id === id);
+    if (matches.length !== 1) throw new Error('无法确认 Desktop 配置位置：' + id);
+    return matches[0];
+  };
+  const business = one('arcfold-business'), originalProvider = one('arcfold-metered-provider');
+  const businessConfig = business.options.config ?? {};
+  const intendedConfig = { goalTreeV3: result.tree };
+  const previous = businessConfig.goalTreeV3?.tokenCounter?.python;
+  const managedPrevious = typeof previous === 'string' && (previous === previousPython || isBundledDesktopPython(home, previous));
+  const previousConfig = { goalTreeV3: { ...result.tree, tokenCounter: { ...result.tree.tokenCounter, python: previous } } };
+  if (Object.keys(businessConfig).length && !same(businessConfig, intendedConfig) &&
+      !(managedPrevious && same(businessConfig, previousConfig)))
+    throw new Error('Arcfold 已有不同的运行设置，不能自动覆盖。');
+  if (originalProvider.options.disabled !== true && Object.keys(originalProvider.options.config ?? {}).length)
+    throw new Error('Arcfold 已有不同的模型连接设置，不能自动覆盖。');
+  const desktopPatch = result.patches.find(row => row.insert).insert[0];
+  const existing = all.filter(row => row.options.id === desktopPatch.id);
+  if (existing.length > 1 || existing.length && (!same(existing[0].options.config, desktopPatch.config) || existing[0].options.name !== desktopPatch.name))
+    throw new Error('Desktop 模型连接与保存的设置不一致。');
+  // Each native Loader operation persists through its own owning config tree.
+  // No arbitrary profile file is replaced. A partial failure is reported and
+  // the saved initialization remains available for an exact retry.
+  if (originalProvider.options.disabled !== true)
+    await originalProvider.parent.tree.update(originalProvider.options.id, { disabled: true });
+  if (!same(businessConfig, intendedConfig))
+    await business.parent.tree.update(business.options.id, { config: intendedConfig });
+  if (!existing.length) {
+    const group = business.parent === business.parent.tree.root ? null : business.parent.ctx.fiber.entry?.id ?? null;
+    await business.parent.tree.create(desktopPatch, group);
+  }
+  const defaultModel = one('agent-default-model'), currentDefault = defaultModel.options.config ?? {};
+  const unset = value => value === undefined || value === '' || value && typeof value === 'object' && typeof value.__jsExpr === 'string';
+  if (unset(currentDefault.provider) && unset(currentDefault.model)) {
+    const main = result.tree.models.main;
+    await defaultModel.parent.tree.update(defaultModel.options.id, { config: { provider: main.provider, model: main.model, reasoningEffort: main.reasoningEffort } });
+  }
+  await ctx.loader.await();
+  // Tree UI registration is reactive and can follow the business plugin's
+  // own startup. Do not report ready until the browser-facing service exists.
+  const deadline = Date.now() + 5000;
+  while (!ctx.get('arcfoldTreeWeb') && Date.now() < deadline)
+    await new Promise(resolve => setTimeout(resolve, 25));
+  if (!ctx.get('arcfoldTreeRuntime') || !ctx.get('arcfoldTreeV3') || !ctx.get('arcfoldTreeWeb') || !ctx.get('arcfoldDeepSeekTransport'))
+    throw new Error('Desktop 未能启动 Arcfold，请保留当前设置并检查错误。');
+}
+
+export function apply(ctx) {
+  const isDesktop = Boolean(process.versions.electron && process.argv.some(value => value.includes('dsh-desktop-host')));
+  if (!isDesktop) {
+    ctx.provide('arcfoldDesktopSetup', Object.freeze({ status: () => ({ state: 'not_desktop' }) }));
+    return;
+  }
+  const packageRoot = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+  let setup;
+  try {
+    const home = realpathSync(resolveDshHome());
+    const policy = JSON.parse(readFileSync(join(packageRoot, 'runtime/initial-policy.json'), 'utf8'));
+    setup = createDesktopSetup({ home, installationFile: join(packageRoot, 'package.json'), policy,
+      preparePython: () => prepareBundledDesktopPython(packageRoot, home),
+      activate: (result, previousPython) => activateDesktop(ctx.root, result, { home, previousPython }) });
+  } catch (error) {
+    setup = Object.freeze({ status: () => ({ state: 'unavailable', activationError: error.message }) });
+  }
+  ctx.provide('arcfoldDesktopSetup', setup);
+  if (setup.status().state === 'configured') {
+    // Do not wait for the Loader from inside its own initialization task.
+    setImmediate(() => { void ctx.loader.await().then(() => setup.resume()); });
+  }
+}

package/src/desktop/configuration.mjs

@@ -0,0 +1,117 @@
+import { dirname, join, resolve, sep } from 'node:path';
+import { accessSync, closeSync, constants, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { canonicalRuntimePath, runtimeProviderDefaults, runtimeTransport, validateRuntimeConfig } from '../runtime-config.mjs';
+import { initializeOwnedWebBudget, preflightWebBudget } from '../web-budget-recovery.mjs';
+import { canonicalJson } from '../store.mjs';
+
+const roles = ['main', 'attribution', 'learning', 'consolidation', 'verification', 'improvement', 'script_writer'];
+const disjoint = (a, b) => a !== b && !a.startsWith(b + sep) && !b.startsWith(a + sep);
+const assert = (condition, message) => { if (!condition) throw new Error(message); };
+
+/** Project an already authorized Desktop installation into the native host.
+ * This function is read-only. In particular it does not create a ledger,
+ * adopt another installation's files, obtain credentials or authorize spending. */
+function projectDesktopConfiguration({ local, runtimeRoot, python, userId, models }, checkLedger) {
+  const config = validateRuntimeConfig(local);
+  const data = canonicalRuntimePath(config.dataRoot), workspace = canonicalRuntimePath(config.workspace);
+  const workers = canonicalRuntimePath(runtimeRoot, 'runtimeRoot');
+  const interpreter = realpathSync(canonicalRuntimePath(python, 'python'));
+  assert(lstatSync(interpreter).isFile(), 'Desktop token counter needs an executable interpreter');
+  accessSync(interpreter, constants.X_OK);
+  const install = dirname(canonicalRuntimePath(config.installationFile));
+  assert(lstatSync(workspace).isDirectory(), 'Desktop workspace must already exist');
+  assert(disjoint(data, workspace) && disjoint(workers, data) && disjoint(workers, workspace) &&
+    disjoint(data, install) && disjoint(workers, install), 'Desktop data, workspace, processes and installed code must be separate');
+  assert(typeof userId === 'string' && userId.trim().length > 0 && userId.length <= 256, 'An explicit Desktop user identity is required');
+  const transport = runtimeTransport(config), route = transport.routes['deepseek-official'];
+  assert(route?.mode === 'web-only' && route.scope === 'web-unlimited' && route.webAuthorization && route.network?.mode === 'direct',
+    'Desktop requires its own explicitly authorized, direct DeepSeek accounting route');
+  const evidence = canonicalRuntimePath(transport.artifactDirectory), ledgerPath = canonicalRuntimePath(route.ledgerPath);
+  assert(!disjoint(data, evidence) && evidence !== data && evidence.startsWith(data + sep), 'Desktop request evidence must be inside its data directory');
+  if (checkLedger) preflightWebBudget({ artifactDirectory: evidence, ledgerPath });
+  assert(models && typeof models === 'object' && Object.keys(models).length === roles.length && roles.every(role => Object.hasOwn(models, role)),
+    'All seven 4397 model roles must be specified explicitly');
+  for (const role of roles) {
+    const value = models[role], policy = route.modelPolicies[value?.model];
+    assert(value && Object.keys(value).every(k => ['provider', 'model', 'modelVersion', 'reasoningEffort', 'maxTokens'].includes(k)) &&
+      value.provider === 'deepseek-official' && policy && typeof value.modelVersion === 'string' && value.modelVersion.length > 0 &&
+      policy.reasoningEfforts.includes(value.reasoningEffort) && Number.isSafeInteger(value.maxTokens) && value.maxTokens > 0 &&
+      value.maxTokens <= (policy.requestMaxTokens ?? policy.maxOutputTokens), `Invalid explicit Desktop model role: ${role}`);
+  }
+  const main = models.main;
+  assert(['provider', 'model', 'reasoningEffort', 'maxTokens'].every(k => config.main?.[k] === main[k]), 'Desktop main model must match the authorized configuration');
+  const defaults = runtimeProviderDefaults(config, 'deepseek-official');
+  assert(defaults.available, 'Desktop provider defaults do not fit the accounting policies');
+  const tree = { enabled: true, adapter: 'desktop-private-v1', followConversationModel: true, workspace, privateRoot: data, runtimeRoot: workers,
+    treeFilename: join(data, 'tree.sqlite'), userId, models: structuredClone(models), stage: 'desktop', tokenCounter: { python: interpreter },
+    budget: { mode: 'web-only', scope: 'web-unlimited', webAuthorization: structuredClone(route.webAuthorization),
+      ledgerPath, artifactDirectory: evidence, modelPolicies: structuredClone(route.modelPolicies), endpoint: route.endpoint,
+      timeoutMs: route.timeoutMs, ...(route.allowLocalTestEndpoint === true ? { allowLocalTestEndpoint: true } : {}) } };
+  // The caller supplies the independently verified offline interpreter. No
+  // hard-coded developer machine path is substituted here.
+  return { tree, patches: [
+    { id: 'arcfold-business', config: { goalTreeV3: tree } },
+    { id: 'arcfold-metered-provider', disabled: true },
+    { insert: [{ id: 'arcfold-desktop-metered-provider', name: '@arcfold/dsh/desktop-deepseek',
+      config: { apiKeyRef: route.apiKeyRef, maxTokens: defaults.maxTokens, reasoningEffort: defaults.reasoningEffort } }] },
+    { id: 'agent-default-model', config: { provider: main.provider, model: main.model, reasoningEffort: main.reasoningEffort } },
+    { id: 'working-directory', config: { defaultDirectory: workspace } },
+  ] };
+}
+
+export function desktopConfiguration(options) { return projectDesktopConfiguration(options, true); }
+
+const hash = value => createHash('sha256').update(value).digest('hex');
+function writePrivateNew(path, value) {
+  const fd = openSync(path, 'wx', 0o600);
+  try { writeFileSync(fd, value); fsyncSync(fd); } finally { closeSync(fd); }
+  const directory = openSync(dirname(path), 'r');
+  try { fsyncSync(directory); } finally { closeSync(directory); }
+}
+function privateRegular(path) {
+  const st = lstatSync(path);
+  assert(st.isFile() && !st.isSymbolicLink() && st.nlink === 1 && st.uid === process.getuid() && !(st.mode & 0o077), 'Desktop initialization receipt must remain private and unmodified');
+  return st;
+}
+
+/** Explicit first use for a new, separate Desktop namespace. A completed
+ * setup is idempotent only for the exact same inputs and owned ledger. An
+ * interrupted setup is retained and refused for manual reconciliation. */
+export async function initializeDesktop(options, consent, runtimePython = options.python) {
+  assert(consent?.confirmed === true && Object.keys(consent).length === 1, 'Explicit Desktop model-spending confirmation is required');
+  // Only this installation's interpreter changes with a plugin upgrade. The
+  // original settings still bind the receipt and the accounting authorization.
+  const runtimeOptions = { ...options, python: runtimePython };
+  const projection = projectDesktopConfiguration(runtimeOptions, false), tree = projection.tree;
+  const root = tree.privateRoot, evidence = tree.budget.artifactDirectory, ledger = tree.budget.ledgerPath;
+  assert(evidence === join(root, 'requests') && ledger === join(evidence, 'deepseek-web.sqlite'), 'First use requires the fixed independent Desktop evidence directory');
+  assert(resolve(options.local.dataRoot) === root, 'Desktop data directory cannot be an alias');
+  const configPath = join(root, 'desktop-configuration.json'), intentPath = join(root, 'desktop-initialization.json'), completedPath = join(root, 'desktop-initialization-completed.json');
+  const bytes = canonicalJson({ schema: 'arcfold-desktop-configuration-v1', options }) + '\n', inputHash = hash(bytes);
+  if (existsSync(root)) {
+    const rootStat = lstatSync(root);
+    assert(rootStat.isDirectory() && !rootStat.isSymbolicLink() && rootStat.uid === process.getuid() && !(rootStat.mode & 0o077), 'Desktop data directory must remain private and owned');
+    assert(existsSync(completedPath), 'Desktop initialization is interrupted or the directory is not owned; reconcile before retrying');
+    privateRegular(intentPath); privateRegular(configPath); privateRegular(completedPath);
+    const intent = JSON.parse(readFileSync(intentPath, 'utf8')), completed = JSON.parse(readFileSync(completedPath, 'utf8'));
+    assert(intent.schema === 'arcfold-desktop-initialization-v1' && completed.schema === 'arcfold-desktop-initialization-completed-v1', 'Unsupported Desktop initialization receipt');
+    assert(intent.inputHash === inputHash && completed.inputHash === inputHash && hash(readFileSync(configPath)) === inputHash,
+      'Desktop initialization retry requires the same original configuration');
+    const st = privateRegular(ledger);
+    assert(st.dev === completed.ledger.dev && st.ino === completed.ledger.ino, 'Desktop accounting ledger has been replaced');
+    preflightWebBudget({ artifactDirectory: evidence, ledgerPath: ledger });
+    return { created: false, configPath, ...projection };
+  }
+  assert(runtimePython === options.python, 'Fresh Desktop initialization must record its runtime');
+  // mkdir is the ownership claim; it fails instead of adopting any existing
+  // directory. Completion is published only after the independent ledger.
+  mkdirSync(root, { mode: 0o700 });
+  writePrivateNew(intentPath, JSON.stringify({ schema: 'arcfold-desktop-initialization-v1', inputHash }) + '\n');
+  writePrivateNew(configPath, bytes);
+  const account = await initializeOwnedWebBudget({ artifactDirectory: evidence, ledgerPath: ledger, webAuthorization: tree.budget.webAuthorization });
+  assert(account.created && account.ledgerPath === ledger, 'First use cannot adopt an existing accounting ledger');
+  const st = privateRegular(ledger);
+  writePrivateNew(completedPath, JSON.stringify({ schema: 'arcfold-desktop-initialization-completed-v1', inputHash, ledger: { dev: st.dev, ino: st.ino } }) + '\n');
+  return { created: true, configPath, ...desktopConfiguration(runtimeOptions) };
+}

package/src/desktop/provider.mjs

@@ -0,0 +1,46 @@
+import { assertUsableApiKey, LlmError } from '@deepseek-ai/dsh-llm';
+import { resolveAdapterOptions } from '@deepseek-ai/dsh-llm-deepseek-api-key';
+import { launchEnvironmentOf } from '@deepseek-ai/dsh-launch-environment';
+import { loadDesktopDeepSeekAdapter } from './adapter.mjs';
+
+export const name = 'arcfold-desktop-deepseek-provider';
+export const inject = ['llm', 'credentials', 'arcfoldDeepSeekTransport'];
+export async function apply(ctx, config = {}) {
+  const { catalogModelInfo, registerDeepSeekProvider } = await loadDesktopDeepSeekAdapter();
+  const service = ctx.arcfoldDeepSeekTransport;
+  const { provider, endpoint, modelPolicies } = service.configuration;
+  if (provider !== 'deepseek-official' || !Object.keys(modelPolicies).length)
+    throw new Error('An explicit metered DeepSeek model catalog is required');
+  if (typeof config.apiKeyRef !== 'string' || !config.apiKeyRef ||
+      !Number.isSafeInteger(config.maxTokens) || config.maxTokens < 1 ||
+      !['off', 'low', 'high', 'max'].includes(config.reasoningEffort))
+    throw new Error('A credential reference, output limit and reasoning effort are required');
+  const models = Object.entries(modelPolicies).map(([id, policy]) => {
+    if (config.maxTokens > (policy.requestMaxTokens ?? policy.maxOutputTokens) ||
+        !policy.reasoningEfforts.includes(config.reasoningEffort))
+      throw new Error('Provider defaults exceed a frozen model accounting policy');
+    return { id, name: id, inputModalities: ['text'], contextWindow: policy.contextWindow,
+      maxTokens: config.maxTokens };
+  });
+  // This deployment generation is fixed. A different route/catalog requires a
+  // plugin reload; the user-selected model remains an ordinary DSH option.
+  const connection = resolveAdapterOptions({
+    baseURL: endpoint.slice(0, -'/v1/messages'.length), apiKeyEnv: config.apiKeyRef,
+    models, maxTokens: config.maxTokens, reasoningEffort: config.reasoningEffort,
+    retryPolicy: { mode: 'normal', maxRetries: 0 },
+  }, launchEnvironmentOf(ctx));
+  for (const model of connection.models) Object.freeze(model);
+  Object.freeze(connection.models); Object.freeze(connection);
+  registerDeepSeekProvider(ctx, provider, {
+    providerName: 'DeepSeek', options: () => connection, connect: async () => connection,
+    createTransport: options => service.createTransport(options),
+    // Resolve secrets only inside the official credential service. They remain
+    // in memory for the request and never enter Arcfold config or evidence.
+    resolveAuth: async current => {
+      const credential = await ctx.credentials.resolve(current.apiKeyEnv);
+      if (!credential) throw new LlmError('Configure the DeepSeek credential in the host Models page', 'MISSING_CREDENTIAL');
+      return { headers: { 'x-api-key': assertUsableApiKey(credential.value, name, current.apiKeyEnv) } };
+    },
+    discoverModels: async route => connection.models.map(model => catalogModelInfo(route, model)),
+  });
+}

package/src/desktop/python-runtime.mjs

@@ -0,0 +1,105 @@
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { accessSync, constants, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+export const desktopPython = Object.freeze({
+  path: 'runtime/desktop-python.tar.gz',
+  url: 'https://github.com/astral-sh/python-build-standalone/releases/download/20260901/cpython-3.12.14%2B20260901-aarch64-apple-darwin-install_only_stripped.tar.gz',
+  bytes: 24981445,
+  sha256: '81a359f1cfadd4da11766534c5913791cea55f26e1bb902cacd2a531bb1e4b2b',
+  // runtimeDigest of the pinned archive freshly unpacked by /usr/bin/tar.
+  treeSha256: '59df7f39ee074442e75a776aacf8810c51b41a64ef5d37ad5e90da39a2a808d7',
+});
+
+const executable = 'python/bin/python3.12';
+const cache = home => join(home, 'arcfold-desktop-counter');
+
+export function readDesktopPythonArchive(file) {
+  const stat = lstatSync(file);
+  if (!stat.isFile() || stat.size !== desktopPython.bytes)
+    throw new Error('Arcfold 文本计数文件不完整，请重新安装此版本。');
+  const bytes = readFileSync(file);
+  if (createHash('sha256').update(bytes).digest('hex') !== desktopPython.sha256)
+    throw new Error('Arcfold 文本计数文件校验失败，请重新安装此版本。');
+  return bytes;
+}
+
+export function isBundledDesktopPython(home, path) {
+  return typeof home === 'string' && typeof path === 'string' &&
+    /^[a-f0-9]{64}\/python\/bin\/python3\.\d+$/u.test(relative(cache(home), path));
+}
+
+function requirePrivateDirectory(path) {
+  const stat = lstatSync(path);
+  if (!stat.isDirectory() || stat.uid !== process.getuid() || (stat.mode & 0o077))
+    throw new Error('Arcfold 文本计数目录的所有者或权限不符合要求。');
+}
+
+function runtimeDigest(root) {
+  const hash = createHash('sha256');
+  function visit(directory, prefix) {
+    for (const name of readdirSync(directory).sort()) {
+      const path = join(directory, name);
+      const entry = prefix + name;
+      const stat = lstatSync(path);
+      let record;
+      if (stat.isDirectory()) {
+        record = [entry, 'directory'];
+      } else if (stat.isSymbolicLink()) {
+        record = [entry, 'link', readlinkSync(path)];
+      } else if (stat.isFile()) {
+        record = [entry, 'file', createHash('sha256').update(readFileSync(path)).digest('hex')];
+      } else {
+        throw new Error('Arcfold 文本计数缓存校验失败。');
+      }
+      hash.update(JSON.stringify(record) + '\n');
+      if (stat.isDirectory()) visit(path, entry + '/');
+    }
+  }
+  visit(root, '');
+  return hash.digest('hex');
+}
+
+function installedPython(path) {
+  requirePrivateDirectory(path);
+  if (runtimeDigest(path) !== desktopPython.treeSha256)
+    throw new Error('Arcfold 文本计数缓存校验失败，请联系维护者修复此配置下的缓存。');
+  const file = join(path, executable);
+  if (!lstatSync(file).isFile() || realpathSync(file) !== file)
+    throw new Error('Arcfold 文本计数程序无效，请检查本机安装。');
+  accessSync(file, constants.X_OK);
+  return file;
+}
+
+/** Extract the checked, relocatable runtime into this Desktop profile. */
+export function prepareBundledDesktopPython(packageRoot, home) {
+  if (process.platform !== 'darwin' || process.arch !== 'arm64')
+    throw new Error('当前 Arcfold Desktop 安装包需要配备 Apple 芯片的 Mac。');
+  const archive = join(packageRoot, desktopPython.path);
+  if (!existsSync(archive)) throw new Error('当前安装包缺少 Arcfold 文本计数环境，请重新安装此版本。');
+  const bytes = readDesktopPythonArchive(archive);
+  const directory = cache(realpathSync(home));
+  mkdirSync(directory, { mode: 0o700, recursive: true });
+  requirePrivateDirectory(directory);
+  const destination = join(directory, desktopPython.sha256);
+  if (existsSync(destination)) return installedPython(destination);
+  const stage = mkdtempSync(join(directory, '.install-'));
+  try {
+    const stagedArchive = join(stage, 'runtime.tar.gz');
+    writeFileSync(stagedArchive, bytes, { mode: 0o600, flag: 'wx' });
+    execFileSync('/usr/bin/tar', ['-xzf', stagedArchive, '-C', stage], {
+      stdio: ['ignore', 'ignore', 'pipe'], timeout: 60_000,
+    });
+    rmSync(stagedArchive);
+    installedPython(stage);
+    try {
+      renameSync(stage, destination);
+    } catch (error) {
+      if (!['EEXIST', 'ENOTEMPTY'].includes(error.code)) throw error;
+    }
+    return installedPython(destination);
+  } finally {
+    rmSync(stage, { force: true, recursive: true });
+  }
+}