iteration-cli 0.4.4 → 0.6.0

package/dist/turn-summary.js

@@ -0,0 +1,302 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { isLaunchDirectory, parseCollectorFrictionSummary, } from "iteration-trace-contracts";
+import * as z from "zod";
+import { collectorSource, ensurePrivateDirectory, } from "./storage.js";
+const REFRESH_INTERVAL_MS = 5 * 60 * 1000;
+const REQUEST_RETENTION_MS = 14 * 24 * 60 * 60 * 1000;
+const MAX_REFRESHES_PER_PASS = 20;
+const REQUEST_TIMEOUT_MS = 10_000;
+const HOOK_TIMEOUT_SECONDS = 1;
+const REQUEST_KEY_PATTERN = /^\d{1,10}$/;
+export function turnSummaryPaths(dataDirectory) {
+    const directory = path.join(dataDirectory, "turn-summary");
+    return {
+        directory,
+        script: path.join(directory, "stop-hook.sh"),
+        requests: path.join(directory, "requests"),
+        lines: path.join(directory, "lines"),
+        shown: path.join(directory, "shown"),
+    };
+}
+function shellQuote(value) {
+    return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+// The hook runs at the end of every agent turn, so it only reads files the
+// collector keeps current and never waits on the network. Every failure prints
+// the empty object both agents accept, so a broken summary never blocks a turn.
+function hookScript(paths) {
+    return `#!/bin/sh
+exec 2>/dev/null
+cat >/dev/null
+summary=${shellQuote(paths.directory)}
+quiet() { printf '{}\\n'; exit 0; }
+unset GIT_DIR GIT_WORK_TREE GIT_COMMON_DIR GIT_PREFIX
+cd "\${CLAUDE_PROJECT_DIR:-.}" || quiet
+directory=$(git rev-parse --show-toplevel) || quiet
+case $directory in /*) ;; *) quiet ;; esac
+set -- $(printf '%s' "$directory" | cksum)
+key=$1
+[ -n "$key" ] || quiet
+printf '%s\\n' "$directory" > "$summary/requests/$key"
+[ -f "$summary/lines/$key" ] || quiet
+{ IFS= read -r owner && IFS= read -r message; } < "$summary/lines/$key" || quiet
+[ "$owner" = "$directory" ] || quiet
+last=
+[ -f "$summary/shown/$key" ] && IFS= read -r last < "$summary/shown/$key"
+[ "$last" = "$message" ] && quiet
+printf '%s\\n' "$message" > "$summary/shown/$key" || quiet
+printf '%s\\n' "$message"
+`;
+}
+function hookCommand(paths) {
+    return `/bin/sh ${shellQuote(paths.script)}`;
+}
+function agentHookFile(config) {
+    return "claudeHome" in config
+        ? path.join(config.claudeHome, "settings.json")
+        : path.join(config.codexHome, "hooks.json");
+}
+const hookEntrySchema = z.object({ command: z.string().optional() }).loose();
+const hookGroupSchema = z
+    .object({ hooks: z.array(hookEntrySchema).optional() })
+    .loose();
+const hookFileSchema = z
+    .object({
+    hooks: z
+        .object({ Stop: z.array(hookGroupSchema).optional() })
+        .loose()
+        .optional(),
+})
+    .loose();
+async function readHookFile(filename) {
+    let contents;
+    let mode = 0o600;
+    try {
+        contents = await fs.readFile(filename, "utf8");
+        mode = (await fs.stat(filename)).mode & 0o777;
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return { file: {}, mode };
+        }
+        throw new Error(`Could not read agent hooks at ${filename}.`, {
+            cause: error,
+        });
+    }
+    let decoded;
+    try {
+        decoded = JSON.parse(contents);
+    }
+    catch (error) {
+        throw new Error(`Agent hooks at ${filename} are not valid JSON.`, {
+            cause: error,
+        });
+    }
+    const parsed = hookFileSchema.safeParse(decoded);
+    if (!parsed.success) {
+        throw new Error(`Agent hooks at ${filename} have an unexpected shape.`, {
+            cause: parsed.error,
+        });
+    }
+    return { file: parsed.data, mode };
+}
+async function writeHookFile(filename, file, mode) {
+    await fs.mkdir(path.dirname(filename), { recursive: true });
+    // Settings kept in a dotfiles repository are often symlinks; replacing the
+    // link with a file would silently detach them from that repository.
+    const target = await fs.realpath(filename).catch((error) => {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return filename;
+        throw error;
+    });
+    const temporary = `${target}.iteration-${process.pid}.tmp`;
+    await fs.writeFile(temporary, `${JSON.stringify(file, null, 2)}\n`, {
+        encoding: "utf8",
+        mode,
+    });
+    await fs.rename(temporary, target);
+}
+function withoutCommand(groups, command) {
+    return groups.flatMap((group) => {
+        const hooks = group.hooks?.filter((hook) => hook.command !== command);
+        if (hooks === undefined || hooks.length === group.hooks?.length)
+            return [group];
+        return hooks.length === 0 ? [] : [{ ...group, hooks }];
+    });
+}
+function hasCommand(groups, command) {
+    return groups.some((group) => group.hooks?.some((hook) => hook.command === command));
+}
+export async function installTurnSummary(config) {
+    const paths = turnSummaryPaths(config.dataDirectory);
+    await ensurePrivateDirectory(paths.directory);
+    await Promise.all([paths.requests, paths.lines, paths.shown].map(ensurePrivateDirectory));
+    await fs.writeFile(paths.script, hookScript(paths), {
+        encoding: "utf8",
+        mode: 0o700,
+    });
+    await fs.chmod(paths.script, 0o700);
+    const filename = agentHookFile(config);
+    const { file, mode } = await readHookFile(filename);
+    const command = hookCommand(paths);
+    const stop = file.hooks?.Stop ?? [];
+    if (hasCommand(stop, command))
+        return;
+    await writeHookFile(filename, {
+        ...file,
+        hooks: {
+            ...file.hooks,
+            Stop: [
+                ...stop,
+                {
+                    hooks: [
+                        { type: "command", command, timeout: HOOK_TIMEOUT_SECONDS },
+                    ],
+                },
+            ],
+        },
+    }, mode);
+}
+export async function uninstallTurnSummary(config) {
+    const filename = agentHookFile(config);
+    const { file, mode } = await readHookFile(filename);
+    const stop = file.hooks?.Stop ?? [];
+    const command = hookCommand(turnSummaryPaths(config.dataDirectory));
+    if (!hasCommand(stop, command))
+        return;
+    const remaining = withoutCommand(stop, command);
+    const { Stop: _removed, ...otherEvents } = file.hooks ?? {};
+    await writeHookFile(filename, {
+        ...file,
+        hooks: remaining.length === 0
+            ? otherEvents
+            : { ...otherEvents, Stop: remaining },
+    }, mode);
+}
+export function turnSummaryMessage(summary) {
+    if (summary.weekEpisodes === 0)
+        return null;
+    const episodes = `${summary.weekEpisodes} friction episode${summary.weekEpisodes === 1 ? "" : "s"}`;
+    const recent = summary.dayEpisodes === 0
+        ? ""
+        : ` · ${summary.dayEpisodes} new since yesterday`;
+    return `◆ Iteration · ${episodes} in this repo this week${recent}`;
+}
+export class TurnSummaryRefreshError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "TurnSummaryRefreshError";
+    }
+}
+async function fetchSummary(config, directory, fetcher, signal) {
+    const url = new URL("/api/traces/friction-summary", config.endpoint);
+    url.searchParams.set("directory", directory);
+    let response;
+    try {
+        response = await fetcher(url, {
+            headers: { authorization: `Bearer ${config.token}` },
+            signal: signal
+                ? AbortSignal.any([signal, AbortSignal.timeout(REQUEST_TIMEOUT_MS)])
+                : AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        if (signal?.aborted)
+            throw error;
+        throw new TurnSummaryRefreshError("Friction summary could not reach Iteration.", { cause: error });
+    }
+    if (response.status !== 200) {
+        throw new TurnSummaryRefreshError(`Friction summary failed with HTTP ${response.status}.`);
+    }
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch (error) {
+        throw new TurnSummaryRefreshError("Friction summary returned an unreadable response.", { cause: error });
+    }
+    const parsed = parseCollectorFrictionSummary(body);
+    if (!parsed.success)
+        throw new TurnSummaryRefreshError(parsed.error);
+    return parsed.value;
+}
+async function readRequest(filename) {
+    try {
+        const [directory] = (await fs.readFile(filename, "utf8")).split("\n");
+        return directory ?? null;
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+async function writeLine(paths, key, directory, message) {
+    const filename = path.join(paths.lines, key);
+    if (message === null) {
+        await fs.rm(filename, { force: true });
+        return;
+    }
+    const temporary = `${filename}.${process.pid}.tmp`;
+    await fs.writeFile(temporary, `${directory}\n${JSON.stringify({ systemMessage: message })}\n`, { encoding: "utf8", mode: 0o600 });
+    await fs.rename(temporary, filename);
+}
+async function forget(paths, key) {
+    await Promise.all([paths.requests, paths.lines, paths.shown].map((directory) => fs.rm(path.join(directory, key), { force: true })));
+}
+// Refreshes the summary line for each repository the hook asked about. The
+// hook reads the result on a later turn, so a slow or failed request never
+// delays the agent.
+export async function refreshTurnSummaries(config, refreshedAt, nowMs, fetcher = fetch, signal) {
+    const paths = turnSummaryPaths(config.dataDirectory);
+    let keys;
+    try {
+        keys = await fs.readdir(paths.requests);
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return 0;
+        throw error;
+    }
+    let refreshed = 0;
+    for (const key of keys.sort()) {
+        signal?.throwIfAborted();
+        if (!REQUEST_KEY_PATTERN.test(key))
+            continue;
+        const filename = path.join(paths.requests, key);
+        const stats = await fs.stat(filename).catch((error) => {
+            if (error instanceof Error && "code" in error && error.code === "ENOENT")
+                return null;
+            throw error;
+        });
+        if (stats === null)
+            continue;
+        const directory = await readRequest(filename);
+        if (nowMs - stats.mtimeMs > REQUEST_RETENTION_MS ||
+            directory === null ||
+            !isLaunchDirectory(directory)) {
+            await forget(paths, key);
+            refreshedAt.delete(key);
+            continue;
+        }
+        const previous = refreshedAt.get(key);
+        if (previous !== undefined &&
+            previous.directory === directory &&
+            nowMs - previous.atMs < REFRESH_INTERVAL_MS) {
+            continue;
+        }
+        if (refreshed === MAX_REFRESHES_PER_PASS)
+            break;
+        refreshedAt.set(key, { directory, atMs: nowMs });
+        refreshed += 1;
+        const summary = await fetchSummary(config, directory, fetcher, signal);
+        await writeLine(paths, key, directory, turnSummaryMessage(summary));
+    }
+    return refreshed;
+}
+export function turnSummaryApprovalHint(config) {
+    return collectorSource(config) === "codex"
+        ? " Approve Iteration's turn summary once with /hooks in Codex."
+        : "";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iteration-cli",
-  "version": "0.4.4",
+  "version": "0.6.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -18,7 +18,7 @@
   },
   "dependencies": {
     "zod": "4.6.4",
-    "iteration-trace-contracts": "0.3.0"
+    "iteration-trace-contracts": "0.6.0"
   },
   "scripts": {
     "build": "pnpm --filter iteration-trace-contracts build && tsc -p tsconfig.json"