@vibedev-si/dsh-vibedev 0.2.1

package/lib/pricing.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Price estimates from the catalog's `media_pricing` (selling prices with the
+ * account multiplier applied). The gateway estimates the same way at admission:
+ * 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.
+ * @module dsh-vibedev/pricing
+ */
+import type { MediaModel } 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;
+}
+/**
+ * Format an amount in yuan.
+ * @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)`.
+ * @param model - the model.
+ * @returns the price, or undefined when the catalog gives none.
+ */
+export declare function describePrice(model: MediaModel): string | undefined;
+/**
+ * Estimate an image request.
+ * @param model - the image model.
+ * @param count - images requested.
+ * @returns the estimate, or undefined without a price.
+ */
+export declare function estimateImages(model: MediaModel, count: number): Estimate | undefined;
+/**
+ * Estimate a video request.
+ * @param model - the video model.
+ * @param duration - the requested length in seconds, when given.
+ * @param resolution - the requested resolution, when given.
+ * @param referenceMs - the summed length of the reference videos.
+ * @returns the estimate, or undefined without a price.
+ */
+export declare function estimateVideo(model: MediaModel, duration: number | undefined, resolution: string | undefined, referenceMs?: number): Estimate | undefined;
+/**
+ * Estimate a music or podcast request.
+ * @param model - the audio model.
+ * @returns the estimate, or undefined without a price.
+ */
+export declare function estimateAudio(model: MediaModel): Estimate | undefined;

package/lib/runtime.d.ts

@@ -0,0 +1,150 @@
+/**
+ * What every media tool shares: the gateway client, the model catalog (cached
+ * briefly), model choice, the workspace output folders, input loading
+ * (workspace paths, links, data URLs and `chat:` attachments) and the optional
+ * spending confirmation.
+ * @module dsh-vibedev/runtime
+ */
+import type { AttachmentStore } from '@deepseek-ai/dsh-attachment';
+import type { FileSystem } from '@deepseek-ai/dsh-fs';
+import type { JobRegistry } from '@deepseek-ai/dsh-jobs';
+import type { ToolRunContext } from '@deepseek-ai/dsh-tools';
+import type { ApprovalService } from '@deepseek-ai/dsh-user-approval';
+import type { MediaKind, MediaModel } from './gateway/catalog.js';
+import type { GatewayHttp } from './gateway/http.js';
+import type { MediaLibrary } from './gateway/assets.js';
+import type { ChatMediaKind } from './media/chat.js';
+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';
+/** Live settings (the plugin's volatile config). */
+export interface MediaSettings {
+    /** Output folder, relative to the workspace (or absolute). */
+    readonly outputDir: () => string;
+    readonly confirmSpending: () => boolean;
+    /** A pinned model id, or `''` to let the agent choose. */
+    readonly defaultModel: (slot: ModelSlot) => string;
+}
+/** Construction options. Optional services are read when used, since they can come and go. */
+export interface RuntimeOptions {
+    readonly http: GatewayHttp;
+    readonly library: MediaLibrary;
+    readonly tracker: TaskTracker;
+    readonly store: TaskStore;
+    readonly settings: MediaSettings;
+    readonly stateDir: string;
+    readonly fs?: () => FileSystem | undefined;
+    readonly attachments?: () => AttachmentStore | undefined;
+    readonly approval?: () => ApprovalService | undefined;
+    readonly jobs?: () => JobRegistry | undefined;
+    readonly now?: () => number;
+    readonly log?: (message: string) => void;
+}
+/**
+ * Who a media request runs for: an agent's tool call (a {@link ToolRunContext}
+ * fits as it is), or a host caller such as the film workbench, which names the
+ * workspace itself and shows the cost in its own interface first.
+ */
+export interface MediaCall {
+    readonly signal: AbortSignal;
+    readonly callId?: ToolRunContext['callId'];
+    readonly agent?: ToolRunContext['agent'];
+    /** The workspace, for callers without an agent session. */
+    readonly cwd?: string;
+    /** The caller already showed the cost and the user chose to go ahead. */
+    readonly confirmed?: boolean;
+}
+/** Shared state and helpers of the media tools. */
+export declare class MediaRuntime {
+    readonly options: RuntimeOptions;
+    private catalog;
+    private fetching;
+    private generation;
+    readonly now: () => number;
+    /**
+     * @param options - gateway client, stores, settings and host services.
+     */
+    constructor(options: RuntimeOptions);
+    get http(): GatewayHttp;
+    get library(): MediaLibrary;
+    get tracker(): TaskTracker;
+    get store(): TaskStore;
+    get settings(): MediaSettings;
+    /**
+     * The media models this account can use. Cached for two minutes; a failed
+     * refresh falls back to the last list for up to an hour.
+     * @param signal - cancels the request.
+     * @returns the models, in catalog order.
+     */
+    models(signal?: AbortSignal): Promise<MediaModel[]>;
+    /** Forget what belonged to the previous account (catalog and uploaded assets), as after a sign-in change. */
+    accountChanged(): void;
+    /** Forget the cached catalog. */
+    invalidateCatalog(): void;
+    /**
+     * Choose the model for a request: the one asked for, else the pinned one,
+     * else the first in catalog order that `accept` takes (or simply the first).
+     * @param kind - the kind of output.
+     * @param slot - the settings slot.
+     * @param requested - the model the agent asked for, if any.
+     * @param accept - whether a model can serve this request.
+     * @param signal - cancels the catalog request.
+     * @returns the model.
+     */
+    pickModel(kind: MediaKind, slot: ModelSlot, requested: string | undefined, accept?: (model: MediaModel) => boolean, signal?: AbortSignal): Promise<MediaModel>;
+    /**
+     * The workspace of the calling session.
+     * @param call - the tool call or host call.
+     * @returns its absolute working directory, when it has one.
+     */
+    workspace(call: MediaCall): string | undefined;
+    /**
+     * The absolute folder outputs of one kind are saved in: `<workspace>/<outputDir>/<sub>`.
+     * Without a workspace, the plugin state directory is used.
+     * @param call - the tool call or host call.
+     * @param sub - `images`, `videos`, `audio` or `transcripts`.
+     * @returns the folder (created on first write).
+     */
+    outputFolder(call: MediaCall, sub: string): string;
+    /**
+     * A file-name stem: the requested name, else a timestamp plus the start of the prompt.
+     * @param filename - the agent's requested name, without extension.
+     * @param prompt - the prompt.
+     * @returns the stem.
+     */
+    stem(filename: string | undefined, prompt: string | undefined): string;
+    /**
+     * A path relative to the workspace when it is inside it, for messages.
+     * @param call - the tool call or host call.
+     * @param path - an absolute path.
+     * @returns the display path.
+     */
+    display(call: MediaCall, path: string): string;
+    private reader;
+    /**
+     * Load one input: a `chat:` attachment, a data URL, a link, or a path in the workspace.
+     * @param call - the tool call or host call.
+     * @param source - what the agent passed.
+     * @param want - the kind the input needs.
+     * @param maxBytes - the largest accepted file.
+     * @returns the loaded media.
+     */
+    load(call: MediaCall, source: string, want: ChatMediaKind, maxBytes: number): Promise<LoadedMedia>;
+    /**
+     * Ask the user before spending, when the setting asks for it.
+     * @param call - the tool call or host call.
+     * @param toolName - the tool asking.
+     * @param what - the request and its estimated price, in English and Chinese.
+     * @throws {@link MediaError} when the user declines or nobody can answer.
+     */
+    confirmSpending(call: MediaCall, toolName: string, what: {
+        en: string;
+        zh: string;
+    }): Promise<void>;
+    /** The background-job registry, when the host has one. */
+    jobs(): JobRegistry | undefined;
+    /** Log through the host. */
+    log(message: string): void;
+}

package/lib/search/provider.d.ts

@@ -0,0 +1,86 @@
+/**
+ * `GatewaySearchProvider`: a `WebSearchProvider` backed by the VibeDev gateway's
+ * `POST /v1/vibedev/web-search`. The gateway returns titles, snippets and
+ * publication dates, not page bodies (`web_fetch` reads pages), plus instant
+ * answers, which become the result's `content`.
+ *
+ * The gateway asks clients to send searches one at a time and to wait as
+ * `Retry-After` says, so the provider queues searches (`web_search` runs one
+ * call's queries in parallel) and waits out short rate-limit and busy answers
+ * before giving up. A token the gateway rejects is reported back to where it
+ * came from, which renews it, and the search is retried once.
+ *
+ * Ported from the VibeDev app's own search package
+ * (`@vibedev/dsh-web-search-gateway`, provider.ts); here the credential is the
+ * plugin's (host account, its own sign-in, or a development key).
+ * @module dsh-vibedev/search/provider
+ */
+import type { WebSearchProvider, WebSearchRequest, WebSearchResult } from '@deepseek-ai/dsh-web';
+import type { GatewayCredential } from '../gateway/http.js';
+/** Stable id the provider registers under; a profile selects it as `web.searchProvider`. */
+export declare const GATEWAY_SEARCH_PROVIDER_ID = "vibedev-gateway";
+/** What the provider needs from its plugin, plus test seams. */
+export interface GatewaySearchOptions {
+    /** Absolute URL of the gateway's web-search endpoint. */
+    readonly endpoint: string;
+    /** The credential for the next request; undefined while nobody is signed in and no key is set. */
+    readonly resolveCredential: () => Promise<GatewayCredential | undefined>;
+    /** Report a credential the gateway rejected, so its source renews it. */
+    readonly rejectCredential?: (credential: GatewayCredential) => Promise<void>;
+    /** `User-Agent` sent with every request. */
+    readonly userAgent: string;
+    /** Deadline for one HTTP request. */
+    readonly requestTimeoutMs: number;
+    /** Retries after a rate-limited or busy answer. */
+    readonly maxRetries: number;
+    /** Longest `Retry-After` waited out; a longer one fails the search at once. */
+    readonly maxRetryWaitMs: number;
+    /** HTTP client; defaults to the global `fetch`. */
+    readonly fetch?: typeof globalThis.fetch;
+    /** Delay used for `Retry-After`; defaults to a timer that the search's signal cancels. */
+    readonly sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+/**
+ * Milliseconds a `Retry-After` header asks for: delta seconds or an HTTP date.
+ * @param header - the header value, or null when absent.
+ * @param now - the current epoch milliseconds, for an HTTP date.
+ * @returns the wait, or undefined when the header is absent or unreadable.
+ */
+export declare function searchRetryAfterMs(header: string | null, now?: number): number | undefined;
+/**
+ * The request body: the query and, when bounded, the result count within the gateway's limits.
+ * Any other field makes the gateway answer 400.
+ * @param request - the seam request.
+ * @returns the JSON body.
+ */
+export declare function requestBody(request: WebSearchRequest): string;
+/**
+ * Map a gateway search answer to the seam's result. Entries without a usable URL are dropped;
+ * instant answers become `content`.
+ * @param payload - the parsed response body.
+ * @returns the normalized result.
+ */
+export declare function mapSearchResponse(payload: unknown): WebSearchResult;
+/** Web search through the VibeDev gateway. */
+export declare class GatewaySearchProvider implements WebSearchProvider {
+    private readonly options;
+    readonly id = "vibedev-gateway";
+    private queue;
+    /**
+     * @param options - endpoint, credential plane, retry bounds, and test seams.
+     */
+    constructor(options: GatewaySearchOptions);
+    /** Always usable: without a credential a search fails with a sign-in hint rather than an unselected provider. */
+    available(): boolean;
+    /**
+     * Run one search after the ones already queued.
+     * @param request - the query and optional result bound.
+     * @param signal - cancels the search, queued or running.
+     * @returns the normalized result.
+     */
+    search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>;
+    private searchNow;
+    private credential;
+    private post;
+    private json;
+}

package/lib/service.d.ts

@@ -0,0 +1,99 @@
+/**
+ * The media service other plugins call, registered as `vibedevMedia`: the
+ * film workbench's storyboard generates through it when someone presses a
+ * generate button. It takes the same paths as the agent tools — model
+ * choice, reference checks and uploads, idempotent submission, a background
+ * 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.
+ * @module dsh-vibedev/service
+ */
+import type { MediaModel } from './gateway/catalog.js';
+import type { MediaRuntime } from './runtime.js';
+import type { TaskRecord, TaskStatus } from './tasks/store.js';
+import type { ImageRequest } from './tools/image.js';
+import type { VideoRequest } from './tools/video.js';
+/** Where a host request runs and where its results go. */
+export interface HostTarget {
+    /** The workspace; relative input paths resolve against it. */
+    readonly cwd: string;
+    /** Absolute folder the results are saved in. */
+    readonly folder: string;
+    /** File-name stem of the results. */
+    readonly stem: string;
+}
+/** A video or audio task, as host callers see it. */
+export interface MediaTaskView {
+    readonly id: string;
+    readonly kind: TaskRecord['kind'];
+    readonly model: string;
+    readonly status: TaskStatus;
+    readonly progress?: string;
+    readonly outputs?: readonly {
+        readonly path?: string;
+        readonly url?: string;
+        readonly durationSeconds?: number;
+    }[];
+    readonly error?: {
+        readonly code: string;
+        readonly message: string;
+    };
+    readonly estimatedCny?: string;
+    readonly chargedCny?: string;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+}
+export declare class MediaHostService {
+    private readonly runtime;
+    readonly version: string;
+    constructor(runtime: MediaRuntime, version: string);
+    private call;
+    /**
+     * The media models this account can use (cached briefly).
+     * @param signal - cancels the request.
+     * @returns the models in catalog order.
+     */
+    models(signal?: AbortSignal): Promise<readonly MediaModel[]>;
+    /**
+     * Generate images now and save them.
+     * @param request - what to generate.
+     * @param target - the workspace and where the files go.
+     * @param signal - cancels the request.
+     * @returns the model, the saved files, the estimate and a revised prompt.
+     */
+    generateImages(request: ImageRequest, target: HostTarget, signal: AbortSignal): Promise<{
+        images: {
+            absolutePath: string;
+            mediaType: string;
+            bytes: number;
+        }[];
+        model: string;
+        estimatedCny?: string;
+        revisedPrompt?: string;
+    }>;
+    /**
+     * Submit a video. The plugin follows the task in the background and saves
+     * the video when it finishes; watch it with {@link task} and {@link onTask}.
+     * A submission the gateway did not confirm is resent in the background
+     * under the same key, so it is reported as a task still being submitted
+     * rather than as a failure.
+     * @param request - what to generate.
+     * @param target - the workspace and where the video goes.
+     * @param signal - cancels the preparation and the submission.
+     * @returns the task.
+     */
+    startVideo(request: VideoRequest, target: HostTarget, signal: AbortSignal): Promise<MediaTaskView>;
+    /**
+     * A task's current state.
+     * @param id - the task id.
+     * @returns the task, or `undefined` when there is none.
+     */
+    task(id: string): Promise<MediaTaskView | undefined>;
+    /**
+     * Hear about every change to one task.
+     * @param id - the task id.
+     * @param listener - called with the task after each change.
+     * @returns stops listening.
+     */
+    onTask(id: string, listener: (task: MediaTaskView) => void): () => void;
+}

package/lib/tasks/remote.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Reading the gateway's asynchronous task objects: `POST /v1/videos` and
+ * `GET /v1/videos/{id}` (OpenAI video shape plus the gateway's `effective`
+ * receipt and `asset`), and `POST /v1/audio/generations` and
+ * `GET /v1/audio/generations/{id}` (`outputs[]`). Unknown statuses count as
+ * still running; only an explicit terminal status ends a task.
+ * @module dsh-vibedev/tasks/remote
+ */
+/** One produced file as the gateway describes it. */
+export interface RemoteOutput {
+    /** Position in `outputs[]`, for `/content?index=N`. */
+    readonly index: number;
+    readonly url?: string;
+    readonly contentType?: string;
+    readonly title?: string;
+    readonly durationSeconds?: number;
+}
+/** A task's state. */
+export interface RemoteTask {
+    readonly id: string;
+    readonly state: 'pending' | 'completed' | 'failed';
+    /** The gateway's own status word. */
+    readonly status: string;
+    /** Percent done, when the gateway reports it. */
+    readonly progress?: number;
+    readonly error?: {
+        readonly code: string;
+        readonly message: string;
+    };
+    /** Estimated price at submission (CNY, two decimals). */
+    readonly estimatedCny?: string;
+    /** Settled charge (CNY); absent until the gateway settles, which is not the same as free. */
+    readonly chargedCny?: string;
+    readonly outputs: readonly RemoteOutput[];
+}
+/**
+ * Read a video task.
+ * @param body - the parsed answer.
+ * @returns the task, or undefined when the answer names no task id.
+ */
+export declare function parseVideoTask(body: unknown): RemoteTask | undefined;
+/**
+ * Read a music or podcast task.
+ * @param body - the parsed answer.
+ * @returns the task, or undefined when the answer names no task id.
+ */
+export declare function parseAudioTask(body: unknown): RemoteTask | undefined;

package/lib/tasks/store.d.ts

@@ -0,0 +1,132 @@
+/**
+ * The durable list of video and audio tasks, one file per task under
+ * `<state dir>/tasks/`, so harness processes sharing a home never overwrite
+ * each other's tasks. A task is recorded before it is submitted, under the id
+ * that doubles as its `Idempotency-Key`: a submission cut short is resent under
+ * the same key (the gateway returns the original task instead of creating a
+ * second one), and a task still running when the host restarts is followed to
+ * the end. A claim file names the process following a task, so two processes
+ * never poll and download the same one.
+ * @module dsh-vibedev/tasks/store
+ */
+/** What a task produces. */
+export type TaskKind = 'video' | 'audio';
+/**
+ * `submitting`: recorded, not yet confirmed by the gateway. `pending`: the
+ * gateway accepted it. `lost`: given up on (too old, or the gateway forgot it).
+ */
+export type TaskStatus = 'submitting' | 'pending' | 'completed' | 'failed' | 'lost';
+/** One produced file. */
+export interface TaskOutput {
+    /** Position in the gateway's outputs. */
+    readonly index?: number;
+    /** Where it was saved; absent when the download failed. */
+    readonly path?: string;
+    /** The gateway's link to the file (valid for about 30 days). */
+    readonly url?: string;
+    readonly contentType?: string;
+    readonly bytes?: number;
+    readonly title?: string;
+    readonly durationSeconds?: number;
+}
+/** One task. */
+export interface TaskRecord {
+    /** Local id; also the `Idempotency-Key` of the submission. */
+    readonly id: string;
+    readonly kind: TaskKind;
+    readonly model: string;
+    /** A short description for listings (a prompt excerpt). */
+    readonly label: string;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+    /** The session that asked for it. */
+    readonly owner?: string;
+    /** Absolute directory the outputs are saved in. */
+    readonly outputDir: string;
+    /** File-name stem for the outputs. */
+    readonly stem: string;
+    /** The submission, kept so an unconfirmed one can be resent unchanged. */
+    readonly endpoint: string;
+    readonly body: Readonly<Record<string, unknown>>;
+    readonly gatewayId?: string;
+    readonly status: TaskStatus;
+    readonly progress?: string;
+    /** Outputs saved so far; a finished task lists every output. */
+    readonly outputs?: readonly TaskOutput[];
+    readonly error?: {
+        readonly code: string;
+        readonly message: string;
+    };
+    readonly estimatedCny?: string;
+    readonly chargedCny?: string;
+    readonly finishedAt?: number;
+}
+/**
+ * Whether a task has ended.
+ * @param record - the task.
+ * @returns true for completed, failed and lost tasks.
+ */
+export declare function isFinished(record: Pick<TaskRecord, 'status'>): boolean;
+/** Task records under `<state dir>/tasks/`. */
+export declare class TaskStore {
+    private readonly directory;
+    private readonly now;
+    private readonly chains;
+    /**
+     * @param directory - the plugin state directory.
+     * @param now - clock.
+     */
+    constructor(directory: string, now?: () => number);
+    private get dir();
+    private file;
+    /** Run one change to a task after the previous change to it in this process. */
+    private serial;
+    /** All tasks, newest first, as they are on disk now (other processes' tasks included). */
+    list(): Promise<TaskRecord[]>;
+    /**
+     * One task.
+     * @param id - its local id.
+     * @returns the task, or undefined.
+     */
+    get(id: string): Promise<TaskRecord | undefined>;
+    /**
+     * Record a new task.
+     * @param record - the task.
+     * @returns the stored task.
+     */
+    add(record: TaskRecord): Promise<TaskRecord>;
+    /**
+     * Change a task.
+     * @param id - its local id.
+     * @param patch - the fields to replace.
+     * @returns the updated task, or undefined when it is unknown.
+     */
+    update(id: string, patch: Partial<Omit<TaskRecord, 'id' | 'kind' | 'createdAt'>>): Promise<TaskRecord | undefined>;
+    /**
+     * Forget a task, such as a submission the gateway refused outright.
+     * @param id - its local id.
+     */
+    remove(id: string): Promise<void>;
+    /**
+     * Claim the right to follow a task: free, already ours, or held by a process
+     * that stopped renewing it for `staleMs`.
+     * @param id - the task.
+     * @param holder - this process's claim id.
+     * @param staleMs - how old an unrenewed claim may be before it is taken over.
+     * @returns whether this process now holds the claim.
+     */
+    claim(id: string, holder: string, staleMs: number): Promise<boolean>;
+    /**
+     * Keep a claim alive.
+     * @param id - the task.
+     * @param holder - this process's claim id.
+     */
+    renewClaim(id: string, holder: string): Promise<void>;
+    /**
+     * Give up a claim this process holds.
+     * @param id - the task.
+     * @param holder - this process's claim id.
+     */
+    release(id: string, holder: string): Promise<void>;
+    private prune;
+}