@rol1n/pi-kit 0.0.0-stage → 0.1.0

package/extensions/custom-providers/asr/types.ts

@@ -0,0 +1,20 @@
+export interface AsrModelDefinition {
+  id: string;
+  name: string;
+  provider: string;
+  description: string;
+  sampleRate?: number;
+}
+
+export interface VoiceCallbacks {
+  onFinal(text: string): void;
+  onError(err: Error): void;
+  onClose(): void;
+}
+
+export interface StreamingAsrProvider {
+  start(callbacks: VoiceCallbacks): Promise<void>;
+  sendAudio(chunk: Buffer): void;
+  stop(): Promise<void>;
+  cancel(): void;
+}

package/extensions/custom-providers/chat/index.ts

@@ -0,0 +1,33 @@
+import type { ModalityProvidersRecord } from "../types.ts";
+import { magpieChatProvider } from "./magpie.ts";
+import {
+  SHUAIAPI_MODELS,
+  BIGMODEL_MODELS,
+  DASHSCOPE_CHAT_MODELS,
+} from "./models.ts";
+
+const SHUAIAPI_BASE_URL = "https://cdn.shuaiapi.com/v1";
+const BIGMODEL_BASE_URL = "https://open.bigmodel.cn/api/paas/v4";
+const DASHSCOPE_BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1";
+
+export const chatProviders: ModalityProvidersRecord = {
+  magpie: magpieChatProvider,
+  shuaiapi: {
+    name: "SHUAI API",
+    baseUrl: SHUAIAPI_BASE_URL,
+    api: "openai-completions",
+    models: SHUAIAPI_MODELS,
+  },
+  bigmodel: {
+    name: "BigModel (智谱)",
+    baseUrl: BIGMODEL_BASE_URL,
+    api: "openai-completions",
+    models: BIGMODEL_MODELS,
+  },
+  dashscope: {
+    name: "Aliyun DashScope (阿里百炼)",
+    baseUrl: DASHSCOPE_BASE_URL,
+    api: "openai-completions",
+    models: DASHSCOPE_CHAT_MODELS,
+  },
+};

package/extensions/custom-providers/chat/magpie.ts

@@ -0,0 +1,258 @@
+import type { AnyModel, Api, Model } from "@earendil-works/pi-ai";
+import type { ProviderConfig, ProviderModelConfig } from "@earendil-works/pi-coding-agent";
+
+type ChatModelConfig = Extract<ProviderModelConfig, { type?: "chat" }>;
+type ClassifierModelConfig = Extract<ProviderModelConfig, { type: "classifier" }>;
+type RefreshContext = Parameters<NonNullable<ProviderConfig["refreshModels"]>>[0];
+
+type MagpieChatModelConfig = ChatModelConfig & {
+  api: "anthropic-messages" | "google-generative-ai" | "openai-responses" | "openai-completions";
+  baseUrl: string;
+};
+
+type MagpieClassifierModelConfig = ClassifierModelConfig & {
+  type: "classifier";
+  api: "typesafe-system-one";
+  baseUrl: string;
+};
+
+type MagpieDiscoveredModelConfig = MagpieChatModelConfig | MagpieClassifierModelConfig;
+
+// Authenticate with a Magpie gateway key via /login magpie (stored in Pi's
+// auth.json) or MAGPIE_GATEWAY_KEY. This is not an upstream provider API key.
+
+const BASE_URL = process.env.MAGPIE_BASE_URL ?? "http://127.0.0.1:3425/v1";
+const DEFAULT_CONTEXT_WINDOW = 128_000;
+const DEFAULT_MAX_TOKENS = 8_192;
+
+const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+const NON_CHAT_TYPES = new Set(["image", "video", "audio", "embedding", "rerank"]);
+
+// Follow Magpie's own Pi adapter and gateway's ThinksOnlyWhenAsked /
+// AdaptiveThinking predicates, not a blanket assumption about Messages models:
+// internal/agent/agents.go and internal/gateway/anthropic.go (dee5c9d).
+const CLAUDE_MODEL = /(?:^|[/.:-])claude-/i;
+const CLAUDE_VERSION = /(?:^|[^a-z0-9])(?:claude-)?(?:opus|sonnet|haiku|fable|mythos)-(\d{1,2})(?:[-.](\d{1,2}))?(?:[^0-9]|$)|claude-(\d+)(?:[-.](\d))?-(?:opus|sonnet|haiku)/i;
+const GEMINI_MODEL = /(?:^|\/)(?:gemini|gemma)[-.]/i;
+const DECISION_MODEL = /(?:^|\/)(?:jev(?:-|$)|decision-model)/i;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function positiveInteger(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : undefined;
+}
+
+function reasoningLevels(entry: Record<string, unknown>): string[] {
+  const flat = entry.reasoning_levels;
+  const levels = Array.isArray(flat) && flat.every((level) => typeof level === "string")
+    ? flat
+    : Array.isArray(entry.supported_reasoning_levels) ? entry.supported_reasoning_levels : [];
+  return levels.flatMap((level) => {
+    const effort = isRecord(level) ? level.effort : level;
+    return typeof effort === "string" && effort.trim() ? [effort.trim().toLowerCase()] : [];
+  });
+}
+
+function thinkingLevelMap(levels: string[], claudeOff: boolean): ChatModelConfig["thinkingLevelMap"] {
+  // An absent/unknown effort list is not an exhaustive list of unsupported levels
+  // (e.g. budget-based thinking). Let Pi's native adapter supply its defaults.
+  if (!levels.some((level) => level === "none" || THINKING_LEVELS.some((known) => known !== "off" && known === level))) {
+    return undefined;
+  }
+  const mapping: NonNullable<ChatModelConfig["thinkingLevelMap"]> = Object.fromEntries(THINKING_LEVELS.map((level) => [
+    level,
+    level === "off" ? (levels.includes("none") ? "none" : null) : levels.includes(level) ? level : null,
+  ]));
+  // Claude can take thinking.type=disabled even when none is not an effort.
+  // Other Messages models (e.g. always-thinking GLM) must not inherit this.
+  if (claudeOff && mapping.off === null) delete mapping.off;
+  return mapping;
+}
+
+function toClassifierModel(entry: Record<string, unknown> & { id: string }, gatewayUrl: string): MagpieClassifierModelConfig {
+  return {
+    type: "classifier",
+    id: entry.id,
+    name: typeof entry.display_name === "string" && entry.display_name.trim() ? entry.display_name : entry.id,
+    api: "typesafe-system-one",
+    // TypeSafe System One transport appends /systemone to baseUrl.
+    // Magpie serves POST /v1/systemone, so baseUrl is `${gatewayUrl}/v1`.
+    baseUrl: `${gatewayUrl}/v1`,
+    contextWindow: positiveInteger(entry.context_window)
+      ?? positiveInteger(entry.context_length)
+      ?? positiveInteger(entry.max_input_tokens)
+      ?? 64_000,
+    input: ["text"],
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+  };
+}
+
+function isDecisionModel(entry: Record<string, unknown>, endpoints: string[]): boolean {
+  if (entry.kind === "decision" || entry.type === "classifier") return true;
+  if (endpoints.some((ep) => ep.includes("/v1/systemone"))) return true;
+  if (typeof entry.id === "string" && (DECISION_MODEL.test(entry.id) || entry.id.startsWith("group/jev"))) return true;
+  return false;
+}
+
+function toChatModel(entry: Record<string, unknown> & { id: string }, gatewayUrl: string): MagpieChatModelConfig {
+  // Follow Magpie's /v1/models metadata, not model-name/vendor heuristics:
+  // https://github.com/yetone/magpie/blob/main/docs/integrating.md
+  // Protocol precedence: Responses, then Messages, then native Google Gemini, then Chat fallback.
+  const endpoints = Array.isArray(entry.native_endpoints)
+    ? entry.native_endpoints.filter((ep): ep is string => typeof ep === "string")
+    : [];
+
+  const isGemini = endpoints.some((ep) => ep.includes("/v1beta") || ep.includes("generateContent")) ||
+    ((typeof entry.owned_by === "string" && ["google", "google-vertex", "gemini"].includes(entry.owned_by.toLowerCase())) ||
+      GEMINI_MODEL.test(entry.id)) && !endpoints.includes("/v1/responses") && !endpoints.includes("/v1/messages");
+
+  const api: MagpieChatModelConfig["api"] = endpoints.includes("/v1/responses") ? "openai-responses"
+    : endpoints.includes("/v1/messages") ? "anthropic-messages"
+    : isGemini ? "google-generative-ai"
+    : "openai-completions";
+
+  const version = api === "anthropic-messages" ? CLAUDE_VERSION.exec(entry.id) : null;
+  const claudeOff = api === "anthropic-messages" && (CLAUDE_MODEL.test(entry.id) || version !== null);
+  const major = Number(version?.[3] ?? version?.[1] ?? 0);
+  const minor = Number(version?.[4] ?? version?.[2] ?? 0);
+  const adaptive = major > 4 || (major === 4 && minor >= 6);
+  const levels = reasoningLevels(entry);
+  const reasoning = typeof entry.reasoning === "boolean" ? entry.reasoning : levels.length > 0;
+  const effortMap = reasoning ? thinkingLevelMap(levels, claudeOff) : undefined;
+  const modalities = isRecord(entry.modalities) ? entry.modalities.input : undefined;
+  const input: ChatModelConfig["input"] = Array.isArray(modalities)
+    ? [...new Set(modalities.filter((value): value is "text" | "image" => value === "text" || value === "image"))]
+    : [];
+  const contextWindow = positiveInteger(entry.context_window)
+    ?? positiveInteger(entry.context_length)
+    ?? positiveInteger(entry.max_input_tokens)
+    ?? DEFAULT_CONTEXT_WINDOW;
+
+  // Base URL selection:
+  // - Anthropic: gatewayUrl (Anthropic SDK appends /v1/messages)
+  // - Gemini: `${gatewayUrl}/v1beta` (Google GenAI SDK appends /models/{model}:streamGenerateContent)
+  // - OpenAI: `${gatewayUrl}/v1` (OpenAI SDK appends /responses or /chat/completions)
+  const baseUrl = api === "anthropic-messages" ? gatewayUrl
+    : api === "google-generative-ai" ? `${gatewayUrl}/v1beta`
+    : `${gatewayUrl}/v1`;
+
+  return {
+    type: "chat",
+    id: entry.id,
+    name: typeof entry.display_name === "string" && entry.display_name.trim() ? entry.display_name : entry.id,
+    api,
+    baseUrl,
+    reasoning,
+    ...(effortMap ? { thinkingLevelMap: effortMap } : {}),
+    // Only recognized Claude versions use Magpie's adaptive policy. Effort
+    // names alone do not prove support; opaque aliases need modelOverrides.
+    ...(adaptive ? { compat: { forceAdaptiveThinking: true } } : {}),
+    input: input.length > 0 ? input : ["text"],
+    contextWindow,
+    maxTokens: Math.min(positiveInteger(entry.max_output_tokens) ?? DEFAULT_MAX_TOKENS, contextWindow),
+    // Magpie does not publish prices here. Zero means unknown, not free;
+    // modelOverrides in models.json can provide verified prices and capabilities.
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+  };
+}
+
+export const refreshMagpieModels = async (context: RefreshContext): Promise<ProviderModelConfig[]> => {
+  const gatewayUrl = (context.baseUrl ?? BASE_URL).replace(/\/+$/, "").replace(/\/v1$/, "");
+  // Keep the entire snapshot: rebuilding from IDs would silently turn native
+  // Messages/Responses/Gemini/System One models back into Chat and discard capabilities.
+  // Reject snapshots from another gateway, including during offline startup:
+  // otherwise a changed gateway/key could send future prompts to the old host.
+  const cached = (context.stored?.models ?? [])
+    .filter((model): model is AnyModel => model.provider === "magpie")
+    .filter((model) => {
+      const type = model.type ?? "chat";
+      if (type === "classifier") {
+        return model.api === "typesafe-system-one" && model.baseUrl.replace(/\/+$/, "") === `${gatewayUrl}/v1`;
+      }
+      if (type === "chat") {
+        const expectedUrl = model.api === "anthropic-messages" ? gatewayUrl
+          : model.api === "google-generative-ai" ? `${gatewayUrl}/v1beta`
+          : model.api === "openai-responses" || model.api === "openai-completions" ? `${gatewayUrl}/v1` : undefined;
+        return Boolean(expectedUrl && model.baseUrl.replace(/\/+$/, "") === expectedUrl);
+      }
+      return false;
+    })
+    .map((model) => ({ ...model }));
+  if (!context.allowNetwork || context.signal.aborted) return cached;
+  const key = context.credential?.type === "api_key"
+    ? context.credential.key
+    : process.env.MAGPIE_GATEWAY_KEY;
+  if (!key) return cached;
+
+  // Magpie accepts a gateway key in Bearer, x-api-key, or ?key=; avoid URL/log leakage.
+  // Send X-Magpie-Deciders to include System One decision models, and X-Magpie-Prices for prices.
+  const response = await fetch(`${gatewayUrl}/v1/models`, {
+    headers: {
+      Authorization: `Bearer ${key}`,
+      "X-Magpie-Deciders": "1",
+      "X-Magpie-Prices": "1",
+    },
+    signal: context.signal,
+  });
+  if (!response.ok) throw new Error(`Magpie model discovery failed (HTTP ${response.status})`);
+  const catalog: unknown = await response.json();
+  if (!isRecord(catalog) || !Array.isArray(catalog.data)) {
+    throw new Error("Magpie model discovery returned an invalid /v1/models response");
+  }
+
+  const discovered = new Map<string, MagpieDiscoveredModelConfig>();
+  for (const entry of catalog.data) {
+    if (!isRecord(entry) || typeof entry.id !== "string" || !entry.id.trim()) continue;
+    if ((typeof entry.type === "string" && NON_CHAT_TYPES.has(entry.type)) || discovered.has(entry.id)) continue;
+    const endpoints = Array.isArray(entry.native_endpoints)
+      ? entry.native_endpoints.filter((ep): ep is string => typeof ep === "string")
+      : [];
+    if (isDecisionModel(entry, endpoints)) {
+      discovered.set(entry.id, toClassifierModel({ ...entry, id: entry.id }, gatewayUrl));
+    } else {
+      discovered.set(entry.id, toChatModel({ ...entry, id: entry.id }, gatewayUrl));
+    }
+  }
+  if (context.signal.aborted) return cached;
+  const models = [...discovered.values()];
+  await context.publish({
+    persist: {
+      checkedAt: Date.now(),
+      models: models.map((model) => ({
+        ...model,
+        provider: "magpie",
+      })),
+    },
+  });
+  return models;
+};
+
+async function loadTypesafeSystemOneClassifier() {
+  // Use the host's public provider collection so Pi can map the module in both
+  // npm and bundled installations. No machine-specific fallback path is needed.
+  const { builtinProviders } = await import("@earendil-works/pi-ai/providers/all");
+  const provider = builtinProviders().find((candidate) => candidate.id === "typesafe");
+  if (!provider?.classify) {
+    throw new Error("This Pi version does not provide the TypeSafe System One classifier");
+  }
+  return { classify: provider.classify };
+}
+
+export const magpieChatProvider = {
+  name: "Magpie",
+  baseUrl: BASE_URL,
+  api: "openai-completions",
+  apiKey: "$MAGPIE_GATEWAY_KEY",
+  models: [],
+  refreshModels: refreshMagpieModels,
+  classifiers: {
+    "typesafe-system-one": {
+      classify: async (model, context, options) => {
+        const impl = await loadTypesafeSystemOneClassifier();
+        return impl.classify(model, context, options);
+      },
+    },
+  },
+} satisfies ProviderConfig;

package/extensions/custom-providers/chat/models.ts

@@ -0,0 +1,111 @@
+export const SHUAIAPI_MODELS: Record<string, unknown>[] = [
+  {
+    id: "gpt-6-sol",
+    name: "GPT-6 Sol",
+    reasoning: true,
+    input: ["text", "image"],
+    contextWindow: 1_000_000,
+    maxTokens: 128_000,
+    thinkingLevelMap: {
+      off: "none", minimal: null, low: "low", medium: "medium",
+      high: "high", xhigh: "xhigh", max: "max",
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    compat: { supportsUsageInStreaming: true, supportsDeveloperRole: false },
+  },
+  {
+    id: "gpt-6-astra",
+    name: "GPT-6 Astra",
+    reasoning: true,
+    input: ["text", "image"],
+    contextWindow: 1_000_000,
+    maxTokens: 128_000,
+    thinkingLevelMap: {
+      off: "none", minimal: null, low: "low", medium: "medium",
+      high: "high", xhigh: "xhigh", max: "max",
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    compat: { supportsUsageInStreaming: true, supportsDeveloperRole: false },
+  },
+  {
+    id: "gpt-6-luna",
+    name: "GPT-6 Luna",
+    reasoning: true,
+    input: ["text", "image"],
+    contextWindow: 1_000_000,
+    maxTokens: 128_000,
+    thinkingLevelMap: {
+      off: "none", minimal: null, low: "low", medium: "medium",
+      high: "high", xhigh: "xhigh", max: "max",
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    compat: { supportsUsageInStreaming: true, supportsDeveloperRole: false },
+  },
+];
+
+export const BIGMODEL_MODELS: Record<string, unknown>[] = [
+  {
+    id: "glm-5.3-flash",
+    name: "GLM-5.3 Flash",
+    reasoning: true,
+    input: ["text", "image"],
+    contextWindow: 1_000_000,
+    maxTokens: 128_000,
+    thinkingLevelMap: {
+      minimal: null, low: "low", medium: null,
+      high: "high", xhigh: null, max: "max",
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    compat: {
+      supportsUsageInStreaming: true,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: true,
+      thinkingFormat: "zai",
+      maxTokensField: "max_tokens",
+    },
+  },
+  {
+    id: "glm-5.3",
+    name: "GLM-5.3",
+    reasoning: true,
+    input: ["text"],
+    contextWindow: 1_000_000,
+    maxTokens: 128_000,
+    thinkingLevelMap: {
+      minimal: null, low: "low", medium: null,
+      high: "high", xhigh: null, max: "max",
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    compat: {
+      supportsUsageInStreaming: true,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: true,
+      thinkingFormat: "zai",
+      maxTokensField: "max_tokens",
+    },
+  },
+];
+
+export const DASHSCOPE_CHAT_MODELS: Record<string, unknown>[] = [
+  {
+    id: "qwen3.8-max",
+    name: "Qwen 3.8 Max (通义千问)",
+    reasoning: true,
+    input: ["text", "image"],
+    contextWindow: 1_000_000,
+    maxTokens: 131_072,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    compat: { supportsUsageInStreaming: true },
+  },
+  {
+    id: "qwen3.8-flash",
+    name: "Qwen 3.8 Flash (通义千问)",
+    reasoning: true,
+    input: ["text", "image"],
+    contextWindow: 1_000_000,
+    maxTokens: 131_072,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    compat: { supportsUsageInStreaming: true },
+  },
+  // Pending: qwen-audio-3.1-asr-flash-streaming (ASR; Pi has no audio model type).
+];

package/extensions/custom-providers/classifier/index.ts

@@ -0,0 +1,6 @@
+import type { ModalityProvidersRecord } from "../types.ts";
+import { CLASSIFIER_MODELS } from "./models.ts";
+
+export const classifierProviders: ModalityProvidersRecord = {
+  // Reserved for classifier models (type: "classifier", classify handler)
+};

package/extensions/custom-providers/classifier/models.ts

@@ -0,0 +1 @@
+export const CLASSIFIER_MODELS: Record<string, unknown>[] = [];

package/extensions/custom-providers/image/handlers/dashscope.ts

@@ -0,0 +1,240 @@
+import { readFile } from "node:fs/promises";
+import { extname, resolve } from "node:path";
+
+const MIME_BY_EXTENSION: Record<string, string | undefined> = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+  ".bmp": "image/bmp",
+  ".tif": "image/tiff",
+  ".tiff": "image/tiff",
+  ".gif": "image/gif",
+};
+
+/** DashScope caps reference images at 10 MB. */
+const MAX_REFERENCE_BYTES = 10 * 1024 * 1024;
+
+/**
+ * Content item accepted by the DashScope multimodal-generation endpoint.
+ * `url` is our extension over Pi's native `image` content: DashScope accepts public
+ * URLs directly, so inlining them as base64 would be a pointless download.
+ */
+type DashscopeInput = {
+  type: string;
+  text?: string;
+  data?: string;
+  mimeType?: string;
+  url?: string;
+};
+
+/**
+ * `parameters.size` uses the `width*height` form (asterisk, not `x`).
+ * All values below stay inside qwen-image-3.0's documented bounds: total pixels
+ * within 512*512..2048*2048 and aspect ratio within 1:8..8:1.
+ */
+const DASHSCOPE_RATIO_SIZES: Record<string, string> = {
+  "1:1": "1024*1024",
+  "2:3": "1024*1536",
+  "3:2": "1536*1024",
+  "3:4": "1728*2368",
+  "4:3": "2368*1728",
+  "9:16": "1080*1920",
+  "16:9": "1920*1080",
+};
+
+export async function generateDashscopeImages(
+  model: { api: string; provider: string; id: string; baseUrl?: string },
+  context: { input: DashscopeInput[] },
+  options?: {
+    apiKey?: string;
+    signal?: AbortSignal;
+    fetch?: typeof fetch;
+    onPayload?: (payload: unknown, model: unknown) => unknown | Promise<unknown>;
+    onResponse?: (response: { status: number; headers: Record<string, string> }, model: unknown) => void | Promise<void>;
+  },
+) {
+  const result = {
+    api: model.api,
+    provider: model.provider,
+    model: model.id,
+    output: [] as { type: "image"; data: string; mimeType: string }[],
+    stopReason: "stop" as "stop" | "error" | "aborted",
+    timestamp: Date.now(),
+    errorMessage: undefined as string | undefined,
+  };
+
+  try {
+    if (!options?.apiKey) throw new Error("No API key for dashscope; use /login first");
+
+    // DashScope expects image objects before exactly one text instruction.
+    const content: Array<{ text: string } | { image: string }> = [];
+    for (const item of context.input) {
+      if (item.type === "image") {
+        if (item.url) content.push({ image: item.url });
+        else if (item.data && item.mimeType) content.push({ image: `data:${item.mimeType};base64,${item.data}` });
+        else throw new Error("DashScope image input requires either a url or base64 data + mimeType");
+      } else if (item.text) {
+        content.push({ text: item.text });
+      }
+    }
+    const prompt = content
+      .filter((item): item is { text: string } => "text" in item)
+      .map((item) => item.text)
+      .join("\n")
+      .trim();
+    if (!prompt) throw new Error("DashScope image generation requires a text prompt");
+
+    let payload: unknown = {
+      model: model.id,
+      input: { messages: [{ role: "user", content }] },
+      parameters: { prompt_extend: true },
+    };
+    const replacement = await options.onPayload?.(payload, model);
+    if (replacement !== undefined) payload = replacement;
+    const request = options.fetch ?? fetch;
+    const response = await request(`${model.baseUrl}/services/aigc/multimodal-generation/generation`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${options.apiKey}`,
+      },
+      body: JSON.stringify(payload),
+      signal: options.signal,
+    });
+    await options.onResponse?.({
+      status: response.status,
+      headers: Object.fromEntries(response.headers),
+    }, model);
+    if (!response.ok) throw new Error(`DashScope image request failed (HTTP ${response.status})`);
+    const data = await response.json() as {
+      request_id?: string;
+      output?: { choices?: { message?: { content?: { image?: string }[] } }[] };
+    };
+    const imageUrls = data.output?.choices?.flatMap((choice) =>
+      choice.message?.content?.flatMap((item) => item.image ? [item.image] : []) ?? []
+    ) ?? [];
+    if (imageUrls.length === 0) throw new Error("DashScope returned no images");
+
+    for (const imageUrl of imageUrls) {
+      const url = new URL(imageUrl);
+      if (url.protocol !== "https:" || !/^dashscope-result-[a-z0-9-]+\.oss-[a-z0-9-]+\.aliyuncs\.com$/.test(url.hostname)) {
+        throw new Error("DashScope returned an unexpected image URL");
+      }
+      const imageResponse = await request(url, { signal: options.signal, redirect: "manual" });
+      if (!imageResponse.ok) throw new Error(`Image download failed (HTTP ${imageResponse.status})`);
+      const mimeType = imageResponse.headers.get("content-type")?.split(";")[0]?.trim().toLowerCase()
+        ?? (url.pathname.toLowerCase().endsWith(".png") ? "image/png" : "");
+      if (!["image/png", "image/jpeg", "image/webp"].includes(mimeType)) {
+        throw new Error("DashScope returned an unsupported image type");
+      }
+      if (!imageResponse.body) throw new Error("DashScope returned an empty image body");
+      const reader = imageResponse.body.getReader();
+      const chunks: Uint8Array[] = [];
+      let size = 0;
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        size += value.byteLength;
+        if (size > 25 * 1024 * 1024) {
+          await reader.cancel();
+          throw new Error("DashScope image exceeds 25 MB");
+        }
+        chunks.push(value);
+      }
+      if (size === 0) throw new Error("DashScope returned an empty image");
+      result.output.push({
+        type: "image",
+        data: Buffer.concat(chunks, size).toString("base64"),
+        mimeType,
+      });
+    }
+    return { ...result, responseId: data.request_id };
+  } catch (error) {
+    result.stopReason = options?.signal?.aborted ? "aborted" : "error";
+    result.errorMessage = error instanceof Error ? error.message : String(error);
+    result.output = [];
+    return result;
+  }
+}
+
+/**
+ * Direct entry point used by `image-generate.ts`: adds the two capabilities Pi's native
+ * `ImagesContext` cannot express, an output aspect ratio and a reference image.
+ */
+export async function generateDashscopeImage(
+  ctx: { prompt: string; model: string; aspectRatio?: string; image?: string },
+  options: { apiKey: string; baseUrl?: string; cwd?: string; signal?: AbortSignal },
+) {
+  const input: DashscopeInput[] = [];
+  if (ctx.image) input.push(await toDashscopeReference(ctx.image, options.cwd));
+  input.push({ type: "text", text: ctx.prompt });
+
+  const size = resolveSize(ctx.aspectRatio);
+  const res = await generateDashscopeImages(
+    {
+      api: "dashscope-images",
+      provider: "dashscope",
+      id: ctx.model,
+      baseUrl: options.baseUrl || "https://dashscope.aliyuncs.com/api/v1",
+    },
+    { input },
+    {
+      apiKey: options.apiKey,
+      signal: options.signal,
+      ...(size
+        ? {
+            onPayload: (payload: unknown) => {
+              const current = payload as { parameters?: Record<string, unknown> };
+              return { ...current, parameters: { ...current.parameters, size } };
+            },
+          }
+        : {}),
+    },
+  );
+
+  if (res.stopReason === "error" || !res.output[0]) {
+    throw new Error(`DashScope image generation failed: ${res.errorMessage || "Unknown error"}`);
+  }
+
+  const out = res.output[0];
+  return {
+    buffer: Buffer.from(out.data, "base64"),
+    mimeType: out.mimeType,
+    model: ctx.model,
+    provider: "dashscope",
+  };
+}
+
+/** Map `16:9`-style ratios onto DashScope's `width*height` sizes. Unknown ratios are dropped. */
+export function resolveSize(aspectRatio?: string): string | undefined {
+  if (!aspectRatio) return undefined;
+  return DASHSCOPE_RATIO_SIZES[aspectRatio.trim()];
+}
+
+/** Turn an `image` argument into a DashScope image object, failing loudly on a missing local file. */
+async function toDashscopeReference(reference: string, cwd?: string): Promise<DashscopeInput> {
+  const value = reference.trim();
+  if (value.startsWith("http://") || value.startsWith("https://")) {
+    return { type: "image", url: value };
+  }
+
+  const localPath = resolve(cwd || process.cwd(), value);
+  let buffer: Buffer;
+  try {
+    buffer = await readFile(localPath);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new Error(`Reference image not readable at ${localPath}: ${reason}`);
+  }
+
+  const mimeType = MIME_BY_EXTENSION[extname(localPath).toLowerCase()];
+  if (!mimeType) {
+    throw new Error(`Unsupported reference image type: ${extname(localPath) || localPath}`);
+  }
+  if (buffer.byteLength > MAX_REFERENCE_BYTES) {
+    throw new Error("Reference image exceeds DashScope's 10 MB limit");
+  }
+
+  return { type: "image", data: buffer.toString("base64"), mimeType };
+}