@vibedev-si/dsh-vibedev 0.3.0 → 0.3.1

package/lib/pricing.d.ts

@@ -4,27 +4,45 @@
  * per-second video prices times billed seconds, where billed seconds are the
  * output length plus the summed reference video length, rounded up once.
  * Estimates are for the user's information; the gateway's receipt is the charge.
+ *
+ * A model without a price is "not priced" (未定价), never free: only a price the
+ * catalog states as zero is shown as ¥0.
  * @module dsh-vibedev/pricing
  */
-import type { MediaModel } from './gateway/catalog.js';
+import type { MediaKind, MediaModel, PriceUnit } from './gateway/catalog.js';
 /** One estimate. */
 export interface Estimate {
     readonly amountCny: number;
     /** How it was reached, such as `¥0.99/s × 5 s`. */
     readonly basis: string;
 }
+/** Text in both languages the plugin speaks. */
+export interface Bilingual {
+    readonly en: string;
+    readonly zh: string;
+}
+/** Shown wherever the catalog gives no price. */
+export declare const UNPRICED: Bilingual;
 /**
- * Format an amount in yuan.
+ * Format an amount in yuan: two decimals, more when a small unit price needs them (`¥0.015`).
  * @param amount - the amount.
  * @returns `¥4.95`.
  */
 export declare function yuan(amount: number): string;
 /**
- * A one-line price for listings: `¥0.10 per image`, `¥0.99/s (720p)`.
+ * The unit after a price: `/s`, `/原始秒`, `/次`.
+ * @param unit - the price unit.
+ * @param kind - the kind of model, which names a generation (an image, a video, a request).
+ * @returns the suffix in both languages.
+ */
+export declare function unitSuffix(unit: PriceUnit, kind: MediaKind): Bilingual;
+/**
+ * A one-line price for listings: `¥0.10 per image`, `¥0.99/s (720p)`; `not priced` without a price.
  * @param model - the model.
- * @returns the price, or undefined when the catalog gives none.
+ * @param lang - the language.
+ * @returns the price line.
  */
-export declare function describePrice(model: MediaModel): string | undefined;
+export declare function describePrice(model: MediaModel, lang?: keyof Bilingual): string;
 /**
  * Estimate an image request.
  * @param model - the image model.
@@ -41,9 +59,27 @@ export declare function estimateImages(model: MediaModel, count: number): Estima
  * @returns the estimate, or undefined without a price.
  */
 export declare function estimateVideo(model: MediaModel, duration: number | undefined, resolution: string | undefined, referenceMs?: number): Estimate | undefined;
+/** What an audio request costs, as far as it can be known before it runs. */
+export interface AudioQuote {
+    /** The catalog states a price. */
+    readonly priced: boolean;
+    readonly unit?: PriceUnit;
+    readonly unitPriceCny?: number;
+    /**
+     * The amount, when it is known before the request runs: per generation, or
+     * per minute of an input whose length was measured. Speech billed per
+     * original second is known only once the provider reports that length.
+     */
+    readonly amountCny?: number;
+    /** The unit price: `¥0.50/次`, `¥0.02/原始秒`, `¥0.30/分钟`, or `未定价`. */
+    readonly label: Bilingual;
+    /** How the charge is reached. */
+    readonly basis: Bilingual;
+}
 /**
- * Estimate a music or podcast request.
- * @param model - the audio model.
- * @returns the estimate, or undefined without a price.
+ * Quote an audio request: music, podcast and speech generation, or a transcription.
+ * @param model - the audio or transcription model.
+ * @param inputSeconds - for a transcription, the measured length of the input, when known.
+ * @returns the quote; `priced: false` (未定价) when the catalog gives no usable price.
  */
-export declare function estimateAudio(model: MediaModel): Estimate | undefined;
+export declare function quoteAudio(model: MediaModel, inputSeconds?: number): AudioQuote;

package/lib/runtime.d.ts

@@ -18,7 +18,22 @@ import type { LoadedMedia } from './media/sources.js';
 import type { TaskStore } from './tasks/store.js';
 import type { TaskTracker } from './tasks/tracker.js';
 /** The model a setting can pin per kind of output. */
-export type ModelSlot = 'image' | 'video' | 'music' | 'podcast' | 'transcription';
+export type ModelSlot = 'image' | 'video' | 'music' | 'podcast' | 'speech' | 'transcription';
+/**
+ * Whether a model serves a slot. Audio models serve the kind their catalog
+ * entry declares, and only that: an undeclared kind serves none.
+ * @param model - the model.
+ * @param slot - the slot.
+ * @returns whether the model can be chosen for it.
+ */
+export declare function servesSlot(model: MediaModel, slot: ModelSlot): boolean;
+/**
+ * The model a name refers to: its id, else one of its aliases (case-insensitive).
+ * @param models - the catalog.
+ * @param wanted - the id or alias.
+ * @returns the model, or undefined.
+ */
+export declare function modelNamed(models: readonly MediaModel[], wanted: string): MediaModel | undefined;
 /** Live settings (the plugin's volatile config). */
 export interface MediaSettings {
     /** Output folder, relative to the workspace (or absolute). */
@@ -94,6 +109,14 @@ export declare class MediaRuntime {
      * @returns the model.
      */
     pickModel(kind: MediaKind, slot: ModelSlot, requested: string | undefined, accept?: (model: MediaModel) => boolean, signal?: AbortSignal): Promise<MediaModel>;
+    /**
+     * The model a name refers to, whatever its kind.
+     * @param requested - an id or alias.
+     * @param signal - cancels the catalog request.
+     * @returns the model.
+     * @throws {@link MediaError} when the account has no such model.
+     */
+    findModel(requested: string, signal?: AbortSignal): Promise<MediaModel>;
     /**
      * The workspace of the calling session.
      * @param call - the tool call or host call.

package/lib/service.d.ts

@@ -6,9 +6,17 @@
  * follower that saves the result — with the caller naming the workspace and
  * where results go. The caller has already shown the price and the user chose
  * to go ahead, so the spending confirmation setting does not ask again.
+ *
+ * Every task, video or audio, is read the same way: {@link MediaHostService.task}
+ * (what is recorded), {@link MediaHostService.refreshTask} (ask the gateway again:
+ * fresh links, settlement — a query only, it never submits),
+ * {@link MediaHostService.onTask} (each change) and
+ * {@link MediaHostService.result} (the files to play or download).
  * @module dsh-vibedev/service
  */
+import type { AudioForm, AudioRequest } from './audio/request.js';
 import type { MediaModel } from './gateway/catalog.js';
+import type { AudioQuote } from './pricing.js';
 import type { MediaRuntime } from './runtime.js';
 import type { TaskRecord, TaskStatus } from './tasks/store.js';
 import type { ImageRequest } from './tools/image.js';
@@ -22,24 +30,42 @@ export interface HostTarget {
     /** File-name stem of the results. */
     readonly stem: string;
 }
+/** One produced file, as host callers see it. */
+export interface MediaOutputView {
+    /** Where it was saved; absent while it could not be downloaded. */
+    readonly path?: string;
+    /** The gateway's link (signed; it expires — {@link MediaHostService.result} renews it). */
+    readonly url?: string;
+    readonly contentType?: string;
+    readonly title?: string;
+    /** Playback length. */
+    readonly durationSeconds?: number;
+    /** The original length it is billed on (speech), when it differs from playback. */
+    readonly originalSeconds?: number;
+}
 /** A video or audio task, as host callers see it. */
 export interface MediaTaskView {
     readonly id: string;
     readonly kind: TaskRecord['kind'];
+    /** For audio: music, podcast or speech. */
+    readonly audioKind?: string;
     readonly model: string;
     readonly status: TaskStatus;
     readonly progress?: string;
-    readonly outputs?: readonly {
-        readonly path?: string;
-        readonly url?: string;
-        readonly durationSeconds?: number;
-    }[];
+    readonly outputs?: readonly MediaOutputView[];
     readonly error?: {
         readonly code: string;
         readonly message: string;
     };
     readonly estimatedCny?: string;
     readonly chargedCny?: string;
+    /**
+     * `pending`: the result is there, the charge is still being settled (it is
+     * never generated again); `settled`: `chargedCny` is final.
+     */
+    readonly settlement?: 'pending' | 'settled';
+    /** How it is billed: the unit, the unit price, and the billed length once known. */
+    readonly billing?: TaskRecord['billing'];
     readonly createdAt: number;
     readonly updatedAt: number;
 }
@@ -49,11 +75,26 @@ export declare class MediaHostService {
     constructor(runtime: MediaRuntime, version: string);
     private call;
     /**
-     * The media models this account can use (cached briefly).
+     * The media models this account can use (cached briefly; renewed after a sign-in, sign-out or account switch).
      * @param signal - cancels the request.
      * @returns the models in catalog order.
      */
     models(signal?: AbortSignal): Promise<readonly MediaModel[]>;
+    /**
+     * The forms to show for the audio models this account can use: one per
+     * model that declares what it makes, with only the fields it takes, their
+     * declared choices and limits, and its price.
+     * @param signal - cancels the catalog request.
+     * @returns the forms, in catalog order.
+     */
+    audioForms(signal?: AbortSignal): Promise<readonly AudioForm[]>;
+    /**
+     * The price of one audio or transcription model: `¥0.50/次`, `¥0.02/原始秒`, `¥0.30/分钟`, or 未定价.
+     * @param model - the model id or alias.
+     * @param signal - cancels the catalog request.
+     * @returns the quote.
+     */
+    audioPrice(model: string, signal?: AbortSignal): Promise<AudioQuote>;
     /**
      * Generate images now and save them.
      * @param request - what to generate.
@@ -84,11 +125,44 @@ export declare class MediaHostService {
      */
     startVideo(request: VideoRequest, target: HostTarget, signal: AbortSignal): Promise<MediaTaskView>;
     /**
-     * A task's current state.
+     * Submit music, a podcast episode or speech. Fields are checked against
+     * what the model declares before anything is uploaded or charged; speech
+     * references are uploaded to the gateway media library first.
+     *
+     * One user operation, one task: pass the same `operationId` when the same
+     * click is retried and the task already recorded under it is returned —
+     * nothing is submitted twice. Without one, every call is a new operation.
+     * @param request - what to generate.
+     * @param target - the workspace and where the audio goes.
+     * @param signal - cancels the preparation and the submission.
+     * @returns the task.
+     */
+    startAudio(request: AudioRequest, target: HostTarget, signal: AbortSignal): Promise<MediaTaskView>;
+    private submit;
+    /**
+     * A task's current state, as recorded (no request to the gateway).
      * @param id - the task id.
      * @returns the task, or `undefined` when there is none.
      */
     task(id: string): Promise<MediaTaskView | undefined>;
+    /**
+     * Ask the gateway about a task again — a query, never a submission: a
+     * finished task gets fresh links and its missing files are downloaded
+     * again, and a pending settlement is read again. A running task is followed.
+     * @param id - the task id.
+     * @param signal - cancels the query.
+     * @returns the task after the query, or `undefined` when there is none.
+     */
+    refreshTask(id: string, signal?: AbortSignal): Promise<MediaTaskView | undefined>;
+    /**
+     * The files of a finished task, ready to play or download: saved files by
+     * path, and links renewed by a query when one is needed (a missing file, an
+     * expired link). Never generates again.
+     * @param id - the task id.
+     * @param signal - cancels the query.
+     * @returns the outputs, or `undefined` while the task has none.
+     */
+    result(id: string, signal?: AbortSignal): Promise<readonly MediaOutputView[] | undefined>;
     /**
      * Hear about every change to one task.
      * @param id - the task id.

package/lib/tasks/remote.d.ts

@@ -13,11 +13,18 @@ export interface RemoteOutput {
     readonly url?: string;
     readonly contentType?: string;
     readonly title?: string;
+    /** Playback length. */
     readonly durationSeconds?: number;
+    /** The provider's original length this output is billed on, when it differs from playback (speech). */
+    readonly originalSeconds?: number;
 }
 /** A task's state. */
 export interface RemoteTask {
     readonly id: string;
+    /**
+     * `completed` also covers `settlement_pending`: the result exists and is
+     * saved, only the charge is still being settled — it is never generated again.
+     */
     readonly state: 'pending' | 'completed' | 'failed';
     /** The gateway's own status word. */
     readonly status: string;
@@ -31,6 +38,12 @@ export interface RemoteTask {
     readonly estimatedCny?: string;
     /** Settled charge (CNY); absent until the gateway settles, which is not the same as free. */
     readonly chargedCny?: string;
+    /** Whether the charge of a finished task has settled; absent when the gateway does not say. */
+    readonly settlement?: 'pending' | 'settled';
+    /** The billed original length of the whole task, in seconds (speech). */
+    readonly billedOriginalSeconds?: number;
+    /** The billed input length, in minutes (transcription). */
+    readonly billedMinutes?: number;
     readonly outputs: readonly RemoteOutput[];
 }
 /**

package/lib/tasks/store.d.ts

@@ -27,7 +27,10 @@ export interface TaskOutput {
     readonly contentType?: string;
     readonly bytes?: number;
     readonly title?: string;
+    /** Playback length. */
     readonly durationSeconds?: number;
+    /** The original length this output is billed on (speech), when the gateway reports it. */
+    readonly originalSeconds?: number;
 }
 /** One task. */
 export interface TaskRecord {
@@ -59,6 +62,20 @@ export interface TaskRecord {
     };
     readonly estimatedCny?: string;
     readonly chargedCny?: string;
+    /**
+     * Whether the charge of a finished task has settled. `pending`: the result is
+     * saved and is never generated again; only the charge is still to come.
+     */
+    readonly settlement?: 'pending' | 'settled';
+    /** What an audio task makes (music, podcast or speech). */
+    readonly audioKind?: string;
+    /** How the task is billed, and the billed length once the gateway reports it. */
+    readonly billing?: {
+        readonly unit?: string;
+        readonly unitPriceCny?: string;
+        readonly originalSeconds?: number;
+        readonly minutes?: number;
+    };
     readonly finishedAt?: number;
 }
 /**

package/lib/tasks/tracker.d.ts

@@ -143,8 +143,21 @@ export declare class TaskTracker {
      * @returns how long to wait before the next try, or undefined once the task has been ended.
      */
     private afterFailure;
+    /** The money and billing facts of a gateway answer, merged into what the record already knows. */
+    private moneyOf;
     /** Record what the gateway says about a task; save the outputs of a finished one. */
     private apply;
+    /**
+     * Ask the gateway about a task again, by query only: a finished task gets
+     * fresh links (signed links expire), files that are missing locally are
+     * downloaded again, and a pending settlement is read again. Nothing is ever
+     * submitted from here, so a failed query or download cannot create a task.
+     * A task still running is followed as usual.
+     * @param id - the local task id.
+     * @param signal - cancels the query.
+     * @returns the task after the query.
+     */
+    refresh(id: string, signal?: AbortSignal): Promise<TaskRecord>;
     /**
      * Save every output not saved yet, recording each one as it lands. A
      * shutdown mid-download throws, so the task stays open and is resumed.

package/lib/tools/audio.d.ts

@@ -1,6 +1,7 @@
 /**
- * `audio_generate`: a song or a podcast episode, as a background task whose
- * results are saved in the workspace.
+ * `audio_generate`: music, a podcast episode or speech, as a background task
+ * whose results are saved in the workspace. Every field is checked against
+ * what the chosen model declares (see `audio/request`).
  * @module dsh-vibedev/tools/audio
  */
 import type { ToolDefinition } from '@deepseek-ai/dsh-tools';

package/lib/tools/models.d.ts

@@ -4,7 +4,14 @@
  * @module dsh-vibedev/tools/models
  */
 import type { ToolDefinition } from '@deepseek-ai/dsh-tools';
+import type { MediaModel } from '../gateway/catalog.js';
 import type { MediaRuntime } from '../runtime.js';
+/**
+ * What an audio model takes, from its declaration: the fields, speech references, output formats and sample rates.
+ * @param model - an audio or transcription model.
+ * @returns one line, or undefined when nothing is declared.
+ */
+export declare function describeAudioModel(model: MediaModel): string | undefined;
 /**
  * Build the tool.
  * @param runtime - the media runtime.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibedev-si/dsh-vibedev",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "VibeDev 账号与模型：在 DeepSeek Harness 里登录 VibeDev，与 DeepSeek 账号并存，使用 VibeDev 网关的模型（Claude、GPT 等），并生成图片、视频、音乐和播客 · VibeDev account and models for DeepSeek Harness: sign in to VibeDev next to the DeepSeek account and use the VibeDev gateway's models (Claude, GPT and more), plus image, video, music and podcast generation",
   "type": "module",
   "main": "lib/index.js",