@302ai/media-studio-core 0.1.0-beta.0

package/dist/client/session.js

@@ -0,0 +1,91 @@
+import { nanoid } from "nanoid";
+export class ChatSession {
+    sessionId;
+    chat;
+    messages;
+    isTurnActive = false;
+    constructor(chat, options = {}) {
+        this.chat = chat;
+        this.sessionId = options.sessionId ?? nanoid();
+        this.messages = options.initialMessages ? [...options.initialMessages] : [];
+    }
+    /**
+     * Whether a message turn is currently in-flight.
+     */
+    get isBusy() {
+        return this.isTurnActive;
+    }
+    /**
+     * Returns a copy of the current in-memory conversation history.
+     */
+    getMessages() {
+        return [...this.messages];
+    }
+    /**
+     * Clears accumulated turn history while preserving the session ID.
+     */
+    clearHistory() {
+        if (this.isTurnActive) {
+            throw new Error("Cannot clear history while a turn is active.");
+        }
+        this.messages = [];
+    }
+    /**
+     * Sends a user turn within this session.
+     *
+     * Automatically appends the user message to history, dispatches the full
+     * history to the model, and asynchronously appends the assistant's reply
+     * to history once the stream completes.
+     *
+     * Throws an error if another turn is already active on this session.
+     */
+    async sendMessage(prompt, options) {
+        if (this.isTurnActive) {
+            throw new Error("Cannot send message: a turn is already active in this ChatSession.");
+        }
+        this.isTurnActive = true;
+        const userMessage = { role: "user", content: prompt };
+        const turnMessages = [...this.messages, userMessage];
+        this.messages.push(userMessage);
+        let stream;
+        try {
+            stream = await this.chat.stream({
+                sessionId: this.sessionId,
+                messages: turnMessages,
+                chatTaskId: options?.chatTaskId,
+                signal: options?.signal,
+                maxRetries: options?.maxRetries,
+                initialRetryDelayMs: options?.initialRetryDelayMs,
+                onFinalResponse: (finalResponse) => {
+                    this.isTurnActive = false;
+                    this.messages.push({
+                        role: "assistant",
+                        content: finalResponse.text,
+                    });
+                    options?.onFinalResponse?.(finalResponse);
+                },
+                onError: (err) => {
+                    this.isTurnActive = false;
+                    const idx = this.messages.lastIndexOf(userMessage);
+                    if (idx !== -1 && this.messages[idx + 1]?.role !== "assistant") {
+                        this.messages.splice(idx, 1);
+                    }
+                    options?.onError?.(err);
+                },
+            });
+            // Ensure turn is marked inactive once stream settles (e.g. clean completion, early break, or abort)
+            stream.settled.finally(() => {
+                this.isTurnActive = false;
+            });
+        }
+        catch (err) {
+            this.isTurnActive = false;
+            const idx = this.messages.lastIndexOf(userMessage);
+            if (idx !== -1) {
+                this.messages.splice(idx, 1);
+            }
+            throw err;
+        }
+        return stream;
+    }
+}

package/dist/client/sessions.d.ts

@@ -0,0 +1,54 @@
+import { type ListSessionsQuery, type ListSessionsResponse, type PrewarmSessionReady, type SessionPrewarmOutcome, type SessionPrewarmStage, type SessionSource } from "../sessions/types.js";
+export type SessionPrewarmOptions = {
+    sessionId: string;
+    source: SessionSource;
+    note?: string;
+    installUserSkills?: boolean;
+    signal?: AbortSignal;
+    onStageChange?: (stage: SessionPrewarmStage) => void;
+    /**
+     * Fired exactly once, when the first `session_ready` event arrives. That
+     * event is the upstream commit point: the session is durably persisted and
+     * the id is safe to store from this moment on.
+     */
+    onSessionReady?: (session: PrewarmSessionReady) => void;
+};
+/**
+ * Session management against the media-studio gateway: list, remove, and
+ * provision (prewarm) sessions.
+ */
+export declare class ClientSessions {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly customFetch;
+    constructor(baseUrl: string, apiKey: string, customFetch?: typeof fetch);
+    private authHeaders;
+    /**
+     * Lists sessions from the server (the single source of truth).
+     *
+     * @throws {ChatUpstreamError} on HTTP failure.
+     */
+    list(query?: ListSessionsQuery): Promise<ListSessionsResponse>;
+    /**
+     * Deletes a session server-side. Destroys the upstream conversation memory;
+     * this is irreversible.
+     *
+     * @throws {ChatUpstreamError} on HTTP failure.
+     */
+    remove(sessionId: string): Promise<void>;
+    /**
+     * Provisions a session via the prewarm SSE endpoint — the same flow the
+     * web app uses. Streams stage events through `onStageChange` and resolves
+     * to a three-state outcome bounded by the `session_ready` commit point:
+     *
+     * - `ready` — full provisioning completed;
+     * - `fallback` — the session is persisted but sandbox/skills provisioning
+     *   failed or the stream ended early; plain-text chat still works;
+     * - `failed` — the session was never persisted upstream.
+     *
+     * Never call this again with a fresh id after `onSessionReady` fired for an
+     * id — that creates orphan sessions.
+     */
+    prewarm(options: SessionPrewarmOptions): Promise<SessionPrewarmOutcome>;
+    private consumePrewarmStream;
+}

package/dist/client/sessions.js

@@ -0,0 +1,213 @@
+import { createParser } from "eventsource-parser";
+import { DeleteSessionResponseSchema, ListSessionsResponseSchema, PrewarmDoneSchema, PrewarmErrorSchema, PrewarmSandboxReadySchema, PrewarmSessionReadySchema, PrewarmSkillsReadySchema, } from "../sessions/types.js";
+import { ChatUpstreamError, extractUpstreamErrorMessage, } from "../transport/errors.js";
+const PREWARM_TIMEOUT_MS = 60_000;
+const MAX_NETWORK_RETRIES = 2;
+const RETRY_BASE_DELAY_MS = 500;
+function delay(durationMs) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, durationMs);
+    });
+}
+/**
+ * Session management against the media-studio gateway: list, remove, and
+ * provision (prewarm) sessions.
+ */
+export class ClientSessions {
+    baseUrl;
+    apiKey;
+    customFetch;
+    constructor(baseUrl, apiKey, customFetch) {
+        this.baseUrl = baseUrl;
+        this.apiKey = apiKey;
+        this.customFetch = customFetch ?? fetch;
+    }
+    authHeaders() {
+        return { Authorization: `Bearer ${this.apiKey}` };
+    }
+    /**
+     * Lists sessions from the server (the single source of truth).
+     *
+     * @throws {ChatUpstreamError} on HTTP failure.
+     */
+    async list(query) {
+        const params = new URLSearchParams();
+        if (query?.limit !== undefined)
+            params.set("limit", String(query.limit));
+        if (query?.offset !== undefined) {
+            params.set("offset", String(query.offset));
+        }
+        if (query?.note !== undefined)
+            params.set("note", query.note);
+        const search = params.toString();
+        const url = `${this.baseUrl}/api/sessions${search ? `?${search}` : ""}`;
+        const response = await this.customFetch(url, {
+            method: "GET",
+            headers: this.authHeaders(),
+        });
+        if (!response.ok) {
+            const rawBody = await response.text();
+            const message = extractUpstreamErrorMessage(rawBody) ||
+                `Failed to fetch sessions with status ${response.status}`;
+            throw new ChatUpstreamError(message, response.status, rawBody);
+        }
+        const rawJson = await response.json();
+        return ListSessionsResponseSchema.parse(rawJson);
+    }
+    /**
+     * Deletes a session server-side. Destroys the upstream conversation memory;
+     * this is irreversible.
+     *
+     * @throws {ChatUpstreamError} on HTTP failure.
+     */
+    async remove(sessionId) {
+        const url = `${this.baseUrl}/api/sessions?sessionId=${encodeURIComponent(sessionId)}`;
+        const response = await this.customFetch(url, {
+            method: "DELETE",
+            headers: this.authHeaders(),
+        });
+        if (!response.ok) {
+            const rawBody = await response.text();
+            const message = extractUpstreamErrorMessage(rawBody) ||
+                `Failed to delete session with status ${response.status}`;
+            throw new ChatUpstreamError(message, response.status, rawBody);
+        }
+        const rawJson = await response.json();
+        DeleteSessionResponseSchema.parse(rawJson);
+    }
+    /**
+     * Provisions a session via the prewarm SSE endpoint — the same flow the
+     * web app uses. Streams stage events through `onStageChange` and resolves
+     * to a three-state outcome bounded by the `session_ready` commit point:
+     *
+     * - `ready` — full provisioning completed;
+     * - `fallback` — the session is persisted but sandbox/skills provisioning
+     *   failed or the stream ended early; plain-text chat still works;
+     * - `failed` — the session was never persisted upstream.
+     *
+     * Never call this again with a fresh id after `onSessionReady` fired for an
+     * id — that creates orphan sessions.
+     */
+    async prewarm(options) {
+        const { onStageChange, onSessionReady } = options;
+        const timeoutController = new AbortController();
+        const timeout = setTimeout(() => timeoutController.abort(), PREWARM_TIMEOUT_MS);
+        const signal = options.signal
+            ? AbortSignal.any([timeoutController.signal, options.signal])
+            : timeoutController.signal;
+        const state = { sessionReady: null, outcome: null };
+        onStageChange?.("creating");
+        try {
+            for (let attempt = 0; attempt <= MAX_NETWORK_RETRIES; attempt++) {
+                if (state.outcome || signal.aborted)
+                    break;
+                if (attempt > 0)
+                    await delay(attempt * RETRY_BASE_DELAY_MS);
+                try {
+                    const response = await this.customFetch(`${this.baseUrl}/api/sessions/prewarm`, {
+                        method: "POST",
+                        headers: {
+                            ...this.authHeaders(),
+                            Accept: "text/event-stream",
+                            "Content-Type": "application/json",
+                        },
+                        body: JSON.stringify({
+                            sessionId: options.sessionId,
+                            source: options.source,
+                            ...(options.note !== undefined ? { note: options.note } : {}),
+                            ...(options.installUserSkills !== undefined
+                                ? { installUserSkills: options.installUserSkills }
+                                : {}),
+                        }),
+                        signal,
+                    });
+                    if (!response.ok) {
+                        // 4xx (except 429) is deterministic: no point retrying.
+                        const retryable = response.status >= 500 || response.status === 429;
+                        if (!retryable)
+                            break;
+                        continue;
+                    }
+                    await this.consumePrewarmStream(response, state, {
+                        onStageChange,
+                        onSessionReady,
+                    });
+                }
+                catch {
+                    if (signal.aborted)
+                        break;
+                    // Network failure or mid-stream read/parse error: retry until the
+                    // budget is exhausted, then fall back on the session_ready boundary.
+                }
+                if (state.outcome)
+                    break;
+            }
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+        if (state.outcome)
+            return state.outcome;
+        return state.sessionReady
+            ? { status: "fallback", session: state.sessionReady }
+            : { status: "failed" };
+    }
+    async consumePrewarmStream(response, state, callbacks) {
+        if (!response.body)
+            return;
+        const parser = createParser({
+            onEvent(message) {
+                if (!message.data || state.outcome)
+                    return;
+                const data = JSON.parse(message.data);
+                switch (message.event) {
+                    case "session_ready": {
+                        const session = PrewarmSessionReadySchema.parse(data);
+                        if (!state.sessionReady)
+                            callbacks.onSessionReady?.(session);
+                        state.sessionReady = session;
+                        callbacks.onStageChange?.("sandbox");
+                        return;
+                    }
+                    case "sandbox_ready": {
+                        PrewarmSandboxReadySchema.parse(data);
+                        callbacks.onStageChange?.("skills");
+                        return;
+                    }
+                    case "skills_ready": {
+                        PrewarmSkillsReadySchema.parse(data);
+                        callbacks.onStageChange?.("finishing");
+                        return;
+                    }
+                    case "done": {
+                        PrewarmDoneSchema.parse(data);
+                        state.outcome = state.sessionReady
+                            ? { status: "ready", session: state.sessionReady }
+                            : { status: "failed" };
+                        return;
+                    }
+                    case "error": {
+                        PrewarmErrorSchema.parse(data);
+                        state.outcome = state.sessionReady
+                            ? { status: "fallback", session: state.sessionReady }
+                            : { status: "failed" };
+                        return;
+                    }
+                    default:
+                        return;
+                }
+            },
+        });
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            parser.feed(decoder.decode(value, { stream: true }));
+            if (state.outcome)
+                break;
+        }
+        parser.feed(decoder.decode());
+    }
+}

package/dist/client/types.d.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import type { ChatFinalResponse } from "../stream/stream.js";
+import type { ChatUpstreamMessage } from "../transport/types.js";
+export interface MediaStudioClientOptions {
+    apiKey: string;
+    baseUrl?: string | undefined;
+    locale?: string | undefined;
+    fetch?: typeof fetch | undefined;
+}
+export declare const MeResponseSchema: z.ZodObject<{
+    uid: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    apiKeyMasked: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    exp: z.ZodOptional<z.ZodNumber>;
+    valid: z.ZodBoolean;
+}, z.core.$strip>;
+export type MeResponse = z.infer<typeof MeResponseSchema>;
+export interface QuickPromptOptions {
+    sessionId: string;
+    chatTaskId?: string | undefined;
+    signal?: AbortSignal | undefined;
+    maxRetries?: number | undefined;
+    initialRetryDelayMs?: number | undefined;
+    onFinalResponse?: ((res: ChatFinalResponse) => void) | undefined;
+    onError?: ((err: unknown) => void) | undefined;
+}
+export interface ChatTurnOptions {
+    sessionId: string;
+    messages: ChatUpstreamMessage[];
+    chatTaskId?: string | undefined;
+    sinceSeq?: number | string | undefined;
+    modelParams?: unknown;
+    skillUrls?: string[] | undefined;
+    structuredOutput?: boolean | undefined;
+    signal?: AbortSignal | undefined;
+    maxRetries?: number | undefined;
+    initialRetryDelayMs?: number | undefined;
+    onFinalResponse?: ((res: ChatFinalResponse) => void) | undefined;
+    onError?: ((err: unknown) => void) | undefined;
+}
+export interface ChatSessionOptions {
+    sessionId?: string | undefined;
+    initialMessages?: ChatUpstreamMessage[] | undefined;
+}

package/dist/client/types.js

@@ -0,0 +1,9 @@
+import { z } from "zod";
+export const MeResponseSchema = z.object({
+    uid: z.string().nullable().optional(),
+    name: z.string().nullable().optional(),
+    email: z.string().nullable().optional(),
+    apiKeyMasked: z.string().nullable().optional(),
+    exp: z.number().optional(),
+    valid: z.boolean(),
+});

package/dist/events.d.ts

@@ -0,0 +1,90 @@
+import { z } from "zod";
+/** Text part delta in streaming turn. */
+export declare const TextDeltaEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"text-delta">;
+    delta: z.ZodString;
+    id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Reasoning / thinking part delta in streaming turn. */
+export declare const ReasoningDeltaEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"reasoning-delta">;
+    delta: z.ZodString;
+    id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Tool invocation event emitted when assistant calls an external tool. */
+export declare const ToolCallEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"tool-call">;
+    toolCallId: z.ZodString;
+    toolName: z.ZodString;
+    args: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+/** Tool result response emitted after tool execution finishes. */
+export declare const ToolResultEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"tool-result">;
+    toolCallId: z.ZodString;
+    result: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+/** High-level media result event emitted when image/video generation completes. */
+export declare const MediaResultEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"media-result">;
+    result: z.ZodObject<{
+        status: z.ZodOptional<z.ZodString>;
+        domain: z.ZodOptional<z.ZodString>;
+        operation: z.ZodOptional<z.ZodString>;
+        modelUsed: z.ZodOptional<z.ZodString>;
+        taskId: z.ZodOptional<z.ZodString>;
+        resultUrl: z.ZodOptional<z.ZodString>;
+        prompt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/** Terminal finish event indicating turn completion. */
+export declare const FinishEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"finish">;
+    finishReason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Stream error event. Supports either error or message string. */
+export declare const StreamErrorEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"error">;
+    error: z.ZodOptional<z.ZodString>;
+    message: z.ZodOptional<z.ZodString>;
+    chatTaskId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Discriminated union of all possible streaming events yielded by ChatStream. */
+export declare const ChatStreamEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"text-delta">;
+    delta: z.ZodString;
+    id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"reasoning-delta">;
+    delta: z.ZodString;
+    id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"tool-call">;
+    toolCallId: z.ZodString;
+    toolName: z.ZodString;
+    args: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"tool-result">;
+    toolCallId: z.ZodString;
+    result: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"media-result">;
+    result: z.ZodObject<{
+        status: z.ZodOptional<z.ZodString>;
+        domain: z.ZodOptional<z.ZodString>;
+        operation: z.ZodOptional<z.ZodString>;
+        modelUsed: z.ZodOptional<z.ZodString>;
+        taskId: z.ZodOptional<z.ZodString>;
+        resultUrl: z.ZodOptional<z.ZodString>;
+        prompt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"finish">;
+    finishReason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"error">;
+    error: z.ZodOptional<z.ZodString>;
+    message: z.ZodOptional<z.ZodString>;
+    chatTaskId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "type">;
+export type ChatStreamEvent = z.infer<typeof ChatStreamEventSchema>;

package/dist/format/tool-formatter.d.ts

@@ -0,0 +1,31 @@
+export type ToolCategory = "agent" | "create" | "model" | "search" | "file" | "bash" | "skill" | "other";
+export interface FormattedToolMilestone {
+    rawName: string;
+    normalizedName: string;
+    category: ToolCategory;
+    milestoneLine: string;
+    actionLabel: string;
+    details: {
+        model?: string;
+        aspectRatio?: string;
+        duration?: string;
+        resolution?: string;
+        voice?: string;
+        operation?: string;
+        subagentType?: string;
+        description?: string;
+        target?: string;
+        query?: string;
+    };
+}
+/**
+ * 1:1 normalization parity with main project's `normalizeMcpToolName`.
+ * Strips `tool-` prefix, lowercases, resolves MCP namespaces (`mcp__server__name`),
+ * and trims trailing `output` suffix.
+ */
+export declare function normalizeMcpToolName(toolName: string): string;
+/**
+ * Parses and formats a tool call into a structured milestone and dynamic action label.
+ * Fully aligned 1:1 with the main project's tool renderer hierarchy.
+ */
+export declare function formatToolMilestone(toolName: string, args: unknown): FormattedToolMilestone;