clementine-agent 1.18.101 → 1.18.102

package/dist/agent/path-b-installer.d.ts

@@ -0,0 +1,75 @@
+/**
+ * PRD §6 Phase 4d / 1.18.102 — Path B installer.
+ *
+ * Drops a `.claude/settings.local.json` into a project's cwd that registers
+ * the SDK's command-type hooks to POST events at the dashboard's
+ * /api/hooks/event endpoint. The installer is opt-in per task — the user
+ * clicks "Enable hooks" on the task card after they've decided they want
+ * real per-tool latency.
+ *
+ * Why settings.local.json (not settings.json):
+ * - The SDK's `setting_sources=['project','local']` reads both. We use
+ *   the 'local' source so we never touch the user's hand-written
+ *   settings.json. settings.local.json is conventionally gitignored —
+ *   our hooks are per-machine config (they reference a localhost dashboard
+ *   token), not source-controllable.
+ * - A future "disable hooks" path can rm the file without affecting any
+ *   hand-written project settings.
+ *
+ * Auth: the hook commands include the dashboard token in the X-Dashboard-Token
+ * header. The token is baked into the curl command at install time. If the
+ * dashboard restarts and rotates its token, the user has to re-enable hooks
+ * (a small UX cost we accept; the alternative is having hooks read the
+ * token from disk at fire-time which adds a syscall to every tool call).
+ */
+export interface SettingsTemplateOptions {
+    /** Dashboard token to include in the X-Dashboard-Token header. Required. */
+    token: string;
+    /** Localhost port the dashboard is listening on. Defaults to 3030. */
+    port?: number;
+    /** Mark the file with a comment so users know who wrote it. */
+    installerVersion?: string;
+}
+/** Build the JSON content of .claude/settings.local.json. The shape matches
+ *  the SDK's hook config schema: a top-level `hooks` map keyed by event name,
+ *  each value an array of `{ hooks: [{ type, command }] }` matchers. The
+ *  empty matcher means "always fire". */
+export declare function buildSettingsTemplate(opts: SettingsTemplateOptions): Record<string, unknown>;
+export interface InstallResult {
+    ok: boolean;
+    filePath: string;
+    /** Whether the file existed before this call. */
+    wasExisting: boolean;
+    /** Whether we replaced an existing installer-managed file vs writing fresh. */
+    wasUpdate: boolean;
+    /** Set when ok=false. */
+    error?: string;
+}
+/** Write/update .claude/settings.local.json in `workDir`. If the file
+ *  already exists and is NOT installer-managed (no _clementine key), we
+ *  bail out and refuse to overwrite to avoid clobbering user content. */
+export declare function installPathBHooks(workDir: string, opts: SettingsTemplateOptions): InstallResult;
+export interface HooksStatus {
+    /** Whether a settings.local.json exists in the workDir. */
+    installed: boolean;
+    /** Whether the file is one we wrote (has _clementine sentinel). */
+    managedByUs: boolean;
+    /** Resolved path we checked (helpful for diagnostic toasts). */
+    filePath: string;
+    /** When we installed it (ISO). null if not managed by us. */
+    installedAt?: string;
+    /** Installer version that wrote it. null if not managed by us. */
+    installerVersion?: string;
+    /** True if the file exists but came from somewhere else (user). */
+    conflictsWithUser: boolean;
+}
+/** Inspect a workDir's hook installation state. Used by the dashboard's
+ *  task card to decide whether to render "Enable hooks" or "Hooks: on". */
+export declare function getHooksStatus(workDir: string): HooksStatus;
+/** Removes our installer-managed settings.local.json. Refuses if the file
+ *  isn't ours (so a misclick doesn't delete user config). */
+export declare function uninstallPathBHooks(workDir: string): {
+    ok: boolean;
+    error?: string;
+};
+//# sourceMappingURL=path-b-installer.d.ts.map

package/dist/agent/path-b-installer.js

@@ -0,0 +1,183 @@
+/**
+ * PRD §6 Phase 4d / 1.18.102 — Path B installer.
+ *
+ * Drops a `.claude/settings.local.json` into a project's cwd that registers
+ * the SDK's command-type hooks to POST events at the dashboard's
+ * /api/hooks/event endpoint. The installer is opt-in per task — the user
+ * clicks "Enable hooks" on the task card after they've decided they want
+ * real per-tool latency.
+ *
+ * Why settings.local.json (not settings.json):
+ * - The SDK's `setting_sources=['project','local']` reads both. We use
+ *   the 'local' source so we never touch the user's hand-written
+ *   settings.json. settings.local.json is conventionally gitignored —
+ *   our hooks are per-machine config (they reference a localhost dashboard
+ *   token), not source-controllable.
+ * - A future "disable hooks" path can rm the file without affecting any
+ *   hand-written project settings.
+ *
+ * Auth: the hook commands include the dashboard token in the X-Dashboard-Token
+ * header. The token is baked into the curl command at install time. If the
+ * dashboard restarts and rotates its token, the user has to re-enable hooks
+ * (a small UX cost we accept; the alternative is having hooks read the
+ * token from disk at fire-time which adds a syscall to every tool call).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+/** Hooks we install. Picked for the latency dashboard's needs:
+ *  PreToolUse + PostToolUse give us tool durations (PostToolUse carries
+ *  duration_ms). SubagentStart/Stop close the gap path C handles via
+ *  transcript backfill. Stop / Notification add nice-to-have signal but
+ *  are minimal cost. */
+const HOOK_EVENTS = [
+    'PreToolUse',
+    'PostToolUse',
+    'SubagentStart',
+    'SubagentStop',
+    'Stop',
+    'Notification',
+    'UserPromptSubmit',
+    'SessionStart',
+    'PreCompact',
+];
+/** Build the JSON content of .claude/settings.local.json. The shape matches
+ *  the SDK's hook config schema: a top-level `hooks` map keyed by event name,
+ *  each value an array of `{ hooks: [{ type, command }] }` matchers. The
+ *  empty matcher means "always fire". */
+export function buildSettingsTemplate(opts) {
+    const port = opts.port ?? 3030;
+    // Use POSIX `curl` — preinstalled on macOS and most Linuxes; Windows users
+    // running WSL or Git Bash also have it. We add `--max-time 2` so a
+    // wedged dashboard can't stall the SDK's tool execution.
+    const curlCmd = `curl -s --max-time 2 -X POST `
+        + `-H "X-Dashboard-Token: ${opts.token}" `
+        + `-H "Content-Type: application/json" `
+        + `--data-binary @- `
+        + `http://127.0.0.1:${port}/api/hooks/event`;
+    const hooks = {};
+    for (const eventName of HOOK_EVENTS) {
+        hooks[eventName] = [
+            {
+                // Empty matcher fires for every event; the dashboard endpoint
+                // can later expose a UI for restricting to specific tool names.
+                hooks: [{ type: 'command', command: curlCmd }],
+            },
+        ];
+    }
+    return {
+        // Sentinel field so we can detect (and update) installer-managed
+        // settings without touching anything else in the file.
+        _clementine: {
+            managedBy: 'clementine-agent path-b-installer',
+            installedAt: new Date().toISOString(),
+            installerVersion: opts.installerVersion ?? '1.18.102',
+            port,
+        },
+        hooks,
+    };
+}
+/** Write/update .claude/settings.local.json in `workDir`. If the file
+ *  already exists and is NOT installer-managed (no _clementine key), we
+ *  bail out and refuse to overwrite to avoid clobbering user content. */
+export function installPathBHooks(workDir, opts) {
+    if (!workDir)
+        return { ok: false, filePath: '', wasExisting: false, wasUpdate: false, error: 'workDir required' };
+    if (!opts.token)
+        return { ok: false, filePath: '', wasExisting: false, wasUpdate: false, error: 'token required' };
+    const dir = path.join(workDir, '.claude');
+    const file = path.join(dir, 'settings.local.json');
+    let wasExisting = false;
+    let wasUpdate = false;
+    if (existsSync(file)) {
+        wasExisting = true;
+        try {
+            const raw = readFileSync(file, 'utf-8');
+            const parsed = JSON.parse(raw);
+            // Only proceed if the file was previously installed by us.
+            if (!parsed._clementine || typeof parsed._clementine !== 'object') {
+                return {
+                    ok: false,
+                    filePath: file,
+                    wasExisting: true,
+                    wasUpdate: false,
+                    error: 'settings.local.json exists but was not created by clementine — refusing to overwrite. Move or delete the file and retry.',
+                };
+            }
+            wasUpdate = true;
+        }
+        catch (err) {
+            return {
+                ok: false,
+                filePath: file,
+                wasExisting: true,
+                wasUpdate: false,
+                error: 'could not parse existing settings.local.json: ' + String(err),
+            };
+        }
+    }
+    try {
+        mkdirSync(dir, { recursive: true });
+        const content = buildSettingsTemplate(opts);
+        writeFileSync(file, JSON.stringify(content, null, 2) + '\n');
+        return { ok: true, filePath: file, wasExisting, wasUpdate };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            filePath: file,
+            wasExisting,
+            wasUpdate,
+            error: 'failed to write settings.local.json: ' + String(err),
+        };
+    }
+}
+/** Inspect a workDir's hook installation state. Used by the dashboard's
+ *  task card to decide whether to render "Enable hooks" or "Hooks: on". */
+export function getHooksStatus(workDir) {
+    const filePath = path.join(workDir, '.claude', 'settings.local.json');
+    if (!existsSync(filePath)) {
+        return { installed: false, managedByUs: false, filePath, conflictsWithUser: false };
+    }
+    try {
+        const raw = readFileSync(filePath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        const sentinel = parsed._clementine;
+        if (sentinel && typeof sentinel === 'object') {
+            return {
+                installed: true,
+                managedByUs: true,
+                filePath,
+                installedAt: sentinel.installedAt,
+                installerVersion: sentinel.installerVersion,
+                conflictsWithUser: false,
+            };
+        }
+        return { installed: true, managedByUs: false, filePath, conflictsWithUser: true };
+    }
+    catch {
+        // Couldn't parse — treat as a user file we shouldn't touch.
+        return { installed: true, managedByUs: false, filePath, conflictsWithUser: true };
+    }
+}
+/** Removes our installer-managed settings.local.json. Refuses if the file
+ *  isn't ours (so a misclick doesn't delete user config). */
+export function uninstallPathBHooks(workDir) {
+    const filePath = path.join(workDir, '.claude', 'settings.local.json');
+    if (!existsSync(filePath))
+        return { ok: true };
+    const status = getHooksStatus(workDir);
+    if (!status.managedByUs) {
+        return { ok: false, error: 'settings.local.json is not managed by clementine — refusing to delete' };
+    }
+    try {
+        // Use unlinkSync via dynamic import to keep the static fs imports list
+        // tight; this path is rarely invoked.
+        const fs = require('node:fs');
+        fs.unlinkSync(filePath);
+        return { ok: true };
+    }
+    catch (err) {
+        return { ok: false, error: 'failed to remove: ' + String(err) };
+    }
+}
+//# sourceMappingURL=path-b-installer.js.map

package/dist/agent/run-agent.js

@@ -253,7 +253,12 @@ export async function runAgent(prompt, opts) {
         systemPrompt: profileAppend
             ? { type: 'preset', preset: 'claude_code', append: profileAppend }
             : { type: 'preset', preset: 'claude_code' },
-        settingSources: opts.settingSources ?? ['project'],
+        // PRD §6 Phase 4d / 1.18.102: read both project and local sources by
+        // default. The path B installer writes to .claude/settings.local.json
+        // (which the SDK reads under the 'local' source) so we never clobber
+        // the user's hand-written .claude/settings.json. Callers can still
+        // override settingSources via opts.
+        settingSources: opts.settingSources ?? ['project', 'local'],
         agents,
         // SDK's McpServerConfig is a union; cast at the boundary since
         // callers can mix stdio + http + sse server shapes.

package/dist/cli/dashboard.js

@@ -4594,6 +4594,101 @@ export async function cmdDashboard(opts) {
     // path on runAgentCron honors the signal and unwinds cleanly. The
     // CronScheduler's own catch path then writes the closing CronRunEntry
     // with status='error' + an "AbortError" message.
+    // ── PRD §6 Phase 4d / 1.18.102: Path B opt-in install ──────────
+    // Three endpoints for managing the .claude/settings.local.json hook
+    // wiring on a per-task basis. Hooks are opt-in (the user picks which
+    // tasks should pay the small per-tool overhead of curl-on-every-event)
+    // and the installer refuses to overwrite a settings.local.json that
+    // wasn't created by us.
+    app.get('/api/cron/:job/hooks-status', async (req, res) => {
+        try {
+            const jobName = req.params.job;
+            if (!jobName) {
+                res.status(400).json({ ok: false, error: 'job required' });
+                return;
+            }
+            // Find the job's workDir from the cron definitions.
+            const { parseCronJobs } = await import('../gateway/cron-scheduler.js');
+            const jobs = parseCronJobs();
+            const job = jobs.find((j) => String(j.name).toLowerCase() === jobName.toLowerCase());
+            if (!job) {
+                res.status(404).json({ ok: false, error: `job "${jobName}" not found` });
+                return;
+            }
+            if (!job.workDir) {
+                res.json({ ok: true, status: { installed: false, managedByUs: false, filePath: '', conflictsWithUser: false }, message: 'Task has no workDir set — hooks need a project directory.' });
+                return;
+            }
+            const { getHooksStatus } = await import('../agent/path-b-installer.js');
+            const status = getHooksStatus(job.workDir);
+            res.json({ ok: true, workDir: job.workDir, status });
+        }
+        catch (err) {
+            res.status(500).json({ ok: false, error: String(err) });
+        }
+    });
+    app.post('/api/cron/:job/enable-hooks', async (req, res) => {
+        try {
+            const jobName = req.params.job;
+            if (!jobName) {
+                res.status(400).json({ ok: false, error: 'job required' });
+                return;
+            }
+            const { parseCronJobs } = await import('../gateway/cron-scheduler.js');
+            const jobs = parseCronJobs();
+            const job = jobs.find((j) => String(j.name).toLowerCase() === jobName.toLowerCase());
+            if (!job) {
+                res.status(404).json({ ok: false, error: `job "${jobName}" not found` });
+                return;
+            }
+            if (!job.workDir) {
+                res.status(400).json({ ok: false, error: 'task has no workDir set' });
+                return;
+            }
+            const port = Number(process.env.PORT) || 3030;
+            const { installPathBHooks } = await import('../agent/path-b-installer.js');
+            const result = installPathBHooks(job.workDir, { token: dashboardToken, port });
+            if (!result.ok) {
+                res.status(409).json({ ...result, ok: false });
+                return;
+            }
+            const { ok: _ignore, ...rest } = result;
+            res.json({ ...rest, ok: true, message: result.wasUpdate ? 'Hooks updated.' : 'Hooks installed. The next run of this task will emit per-tool latency to the dashboard.' });
+        }
+        catch (err) {
+            res.status(500).json({ ok: false, error: String(err) });
+        }
+    });
+    app.post('/api/cron/:job/disable-hooks', async (req, res) => {
+        try {
+            const jobName = req.params.job;
+            if (!jobName) {
+                res.status(400).json({ ok: false, error: 'job required' });
+                return;
+            }
+            const { parseCronJobs } = await import('../gateway/cron-scheduler.js');
+            const jobs = parseCronJobs();
+            const job = jobs.find((j) => String(j.name).toLowerCase() === jobName.toLowerCase());
+            if (!job) {
+                res.status(404).json({ ok: false, error: `job "${jobName}" not found` });
+                return;
+            }
+            if (!job.workDir) {
+                res.status(400).json({ ok: false, error: 'task has no workDir set' });
+                return;
+            }
+            const { uninstallPathBHooks } = await import('../agent/path-b-installer.js');
+            const result = uninstallPathBHooks(job.workDir);
+            if (!result.ok) {
+                res.status(409).json({ ok: false, error: result.error });
+                return;
+            }
+            res.json({ ok: true, message: 'Hooks disabled. The next run of this task will use only the in-process tap (path A).' });
+        }
+        catch (err) {
+            res.status(500).json({ ok: false, error: String(err) });
+        }
+    });
     app.post('/api/cron/run/:job/cancel', async (req, res) => {
         try {
             const jobName = req.params.job;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clementine-agent",
-  "version": "1.18.101",
+  "version": "1.18.102",
   "description": "Clementine — Personal AI Assistant (TypeScript)",
   "type": "module",
   "main": "dist/index.js",