@atomic-chat/core 0.5.1

package/dist/server/public/trace.js

@@ -0,0 +1,223 @@
+/**
+ * The record of one request as it goes through the Local API Server, and the `api:request` events
+ * made from it: the analytics observation the app aggregates, and — only while the app's API screen
+ * is open — the inspector's started / progress / finished view.
+ *
+ * Ported from: src-tauri/src/core/server/proxy.rs (`EmitState`, `proxy_request`),
+ * src-tauri/src/core/server/request_inspector.rs (`RequestInspector::begin`, `InspectorHandle`).
+ *
+ * The request is closed when its response closes, however that happens — the whole body sent, the
+ * client gone, the upstream stalled — so there is no finish call to forget on an early return, which
+ * is what the Rust `FinishGuard` exists to prevent.
+ *
+ * One deliberate difference: time to first token is measured from the moment the request arrived.
+ * The Rust relay measured it from the start of the relay task in the finished event but from the
+ * request's arrival in progress events, so the same request reported two different numbers.
+ */
+import { randomBytes } from 'node:crypto';
+import { clientMaxTokens } from './errors.js';
+import { promptPreview, StreamTelemetry } from './telemetry.js';
+const PROGRESS_INTERVAL_MS = 1000;
+/** Above this many requests in flight progress events stop: the dashboard is saturated already. */
+const PROGRESS_INFLIGHT_CEILING = 64;
+let nextSeq = 0;
+let inFlight = 0;
+export function endpointFromPath(path) {
+    switch (path) {
+        case '/chat/completions':
+            return 'chat/completions';
+        case '/responses':
+            return 'responses';
+        case '/messages':
+            return 'messages';
+        case '/completions':
+            return 'completions';
+        case '/embeddings':
+            return 'embeddings';
+        case '/messages/count_tokens':
+            return 'messages/count_tokens';
+        case '/images/generations':
+            return 'images/generations';
+        case '/videos':
+            return 'videos';
+        case '/models':
+            return 'models';
+        case '/muse-code/models':
+            return 'muse-code/models';
+        case '/metrics':
+            return 'metrics';
+        default:
+            return path.startsWith('/videos/') ? 'videos' : 'other';
+    }
+}
+const now = () => performance.now();
+export class RequestTrace {
+    method;
+    deps;
+    endpoint;
+    modelId = null;
+    backend = 'unknown';
+    provider = null;
+    stream = false;
+    anthropicFallback = false;
+    errorKind = null;
+    /** Not product traffic (preflight, docs, model polling, scanners): no analytics, no inspector row. */
+    skipEmit = false;
+    upstreamStatus = null;
+    oomDetected = false;
+    ctxOverflowDetected = false;
+    /** Streamed telemetry for the inspector, when a relay collected any. */
+    telemetry;
+    startedAt = now();
+    startedAtMs = Date.now();
+    headersAt;
+    id = `apireq_${randomBytes(6).toString('hex')}`;
+    seq;
+    announced = false;
+    closed = false;
+    lastProgress = 0;
+    stashed;
+    constructor(method, deps) {
+        this.method = method;
+        this.deps = deps;
+        // Watching is decided once, at arrival, as the app's inspector does: a request never switches
+        // halfway between carrying previews and not.
+        if (deps.emit && deps.inspecting?.()) {
+            this.seq = nextSeq++;
+            inFlight++;
+        }
+    }
+    /** Whether the inspector is watching this request (previews and telemetry are collected). */
+    get inspecting() {
+        return this.seq !== undefined;
+    }
+    /** Ties the trace to its response: headers time on `writeHead`, the finish on `close`. */
+    attach(res) {
+        const writeHead = res.writeHead.bind(res);
+        res.writeHead = (...args) => {
+            this.headersAt ??= now();
+            return writeHead(...args);
+        };
+        res.once('close', () => this.close(res));
+    }
+    /**
+     * The inspector's `request-started`, with the prompt preview when the body is known. Idempotent:
+     * a body-parse site announces with detail, the close announces without for everything else.
+     */
+    announce(body, raw) {
+        if (this.seq === undefined || this.announced)
+            return;
+        this.announced = true;
+        const preview = body !== undefined ? promptPreview(body) : undefined;
+        this.deps.emit?.('api:request', {
+            phase: 'started',
+            id: this.id,
+            seq: this.seq,
+            started_at_ms: this.startedAtMs,
+            endpoint: this.endpoint ?? 'other',
+            method: this.method,
+            model_id: this.modelId,
+            stream: this.stream,
+            message_count: preview?.message_count ?? null,
+            prompt_preview: preview?.text ?? null,
+            prompt_chars: preview?.chars ?? null,
+            has_non_text_parts: preview?.has_non_text_parts ?? false,
+            client_max_tokens: raw ? (clientMaxTokens(raw) ?? null) : null,
+        });
+    }
+    /** A telemetry collector, when the inspector is watching. */
+    startTelemetry() {
+        if (!this.inspecting)
+            return undefined;
+        this.telemetry ??= new StreamTelemetry();
+        return this.telemetry;
+    }
+    /** Telemetry from a whole (non-streamed) response body: there is no time to first token. */
+    stash(fields) {
+        this.stashed = { ...fields, ttft_ms: null };
+    }
+    /** A throttled progress tick for a long stream. */
+    progress() {
+        if (this.seq === undefined || this.closed || !this.telemetry)
+            return;
+        if (inFlight > PROGRESS_INFLIGHT_CEILING)
+            return;
+        const elapsed = Math.floor(now() - this.startedAt);
+        if (elapsed - this.lastProgress < PROGRESS_INTERVAL_MS)
+            return;
+        this.lastProgress = elapsed;
+        this.deps.emit?.('api:request', {
+            phase: 'progress',
+            id: this.id,
+            seq: this.seq,
+            ttft_ms: this.telemetry.ttftMs(this.startedAt),
+            completion_tokens: this.telemetry.completionTokensOrEstimate(),
+            reply_chars: this.telemetry.replyChars,
+            elapsed_ms: elapsed,
+        });
+    }
+    close(res) {
+        if (this.closed)
+            return;
+        this.closed = true;
+        if (this.seq !== undefined)
+            inFlight = Math.max(0, inFlight - 1);
+        if (!this.deps.emit)
+            return;
+        const end = now();
+        const headers = this.headersAt ?? end;
+        const status = res.headersSent ? res.statusCode : 0;
+        if (!this.skipEmit)
+            this.announce();
+        const observation = this.skipEmit
+            ? null
+            : {
+                endpoint: this.endpoint ?? 'other',
+                method: this.method,
+                model_id: this.modelId,
+                backend: this.backend,
+                provider: this.provider,
+                stream: this.stream,
+                status,
+                latency_ms: Math.floor(headers - this.startedAt),
+                is_anthropic_fallback: this.anthropicFallback,
+                error_kind: this.errorKind,
+                upstream_status: this.upstreamStatus,
+                oom_detected: this.oomDetected,
+                ctx_overflow_detected: this.ctxOverflowDetected,
+            };
+        let finish = null;
+        if (this.announced) {
+            const telemetry = this.telemetry?.finishFields(this.startedAt) ?? this.stashed;
+            finish = {
+                ttft_ms: null,
+                prompt_tokens: null,
+                completion_tokens: null,
+                total_tokens: null,
+                tokens_estimated: false,
+                prompt_per_second: null,
+                predicted_per_second: null,
+                finish_reason: null,
+                reply_preview: null,
+                reply_chars: null,
+                ...telemetry,
+                status: status || null,
+                error_kind: this.errorKind,
+                aborted: !res.writableFinished,
+                headers_ms: Math.floor(headers - this.startedAt),
+                duration_ms: Math.floor(end - this.startedAt),
+            };
+        }
+        if (!observation && !finish)
+            return;
+        this.deps.emit('api:request', {
+            phase: 'finished',
+            id: this.id,
+            seq: this.seq ?? -1,
+            finished_at_ms: Date.now(),
+            observation,
+            finish,
+        });
+    }
+}
+//# sourceMappingURL=trace.js.map

package/dist/server/public/trace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.js","sourceRoot":"","sources":["../../../src/server/public/trace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAIzC,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAI/D,MAAM,oBAAoB,GAAG,IAAI,CAAA;AACjC,mGAAmG;AACnG,MAAM,yBAAyB,GAAG,EAAE,CAAA;AAEpC,IAAI,OAAO,GAAG,CAAC,CAAA;AACf,IAAI,QAAQ,GAAG,CAAC,CAAA;AAEhB,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,mBAAmB;YACtB,OAAO,kBAAkB,CAAA;QAC3B,KAAK,YAAY;YACf,OAAO,WAAW,CAAA;QACpB,KAAK,WAAW;YACd,OAAO,UAAU,CAAA;QACnB,KAAK,cAAc;YACjB,OAAO,aAAa,CAAA;QACtB,KAAK,aAAa;YAChB,OAAO,YAAY,CAAA;QACrB,KAAK,wBAAwB;YAC3B,OAAO,uBAAuB,CAAA;QAChC,KAAK,qBAAqB;YACxB,OAAO,oBAAoB,CAAA;QAC7B,KAAK,SAAS;YACZ,OAAO,QAAQ,CAAA;QACjB,KAAK,SAAS;YACZ,OAAO,QAAQ,CAAA;QACjB,KAAK,mBAAmB;YACtB,OAAO,kBAAkB,CAAA;QAC3B,KAAK,UAAU;YACb,OAAO,SAAS,CAAA;QAClB;YACE,OAAO,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAA;IAC3D,CAAC;AACH,CAAC;AAED,MAAM,GAAG,GAAG,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,CAAA;AAEnC,MAAM,OAAO,YAAY;IA2BJ;IACA;IA3BnB,QAAQ,CAAoB;IAC5B,OAAO,GAAkB,IAAI,CAAA;IAC7B,OAAO,GAAG,SAAS,CAAA;IACnB,QAAQ,GAAkB,IAAI,CAAA;IAC9B,MAAM,GAAG,KAAK,CAAA;IACd,iBAAiB,GAAG,KAAK,CAAA;IACzB,SAAS,GAAkB,IAAI,CAAA;IAC/B,sGAAsG;IACtG,QAAQ,GAAG,KAAK,CAAA;IAChB,cAAc,GAAkB,IAAI,CAAA;IACpC,WAAW,GAAG,KAAK,CAAA;IACnB,mBAAmB,GAAG,KAAK,CAAA;IAC3B,wEAAwE;IACxE,SAAS,CAA6B;IAErB,SAAS,GAAG,GAAG,EAAE,CAAA;IACjB,WAAW,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;IACjC,SAAS,CAAoB;IACpB,EAAE,GAAG,UAAU,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAA;IAC/C,GAAG,CAAoB;IAChC,SAAS,GAAG,KAAK,CAAA;IACjB,MAAM,GAAG,KAAK,CAAA;IACd,YAAY,GAAG,CAAC,CAAA;IAChB,OAAO,CAA6B;IAE5C,YACmB,MAAc,EACd,IAAsB;QADtB,WAAM,GAAN,MAAM,CAAQ;QACd,SAAI,GAAJ,IAAI,CAAkB;QAEvC,8FAA8F;QAC9F,6CAA6C;QAC7C,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,UAAU,EAAE,EAAE,EAAE,CAAC;YACrC,IAAI,CAAC,GAAG,GAAG,OAAO,EAAE,CAAA;YACpB,QAAQ,EAAE,CAAA;QACZ,CAAC;IACH,CAAC;IAED,6FAA6F;IAC7F,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,GAAG,KAAK,SAAS,CAAA;IAC/B,CAAC;IAED,0FAA0F;IAC1F,MAAM,CAAC,GAAmB;QACxB,MAAM,SAAS,GAAG,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAA2C,CAClF;QAAC,GAAwE,CAAC,SAAS,GAAG,CACrF,GAAG,IAAe,EAClB,EAAE;YACF,IAAI,CAAC,SAAS,KAAK,GAAG,EAAE,CAAA;YACxB,OAAO,SAAS,CAAC,GAAG,IAAI,CAAC,CAAA;QAC3B,CAAC,CAAA;QACD,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAA;IAC1C,CAAC;IAED;;;OAGG;IACH,QAAQ,CAAC,IAAgB,EAAE,GAAY;QACrC,IAAI,IAAI,CAAC,GAAG,KAAK,SAAS,IAAI,IAAI,CAAC,SAAS;YAAE,OAAM;QACpD,IAAI,CAAC,SAAS,GAAG,IAAI,CAAA;QACrB,MAAM,OAAO,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;QACpE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,aAAa,EAAE;YAC9B,KAAK,EAAE,SAAS;YAChB,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,aAAa,EAAE,IAAI,CAAC,WAAW;YAC/B,QAAQ,EAAE,IAAI,CAAC,QAAQ,IAAI,OAAO;YAClC,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,QAAQ,EAAE,IAAI,CAAC,OAAO;YACtB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,aAAa,EAAE,OAAO,EAAE,aAAa,IAAI,IAAI;YAC7C,cAAc,EAAE,OAAO,EAAE,IAAI,IAAI,IAAI;YACrC,YAAY,EAAE,OAAO,EAAE,KAAK,IAAI,IAAI;YACpC,kBAAkB,EAAE,OAAO,EAAE,kBAAkB,IAAI,KAAK;YACxD,iBAAiB,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI;SAC/D,CAAC,CAAA;IACJ,CAAC;IAED,6DAA6D;IAC7D,cAAc;QACZ,IAAI,CAAC,IAAI,CAAC,UAAU;YAAE,OAAO,SAAS,CAAA;QACtC,IAAI,CAAC,SAAS,KAAK,IAAI,eAAe,EAAE,CAAA;QACxC,OAAO,IAAI,CAAC,SAAS,CAAA;IACvB,CAAC;IAED,4FAA4F;IAC5F,KAAK,CAAC,MAAuB;QAC3B,IAAI,CAAC,OAAO,GAAG,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;IAC7C,CAAC;IAED,mDAAmD;IACnD,QAAQ;QACN,IAAI,IAAI,CAAC,GAAG,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,SAAS;YAAE,OAAM;QACpE,IAAI,QAAQ,GAAG,yBAAyB;YAAE,OAAM;QAChD,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,CAAA;QAClD,IAAI,OAAO,GAAG,IAAI,CAAC,YAAY,GAAG,oBAAoB;YAAE,OAAM;QAC9D,IAAI,CAAC,YAAY,GAAG,OAAO,CAAA;QAC3B,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,aAAa,EAAE;YAC9B,KAAK,EAAE,UAAU;YACjB,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC;YAC9C,iBAAiB,EAAE,IAAI,CAAC,SAAS,CAAC,0BAA0B,EAAE;YAC9D,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,UAAU;YACtC,UAAU,EAAE,OAAO;SACpB,CAAC,CAAA;IACJ,CAAC;IAEO,KAAK,CAAC,GAAmB;QAC/B,IAAI,IAAI,CAAC,MAAM;YAAE,OAAM;QACvB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAA;QAClB,IAAI,IAAI,CAAC,GAAG,KAAK,SAAS;YAAE,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,GAAG,CAAC,CAAC,CAAA;QAChE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;YAAE,OAAM;QAE3B,MAAM,GAAG,GAAG,GAAG,EAAE,CAAA;QACjB,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,IAAI,GAAG,CAAA;QACrC,MAAM,MAAM,GAAG,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAA;QACnD,IAAI,CAAC,IAAI,CAAC,QAAQ;YAAE,IAAI,CAAC,QAAQ,EAAE,CAAA;QAEnC,MAAM,WAAW,GAAiC,IAAI,CAAC,QAAQ;YAC7D,CAAC,CAAC,IAAI;YACN,CAAC,CAAC;gBACE,QAAQ,EAAE,IAAI,CAAC,QAAQ,IAAI,OAAO;gBAClC,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,QAAQ,EAAE,IAAI,CAAC,OAAO;gBACtB,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,MAAM;gBACN,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC;gBAChD,qBAAqB,EAAE,IAAI,CAAC,iBAAiB;gBAC7C,UAAU,EAAE,IAAI,CAAC,SAAS;gBAC1B,eAAe,EAAE,IAAI,CAAC,cAAc;gBACpC,YAAY,EAAE,IAAI,CAAC,WAAW;gBAC9B,qBAAqB,EAAE,IAAI,CAAC,mBAAmB;aAChD,CAAA;QAEL,IAAI,MAAM,GAAkC,IAAI,CAAA;QAChD,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC,OAAO,CAAA;YAC9E,MAAM,GAAG;gBACP,OAAO,EAAE,IAAI;gBACb,aAAa,EAAE,IAAI;gBACnB,iBAAiB,EAAE,IAAI;gBACvB,YAAY,EAAE,IAAI;gBAClB,gBAAgB,EAAE,KAAK;gBACvB,iBAAiB,EAAE,IAAI;gBACvB,oBAAoB,EAAE,IAAI;gBAC1B,aAAa,EAAE,IAAI;gBACnB,aAAa,EAAE,IAAI;gBACnB,WAAW,EAAE,IAAI;gBACjB,GAAG,SAAS;gBACZ,MAAM,EAAE,MAAM,IAAI,IAAI;gBACtB,UAAU,EAAE,IAAI,CAAC,SAAS;gBAC1B,OAAO,EAAE,CAAC,GAAG,CAAC,gBAAgB;gBAC9B,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC;gBAChD,WAAW,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC;aAC9C,CAAA;QACH,CAAC;QACD,IAAI,CAAC,WAAW,IAAI,CAAC,MAAM;YAAE,OAAM;QACnC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE;YAC5B,KAAK,EAAE,UAAU;YACjB,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,GAAG,EAAE,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;YACnB,cAAc,EAAE,IAAI,CAAC,GAAG,EAAE;YAC1B,WAAW;YACX,MAAM;SACP,CAAC,CAAA;IACJ,CAAC;CACF"}

package/dist/server/public/types.d.ts

@@ -0,0 +1,131 @@
+/**
+ * What the public API server needs from the rest of the core, and how it is configured.
+ *
+ * Deliberately narrow and injected: the server is replayed against the Rust proxy's recorded
+ * exchanges (`test/contract/proxy-http.test.ts`) with stub sessions, stub providers and a scripted
+ * context-increase outcome, so none of this may reach for a runtime or a settings file directly.
+ */
+import type { CoreEvents, DiffusionErrorBody, DiffusionFamilyDefaults, DiffusionFamilyRanges, DiffusionModality, GalleryListOptions, GalleryVideoItem, ImageGenerateRequest, ImageJob, VideoGalleryPage, VideoGenerateRequest, VideoJob } from '../../contracts/index.js';
+import type { LocalProvider, RemoteProvider } from '../../router/index.js';
+import type { ChatGptBackend } from '../../cloud/index.js';
+import type { ErrorSink } from '../../telemetry/index.js';
+/** A model a local engine is serving right now. */
+export interface LocalTarget {
+    provider: LocalProvider;
+    modelId: string;
+    port: number;
+    /** Per-session bearer the engine expects; empty for MLX, which has no auth layer. */
+    apiKey: string;
+    isEmbedding: boolean;
+}
+/** What asking the owning runtime for a larger context produced. */
+export interface CtxIncreaseOutcome {
+    ok: boolean;
+    new_ctx_len?: number;
+    reason?: string;
+}
+/** The resident image model as `POST /images/generations` needs it: who it is, and how a job runs. */
+export interface ImagesBackend {
+    /** The loaded model with the family defaults it was loaded with, or `undefined` when there is none. */
+    loaded: () => {
+        modelId: string;
+        displayName: string;
+        defaults: DiffusionFamilyDefaults;
+    } | undefined;
+    /** Start a job; `done` settles with the outcome and never rejects. */
+    start: (request: ImageGenerateRequest) => Promise<{
+        id: string;
+        done: Promise<{
+            ok: true;
+            outcome: {
+                job: ImageJob;
+                images: Buffer[];
+            };
+        } | {
+            ok: false;
+            error: DiffusionErrorBody;
+        }>;
+    }>;
+    /** Give up on a job the client no longer waits for. */
+    cancel: (jobId: string) => Promise<unknown>;
+}
+/** The resident video model as `/videos` needs it, plus the two places a video lives: the runner and the gallery. */
+export interface VideosBackend {
+    /** The loaded model with the family defaults and ranges it was loaded with, or `undefined` when there is none. */
+    loaded: () => {
+        modelId: string;
+        displayName: string;
+        modality: DiffusionModality;
+        defaults: DiffusionFamilyDefaults;
+        ranges: DiffusionFamilyRanges;
+    } | undefined;
+    /** Start a job; `done` settles with the outcome and never rejects. */
+    start: (request: VideoGenerateRequest) => Promise<{
+        id: string;
+        done: Promise<{
+            ok: true;
+            outcome: {
+                job: VideoJob;
+                images: Buffer[];
+            };
+        } | {
+            ok: false;
+            error: DiffusionErrorBody;
+        }>;
+    }>;
+    /** The runner's record of a job, while it keeps one. */
+    job: (id: string) => VideoJob | null;
+    /** Every video job the runner remembers, newest first. */
+    jobs: () => VideoJob[];
+    /** The gallery's clip, which outlives the job record. */
+    item: (id: string) => Promise<GalleryVideoItem | null>;
+    list: (options: GalleryListOptions) => Promise<VideoGalleryPage>;
+    cancel: (jobId: string) => Promise<unknown>;
+    delete: (id: string) => Promise<void>;
+}
+export interface PublicServerDeps {
+    /** The session `provider` serves for `modelId`, matched with the proxy's `.`/`_` rule. */
+    findLocal: (provider: LocalProvider, modelId: string) => LocalTarget | undefined;
+    /** Every loaded session, in `LOCAL_SEARCH_ORDER` provider order. */
+    listLocal: () => LocalTarget[];
+    /** Registered cloud providers, keyed by provider id. */
+    providers: () => ReadonlyMap<string, RemoteProvider>;
+    /**
+     * Reload a local model with a larger context because a request overflowed it. In the app this was
+     * a round trip to the llama.cpp extension; in the core it is the runtime's own `increaseCtx`.
+     */
+    increaseCtx: (provider: LocalProvider, modelId: string, trigger: string) => Promise<CtxIncreaseOutcome>;
+    /**
+     * Whether the app's API screen is watching. Only then are prompt and reply previews and stream
+     * telemetry collected (ATO-113); the analytics observation is sent regardless.
+     */
+    inspecting?: () => boolean;
+    /** The ChatGPT subscription, for models registered under the `chatgpt` provider. */
+    chatgpt?: ChatGptBackend;
+    /**
+     * Hosts trusted for this one request besides the configured ones: the live tunnel name, and the
+     * accepted socket's own address when the listener is reachable from the LAN. Asked per request,
+     * not per connection — a keep-alive connection outlives a tunnel (see `dynamic-hosts.ts`).
+     */
+    dynamicTrustedHosts?: (localAddress: string | undefined) => readonly string[];
+    emit?: <K extends keyof CoreEvents>(name: K, payload: CoreEvents[K]) => void;
+    fetch?: typeof fetch;
+    /** Image generation on the resident image model; without it the route answers 503. */
+    images?: ImagesBackend;
+    /** The video counterpart, for `/videos`. */
+    videos?: VideosBackend;
+    /** Where a request that failed on our side, or a failing local engine, is reported. */
+    errors?: ErrorSink | undefined;
+}
+export interface PublicServerConfig {
+    host: string;
+    port: number;
+    /** Normalised: `''` or `/segment` without a trailing slash. */
+    prefix: string;
+    /** Key clients must present; empty disables the check. */
+    apiKey: string;
+    /** Hosts allowed besides the built-in loopback names; `*` allows every host. */
+    trustedHosts: string[];
+    /** Timeout for requests to a cloud provider, in seconds (the proxy's `proxy_timeout`). */
+    proxyTimeoutSecs: number;
+}

package/dist/server/public/types.js

@@ -0,0 +1,9 @@
+/**
+ * What the public API server needs from the rest of the core, and how it is configured.
+ *
+ * Deliberately narrow and injected: the server is replayed against the Rust proxy's recorded
+ * exchanges (`test/contract/proxy-http.test.ts`) with stub sessions, stub providers and a scripted
+ * context-increase outcome, so none of this may reach for a runtime or a settings file directly.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/server/public/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/server/public/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/server/public/videos-params.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The client's `/v1/videos` bodies and the objects it reads back, in the shape of the OpenAI Videos
+ * API, structurally validated but not yet bound to a model. Pure: what the facade in `videos.ts`
+ * parses and serialises.
+ */
+import type { DiffusionFamilyDefaults, DiffusionFamilyRanges, GalleryVideoItem, VideoGenerateRequest, VideoJob } from '../../contracts/index.js';
+export declare const MAX_SECONDS = 600;
+export declare const DEFAULT_LIST_LIMIT = 20;
+export declare const MAX_LIST_LIMIT = 100;
+export interface VideosParams {
+    model?: string;
+    prompt: string;
+    /** Clip length the client asked for; absent = the family's default frame count. */
+    seconds?: number;
+    /** Absent = the loaded family's default size. */
+    size?: {
+        width: number;
+        height: number;
+    };
+    seed?: number;
+    negativePrompt?: string;
+}
+/**
+ * `'768x512'` → the dimensions; `'auto'` or `''` → `undefined`. Unlike the image facade this sets no
+ * bounds of its own: a video family's range and grid differ per model, and the runner holds the
+ * request to them.
+ */
+export declare function parseVideoSize(size: string): {
+    width: number;
+    height: number;
+} | undefined;
+export declare function parseVideoParams(body: unknown): VideosParams;
+/** The loaded video family as the facade needs it. */
+export interface LoadedVideoModel {
+    modelId: string;
+    displayName: string;
+    modality: 'image' | 'video';
+    defaults: DiffusionFamilyDefaults;
+    ranges: DiffusionFamilyRanges;
+}
+/**
+ * Bind the request to the loaded family: steps, guidance, sampler and the default size are what the
+ * model was loaded with; `seconds` becomes the nearest valid frame count, clamped to the family's range.
+ */
+export declare function buildVideoRequest(params: VideosParams, loaded: LoadedVideoModel): VideoGenerateRequest;
+export type OpenAiVideoStatus = 'queued' | 'in_progress' | 'completed' | 'failed';
+/** The video object of the OpenAI Videos API, with the core's own facts under `atomic`. */
+export interface OpenAiVideo {
+    id: string;
+    object: 'video';
+    model: string;
+    status: OpenAiVideoStatus;
+    /** 0..100. */
+    progress: number;
+    created_at: number;
+    completed_at: number | null;
+    expires_at: null;
+    /** The clip length as OpenAI writes it: a string of seconds. */
+    seconds: string;
+    size: string;
+    prompt: string;
+    remixed_from_video_id: null;
+    error: {
+        code: string;
+        message: string;
+    } | null;
+    atomic: {
+        job_id: string;
+        seed: number | null;
+        path: string | null;
+        poster_path: string | null;
+    };
+}
+export declare function videoStatusOf(state: VideoJob['state']): OpenAiVideoStatus;
+export declare function videoObjectFromJob(job: VideoJob): OpenAiVideo;
+/** A clip the gallery still holds after the job record is gone: always completed. */
+export declare function videoObjectFromItem(item: GalleryVideoItem): OpenAiVideo;
+export type VideoPathMatch = {
+    kind: 'collection';
+} | {
+    kind: 'video';
+    id: string;
+} | {
+    kind: 'content';
+    id: string;
+};
+/** `/videos`, `/videos/{id}` and `/videos/{id}/content`; anything else under `/videos/` is nothing. */
+export declare function matchVideoPath(path: string): VideoPathMatch | undefined;
+/** The methods a matched path accepts, for the 405's `Allow`. */
+export declare function allowedVideoMethods(match: VideoPathMatch): string[];
+/** `?limit&after&order` of the listing; `order` is accepted and the list is newest first either way. */
+export declare function parseListQuery(query: string | undefined): {
+    limit: number;
+    after?: string;
+};