@someonegg/codex-hub 0.0.0-stage → 0.1.0

package/dist/server/server/repository/timeline-prefix-index.js

@@ -0,0 +1,342 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+const PREFIX_BYTES = 24;
+const PREFIX_PROTOCOL = "timeline-prefix-v2";
+export function deriveTimelinePrefixIndex(normalized, prefixKey) {
+    const states = new Uint8Array((normalized.timeline.length + 1) * PREFIX_BYTES);
+    let previousOrdinal;
+    let itemIndex = 0;
+    let state = createHmac("sha256", prefixKey)
+        .update(PREFIX_PROTOCOL, "utf8")
+        .update("\0", "utf8")
+        .update(normalized.session.id, "utf8")
+        .digest()
+        .subarray(0, PREFIX_BYTES);
+    states.set(state, 0);
+    for (const item of normalized.timeline) {
+        validateOrdinal(item.ordinal, previousOrdinal);
+        previousOrdinal = item.ordinal;
+        itemIndex += 1;
+        state = advancePrefix(state, item, normalized, prefixKey);
+        states.set(state, itemIndex * PREFIX_BYTES);
+    }
+    return TimelinePrefixIndex.fromCompleteStates(itemIndex, states);
+}
+export function extendsTimelinePrefix(previous, next) {
+    if (previous.session.id !== next.session.id || previous.timeline.length > next.timeline.length) {
+        return false;
+    }
+    for (let index = 0; index < previous.timeline.length; index += 1) {
+        const item = previous.timeline[index];
+        if (item !== next.timeline[index])
+            return false;
+        if (item.kind === "tool" &&
+            previous.toolDetails.get(item.id) !== next.toolDetails.get(item.id)) {
+            return false;
+        }
+        if (item.kind === "directive" &&
+            previous.directiveDetails.get(item.id) !== next.directiveDetails.get(item.id)) {
+            return false;
+        }
+        if (item.kind === "internal" &&
+            previous.internalDetails.get(item.id) !== next.internalDetails.get(item.id)) {
+            return false;
+        }
+    }
+    return true;
+}
+export function extendTimelinePrefixIndex(previousIndex, previous, next, prefixKey, 
+/** Internal callers may skip a continuity scan they have just completed. */
+continuityValidated = false) {
+    if (!continuityValidated && !extendsTimelinePrefix(previous, next)) {
+        throw new Error("Cannot extend a timeline prefix index across a changed prefix");
+    }
+    return TimelinePrefixIndex.fromAppend(previousIndex, previous, next, prefixKey);
+}
+export class TimelinePrefixIndex {
+    #itemCount;
+    #segments;
+    #segmentEnds;
+    constructor(itemCount, segments) {
+        this.#itemCount = itemCount;
+        this.#segments = segments;
+        const segmentEnds = [];
+        let storedSlots = 0;
+        for (const segment of segments) {
+            if (segment.byteLength === 0 || segment.byteLength % PREFIX_BYTES !== 0) {
+                throw new Error("Timeline prefix index has an invalid segment byte length");
+            }
+            storedSlots += segment.byteLength / PREFIX_BYTES;
+            segmentEnds.push(storedSlots);
+        }
+        if (storedSlots !== itemCount + 1) {
+            throw new Error("Timeline prefix index has an invalid byte length");
+        }
+        this.#segmentEnds = segmentEnds;
+    }
+    static fromCompleteStates(itemCount, states) {
+        return new TimelinePrefixIndex(itemCount, [states.slice()]);
+    }
+    static fromAppend(previous, previousNormalized, normalized, prefixKey) {
+        const previousItemCount = previousNormalized.timeline.length;
+        if (previous.#itemCount !== previousItemCount ||
+            normalized.timeline.length <= previousItemCount) {
+            throw new Error("Timeline prefix index does not match the append boundary");
+        }
+        const appendedCount = normalized.timeline.length - previousItemCount;
+        const appendedStates = new Uint8Array(appendedCount * PREFIX_BYTES);
+        let previousOrdinal = normalized.timeline[previousItemCount - 1]?.ordinal;
+        let state = previous.#slot(previousItemCount);
+        for (let itemIndex = previousItemCount; itemIndex < normalized.timeline.length; itemIndex += 1) {
+            const item = normalized.timeline[itemIndex];
+            validateOrdinal(item.ordinal, previousOrdinal);
+            previousOrdinal = item.ordinal;
+            state = advancePrefix(state, item, normalized, prefixKey);
+            appendedStates.set(state, (itemIndex - previousItemCount) * PREFIX_BYTES);
+        }
+        return new TimelinePrefixIndex(normalized.timeline.length, [
+            ...previous.#segments,
+            appendedStates,
+        ]);
+    }
+    get byteLength() {
+        return (this.#itemCount + 1) * PREFIX_BYTES;
+    }
+    boundaryAt(timeline, throughOrdinal) {
+        const maximumOrdinal = timeline.at(-1)?.ordinal ?? 0;
+        if (timeline.length !== this.#itemCount) {
+            throw new Error("Timeline prefix index does not match the timeline");
+        }
+        if (throughOrdinal > maximumOrdinal)
+            return null;
+        let low = 0;
+        let high = timeline.length;
+        while (low < high) {
+            const middle = low + Math.floor((high - low) / 2);
+            if (timeline[middle].ordinal <= throughOrdinal)
+                low = middle + 1;
+            else
+                high = middle;
+        }
+        return this.#boundary(timeline, low);
+    }
+    boundaryAtOrBefore(timeline, throughOrdinal) {
+        const maximumOrdinal = timeline.at(-1)?.ordinal ?? 0;
+        return this.boundaryAt(timeline, Math.min(throughOrdinal, maximumOrdinal));
+    }
+    matches(timeline, boundary, candidate) {
+        const encoded = Buffer.from(candidate, "base64url");
+        if (encoded.byteLength !== PREFIX_BYTES)
+            return false;
+        const slotIndex = boundary.throughOrdinal === 0 ? 0 : upperBound(timeline, boundary.throughOrdinal);
+        const slot = slotIndex === 0 || timeline[slotIndex - 1]?.ordinal === boundary.throughOrdinal
+            ? this.#slot(slotIndex)
+            : null;
+        return slot !== null && timingSafeEqual(slot, encoded);
+    }
+    #boundary(timeline, slot) {
+        return {
+            throughOrdinal: slot === 0 ? 0 : timeline[slot - 1].ordinal,
+            timelinePrefixRevision: Buffer.from(this.#slot(slot)).toString("base64url"),
+        };
+    }
+    #slot(index) {
+        let low = 0;
+        let high = this.#segmentEnds.length;
+        while (low < high) {
+            const middle = low + Math.floor((high - low) / 2);
+            if (this.#segmentEnds[middle] <= index)
+                low = middle + 1;
+            else
+                high = middle;
+        }
+        const segment = this.#segments[low];
+        if (segment === undefined) {
+            throw new Error("Timeline prefix slot is out of bounds");
+        }
+        const segmentStart = low === 0 ? 0 : this.#segmentEnds[low - 1];
+        const start = (index - segmentStart) * PREFIX_BYTES;
+        return segment.subarray(start, start + PREFIX_BYTES);
+    }
+}
+function validateOrdinal(ordinal, previousOrdinal) {
+    if (!Number.isSafeInteger(ordinal) ||
+        ordinal < 1 ||
+        (previousOrdinal !== undefined && ordinal <= previousOrdinal)) {
+        throw new Error("Timeline ordinals must be strictly increasing positive integers");
+    }
+}
+function advancePrefix(state, item, normalized, prefixKey) {
+    const chunks = [];
+    writeTimelineItem(new DigestWriter((chunk) => {
+        chunks.push(typeof chunk === "string" ? Buffer.from(chunk, "utf8") : Buffer.from(chunk));
+    }), item, normalized);
+    return createHmac("sha256", prefixKey)
+        .update(state)
+        .update(Buffer.concat(chunks))
+        .digest()
+        .subarray(0, PREFIX_BYTES);
+}
+function upperBound(timeline, ordinal) {
+    let low = 0;
+    let high = timeline.length;
+    while (low < high) {
+        const middle = low + Math.floor((high - low) / 2);
+        if (timeline[middle].ordinal <= ordinal)
+            low = middle + 1;
+        else
+            high = middle;
+    }
+    return low;
+}
+function writeTimelineItem(writer, item, normalized) {
+    writer.string("kind", item.kind);
+    writer.string("id", item.id);
+    writer.number("ordinal", item.ordinal);
+    writer.nullableString("timestamp", item.timestamp);
+    switch (item.kind) {
+        case "message":
+            writer.string("role", item.role);
+            writer.nullableString("phase", item.phase);
+            writer.nullableString("itemType", item.itemType ?? null);
+            writer.string("markdown", item.markdown);
+            return;
+        case "directive":
+            writer.boolean("hasDetail", item.hasDetail);
+            if (!item.hasDetail) {
+                writer.string("text", item.text);
+                return;
+            }
+            writer.string("summary", item.summary);
+            writer.number("charCount", item.charCount);
+            writer.nullableObject("detail", normalized.directiveDetails.get(item.id) ?? null, (entry, detail) => {
+                entry.string("text", detail.text);
+                entry.boolean("truncated", detail.truncated);
+            });
+            return;
+        case "tool":
+            writer.string("stage", item.stage);
+            writer.string("callId", item.callId);
+            writer.string("toolName", item.toolName);
+            if (item.stage === "output")
+                writer.string("status", item.status);
+            writer.nullableString("preview", item.preview);
+            writer.number("charCount", item.charCount);
+            writer.boolean("hasDetail", item.hasDetail);
+            writer.nullableObject("detail", normalized.toolDetails.get(item.id) ?? null, (entry, detail) => {
+                entry.nullableString("input", detail.input);
+                entry.nullableString("output", detail.output);
+                entry.boolean("truncated", detail.truncated);
+            });
+            return;
+        case "user_input":
+            writer.string("stage", item.stage);
+            writer.string("callId", item.callId);
+            if (item.stage === "request") {
+                writer.array("questions", item.questions, (entry, question) => {
+                    entry.string("id", question.id);
+                    entry.string("header", question.header);
+                    entry.string("question", question.question);
+                    entry.array("options", question.options, (optionEntry, option) => {
+                        optionEntry.string("label", option.label);
+                        optionEntry.string("description", option.description);
+                    });
+                });
+                return;
+            }
+            writer.string("outcome", item.outcome);
+            if (item.outcome === "answered") {
+                writer.array("answers", item.answers, (entry, answer) => {
+                    entry.string("questionId", answer.questionId);
+                    entry.array("answers", answer.answers, (answerEntry, value) => {
+                        answerEntry.valueString(value);
+                    });
+                });
+            }
+            else if (item.outcome === "unavailable") {
+                writer.string("summary", item.summary);
+            }
+            return;
+        case "token":
+            writer.nullableObject("tokenUsage.total", item.tokenUsage.total, writeTokenCounters);
+            writer.nullableObject("tokenUsage.last", item.tokenUsage.last, writeTokenCounters);
+            return;
+        case "internal":
+            writer.string("eventType", item.eventType);
+            writer.nullableObject("detail", normalized.internalDetails.get(item.id) ?? null, (entry, detail) => {
+                entry.string("json", detail.json);
+                entry.boolean("truncated", detail.truncated);
+            });
+            return;
+    }
+}
+function writeTokenCounters(writer, counters) {
+    writer.nullableNumber("totalTokens", counters.totalTokens);
+    writer.nullableNumber("inputTokens", counters.inputTokens);
+    writer.nullableNumber("cachedInputTokens", counters.cachedInputTokens);
+    writer.nullableNumber("cacheWriteInputTokens", counters.cacheWriteInputTokens);
+    writer.nullableNumber("outputTokens", counters.outputTokens);
+    writer.nullableNumber("reasoningOutputTokens", counters.reasoningOutputTokens);
+}
+class DigestWriter {
+    update;
+    constructor(update) {
+        this.update = update;
+    }
+    string(name, value) {
+        this.#field(name, "string");
+        this.valueString(value);
+    }
+    nullableString(name, value) {
+        this.#field(name, "nullable-string");
+        if (value === null) {
+            this.#token("null");
+            return;
+        }
+        this.valueString(value);
+    }
+    boolean(name, value) {
+        this.#field(name, "boolean");
+        this.#token(value ? "true" : "false");
+    }
+    number(name, value) {
+        this.#field(name, "number");
+        this.#token(String(value));
+    }
+    nullableNumber(name, value) {
+        this.#field(name, "nullable-number");
+        this.#token(value === null ? "null" : String(value));
+    }
+    nullableObject(name, value, write) {
+        this.#field(name, "nullable-object");
+        if (value === null) {
+            this.#token("null");
+            return;
+        }
+        this.#token("object-start");
+        write(this, value);
+        this.#token("object-end");
+    }
+    array(name, values, write) {
+        this.#field(name, "array");
+        this.#token(String(values.length));
+        for (const value of values) {
+            this.#token("item-start");
+            write(this, value);
+            this.#token("item-end");
+        }
+    }
+    valueString(value) {
+        const bytes = Buffer.byteLength(value, "utf8");
+        this.update(`value:${bytes}:`);
+        this.update(value);
+        this.update(";");
+    }
+    #field(name, type) {
+        this.#token(`field:${type}`);
+        this.valueString(name);
+    }
+    #token(value) {
+        this.update(`${value.length}:${value};`);
+    }
+}
+//# sourceMappingURL=timeline-prefix-index.js.map

package/dist/server/server/repository/timeline-prefix-registry.js

@@ -0,0 +1,55 @@
+import { randomBytes } from "node:crypto";
+import { deriveTimelinePrefixIndex, extendsTimelinePrefix, extendTimelinePrefixIndex, } from "./timeline-prefix-index.js";
+function buildTimelinePrefixIndex(normalized, prefixKey, previous) {
+    return previous !== undefined &&
+        extendsTimelinePrefix(previous.normalized, normalized) &&
+        previous.normalized.timeline.length < normalized.timeline.length
+        ? extendTimelinePrefixIndex(previous.timelinePrefixIndex, previous.normalized, normalized, prefixKey, true)
+        : deriveTimelinePrefixIndex(normalized, prefixKey);
+}
+export class TimelinePrefixRegistry {
+    buildIndex;
+    prefixKey;
+    #published = new Map();
+    #generation = 0n;
+    constructor(buildIndex = buildTimelinePrefixIndex, prefixKey = randomBytes(32)) {
+        this.buildIndex = buildIndex;
+        this.prefixKey = prefixKey;
+    }
+    prepare(sessions, dirtyIds) {
+        const baseGeneration = this.#generation;
+        const next = new Map();
+        for (const [id, normalized] of sessions) {
+            const previous = this.#published.get(id);
+            if (previous !== undefined && dirtyIds !== undefined && !dirtyIds.has(id)) {
+                next.set(id, previous);
+                continue;
+            }
+            const unchangedPrefix = previous !== undefined &&
+                previous.normalized.timeline.length === normalized.timeline.length &&
+                extendsTimelinePrefix(previous.normalized, normalized);
+            const published = {
+                normalized,
+                timelinePrefixIndex: unchangedPrefix
+                    ? previous.timelinePrefixIndex
+                    : this.buildIndex(normalized, this.prefixKey, previous),
+            };
+            next.set(id, published);
+        }
+        let committed = false;
+        return {
+            sessions: next,
+            commit: () => {
+                if (committed)
+                    return;
+                if (this.#generation !== baseGeneration) {
+                    throw new Error("Cannot commit stale prepared timeline prefixes");
+                }
+                this.#published = next;
+                this.#generation += 1n;
+                committed = true;
+            },
+        };
+    }
+}
+//# sourceMappingURL=timeline-prefix-registry.js.map

package/dist/server/server/security/opaque-id.js

@@ -0,0 +1,13 @@
+import { createHash } from "node:crypto";
+export function encodeStringTuple(...parts) {
+    return parts.map((part) => `${part.length}:${part}`).join("");
+}
+export function opaqueIdForParts(...parts) {
+    return createHash("sha256")
+        .update(encodeStringTuple(...parts), "utf16le")
+        .digest("base64url");
+}
+export function opaqueIdForPath(canonicalPath) {
+    return createHash("sha256").update(canonicalPath, "utf8").digest("base64url");
+}
+//# sourceMappingURL=opaque-id.js.map

package/dist/server/server/source/session-source.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=session-source.js.map

package/dist/server/server/updates/session-updates-service.js

@@ -0,0 +1,147 @@
+import { reconcileSessionState } from "../interaction/reconcile-session-state.js";
+import { createProcessUpdateRevisionFactory, withUpdateRevision, } from "./update-revision.js";
+export const UPDATES_PROBE_INTERVAL_MS = 1_500;
+export const UPDATES_WAIT_TIMEOUT_MS = 25_000;
+export const MAX_UPDATES_WAITERS = 100;
+export const MAX_UPDATES_WAITERS_PER_SESSION = 10;
+export class SessionUpdatesError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "SessionUpdatesError";
+    }
+}
+export class SessionUpdatesService {
+    sessions;
+    options;
+    #createRevision;
+    #probeIntervalMs;
+    #waitTimeoutMs;
+    #maxWaiters;
+    #maxWaitersPerSession;
+    #now;
+    #waiters = new Map();
+    #waitersBySession = new Map();
+    #closed = false;
+    constructor(sessions, options = {}) {
+        this.sessions = sessions;
+        this.options = options;
+        this.#createRevision = options.createRevision ?? createProcessUpdateRevisionFactory();
+        this.#probeIntervalMs = options.probeIntervalMs ?? UPDATES_PROBE_INTERVAL_MS;
+        this.#waitTimeoutMs = options.waitTimeoutMs ?? UPDATES_WAIT_TIMEOUT_MS;
+        this.#maxWaiters = options.maxWaiters ?? MAX_UPDATES_WAITERS;
+        this.#maxWaitersPerSession = options.maxWaitersPerSession ?? MAX_UPDATES_WAITERS_PER_SESSION;
+        this.#now = options.now ?? Date.now;
+    }
+    revision(session, interaction) {
+        return this.#createRevision(session, interaction);
+    }
+    async wait(sessionId, query, signal) {
+        this.#throwIfAborted(signal);
+        const initial = await this.#probe(sessionId, query);
+        if (initial.updateRevision !== query.after || initial.hasMore)
+            return initial;
+        if (initial.session.status === "archived")
+            return null;
+        const waiter = this.#acquire(sessionId, signal);
+        const deadline = this.#now() + this.#waitTimeoutMs;
+        try {
+            while (true) {
+                const remaining = deadline - this.#now();
+                if (remaining <= 0)
+                    return null;
+                await delay(Math.min(this.#probeIntervalMs, remaining), waiter.signal);
+                const current = await this.#probe(sessionId, query);
+                if (current.updateRevision !== query.after || current.hasMore)
+                    return current;
+            }
+        }
+        finally {
+            this.#release(waiter);
+        }
+    }
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        for (const waiter of this.#waiters.keys())
+            waiter.abort();
+    }
+    async #probe(sessionId, query) {
+        this.#throwIfAborted();
+        const snapshot = await this.sessions.getSessionUpdates(sessionId, query.cursor);
+        if (snapshot === null) {
+            throw new SessionUpdatesError("session_not_found", "Session not found");
+        }
+        const interaction = await this.#describeInteraction(sessionId, snapshot.interactionSession);
+        return withUpdateRevision(reconcileSessionState({
+            session: snapshot.session,
+            cursor: snapshot.cursor,
+            hasMore: snapshot.hasMore,
+            interaction,
+        }), this.#createRevision);
+    }
+    #describeInteraction(sessionId, input) {
+        if (this.options.interaction === undefined)
+            return Promise.resolve({ supported: false, attachCommand: null });
+        return this.options.interaction.describeSnapshot(sessionId, input);
+    }
+    #acquire(sessionId, signal) {
+        this.#throwIfAborted(signal);
+        const sessionCount = this.#waitersBySession.get(sessionId) ?? 0;
+        if (this.#waiters.size >= this.#maxWaiters || sessionCount >= this.#maxWaitersPerSession) {
+            throw new SessionUpdatesError("updates_capacity_exceeded", "Too many automatic update requests are already waiting");
+        }
+        const controller = new AbortController();
+        const abort = () => controller.abort(signal?.reason);
+        signal?.addEventListener("abort", abort, { once: true });
+        if (signal?.aborted)
+            controller.abort(signal.reason);
+        this.#waiters.set(controller, {
+            sessionId,
+            externalSignal: signal,
+            externalAbort: abort,
+        });
+        this.#waitersBySession.set(sessionId, sessionCount + 1);
+        return controller;
+    }
+    #release(controller) {
+        const entry = this.#waiters.get(controller);
+        if (entry === undefined)
+            return;
+        this.#waiters.delete(controller);
+        const { sessionId } = entry;
+        const count = (this.#waitersBySession.get(sessionId) ?? 1) - 1;
+        if (count === 0)
+            this.#waitersBySession.delete(sessionId);
+        else
+            this.#waitersBySession.set(sessionId, count);
+        entry.externalSignal?.removeEventListener("abort", entry.externalAbort);
+    }
+    #throwIfAborted(signal) {
+        if (this.#closed || signal?.aborted)
+            throw abortError();
+    }
+}
+function delay(milliseconds, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal.aborted)
+            return reject(abortError());
+        const timer = setTimeout(done, milliseconds);
+        const abort = () => {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", abort);
+            reject(abortError());
+        };
+        function done() {
+            signal.removeEventListener("abort", abort);
+            resolve();
+        }
+        signal.addEventListener("abort", abort, { once: true });
+    });
+}
+function abortError() {
+    return new DOMException("The operation was aborted", "AbortError");
+}
+//# sourceMappingURL=session-updates-service.js.map

package/dist/server/server/updates/update-revision.js

@@ -0,0 +1,25 @@
+import { createHmac, randomBytes } from "node:crypto";
+export function createProcessUpdateRevisionFactory(secret = randomBytes(32)) {
+    return (session, interaction) => createHmac("sha256", secret)
+        .update(canonicalJson({ session, interaction }))
+        .digest("base64url");
+}
+export function withUpdateRevision(value, createRevision) {
+    const { nickname: _nickname, ...revisionSession } = value.session;
+    return {
+        ...value,
+        updateRevision: createRevision(revisionSession, value.interaction),
+    };
+}
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (value !== null && typeof value === "object") {
+        return `{${Object.entries(value)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+//# sourceMappingURL=update-revision.js.map

package/dist/server/shared/api-contract.js

@@ -0,0 +1,2 @@
+export * from "./interaction.js";
+//# sourceMappingURL=api-contract.js.map

package/dist/server/shared/domain.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=domain.js.map

package/dist/server/shared/interaction.js

@@ -0,0 +1,12 @@
+export const MAX_INTERACTION_MESSAGE_BYTES = 64 * 1024;
+export const MAX_INTERACTION_KEY_SEQUENCE_LENGTH = 64;
+export const INTERACTION_KEYS = [
+    "enter",
+    "up",
+    "down",
+    "left",
+    "right",
+    "interrupt",
+    "plan",
+];
+//# sourceMappingURL=interaction.js.map

package/dist/server/shared/uploads.js

@@ -0,0 +1,2 @@
+export const MAX_UPLOAD_BYTES = 20 * 1024 * 1024;
+//# sourceMappingURL=uploads.js.map