@achieveai/hitl-mcp-server 2.9.6 → 2.11.2

package/dist/host-settings.js

@@ -0,0 +1,136 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync, unlinkSync } from 'fs';
+import { homedir } from 'os';
+import { randomBytes } from 'crypto';
+import path from 'path';
+/** The env var Claude Code reads to decide when to auto-background a long-running MCP tool call. */
+export const AUTO_BACKGROUND_ENV_KEY = 'CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS';
+/** The value that disables auto-backgrounding, so a blocking HITL tool call is never yanked away before the human answers. */
+export const AUTO_BACKGROUND_TARGET_VALUE = '0';
+/** Locate the host Claude Code settings file: ~/.claude/settings.json */
+export function getHostSettingsPath() {
+    return path.join(homedir(), '.claude', 'settings.json');
+}
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+/**
+ * Read a Claude Code settings.json file. Returns an empty object when the
+ * file is missing or blank, so callers can merge into the result unconditionally.
+ * Malformed JSON is not swallowed — it throws, so a caller can surface a clear
+ * error instead of silently discarding a user's existing settings.
+ */
+export function readHostSettings(settingsPath = getHostSettingsPath()) {
+    if (!existsSync(settingsPath))
+        return {};
+    const raw = readFileSync(settingsPath, 'utf-8');
+    if (!raw.trim())
+        return {};
+    return JSON.parse(raw);
+}
+/**
+ * Merge the auto-background remediation value into an existing settings
+ * object, preserving every other top-level key and every other `env` entry.
+ * Pure function — never mutates its input. Applying it to its own output is
+ * idempotent (produces an equal object).
+ */
+export function mergeAutoBackgroundSetting(existingSettings) {
+    const existingEnv = asRecord(existingSettings.env);
+    return {
+        ...existingSettings,
+        env: {
+            ...existingEnv,
+            [AUTO_BACKGROUND_ENV_KEY]: AUTO_BACKGROUND_TARGET_VALUE,
+        },
+    };
+}
+/**
+ * Write via a temp file in the same directory, then rename over the target,
+ * so a crash mid-write can never leave a partially-written settings.json.
+ * `renameSync` maps to MoveFileEx with MOVEFILE_REPLACE_EXISTING on Windows,
+ * so replacing an existing destination is atomic there too. The temp file is
+ * removed on failure so a full disk (or a failed rename) cannot leave debris
+ * behind.
+ */
+function writeAtomic(file, contents) {
+    const tmp = `${file}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`;
+    try {
+        writeFileSync(tmp, contents, 'utf-8');
+        renameSync(tmp, file);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch {
+            /* nothing to clean up */
+        }
+        throw err;
+    }
+}
+/**
+ * Apply the auto-background remediation to disk: read the existing
+ * settings.json (if any), merge in the target env value via
+ * {@link mergeAutoBackgroundSetting}, and write the result back only if it
+ * actually changed. Re-running this after a prior successful run is a no-op
+ * (`updated: false`) rather than rewriting an identical file.
+ *
+ * The parent directory (e.g. ~/.claude) is created if missing. Writes are
+ * atomic — see {@link writeAtomic}.
+ */
+export function applyAutoBackgroundSetting(settingsPath = getHostSettingsPath()) {
+    const existing = readHostSettings(settingsPath);
+    const merged = mergeAutoBackgroundSetting(existing);
+    if (JSON.stringify(merged) === JSON.stringify(existing)) {
+        return { updated: false, path: settingsPath };
+    }
+    mkdirSync(path.dirname(settingsPath), { recursive: true });
+    writeAtomic(settingsPath, JSON.stringify(merged, null, 2) + '\n');
+    return { updated: true, path: settingsPath };
+}
+/**
+ * Detect whether the auto-background guard is already in effect:
+ *  - `activeInEnv`: the currently running process inherited it — in effect now.
+ *  - `configuredForRestart`: ~/.claude/settings.json has it queued — takes
+ *    effect the next time Claude Code restarts, not for the current session.
+ *
+ * Never throws: a missing or malformed settings.json is treated the same as
+ * "not configured", since this is a read-only diagnostic.
+ */
+export function detectAutoBackgroundStatus(env = process.env, settingsPath = getHostSettingsPath()) {
+    const envValue = env[AUTO_BACKGROUND_ENV_KEY];
+    const activeInEnv = envValue === AUTO_BACKGROUND_TARGET_VALUE;
+    let settings;
+    try {
+        settings = readHostSettings(settingsPath);
+    }
+    catch {
+        settings = {};
+    }
+    const settingsEnv = asRecord(settings.env);
+    const rawSettingsValue = settingsEnv[AUTO_BACKGROUND_ENV_KEY];
+    const settingsValue = typeof rawSettingsValue === 'string' ? rawSettingsValue : undefined;
+    const configuredForRestart = settingsValue === AUTO_BACKGROUND_TARGET_VALUE;
+    return {
+        active: activeInEnv || configuredForRestart,
+        activeInEnv,
+        configuredForRestart,
+        envValue,
+        settingsValue,
+    };
+}
+/**
+ * Build reusable, human-readable remediation text for when the auto-background
+ * guard is not yet active. Shared by the setup diagnostic step, and any future
+ * CLI/UX surface that needs to explain the same fix.
+ */
+export function buildAutoBackgroundRemediationText(settingsPath = getHostSettingsPath()) {
+    return [
+        `${AUTO_BACKGROUND_ENV_KEY} is not set to "${AUTO_BACKGROUND_TARGET_VALUE}", so Claude Code may auto-background a long-running HITL tool call before you get a chance to respond.`,
+        `Fix: merge the following into ${settingsPath} (preserve every other key):`,
+        `  { "env": { "${AUTO_BACKGROUND_ENV_KEY}": "${AUTO_BACKGROUND_TARGET_VALUE}" } }`,
+        `Restart Claude Code afterward for the change to take effect.`,
+    ].join('\n');
+}
+//# sourceMappingURL=host-settings.js.map

package/dist/host-settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-settings.js","sourceRoot":"","sources":["../src/host-settings.ts"],"names":[],"mappings":"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"}

package/dist/identity.d.ts

@@ -0,0 +1,20 @@
+import type { SenderIdentity } from './types.js';
+/** Resolves a human-readable session name, or null when none is available. */
+export type SessionNameResolver = () => string | null;
+/**
+ * No documented Claude Code env var exposes a human-readable session name
+ * today — only a UUID. This seam lets a real resolver replace this default
+ * without touching call sites.
+ */
+export declare const defaultSessionNameResolver: SessionNameResolver;
+/**
+ * Resolve a display-ready sender identity for an outgoing message, in
+ * precedence order: session name override > linked-worktree branch > path
+ * fallback.
+ *
+ * Purely a function of its arguments — never reads `process.cwd()` or
+ * `os.hostname()` itself, so callers control (and tests can mock) both `cwd`
+ * and `deviceName`; per-tool cwd rules live at each call site.
+ */
+export declare function resolveSenderIdentity(cwd: string, deviceName: string, sessionResolver?: SessionNameResolver): SenderIdentity;
+//# sourceMappingURL=identity.d.ts.map

package/dist/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,8EAA8E;AAC9E,MAAM,MAAM,mBAAmB,GAAG,MAAM,MAAM,GAAG,IAAI,CAAC;AAEtD;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,EAAE,mBAAgC,CAAC;AAQ1E;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,EAClB,eAAe,GAAE,mBAAgD,GAChE,cAAc,CAYhB"}

package/dist/identity.js

@@ -0,0 +1,35 @@
+import { detectRepoContext, isLinkedWorktree } from './git-context.js';
+/**
+ * No documented Claude Code env var exposes a human-readable session name
+ * today — only a UUID. This seam lets a real resolver replace this default
+ * without touching call sites.
+ */
+export const defaultSessionNameResolver = () => null;
+/** Last two `/`-joined path segments of `cwd`, tolerating either path separator. Never absolute (F-9). */
+function lastTwoSegments(cwd) {
+    const segments = cwd.split(/[\\/]/).filter(Boolean);
+    return segments.slice(-2).join('/');
+}
+/**
+ * Resolve a display-ready sender identity for an outgoing message, in
+ * precedence order: session name override > linked-worktree branch > path
+ * fallback.
+ *
+ * Purely a function of its arguments — never reads `process.cwd()` or
+ * `os.hostname()` itself, so callers control (and tests can mock) both `cwd`
+ * and `deviceName`; per-tool cwd rules live at each call site.
+ */
+export function resolveSenderIdentity(cwd, deviceName, sessionResolver = defaultSessionNameResolver) {
+    const sessionName = sessionResolver();
+    if (sessionName !== null)
+        return { label: sessionName, source: 'session' };
+    if (isLinkedWorktree(cwd)) {
+        const branch = detectRepoContext(cwd)?.branch;
+        if (branch)
+            return { label: `${deviceName} - ${branch}`, source: 'worktree' };
+        // isLinkedWorktree true but no branch (race/edge case) — fall through rather
+        // than emit a malformed label.
+    }
+    return { label: `${deviceName} ${lastTwoSegments(cwd)}`, source: 'path' };
+}
+//# sourceMappingURL=identity.js.map

package/dist/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAMvE;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAwB,GAAG,EAAE,CAAC,IAAI,CAAC;AAE1E,0GAA0G;AAC1G,SAAS,eAAe,CAAC,GAAW;IAClC,MAAM,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACpD,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACtC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CACnC,GAAW,EACX,UAAkB,EAClB,kBAAuC,0BAA0B;IAEjE,MAAM,WAAW,GAAG,eAAe,EAAE,CAAC;IACtC,IAAI,WAAW,KAAK,IAAI;QAAE,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IAE3E,IAAI,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,MAAM,GAAG,iBAAiB,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QAC9C,IAAI,MAAM;YAAE,OAAO,EAAE,KAAK,EAAE,GAAG,UAAU,MAAM,MAAM,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;QAC9E,6EAA6E;QAC7E,+BAA+B;IACjC,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,GAAG,UAAU,IAAI,eAAe,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;AAC5E,CAAC"}

package/dist/mcp-server.d.ts

@@ -1,3 +1,67 @@
 #!/usr/bin/env node
-export {};
+import type { HitlConfig } from './types.js';
+export declare class HumanInTheLoopServer {
+    private server;
+    private transport;
+    private config;
+    /** reviewIds still waiting on a human, so a graceful exit can release them (D-3). */
+    private outstandingReviews;
+    /** `config` is injectable so a test can construct a server without a real ~/.hitl. */
+    constructor(config?: HitlConfig);
+    private setupHandlers;
+    /**
+     * ReviewPlan: snapshot a markdown plan, publish it for line-anchored review,
+     * and block until a human submits a verdict.
+     */
+    private handleReviewPlan;
+    /**
+     * Drop a subscription hold after the late-response window.
+     *
+     * The timer is unref'd so it can never be the reason the process stays alive.
+     */
+    private releaseLater;
+    /**
+     * Download, decode and validate a submitted review, then acknowledge it.
+     *
+     * The ack is what lets the client distinguish "the server read this" from "I
+     * clicked submit": the response attachment expires after 3 h while the
+     * message itself survives 12 h, so a submit can be accepted at click time and
+     * still never arrive (C-12).
+     */
+    private consumeReviewResponse;
+    private downloadResponseBody;
+    /**
+     * Publish the sender's own identity as a companion to a question or
+     * notification just published, unless the operator opted out.
+     *
+     * Shared by AskUserQuestion and Notify — both resolve identity from
+     * `process.cwd()` (ReviewPlan resolves from the plan's own directory
+     * instead, so it is not part of this shared path). Decoration only: never
+     * lets a publish failure escape past the tool call it decorates, matching
+     * `publishAck`'s log-and-continue pattern below.
+     */
+    private publishSenderIdentityFor;
+    /** Tell the client whether its submission actually landed. */
+    private publishAck;
+    /**
+     * Fail before publishing when no client can be found or launched.
+     *
+     * Without a timeout to bound it, publishing to a topic nobody is subscribed
+     * to is a permanent silent hang — the agent blocks and the human never sees a
+     * window to explain why (A-10).
+     */
+    private requireClient;
+    /**
+     * Start emitting progress notifications, returning the stop function.
+     *
+     * Whether these actually keep the call alive is the calling host's decision:
+     * the MCP SDK's DEFAULT_REQUEST_TIMEOUT_MSEC is 60 s and
+     * `resetTimeoutOnProgress` defaults to false, so a host that does not opt in
+     * will time the call out regardless of what we send (D-2).
+     */
+    private startHeartbeat;
+    run(): Promise<void>;
+    /** Publish cancel_review for every review still waiting on a human. */
+    private cancelOutstandingReviews;
+}
 //# sourceMappingURL=mcp-server.d.ts.map

package/dist/mcp-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":""}
+{"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":";AAcA,OAAO,KAAK,EAaV,UAAU,EAGX,MAAM,YAAY,CAAC;AAuDpB,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAgB;IACjC,OAAO,CAAC,MAAM,CAAa;IAC3B,qFAAqF;IACrF,OAAO,CAAC,kBAAkB,CAAqB;IAE/C,sFAAsF;gBAC1E,MAAM,GAAE,UAAyB;IAY7C,OAAO,CAAC,aAAa;IA+brB;;;OAGG;YACW,gBAAgB;IAmK9B;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAIpB;;;;;;;OAOG;YACW,qBAAqB;YAiErB,oBAAoB;IAUlC;;;;;;;;;OASG;YACW,wBAAwB;IAmBtC,8DAA8D;YAChD,UAAU;IAuBxB;;;;;;OAMG;IACH,OAAO,CAAC,aAAa;IAUrB;;;;;;;OAOG;IACH,OAAO,CAAC,cAAc;IAyBhB,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IA0B1B,uEAAuE;YACzD,wBAAwB;CAkBvC"}