@huaweidevtools/aishell-dsh-llm 0.0.1-beta.2 → 0.0.1-beta.3

package/lib/types/adapter.d.ts

@@ -10,13 +10,43 @@
  */
 import { LlmAdapter } from '@deepseek-ai/dsh-llm';
 import type { GenerateOptions, LlmModelInfo, LlmProviderInfo, LlmResolvedModelInfo, StreamChunk } from '@deepseek-ai/dsh-llm';
+import type { AttachmentStore } from '@deepseek-ai/dsh-attachment';
 import type { CredentialsStore } from '@huaweidevtools/aishell-dsh-credentials-store';
+import { type ImageRequestBudget } from './images.ts';
 /** Adapter construction options. */
 export interface GatewayAdapterOptions {
-    /** Chat API base URL (e.g. `https://api.aishell.openbuildlab.com`). */
-    readonly baseUrl: string;
+    /**
+     * Resolve the current chat API base URL (e.g. `https://openai.aishell.openbuildlab.com/v1`).
+     *
+     * A reader, not a value, for the same reason `resolveAttachments` is: this
+     * plugin's whole Config is `Volatile`, so a settings edit is a
+     * volatile-only update. The loader commits such an update into the existing
+     * references and returns without re-running `apply()`
+     * (`cordis-plugin-loader/lib/index.js:381-388`), which means the adapter
+     * instance outlives the value it was built with. A captured string would
+     * leave the settings surface showing the new endpoint while requests kept
+     * going to the old one — silently, and for the life of the process.
+     */
+    readonly resolveBaseUrl: () => string;
     /** Credential store for reading AK/SK. */
     readonly keyring: CredentialsStore;
+    /**
+     * Resolve the mounted attachment service, when the deployment has one.
+     *
+     * Resolved per request rather than captured at construction: the service is
+     * provided by a sibling plugin whose fiber may mount after this one, and a
+     * captured `undefined` would disable image input for the whole session.
+     */
+    readonly resolveAttachments?: () => AttachmentStore | undefined;
+    /** Mounted filesystem provider, mapped into the tool execution world for image handle paths. */
+    readonly resolveHostPath?: (hostPath: string) => string | undefined;
+    /**
+     * Resolve the per-image projection policy, read per request so a budget edit
+     * takes effect without a reload — same reasoning as `resolveBaseUrl`.
+     */
+    readonly resolveImageBudget: () => ImageRequestBudget;
+    /** Resolve accumulated represented base64 bytes one request may carry before images must be offloaded. */
+    readonly resolveMaxRequestImageBytes: () => number;
 }
 export declare class GatewayAdapter extends LlmAdapter {
     private readonly opts;
@@ -34,15 +64,81 @@ export declare class GatewayAdapter extends LlmAdapter {
     private fetchWireModels;
     listModels(provider: string): Promise<readonly LlmModelInfo[]>;
     resolveModel(provider: string, model: string): Promise<LlmResolvedModelInfo>;
-    /** Read AK/SK (and optional SecurityToken) from the credential store. */
+    /**
+     * Whether a usable AK/SK pair is stored.
+     *
+     * The one predicate behind every "can this route do anything" question:
+     * `fetchWireModels` returns an empty catalog without it, and the Models-page
+     * card reports readiness from it. Kept in one place so the catalog and the
+     * card cannot disagree about whether this route is usable.
+     *
+     * @returns whether both halves of the signing credential are present.
+     */
+    hasCredentials(): boolean;
+    /**
+     * Read the AK/SK pair from the credential store.
+     *
+     * Delegates to the shared reader: this adapter, `aishell-e2b`,
+     * `aishell-credentials` and `aishell-deploy` all read the same record, and a
+     * local copy of that rule is how two of them end up disagreeing about what
+     * "credentials are configured" means.
+     *
+     * Read per request, never captured — that is what makes a rotation in the
+     * credential form apply to the very next call.
+     */
     private readCredentials;
-    /** Read credentials or throw MISSING_CREDENTIAL — every signing code path goes through here. */
+    /**
+     * Read credentials or throw `MISSING_CREDENTIAL` — every signing code path
+     * goes through here.
+     */
     private requireCredentials;
     /**
      * Sign a request with AK/SK and fetch. Encapsulates the SDK-HMAC-SHA256
      * signing flow: read credentials → sign → attach headers → fetch.
      */
     private signedFetch;
+    /**
+     * Diagnose an "unsupported model" rejection and append what to do about it.
+     *
+     * The gateway answers a model id it does not carry with `AISHELL.1004`
+     * (`model_not_found`, HTTP 404 — see {@link isModelNotFound}). The default
+     * selection is a pinned literal (it must be readable before any credential or
+     * network call could enumerate the catalog), so the day the catalog drops
+     * that id, every fresh session fails here. Rather than leave the user to
+     * reverse-engineer the supported set, the failure itself asks the gateway
+     * (the catalog cache usually makes this a second signed GET already in
+     * flight) and names the models it currently accepts.
+     *
+     * Returns '' for any other failure, so the message stays untouched there.
+     */
+    private unsupportedModelHint;
+    /**
+     * Resolve one image occurrence's execution-world read path, when the
+     * deployment exposes one. Only enriches the handle text written beside an
+     * image; a deployment without a filesystem provider simply yields the
+     * shorter form.
+     *
+     * Deliberately unguarded, like the official adapters: this throws only for
+     * an invalid durable reference, and every reference reaching here was
+     * already validated by the `readImageRequest` that loaded its bytes — so a
+     * throw means the attachment record is inconsistent, which should surface
+     * rather than be absorbed into less informative handle text.
+     */
+    private readonly imageAccess;
+    /**
+     * Turn the harness history into the wire body, loading image bytes on the
+     * way.
+     *
+     * Deliberately the whole image pipeline and nothing else, so `stream` stays
+     * about transport. Ordering matters and mirrors the official adapters:
+     * resolve the attachment service, prepare one request version per retained
+     * image, fail the request if the budget is exceeded (handing
+     * `dsh-compaction-image-offload` its decision), and only then project the
+     * offloaded occurrences to placeholder text — a mark set by an earlier
+     * request's offload decision, which serialization must replace rather than
+     * look up bytes for.
+     */
+    private buildBody;
     stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
 }
 //# sourceMappingURL=adapter.d.ts.map

package/lib/types/client/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * aishell LLM browser half — shadows the Models page's provider row.
+ *
+ * The page's row for the aishell family is read-only: its profile has no
+ * fields the host editor knows how to write, and its credentials are entered
+ * through the credential form the `aishell-credentials` chips open. What the
+ * row should tell the user is the one fact the old card extension distilled —
+ * ready or not — so the browser half paints it as a status dot beside the
+ * row's name and hides the header's Edit button (see
+ * `client/provider-row-shadow.ts`).
+ *
+ * The readiness fact is read from the `aishell-client-credentials` settings
+ * namespace (`aishell-credentials` owns it; the shadow never names accounts
+ * or manages anything). The shadow follows that namespace through
+ * `whileServed`, so a deployment without that plugin (this LLM package
+ * installed standalone) shows no trace of the dot either — the fact is
+ * unknown, not false.
+ *
+ * The dot's hover copy rides this package's own locale namespace. The shadow
+ * is a DOM patch that does not re-render on a locale switch, so the install
+ * is redone on `locale/change` — the repaint is attribute writes over rows
+ * the sweep re-finds, not a page mutation.
+ *
+ * @module @huaweidevtools/aishell-dsh-llm/client
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+export type { ProviderRowShadowDisposer, ProviderRowTitles, } from './provider-row-shadow.ts';
+export { installProviderRowShadow, ROW_DOT_MARKER, ROW_EDIT_HIDDEN, } from './provider-row-shadow.ts';
+/** Required services. */
+export declare const inject: string[];
+export declare function apply(ctx: ClientContext): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/client/locales.d.ts

@@ -0,0 +1,30 @@
+/**
+ * aishell-llm locale dictionaries — the Models-page provider row's copy.
+ *
+ * The row shadow is a DOM patch, not a React render, so its strings do not
+ * ride the framework's locale seat: the install reads them through `t` at
+ * install time and repaints on a locale switch (the client half re-installs
+ * on `locale/change`). zh is the key-set source of truth; en mirrors it.
+ *
+ * @module @huaweidevtools/aishell-dsh-llm/client/locales
+ */
+/** Dictionary namespace owned by this plugin. */
+export declare const NS: "aishell-llm";
+/** Simplified Chinese dictionary (the key-set source of truth). */
+export declare const zh: {
+    readonly 'provider.ready': "已就绪";
+    readonly 'provider.warn': "未就绪 — 凭据未配置（点击对话输入框上方的凭据按钮填写 AK/SK）";
+};
+/** English dictionary. */
+export declare const en: {
+    readonly 'provider.ready': "Ready";
+    readonly 'provider.warn': "Not ready — credentials missing (click the credentials button above the chat input to enter AK/SK)";
+};
+/** All keys (derived from the zh dictionary, the source of truth). */
+export type AishellLlmLocaleKey = keyof typeof zh;
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        'aishell-llm': AishellLlmLocaleKey;
+    }
+}
+//# sourceMappingURL=locales.d.ts.map

package/lib/types/client/provider-row-shadow.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Runtime shadow of the aishell provider's Models-page row.
+ *
+ * The Models page renders each configured provider as a row whose header
+ * (`rowHead`) shows the display name followed by an Edit button the aishell
+ * family has no use for: the profile has no fields the host editor knows how
+ * to write (the old card extension said so itself), and the row's directory
+ * entry names no api-key credential, so the host header also paints no status
+ * dot. What the user actually needs from this row is the one fact the old
+ * card distilled — ready or not — and that reads better beside the name than
+ * in a card below the header.
+ *
+ * The header lives in ui-settings-models, digest-protected with no slot for
+ * the identity half (the `settings.models.provider-card` seat extends the
+ * area BELOW the header, which is exactly the part this family no longer
+ * wants). The shadow therefore works the way aishell-brand's host residues
+ * do: find the row, patch the DOM. The row is located by its rendered name
+ * (the directory entry's displayName, `PROVIDER_DISPLAY_NAME` — a literal
+ * both halves share); the class names beside it are CSS-module hashes, so
+ * they are matched by the same `[class*="…"]` substring selectors the hero
+ * patch already relies on.
+ *
+ * What the shadow does to a found row:
+ *
+ *   1. a status dot after the name — the host credential dot's own 8px
+ *      geometry and success/warn colors, green when AK/SK are stored, warn
+ *      when they are not, with the readiness copy (installer-supplied, so it
+ *      follows the active locale) as its title;
+ *   2. the row's Edit button is hidden — the row is read-only, and the only
+ *      control the header keeps is whatever the host itself decides (Remove,
+ *      for user-added rows; this family's row is not removable). The hide is
+ *      a marker-keyed `display: none !important` rule, not the `hidden`
+ *      attribute: the button's own class sets `display: inline-flex`, and an
+ *      author declaration beats the UA sheet's `[hidden] { display: none }`,
+ *      so the attribute alone leaves the button visible.
+ *
+ * The Models page re-renders the rows (credential saves, pushed
+ * invalidations), so a MutationObserver keeps the shadow applied for as long
+ * as the page exists. Shadowing is a default, not a force: install() and the
+ * disposer it returns are symmetric, so disabling the plugin restores the
+ * official row exactly — dot removed, Edit button back.
+ *
+ * @module @huaweidevtools/aishell-dsh-llm/client/provider-row-shadow
+ */
+/**
+ * The disposer stops the observer, removes every dot the install added, and
+ * restores every hidden Edit button; a no-op install returns this.
+ */
+export type ProviderRowShadowDisposer = () => void;
+/** Marker attribute the dot carries (exposed for the spec). */
+export declare const ROW_DOT_MARKER = "data-aishell-provider-dot";
+/** Marker attribute a hidden Edit button carries (exposed for the spec). */
+export declare const ROW_EDIT_HIDDEN = "data-aishell-edit-hidden";
+/** The dot's own CSS: the host credential dot's geometry and palette. */
+export declare const ROW_DOT_CSS: string;
+/** Title copy for the dot, by readiness — supplied by the installer so it
+ * follows the active locale (this module is a DOM patch with no locale seat
+ * of its own). The warn state keeps the actionable half — where to enter
+ * AK/SK — because that is the one thing a fresh user cannot guess; the ready
+ * state needs nothing beyond itself. */
+export interface ProviderRowTitles {
+    /** Hover copy when AK/SK are stored. */
+    readonly ok: string;
+    /** Hover copy when they are not. */
+    readonly warn: string;
+}
+/**
+ * Install the provider-row shadow on a document.
+ *
+ * `ready` is the credential fact as the browser half derives it from the
+ * settings namespace `aishell-credentials` owns (see `client/index.ts`);
+ * `titles` is the dot's hover copy in the active locale (the installer
+ * translates; this module holds only the DOM work). Neither is read from any
+ * store here, so a later credential save or locale switch is a reinstall with
+ * the new values, not a re-derivation buried in here. Sweeps the page once,
+ * then observes the body so re-rendered rows are covered too. Returns the
+ * disposer that stops the observer and restores every row.
+ */
+export declare function installProviderRowShadow(target: Document, ready: boolean, titles: ProviderRowTitles): ProviderRowShadowDisposer;
+//# sourceMappingURL=provider-row-shadow.d.ts.map

package/lib/types/images.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Request-image preparation for the aishell gateway adapter.
+ *
+ * The harness hands an adapter durable *references*, never bytes: an
+ * {@link ImageBlock} carries an opaque `attachmentId` that is explicitly
+ * "never a filesystem path or bearer URL". Turning one into the base64 payload
+ * an OpenAI `image_url` part needs is therefore an asynchronous read against
+ * the mounted attachment service — which is why this runs as a step ahead of
+ * serialization rather than inside it.
+ *
+ * Mirrors the official adapters' shape (`dsh-llm-pi-ai`'s `collectImageRefs` /
+ * `prepareRequestImages`, `dsh-llm-deepseek`'s `prepareImages`): collect the
+ * retained references, ask the attachment service for one deterministic
+ * request version each, and let the route's budget decide whether the request
+ * fits.
+ *
+ * @module @huaweidevtools/aishell-dsh-llm/images
+ */
+import type { AttachmentStore, ImageAttachmentRef, RequestImageAttachment } from '@deepseek-ai/dsh-attachment';
+import type { ImageAttachmentAccessResolver, RequestMessage } from '@deepseek-ai/dsh-llm';
+/** Key under which one durable image's request version is held. */
+export type ImageKey = ImageAttachmentRef['attachmentId'];
+/** Request versions by durable attachment id, as {@link prepareRequestImages} returns them. */
+export type RequestImages = ReadonlyMap<ImageKey, RequestImageAttachment>;
+/**
+ * The route's per-image projection policy: the total-pixel cap one image is
+ * scaled into, and the encoded-byte target the encoder aims for. Both are
+ * config fields on this plugin's Config, sharing the pi-ai defaults.
+ */
+export interface ImageRequestBudget {
+    /** Positive width-times-height cap one request image is projected into. */
+    readonly maxPixels: number;
+    /** Encoded-byte target per request image; the smallest ladder output wins when none fits. */
+    readonly maxBytes: number;
+}
+/**
+ * Execution-world path resolver, re-exported under this module's vocabulary.
+ * The official type rather than a local restatement: it is what
+ * `requestImageHandleText` / `offloadedImageText` accept, so an ad-hoc copy
+ * could drift from the contract it is passed into.
+ */
+export type ImageAccessResolver = ImageAttachmentAccessResolver;
+/**
+ * True when any message carries an image block — the guard that decides
+ * whether this adapter needs the attachment service at all.
+ *
+ * @param messages - complete request history.
+ * @returns whether any message content holds an image.
+ */
+export declare function historyHasImage(messages: readonly RequestMessage[]): boolean;
+/**
+ * Reject image blocks in roles the wire format cannot carry them in.
+ *
+ * A user or tool-result message maps onto content parts, so an image there is
+ * representable. Every other role serializes to a plain string (assistant
+ * text plus tool calls, system/developer prose), where an image would be
+ * silently dropped — the exact failure this module exists to remove, so it
+ * fails loud instead.
+ *
+ * @param messages - complete request history.
+ * @throws LlmError `UNSUPPORTED_CONTENT` naming the offending role.
+ */
+export declare function assertImageRoles(messages: readonly RequestMessage[]): void;
+/**
+ * Resolve one request version per retained image, keyed by durable attachment
+ * id so a reference shared by several occurrences is read once.
+ *
+ * Occurrences already marked `offloaded` are skipped: their bytes are not sent
+ * (serialization replaces them with placeholder text), so reading them would
+ * be work whose result nothing consumes.
+ *
+ * @param messages - complete request history.
+ * @param attachments - mounted attachment service.
+ * @param budget - projection policy for this route.
+ * @param signal - request cancellation, honoured by the attachment read.
+ * @returns request versions by durable attachment id.
+ */
+export declare function prepareRequestImages(messages: readonly RequestMessage[], attachments: AttachmentStore, budget: ImageRequestBudget, signal?: AbortSignal): Promise<RequestImages>;
+/**
+ * Request version for one retained occurrence, or a loud failure.
+ *
+ * Every image block reaching serialization must have been prepared, so a
+ * miss is a bug in this adapter rather than bad input — but the alternative
+ * (letting the lookup produce `undefined` and reading `.bytes` off it) turns
+ * it into a `TypeError` from deep inside the request body, so it is named.
+ *
+ * @param images - prepared request versions.
+ * @param ref - durable reference of one retained occurrence.
+ * @returns the request version carrying that image's bytes.
+ * @throws LlmError `INVALID_REQUEST` when the reference was never prepared.
+ */
+export declare function requireRequestImage(images: RequestImages, ref: ImageAttachmentRef): RequestImageAttachment;
+/**
+ * Replace every offloaded occurrence with its placeholder text.
+ *
+ * The durable `offloaded` mark is a surface fact shared by all routes; only
+ * the placeholder wording is route-owned. Request assembly does not do this
+ * for adapters, so an adapter that skips it would send an image whose bytes
+ * it deliberately never loaded.
+ *
+ * @param messages - complete request history.
+ * @param resolveAccess - execution-world path resolver, when one is available.
+ * @returns the history with offloaded occurrences projected to text.
+ */
+export declare function projectOffloaded(messages: readonly RequestMessage[], resolveAccess?: ImageAccessResolver): readonly RequestMessage[];
+/**
+ * Fail the request when its retained images exceed the route's byte budget.
+ *
+ * This adapter does not offload on its own: the durable decision belongs to
+ * the surface, and `dsh-compaction-image-offload` (mounted by `dsh-base`) is
+ * the component that records it and retries the step. Throwing the canonical
+ * code with the required count is what hands it that decision.
+ *
+ * @param messages - complete request history, carrying the surface's offload marks.
+ * @param images - prepared request versions.
+ * @param maxBytes - accumulated represented base64 bytes this route accepts.
+ * @throws LlmError `IMAGE_OFFLOAD_REQUIRED` carrying how many more occurrences must be offloaded.
+ */
+export declare function assertRequestImageBudget(messages: readonly RequestMessage[], images: RequestImages, maxBytes: number): void;
+//# sourceMappingURL=images.d.ts.map

package/lib/types/index.d.ts

@@ -10,20 +10,54 @@
  * Credential management (settings namespace + watch → store transfer) lives
  * in `aishell-credentials`; this plugin only consumes the stored credentials.
  *
+ * This plugin also declares the `aishell` route in the configurable-provider
+ * directory (`registerConfigurableProviders`), which is what the Models page
+ * joins with live routes — and it carries a Config schema, without which the
+ * settings mirror (and therefore the Models row) never lists this namespace.
+ * The row itself carries no card: the browser half replaces the page's
+ * Edit-card extension with a status dot beside the row's name (see
+ * `client/provider-row-shadow.ts`).
+ *
  * @module @huaweidevtools/aishell-dsh-llm
  */
-import type { Context } from '@deepseek-ai/cordis';
+import type { Context, Volatile } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
 export type { GatewayAdapter, GatewayAdapterOptions } from './adapter.ts';
 /** Plugin config. */
 export interface Config {
     /** Chat API base URL. Default: the public aishell gateway. */
-    readonly baseUrl?: string;
-    /** Credential store service name; defaults to `'aishell-dsh'`. */
-    readonly keyringService?: string;
+    readonly baseUrl: Volatile<string>;
+    /** Total-pixel cap one request image is projected into. */
+    readonly requestImagePixelBudget: Volatile<number>;
+    /** Encoded-byte target for one request image. */
+    readonly requestImageMaxBytes: Volatile<number>;
+    /** Accumulated base64 image bytes one request accepts before offload is required. */
+    readonly maxRequestImageBytes: Volatile<number>;
 }
+/**
+ * Settings schema for this entry.
+ *
+ * The schema exists for two reasons beyond configurability: the settings
+ * mirror only lists namespaces whose plugin declares a Config, and the Models
+ * page derives a provider row's existence from that listing — without a
+ * schema, the `aishell` route registers its adapter but never shows up as a
+ * configurable provider.
+ */
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    baseUrl: z<string, string, "volatile-defined">;
+    requestImagePixelBudget: z<number, number, "volatile-defined">;
+    requestImageMaxBytes: z<number, number, "volatile-defined">;
+    maxRequestImageBytes: z<number, number, "volatile-defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    baseUrl: z<string, string, "volatile-defined">;
+    requestImagePixelBudget: z<number, number, "volatile-defined">;
+    requestImageMaxBytes: z<number, number, "volatile-defined">;
+    maxRequestImageBytes: z<number, number, "volatile-defined">;
+}>>, "plain">;
 export declare const name = "aishell-llm";
 export declare const inject: string[];
 /** The provider route this plugin owns. */
 export declare const PROVIDER = "aishell";
-export declare function apply(ctx: Context, config?: Config): void;
+export { PROVIDER_DISPLAY_NAME } from './provider-name.ts';
+export declare function apply(ctx: Context, config: Config): void;
 //# sourceMappingURL=index.d.ts.map

package/lib/types/provider-name.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The aishell provider's display name, shared by both plugin halves.
+ *
+ * The Host half registers it on the configurable-provider directory (the
+ * Models page renders it as the provider row's name), and the browser half's
+ * row shadow finds that row by matching the rendered name against this
+ * literal (see `client/provider-row-shadow.ts`). It must stay a single
+ * literal string — the shadow compares `textContent` with it.
+ *
+ * It is also the name `providerInfo()` reports, so the picker and the Models
+ * row call the route the same thing: this package's whole surface is one
+ * product, and qualifying it by cloud ("AI Shell (Huawei Cloud)") added a
+ * distinction no reader needed — there is no second AI Shell to tell it
+ * apart from.
+ */
+export declare const PROVIDER_DISPLAY_NAME = "AI Shell";
+//# sourceMappingURL=provider-name.d.ts.map

package/lib/types/serialize.d.ts

@@ -1,13 +1,30 @@
 /**
  * Serialize harness {@link GenerateOptions} into an OpenAI-compatible wire request.
  *
- * Text-only: image blocks are not mapped (the gateway adapter is for text
- * models; image support can be added later by extending `blocksToText`).
+ * Messages without images serialize to a plain string, exactly as before image
+ * support existed. A message carrying an image serializes to an ordered part
+ * list instead — a handle-text part naming the image, then the image itself as
+ * a base64 data URL — which is the only shape an OpenAI-compatible endpoint
+ * accepts image input in.
+ *
+ * Image bytes are not read here. The harness hands over durable references,
+ * not bytes, so `prepareRequestImages` resolves them one step ahead of this
+ * call and passes the result in; that keeps this function synchronous and
+ * keeps the one await in the adapter, where the attachment service is
+ * reachable.
  *
  * @module @huaweidevtools/aishell-dsh-llm/serialize
  */
 import type { GenerateOptions } from '@deepseek-ai/dsh-llm';
+import { type ImageAccessResolver, type RequestImages } from './images.ts';
 import type { WireRequest } from './types.ts';
-/** Build the POST body for `/chat/completions`. */
-export declare function serializeRequest(options: GenerateOptions): WireRequest;
+/**
+ * Build the POST body for `/chat/completions`.
+ *
+ * @param options - provider-neutral request.
+ * @param images - prepared request versions, required only when the history carries a retained image.
+ * @param resolveAccess - execution-world path resolver for image handle text, when a provider exposes one.
+ * @returns the OpenAI-compatible request body.
+ */
+export declare function serializeRequest(options: GenerateOptions, images?: RequestImages, resolveAccess?: ImageAccessResolver): WireRequest;
 //# sourceMappingURL=serialize.d.ts.map

package/lib/types/types.d.ts

@@ -1,5 +1,5 @@
 /**
- * OpenAI-compatible chat-completions wire format (text-only).
+ * OpenAI-compatible chat-completions wire format.
  *
  * @module @huaweidevtools/aishell-dsh-llm/types
  */
@@ -16,6 +16,25 @@ export interface WireRequest {
     max_tokens?: number;
     stop?: string[];
 }
+/** One message's content: plain text, or an ordered part list when it carries an image. */
+export type WireContent = string | WireContentPart[];
+/**
+ * One content part. Only the two shapes this adapter emits are declared: text,
+ * and the base64 data URL an OpenAI-compatible endpoint reads an image from.
+ * The harness's `reasoning` blocks fold into text; `file` blocks are projected
+ * to handle text by request assembly before any adapter sees them.
+ */
+export type WireContentPart = WireTextPart | WireImageUrlPart;
+export interface WireTextPart {
+    type: 'text';
+    text: string;
+}
+export interface WireImageUrlPart {
+    type: 'image_url';
+    image_url: {
+        url: string;
+    };
+}
 /** One wire message. */
 export type WireMessage = WireSystemMessage | WireUserMessage | WireAssistantMessage | WireToolMessage;
 export interface WireSystemMessage {
@@ -24,7 +43,7 @@ export interface WireSystemMessage {
 }
 export interface WireUserMessage {
     role: 'user';
-    content: string;
+    content: WireContent;
 }
 export interface WireAssistantMessage {
     role: 'assistant';
@@ -34,6 +53,13 @@ export interface WireAssistantMessage {
 export interface WireToolMessage {
     role: 'tool';
     tool_call_id: string;
+    /**
+     * Always a string, even when the tool result carried an image. OpenAI's
+     * tool message takes text only; an image from a tool result is hoisted into
+     * a separate `user` turn instead, which is what the one OpenAI-path
+     * serializer in the ecosystem does. Widening this field would produce a
+     * request that some gateways reject with 400 and others silently drop.
+     */
     content: string;
 }
 export interface WireAssistantToolCall {
@@ -60,25 +86,33 @@ export interface WireChunk {
 /** One model entry from the GET /models response (OpenAI-compatible). */
 export interface WireModel {
     id: string;
+    /**
+     * Display name, when the gateway sends one. Outside OpenAI's own model
+     * object (which carries `id` alone), so it is an extension like the
+     * metadata below, and the gateway omits it for a model that declares none.
+     *
+     * This is the field that lets an id stay a durable routing key while the
+     * label a person reads stays free to change — the split every official
+     * adapter's `name ?? id` expresses. Without it the two roles collapse onto
+     * the id, and a reserved name like `trial` has to read well in a picker.
+     */
+    name?: string;
     object?: string;
     owned_by?: string;
     created?: number;
-    capabilities?: WireModelCapabilities;
+    /**
+     * The gateway's request-modality list (`["text","image"]`) — the catalog's
+     * own answer to "what does this model accept", and the only field this
+     * adapter reads for capability. A sibling `capabilities` object is not
+     * declared: the gateway may send one, and its `image: boolean` reads like a
+     * fallback for an absent `modalities`, but nothing here consumes it, so
+     * declaring it would only suggest a fallback that does not exist.
+     */
     modalities?: string[];
     reasoning_effort?: string[];
     limits?: WireModelLimits;
     pricing?: WireModelPricing;
 }
-export interface WireModelCapabilities {
-    text?: boolean;
-    image?: boolean;
-    video?: boolean;
-    audio?: boolean;
-    streaming?: boolean;
-    thinking?: boolean;
-    tool_call?: boolean;
-    embedding?: boolean;
-}
 export interface WireModelLimits {
     context_window?: number;
     max_prompt_tokens?: number;