mtech-ai-local-runner 0.1.53 → 0.1.55

package/dist/src/guide/company.js

@@ -0,0 +1,102 @@
+import { readFile, readdir, stat } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { MULTI_REPOSITORY, UNREGISTERED } from "./types.js";
+const NOT_COMPANY = Object.freeze({ company: false, projectKey: null });
+const SCAN_LIMIT = 200;
+const SCAN_MS = 50;
+const MAX_DEPTH = 64;
+const URL_REMOTE = /^(?:https?|ssh|git):\/\/(?:[^@/]*@)?([^/:]+)(?::\d+)?\/([^/]+)\/([^/]+?)(?:\.git)?\/?$/i;
+const SCP_REMOTE = /^[^@\s/]+@([^:\s/]+):([^/\s]+)\/([^/\s]+?)(?:\.git)?$/i;
+/** The host, workspace and repository of a remote URL. The user part, and any token in it, is dropped. */
+export function parseRemote(url) {
+    const trimmed = url.trim();
+    const match = URL_REMOTE.exec(trimmed) ?? SCP_REMOTE.exec(trimmed);
+    if (!match)
+        return null;
+    return { host: match[1].toLowerCase(), workspace: match[2].toLowerCase(), repository: match[3].toLowerCase() };
+}
+/** The url of [remote "origin"] in a git config text, or null. */
+export function originUrl(config) {
+    let inOrigin = false;
+    for (const raw of config.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (line.startsWith("[")) {
+            inOrigin = /^\[remote\s+"origin"\]$/.test(line);
+            continue;
+        }
+        const match = inOrigin ? /^url\s*=\s*(.+)$/.exec(line) : null;
+        if (match)
+            return match[1].trim();
+    }
+    return null;
+}
+const isBitbucket = (host) => host === "bitbucket.org" || host.endsWith(".bitbucket.org");
+/** The repository name when the config's origin is a company remote, else null. */
+async function companyRepository(configPath, policy) {
+    let text;
+    try {
+        text = await readFile(configPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    const url = originUrl(text);
+    const remote = url === null ? null : parseRemote(url);
+    return remote !== null && isBitbucket(remote.host) && policy.companyWorkspaces.includes(remote.workspace) ? remote.repository : null;
+}
+/** The config file of the clone that holds dir, following a worktree's .git file to the main clone; null outside one. */
+async function gitConfigFor(start) {
+    let dir = resolve(start);
+    for (let depth = 0; depth < MAX_DEPTH; depth += 1) {
+        const dotGit = join(dir, ".git");
+        const info = await stat(dotGit).catch(() => null);
+        if (info?.isDirectory())
+            return join(dotGit, "config");
+        if (info?.isFile()) {
+            const pointer = /^gitdir:\s*(.+)$/m.exec(await readFile(dotGit, "utf8").catch(() => ""))?.[1]?.trim();
+            if (!pointer)
+                return null;
+            const gitDir = isAbsolute(pointer) ? pointer : resolve(dir, pointer);
+            const common = (await readFile(join(gitDir, "commondir"), "utf8").catch(() => "")).trim();
+            return join(common === "" ? gitDir : isAbsolute(common) ? common : resolve(gitDir, common), "config");
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+    return null;
+}
+export async function classifyWorkspace(cwd, policy, clock = Date.now) {
+    if (typeof cwd !== "string" || !isAbsolute(cwd))
+        return NOT_COMPANY;
+    const config = await gitConfigFor(cwd);
+    if (config !== null) {
+        const repository = await companyRepository(config, policy);
+        if (repository === null)
+            return NOT_COMPANY;
+        return { company: true, projectKey: Object.hasOwn(policy.repositories, repository) ? policy.repositories[repository] : UNREGISTERED };
+    }
+    // Not inside a clone: a folder that holds company clones, such as ~/Projects, counts as company work.
+    const started = clock();
+    let names;
+    try {
+        names = (await readdir(cwd)).sort().slice(0, SCAN_LIMIT);
+    }
+    catch {
+        return NOT_COMPANY;
+    }
+    for (const name of names) {
+        if (clock() - started > SCAN_MS)
+            break;
+        if (name.startsWith("."))
+            continue;
+        const dotGit = join(cwd, name, ".git");
+        const info = await stat(dotGit).catch(() => null);
+        if (!info?.isDirectory())
+            continue;
+        if (await companyRepository(join(dotGit, "config"), policy) !== null)
+            return { company: true, projectKey: MULTI_REPOSITORY };
+    }
+    return NOT_COMPANY;
+}

package/dist/src/guide/doctor.js

@@ -0,0 +1,47 @@
+import { guideStatusOf } from "../asks/commands.js";
+import { aggregateDay, sumDays } from "./aggregate.js";
+import { eventDays, lastEventAt, readDetails, readEventLines, readPolicyCache, utcDate } from "./files.js";
+import { codexGuideTrust } from "./integrations.js";
+import { GUIDE_APPS } from "./types.js";
+const RECENT_LINES = 20;
+const CODEX_GUIDE_TRUST = "Codex runs the two guide hooks only after you trust them once. In the Codex app, trust them under Settings → Hooks "
+    + "or with the Review hooks button. In the Codex CLI in a terminal, trust them with /hooks.";
+export async function guideDoctorReport(input) {
+    const now = input.now ?? Date.now();
+    try {
+        const cached = await readPolicyCache(input.stateRoot, now);
+        const integrations = [];
+        for (const app of GUIDE_APPS) {
+            const status = await guideStatusOf(app, input.env, input.stateRoot);
+            if (status.state === "not_installed") {
+                integrations.push(status);
+                continue;
+            }
+            const last = await lastEventAt(input.stateRoot, app);
+            if (app === "codex") {
+                const trusted = await codexGuideTrust(input.env);
+                integrations.push({ ...status, trusted, last_event_at: last, ...(trusted === "yes" ? {} : { action: CODEX_GUIDE_TRUST }) });
+            }
+            else {
+                integrations.push({ ...status, last_event_at: last });
+            }
+        }
+        const today = (await eventDays(input.stateRoot)).get(utcDate(now));
+        const lines = today === undefined ? [] : await readEventLines([today.reported, today.fresh].filter((path) => path !== undefined));
+        const groups = [...aggregateDay(lines).values()];
+        return {
+            policy: cached === null ? null : { version: cached.policy.version, confirmed_seconds_ago: Math.max(0, Math.floor((now - cached.confirmedAt) / 1000)),
+                stale: cached.stale, rules: cached.policy.rules },
+            integrations,
+            today: groups.length === 0 ? null : sumDays(groups),
+            recent: (await readDetails(input.stateRoot, [utcDate(now - 86_400_000), utcDate(now)])).slice(-RECENT_LINES),
+        };
+    }
+    catch {
+        return { policy: null, integrations: [], today: null, recent: [] };
+    }
+}
+/** Doctor prints its guide section only once guide has a policy or a hook on this Mac. */
+export function guideReportShown(report) {
+    return report.policy !== null || report.integrations.some(item => item.state !== "not_installed");
+}

package/dist/src/guide/files.js

@@ -0,0 +1,237 @@
+import { createHash } from "node:crypto";
+import { appendFile, mkdir, readFile, readdir, rename, rm, stat, utimes, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { GUIDE_DIR, STALE_POLICY_MS, isGuideApp, isOutcome, isRuleId, parseGuidancePolicy } from "./types.js";
+const DIR_MODE = 0o700;
+const FILE_MODE = 0o600;
+const MAX_OWN_WRITES = 200;
+export const SESSION_TTL_MS = 48 * 3_600_000;
+export const LOCAL_RETENTION_DAYS = 14;
+const DAY_FILE = /^(\d{4}-\d{2}-\d{2})(\.reported)?\.ndjson$/;
+export const guidePath = (stateRoot, ...parts) => join(stateRoot, GUIDE_DIR, ...parts);
+export const utcDate = (ms) => new Date(ms).toISOString().slice(0, 10);
+/** sha256 of the app and the session id. It names the session's file; its first 16 characters tag the session's count lines. */
+export function sessionHash(app, sessionId) {
+    return createHash("sha256").update(`${app}\0${sessionId}`).digest("hex");
+}
+async function writeAtomic(path, content) {
+    await mkdir(dirname(path), { recursive: true, mode: DIR_MODE });
+    const temporary = `${path}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`;
+    try {
+        await writeFile(temporary, content, { mode: FILE_MODE, flag: "wx" });
+        await rename(temporary, path);
+    }
+    catch (error) {
+        await rm(temporary, { force: true });
+        throw error;
+    }
+}
+async function readJson(path) {
+    try {
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export async function readPolicyCache(stateRoot, now) {
+    const raw = await readJson(guidePath(stateRoot, "policy.json"));
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const { policy, confirmed_at: confirmedAt } = raw;
+    const parsed = parseGuidancePolicy(policy);
+    if (parsed === null || typeof confirmedAt !== "number" || !Number.isSafeInteger(confirmedAt))
+        return null;
+    return { policy: parsed, confirmedAt, stale: now - confirmedAt > STALE_POLICY_MS };
+}
+/** Caches the policy exactly as the Gateway sent it, confirmed at confirmedAt. */
+export async function writePolicyCache(stateRoot, wirePolicy, confirmedAt) {
+    await writeAtomic(guidePath(stateRoot, "policy.json"), `${JSON.stringify({ policy: wirePolicy, confirmed_at: confirmedAt })}\n`);
+}
+/** Moves the cached policy's confirmation time. Resolves false when there is no valid cache. */
+export async function confirmPolicyCache(stateRoot, confirmedAt) {
+    const raw = await readJson(guidePath(stateRoot, "policy.json"));
+    const policy = raw !== null && typeof raw === "object" ? raw.policy : undefined;
+    if (parseGuidancePolicy(policy) === null)
+        return false;
+    await writePolicyCache(stateRoot, policy, confirmedAt);
+    return true;
+}
+/** Removes everything guide keeps. Used when the Gateway says guide is off for this person, so nothing waits to be sent. */
+export async function deleteGuideState(stateRoot) {
+    await rm(join(stateRoot, GUIDE_DIR), { recursive: true, force: true });
+}
+function isSession(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const state = value;
+    return typeof state.company === "boolean" && (state.projectKey === null || typeof state.projectKey === "string")
+        && typeof state.counted === "boolean" && typeof state.searched === "boolean"
+        && Array.isArray(state.warned) && state.warned.every(isRuleId)
+        && Array.isArray(state.ownWrites) && state.ownWrites.every(path => typeof path === "string")
+        && state.details !== null && typeof state.details === "object" && !Array.isArray(state.details);
+}
+export async function readSession(stateRoot, hash) {
+    const value = await readJson(guidePath(stateRoot, "sessions", `${hash}.json`));
+    return isSession(value) ? value : null;
+}
+export async function writeSession(stateRoot, hash, state) {
+    await writeAtomic(guidePath(stateRoot, "sessions", `${hash}.json`), `${JSON.stringify({ ...state, ownWrites: state.ownWrites.slice(-MAX_OWN_WRITES) })}\n`);
+}
+async function appendLines(stateRoot, folder, lines) {
+    if (lines.length === 0)
+        return;
+    const byDate = new Map();
+    for (const line of lines) {
+        const date = utcDate(line.t * 1000);
+        byDate.set(date, `${byDate.get(date) ?? ""}${JSON.stringify(line)}\n`);
+    }
+    await mkdir(guidePath(stateRoot, folder), { recursive: true, mode: DIR_MODE });
+    for (const [date, text] of byDate)
+        await appendFile(guidePath(stateRoot, folder, `${date}.ndjson`), text, { mode: FILE_MODE });
+}
+export async function appendEvents(stateRoot, lines) { await appendLines(stateRoot, "events", lines); }
+export async function appendDetails(stateRoot, lines) { await appendLines(stateRoot, "detail", lines); }
+export async function stampLastEvent(stateRoot, app, now) {
+    const path = guidePath(stateRoot, "last", app);
+    const time = new Date(now);
+    try {
+        await utimes(path, time, time);
+        return;
+    }
+    catch { /* Not there yet. */ }
+    await mkdir(dirname(path), { recursive: true, mode: DIR_MODE });
+    await writeFile(path, "", { mode: FILE_MODE });
+    await utimes(path, time, time);
+}
+/** The last hook run of an app, rounded down to the hour, so the heartbeat changes at most hourly; null before any. */
+export async function lastEventAt(stateRoot, app) {
+    try {
+        return Math.floor((await stat(guidePath(stateRoot, "last", app))).mtimeMs / 3_600_000) * 3600;
+    }
+    catch {
+        return null;
+    }
+}
+export async function eventDays(stateRoot) {
+    const days = new Map();
+    let names = [];
+    try {
+        names = await readdir(guidePath(stateRoot, "events"));
+    }
+    catch {
+        return days;
+    }
+    for (const name of names) {
+        const match = DAY_FILE.exec(name);
+        if (!match)
+            continue;
+        const day = days.get(match[1]) ?? {};
+        if (match[2])
+            day.reported = guidePath(stateRoot, "events", name);
+        else
+            day.fresh = guidePath(stateRoot, "events", name);
+        days.set(match[1], day);
+    }
+    return days;
+}
+export async function readEventLines(paths) {
+    const lines = [];
+    for (const path of paths) {
+        let text = "";
+        try {
+            text = await readFile(path, "utf8");
+        }
+        catch {
+            continue;
+        }
+        for (const raw of text.split("\n")) {
+            if (raw === "")
+                continue;
+            try {
+                const line = JSON.parse(raw);
+                if (typeof line.t === "number" && isGuideApp(line.a) && typeof line.p === "string" && typeof line.s === "string"
+                    && typeof line.m === "string" && typeof line.n === "number")
+                    lines.push(line);
+            }
+            catch { /* A line a crash cut short is skipped. */ }
+        }
+    }
+    return lines;
+}
+export async function readDetails(stateRoot, dates) {
+    const lines = [];
+    for (const date of dates) {
+        let text = "";
+        try {
+            text = await readFile(guidePath(stateRoot, "detail", `${date}.ndjson`), "utf8");
+        }
+        catch {
+            continue;
+        }
+        for (const raw of text.split("\n")) {
+            if (raw === "")
+                continue;
+            try {
+                const line = JSON.parse(raw);
+                if (typeof line.t === "number" && isGuideApp(line.a) && isRuleId(line.r) && isOutcome(line.o) && typeof line.x === "string")
+                    lines.push(line);
+            }
+            catch { /* Skipped. */ }
+        }
+    }
+    return lines;
+}
+/**
+ * Moves a reported day's fresh lines into <date>.reported.ndjson. A hook that appends while this runs writes a new fresh
+ * file, which the next pass reports together with everything else of that day.
+ */
+export async function markReported(stateRoot, date) {
+    const fresh = guidePath(stateRoot, "events", `${date}.ndjson`);
+    const merging = `${fresh}.${process.pid}.merging`;
+    try {
+        await rename(fresh, merging);
+    }
+    catch {
+        return;
+    }
+    const text = await readFile(merging, "utf8").catch(() => "");
+    await appendFile(guidePath(stateRoot, "events", `${date}.reported.ndjson`), text, { mode: FILE_MODE });
+    await rm(merging, { force: true });
+}
+/** Removes a day the Gateway refused, so it is not sent again. */
+export async function dropDay(stateRoot, date) {
+    await rm(guidePath(stateRoot, "events", `${date}.ndjson`), { force: true });
+    await rm(guidePath(stateRoot, "events", `${date}.reported.ndjson`), { force: true });
+}
+/** Day files older than fourteen days, and sessions untouched for two days, are deleted. */
+export async function pruneGuideFiles(stateRoot, now) {
+    const oldest = utcDate(now - LOCAL_RETENTION_DAYS * 86_400_000);
+    for (const folder of ["events", "detail"]) {
+        let names = [];
+        try {
+            names = await readdir(guidePath(stateRoot, folder));
+        }
+        catch {
+            continue;
+        }
+        for (const name of names) {
+            const date = /^(\d{4}-\d{2}-\d{2})/.exec(name)?.[1];
+            if (date !== undefined && date < oldest)
+                await rm(guidePath(stateRoot, folder, name), { force: true });
+        }
+    }
+    let sessions = [];
+    try {
+        sessions = await readdir(guidePath(stateRoot, "sessions"));
+    }
+    catch {
+        return;
+    }
+    for (const name of sessions) {
+        const path = guidePath(stateRoot, "sessions", name);
+        const info = await stat(path).catch(() => null);
+        if (info !== null && now - info.mtimeMs > SESSION_TTL_MS)
+            await rm(path, { force: true });
+    }
+}

package/dist/src/guide/hook-client.js

@@ -0,0 +1,289 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { stat } from "node:fs/promises";
+import { isAbsolute, join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { classifyWorkspace } from "./company.js";
+import { appendDetails, appendEvents, readPolicyCache, readSession, sessionHash, stampLastEvent, writeSession } from "./files.js";
+import { classifyToolCall, knowledgeBaseTail } from "./matching.js";
+import { KB_SEARCH_FIRST_TEXT, SESSION_GUIDANCE_TEXT, cliRuleText } from "./templates.js";
+import { MAX_HOOK_INPUT_BYTES, RULE_IDS, SESSION_ID, UNREGISTERED, isGuideApp, isGuideEvent } from "./types.js";
+const STDIN_TIMEOUT_MS = 1000;
+const STATE_ROOT_FLAG = "--state-root=";
+const MAX_DETAILS_PER_RULE = 20;
+const MAX_OWN_WRITES = 200;
+const START_SOURCES = new Set(["startup", "clear", "compact"]);
+/** The same values as the asks hook client (src/asks/hook-client.ts): a test keeps the two in step. */
+const INTERACTIVE_ENTRYPOINTS = new Set(["cli", "claude-desktop", "claude-vscode"]);
+const CLAUDE_JOBS_DIR = "claude-jobs";
+const TRUNCATED_SESSION_ID = /"session_id"\s*:\s*"([^"\\]{1,128})"/;
+function isRunnerJobHome(env, stateRoot) {
+    const home = env.HOME;
+    if (!home || !isAbsolute(home))
+        return false;
+    const roots = new Set([resolve(stateRoot)]);
+    try {
+        roots.add(realpathSync(stateRoot));
+    }
+    catch { /* A state root that does not exist holds no jobs. */ }
+    const resolved = resolve(home);
+    return [...roots].some(root => resolved.startsWith(join(root, CLAUDE_JOBS_DIR) + sep));
+}
+/** True when a person attends the session: the asks hook client's rule, repeated so this client loads nothing of asks. */
+export function isHumanSession(app, env, stateRoot) {
+    if (isRunnerJobHome(env, stateRoot))
+        return false;
+    if (app !== "claude")
+        return true;
+    const attended = env.CLAUDE_CODE_SESSION_ATTENDED;
+    if (attended !== undefined && attended !== "")
+        return attended === "1";
+    return INTERACTIVE_ENTRYPOINTS.has(env.CLAUDE_CODE_ENTRYPOINT ?? "");
+}
+function stateRootFrom(env) {
+    return env.XDG_STATE_HOME ? join(env.XDG_STATE_HOME, "mtec-ai-local-runner") : join(env.HOME ?? "", ".local", "state", "mtec-ai-local-runner");
+}
+function parseArguments(argv, env) {
+    const rest = [...argv];
+    let stateRoot = stateRootFrom(env);
+    if (rest[0]?.startsWith(STATE_ROOT_FLAG)) {
+        stateRoot = rest.shift().slice(STATE_ROOT_FLAG.length);
+        if (!isAbsolute(stateRoot))
+            return null;
+    }
+    const [app, event, ...extra] = rest;
+    if (extra.length > 0 || !isGuideApp(app) || !isGuideEvent(event))
+        return null;
+    return { stateRoot, app, event };
+}
+/** At most 64 KiB of hook input within a second. truncated says the input was longer; null when nothing came in time. */
+async function readInput(stdin, timeoutMs) {
+    let timer;
+    const timeout = new Promise(done => { timer = setTimeout(() => done(null), timeoutMs); });
+    const read = (async () => {
+        const chunks = [];
+        let size = 0;
+        for await (const chunk of stdin) {
+            const bytes = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+            if (size + bytes.length > MAX_HOOK_INPUT_BYTES) {
+                chunks.push(bytes.subarray(0, MAX_HOOK_INPUT_BYTES - size));
+                return { text: Buffer.concat(chunks).toString("utf8"), truncated: true };
+            }
+            size += bytes.length;
+            chunks.push(bytes);
+        }
+        return { text: Buffer.concat(chunks).toString("utf8"), truncated: false };
+    })().catch(() => null);
+    try {
+        return await Promise.race([read, timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function parseRecord(raw) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+/** The count and detail lines of one hook run, written together at its end. */
+class Recorder {
+    app;
+    hash;
+    now;
+    events = [];
+    details = [];
+    constructor(app, hash, now) {
+        this.app = app;
+        this.hash = hash;
+        this.now = now;
+    }
+    line(session, metric, n) {
+        return { t: Math.floor(this.now / 1000), a: this.app, p: session.projectKey ?? UNREGISTERED, s: this.hash.slice(0, 16), m: metric, n };
+    }
+    count(session, metric, n = 1) {
+        this.events.push(this.line(session, metric, n));
+    }
+    rule(session, rule, outcome, subject) {
+        this.events.push({ ...this.line(session, "rule", 1), r: rule, o: outcome });
+        const written = session.details[rule] ?? 0;
+        if (subject !== "" && written < MAX_DETAILS_PER_RULE) {
+            session.details[rule] = written + 1;
+            this.details.push({ t: Math.floor(this.now / 1000), a: this.app, r: rule, o: outcome, x: subject });
+        }
+    }
+    async flush(stateRoot, session) {
+        await appendEvents(stateRoot, this.events);
+        await appendDetails(stateRoot, this.details);
+        await writeSession(stateRoot, this.hash, session);
+        await stampLastEvent(stateRoot, this.app, this.now);
+    }
+}
+/** A stale policy turns warn into observe; off stays off. */
+function effectiveModes(rules, stale) {
+    if (!stale)
+        return rules;
+    return Object.fromEntries(RULE_IDS.map(rule => [rule, rules[rule] === "warn" ? "observe" : rules[rule]]));
+}
+/**
+ * One rule's mode applied to one match: the text to add, or null. A rule other than session_guidance adds its text once
+ * per session; later matches, and a match while another text was already chosen, are counted as observed.
+ */
+function evaluate(rule, modes, session, recorder, subject, text, mayWarn) {
+    const mode = modes[rule];
+    if (mode === "off")
+        return null;
+    if (mode === "warn" && mayWarn && (rule === "session_guidance" || !session.warned.includes(rule))) {
+        if (rule !== "session_guidance")
+            session.warned.push(rule);
+        recorder.rule(session, rule, "warned", subject);
+        return text;
+    }
+    recorder.rule(session, rule, "observed", subject);
+    return null;
+}
+function absolute(path, cwd) {
+    return isAbsolute(path) ? resolve(path) : resolve(typeof cwd === "string" && isAbsolute(cwd) ? cwd : "/", path);
+}
+async function fileSize(path) {
+    try {
+        return (await stat(path)).size;
+    }
+    catch {
+        return 0;
+    }
+}
+async function toolText(app, record, modes, session, recorder, gatewayToolNames) {
+    const findings = classifyToolCall(app, record.tool_name, record.tool_input, gatewayToolNames);
+    if (findings === null) {
+        recorder.count(session, "undecidable");
+        return null;
+    }
+    let text = null;
+    for (const finding of findings) {
+        if (finding.kind === "knowledge_search") {
+            session.searched = true;
+            recorder.count(session, "knowledge_search_calls");
+        }
+        else if (finding.kind === "gateway_tool") {
+            recorder.count(session, "gateway_tool_calls");
+        }
+        else if (finding.kind === "kb_write") {
+            for (const path of finding.paths) {
+                const full = absolute(path, record.cwd);
+                if (!session.ownWrites.includes(full))
+                    session.ownWrites = [...session.ownWrites, full].slice(-MAX_OWN_WRITES);
+            }
+        }
+        else if (finding.kind === "kb_read") {
+            recorder.count(session, `kb_reads_${finding.readKind}`);
+            if (finding.readKind === "read_tool")
+                recorder.count(session, "kb_read_bytes", await fileSize(absolute(finding.paths[0], record.cwd)));
+            const foreign = finding.paths.filter(path => !session.ownWrites.includes(absolute(path, record.cwd)));
+            if (!session.searched && foreign.length > 0) {
+                const chosen = evaluate("kb_search_first", modes, session, recorder, knowledgeBaseTail(foreign[0]), KB_SEARCH_FIRST_TEXT, text === null);
+                text ??= chosen;
+            }
+        }
+        else {
+            const chosen = evaluate(finding.rule, modes, session, recorder, finding.subject, cliRuleText(finding.rule), text === null);
+            text ??= chosen;
+        }
+    }
+    return text;
+}
+/** Never throws, never writes to stderr and always resolves 0. */
+export async function runGuideHook(argv, io) {
+    try {
+        const args = parseArguments(argv, io.env);
+        if (args === null)
+            return 0;
+        const now = io.now?.() ?? Date.now();
+        const cached = await readPolicyCache(args.stateRoot, now);
+        // No policy: guide is off for this person, or the runner never synced. Nothing is printed or recorded.
+        if (cached === null || !isHumanSession(args.app, io.env, args.stateRoot))
+            return 0;
+        const input = await readInput(io.stdin, io.stdinTimeoutMs ?? STDIN_TIMEOUT_MS);
+        if (input === null)
+            return 0;
+        const record = input.truncated ? null : parseRecord(input.text);
+        const sessionId = record !== null ? record.session_id : TRUNCATED_SESSION_ID.exec(input.text)?.[1];
+        if (typeof sessionId !== "string" || !SESSION_ID.test(sessionId))
+            return 0;
+        const hash = sessionHash(args.app, sessionId);
+        const recorder = new Recorder(args.app, hash, now);
+        let session = await readSession(args.stateRoot, hash);
+        if (record === null) {
+            // Too large to read in full: counted only for a session already known as company work (planning decision 6).
+            if (session?.company) {
+                recorder.count(session, "undecidable");
+                await recorder.flush(args.stateRoot, session);
+            }
+            return 0;
+        }
+        if (session === null) {
+            const workspace = await classifyWorkspace(typeof record.cwd === "string" ? record.cwd : "", cached.policy);
+            session = { company: workspace.company, projectKey: workspace.projectKey, counted: false, searched: false, warned: [], ownWrites: [], details: {} };
+            if (!session.company) {
+                await writeSession(args.stateRoot, hash, session);
+                return 0;
+            }
+        }
+        if (!session.company)
+            return 0;
+        if (!session.counted) {
+            recorder.count(session, "session");
+            session.counted = true;
+        }
+        if (cached.stale)
+            recorder.count(session, "undecidable");
+        const modes = effectiveModes(cached.policy.rules, cached.stale);
+        let text = null;
+        if (args.event === "session-start") {
+            const source = record.source;
+            if (source === undefined || (typeof source === "string" && START_SOURCES.has(source))) {
+                text = evaluate("session_guidance", modes, session, recorder, "", SESSION_GUIDANCE_TEXT, true);
+            }
+        }
+        else {
+            text = await toolText(args.app, record, modes, session, recorder, cached.policy.gatewayToolNames);
+        }
+        if (text !== null)
+            recorder.count(session, "injected_chars", text.length);
+        // Recorded before anything is printed: a write that fails prints nothing (spec section 8).
+        await recorder.flush(args.stateRoot, session);
+        if (text !== null) {
+            io.stdout(JSON.stringify({ hookSpecificOutput: { hookEventName: args.event === "session-start" ? "SessionStart" : "PreToolUse", additionalContext: text } }));
+        }
+        return 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/** True when Node runs this file as its entry point, directly or through a symlink. */
+function isDirectInvocation(moduleUrl, argvPath) {
+    if (!argvPath)
+        return false;
+    try {
+        return realpathSync(fileURLToPath(moduleUrl)) === realpathSync(argvPath);
+    }
+    catch {
+        return false;
+    }
+}
+if (isDirectInvocation(import.meta.url, process.argv[1])) {
+    void runGuideHook(process.argv.slice(2), {
+        stdin: process.stdin,
+        stdout: text => { process.stdout.write(`${text}\n`); },
+        env: process.env,
+    }).then(() => {
+        process.exitCode = 0;
+        process.stdin.destroy();
+    });
+}