cortico 0.1.0

package/src/providers/console/settings.ts

@@ -0,0 +1,443 @@
+import type {
+  CoreConfig,
+  LLMProviderEntry,
+  ModelSpec,
+  ConfigGroup,
+  ConfigValues,
+} from '../../core/types.ts';
+import {
+  coerceGroupValues,
+  getByPath,
+  readGroupValues,
+  setByPath,
+} from '../../core/config-schema.ts';
+import { existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { updateJsonObject } from '../../config-file.ts';
+import type { Language } from '../../core/language.ts';
+import type { ConsoleLamp, ConsolePageContribution } from '../../web/shared/console-protocol.ts';
+import type { ConsolePageSource } from '../../web/console-pages.ts';
+import { providerModules, type ProviderRegistry } from '../registry.ts';
+import type { ProviderAvailability, ProviderModule } from '../base.ts';
+import { endpointAvailability, validateEntry } from '../configuration.ts';
+import { quotePrices, validatePrices, type PriceDefinition } from '../pricebook.ts';
+import { GenerationError } from '../../core/generation.ts';
+import { readTextFile } from '../../core/util.ts';
+import { responseRequest } from '../../protocol/open-responses/context-helpers.ts';
+import { record } from '../../protocol/open-responses/context.ts';
+import { text } from './strings.ts';
+import type { ProviderConsoleHost } from './types.ts';
+import { connectionGroup } from './config.ts';
+
+export type SecretStatus = 'env' | 'file' | 'none';
+
+/** Output token limit used by the connectivity probe. */
+const PROBE_MAX_OUTPUT_TOKENS = 256;
+
+/** 从磁盘加载的密钥变量名按字面匹配。 */
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** Console entry points receive the request language; callers that omit it use Chinese. */
+export class ProviderSettings {
+  constructor(
+    private readonly config: CoreConfig,
+    private readonly registry: ProviderRegistry,
+    /** 当前部署的 config.json，用于保存 activeProvider。 */
+    private readonly file: string,
+    /** 共享端点目录，配置写入各端点的 config.json。 */
+    private readonly providersDir: string,
+    private readonly modules: readonly ProviderModule[] = providerModules,
+  ) {
+    for (const [name, entry] of Object.entries(config.providers))
+      config.providers[name] =
+        this.modules
+          .find((module) => module.id === entry.kind)
+          ?.normalize?.(structuredClone(entry)) ?? entry;
+  }
+
+  private module(kind: string): ProviderModule {
+    const module = this.modules.find((module) => module.id === kind);
+    if (!module) throw new Error(`Unknown provider module: ${kind}`);
+    return module;
+  }
+
+  private entries(module: ProviderModule) {
+    return Object.entries(this.config.providers)
+      .filter(([, entry]) => entry.kind === module.id)
+      .map(([name, entry]) => ({ name, entry }));
+  }
+  private declaredGroups(language: Language) {
+    return this.modules.flatMap((module) =>
+      this.entries(module).flatMap(({ name, entry }) =>
+        [connectionGroup(name, entry, language), ...(module.config?.(name, entry, language) ?? [])]
+          .map((group) => ({ name, group })),
+      ),
+    );
+  }
+  groups(language: Language = 'zh'): ConfigGroup[] {
+    return this.declaredGroups(language).map(({ group }) => group);
+  }
+
+  values(groupId: string, language: Language = 'zh'): ConfigValues {
+    const { name, group } = this.declaredGroups(language).find((value) => value.group.id === groupId)!;
+    const prefix = `providers.${name}.`;
+    return readGroupValues(this.config, group, (path) =>
+      getByPath(
+        this.config.providers[name] as unknown as Record<string, unknown>,
+        path.slice(prefix.length),
+      ),
+    );
+  }
+
+  setConfig(groupId: string, values: ConfigValues, language: Language = 'zh'): string {
+    const S = text(language);
+    const declared = this.declaredGroups(language).find((value) => value.group.id === groupId);
+    if (!declared) throw new Error(S.unknownGroup);
+    const { name, group } = declared;
+    const coerced = coerceGroupValues(group, values, language);
+    if ('error' in coerced) throw new Error(coerced.error);
+    const next = structuredClone(this.config.providers[name]);
+    const prefix = `providers.${name}.`;
+    for (const [path, value] of Object.entries(coerced.values)) {
+      if (!path.startsWith(prefix)) throw new Error(S.groupOutOfScope);
+      setByPath(next as unknown as Record<string, unknown>, path.slice(prefix.length), value);
+    }
+    this.persist(name, validateEntry(this.module(next.kind), next, language), this.config.activeProvider);
+    return S.saved;
+  }
+
+  /** 端点配置写入共享目录；activeProvider 写入当前部署的 config.json。 */
+  private persist(name: string, entry: LLMProviderEntry, activeProvider: string): void {
+    const next = structuredClone(entry);
+    updateJsonObject(this.file, (raw) => {
+      raw.activeProvider = activeProvider;
+      raw.providerSchemaVersion = 3;
+    });
+    const dir = join(this.providersDir, name);
+    mkdirSync(dir, { recursive: true });
+    updateJsonObject(join(dir, 'config.json'), (raw) => {
+      for (const key of Object.keys(raw)) delete raw[key];
+      for (const [key, value] of Object.entries(next)) raw[key] = value;
+    });
+    this.config.providers = { ...this.config.providers, [name]: next };
+    this.config.activeProvider = activeProvider;
+    this.config.providerSchemaVersion = 3;
+    // 端点 .env 的内容按 provider 实例缓存。
+    this.registry.invalidate(name);
+  }
+
+  save(name: string, entry: LLMProviderEntry, language: Language = 'zh'): void {
+    const module = this.module(entry.kind);
+    const prior = this.config.providers[name];
+    if (prior && prior.kind !== entry.kind && this.modules.some((m) => m.id === prior.kind))
+      throw new Error(text(language).kindChange);
+    this.persist(name, validateEntry(module, entry, language), this.config.activeProvider);
+  }
+
+  /** 设为当前端点前，要求端点具有有效的模型配置。 */
+  activate(name: string, spec?: ModelSpec, language: Language = 'zh'): void {
+    const S = text(language);
+    const entry = this.config.providers[name];
+    if (!entry) throw new Error(S.unknownInstance);
+    const requested = { ...entry, ...(spec ? { spec } : {}) };
+    if (!requested.spec) throw new Error(S.specRequired);
+    const next = validateEntry(this.module(entry.kind), requested, language);
+    this.persist(name, next, name);
+  }
+
+  /** 删除端点及其整个目录；当前活跃端点不能删除。 */
+  delete(name: string, language: Language = 'zh'): void {
+    const S = text(language);
+    if (!this.config.providers[name]) throw new Error(S.unknownInstance);
+    if (name === this.config.activeProvider) throw new Error(S.deleteActive);
+    this.registry.invalidate(name);
+    const { [name]: _dropped, ...rest } = this.config.providers;
+    this.config.providers = rest;
+    rmSync(join(this.providersDir, name), { recursive: true, force: true });
+  }
+
+  /** 密钥值优先来自进程环境，其次为端点 .env；未配置变量名时没有来源。 */
+  secretStatus(name: string, entry: LLMProviderEntry): SecretStatus {
+    if (!entry.secret) return 'none';
+    if (process.env[entry.secret]) return 'env';
+    const file = join(this.providersDir, name, '.env');
+    if (!existsSync(file)) return 'none';
+    return new RegExp(`^\\s*${escapeRegExp(entry.secret)}\\s*=\\s*\\S+`, 'm').test(readTextFile(file)) ? 'file' : 'none';
+  }
+
+  /** 把密钥值写进端点目录的 `.env`(同名行覆盖),并让实例重建以读到它。 */
+  setSecret(name: string, value: string, language: Language = 'zh'): SecretStatus {
+    const S = text(language);
+    const entry = this.config.providers[name];
+    if (!entry) throw new Error(S.unknownInstance);
+    if (!entry.secret) throw new Error(S.secretNameRequired);
+    if (!value.trim() || /\s/.test(value)) throw new Error(S.secretValueInvalid);
+    const dir = join(this.providersDir, name);
+    mkdirSync(dir, { recursive: true });
+    const file = join(dir, '.env');
+    const line = `${entry.secret}=${value.trim()}`;
+    const current = existsSync(file) ? readTextFile(file) : '';
+    const pattern = new RegExp(`^\\s*${escapeRegExp(entry.secret)}\\s*=.*$`, 'm');
+    const next = pattern.test(current)
+      ? current.replace(pattern, line)
+      : current + (current && !current.endsWith('\n') ? '\n' : '') + line + '\n';
+    writeFileSync(file, next, 'utf8');
+    this.registry.invalidate(name);
+    return this.secretStatus(name, entry);
+  }
+
+  private assertNewName(name: string, language: Language): void {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(name)) throw new Error(text(language).nameFormat);
+    const existing = this.config.providers[name];
+    // kind 未注册的条目可被同名新端点覆盖，沿用现有目录和密钥。
+    if (existing && this.modules.some((module) => module.id === existing.kind)) throw new Error(text(language).nameTaken);
+  }
+
+  /** 端点目录里除 `config.json` 外还有什么(密钥、授权状态),删前给操作者看。 */
+  private directoryExtras(name: string): string[] {
+    const dir = join(this.providersDir, name);
+    if (!existsSync(dir)) return [];
+    return readdirSync(dir).filter((file) => file !== 'config.json');
+  }
+
+  private async probe(name: string, language: Language) {
+    const S = text(language);
+    const entry = this.config.providers[name];
+    if (!entry) throw new Error(S.unknownInstance);
+    if (!entry.spec) throw new Error(S.specRequired);
+    const request = {
+      ...responseRequest(entry.spec, [record({ type: 'message', role: 'user', content: 'ping' })]),
+      max_output_tokens: Math.min(entry.spec.maxTokens ?? PROBE_MAX_OUTPUT_TOKENS, PROBE_MAX_OUTPUT_TOKENS),
+    };
+    const started = Date.now();
+    try {
+      const generation = await this.registry.bind(name).respond(request, { diagnostic: true, nativeSpec: entry.spec, role: 'probe' });
+      const attempt = generation.attempts.at(-1);
+      return {
+        ok: true,
+        status: attempt?.status ?? null,
+        elapsedMs: attempt?.elapsedMs ?? Date.now() - started,
+        model: generation.response.model,
+        usage: attempt ? {
+          input: attempt.meters.input, cachedInput: attempt.meters.cachedInput,
+          output: attempt.meters.output, reasoning: attempt.meters.reasoning,
+        } : undefined,
+        encryptedReasoning: generation.response.output.some((item) => item.type === 'reasoning' && Boolean(item.encrypted_content)),
+        charges: (attempt?.charges ?? []).map((charge) => ({ currency: charge.quote.currency, amount: charge.amount })),
+      };
+    } catch (error) {
+      const status = error instanceof GenerationError ? error.status : null;
+      const hint = status === 404 ? S.probeNoResponses
+        : status === 401 || status === 403 ? S.probeAuth
+        : status === 0 || status === null ? S.probeUnreachable
+        : undefined;
+      return {
+        ok: false,
+        status,
+        elapsedMs: Date.now() - started,
+        error: error instanceof Error ? error.message : String(error),
+        ...(hint ? { hint } : {}),
+      };
+    }
+  }
+
+  sources() {
+    return this.modules.map((module) => ({
+      id: `llm:${module.id}`,
+      contribute: (language) => this.contribute(module, language),
+    })) satisfies ConsolePageSource[];
+  }
+
+  availability(name: string, language: Language = 'zh'): ProviderAvailability {
+    const entry = this.config.providers[name];
+    if (!entry) return { ready: false, reason: text(language).unknownInstance };
+    return endpointAvailability(
+      this.module(entry.kind),
+      name,
+      entry,
+      this.secretStatus(name, entry) !== 'none',
+      language,
+    );
+  }
+
+  /**
+   * 汇总端点的本地可用性，附第一个可用端点或最后一个不可用原因。
+   */
+  private availableLamp(
+    entries: ReadonlyArray<{ name: string }>,
+    language: Language,
+  ): ConsoleLamp {
+    const S = text(language);
+    let reason = S.availableLampNone;
+    for (const { name } of entries) {
+      const state = this.availability(name, language);
+      if (state.ready) {
+        return { label: S.availableLamp, state: 'online', hint: S.availableLampReady(name) };
+      }
+      if (state.reason) reason = `${name}: ${state.reason}`;
+    }
+    return { label: S.availableLamp, state: 'offline', hint: reason };
+  }
+
+  /** 汇总所有模块的端点可用性。 */
+  providersLamp(language: Language = 'zh'): ConsoleLamp {
+    return this.availableLamp(
+      this.modules.flatMap((module) => this.entries(module)),
+      language,
+    );
+  }
+
+  private contribute(module: ProviderModule, language: Language): ConsolePageContribution {
+    const S = text(language);
+    const entries = this.entries(module);
+    const host: ProviderConsoleHost = {
+      language,
+      entries: () => this.entries(module),
+      instance: (name) => {
+        if (!this.entries(module).some((value) => value.name === name))
+          throw new Error(S.foreignInstance);
+        return this.registry.resolve(name);
+      },
+      save: (name, entry) => {
+        if (entry.kind !== module.id) throw new Error(S.foreignInstance);
+        this.save(name, entry, language);
+      },
+    };
+    const extra = module.console?.(host) ?? {};
+    return {
+      ...extra,
+      id: `llm:${module.id}`,
+      kind: 'llm',
+      label: module.title,
+      availability: 'active',
+      lamps: [
+        {
+          label: S.activeInstanceLamp,
+          state: entries.some((value) => value.name === this.config.activeProvider)
+            ? 'online'
+            : 'offline',
+        },
+        this.availableLamp(this.entries(module), language),
+        ...(extra.lamps ?? []),
+      ],
+      badges: [{ label: S.instancesBadge, value: String(entries.length) }, ...(extra.badges ?? [])],
+      panels: [
+        {
+          id: 'settings',
+          title: S.settingsPanel,
+          description: S.settingsPanelDescription,
+          getMethods: ['state'],
+          // 使用控制台内建端点面板，操作由下方 invoke 提供。
+          builtin: 'llm-settings',
+        },
+        ...(extra.panels ?? []),
+      ],
+      config: extra.config ?? entries.flatMap(
+        ({ name, entry }) => module.config?.(name, entry, language) ?? [],
+      ),
+      invoke: async (panel, method, args) => {
+        if (panel !== 'settings') {
+          if (!extra.invoke) throw new Error(S.unknownPanel);
+          return extra.invoke(panel, method, args);
+        }
+        const at = {
+          startedAt: new Date().toISOString(),
+          requestedServiceTier: null as string | null,
+        };
+        if (method === 'state') {
+          const localized = module.localize?.(language) ?? {};
+          return {
+            active: this.config.activeProvider,
+            reasoningTiers: localized.reasoningTiers ?? module.reasoningTiers,
+            serviceTiers: localized.serviceTiers ?? module.serviceTiers,
+            temperatureNote: localized.temperatureNote ?? module.temperatureNote,
+            baseUrlSuggestions: module.baseUrlSuggestions ?? [],
+            effortSuggestions: module.reasoningTiers.length ? [] : module.effortSuggestions ?? [],
+            instances: this.entries(module).map(({ name, entry }) => ({
+              name,
+              entry,
+              config: this.declaredGroups(language).filter((item) => item.name === name)
+                .map(({ group }) => ({ group, values: this.values(group.id, language) })),
+              secretConfigured: this.secretStatus(name, entry),
+              quotes: (entry.spec ? [entry.spec] : []).map((spec) => ({
+                model: spec.model,
+                quotes: quotePrices(
+                  entry,
+                  { model: spec.model },
+                  { ...at, requestedServiceTier: entry.serviceTier ?? null },
+                  module.prices?.(
+                    entry,
+                    { model: spec.model },
+                    { ...at, requestedServiceTier: entry.serviceTier ?? null },
+                  ) ?? [],
+                ),
+              })),
+            })),
+          };
+        }
+        const [raw] = args;
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+          throw new Error(S.bodyRequired);
+        const body = raw as Record<string, unknown>;
+        if (typeof body.name !== 'string') throw new Error(S.nameRequired);
+        const name = body.name;
+        if (method === 'create') {
+          this.assertNewName(name, language);
+          // 未设置端点价目覆盖，报价仍可来自模块。
+          this.save(name, {
+            kind: module.id,
+            baseUrl: String(body.baseUrl || module.defaultBaseUrl || ''),
+            pricing: [],
+          }, language);
+          return { ok: true };
+        }
+        const entry = this.config.providers[name];
+        if (!entry || entry.kind !== module.id) throw new Error(S.foreignInstance);
+        if (method === 'activate') this.activate(name, body.spec as ModelSpec | undefined, language);
+        else if (method === 'save') {
+          // 面板一格一存,所以给到哪几个键就只并哪几个。
+          const next: LLMProviderEntry = { ...entry };
+          if (body.spec !== undefined) {
+            if (!body.spec || typeof body.spec !== 'object' || Array.isArray(body.spec))
+              throw new Error(S.specRequired);
+            next.spec = body.spec as ModelSpec;
+          }
+          if (body.pricing !== undefined) next.pricing = validatePrices(body.pricing, language);
+          if (typeof body.serviceTier === 'string') next.serviceTier = body.serviceTier;
+          if (typeof body.baseUrl === 'string') next.baseUrl = body.baseUrl.trim();
+          if (typeof body.secret === 'string') {
+            if (body.secret.trim()) next.secret = body.secret.trim();
+            else delete next.secret;
+          }
+          if (typeof body.multimodal === 'boolean') next.multimodal = body.multimodal;
+          if (body.options !== undefined) {
+            if (!body.options || typeof body.options !== 'object' || Array.isArray(body.options))
+              throw new Error(S.optionsObject);
+            next.options = body.options as Record<string, unknown>;
+          }
+          this.save(name, next, language);
+        } else if (method === 'delete') {
+          this.delete(name, language);
+        } else if (method === 'duplicate') {
+          if (typeof body.as !== 'string') throw new Error(S.nameRequired);
+          this.assertNewName(body.as, language);
+          this.save(body.as, structuredClone(entry), language);
+        } else if (method === 'setSecret') {
+          if (typeof body.value !== 'string') throw new Error(S.secretValueInvalid);
+          return { secretConfigured: this.setSecret(name, body.value, language) };
+        } else if (method === 'models') {
+          const instance = this.registry.resolve(name);
+          if (!instance.listModels) throw new Error(S.modelsUnsupported);
+          return { models: await instance.listModels() };
+        } else if (method === 'probe') {
+          return this.probe(name, language);
+        } else if (method === 'extras') {
+          return { files: this.directoryExtras(name) };
+        } else throw new Error(S.unknownMethod);
+        return { ok: true };
+      },
+    };
+  }
+}

package/src/providers/console/strings.ts

@@ -0,0 +1,74 @@
+import { pick, type Language } from '../../core/language.ts';
+
+/** Server side: ConfigGroups, manifest labels and receipts built by `ProviderSettings`. */
+const zh = {
+  connectionDescription: '请求绑定在开始时固定；修改后从下一次请求生效。',
+  baseUrl: '供应地址',
+  secret: '密钥环境变量',
+  secretDescription: '填写变量名；密钥内容由部署环境提供。',
+  multimodal: '启用图像输入',
+  activeInstanceLamp: '当前供应实例',
+  availableLamp: '可用端点',
+  availableLampNone: '没有可用端点',
+  availableLampReady: (name: string) => `${name} 可用`,
+  instancesBadge: '实例',
+  settingsPanel: '实例与模型',
+  settingsPanelDescription: "保存端点模型、价目及当前部署使用的端点。",
+  saved: '参数已保存；下一次请求生效。',
+  unknownGroup: '未知 Provider 参数组',
+  groupOutOfScope: 'Provider 参数组只能修改所属实例',
+  kindChange: '不能改变已有实例的模块类型',
+  unknownInstance: '未知供应实例',
+  foreignInstance: '供应实例不属于此模块',
+  unknownPanel: '未知 Provider 面板',
+  bodyRequired: '需要实例配置对象',
+  nameRequired: '需要实例名',
+  nameFormat: '实例名只能包含字母、数字、下划线与连字符',
+  nameTaken: '实例名已存在',
+  specRequired: '需要模型档对象',
+  unknownMethod: '未知 Provider 操作',
+  optionsObject: '原生参数必须是对象',
+  deleteActive: '当前供应实例不能删除;先启用别的实例',
+  secretNameRequired: '先填写密钥环境变量名,再写入密钥值',
+  secretValueInvalid: '密钥值不能为空或含空白',
+  modelsUnsupported: '此模块不提供模型列表',
+  probeNoResponses: "请求返回 404；请检查供应地址、端点路径及服务支持的 API。",
+  probeAuth: '鉴权失败:检查密钥变量名与密钥值',
+  probeUnreachable: "连接或响应流失败；请检查网络、供应地址与代理。",
+};
+const en: typeof zh = {
+  connectionDescription: 'Requests bind at start; changes apply from the next request.',
+  baseUrl: 'Provider URL',
+  secret: 'Secret environment variable',
+  secretDescription: 'Enter the variable name; the deployment environment supplies the secret.',
+  multimodal: 'Enable image input',
+  activeInstanceLamp: 'Active provider instance',
+  availableLamp: 'Usable endpoint',
+  availableLampNone: 'No usable endpoint',
+  availableLampReady: (name: string) => `${name} is usable`,
+  instancesBadge: 'Instances',
+  settingsPanel: 'Instances and models',
+  settingsPanelDescription: "Save the endpoint model, pricing and the active endpoint for this deployment.",
+  saved: 'Parameters saved; they apply from the next request.',
+  unknownGroup: 'Unknown provider parameter group',
+  groupOutOfScope: 'A provider parameter group can only modify its own instance',
+  kindChange: 'The module type of an existing instance cannot be changed',
+  unknownInstance: 'Unknown provider instance',
+  foreignInstance: 'The provider instance does not belong to this module',
+  unknownPanel: 'Unknown provider panel',
+  bodyRequired: 'An instance configuration object is required',
+  nameRequired: 'An instance name is required',
+  nameFormat: 'Instance names may only contain letters, digits, underscores and hyphens',
+  nameTaken: 'Instance name already exists',
+  specRequired: 'A model spec object is required',
+  unknownMethod: 'Unknown provider action',
+  optionsObject: 'Native options must be an object',
+  deleteActive: 'The active provider instance cannot be deleted; activate another instance first',
+  secretNameRequired: 'Set the secret environment variable name before writing a key value',
+  secretValueInvalid: 'The key value cannot be empty or contain whitespace',
+  modelsUnsupported: 'This module does not list models',
+  probeNoResponses: "The request returned 404; check the provider URL, endpoint path and supported APIs.",
+  probeAuth: 'Authentication failed: check the secret variable name and the key value',
+  probeUnreachable: "The connection or response stream failed; check the network, provider URL and proxy.",
+};
+export const text = (language: Language) => pick(language, { zh, en });

package/src/providers/console/types.ts

@@ -0,0 +1,11 @@
+import type { LLMProviderEntry } from '../../core/types.ts';
+import type { Language } from '../../core/language.ts';
+import type { ProviderInstance } from '../base.ts';
+
+export interface ProviderConsoleHost {
+  /** Console language for panel titles, receipts and error texts. */
+  readonly language: Language;
+  entries(): Array<{ name: string; entry: LLMProviderEntry }>;
+  instance(name: string): ProviderInstance;
+  save(name: string, entry: LLMProviderEntry): void;
+}

package/src/providers/llamacpp/archive.ts

@@ -0,0 +1,148 @@
+/**
+ * Download and unpack a release archive. ZIP input waits for pending output writes
+ * after each chunk; tar archives use a stream pipeline.
+ */
+import { createReadStream, createWriteStream, mkdirSync, type WriteStream } from 'node:fs';
+import { chmod, open, symlink } from 'node:fs/promises';
+import { dirname, isAbsolute, join, normalize, sep } from 'node:path';
+import { Readable, Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { createGunzip } from 'node:zlib';
+import { Unzip, UnzipInflate } from 'fflate';
+import { extract } from 'tar-stream';
+
+export interface DownloadOptions {
+  fetchImpl?: typeof fetch;
+  onProgress?: (done: number, total: number | null) => void;
+  signal?: AbortSignal;
+}
+
+export async function downloadFile(url: string, dest: string, options: DownloadOptions = {}): Promise<void> {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const res = await fetchImpl(url, { signal: options.signal, redirect: 'follow' });
+  if (!res.ok || !res.body) throw new Error(`HTTP ${res.status}`);
+  const length = Number(res.headers.get('content-length'));
+  const total = Number.isFinite(length) && length > 0 ? length : null;
+  let done = 0;
+  const counter = new Transform({
+    transform(chunk: Buffer, _encoding, callback) {
+      done += chunk.length;
+      options.onProgress?.(done, total);
+      callback(null, chunk);
+    },
+  });
+  mkdirSync(dirname(dest), { recursive: true });
+  await pipeline(Readable.fromWeb(res.body as import('node:stream/web').ReadableStream), counter, createWriteStream(dest));
+}
+
+/** Rejects paths that would escape `destDir`; returns the absolute target path. */
+function safeTarget(destDir: string, entryName: string, stripComponents: number): string | null {
+  const parts = entryName.split(/[\\/]+/).filter((part) => part.length > 0);
+  if (parts.some((part) => part === '..') || isAbsolute(entryName)) throw new Error(`unsafe archive entry: ${entryName}`);
+  const kept = parts.slice(stripComponents);
+  if (kept.length === 0) return null;
+  const target = normalize(join(destDir, ...kept));
+  if (!target.startsWith(normalize(destDir) + sep) && target !== normalize(destDir)) throw new Error(`unsafe archive entry: ${entryName}`);
+  return target;
+}
+
+export async function extractArchive(
+  file: string,
+  format: 'zip' | 'tgz',
+  destDir: string,
+  stripComponents: number,
+): Promise<void> {
+  mkdirSync(destDir, { recursive: true });
+  if (format === 'zip') await extractZip(file, destDir, stripComponents);
+  else await extractTgz(file, destDir, stripComponents);
+}
+
+async function extractZip(file: string, destDir: string, stripComponents: number): Promise<void> {
+  const unzip = new Unzip();
+  unzip.register(UnzipInflate);
+  let failure: Error | null = null;
+  /** Output files with bytes still in flight; the read loop waits for them after every chunk. */
+  const active = new Set<{ out: WriteStream; done: Promise<void> }>();
+  unzip.onfile = (entry) => {
+    if (entry.name.endsWith('/')) return;
+    const target = safeTarget(destDir, entry.name, stripComponents);
+    if (!target) return;
+    mkdirSync(dirname(target), { recursive: true });
+    const out = createWriteStream(target);
+    const file = {
+      out,
+      done: new Promise<void>((resolve, reject) => out.once('finish', resolve).once('error', reject)),
+    };
+    active.add(file);
+    entry.ondata = (err, data, final) => {
+      if (err) {
+        failure = err;
+        out.destroy(err);
+        return;
+      }
+      if (data.length) out.write(Buffer.from(data.buffer, data.byteOffset, data.byteLength));
+      if (final) out.end();
+    };
+    entry.start();
+  };
+  /**
+   * Check current writableNeedDrain before waiting for drain.
+   * An ended stream is awaited through its completion promise, since drain may no longer fire.
+   */
+  const settle = async (): Promise<void> => {
+    for (const file of [...active]) {
+      if (file.out.writableEnded) {
+        await file.done;
+        active.delete(file);
+      } else if (file.out.writableNeedDrain) {
+        await new Promise<void>((resolve) => file.out.once('drain', () => resolve()));
+      }
+    }
+  };
+  const handle = await open(file, 'r');
+  try {
+    const chunk = Buffer.allocUnsafe(256 * 1024);
+    for (;;) {
+      const { bytesRead } = await handle.read(chunk, 0, chunk.length, null);
+      if (bytesRead === 0) break;
+      unzip.push(new Uint8Array(chunk.subarray(0, bytesRead)), false);
+      if (failure) throw failure;
+      await settle();
+    }
+    unzip.push(new Uint8Array(0), true);
+  } finally {
+    await handle.close();
+  }
+  if (failure) throw failure;
+  await Promise.all([...active].map((file) => file.done));
+}
+
+async function extractTgz(file: string, destDir: string, stripComponents: number): Promise<void> {
+  const tar = extract();
+  const links: Array<{ target: string; linkname: string }> = [];
+  tar.on('entry', (header, stream, next) => {
+    void (async () => {
+      const target = safeTarget(destDir, header.name, stripComponents);
+      if (!target) {
+        stream.resume();
+        return;
+      }
+      if (header.type === 'directory') {
+        mkdirSync(target, { recursive: true });
+        stream.resume();
+      } else if (header.type === 'symlink' && header.linkname) {
+        links.push({ target, linkname: header.linkname });
+        stream.resume();
+      } else if (header.type === 'file') {
+        mkdirSync(dirname(target), { recursive: true });
+        await pipeline(stream, createWriteStream(target));
+        if (header.mode !== undefined && process.platform !== 'win32') await chmod(target, header.mode & 0o777);
+      } else stream.resume();
+    })().then(() => next(), next);
+  });
+  await pipeline(createReadStream(file), createGunzip(), tar);
+  for (const link of links) {
+    mkdirSync(dirname(link.target), { recursive: true });
+    await symlink(link.linkname, link.target).catch(() => undefined);
+  }
+}