@vincemakes/kiso-web 0.0.0-stage → 0.53.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kiso contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,51 @@
-# Temporary Holding Version
+# kiso web
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A local web app on the kiso hosted-session service: `kiso-web` runs the host in its own process and serves the page at
+`http://127.0.0.1:4317`.
+
+```bash
+npm install -g @vincemakes/kiso-web
+kiso web            # or kiso-web; the terminal's `kiso` runs this package when it is installed
+```
+
+The host must be running for the page to work: it runs while the command runs. Node 22 or later, macOS or Linux (Windows is not supported yet); the
+page runs in Safari 17, Chrome or Edge. Built into the root build; typecheck, gates and proofs run here and in the Web workflow.
+
+Development:
+
+```
+npm run build -w @vincemakes/kiso-web         # tsc (host, shared, state) + vite (the page into out/)
+npm run start -w @vincemakes/kiso-web         # kiso-web: the host, and the default browser opened on the page
+npm run gates -w @vincemakes/kiso-web         # size, deps, imports, names, paths, CJK
+npm run proofs:fast -w @vincemakes/kiso-web   # daily, before each commit: no browser, no kill -9
+npm run proofs:full -w @vincemakes/kiso-web   # end of a milestone, before a push, before a release
+npm run check -w @vincemakes/kiso-web         # build + typecheck + gates + proofs:fast
+npm run check:full -w @vincemakes/kiso-web    # the same with proofs:full
+```
+
+`kiso-web [--port 4317] [--no-open] [--revoke-sessions]`. The port is fixed, so a page added to the Dock (Safari: File > Add to Dock;
+Chrome or Edge: Install page as app) keeps its address. Running it again while a host holds the port opens the browser on that host;
+anything else on the port is an error that names the process. The host runs while the command runs: with no host, the page cannot load.
+
+Sign-in: the command opens the browser on a one-time connect code in the address (good for two minutes); the page trades it for a
+session cookie (`HttpOnly`, `SameSite=Strict`, named after the port) and strips it from the address, so the page holds no secret of its
+own. The host keeps the sessions hashed in `$KISO_HOME/web.json` (mode 0600); `--revoke-sessions` forgets them all, and every page signs in
+again from the command. Every request still passes the Host and Origin checks: a cookie on 127.0.0.1 is sent to every port of it. A session
+is a key to this machine's shell: do not run a page you do not trust on 127.0.0.1.
+
+Each proof is a script; its exit code is the verdict. `fast` is the reducer, markdown, usage, guard, sign-in, policy, control and task
+proofs (seconds to under a minute). `full` adds the ones that kill the host with `kill -9` and the page proofs, which drive a headless
+Chrome through the DevTools protocol (Chrome is found on the machine, or named by `KISO_WEB_CHROME`), including a tab closed and reopened
+mid-run and one approval answered from two tabs. Rule: a change that only touches page styles or components needs `fast`; a change to
+`src/main`, `src/shared`, the state reducer, the transport or recovery needs `full`.
+
+The model, the effort and the sign-in come from the terminal's own configuration (`~/.kiso/config.json`, `auth.json`), read through
+the `./config` door of `@vincemakes/kiso-code`: one login serves both products, and no key is read from the web app's own environment.
+Works live where the terminal keeps sessions (`~/.kiso/projects/<enc>/`), so the history lists the Works of every folder. The folder
+a new task starts in is `KISO_WEB_WORKSPACE`, else the one used last while it still exists, else the home folder; another is chosen in
+the page's folder browser (folders only; from home, or from a full path typed in). Notifications are off until turned on in Settings,
+and only while the page is open. See `src/main/env.ts` for the rest (`KISO_WEB_FAUX` runs a scripted model, for the proofs).
+
+The proofs budget (`scripts/proofs`) is 2,100 lines from W1c on, by an owner ruling of 2026-11-01 (it was 1,800 from W1b by a ruling of 2026-10-31, 1,600 from S5 by a ruling of 2026-10-26, 1,300 from S4 by a ruling of 2026-10-25, 1,000 from S2 by a ruling of 2026-10-23, and 700 before); the other budgets are unchanged.
+
+Plans, mocks and screenshots live outside this repository.

package/dist/main/agent.js

@@ -0,0 +1,80 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { Agent, createAgent, kisoHome, runsACheck } from "@vincemakes/kiso-runtime";
+import { adapterOptionsFor } from "@vincemakes/kiso-code/config";
+import { createCodingTools } from "@vincemakes/kiso-tools-node";
+import { CODING_TOOL_RULES, breakerExtension, composeSystemPrompt, floorExtension, modeExtensions, modeSystemPrompt, protectedShellExtension, readOnlyShellExtension, setMode, } from "@vincemakes/kiso-code/policy";
+import { observedRevisionFrom } from "./observed-revision.js";
+/** The adapter identity a model is routed by (what pricing is looked up on). */
+export const routeOf = (model) => (model.kind === "adapter" ? model.route : model.profile.kind);
+const DEFAULT_WINDOW = 200_000;
+/** The credential store is never served to a model: file tools and shell checks share this list. */
+export function protectedFiles() {
+    return [join(kisoHome(), "auth.json")];
+}
+/** The agent subclass the service opens per session: it binds the session's
+ *  task delivery after the runtime creates the session — the service gives
+ *  a host no other hook on the Session object. */
+class WebAgent extends Agent {
+    #options;
+    constructor(definition, options) {
+        super(definition);
+        this.#options = options;
+    }
+    async session(options) {
+        const session = await super.session(options);
+        this.#options.onSession?.(options.id, session);
+        return session;
+    }
+}
+/** The system prompt a Work's agent is built with: the terminal's prompt for the folder (its project instructions included), and the tier's note. */
+export function promptOf(workspace, tier) {
+    return [composeSystemPrompt(workspace, protectedFiles()), modeSystemPrompt(tier)].join("\n\n");
+}
+export function createWebAgent(options) {
+    const { store, workspace, model } = options;
+    const root = () => workspace;
+    const toolOptions = {
+        workspaceRoot: workspace,
+        excludeRoots: [kisoHome()],
+        secretEnvNames: options.secretEnvNames ?? [],
+        protectedFiles: protectedFiles(),
+        tasks: options.tasks.shellTasks,
+        observedRevision: observedRevisionFrom(store, workspace),
+        ...(options.toolLimits !== undefined ? { limits: options.toolLimits } : {}),
+    };
+    const window = model.kind === "profile" ? model.contextWindow : undefined;
+    const definition = {
+        model: model.kind === "adapter" ? model.model : model.profile.model,
+        store,
+        workspace,
+        systemPrompt: promptOf(workspace, options.tier()),
+        toolRules: CODING_TOOL_RULES,
+        tools: [...createCodingTools(toolOptions)],
+        // the terminal's chain, in its order: the guards that deny speak first
+        extensions: [
+            protectedShellExtension({ files: protectedFiles, workspaceRoot: root, env: () => ({ home: homedir(), kisoHome: kisoHome() }) }),
+            floorExtension(() => true, root),
+            breakerExtension(),
+            ...modeExtensions(root, options.tier),
+            readOnlyShellExtension(() => ({ workspaceRoot: workspace, excludeRoots: toolOptions.excludeRoots })),
+        ],
+        // in-run compaction, as the terminal turns it on (ADR-0055): only a window someone stated arms the overflow belt
+        contextPolicy: {
+            tiers: {
+                windowTokens: window ?? DEFAULT_WINDOW,
+                isCheck: (command) => runsACheck(command, options.checkRunners ?? []),
+                statedWindow: () => window ?? null,
+            },
+        },
+        ...(model.kind === "adapter"
+            ? { adapter: model.adapter }
+            : {
+                provider: model.profile.kind,
+                ...adapterOptionsFor(model.profile, model.auth, options.sessionId),
+                ...(model.profile.streamIdleMs !== undefined ? { streamIdleMs: model.profile.streamIdleMs } : {}),
+                ...(model.reasoning !== undefined ? { reasoning: model.reasoning } : {}),
+            }),
+    };
+    return options.onSession === undefined ? createAgent(definition) : new WebAgent(definition, options);
+}

package/dist/main/approvals.js

@@ -0,0 +1,68 @@
+const FRESH_MS = 15_000;
+const KEEP = 50;
+export class ApprovalWatch {
+    #spaces;
+    #notify;
+    #presence;
+    /** decisions already announced, per `key/session`; forgotten once answered */
+    #told = new Map();
+    /** Works seen running at the last look */
+    #running = new Set();
+    #notices = [];
+    #seq = 0;
+    #timer;
+    constructor(spaces, notify, presence) {
+        this.#spaces = spaces;
+        this.#notify = notify;
+        this.#presence = presence;
+    }
+    start(everyMs = 1_000) {
+        this.#timer = setInterval(() => void this.poll(), everyMs);
+        this.#timer.unref();
+    }
+    stop() {
+        clearInterval(this.#timer);
+    }
+    /** The notices after `seq` (the page keeps the last number it saw), and the newest number. */
+    since(seq) {
+        return { seq: this.#seq, notices: this.#notices.filter((n) => n.seq > seq) };
+    }
+    #announce(notice) {
+        const full = { ...notice, seq: ++this.#seq };
+        this.#notices.push(full);
+        if (this.#notices.length > KEEP)
+            this.#notices.shift();
+        this.#notify?.(full);
+    }
+    async poll() {
+        const p = this.#presence();
+        const here = p !== null && p.focused && Date.now() - p.at < FRESH_MS ? p : null;
+        for (const space of this.#spaces()) {
+            for (const sessionId of space.opened()) {
+                const id = `${space.key}/${sessionId}`;
+                const away = here === null || here.key !== space.key || here.session !== sessionId;
+                const folder = space.workspace.split("/").pop() ?? "";
+                const running = space.service.isRunning(sessionId);
+                if (running)
+                    this.#running.add(id);
+                else if (this.#running.delete(id) && away)
+                    this.#announce({ kind: "done", key: space.key, sessionId, folder });
+                const pending = running ? await space.service.pendingApprovals(sessionId).catch(() => []) : [];
+                const told = this.#told.get(id) ?? new Set();
+                const still = new Set();
+                for (const approval of pending) {
+                    if (told.has(approval.decisionId))
+                        still.add(approval.decisionId);
+                    else if (away) {
+                        still.add(approval.decisionId);
+                        this.#announce({ kind: "approval", key: space.key, sessionId, decisionId: approval.decisionId, tool: approval.name, folder });
+                    }
+                }
+                if (still.size === 0)
+                    this.#told.delete(id);
+                else
+                    this.#told.set(id, still);
+            }
+        }
+    }
+}

package/dist/main/artifacts.js

@@ -0,0 +1,166 @@
+import { closeSync, copyFileSync, existsSync, fstatSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, statSync } from "node:fs";
+import { basename, extname, isAbsolute, join, relative, resolve } from "node:path";
+import { resolveInside } from "./files.js";
+/**
+ * What a tool call made that the page can show, each "best effort, never a guess": an image block of its result; an artifact
+ * file a successful write or edit touched; or, for a command, a path its text or its output head names that is inside the
+ * folder, of an artifact type, exists, and changed at or after the step began. No folder scan, no watcher.
+ *
+ * A picture a command made OUTSIDE the folder (a browser tool saving a screenshot under /tmp: owner 2026-11-03, the screenshot
+ * must show in the stream) is kept as a copy in the Work's own `<id>.files/`, under the result's `log:` address: the page only
+ * ever reads the copy, never the outside path. Only a raster picture (no svg: it can carry script), named by the command or its
+ * output, changed during the step, at most KEEP_MAX bytes; it is copied once, so a later file of the same name does not replace
+ * it. This widens the 2026-10-31 rule "a file named outside the folder is not taken" for pictures only.
+ */
+const KINDS = {
+    ".png": "image", ".jpg": "image", ".jpeg": "image", ".gif": "image", ".webp": "image", ".svg": "image",
+    ".html": "page", ".htm": "page", ".md": "doc", ".pdf": "doc", ".csv": "doc",
+    ".mp4": "media", ".webm": "media", ".mov": "media", ".mp3": "media", ".wav": "media",
+};
+const NAMED = /[\w@+./-]+\.(?:png|jpe?g|gif|webp|svg|html?|md|pdf|csv|mp4|webm|mov|mp3|wav)\b/gi;
+/** a file's clock and the log's may differ by the file system's granularity */
+const SLACK_MS = 50;
+const KEPT = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif", ".webp": "image/webp" };
+const KEEP_MAX = 10 * 1024 * 1024;
+/** where a kept copy lives: the Work's own folder of files beside its log */
+const keptDir = (dir, workId) => join(dir, `${workId}.files`);
+export const artifactKind = (path) => KINDS[extname(path).toLowerCase()];
+/** `root`: the folder's real path; `dir`: the sessions directory, where a picture made outside the folder is kept. */
+export function artifactsOf(event, workId, call, root, dir) {
+    const out = [];
+    const ref = (n, kind, uri, mediaType, name) => {
+        out.push({ id: `${event.callId}:${n}`, workId, callId: event.callId, kind, uri, ...(mediaType !== undefined ? { mediaType } : {}), ...(name !== undefined ? { name } : {}) });
+    };
+    if (Array.isArray(event.content)) {
+        const blocks = event.content.filter((b) => b.type === "image").length;
+        let k = 0;
+        event.content.forEach((b, n) => {
+            if (b.type !== "image" || !((b.sourceType === "base64" && b.data !== undefined) || b.url?.startsWith("https:") === true))
+                return;
+            // an image block has no file name: the tool, the result's number and, of several, its place
+            const ext = (b.mediaType ?? "image/png").split("/")[1]?.replace("jpeg", "jpg") ?? "png";
+            ref(n, "image", `log:${event.seq}/${n}`, b.mediaType, `${call?.name ?? "image"}-${event.seq}${blocks > 1 ? `-${(k += 1)}` : ""}.${ext}`);
+        });
+    }
+    if (event.isError || call === null)
+        return out;
+    let kept = 0;
+    const outside = (full, since) => {
+        const ext = extname(full).toLowerCase();
+        if (KEPT[ext] === undefined || out.some((a) => a.id === `${event.callId}:${full}`))
+            return;
+        const name = `${event.seq}-k${kept}${ext}`;
+        const copy = join(keptDir(dir, workId), name);
+        try {
+            if (!existsSync(copy)) {
+                const stat = statSync(full);
+                if (!stat.isFile() || stat.mtimeMs < since - SLACK_MS || stat.size > KEEP_MAX)
+                    return;
+                mkdirSync(keptDir(dir, workId), { recursive: true });
+                copyFileSync(full, copy);
+            }
+        }
+        catch {
+            return;
+        }
+        ref(full, "image", `log:${event.seq}/k${kept}`, KEPT[ext], basename(full));
+        kept += 1;
+    };
+    const file = (raw, since) => {
+        const rel = relative(root, isAbsolute(raw) ? raw : resolve(root, raw));
+        const kind = artifactKind(rel);
+        if (rel.startsWith("..") && isAbsolute(raw) && since !== null)
+            return outside(raw, since);
+        if (kind === undefined || rel.startsWith("..") || out.some((a) => a.uri === `file:${rel}`))
+            return;
+        try {
+            const stat = statSync(resolveInside(root, rel));
+            if (stat.isFile() && (since === null || stat.mtimeMs >= since - SLACK_MS))
+                ref(rel, kind, `file:${rel}`);
+        }
+        catch {
+            // gone, outside, protected: not shown
+        }
+    };
+    const path = call.input["path"];
+    if ((call.name === "write_file" || call.name === "edit_file") && typeof path === "string")
+        file(path, null);
+    if (call.name === "shell" && call.startedAt !== null) {
+        const text = `${String(call.input["command"] ?? "")}\n${typeof event.content === "string" ? event.content.slice(0, 16_384) : ""}`;
+        for (const m of text.matchAll(NAMED))
+            file(m[0], call.startedAt);
+    }
+    return out;
+}
+/**
+ * Image blocks of results and of the person's own lines, read from the session's log: an index of seq to the byte range of its line, built once per log and
+ * extended as it grows, so a request reads one event, never the whole log.
+ */
+export class LogImages {
+    #dir;
+    #logs = new Map();
+    constructor(dir) {
+        this.#dir = dir;
+    }
+    /** The n-th block of the result or the line at `seq`: its bytes, an https address to pass on, or null; `k<n>`: the n-th
+     *  picture of that result kept from outside the folder. */
+    block(sessionId, seq, n) {
+        if (typeof n === "string") {
+            const name = (() => {
+                try {
+                    return readdirSync(keptDir(this.#dir, sessionId)).find((f) => f.startsWith(`${seq}-${n}.`));
+                }
+                catch {
+                    return undefined;
+                }
+            })();
+            const type = name === undefined ? undefined : KEPT[extname(name)];
+            return name === undefined || type === undefined ? null : { type, bytes: readFileSync(join(keptDir(this.#dir, sessionId), name)) };
+        }
+        const file = join(this.#dir, `${sessionId}.jsonl`);
+        const at = this.#index(file).get(seq);
+        if (at === undefined)
+            return null;
+        // a tool's result, or the person's own line (a picture pasted into the composer)
+        const event = JSON.parse(read(file, at[0], at[1]).toString("utf8")).event;
+        const b = (event.type === "tool_result" || event.type === "user_input") && Array.isArray(event.content) ? event.content[n] : undefined;
+        if (b?.type !== "image")
+            return null;
+        if (b.sourceType === "base64" && b.data !== undefined)
+            return { type: b.mediaType ?? "image/png", bytes: Buffer.from(b.data, "base64") };
+        return b.url?.startsWith("https:") === true ? { url: b.url } : null;
+    }
+    #index(file) {
+        let log = this.#logs.get(file);
+        const size = statSync(file).size;
+        if (log === undefined || size < log.size)
+            this.#logs.set(file, (log = { size: 0, lines: new Map() }));
+        if (size > log.size) {
+            const chunk = read(file, log.size, size - log.size);
+            let from = 0;
+            for (let nl = chunk.indexOf(10); nl !== -1; from = nl + 1, nl = chunk.indexOf(10, from)) {
+                try {
+                    const seq = JSON.parse(chunk.subarray(from, nl).toString("utf8")).event.seq;
+                    log.lines.set(seq, [log.size + from, nl - from]);
+                }
+                catch {
+                    // a line that is not a record: skipped
+                }
+            }
+            // a line still being written is read next time
+            log.size += from;
+        }
+        return log.lines;
+    }
+}
+function read(file, start, length) {
+    const fd = openSync(file, "r");
+    try {
+        const buf = Buffer.alloc(Math.max(0, Math.min(length, fstatSync(fd).size - start)));
+        readSync(fd, buf, 0, buf.length, start);
+        return buf;
+    }
+    finally {
+        closeSync(fd);
+    }
+}

package/dist/main/auth.js

@@ -0,0 +1,109 @@
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { chmodSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+/**
+ * The page's sign-in. The command that starts the host opens the browser on `#c=<code>`: a one-time connect code that lives two
+ * minutes. The page trades it once (`POST /auth/connect`) for a session cookie, `HttpOnly` and `SameSite=Strict`, named after the
+ * port, and strips the fragment: the page never holds a long-lived secret, and a cookie (unlike page storage) is what Safari copies
+ * into a web app added to the Dock. The host keeps the sessions in `$KISO_HOME/web.json` (mode 0600), as SHA-256 hashes only, and
+ * reads the file again when it changes, so `kiso-web --revoke-sessions` reaches a host that is running. A cookie on 127.0.0.1 is
+ * sent to every port of that host, so the cookie is never the whole guard: the Host and Origin checks stay on every request.
+ */
+const CODE_TTL_MS = 120_000;
+/** a year: the cookie outlives a browser restart and a Dock launch (browsers cap it near 400 days anyway) */
+const COOKIE_AGE_S = 365 * 86_400;
+const MAX_SESSIONS = 50;
+const sha256 = (text) => createHash("sha256").update(text).digest("hex");
+export const cookieName = (port) => `kiso_web_${port}`;
+export const webFile = (home) => join(home, "web.json");
+function readWeb(file) {
+    try {
+        return JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+function writeWeb(file, data) {
+    mkdirSync(dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(data, null, "\t")}\n`, { mode: 0o600 });
+    chmodSync(tmp, 0o600);
+    renameSync(tmp, file);
+}
+/** Forget every session: each page signed in before must be opened again from the command. Returns how many were forgotten. */
+export function revokeSessions(home) {
+    const file = webFile(home);
+    const count = readWeb(file).sessions?.length ?? 0;
+    writeWeb(file, { ...readWeb(file), sessions: [] });
+    return count;
+}
+export class Auth {
+    #file;
+    #cookie;
+    #codes = new Map();
+    #hashes = new Set();
+    #stamp = "";
+    constructor(home, port) {
+        this.#file = webFile(home);
+        this.#cookie = cookieName(port);
+    }
+    /** A fresh one-time code for the browser's address. */
+    code() {
+        const now = Date.now();
+        for (const [c, at] of this.#codes)
+            if (now - at > CODE_TTL_MS)
+                this.#codes.delete(c);
+        const code = randomBytes(24).toString("base64url");
+        this.#codes.set(sha256(code), now);
+        return code;
+    }
+    /** Trade a code for a new session: the Set-Cookie value, or null (unknown, used or expired). */
+    connect(code) {
+        if (typeof code !== "string" || code.length > 128)
+            return null;
+        const key = sha256(code);
+        const at = this.#codes.get(key);
+        this.#codes.delete(key);
+        if (at === undefined || Date.now() - at > CODE_TTL_MS)
+            return null;
+        const session = randomBytes(32).toString("base64url");
+        const kept = (readWeb(this.#file).sessions ?? []).slice(-(MAX_SESSIONS - 1));
+        writeWeb(this.#file, { ...readWeb(this.#file), sessions: [...kept, { hash: sha256(session), createdAt: Date.now() }] });
+        return `${this.#cookie}=${session}; HttpOnly; SameSite=Strict; Path=/; Max-Age=${COOKIE_AGE_S}`;
+    }
+    /** Whether the request carries a session cookie the host still keeps. */
+    signedIn(req) {
+        const given = (req.headers.cookie ?? "")
+            .split(";")
+            .map((part) => part.trim())
+            .find((part) => part.startsWith(`${this.#cookie}=`))
+            ?.slice(this.#cookie.length + 1);
+        if (given === undefined || given === "")
+            return false;
+        this.#reload();
+        const hash = Buffer.from(sha256(given));
+        for (const known of this.#hashes)
+            if (timingSafeEqual(Buffer.from(known), hash))
+                return true;
+        return false;
+    }
+    /** The cookie that ends this browser's session (a sign-out). */
+    cleared() {
+        return `${this.#cookie}=; HttpOnly; SameSite=Strict; Path=/; Max-Age=0`;
+    }
+    #reload() {
+        let stamp = "none";
+        try {
+            const s = statSync(this.#file);
+            stamp = `${s.mtimeMs}:${s.size}`;
+        }
+        catch {
+            // no file: no session
+        }
+        if (stamp === this.#stamp)
+            return;
+        this.#stamp = stamp;
+        this.#hashes = new Set((readWeb(this.#file).sessions ?? []).map((s) => s.hash));
+    }
+}

package/dist/main/context.js

@@ -0,0 +1,20 @@
+import { kisoHome } from "@vincemakes/kiso-runtime";
+import { tiersFor } from "@vincemakes/kiso-runtime/internal";
+import { CODING_TOOL_RULES, composeSystemPrompt, SYSTEM_PROMPT } from "@vincemakes/kiso-code/policy";
+import { createCodingTools } from "@vincemakes/kiso-tools-node";
+import { promptOf, protectedFiles } from "./agent.js";
+/** What the Work's requests always carry, in bytes, for the rail's Context breakdown (an estimate the page labels as one), and where
+ *  compaction starts and must happen for the stated window (the runtime's own tiers; null without a stated window). */
+export function contextParts(workspace, tier, window) {
+    const bytes = (s) => Buffer.byteLength(s, "utf8");
+    const prompt = promptOf(workspace, tier);
+    const instructions = Math.max(0, bytes(composeSystemPrompt(workspace, protectedFiles())) - bytes(SYSTEM_PROMPT));
+    const tools = createCodingTools({ workspaceRoot: workspace, excludeRoots: [kisoHome()], secretEnvNames: [], protectedFiles: protectedFiles() });
+    const tiers = window === null ? null : tiersFor(window, 0);
+    return {
+        system: bytes(prompt) - instructions + CODING_TOOL_RULES.reduce((n, r) => n + bytes(r.line) + 1, 0),
+        instructions,
+        tools: { count: tools.length, bytes: tools.reduce((n, t) => n + bytes(JSON.stringify({ name: t.name, description: t.description, parameters: t.parameters })), 0) },
+        compaction: tiers === null ? null : { starts: tiers.soft, must: tiers.hard },
+    };
+}