@assethub/cli 0.1.30 → 0.1.32

package/dist/hooks/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../src/hooks/install.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,YAAY,CAAA;AAE1C,eAAO,MAAM,WAAW,+DAAgE,CAAA;AACxF,eAAO,MAAM,oBAAoB,KAAK,CAAA;AACtC;;;GAGG;AACH,eAAO,MAAM,2BAA2B,KAAK,CAAA;AAC7C,eAAO,MAAM,oBAAoB,IAAI,CAAA;AAErC,wFAAwF;AACxF,MAAM,MAAM,SAAS,GAAG;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAC,CAAA;AAE7C,wEAAwE;AACxE,KAAK,WAAW,GAAG;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAC,CAAA;AAkBtD,mFAAmF;AACnF,eAAO,MAAM,qBAAqB,GAAI,OAAO,SAAS,EAAE,SAAQ,UAAqB,KAAG,MAmBvF,CAAA;AAWD,eAAO,MAAM,YAAY,GAAI,SAAS,OAAO,KAAG,OACa,CAAA;AAI7D,gFAAgF;AAChF,eAAO,MAAM,WAAW,GAAI,UAAU,MAAM,EAAE,SAAQ,UAAqB,KAAG,MACsB,CAAA;AAMpG;;;;GAIG;AACH,eAAO,MAAM,cAAc,GACzB,MAAM,MAAM,GAAG,SAAS,EACxB,OAAO,SAAS,EAChB,SAAQ,UAAqB,EAC7B,YAAY,MAAM,KACjB,OAAO,CAAC,MAAM,GAAG,SAAS,CAY5B,CAAA;AA6GD,KAAK,SAAS,GAAG;IAAC,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,IAAI,CAAA;CAAC,CAAA;AAElF;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,GACpB,OAAO,CAAC,OAAO,WAAW,EAAE,MAAM,CAAC,EACnC,SAAS,MAAM,EACf,SAAQ,UAAqB,KAC5B,SAK2E,CAAA;AAE9E,eAAO,MAAM,YAAY,GAAU,SAAS,SAAS,GAAG,WAAW,GAAG;IACpE,MAAM,EAAE,UAAU,CAAA;IAClB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,KAAG,OAAO,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,CA8C/C,CAAA;AAED,eAAO,MAAM,cAAc,GAAU,SAAS,SAAS,GAAG,WAAW,GAAG;IACtE,MAAM,EAAE,UAAU,CAAA;CACnB,KAAG,OAAO,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,CAqC7C,CAAA"}

package/dist/hooks/install.js

@@ -0,0 +1,286 @@
+// Register / remove our session hooks.
+//
+// Claude Code: one project's .claude/settings.local.json (the default for
+// `hooks install`), or with --global the user's ~/.claude/settings.json.
+// Codex: one project's .codex/hooks.json, or with --global
+// $CODEX_HOME/hooks.json. Codex has no personal per-project file, so the
+// project file is kept out of git (info/exclude) and a tracked one is refused.
+//
+// Merge rules: keep every existing key and hook, identify our entry by its
+// command string (`<assethub> hooks save`), never duplicate it, and back the
+// original file up before any change.
+import { execFile } from 'node:child_process';
+import { appendFile, copyFile, mkdir, readFile, readdir, realpath, rename, rm, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import { promisify } from 'node:util';
+import { resolveHome } from './paths.js';
+export const HOOK_EVENTS = ['SessionStart', 'Stop', 'SessionEnd', 'PreCompact'];
+export const HOOK_TIMEOUT_SECONDS = 30;
+/**
+ * SessionEnd hooks share a 1.5 s budget that a longer per-hook `timeout` raises
+ * (up to 60 s). The save itself is local; the upload runs in a detached process.
+ */
+export const SESSION_END_TIMEOUT_SECONDS = 10;
+export const MAX_SETTINGS_BACKUPS = 3;
+const CLIENT_NAME = { claude: 'Claude Code', codex: 'Codex' };
+const PROJECT_DIR = { claude: '.claude', codex: '.codex' };
+const PROJECT_FILE = { claude: 'settings.local.json', codex: 'hooks.json' };
+const projectSettingsPath = (projectDir, client = 'claude') => join(resolve(projectDir), PROJECT_DIR[client], PROJECT_FILE[client]);
+/** The client's user-level folder: ~/.claude, or $CODEX_HOME (default ~/.codex). */
+const userConfigDir = (client, paths) => client === 'codex' ? (paths.codexHome ?? join(resolveHome(paths.home), '.codex')) : join(resolveHome(paths.home), '.claude');
+const settingsPath = (client, paths, scope) => scope.projectDir
+    ? projectSettingsPath(scope.projectDir, client)
+    : join(userConfigDir(client, paths), client === 'codex' ? 'hooks.json' : 'settings.json');
+/** What `hooks install` and `setup` must tell the user before recording starts. */
+export const sessionSaveDisclosure = (scope, client = 'claude') => {
+    const name = CLIENT_NAME[client];
+    const where = scope.projectDir
+        ? `${projectSettingsPath(scope.projectDir, client)}. ` +
+            `Every ${name} session opened in ${resolve(scope.projectDir)} (and only there)`
+        : `${client === 'codex' ? '$CODEX_HOME/hooks.json' : '~/.claude/settings.json'} (--global). Every ${name} session on this machine, in any project,`;
+    const remove = scope.projectDir
+        ? `\`assethub hooks uninstall --client ${client}\` from that folder`
+        : `\`assethub hooks uninstall --client ${client} --global\``;
+    return (`Session saving adds SessionStart, Stop, PreCompact and SessionEnd hooks to ${where} ` +
+        'is then copied to ~/.assethub/sessions/ when it ends ' +
+        '(the conversation only: your prompts, the agent\'s replies and tool calls, with recognised secrets masked, readable only by you; copies older than 30 days are deleted), ' +
+        'and uploaded to AssetHub as a coding-agent session only you can read (internal accounts only for now): the masked transcript, ' +
+        'your prompts, the agent\'s replies, its tool calls and images from the project. Uploads that fail are retried in the background ' +
+        'when a later session starts or ends. Secret masking is best effort. ' +
+        'Opt a project out with .assethub/no-session-save, or turn it off with ASSETHUB_SESSION_SAVE=off / ASSETHUB_SESSION_UPLOAD=off; ' +
+        `remove it with ${remove}.`);
+};
+const isObject = (value) => value != null && typeof value === 'object' && !Array.isArray(value);
+// Only a command that runs the CLI itself: `assethub hooks save`, optionally a
+// (quoted) path to it. `echo assethub hooks save` is somebody else's hook.
+const OUR_COMMAND_RE = /^\s*(?:"(?:[^"]*[/\\])?assethub(?:\.js)?"|'(?:[^']*[/\\])?assethub(?:\.js)?'|(?:[^\s"']*[/\\])?assethub(?:\.js)?)\s+hooks\s+save(?:\s|$)/;
+export const isOurCommand = (command) => typeof command === 'string' && OUR_COMMAND_RE.test(command);
+const quoteIfNeeded = (value) => (/\s/.test(value) ? JSON.stringify(value) : value);
+/** Codex hooks name their client, so the saved session is recorded as Codex. */
+export const hookCommand = (cliPath, client = 'claude') => `${quoteIfNeeded(cliPath ?? 'assethub')} hooks save${client === 'codex' ? ' --client codex' : ''}`;
+// Symlinks are followed: a project path or a client folder that leads to the
+// home folder is the home folder. A path that does not exist yet is taken as is.
+const realOrResolved = async (path) => realpath(path).catch(() => resolve(path));
+/**
+ * A project install in the home folder would land in ~/.claude (or ~/.codex),
+ * which the client also reads for every project, so it is refused rather than
+ * silently global.
+ */
+export const hookScopeError = async (home, scope, client = 'claude', codexHome) => {
+    if (!scope.projectDir)
+        return undefined;
+    const homeDir = resolveHome(home);
+    const [project, projectConfig, realHome, userConfig] = await Promise.all([
+        realOrResolved(scope.projectDir),
+        realOrResolved(join(scope.projectDir, PROJECT_DIR[client])),
+        realOrResolved(homeDir),
+        realOrResolved(userConfigDir(client, { home, codexHome })),
+    ]);
+    return project === realHome || projectConfig === userConfig
+        ? 'Run this inside a project folder: in your home folder the hooks would apply to every project. Use --global if that is what you want.'
+        : undefined;
+};
+const run = promisify(execFile);
+const git = async (cwd, ...args) => run('git', ['-C', cwd, ...args]).then(({ stdout }) => stdout, () => undefined);
+/**
+ * Codex reads hooks only from .codex/hooks.json, which a repository may share.
+ * Ours stay personal: a tracked file is refused, an untracked one goes into
+ * the repository's info/exclude (never the shared .gitignore).
+ */
+const keepCodexHooksOutOfGit = async (path) => {
+    const dir = dirname(dirname(path));
+    const found = await git(dir, 'rev-parse', '--show-toplevel', '--git-path', 'info/exclude');
+    if (!found)
+        return undefined; // not a repository, or no git
+    const [top, excludePath] = found.trim().split('\n');
+    const file = relative(await realOrResolved(top), join(await realOrResolved(dir), PROJECT_DIR.codex, PROJECT_FILE.codex));
+    if (file.startsWith('..'))
+        return undefined;
+    if ((await git(top, 'ls-files', '--', file))?.trim())
+        return `${path} is tracked by git, so the hooks would be shared with everyone using the repository; left untouched.`;
+    const exclude = resolve(dir, excludePath);
+    // The file and the backups an install leaves next to it.
+    const pattern = `/${file.split(sep).join('/')}*`;
+    const current = await readFile(exclude, 'utf8').catch(() => '');
+    if (!current.split('\n').includes(pattern)) {
+        await mkdir(dirname(exclude), { recursive: true });
+        await appendFile(exclude, `${current && !current.endsWith('\n') ? '\n' : ''}${pattern}\n`);
+    }
+    return undefined;
+};
+/** `[projects."<path>"]` sections with `trust_level = "trusted"` in Codex's config.toml. */
+const codexTrustedProjects = async (codexDir) => {
+    const toml = await readFile(join(codexDir, 'config.toml'), 'utf8').catch(() => '');
+    const trusted = new Set();
+    const sections = toml.split(/^(?=\[)/m);
+    for (const section of sections) {
+        const header = /^\[projects\."((?:[^"\\]|\\.)*)"\]/.exec(section);
+        if (header && /^\s*trust_level\s*=\s*"trusted"/m.test(section))
+            trusted.add(header[1].replace(/\\(.)/g, '$1'));
+    }
+    return trusted;
+};
+/** What Codex still needs before the hooks run. */
+const codexNotes = async (codexDir, scope) => {
+    const review = ' Codex runs a new or changed hook only after you approve it: open /hooks in Codex.';
+    if (!scope.projectDir)
+        return review;
+    const dir = scope.projectDir;
+    const top = (await git(dir, 'rev-parse', '--show-toplevel'))?.trim();
+    const candidates = [resolve(dir), await realOrResolved(dir), ...(top ? [top, await realOrResolved(top)] : [])];
+    const trusted = await codexTrustedProjects(codexDir);
+    if (candidates.some(path => trusted.has(path)))
+        return review;
+    return (` Codex loads a project's hooks only when the project is trusted: add [projects."${resolve(dir)}"] ` +
+        `with trust_level = "trusted" to ${join(codexDir, 'config.toml')}, or trust the folder when Codex asks.` +
+        review);
+};
+const load = async (client, paths, scope) => {
+    const path = settingsPath(client, paths, scope);
+    let raw;
+    try {
+        raw = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT') {
+            return { path, exists: false, settings: {}, raw: '' };
+        }
+        return { path, error: `Could not read ${path}: ${error.message}` };
+    }
+    if (!raw.trim())
+        return { path, exists: true, settings: {}, raw };
+    try {
+        const parsed = JSON.parse(raw);
+        if (!isObject(parsed))
+            return { path, error: `${path} is not a JSON object; left untouched.` };
+        return { path, exists: true, settings: parsed, raw };
+    }
+    catch {
+        return { path, error: `${path} is not valid JSON; left untouched.` };
+    }
+};
+const escapeRe = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const pruneBackups = async (path) => {
+    const dir = dirname(path);
+    const backupRe = new RegExp(`^${escapeRe(basename(path))}\\.bak-\\d+$`);
+    const ours = (await readdir(dir)).filter(name => backupRe.test(name));
+    const byAge = ours.sort((a, b) => Number(b.split('-').pop()) - Number(a.split('-').pop()));
+    for (const name of byAge.slice(MAX_SETTINGS_BACKUPS))
+        await rm(join(dir, name), { force: true });
+};
+// Write through a temp file and rename, so a concurrent reader (Claude Code)
+// never sees a half-written settings.json.
+const backupAndWrite = async (loaded, next) => {
+    await mkdir(dirname(loaded.path), { recursive: true });
+    if (loaded.exists) {
+        await copyFile(loaded.path, `${loaded.path}.bak-${Date.now()}`);
+    }
+    const tmp = join(dirname(loaded.path), `.${basename(loaded.path)}.${process.pid}.tmp`);
+    await writeFile(tmp, `${JSON.stringify(next, null, 2)}\n`);
+    await rename(tmp, loaded.path);
+    await pruneBackups(loaded.path);
+};
+/**
+ * SessionStart (sweep and retry), Stop (every turn) and PreCompact only mark or
+ * spawn work, and run in the background so they never delay Claude Code.
+ * SessionEnd stays synchronous, because Claude Code is exiting and a
+ * background hook could be cut off. Codex hooks all run synchronously; the
+ * work is the same few local file writes.
+ */
+export const hookEntry = (event, command, client = 'claude') => event === 'SessionEnd'
+    ? { type: 'command', command, timeout: SESSION_END_TIMEOUT_SECONDS }
+    : client === 'codex'
+        ? { type: 'command', command, timeout: HOOK_TIMEOUT_SECONDS }
+        : { type: 'command', command, timeout: HOOK_TIMEOUT_SECONDS, async: true };
+export const installHooks = async (options) => {
+    const { client } = options;
+    const refused = await hookScopeError(options.home, options, client, options.codexHome);
+    if (refused)
+        return { installed: false, detail: refused };
+    const loaded = await load(client, options, options);
+    if ('error' in loaded)
+        return { installed: false, detail: loaded.error };
+    if (client === 'codex' && options.projectDir) {
+        const shared = await keepCodexHooksOutOfGit(loaded.path);
+        if (shared)
+            return { installed: false, detail: shared };
+    }
+    const notes = client === 'codex' ? await codexNotes(userConfigDir(client, options), options) : '';
+    const command = hookCommand(options.cliPath, client);
+    const settings = structuredClone(loaded.settings);
+    const hooks = isObject(settings.hooks) ? settings.hooks : {};
+    let changed = false;
+    for (const event of HOOK_EVENTS) {
+        const groups = Array.isArray(hooks[event]) ? hooks[event] : [];
+        const wanted = hookEntry(event, command, client);
+        let found = false;
+        for (const group of groups) {
+            if (!isObject(group) || !Array.isArray(group.hooks))
+                continue;
+            group.hooks = group.hooks.map((hook) => {
+                if (!isObject(hook) || !isOurCommand(hook.command))
+                    return hook;
+                found = true;
+                // Rewrite entries from older installs (no async, old timeout, old path).
+                if (JSON.stringify(hook) === JSON.stringify(wanted))
+                    return hook;
+                changed = true;
+                return { ...wanted };
+            });
+        }
+        if (!found) {
+            groups.push({ hooks: [{ ...wanted }] });
+            changed = true;
+        }
+        hooks[event] = groups;
+    }
+    settings.hooks = hooks;
+    if (!changed) {
+        return { installed: true, detail: `Hooks already installed in ${loaded.path}.${notes}` };
+    }
+    await backupAndWrite(loaded, settings);
+    return { installed: true, detail: `Installed ${HOOK_EVENTS.join(', ')} hooks in ${loaded.path}.${notes}` };
+};
+export const uninstallHooks = async (options) => {
+    const loaded = await load(options.client, options, options);
+    if ('error' in loaded)
+        return { removed: false, detail: loaded.error };
+    if (!loaded.exists || !isObject(loaded.settings.hooks)) {
+        return { removed: false, detail: `No assethub hooks found in ${loaded.path}.` };
+    }
+    const settings = structuredClone(loaded.settings);
+    const hooks = settings.hooks;
+    let changed = false;
+    for (const event of Object.keys(hooks)) {
+        const groups = hooks[event];
+        if (!Array.isArray(groups))
+            continue;
+        const keptGroups = [];
+        let eventChanged = false;
+        for (const group of groups) {
+            if (!isObject(group) || !Array.isArray(group.hooks)) {
+                keptGroups.push(group);
+                continue;
+            }
+            const kept = group.hooks.filter(hook => !(isObject(hook) && isOurCommand(hook.command)));
+            if (kept.length === group.hooks.length) {
+                keptGroups.push(group);
+                continue;
+            }
+            changed = true;
+            eventChanged = true;
+            if (kept.length > 0)
+                keptGroups.push({ ...group, hooks: kept });
+        }
+        if (keptGroups.length > 0)
+            hooks[event] = keptGroups;
+        else if (eventChanged)
+            delete hooks[event];
+    }
+    if (!changed)
+        return { removed: false, detail: `No assethub hooks found in ${loaded.path}.` };
+    if (Object.keys(hooks).length === 0)
+        delete settings.hooks;
+    await backupAndWrite(loaded, settings);
+    return { removed: true, detail: `Removed assethub hooks from ${loaded.path}` };
+};

package/dist/hooks/paths.d.ts

@@ -0,0 +1,31 @@
+import type { SessionMeta } from './types.js';
+export declare const resolveHome: (home?: string) => string;
+export declare const sessionsRoot: (home?: string) => string;
+export declare const errorsLogPath: (home?: string) => string;
+export declare const PRIVATE_DIR_MODE = 448;
+export declare const PRIVATE_FILE_MODE = 384;
+/** mkdir -p with private modes; also tightens a directory an older version made. */
+export declare const ensurePrivateDir: (dir: string) => Promise<void>;
+/** Write via a temp file and rename, so a reader never sees a half-written file. */
+export declare const writePrivateFileAtomic: (target: string, content: string) => Promise<void>;
+export declare const readMeta: (sessionDir: string) => Promise<SessionMeta | null>;
+export declare const writeMeta: (sessionDir: string, meta: SessionMeta) => Promise<void>;
+/**
+ * A lock is a directory, because creating one is atomic. A lock older than
+ * `staleMs` belongs to a process that died, and is taken over. Returns the
+ * release function, or null when the lock is still held after `waitMs`.
+ */
+export declare const acquireLock: (path: string, { waitMs, staleMs }: {
+    waitMs: number;
+    staleMs: number;
+}) => Promise<(() => Promise<void>) | null>;
+/**
+ * Read, update and write meta under a per-session lock, so a hook and an
+ * upload running at the same time cannot overwrite each other's fields.
+ * If the lock cannot be had in time the write still happens: a hook must
+ * never hang on a stuck lock.
+ */
+export declare const updateMeta: (sessionDir: string, fallback: SessionMeta, update: (latest: SessionMeta) => SessionMeta) => Promise<SessionMeta>;
+export declare const listSessionDirs: (home?: string) => Promise<string[]>;
+export declare const logError: (home: string | undefined, error: unknown) => Promise<void>;
+//# sourceMappingURL=paths.d.ts.map

package/dist/hooks/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/hooks/paths.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,YAAY,CAAA;AAE3C,eAAO,MAAM,WAAW,GAAI,OAAO,MAAM,KAAG,MAA2B,CAAA;AACvE,eAAO,MAAM,YAAY,GAAI,OAAO,MAAM,KAAG,MACK,CAAA;AAClD,eAAO,MAAM,aAAa,GAAI,OAAO,MAAM,KAAG,MAAgD,CAAA;AAI9F,eAAO,MAAM,gBAAgB,MAAQ,CAAA;AACrC,eAAO,MAAM,iBAAiB,MAAQ,CAAA;AAEtC,oFAAoF;AACpF,eAAO,MAAM,gBAAgB,GAAU,KAAK,MAAM,KAAG,OAAO,CAAC,IAAI,CAGhE,CAAA;AAED,oFAAoF;AACpF,eAAO,MAAM,sBAAsB,GAAU,QAAQ,MAAM,EAAE,SAAS,MAAM,KAAG,OAAO,CAAC,IAAI,CAI1F,CAAA;AAED,eAAO,MAAM,QAAQ,GAAU,YAAY,MAAM,KAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAM7E,CAAA;AAED,eAAO,MAAM,SAAS,GAAU,YAAY,MAAM,EAAE,MAAM,WAAW,KAAG,OAAO,CAAC,IAAI,CAEnF,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW,GACtB,MAAM,MAAM,EACZ,qBAAmB;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,KACnD,OAAO,CAAC,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAiBtC,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GACrB,YAAY,MAAM,EAClB,UAAU,WAAW,EACrB,QAAQ,CAAC,MAAM,EAAE,WAAW,KAAK,WAAW,KAC3C,OAAO,CAAC,WAAW,CASrB,CAAA;AAED,eAAO,MAAM,eAAe,GAAU,OAAO,MAAM,KAAG,OAAO,CAAC,MAAM,EAAE,CAWrE,CAAA;AAED,eAAO,MAAM,QAAQ,GAAU,MAAM,MAAM,GAAG,SAAS,EAAE,OAAO,OAAO,KAAG,OAAO,CAAC,IAAI,CAUrF,CAAA"}

package/dist/hooks/paths.js

@@ -0,0 +1,101 @@
+import { appendFile, chmod, mkdir, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { redactText } from './redact.js';
+export const resolveHome = (home) => home ?? homedir();
+export const sessionsRoot = (home) => join(resolveHome(home), '.assethub', 'sessions');
+export const errorsLogPath = (home) => join(sessionsRoot(home), 'errors.log');
+// Sessions hold the artist's conversation and images, and redaction is best
+// effort, so everything under ~/.assethub/sessions is private to the user.
+export const PRIVATE_DIR_MODE = 0o700;
+export const PRIVATE_FILE_MODE = 0o600;
+/** mkdir -p with private modes; also tightens a directory an older version made. */
+export const ensurePrivateDir = async (dir) => {
+    await mkdir(dir, { recursive: true, mode: PRIVATE_DIR_MODE });
+    await chmod(dir, PRIVATE_DIR_MODE);
+};
+/** Write via a temp file and rename, so a reader never sees a half-written file. */
+export const writePrivateFileAtomic = async (target, content) => {
+    const tmp = `${target}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+    await writeFile(tmp, content, { mode: PRIVATE_FILE_MODE });
+    await rename(tmp, target);
+};
+export const readMeta = async (sessionDir) => {
+    try {
+        return JSON.parse(await readFile(join(sessionDir, 'meta.json'), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+};
+export const writeMeta = async (sessionDir, meta) => {
+    await writePrivateFileAtomic(join(sessionDir, 'meta.json'), `${JSON.stringify(meta, null, 2)}\n`);
+};
+/**
+ * A lock is a directory, because creating one is atomic. A lock older than
+ * `staleMs` belongs to a process that died, and is taken over. Returns the
+ * release function, or null when the lock is still held after `waitMs`.
+ */
+export const acquireLock = async (path, { waitMs, staleMs }) => {
+    const deadline = Date.now() + waitMs;
+    for (;;) {
+        try {
+            await mkdir(path, { mode: PRIVATE_DIR_MODE });
+            return () => rm(path, { recursive: true, force: true });
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            const age = await stat(path).then(info => Date.now() - info.mtimeMs, () => 0);
+            if (age > staleMs) {
+                await rm(path, { recursive: true, force: true });
+                continue;
+            }
+            if (Date.now() >= deadline)
+                return null;
+            await new Promise(resolve => setTimeout(resolve, 20));
+        }
+    }
+};
+/**
+ * Read, update and write meta under a per-session lock, so a hook and an
+ * upload running at the same time cannot overwrite each other's fields.
+ * If the lock cannot be had in time the write still happens: a hook must
+ * never hang on a stuck lock.
+ */
+export const updateMeta = async (sessionDir, fallback, update) => {
+    const release = await acquireLock(join(sessionDir, '.meta.lock'), { waitMs: 5_000, staleMs: 30_000 });
+    try {
+        const next = update((await readMeta(sessionDir)) ?? fallback);
+        await writeMeta(sessionDir, next);
+        return next;
+    }
+    finally {
+        await release?.();
+    }
+};
+export const listSessionDirs = async (home) => {
+    const root = sessionsRoot(home);
+    try {
+        const entries = await readdir(root, { withFileTypes: true });
+        return entries
+            .filter(entry => entry.isDirectory())
+            .map(entry => join(root, entry.name))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+};
+export const logError = async (home, error) => {
+    try {
+        await ensurePrivateDir(sessionsRoot(home));
+        const message = error instanceof Error ? (error.stack ?? error.message) : String(error);
+        await appendFile(errorsLogPath(home), `${new Date().toISOString()} ${redactText(message)}\n`, {
+            mode: PRIVATE_FILE_MODE,
+        });
+    }
+    catch {
+        // The hook must never fail the agent, even when logging fails.
+    }
+};

package/dist/hooks/redact.d.ts

@@ -0,0 +1,5 @@
+export declare const REDACTED = "[REDACTED]";
+export declare const redactText: (text: string) => string;
+/** Redact a whole JSONL document, one line at a time. */
+export declare const redactJsonl: (raw: string) => string;
+//# sourceMappingURL=redact.d.ts.map

package/dist/hooks/redact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.d.ts","sourceRoot":"","sources":["../../src/hooks/redact.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,QAAQ,eAAe,CAAA;AAuEpC,eAAO,MAAM,UAAU,GAAI,MAAM,MAAM,KAAG,MAUzC,CAAA;AAED,yDAAyD;AACzD,eAAO,MAAM,WAAW,GAAI,KAAK,MAAM,KAAG,MAAoD,CAAA"}

package/dist/hooks/redact.js

@@ -0,0 +1,67 @@
+// Secret redaction for saved agent transcripts.
+//
+// Applied to raw JSONL text line by line. Every replacement is the literal
+// `[REDACTED]`, and every matcher stops at quotes, backslashes and whitespace,
+// so redacting a JSON line never breaks its JSON.
+export const REDACTED = '[REDACTED]';
+// Token bodies never contain quotes/backslashes/whitespace, so a JSON string
+// boundary always ends a match.
+const TOKEN = String.raw `[A-Za-z0-9._~+/=-]`;
+const WHOLE_MATCH_PATTERNS = [
+    // AssetHub keys: ah_live_..., ah_test_..., ah_pat_...
+    new RegExp(String.raw `\bah_(?:live|test|pat)_[A-Za-z0-9_-]{6,}`, 'g'),
+    // Anthropic before the generic sk- rule.
+    new RegExp(String.raw `\bsk-ant-[A-Za-z0-9_-]{8,}`, 'g'),
+    // OpenAI (sk-..., sk-proj-...).
+    new RegExp(String.raw `\bsk-[A-Za-z0-9_-]{16,}`, 'g'),
+    // Stripe secret/restricted/publishable keys and webhook secrets (sk_live_, rk_test_, whsec_...).
+    new RegExp(String.raw `\b(?:sk|rk|pk)_(?:live|test)_[A-Za-z0-9]{8,}`, 'g'),
+    new RegExp(String.raw `\bwhsec_[A-Za-z0-9]{16,}`, 'g'),
+    // Supabase secret keys.
+    new RegExp(String.raw `\bsb_secret_[A-Za-z0-9_-]{16,}`, 'g'),
+    // AssetHub legacy / ElevenLabs style sk_<hex or alnum>.
+    new RegExp(String.raw `\bsk_[A-Za-z0-9]{16,}`, 'g'),
+    // JWTs, including Supabase anon/service-role keys.
+    new RegExp(String.raw `\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}`, 'g'),
+    // Slack tokens.
+    new RegExp(String.raw `\bxox[abposr]-[A-Za-z0-9-]{10,}`, 'g'),
+    // Google API keys.
+    new RegExp(String.raw `\bAIza[0-9A-Za-z_-]{30,}`, 'g'),
+    // AWS access key ids.
+    new RegExp(String.raw `\b(?:AKIA|ASIA)[0-9A-Z]{16}\b`, 'g'),
+    // GitHub tokens.
+    new RegExp(String.raw `\b(?:ghp|gho|ghs|ghu|github_pat)_[A-Za-z0-9_]{20,}`, 'g'),
+    // Bearer tokens, anywhere.
+    new RegExp(String.raw `\bBearer\s+${TOKEN}{8,}`, 'gi'),
+];
+// PEM private keys. In JSONL the newlines are escaped (`\n`), so the block is one line.
+const PRIVATE_KEY_PATTERN = /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g;
+// Credentials inside a URL: scheme://user:password@host keeps the user and host.
+const URL_CREDENTIALS_PATTERN = /\b([a-z][a-z0-9+.-]*:\/\/[^\s:/@"'\\]+:)[^\s@/"'\\]+@/gi;
+// `Authorization: <scheme> <value>` / `"Authorization": "..."` / xi-api-key.
+const HEADER_PATTERN = new RegExp(String.raw `((?:authorization|x-api-key|xi-api-key)\\?["']?\s*[:=]\s*\\?["']?)(?:(?:Bearer|Basic|Token)\s+)?[^\s"'\\,;]+`, 'gi');
+// NAME=value where NAME looks like a secret variable (ASSETHUB_API_KEY, AWS_SECRET_ACCESS_KEY, ...).
+const ASSIGNMENT_PATTERN = new RegExp(String.raw `\b([A-Za-z0-9_]*(?:API_KEY|APIKEY|SECRET|_KEY|TOKEN|PASSWORD|PASSWD|CREDENTIALS?|DSN|DATABASE_URL)[A-Za-z0-9_]*)(\s*=\s*)(?:\\?["'])?[^\s"'\\]+`, 'gi');
+// A JSON key that names a secret: password, secret, api_key/apiKey, token,
+// clientSecret, service_role_key, AWS_SECRET_ACCESS_KEY, ... ("input_tokens" does not match).
+const SECRET_KEY = String.raw `[A-Za-z0-9_-]*(?:api[_-]?key|secret|token|password|passwd|[_-]key|credentials?)`;
+// "key": "value" at the top level of a JSON line. The value may contain
+// escapes; only the string contents are replaced, so the JSON stays valid.
+const JSON_FIELD_PATTERN = new RegExp(String.raw `("${SECRET_KEY}"\s*:\s*")((?:[^"\\]|\\.)*)(")`, 'gi');
+// The same field inside a JSON string that itself holds JSON (tool inputs are
+// often serialised twice): \"key\": \"value\".
+const ESCAPED_JSON_FIELD_PATTERN = new RegExp(String.raw `(\\"${SECRET_KEY}\\"\s*:\s*\\")((?:[^"\\]|\\\\|\\[^"\\])*)(\\")`, 'gi');
+export const redactText = (text) => {
+    let out = text;
+    out = out.replace(PRIVATE_KEY_PATTERN, REDACTED);
+    out = out.replace(URL_CREDENTIALS_PATTERN, (_m, prefix) => `${prefix}${REDACTED}@`);
+    out = out.replace(ESCAPED_JSON_FIELD_PATTERN, (_m, open, _v, close) => `${open}${REDACTED}${close}`);
+    out = out.replace(JSON_FIELD_PATTERN, (_m, open, _v, close) => `${open}${REDACTED}${close}`);
+    out = out.replace(HEADER_PATTERN, (_m, prefix) => `${prefix}${REDACTED}`);
+    out = out.replace(ASSIGNMENT_PATTERN, (_m, name, eq) => `${name}${eq}${REDACTED}`);
+    for (const pattern of WHOLE_MATCH_PATTERNS)
+        out = out.replace(pattern, REDACTED);
+    return out;
+};
+/** Redact a whole JSONL document, one line at a time. */
+export const redactJsonl = (raw) => raw.split('\n').map(redactText).join('\n');

package/dist/hooks/save.d.ts

@@ -0,0 +1,62 @@
+import type { HookClient, HookInput, SessionMeta } from './types.js';
+import type { UploadOptions } from './upload.js';
+export declare const MAX_IMAGES = 50;
+export declare const MAX_IMAGE_BYTES: number;
+export declare const DEFAULT_RETENTION_DAYS = 30;
+export type SaveSessionOptions = {
+    /** Raw hook JSON as read from stdin. */
+    stdin?: string;
+    /** Or the already-parsed fields. */
+    input?: HookInput;
+    /** The agent the hook runs in; its hook command says so (`--client codex`). */
+    client?: HookClient;
+    home?: string;
+    now?: () => Date;
+    env?: NodeJS.ProcessEnv;
+    upload?: Pick<UploadOptions, 'profile'>;
+    /**
+     * Starts `assethub hooks upload --session <dir> --auto` outside the hook.
+     * SessionEnd runs while Claude Code exits under a short budget, so the
+     * network upload must not run inside it.
+     */
+    startUpload?: (sessionDir: string, profile?: string) => void;
+    /** Starts the background retry of pending sessions on SessionStart. */
+    startSweep?: (profile?: string) => void;
+};
+export type SaveSessionResult = {
+    sessionDir: string;
+    uploadStarted?: boolean;
+    pruned?: number;
+    abandoned?: number;
+    event?: string;
+    skipped?: 'opt-out' | 'no-input';
+};
+/** SessionEnd: upload this session, then retry up to SWEEP_LIMIT older pending ones. */
+export declare const spawnDetachedUpload: (sessionDir: string, profile?: string) => void;
+/** SessionStart: retry up to SWEEP_LIMIT pending sessions. */
+export declare const spawnDetachedSweep: (profile?: string) => void;
+export declare const retentionDays: (env: NodeJS.ProcessEnv) => number | null;
+/** Delete saved sessions last written more than `days` ago, whatever their upload state. */
+export declare const pruneSessions: (root: string, now: Date, days: number, keep: string) => Promise<number>;
+/** A session with no hook for this long, and never ended, was abandoned (crash, killed terminal). */
+export declare const ABANDONED_AFTER_MS: number;
+/** Sessions retried in the background per SessionStart / SessionEnd. */
+export declare const SWEEP_LIMIT = 3;
+/**
+ * Copy + redact the transcript Claude Code keeps at `meta.transcriptPath`, and
+ * collect its images. Runs once per SessionEnd and before an upload, never per
+ * turn. A copy shorter than the saved one is an older read (a transcript only
+ * grows) and never replaces it.
+ */
+export declare const materializeSession: (sessionDir: string, options?: {
+    env?: NodeJS.ProcessEnv;
+    transcriptPath?: string;
+}) => Promise<SessionMeta | null>;
+/**
+ * On SessionStart: a session that never reached SessionEnd and has been quiet
+ * for ABANDONED_AFTER_MS is marked for upload, so a crash or a killed terminal
+ * does not lose it.
+ */
+export declare const markAbandonedSessions: (root: string, now: Date, currentSessionId?: string) => Promise<number>;
+export declare const saveSession: (options?: SaveSessionOptions) => Promise<SaveSessionResult>;
+//# sourceMappingURL=save.d.ts.map

package/dist/hooks/save.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"save.d.ts","sourceRoot":"","sources":["../../src/hooks/save.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAC,UAAU,EAAE,SAAS,EAAgB,WAAW,EAAC,MAAM,YAAY,CAAA;AAChF,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,aAAa,CAAA;AAE9C,eAAO,MAAM,UAAU,KAAK,CAAA;AAC5B,eAAO,MAAM,eAAe,QAAmB,CAAA;AAC/C,eAAO,MAAM,sBAAsB,KAAK,CAAA;AASxC,MAAM,MAAM,kBAAkB,GAAG;IAC/B,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,oCAAoC;IACpC,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,UAAU,CAAA;IACnB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,GAAG,CAAC,EAAE,MAAM,IAAI,CAAA;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;IACvB,MAAM,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE,SAAS,CAAC,CAAA;IACvC;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;IAC5D,uEAAuE;IACvE,UAAU,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;CACxC,CAAA;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B,UAAU,EAAE,MAAM,CAAA;IAClB,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,SAAS,GAAG,UAAU,CAAA;CACjC,CAAA;AAYD,wFAAwF;AACxF,eAAO,MAAM,mBAAmB,GAAI,YAAY,MAAM,EAAE,UAAU,MAAM,KAAG,IACgC,CAAA;AAE3G,8DAA8D;AAC9D,eAAO,MAAM,kBAAkB,GAAI,UAAU,MAAM,KAAG,IAC+B,CAAA;AAErF,eAAO,MAAM,aAAa,GAAI,KAAK,MAAM,CAAC,UAAU,KAAG,MAAM,GAAG,IAM/D,CAAA;AAED,4FAA4F;AAC5F,eAAO,MAAM,aAAa,GACxB,MAAM,MAAM,EACZ,KAAK,IAAI,EACT,MAAM,MAAM,EACZ,MAAM,MAAM,KACX,OAAO,CAAC,MAAM,CAwBhB,CAAA;AAgFD,qGAAqG;AACrG,eAAO,MAAM,kBAAkB,QAAqB,CAAA;AACpD,wEAAwE;AACxE,eAAO,MAAM,WAAW,IAAI,CAAA;AAK5B;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAC7B,YAAY,MAAM,EAClB,UAAS;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAM,KAC/D,OAAO,CAAC,WAAW,GAAG,IAAI,CA6C5B,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,GAChC,MAAM,MAAM,EACZ,KAAK,IAAI,EACT,mBAAmB,MAAM,KACxB,OAAO,CAAC,MAAM,CAmBhB,CAAA;AAED,eAAO,MAAM,WAAW,GAAU,UAAS,kBAAuB,KAAG,OAAO,CAAC,iBAAiB,CAkF7F,CAAA"}