@jini-ai/daemon 0.3.7 → 0.5.0

package/dist/http/media.d.ts

@@ -0,0 +1,146 @@
+import type { Express } from 'express';
+import { type AdapterContext } from '@jini-ai/http-kit';
+type MediaSurface = 'image' | 'video' | 'audio';
+type AudioKind = 'music' | 'speech' | 'sfx';
+type MediaSpeechFormat = 'mp3' | 'wav' | 'flac' | 'aac' | 'opus';
+interface MediaImageReference {
+    readonly dataUrl: string;
+}
+interface MediaGenerationRequest {
+    readonly surface: MediaSurface;
+    readonly model: string;
+    readonly prompt?: string;
+    readonly aspect?: string;
+    readonly length?: number;
+    readonly duration?: number;
+    readonly voice?: string;
+    readonly audioKind?: AudioKind;
+    readonly language?: string;
+    readonly loop?: boolean;
+    readonly promptInfluence?: number;
+    readonly imageRef?: MediaImageReference;
+    readonly imageRefs?: readonly MediaImageReference[];
+    readonly wireModel?: string;
+    readonly speechFormat?: MediaSpeechFormat;
+}
+interface MediaGenerationResult {
+    readonly bytes: Buffer;
+    readonly providerNote: string;
+    readonly suggestedExt?: string;
+    readonly providerId: string;
+    readonly usedStubFallback: boolean;
+    readonly warnings: readonly string[];
+}
+interface MediaDispatchEngine {
+    generate(requiredArgs: Pick<MediaGenerationRequest, 'surface' | 'model'>, optionalArgs?: Omit<MediaGenerationRequest, 'surface' | 'model'>): Promise<MediaGenerationResult>;
+}
+type MediaTaskStatus = 'queued' | 'running' | 'done' | 'failed' | 'interrupted';
+interface MediaTaskError {
+    readonly message: string;
+    readonly status?: number;
+    readonly code?: string;
+}
+interface MediaTask {
+    readonly id: string;
+    readonly ownerRef: string;
+    readonly status: MediaTaskStatus;
+    readonly surface?: string;
+    readonly model?: string;
+    readonly progress: readonly string[];
+    readonly file: unknown | null;
+    readonly error: MediaTaskError | null;
+    readonly startedAt: number;
+    readonly endedAt: number | null;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+}
+interface MediaTaskCreateInput {
+    readonly id: string;
+    readonly ownerRef: string;
+    readonly status?: MediaTaskStatus;
+    readonly surface?: string;
+    readonly model?: string;
+    readonly progress?: readonly string[];
+    readonly file?: unknown | null;
+    readonly error?: MediaTaskError | null;
+    readonly startedAt?: number;
+}
+interface MediaTaskPatch {
+    readonly status?: MediaTaskStatus;
+    readonly surface?: string | null;
+    readonly model?: string | null;
+    readonly progress?: readonly string[];
+    readonly file?: unknown | null;
+    readonly error?: MediaTaskError | null;
+    readonly endedAt?: number | null;
+}
+interface MediaTaskListOptions {
+    readonly includeTerminal?: boolean;
+}
+interface MediaTaskStore {
+    create(requiredArgs: {
+        readonly input: MediaTaskCreateInput;
+    }): Promise<MediaTask>;
+    get({ id }: {
+        readonly id: string;
+    }, _optional?: Record<string, never>): Promise<MediaTask | null>;
+    update({ id, patch }: {
+        readonly id: string;
+        readonly patch: MediaTaskPatch;
+    }, _optional?: Record<string, never>): Promise<MediaTask | null>;
+    listByOwner({ ownerRef }: {
+        readonly ownerRef: string;
+    }, options?: MediaTaskListOptions): Promise<MediaTask[]>;
+    delete({ id }: {
+        readonly id: string;
+    }, _optional?: Record<string, never>): Promise<void>;
+}
+/**
+ * Diagnostic detail for an internal-error response the public API deliberately does not disclose
+ * (SEC-005), matching `delegated-tools.ts`'s `DelegatedToolsInternalErrorContext` precedent.
+ */
+export interface MediaInternalErrorContext {
+    readonly source: 'media-generate-dispatch' | 'media-task-store';
+    readonly taskId: string | null;
+    readonly ownerRef: string | null;
+    readonly correlationId: string;
+    readonly error: unknown;
+}
+export interface MediaHttpDeps {
+    readonly engine: MediaDispatchEngine;
+    readonly taskStore: MediaTaskStore;
+    /** Host-owned sink for the real exception behind a generic `INTERNAL_ERROR` response (SEC-005). Defaults to `console.error`. */
+    readonly onInternalError?: (context: MediaInternalErrorContext) => void;
+}
+interface MediaGenerateRequest {
+    readonly ownerRef: string;
+    readonly request: MediaGenerationRequest;
+}
+interface MediaTaskListQuery {
+    readonly ownerRef: string;
+    readonly options: MediaTaskListOptions;
+}
+export interface MediaGenerateResponse {
+    readonly task: MediaTask;
+}
+export declare const mediaGenerateRoute: import("@jini-ai/http-kit").JsonRouteSpec<MediaGenerateRequest, MediaGenerateResponse, MediaHttpDeps>;
+export interface MediaTaskResponse {
+    readonly task: MediaTask;
+}
+export declare const mediaTaskGetRoute: import("@jini-ai/http-kit").JsonRouteSpec<string, MediaTaskResponse, MediaHttpDeps>;
+export interface MediaTaskDeleteResponse {
+    readonly ok: true;
+}
+export declare const mediaTaskDeleteRoute: import("@jini-ai/http-kit").JsonRouteSpec<string, MediaTaskDeleteResponse, MediaHttpDeps>;
+export interface MediaTaskListResponse {
+    readonly tasks: readonly MediaTask[];
+}
+export declare const mediaTaskListRoute: import("@jini-ai/http-kit").JsonRouteSpec<MediaTaskListQuery, MediaTaskListResponse, MediaHttpDeps>;
+/** Mounts every media route on `app`. A pack's `http(app, services)` calls this directly. */
+export declare function registerMediaRoutes({ app, deps, adapter }: {
+    readonly app: Express;
+    readonly deps: MediaHttpDeps;
+    readonly adapter: AdapterContext;
+}, _optional?: Record<string, never>): void;
+export {};
+//# sourceMappingURL=media.d.ts.map

package/dist/http/media.js

@@ -0,0 +1,346 @@
+/**
+ * @module media
+ *
+ * `POST /api/media/generate`, `GET /api/media/tasks`, `GET /api/media/tasks/:id`, `DELETE
+ * /api/media/tasks/:id` — an HTTP route pack over narrow, transport-owned engine/task-store ports.
+ * A product composition root may satisfy those ports with `@jini-ai/media`; the daemon route pack
+ * deliberately does not point down into that incubating implementation package.
+ *
+ * Follows the "request-now, poll-later" async-task shape `@jini-ai/media`'s own `MediaTaskStore` doc
+ * describes: `POST /api/media/generate` creates a task, kicks off `MediaDispatchEngine.generate()`
+ * in the background (never awaited by the response — a real provider call can take tens of
+ * seconds), and returns the freshly-`'queued'` task immediately. A caller polls
+ * `GET /api/media/tasks/:id` until the task reaches a terminal status (`'done'`/`'failed'`/
+ * `'interrupted'`), mirroring `routines.ts`'s `POST /api/routines/:id/run` (`202`, poll separately)
+ * rather than `runs.ts`'s SSE stream — media generation has no meaningful intermediate event
+ * stream the way a run does, just one eventual result.
+ *
+ * **Where generated bytes land** (per `@jini-ai/media`'s own boundary doc on `MediaGenerationRequest`/
+ * `MediaGenerationResult`: "this engine performs no filesystem I/O... a host pairs this with its
+ * own wiring to decide where generated bytes land"): this route pack encodes the result as a
+ * base64 `data:` URL and stores it directly in `MediaTask.file` (a deliberately untyped `unknown`
+ * field — see `task-store.ts`'s own doc). This is the simplest host-owned answer that needs no new
+ * storage port of its own; a host that wants generated bytes written to a real asset store instead
+ * can layer that on top by reading `MediaTask.file` off a terminal task and re-persisting it
+ * elsewhere — this route pack does not preclude that, it just doesn't invent a new persistence
+ * abstraction to do it for a caller who hasn't asked for one (matching `packages/deploy/source-
+ * map.md`'s "no speculative port" precedent).
+ *
+ * **`ownerRef`** is the same opaque, host-defined scoping key `MediaTaskStore` itself already
+ * uses (e.g. a run id) — this route pack has no `Project`/`Workspace` noun of its own, matching
+ * `active-context.ts`/`delegated-tools.ts`'s precedent for the same category of coupling.
+ *
+ * **SEC-005 redaction**: `MediaDispatchEngine.generate()` can throw a raw vendor-SDK/network
+ * error (API keys, response bodies) that must never reach an HTTP caller verbatim — matching
+ * `delegated-tools.ts`'s `reportInternalError` pattern exactly (a correlation-id-bearing generic
+ * `INTERNAL_ERROR`, the real error only reaching a host-owned sink). Applied to the background
+ * generation failure path (recorded on the task's own `error` field, `message` already redacted
+ * the same way) as well as the sync per-request validation-throw path (`POST /api/media/generate`
+ * itself can throw before ever creating a task — an unregistered `toolId`-shaped programming
+ * error, per `MediaDispatchEngine.generate`'s own contract).
+ */
+import { randomUUID } from 'node:crypto';
+import { createApiError } from '@jini-ai/protocol';
+import { defineJsonRoute, mountJsonRoute } from '@jini-ai/http-kit';
+import { validationError } from '@jini-ai/http-kit';
+import { err, ok } from '@jini-ai/http-kit';
+const SURFACES = new Set(['image', 'video', 'audio']);
+const AUDIO_KINDS = new Set(['music', 'speech', 'sfx']);
+const SPEECH_FORMATS = new Set(['mp3', 'wav', 'flac', 'aac', 'opus']);
+function defaultInternalErrorSink(context) {
+    // eslint-disable-next-line no-console
+    console.error(`[@jini-ai/http-kit] internal error (${context.source}, correlationId=${context.correlationId})`, context.error);
+}
+function reportInternalError(deps, source, error, taskId, ownerRef) {
+    const correlationId = randomUUID();
+    const sink = deps.onInternalError ?? defaultInternalErrorSink;
+    sink({ source, taskId, ownerRef, correlationId, error });
+    return createApiError({ code: 'INTERNAL_ERROR', message: 'an internal error occurred' }, { requestId: correlationId });
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function requireNonEmptyString(body, key) {
+    const value = body[key];
+    return typeof value === 'string' && value.trim().length > 0 ? value : undefined;
+}
+function parseOptionalString(body, key) {
+    const value = body[key];
+    if (value === undefined)
+        return ok({ value: undefined });
+    if (typeof value !== 'string')
+        return err({ error: validationError({ message: `${key} must be a string when provided` }) });
+    return ok({ value });
+}
+function parseOptionalNumber(body, key) {
+    const value = body[key];
+    if (value === undefined)
+        return ok({ value: undefined });
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return err({ error: validationError({ message: `${key} must be a finite number when provided` }) });
+    return ok({ value });
+}
+function parseOptionalBoolean(body, key) {
+    const value = body[key];
+    if (value === undefined)
+        return ok({ value: undefined });
+    if (typeof value !== 'boolean')
+        return err({ error: validationError({ message: `${key} must be a boolean when provided` }) });
+    return ok({ value });
+}
+function parseImageReference(value, field) {
+    if (!isRecord(value) || typeof value.dataUrl !== 'string' || value.dataUrl.trim().length === 0) {
+        return err({ error: validationError({ message: `${field} must be an object with a non-empty dataUrl string` }) });
+    }
+    return ok({ value: { dataUrl: value.dataUrl } });
+}
+function parseOptionalImageRef(body) {
+    const value = body.imageRef;
+    if (value === undefined)
+        return ok({ value: undefined });
+    return parseImageReference(value, 'imageRef');
+}
+function parseOptionalImageRefs(body) {
+    const value = body.imageRefs;
+    if (value === undefined)
+        return ok({ value: undefined });
+    if (!Array.isArray(value))
+        return err({ error: validationError({ message: 'imageRefs must be an array when provided' }) });
+    const refs = [];
+    for (let i = 0; i < value.length; i += 1) {
+        const parsed = parseImageReference(value[i], `imageRefs[${i}]`);
+        if (!parsed.ok)
+            return parsed;
+        refs.push(parsed.value);
+    }
+    return ok({ value: refs });
+}
+function parseMediaGenerate(input) {
+    if (!isRecord(input.body))
+        return err({ error: validationError({ message: 'body must be a JSON object' }) });
+    const body = input.body;
+    const ownerRef = requireNonEmptyString(body, 'ownerRef');
+    if (ownerRef === undefined) {
+        return err({ error: validationError({ message: 'ownerRef must be a non-empty string' }, { issues: [{ path: 'ownerRef', message: 'required non-empty string' }] }) });
+    }
+    const surface = body.surface;
+    if (typeof surface !== 'string' || !SURFACES.has(surface)) {
+        return err({ error: validationError({ message: 'surface must be one of: image, video, audio' }) });
+    }
+    const model = requireNonEmptyString(body, 'model');
+    if (model === undefined) {
+        return err({ error: validationError({ message: 'model must be a non-empty string' }, { issues: [{ path: 'model', message: 'required non-empty string' }] }) });
+    }
+    const audioKind = body.audioKind;
+    if (audioKind !== undefined && (typeof audioKind !== 'string' || !AUDIO_KINDS.has(audioKind))) {
+        return err({ error: validationError({ message: 'audioKind must be one of: music, speech, sfx when provided' }) });
+    }
+    const speechFormat = body.speechFormat;
+    if (speechFormat !== undefined && (typeof speechFormat !== 'string' || !SPEECH_FORMATS.has(speechFormat))) {
+        return err({ error: validationError({ message: 'speechFormat must be one of: mp3, wav, flac, aac, opus when provided' }) });
+    }
+    const prompt = parseOptionalString(body, 'prompt');
+    if (!prompt.ok)
+        return prompt;
+    const aspect = parseOptionalString(body, 'aspect');
+    if (!aspect.ok)
+        return aspect;
+    const voice = parseOptionalString(body, 'voice');
+    if (!voice.ok)
+        return voice;
+    const language = parseOptionalString(body, 'language');
+    if (!language.ok)
+        return language;
+    const wireModel = parseOptionalString(body, 'wireModel');
+    if (!wireModel.ok)
+        return wireModel;
+    const length = parseOptionalNumber(body, 'length');
+    if (!length.ok)
+        return length;
+    const duration = parseOptionalNumber(body, 'duration');
+    if (!duration.ok)
+        return duration;
+    const promptInfluence = parseOptionalNumber(body, 'promptInfluence');
+    if (!promptInfluence.ok)
+        return promptInfluence;
+    const loop = parseOptionalBoolean(body, 'loop');
+    if (!loop.ok)
+        return loop;
+    const imageRef = parseOptionalImageRef(body);
+    if (!imageRef.ok)
+        return imageRef;
+    const imageRefs = parseOptionalImageRefs(body);
+    if (!imageRefs.ok)
+        return imageRefs;
+    return ok({
+        value: {
+            ownerRef,
+            request: {
+                surface: surface,
+                model,
+                ...(prompt.value !== undefined ? { prompt: prompt.value } : {}),
+                ...(aspect.value !== undefined ? { aspect: aspect.value } : {}),
+                ...(length.value !== undefined ? { length: length.value } : {}),
+                ...(duration.value !== undefined ? { duration: duration.value } : {}),
+                ...(voice.value !== undefined ? { voice: voice.value } : {}),
+                ...(audioKind !== undefined ? { audioKind: audioKind } : {}),
+                ...(language.value !== undefined ? { language: language.value } : {}),
+                ...(loop.value !== undefined ? { loop: loop.value } : {}),
+                ...(promptInfluence.value !== undefined ? { promptInfluence: promptInfluence.value } : {}),
+                ...(imageRef.value !== undefined ? { imageRef: imageRef.value } : {}),
+                ...(imageRefs.value !== undefined ? { imageRefs: imageRefs.value } : {}),
+                ...(wireModel.value !== undefined ? { wireModel: wireModel.value } : {}),
+                ...(speechFormat !== undefined ? { speechFormat: speechFormat } : {}),
+            },
+        }
+    });
+}
+function parseTaskId(input) {
+    const id = input.params.id;
+    return typeof id === 'string' && id.length > 0 ? ok({ value: id }) : err({ error: validationError({ message: 'id must be a non-empty path parameter' }) });
+}
+function parseMediaTaskListQuery(input) {
+    const raw = input.query.ownerRef;
+    const ownerRef = Array.isArray(raw) ? raw[0] : raw;
+    if (typeof ownerRef !== 'string' || ownerRef.trim().length === 0) {
+        return err({ error: validationError({ message: 'ownerRef query parameter is required' }, { issues: [{ path: 'ownerRef', message: 'required non-empty string' }] }) });
+    }
+    const includeTerminalRaw = input.query.includeTerminal;
+    const includeTerminal = (Array.isArray(includeTerminalRaw) ? includeTerminalRaw[0] : includeTerminalRaw) === 'true';
+    return ok({ value: { ownerRef, options: { includeTerminal } } });
+}
+/**
+ * Runs the real generation in the background and patches the task to its terminal state.
+ * Deliberately fire-and-forget from `mediaGenerateRoute.handle`'s own perspective — the HTTP
+ * response has already returned the `'queued'` task by the time this settles.
+ */
+async function runMediaGenerationInBackground(deps, taskId, ownerRef, request) {
+    try {
+        await deps.taskStore.update({ id: taskId, patch: { status: 'running' } });
+        const { surface, model, ...options } = request;
+        const result = await deps.engine.generate({ surface, model }, options);
+        const base64 = result.bytes.toString('base64');
+        const mime = mimeTypeForSurface(request.surface, request.speechFormat);
+        await deps.taskStore.update({
+            id: taskId, patch: {
+                status: 'done',
+                file: {
+                    dataUrl: `data:${mime};base64,${base64}`,
+                    providerId: result.providerId,
+                    providerNote: result.providerNote,
+                    ...(result.suggestedExt !== undefined ? { suggestedExt: result.suggestedExt } : {}),
+                    usedStubFallback: result.usedStubFallback,
+                },
+                progress: result.warnings,
+                endedAt: Date.now(),
+            }
+        });
+    }
+    catch (error) {
+        const apiError = reportInternalError(deps, 'media-generate-dispatch', error, taskId, ownerRef);
+        try {
+            await deps.taskStore.update({
+                id: taskId, patch: {
+                    status: 'failed',
+                    error: { message: apiError.message, code: apiError.code },
+                    endedAt: Date.now(),
+                }
+            });
+        }
+        catch (writeError) {
+            // The task store can legitimately already be closed by the time a slow in-flight
+            // generation's failure settles (e.g. daemon shutdown mid-generation — a real vendor call
+            // can take "tens of seconds" per this module's own doc). This function is invoked
+            // fire-and-forget (`void runMediaGenerationInBackground(...)` in `mediaGenerateRoute.handle`
+            // below), so letting this secondary write failure propagate would reject an unobserved
+            // promise — an unhandled rejection that crashes a default-configured Node process over a
+            // condition that isn't actually fatal (the real generation failure was already reported
+            // above; this is only "the store couldn't also persist that fact"). Reported through the
+            // same sink, never rethrown.
+            reportInternalError(deps, 'media-generate-dispatch', writeError, taskId, ownerRef);
+        }
+    }
+}
+/** A minimal, real content-type per surface — enough for a caller to render/play the resulting data URL without needing to know each vendor's own response shape. */
+function mimeTypeForSurface(surface, speechFormat) {
+    if (surface === 'image')
+        return 'image/png';
+    if (surface === 'video')
+        return 'video/mp4';
+    const format = speechFormat ?? 'mp3';
+    const audioMimeByFormat = {
+        mp3: 'audio/mpeg',
+        wav: 'audio/wav',
+        flac: 'audio/flac',
+        aac: 'audio/aac',
+        opus: 'audio/opus',
+    };
+    return audioMimeByFormat[format];
+}
+export const mediaGenerateRoute = defineJsonRoute({
+    method: 'post', path: '/api/media/generate', parse: parseMediaGenerate, handle: async ({ input: { ownerRef, request }, deps }) => {
+        let task;
+        try {
+            task = await deps.taskStore.create({
+                input: {
+                    id: randomUUID(),
+                    ownerRef,
+                    status: 'queued',
+                    surface: request.surface,
+                    model: request.model,
+                }
+            });
+        }
+        catch (error) {
+            return err({ error: reportInternalError(deps, 'media-task-store', error, null, ownerRef) });
+        }
+        void runMediaGenerationInBackground(deps, task.id, ownerRef, request);
+        return ok({ value: { task } });
+    }
+}, { requireSameOrigin: true, successStatus: 202 });
+export const mediaTaskGetRoute = defineJsonRoute({
+    method: 'get', path: '/api/media/tasks/:id', parse: parseTaskId, handle: async ({ input: id, deps }) => {
+        try {
+            const task = await deps.taskStore.get({ id });
+            return task === null ? err({ error: createApiError({ code: 'NOT_FOUND', message: 'media task not found' }) }) : ok({ value: { task } });
+        }
+        catch (error) {
+            return err({ error: reportInternalError(deps, 'media-task-store', error, id, null) });
+        }
+    }
+});
+export const mediaTaskDeleteRoute = defineJsonRoute({
+    method: 'delete', path: '/api/media/tasks/:id', parse: parseTaskId, handle: async ({ input: id, deps }) => {
+        let ownerRef = null;
+        try {
+            const existing = await deps.taskStore.get({ id });
+            if (existing === null)
+                return err({ error: createApiError({ code: 'NOT_FOUND', message: 'media task not found' }) });
+            ownerRef = existing.ownerRef;
+            await deps.taskStore.delete({ id });
+            return ok({ value: { ok: true } });
+        }
+        catch (error) {
+            return err({ error: reportInternalError(deps, 'media-task-store', error, id, ownerRef) });
+        }
+    }
+}, { requireSameOrigin: true });
+export const mediaTaskListRoute = defineJsonRoute({
+    method: 'get', path: '/api/media/tasks', parse: parseMediaTaskListQuery, handle: async ({ input: { ownerRef, options }, deps }) => {
+        try {
+            const tasks = await deps.taskStore.listByOwner({ ownerRef }, options);
+            return ok({ value: { tasks } });
+        }
+        catch (error) {
+            return err({ error: reportInternalError(deps, 'media-task-store', error, null, ownerRef) });
+        }
+    }
+});
+/** Mounts every media route on `app`. A pack's `http(app, services)` calls this directly. */
+export function registerMediaRoutes({ app, deps, adapter }, _optional = {}) {
+    mountJsonRoute({ app, spec: mediaGenerateRoute, deps, adapter });
+    mountJsonRoute({ app, spec: mediaTaskGetRoute, deps, adapter });
+    mountJsonRoute({ app, spec: mediaTaskDeleteRoute, deps, adapter });
+    mountJsonRoute({ app, spec: mediaTaskListRoute, deps, adapter });
+}
+//# sourceMappingURL=media.js.map