@vibedev-si/dsh-vibedev 0.2.1

package/lib/tasks/tracker.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Following video and audio tasks to the end: submit under the task's
+ * idempotency key, poll the gateway, save the results into the workspace and
+ * record the outcome. Polling belongs to the plugin, not to a tool call or a
+ * background job, so a task keeps being followed after its job is stopped and
+ * after the host restarts.
+ *
+ * Money rules: a task record is removed only when the first submission was
+ * refused outright, so nothing can exist under its key. Every answer that
+ * leaves the outcome open (no answer, a gateway error, a 409) keeps the record,
+ * and the same request is resent under the same key, which returns the
+ * original task when there is one. A resend that is refused outright is
+ * retried only briefly, so a refused request is not created later behind the
+ * user's back.
+ * @module dsh-vibedev/tasks/tracker
+ */
+import type { GatewayHttp } from '../gateway/http.js';
+import type { RemoteTask } from './remote.js';
+import type { TaskRecord, TaskStore } from './store.js';
+/** Construction options; the clock and `sleep` are test seams. */
+export interface TrackerOptions {
+    readonly http: GatewayHttp;
+    readonly store: TaskStore;
+    readonly log?: (message: string) => void;
+    readonly now?: () => number;
+    /** Resolves after `ms`, or early when `signal` aborts; never rejects. */
+    readonly sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+    /** Give up on a task this long after it was created. Defaults to 3 hours. */
+    readonly maxAgeMs?: number;
+    /** An unconfirmed submission is resent until it is this old. Defaults to 5 minutes. */
+    readonly resendWindowMs?: number;
+    /**
+     * A resend refused outright is retried until the task is this old, in case
+     * an earlier attempt is still being created. Defaults to 3 minutes.
+     */
+    readonly refusalGraceMs?: number;
+    /** Download attempts for a finished task before its links are reported instead. Defaults to 5. */
+    readonly downloadAttempts?: number;
+    /** The largest output downloaded. Defaults to 2 GiB. */
+    readonly maxDownloadBytes?: number;
+    /** A claim not renewed for this long is taken over by another process. Defaults to 60 seconds. */
+    readonly claimStaleMs?: number;
+}
+/**
+ * Whether a failed submission may still have created the task: no answer, an
+ * unreadable answer, a gateway error that is not "busy", or a 409 such as
+ * `VIDEO_SUBMISSION_IN_PROGRESS` (an earlier attempt is still being submitted).
+ * @param error - the failure.
+ * @returns true when the same key should be sent again.
+ */
+export declare function outcomeUnknown(error: unknown): boolean;
+/**
+ * The live progress line of a running task.
+ * @param task - the gateway's view.
+ * @returns a short line such as `in progress 40%`.
+ */
+export declare function progressLine(task: RemoteTask): string;
+/** Follows tasks; one poll loop per task. */
+export declare class TaskTracker {
+    private readonly options;
+    private readonly following;
+    private readonly submissions;
+    private readonly listeners;
+    private readonly claims;
+    private readonly downloadFailures;
+    private readonly controller;
+    private readonly holder;
+    private readonly now;
+    private readonly sleep;
+    /**
+     * @param options - gateway client, store and test seams.
+     */
+    constructor(options: TrackerOptions);
+    private get signal();
+    private log;
+    /**
+     * Record and submit a new task. An outright refusal of the first attempt
+     * throws and leaves no record. When the outcome stays open, the task stays
+     * recorded and is resent in the background, and this throws `SUBMISSION_UNCONFIRMED`.
+     * @param draft - the task, with status `submitting`.
+     * @param signal - cancels waiting for the submission.
+     * @returns the accepted task.
+     */
+    submit(draft: TaskRecord, signal?: AbortSignal): Promise<TaskRecord>;
+    private runSubmission;
+    /**
+     * Follow a recorded task until it ends or the tracker is disposed. A task
+     * still being submitted is followed once its submission settles.
+     * @param id - the local task id.
+     * @returns the task at the end (or at disposal, still running).
+     */
+    follow(id: string): Promise<TaskRecord>;
+    private followQuietly;
+    /**
+     * Hear about every change to one task.
+     * @param id - the local task id.
+     * @param listener - called with the updated task.
+     * @returns unsubscribe.
+     */
+    onUpdate(id: string, listener: (record: TaskRecord) => void): () => void;
+    /** Follow every task that has not ended, as after a restart. */
+    resume(): Promise<void>;
+    /** Stop all polling and give up this process's claims; tasks stay recorded and are resumed next time. */
+    dispose(): void;
+    private notify;
+    private update;
+    private finish;
+    /** Hold (or keep) this process's claim on a task, renewing it while held. */
+    private holdClaim;
+    private dropClaim;
+    private releaseClaim;
+    private loop;
+    /**
+     * Decide what a failed resend, poll or download means.
+     * @returns how long to wait before the next try, or undefined once the task has been ended.
+     */
+    private afterFailure;
+    /** Record what the gateway says about a task; save the outputs of a finished one. */
+    private apply;
+    /**
+     * 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.
+     */
+    private saveOutputs;
+    /** Download one output: the authenticated `/content` route, then the gateway's no-login link. */
+    private fetchOutput;
+}

package/lib/tools/account.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `media_account`: which VibeDev account the VibeDev models and media requests
+ * use, and the plugin's own sign-in for hosts without a VibeDev account
+ * (official DeepSeek Harness). People can also sign in from the sidebar or
+ * Settings → VibeDev 账号; this is the agent's way to the same sign-in.
+ * @module dsh-vibedev/tools/account
+ */
+import type { ToolDefinition } from '@deepseek-ai/dsh-tools';
+import type { CredentialChain } from '../auth/credentials.js';
+import type { PluginLogin } from '../auth/login.js';
+import type { MediaRuntime } from '../runtime.js';
+/** Where new users register. */
+export declare const REGISTER_URL = "https://vibedev.jzsaas.com";
+/**
+ * Build the tool.
+ * @param runtime - the media runtime.
+ * @param chain - the credential chain.
+ * @param login - the plugin's own sign-in.
+ * @returns the tool definition.
+ */
+export declare function mediaAccountTool(runtime: MediaRuntime, chain: CredentialChain, login: PluginLogin): ToolDefinition;

package/lib/tools/audio.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `audio_generate`: a song or a podcast episode, as a background task whose
+ * results are saved in the workspace.
+ * @module dsh-vibedev/tools/audio
+ */
+import type { ToolDefinition } from '@deepseek-ai/dsh-tools';
+import type { MediaRuntime } from '../runtime.js';
+/**
+ * Build the tool.
+ * @param runtime - the media runtime.
+ * @returns the tool definition.
+ */
+export declare function audioGenerateTool(runtime: MediaRuntime): ToolDefinition;

package/lib/tools/common.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Pieces the media tools share: how inputs are described to the model, the
+ * background job that reports a video or audio task, and the wording of task
+ * outcomes.
+ * @module dsh-vibedev/tools/common
+ */
+import type { ToolRunContext } from '@deepseek-ai/dsh-tools';
+import type { MediaRuntime } from '../runtime.js';
+import type { TaskRecord } from '../tasks/store.js';
+declare module '@deepseek-ai/dsh-jobs' {
+    interface JobKindMap {
+        'media-video': 'media-video';
+        'media-audio': 'media-audio';
+    }
+}
+/** How a media input may be given, for parameter descriptions. */
+export declare const SOURCE_HELP = "a workspace file path, an http(s) link, or chat:1 for the most recent matching file the user attached in this conversation (chat:2 the one before)";
+/**
+ * A prompt excerpt for labels.
+ * @param prompt - the prompt.
+ * @param max - the longest excerpt.
+ * @returns the excerpt.
+ */
+export declare function excerpt(prompt: string | undefined, max?: number): string;
+/**
+ * The charge line of a finished task.
+ * @param record - the task.
+ * @returns `Charged ¥4.95.`, an estimate, or the empty string.
+ */
+export declare function moneyLine(record: TaskRecord): string;
+/**
+ * The model-facing account of a task's current state.
+ * @param runtime - for display paths.
+ * @param exec - the tool call, for workspace-relative paths; optional after a restart.
+ * @param record - the task.
+ * @returns the text.
+ */
+export declare function describeTask(runtime: MediaRuntime, exec: ToolRunContext | undefined, record: TaskRecord): string;
+/**
+ * Report a submitted task through a background job owned by the calling
+ * session, so the agent hears when it ends. Stopping the job stops the report,
+ * not the task: the gateway has no cancel, so the task still finishes, is saved
+ * and is charged.
+ * @param runtime - the media runtime.
+ * @param exec - the submitting tool call.
+ * @param record - the accepted task.
+ * @returns the job id, or undefined when the host has no job registry or refused the job.
+ */
+export declare function startTaskJob(runtime: MediaRuntime, exec: ToolRunContext, record: TaskRecord): string | undefined;
+/** A submitted task and how it is reported. */
+export interface Submitted {
+    readonly record: TaskRecord;
+    /** The background job reporting it, when the host has a job registry. */
+    readonly jobId?: string;
+    /** The gateway did not confirm the submission; it is being resent under the same key. */
+    readonly unconfirmed: boolean;
+}
+/**
+ * Submit a task and start its report. An unconfirmed submission is not an
+ * error here: the agent must not resubmit it, so it is reported like any
+ * other task while the tracker resends it under the same key.
+ * @param runtime - the media runtime.
+ * @param exec - the tool call.
+ * @param draft - the task to submit.
+ * @returns the task and its job.
+ */
+export declare function submitTask(runtime: MediaRuntime, exec: ToolRunContext, draft: TaskRecord): Promise<Submitted>;
+/** The sentence about an unconfirmed submission. */
+export declare const UNCONFIRMED_NOTE: string;
+/**
+ * Wait for a task in the tool call itself, for hosts without background jobs.
+ * @param runtime - the media runtime.
+ * @param exec - the tool call; aborting stops waiting, not the task.
+ * @param record - the accepted task.
+ * @returns the task when it ended, or as it stands when the wait was cut short.
+ */
+export declare function waitForTask(runtime: MediaRuntime, exec: ToolRunContext, record: TaskRecord): Promise<TaskRecord>;

package/lib/tools/image.d.ts

@@ -0,0 +1,50 @@
+/**
+ * `image_generate`: generate images, or edit/derive from reference images,
+ * save them in the workspace and show them to the model.
+ * @module dsh-vibedev/tools/image
+ */
+import type { ToolDefinition } from '@deepseek-ai/dsh-tools';
+import type { MediaCall, MediaRuntime } from '../runtime.js';
+/** One image request, as the tool and host callers make it. */
+export interface ImageRequest {
+    readonly prompt: string;
+    readonly model?: string;
+    /** `WIDTHxHEIGHT` or `auto`. */
+    readonly size?: string;
+    readonly quality?: string;
+    /** 1-4. */
+    readonly n?: number;
+    /** Images to edit or draw from: paths, links, data URLs or `chat:` references. */
+    readonly references?: readonly string[];
+}
+/** One saved image. */
+export interface GeneratedImage {
+    readonly absolutePath: string;
+    readonly mediaType: string;
+    readonly bytes: number;
+    readonly data: Uint8Array;
+}
+/**
+ * Generate images and save them: model choice, reference checks, the spending
+ * confirmation, the gateway call and the files.
+ * @param runtime - the media runtime.
+ * @param call - the tool call or host call.
+ * @param request - what to generate.
+ * @param save - where: the folder and the file-name stem (`-2`, `-3`... for more than one).
+ * @returns the model, the saved images, the estimate and a revised prompt.
+ */
+export declare function generateImages(runtime: MediaRuntime, call: MediaCall, request: ImageRequest, save: {
+    readonly folder: string;
+    readonly stem: string;
+}): Promise<{
+    model: string;
+    images: GeneratedImage[];
+    estimatedCny?: string;
+    revisedPrompt?: string;
+}>;
+/**
+ * Build the tool.
+ * @param runtime - the media runtime.
+ * @returns the tool definition.
+ */
+export declare function imageGenerateTool(runtime: MediaRuntime): ToolDefinition;

package/lib/tools/models.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `media_models`: the media models this VibeDev account can use, with prices
+ * and, for video, what each generation mode accepts.
+ * @module dsh-vibedev/tools/models
+ */
+import type { ToolDefinition } from '@deepseek-ai/dsh-tools';
+import type { MediaRuntime } from '../runtime.js';
+/**
+ * Build the tool.
+ * @param runtime - the media runtime.
+ * @returns the tool definition.
+ */
+export declare function mediaModelsTool(runtime: MediaRuntime): ToolDefinition;

package/lib/tools/tasks.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `media_tasks`: the video and audio tasks dsh-vibedev is following or has
+ * finished, newest first.
+ * @module dsh-vibedev/tools/tasks
+ */
+import type { ToolDefinition } from '@deepseek-ai/dsh-tools';
+import type { MediaRuntime } from '../runtime.js';
+/**
+ * Build the tool.
+ * @param runtime - the media runtime.
+ * @returns the tool definition.
+ */
+export declare function mediaTasksTool(runtime: MediaRuntime): ToolDefinition;

package/lib/tools/transcribe.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `audio_transcribe`: speech to text with a VibeDev transcription model.
+ * Short files answer directly; long ones become a task that is polled here.
+ * @module dsh-vibedev/tools/transcribe
+ */
+import type { ToolDefinition } from '@deepseek-ai/dsh-tools';
+import type { MediaRuntime } from '../runtime.js';
+/**
+ * The length of a PCM WAV file from its header.
+ * @param data - the file bytes.
+ * @returns seconds, or undefined when the header cannot be read.
+ */
+export declare function wavSeconds(data: Uint8Array): number | undefined;
+/**
+ * Build the tool.
+ * @param runtime - the media runtime.
+ * @returns the tool definition.
+ */
+export declare function audioTranscribeTool(runtime: MediaRuntime): ToolDefinition;

package/lib/tools/video.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `video_generate`: plan a video request against what the chosen model
+ * declares, upload every reference to the gateway media library, check the
+ * measured reference lengths, submit once under an idempotency key and report
+ * the result through a background job.
+ * @module dsh-vibedev/tools/video
+ */
+import type { ToolDefinition } from '@deepseek-ai/dsh-tools';
+import type { MediaModel, VideoInput } from '../gateway/catalog.js';
+import type { MediaCall, MediaRuntime } from '../runtime.js';
+import type { TaskRecord } from '../tasks/store.js';
+import type { VideoPlan, VideoRequestOptions } from '../video/plan.js';
+/** One video request, as the tool and host callers make it. */
+export interface VideoRequest extends VideoRequestOptions {
+    readonly model?: string;
+}
+/** A video request checked, uploaded and priced, ready to submit. */
+export interface PreparedVideo {
+    readonly model: MediaModel;
+    readonly plan: VideoPlan;
+    /** The task to submit (status `submitting`). */
+    readonly draft: TaskRecord;
+    /** One entry per uploaded input, in request order. */
+    readonly inputs: readonly VideoInput[];
+    /** `5 s, 16:9, 720p`, for messages. */
+    readonly shape: string;
+}
+/**
+ * Everything before a video submission: choose a model that can serve the
+ * request, load and check every input, upload them all to the gateway media
+ * library, check the measured reference lengths, price it, confirm the
+ * spending, and build the task.
+ * @param runtime - the media runtime.
+ * @param call - the tool call or host call.
+ * @param request - what to generate.
+ * @param save - where the finished video goes: the folder and the file-name stem.
+ * @returns the prepared task.
+ */
+export declare function prepareVideoTask(runtime: MediaRuntime, call: MediaCall, request: VideoRequest, save: {
+    readonly folder: string;
+    readonly stem: string;
+}): Promise<PreparedVideo>;
+/**
+ * Build the tool.
+ * @param runtime - the media runtime.
+ * @returns the tool definition.
+ */
+export declare function videoGenerateTool(runtime: MediaRuntime): ToolDefinition;