@vincemakes/kiso-web 0.0.0-stage → 0.53.0

package/dist/main/settings.js

@@ -0,0 +1,242 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { applyEffortDeclarations, contextWindowOf, demoScript, authForProfile, effortOptions, loadUserConfig, mergeConfigs, preferences, profileAvailable, rememberEffort, startingEffort, } from "@vincemakes/kiso-code/config";
+import { MODE_LABEL, OFFERED_MODES } from "@vincemakes/kiso-code/policy";
+import { lookupModelMetadata } from "@vincemakes/kiso-runtime/internal";
+import { fauxSkip } from "./faux.js";
+import { storeKey } from "./login.js";
+const MAX_RECENT = 10;
+const SAFE_SESSION = /^[A-Za-z0-9._-]+$/;
+/** Whether the model table says the profile's model reads images; unknown is no (nothing is sent that might be dropped). */
+const readsImages = (p) => lookupModelMetadata(p.model, p.baseUrl)?.capabilities.inputModalities?.includes("image") === true;
+const isTier = (value) => OFFERED_MODES.some((m) => m === value);
+export class Settings {
+    #file;
+    /** a scripted model (the proofs); the shared configuration is then not read */
+    #fixed;
+    /** the tier a Work starts with when nothing was set for it */
+    #default;
+    /** the scripted tour, once started: a factory for its model (the demo script after the turns a Work has used) */
+    #demo = null;
+    constructor(home, fixed, mode) {
+        this.#file = join(home, "desktop.json");
+        this.#fixed = fixed;
+        const saved = this.#read().mode;
+        this.#default = isTier(saved) ? saved : mode;
+    }
+    /** The tier of one Work (read by the policy on every decision), else the one new Works start with. */
+    tierOf(sessionId) {
+        const own = sessionId === undefined ? undefined : this.#read().tiers?.[sessionId];
+        return isTier(own) ? own : this.#default;
+    }
+    /** Folders the person picked, newest first; and one more picked now. */
+    recents() {
+        return this.#read().recent ?? [];
+    }
+    addRecent(path) {
+        this.write({ recent: [path, ...this.recents().filter((p) => p !== path)].slice(0, MAX_RECENT) });
+    }
+    /** Start the scripted tour: no key, the terminal's own demo script, for Works opened from now on. */
+    async startDemo() {
+        const { createFauxProvider } = await import("@vincemakes/kiso-evals");
+        this.#demo = (skip) => ({ kind: "adapter", adapter: createFauxProvider(demoScript().slice(skip)), model: "demo", route: "adapter" });
+    }
+    #read() {
+        try {
+            return JSON.parse(readFileSync(this.#file, "utf8"));
+        }
+        catch {
+            return {};
+        }
+    }
+    /** Merge into `desktop.json` (the folder memory lives there too). */
+    write(patch) {
+        try {
+            mkdirSync(join(this.#file, ".."), { recursive: true, mode: 0o700 });
+            writeFileSync(this.#file, `${JSON.stringify({ ...this.#read(), ...patch })}\n`, { mode: 0o600 });
+        }
+        catch {
+            // a read-only home only loses the memory
+        }
+    }
+    lastFolder() {
+        return this.#read().lastFolder;
+    }
+    #config() {
+        const merged = mergeConfigs(loadUserConfig(), null);
+        applyEffortDeclarations(merged);
+        return merged;
+    }
+    /** The profile in use: the Work's own pick, else the person's pick for new Works, if it still exists, else the configuration's own default. */
+    #chosen(config, session) {
+        const models = config.models ?? {};
+        const own = session === undefined ? undefined : this.#read().works?.[session]?.profile;
+        if (own !== undefined && models[own] !== undefined)
+            return own;
+        const picked = this.#read().profile;
+        if (picked !== undefined && models[picked] !== undefined)
+            return picked;
+        return config.model !== undefined && models[config.model] !== undefined ? config.model : null;
+    }
+    /** The model a Work opened now runs on; throws, in words, when none can. */
+    model(ctx) {
+        if (this.#fixed !== null)
+            return this.#fixed;
+        if (this.#demo !== null)
+            return this.#demo(ctx === undefined ? 0 : fauxSkip(ctx.sessionsDir, ctx.sessionId));
+        const config = this.#config();
+        const name = this.#chosen(config, ctx?.sessionId);
+        if (name === null)
+            throw new Error("no model is configured: add a profile to ~/.kiso/config.json (see the terminal's docs) and choose it in Settings");
+        const profile = config.models[name];
+        const auth = authForProfile(name, profile);
+        const effort = startingEffort(profile, this.#effortOf(name, ctx?.sessionId));
+        return {
+            kind: "profile",
+            name,
+            profile,
+            auth: auth.type === "oauth" ? { type: "oauth", providerId: auth.providerId } : { type: "api-key", apiKey: auth.apiKey },
+            contextWindow: contextWindowOf(profile, config) ?? undefined,
+            ...(effort !== null ? { reasoning: { thinking: "default", effort } } : {}),
+        };
+    }
+    /** The effort a Work asked for (when it is one of the profile's levels), else the terminal's remembered one for the profile. */
+    #effortOf(name, session) {
+        const own = session === undefined ? undefined : this.#read().works?.[session]?.effort;
+        return own ?? preferences().effort?.[name];
+    }
+    /** A Work's own model choice (to put back when its rebuild is refused). */
+    workOf(session) {
+        return this.#read().works?.[session];
+    }
+    /** A fork starts with its parent's own tier, model and effort, and remembers where it came from. */
+    forked(parent, child, fork) {
+        const own = this.#read();
+        const tier = own.tiers?.[parent];
+        const work = own.works?.[parent];
+        this.write({
+            ...(tier !== undefined ? { tiers: { ...own.tiers, [child]: tier } } : {}),
+            ...(work !== undefined ? { works: { ...own.works, [child]: work } } : {}),
+            forks: { ...own.forks, [child]: fork },
+        });
+    }
+    forkOf(session) {
+        return this.#read().forks?.[session];
+    }
+    /** Pin or archive a Work (a pin goes first), or take it off. */
+    mark(session, list, on) {
+        const rest = (this.#read()[list] ?? []).filter((id) => id !== session);
+        this.write({ [list]: on ? [session, ...rest] : rest });
+    }
+    /** What the sidebar shows of a Work beyond its log: the fork's parent, its pin's place, whether it is archived. */
+    marksOf(session) {
+        const own = this.#read();
+        const parent = own.forks?.[session]?.parent;
+        const pinned = own.pins?.indexOf(session) ?? -1;
+        return { ...(parent !== undefined ? { parent } : {}), ...(pinned >= 0 ? { pinned } : {}), ...(own.archived?.includes(session) ? { archived: true } : {}) };
+    }
+    /** A deleted Work leaves nothing here; a fork's record of it stays (its notice still names the parent). */
+    forget(session) {
+        const own = this.#read();
+        const drop = (m) => Object.fromEntries(Object.entries(m ?? {}).filter(([k]) => k !== session));
+        this.write({ tiers: drop(own.tiers), works: drop(own.works), forks: drop(own.forks), pins: (own.pins ?? []).filter((id) => id !== session), archived: (own.archived ?? []).filter((id) => id !== session) });
+    }
+    restoreWork(session, work) {
+        const { [session]: _, ...rest } = this.#read().works ?? {};
+        this.write({ works: work === undefined ? rest : { ...rest, [session]: work } });
+    }
+    /** The person's own test-runner commands (`checks` in the configuration), for the compaction phase rule. */
+    checks() {
+        return Object.values(this.#config().checks ?? {});
+    }
+    /** The names of the environment variables that hold a key: no shell child may inherit them. */
+    secretEnvNames() {
+        return Object.values(this.#config().models ?? {}).flatMap((p) => (p.apiKeyEnv === undefined ? [] : [p.apiKeyEnv]));
+    }
+    /** What the home screen should offer: nothing, a key for a profile, a profile to add, or the tour already on. */
+    #setup(config, name) {
+        if (this.#fixed !== null)
+            return "ready";
+        if (this.#demo !== null)
+            return "demo";
+        const models = config.models ?? {};
+        if (Object.keys(models).length === 0)
+            return "noprofile";
+        return name !== null && profileAvailable(models[name]) ? "ready" : "signin";
+    }
+    /** Store a key for a profile (the terminal's credential file); a sign-in ends the tour. */
+    saveKey(profile, key) {
+        storeKey(this.#config().models?.[profile], key);
+        this.#demo = null;
+        if (this.#read().profile === undefined)
+            this.write({ profile });
+    }
+    snapshot(session) {
+        const config = this.#config();
+        const models = config.models ?? {};
+        const name = this.#chosen(config, session);
+        const profile = name === null ? undefined : models[name];
+        const levels = profile === undefined ? null : effortOptions(profile);
+        return {
+            profiles: Object.entries(models).map(([n, p]) => ({ name: n, model: p.model, available: profileAvailable(p), images: readsImages(p) })),
+            profile: name,
+            effort: levels === null || name === null ? null : { ...levels, current: startingEffort(profile, this.#effortOf(name, session)) },
+            mode: this.tierOf(session),
+            setup: this.#setup(config, name),
+            modes: OFFERED_MODES.map((value) => ({ value, label: MODE_LABEL[value] })),
+            signIn: name === null ? { ok: false, text: "No model is configured." } : signInOf(name, profile),
+        };
+    }
+    /** Apply a patch; returns the Work whose model binding it changed (the host rebuilds that Work), else null. */
+    apply(patch) {
+        const config = this.#config();
+        const session = patch.session !== undefined && SAFE_SESSION.test(patch.session) ? patch.session : undefined;
+        if (session !== undefined && (patch.profile !== undefined || patch.effort !== undefined)) {
+            // one Work's model: its own profile and effort, the new-Work default untouched
+            const was = this.workOf(session) ?? {};
+            const profileName = patch.profile !== undefined && config.models?.[patch.profile] !== undefined ? patch.profile : (was.profile ?? this.#chosen(config, session) ?? undefined);
+            const profile = profileName === undefined ? undefined : config.models?.[profileName];
+            const effort = patch.effort !== undefined && profile !== undefined && effortOptions(profile)?.levels.includes(patch.effort) === true ? patch.effort : patch.profile !== undefined ? undefined : was.effort;
+            const next = { ...(profileName !== undefined ? { profile: profileName } : {}), ...(effort !== undefined ? { effort } : {}) };
+            if (next.profile === was.profile && next.effort === was.effort)
+                return null;
+            this.write({ works: { ...this.#read().works, [session]: next } });
+            return session;
+        }
+        if (patch.profile !== undefined && config.models?.[patch.profile] !== undefined) {
+            this.write({ profile: patch.profile });
+            // choosing a profile that can run ends the tour
+            if (profileAvailable(config.models[patch.profile]))
+                this.#demo = null;
+        }
+        const name = patch.profile ?? this.#chosen(config);
+        const profile = name === null ? undefined : config.models?.[name];
+        if (patch.effort !== undefined && name !== null && profile !== undefined && effortOptions(profile)?.levels.includes(patch.effort) === true)
+            rememberEffort(name, patch.effort);
+        if (isTier(patch.mode)) {
+            if (patch.session === undefined) {
+                this.#default = patch.mode;
+                this.write({ mode: patch.mode });
+            }
+            else if (SAFE_SESSION.test(patch.session))
+                this.write({ tiers: { ...this.#read().tiers, [patch.session]: patch.mode } });
+        }
+        return null;
+    }
+}
+/** Where a profile's sign-in comes from, in words; the secret is never part of it. */
+function signInOf(name, profile) {
+    try {
+        const auth = authForProfile(name, profile);
+        if (auth.type === "oauth")
+            return { ok: true, text: `Signed in with ${auth.providerId} (shared with the terminal)` };
+        if (auth.source === "store")
+            return { ok: true, text: "Signed in: a key stored by the terminal's login" };
+        if (auth.source === "env")
+            return { ok: true, text: `Using the key in the environment variable ${profile.apiKeyEnv ?? ""}` };
+        return { ok: true, text: "This endpoint needs no key" };
+    }
+    catch (error) {
+        return { ok: false, text: error instanceof Error ? error.message : String(error) };
+    }
+}

package/dist/main/space.js

@@ -0,0 +1,198 @@
+import { realpathSync } from "node:fs";
+import { SessionStore } from "@vincemakes/kiso-runtime";
+import { named, titleIfUnnamed } from "./names.js";
+import { createSessionService, toWireEvent } from "@vincemakes/kiso-server";
+import { createHttpHandler } from "@vincemakes/kiso-server/http";
+import { createWebAgent, routeOf } from "./agent.js";
+import { createTaskHub, rowsOf } from "./tasks.js";
+import { runRate, runTotals, usageFrameAt } from "./usage.js";
+import { webSanitize } from "./sanitize.js";
+import { TimeIndex } from "./times.js";
+import { artifactsOf, LogImages } from "./artifacts.js";
+const HEAD_LINES = 12;
+const DELTAS = new Set(["thinking", "text_delta"]);
+export function createSpace(options) {
+    const store = new SessionStore(options.dir);
+    const tasks = createTaskHub(options.dir);
+    // the Work's own route (a Work can switch its model in the composer): what its usage is canonicalized and priced on
+    const route = (sessionId) => {
+        try {
+            return routeOf(options.model({ sessionId, sessionsDir: options.dir }));
+        }
+        catch {
+            return "unknown";
+        }
+    };
+    const opened = new Set();
+    const sessions = new Map();
+    const followUps = new Map();
+    // owner 2026-11-03: a Work is titled by a summary of its first message, once, beside its first run; the person's
+    // own name wins, before or after, and a failure leaves the first request's title. A first message sent in the last
+    // minute, not "a run is live": a quick run can end before its first event is seen here, and a replayed old one is old
+    const titled = new Set();
+    const title = (sessionId, event) => {
+        const session = sessions.get(sessionId);
+        if (options.titles !== true || session === undefined || titled.has(sessionId) || Date.now() - times.at(sessionId, event.seq) > 60_000)
+            return;
+        if (service.events(sessionId).some((e) => e.type === "user_input" && e.seq < event.seq) || named(options.dir, sessionId))
+            return;
+        titled.add(sessionId);
+        const text = typeof event.content === "string" ? event.content : event.content.map((b) => (b.type === "text" ? b.text : "")).join(" ");
+        void session.title(text, { signal: AbortSignal.timeout(15_000) }).then((name) => titleIfUnnamed(options.dir, sessionId, name), () => undefined);
+    };
+    const followUp = (sessionId, seq) => {
+        const session = sessions.get(sessionId);
+        const end = [...service.events(sessionId)].reverse().find((e) => e.type === "terminal");
+        if (options.followUps !== true || session === undefined || service.isRunning(sessionId) || end?.seq !== seq || end.outcome.kind !== "completed")
+            return Promise.resolve("");
+        const at = `${sessionId}:${seq}`;
+        if (!followUps.has(at))
+            followUps.set(at, session.followUp({ maxTokens: 200 }).catch(() => ""));
+        return followUps.get(at);
+    };
+    const service = createSessionService({
+        store,
+        open: async (sessionId) => {
+            opened.add(sessionId);
+            return createWebAgent({
+                store,
+                workspace: options.workspace,
+                model: options.model({ sessionId, sessionsDir: options.dir }),
+                tier: () => options.tierOf(sessionId),
+                sessionId,
+                checkRunners: options.checkRunners(),
+                tasks,
+                ...(options.secretEnvNames !== undefined ? { secretEnvNames: options.secretEnvNames } : {}),
+                ...(options.toolLimits !== undefined ? { toolLimits: options.toolLimits } : {}),
+                onSession: (sessionId, session) => {
+                    sessions.set(sessionId, session);
+                    // the model hears how a task ended; nothing wakes an idle session
+                    session.useTasks(tasks.managerFor(sessionId), { wake: false });
+                },
+            });
+        },
+    });
+    // the Work's own model (a Work can switch it in the composer), for its context window
+    const windowOf = (sessionId) => {
+        try {
+            const m = options.model({ sessionId, sessionsDir: options.dir });
+            return m.kind === "profile" ? (m.contextWindow ?? null) : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    const times = new TimeIndex(store);
+    const augment = (event, sessionId) => {
+        const frames = [];
+        // when it happened: for every wire event but the two delta types, which are too many
+        if (!DELTAS.has(event.type) && toWireEvent(event) !== null) {
+            const at = { seq: event.seq, ts: times.at(sessionId, event.seq) };
+            frames.push({ event: "at", data: at });
+        }
+        if (event.type === "user_input")
+            title(sessionId, event);
+        frames.push(...derived(event, sessionId));
+        return frames;
+    };
+    /** The tool, input and execution start of the call a result answers, from the log before it. */
+    const callOf = (sessionId, callId) => {
+        let call = null;
+        let startedAt = null;
+        for (const e of service.events(sessionId)) {
+            if (e.type === "tool_call_end" && e.callId === callId)
+                call = { name: e.name, input: e.input };
+            if (e.type === "tool_execution_started" && e.callId === callId)
+                startedAt = times.at(sessionId, e.seq);
+        }
+        return call === null ? null : { ...call, startedAt };
+    };
+    const realWorkspace = () => {
+        try {
+            return realpathSync(options.workspace);
+        }
+        catch {
+            return options.workspace;
+        }
+    };
+    const derived = (event, sessionId) => {
+        if (event.type === "usage") {
+            const frame = usageFrameAt(service.events(sessionId), event.seq, route(sessionId));
+            return frame === null ? [] : [{ event: "usage", data: { ...frame, window: windowOf(sessionId) } }];
+        }
+        if (event.type === "terminal") {
+            const events = service.events(sessionId);
+            const totals = runTotals(events, event.seq, route(sessionId));
+            return totals === null ? [] : [{ event: "run_usage", data: { seq: event.seq, ...totals, tokPerSec: runRate(events, event.seq, totals.output, (seq) => times.at(sessionId, seq)) } }];
+        }
+        if (event.type === "tool_result") {
+            const artifacts = artifactsOf(event, sessionId, callOf(sessionId, event.callId), realWorkspace(), options.dir);
+            const text = typeof event.content === "string" ? event.content : event.content.map((b) => (b.type === "text" ? b.text : `[${b.type}]`)).join("\n");
+            const lines = text.split("\n");
+            const frame = {
+                seq: event.seq,
+                callId: event.callId,
+                isError: event.isError,
+                head: lines.slice(0, HEAD_LINES),
+                lines: lines.length,
+                bytes: Buffer.byteLength(text),
+                truncated: lines.length > HEAD_LINES,
+                ...((event.tags ?? []).includes("created") ? { created: true } : {}),
+                ...(artifacts.length > 0 ? { artifacts } : {}),
+            };
+            return [{ event: "tool_output", data: frame }];
+        }
+        return [];
+    };
+    // The tasks frame: not tied to any event (a command can end while nothing
+    // else happens), so it is the host's own source, polled while a stream is open.
+    const frames = (sessionId, push) => {
+        let last = "";
+        const tick = () => {
+            try {
+                const rows = rowsOf(tasks.managerFor(sessionId));
+                // elapsed time of a running task changes every tick; the state does not
+                const key = JSON.stringify(rows.map((r) => [r.id, r.label]));
+                const running = rows.some((r) => r.endedAt === null);
+                if (key !== last || running) {
+                    last = key;
+                    const frame = { at: Date.now(), tasks: rows };
+                    push({ event: "tasks", data: frame });
+                }
+            }
+            catch {
+                // a corrupt journal is the terminal's to report; the stream goes on
+            }
+        };
+        tick();
+        const timer = setInterval(tick, 1_000);
+        timer.unref();
+        return () => clearInterval(timer);
+    };
+    const handler = createHttpHandler(service, {
+        prefix: options.prefix,
+        // the host's guard has already run: bearer token, Host and Origin
+        authorize: () => true,
+        augment,
+        frames,
+        projection: { exposeThinking: options.exposeThinking, ...(options.sanitizer === "default" ? {} : { sanitize: webSanitize }) },
+        ...(options.keepaliveMs !== undefined ? { keepaliveMs: options.keepaliveMs } : {}),
+    });
+    return {
+        key: options.key,
+        workspace: options.workspace,
+        dir: options.dir,
+        store,
+        service,
+        tasks,
+        images: new LogImages(options.dir),
+        handler,
+        opened: () => opened,
+        followUp,
+        drain: (graceMs) => service.drain(graceMs),
+        close: async () => {
+            await tasks.close();
+            store.closeAll();
+        },
+    };
+}

package/dist/main/tasks.js

@@ -0,0 +1,92 @@
+/**
+ * Background tasks (ADR-0058) for the web app's sessions.
+ *
+ * THE ONE FILE that reaches behind the public surface: the TaskManager and
+ * its journal types are exported only from `@vincemakes/kiso-runtime/internal`
+ * today. scripts/check-imports.mjs allows exactly this file to do so, and
+ * the spike report proposes the root export that removes the exception.
+ */
+import { closeSync, fstatSync, openSync, readSync } from "node:fs";
+import { join } from "node:path";
+import { TaskManager } from "@vincemakes/kiso-runtime/internal";
+import { processTaskBackend } from "@vincemakes/kiso-tools-node";
+export { TaskManager };
+export function createTaskHub(storeRoot) {
+    // the runner is started with process.execPath: the host is plain node, so the runner is too
+    const backend = processTaskBackend();
+    const managers = new Map();
+    const managerFor = (sessionId) => {
+        let manager = managers.get(sessionId);
+        if (manager === undefined) {
+            manager = new TaskManager({ root: join(storeRoot, `${sessionId}.tasks`), backend });
+            manager.observe();
+            managers.set(sessionId, manager);
+        }
+        return manager;
+    };
+    return {
+        // the manager satisfies ShellTasks structurally (tools-node takes no runtime dependency)
+        shellTasks: (sessionId) => (sessionId === undefined ? undefined : managerFor(sessionId)),
+        managerFor,
+        forget: (sessionId) => {
+            managers.get(sessionId)?.close();
+            managers.delete(sessionId);
+        },
+        close: async () => {
+            for (const manager of managers.values()) {
+                await manager.stopAll("exit", 2_000, "moved");
+                manager.close();
+            }
+        },
+    };
+}
+/** A task's state in a person's words (the terminal's `/tasks` wording). */
+export function stateLabel(task) {
+    const s = task.state;
+    switch (s.kind) {
+        case "starting":
+            return "starting";
+        case "not_run":
+            return "never ran";
+        case "running":
+            return task.stoppedBy !== undefined ? "stopping" : s.ready ? "ready" : "running";
+        case "unknown":
+            return "lost track";
+        case "ended":
+            if (s.stopped)
+                return "stopped";
+            if (s.error !== undefined)
+                return "failed to start";
+            return s.exitCode === 0 ? "exited 0" : s.exitCode !== null ? `failed ${s.exitCode}` : `ended ${s.signal ?? ""}`.trim();
+    }
+}
+/** The last lines of a task's output file (read from its end, never whole). */
+function tailOf(path, lines = 4) {
+    try {
+        const fd = openSync(path, "r");
+        try {
+            const size = fstatSync(fd).size;
+            const length = Math.min(size, 2048);
+            const buf = Buffer.alloc(length);
+            readSync(fd, buf, 0, length, size - length);
+            return buf.toString("utf8").split("\n").filter((l) => l !== "").slice(-lines);
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch {
+        return [];
+    }
+}
+export function rowsOf(manager, now = Date.now()) {
+    return manager.list().map((t) => ({
+        id: t.id,
+        label: stateLabel(t),
+        command: t.command.split("\n")[0],
+        startedAt: t.startedAt,
+        endedAt: t.endedAt ?? null,
+        elapsedMs: (t.endedAt ?? now) - t.startedAt,
+        tail: tailOf(t.outputPath),
+    }));
+}

package/dist/main/times.js

@@ -0,0 +1,28 @@
+/**
+ * When each durable event happened. The wire events carry no timestamp; the
+ * durable records do (`StoreRecord.ts`), so durations ("thought for N s",
+ * a step's time, the footer's duration) are read here and sent as `at`
+ * frames. A session's records are read once; events that arrive later are
+ * stamped on arrival, which is the moment the store wrote them to within
+ * a few milliseconds.
+ */
+export class TimeIndex {
+    #store;
+    #bySession = new Map();
+    constructor(store) {
+        this.#store = store;
+    }
+    at(sessionId, seq) {
+        let known = this.#bySession.get(sessionId);
+        if (known === undefined) {
+            known = new Map(this.#store.load(sessionId).map((r) => [r.event.seq, r.ts]));
+            this.#bySession.set(sessionId, known);
+        }
+        let ts = known.get(seq);
+        if (ts === undefined) {
+            ts = Date.now();
+            known.set(seq, ts);
+        }
+        return ts;
+    }
+}

package/dist/main/usage.js

@@ -0,0 +1,102 @@
+import { canonicalizeUsage } from "@vincemakes/kiso-runtime";
+import { cacheRate } from "../shared/frames.js";
+/**
+ * The run's usage, read off the durable log — `usage` is not on the wire.
+ *
+ * The same two rules the terminal's ledger states (apps/cli chat.ts,
+ * turnUsageLedger): a CALL is its LATEST report (a gateway may report one
+ * request twice), a RUN is the sum over its calls, and an unmeasured term
+ * makes the sum unmeasured. `stop` ends a call; `terminal` ends the run.
+ * The input is the canonical FRESH count, so the cache rate
+ * cache / (fresh + cache) can never pass 100%.
+ */
+const sum = (a, b) => (a === null || b === null ? null : a + b);
+function fold(a, b) {
+    if (a === null)
+        return b;
+    if (b === null)
+        return a;
+    return { fresh: sum(a.fresh, b.fresh), output: sum(a.output, b.output), cacheRead: sum(a.cacheRead, b.cacheRead), costUsd: sum(a.costUsd, b.costUsd), known: a.known && b.known };
+}
+/** One durable usage event as numbers; `route` is the adapter identity the
+ *  canonical mapping keys on ("openai-compat", "anthropic", "adapter"). */
+export function callNumbers(route, ev) {
+    const c = canonicalizeUsage(route, ev);
+    return { fresh: c.input, output: c.output, cacheRead: ev.cacheRead === null ? null : c.cacheRead, costUsd: c.costUsd, known: ev.known };
+}
+/** The frame for the usage event at `seq`: the call, and the run so far. */
+export function usageFrameAt(events, seq, route) {
+    let settled = null;
+    let inFlight = null;
+    let calls = 0;
+    for (const ev of events) {
+        if (ev.seq > seq)
+            break;
+        if (ev.type === "terminal") {
+            settled = null;
+            inFlight = null;
+            calls = 0;
+        }
+        else if (ev.type === "stop") {
+            settled = fold(settled, inFlight);
+            inFlight = null;
+        }
+        else if (ev.type === "usage") {
+            if (inFlight === null)
+                calls += 1;
+            inFlight = callNumbers(route, ev);
+            if (ev.seq === seq) {
+                const turn = fold(settled, inFlight);
+                return { seq, window: null, call: inFlight, turn: { ...turn, cacheRate: cacheRate(turn.fresh, turn.cacheRead), calls } };
+            }
+        }
+    }
+    return null;
+}
+/** The run that ended at the terminal `seq`: its totals. */
+export function runTotals(events, terminalSeq, route) {
+    let settled = null;
+    let inFlight = null;
+    let calls = 0;
+    for (const ev of events) {
+        if (ev.seq > terminalSeq)
+            break;
+        if (ev.type === "terminal") {
+            if (ev.seq === terminalSeq) {
+                const turn = fold(settled, inFlight);
+                return turn === null ? null : { ...turn, cacheRate: cacheRate(turn.fresh, turn.cacheRead), calls };
+            }
+            settled = inFlight = null;
+            calls = 0;
+        }
+        else if (ev.type === "stop") {
+            settled = fold(settled, inFlight);
+            inFlight = null;
+        }
+        else if (ev.type === "usage") {
+            if (inFlight === null)
+                calls += 1;
+            inFlight = callNumbers(route, ev);
+        }
+    }
+    return null;
+}
+const CALL_OUTPUT = new Set(["thinking", "text_start", "text_delta", "tool_call_start", "tool_call_end"]);
+/** The run's decode rate as the terminal times one call (TPS-1), summed: each call from its first output event to its last usage
+ *  report (tool time falls between calls), output over the summed time; null under 0.5 s or with no output ("0 tok/s" is no measurement). */
+export function runRate(events, terminalSeq, output, at) {
+    const start = events.reduce((n, ev) => (ev.type === "terminal" && ev.seq < terminalSeq ? ev.seq : n), -1);
+    let [ms, first, last] = [0, -1, -1];
+    for (const ev of events) {
+        if (ev.seq <= start || ev.seq > terminalSeq)
+            continue;
+        if (CALL_OUTPUT.has(ev.type) && first < 0)
+            first = ev.seq;
+        else if (ev.type === "usage" && first >= 0)
+            last = ev.seq;
+        if (ev.type === "stop" || ev.seq === terminalSeq)
+            [ms, first, last] = [ms + (first >= 0 && last >= 0 ? Math.max(0, at(last) - at(first)) : 0), -1, -1];
+    }
+    const rate = output === null || ms < 500 ? 0 : Math.round(output / (ms / 1000));
+    return rate > 0 ? rate : null;
+}