@automaton-labs/aib 0.0.6 → 0.0.8

package/dist/session/client.js

@@ -1 +1,359 @@
-"use strict";var b=exports&&exports.__createBinding||(Object.create?(function(t,e,r,n){n===void 0&&(n=r);var s=Object.getOwnPropertyDescriptor(e,r);(!s||("get"in s?!e.__esModule:s.writable||s.configurable))&&(s={enumerable:!0,get:function(){return e[r]}}),Object.defineProperty(t,n,s)}):(function(t,e,r,n){n===void 0&&(n=r),t[n]=e[r]})),O=exports&&exports.__setModuleDefault||(Object.create?(function(t,e){Object.defineProperty(t,"default",{enumerable:!0,value:e})}):function(t,e){t.default=e}),g=exports&&exports.__importStar||(function(){var t=function(e){return t=Object.getOwnPropertyNames||function(r){var n=[];for(var s in r)Object.prototype.hasOwnProperty.call(r,s)&&(n[n.length]=s);return n},t(e)};return function(e){if(e&&e.__esModule)return e;var r={};if(e!=null)for(var n=t(e),s=0;s<n.length;s++)n[s]!=="default"&&b(r,e,n[s]);return O(r,e),r}})();Object.defineProperty(exports,"__esModule",{value:!0}),exports.readSessionInfo=c,exports.removeSessionInfo=p,exports.isProcessAlive=u,exports.isSessionHealthy=h,exports.getSessionStatus=I,exports.stopSession=m,exports.ensureSession=_,exports.startSession=P,exports.callSession=j;const f=g(require("node:fs")),v=g(require("node:path")),A=require("node:child_process"),w=require("../shared/errors"),o=require("../shared/metrics"),N=require("../runtime/bundled-node"),d=require("./paths");function c(){try{const t=JSON.parse(f.readFileSync((0,d.getSessionInfoPath)(),"utf8"));if(!t||typeof t!="object"||Array.isArray(t))return null;const e=t;return typeof e.pid!="number"||typeof e.host!="string"||typeof e.port!="number"||typeof e.url!="string"||typeof e.startedAt!="string"?null:{pid:e.pid,host:e.host,port:e.port,url:e.url,startedAt:e.startedAt}}catch{return null}}function p(){f.rmSync((0,d.getSessionInfoPath)(),{force:!0}),f.rmSync((0,d.getSessionUrlPath)(),{force:!0})}function u(t){if(!Number.isInteger(t)||t<=0)return!1;try{return process.kill(t,0),!0}catch{return!1}}async function h(t){try{return(await fetch(`${t.url}/health`)).ok}catch{return!1}}async function I(){const t=c();if(!t)return{ok:!0,running:!1};const e=u(t.pid),r=e?await h(t):!1;return{ok:!0,running:e&&r,processAlive:e,healthy:r,session:{pid:t.pid,host:t.host,port:t.port,url:t.url,startedAt:t.startedAt}}}async function m(){const t=c();if(!t)return{ok:!0,stopped:!1,reason:"session-not-found"};let e=!1;if(u(t.pid))try{process.kill(t.pid),e=!0}catch{e=!1}return p(),{ok:!0,stopped:e,pid:t.pid}}async function _(t){const e=c();if(e&&u(e.pid)){const i=(0,o.metricsNow)(),y=await h(e);if((0,o.recordSpan)(t,"cli.session.healthCheckExisting",i),y)return e}p(),f.mkdirSync((0,d.getSessionDir)(),{recursive:!0});const r=v.resolve(__dirname,"..","bin","aib.js"),n=(0,N.resolveNodeRuntime)(),s=(0,o.metricsNow)();(0,A.spawn)(n.command,[r,"session","serve"],{detached:!0,stdio:"ignore",windowsHide:!0}).unref(),(0,o.recordSpan)(t,"cli.session.spawnProcess",s);const l=Date.now()+1e4,a=(0,o.metricsNow)();for(;Date.now()<l;){const i=c();if(i&&u(i.pid)&&await h(i))return(0,o.recordSpan)(t,"cli.session.waitForHealthy",a),i;await new Promise(y=>setTimeout(y,250))}throw new w.CliError("SESSION_START_TIMEOUT","Timed out waiting for the aib CLI session to start.")}async function P(){const t=await _();return{ok:!0,running:!0,session:{pid:t.pid,host:t.host,port:t.port,url:t.url,startedAt:t.startedAt}}}async function j(t,e){const r=(0,o.metricsNow)(),n=await _(e);(0,o.recordSpan)(e,"cli.session.ensure",r);let s;const S=(0,o.metricsNow)();try{s=await fetch(`${n.url}/run`,{method:"POST",headers:{"content-type":"application/json"},body:JSON.stringify(t)}),(0,o.recordSpan)(e,"cli.session.request",S)}catch(a){throw(0,o.recordSpan)(e,"cli.session.request",S),p(),new w.CliError("SESSION_TRANSPORT_ERROR","Failed to reach the local aib CLI session.",{cause:a instanceof Error?a.message:String(a)})}const l=await s.text();try{return JSON.parse(l)}catch{throw new w.CliError("SESSION_INVALID_JSON","The local aib CLI session returned non-JSON output.",{responseText:l})}}
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readSessionInfo = readSessionInfo;
+exports.removeSessionInfo = removeSessionInfo;
+exports.isProcessAlive = isProcessAlive;
+exports.isSessionHealthy = isSessionHealthy;
+exports.getSessionStatus = getSessionStatus;
+exports.stopSession = stopSession;
+exports.ensureSession = ensureSession;
+exports.startSession = startSession;
+exports.callSession = callSession;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const errors_1 = require("../shared/errors");
+const metrics_1 = require("../shared/metrics");
+const bundled_node_1 = require("../runtime/bundled-node");
+const paths_1 = require("./paths");
+const session_health_1 = require("./session-health");
+function readSessionInfo() {
+    try {
+        const parsed = JSON.parse(fs.readFileSync((0, paths_1.getSessionInfoPath)(), "utf8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return null;
+        }
+        const candidate = parsed;
+        if (typeof candidate.pid !== "number" ||
+            typeof candidate.host !== "string" ||
+            typeof candidate.port !== "number" ||
+            typeof candidate.url !== "string" ||
+            typeof candidate.startedAt !== "string") {
+            return null;
+        }
+        return {
+            pid: candidate.pid,
+            host: candidate.host,
+            port: candidate.port,
+            url: candidate.url,
+            startedAt: candidate.startedAt
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function removeSessionInfo() {
+    fs.rmSync((0, paths_1.getSessionInfoPath)(), { force: true });
+    fs.rmSync((0, paths_1.getSessionUrlPath)(), { force: true });
+}
+function isProcessAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0) {
+        return false;
+    }
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function isSessionHealthy(info) {
+    return (0, session_health_1.isReusableSessionHealth)(await readSessionHealth(info));
+}
+async function readSessionHealth(info) {
+    try {
+        const response = await fetch(`${info.url}/health`);
+        if (!response.ok)
+            return null;
+        const parsed = await response.json();
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function getSessionStatus() {
+    const info = readSessionInfo();
+    if (!info) {
+        return {
+            ok: true,
+            running: false
+        };
+    }
+    const processAlive = isProcessAlive(info.pid);
+    const health = processAlive ? await readSessionHealth(info) : null;
+    const healthy = (0, session_health_1.isReusableSessionHealth)(health);
+    return {
+        ok: true,
+        running: processAlive && healthy,
+        processAlive,
+        healthy,
+        session: {
+            pid: info.pid,
+            host: info.host,
+            port: info.port,
+            url: info.url,
+            startedAt: info.startedAt,
+            ...(health?.runtime && typeof health.runtime === "object" && !Array.isArray(health.runtime)
+                ? { runtime: health.runtime }
+                : {})
+        }
+    };
+}
+async function stopSession() {
+    const info = readSessionInfo();
+    if (!info) {
+        return {
+            ok: true,
+            stopped: false,
+            reason: "session-not-found"
+        };
+    }
+    let graceful = false;
+    let forced = false;
+    if (isProcessAlive(info.pid)) {
+        try {
+            const response = await fetch(`${info.url}/shutdown`, { method: "POST" });
+            graceful = response.ok && await waitForProcessExit(info.pid, 10_000);
+        }
+        catch {
+            graceful = false;
+        }
+        if (!graceful && isProcessAlive(info.pid)) {
+            try {
+                process.kill(info.pid);
+                forced = true;
+            }
+            catch {
+                forced = false;
+            }
+        }
+    }
+    removeSessionInfo();
+    return {
+        ok: true,
+        stopped: graceful || forced,
+        graceful,
+        forced,
+        pid: info.pid
+    };
+}
+async function waitForProcessExit(pid, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!isProcessAlive(pid))
+            return true;
+        await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+    return !isProcessAlive(pid);
+}
+async function ensureSession(metricsSpans) {
+    const existing = readSessionInfo();
+    if (existing && isProcessAlive(existing.pid)) {
+        const healthStartedAt = (0, metrics_1.metricsNow)();
+        const health = await readSessionHealth(existing);
+        const healthy = (0, session_health_1.isReusableSessionHealth)(health);
+        (0, metrics_1.recordSpan)(metricsSpans, "cli.session.healthCheckExisting", healthStartedAt);
+        if (healthy) {
+            return existing;
+        }
+        if ((0, session_health_1.isDrainingSessionHealth)(health)) {
+            const drainWaitStartedAt = (0, metrics_1.metricsNow)();
+            const stopped = await waitForProcessExit(existing.pid, 12_000);
+            (0, metrics_1.recordSpan)(metricsSpans, "cli.session.waitForDrainingExit", drainWaitStartedAt);
+            if (!stopped) {
+                throw new errors_1.CliError("SESSION_RUNTIME_DRAIN_TIMEOUT", "The previous AIB session runtime did not finish draining before the replacement deadline.");
+            }
+        }
+    }
+    removeSessionInfo();
+    fs.mkdirSync((0, paths_1.getSessionDir)(), { recursive: true });
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            return await spawnSessionAndWaitForHealth(metricsSpans);
+        }
+        catch (error) {
+            const retryable = error instanceof errors_1.CliError &&
+                (error.code === "SESSION_START_FAILED" || error.code === "SESSION_START_TIMEOUT");
+            if (!retryable || attempt === 1)
+                throw error;
+            await new Promise((resolve) => setTimeout(resolve, 250));
+        }
+    }
+    throw new errors_1.CliError("SESSION_START_FAILED", "The aib CLI session did not start after the bounded retry.");
+}
+async function spawnSessionAndWaitForHealth(metricsSpans) {
+    const cliEntrypoint = path.resolve(__dirname, "..", "bin", "aib.js");
+    const nodeRuntime = (0, bundled_node_1.resolveNodeRuntime)();
+    const spawnStartedAt = (0, metrics_1.metricsNow)();
+    const child = (0, node_child_process_1.spawn)(nodeRuntime.command, [cliEntrypoint, "session", "serve"], {
+        detached: true,
+        stdio: "ignore",
+        windowsHide: true
+    });
+    let startupFailure = null;
+    const onStartupError = (error) => {
+        startupFailure ??= new errors_1.CliError("SESSION_START_FAILED", "The aib CLI session process failed before the runtime became healthy.", {
+            causeCode: typeof error.code === "string"
+                ? error.code
+                : null,
+            cause: error.message
+        });
+    };
+    const onStartupExit = (exitCode, signal) => {
+        startupFailure ??= new errors_1.CliError("SESSION_START_FAILED", "The aib CLI session process exited before the runtime became healthy.", { exitCode, signal });
+    };
+    const stopObservingStartup = () => {
+        child.removeListener("error", onStartupError);
+        child.removeListener("exit", onStartupExit);
+    };
+    child.once("error", onStartupError);
+    child.once("exit", onStartupExit);
+    child.unref();
+    (0, metrics_1.recordSpan)(metricsSpans, "cli.session.spawnProcess", spawnStartedAt);
+    const deadline = Date.now() + 10_000;
+    const waitStartedAt = (0, metrics_1.metricsNow)();
+    while (Date.now() < deadline) {
+        const sessionInfo = readSessionInfo();
+        if (sessionInfo && isProcessAlive(sessionInfo.pid) && (await isSessionHealthy(sessionInfo))) {
+            stopObservingStartup();
+            (0, metrics_1.recordSpan)(metricsSpans, "cli.session.waitForHealthy", waitStartedAt);
+            return sessionInfo;
+        }
+        if (startupFailure) {
+            stopObservingStartup();
+            (0, metrics_1.recordSpan)(metricsSpans, "cli.session.waitForHealthy", waitStartedAt);
+            throw startupFailure;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 250));
+    }
+    const finalSessionInfo = readSessionInfo();
+    if (finalSessionInfo && isProcessAlive(finalSessionInfo.pid) && (await isSessionHealthy(finalSessionInfo))) {
+        stopObservingStartup();
+        (0, metrics_1.recordSpan)(metricsSpans, "cli.session.waitForHealthy", waitStartedAt);
+        return finalSessionInfo;
+    }
+    if (startupFailure) {
+        stopObservingStartup();
+        (0, metrics_1.recordSpan)(metricsSpans, "cli.session.waitForHealthy", waitStartedAt);
+        throw startupFailure;
+    }
+    stopObservingStartup();
+    throw new errors_1.CliError("SESSION_START_TIMEOUT", "Timed out waiting for the aib CLI session to start.");
+}
+async function startSession() {
+    const session = await ensureSession();
+    return {
+        ok: true,
+        running: true,
+        session: {
+            pid: session.pid,
+            host: session.host,
+            port: session.port,
+            url: session.url,
+            startedAt: session.startedAt
+        }
+    };
+}
+async function callSession(payload, metricsSpans) {
+    const ensureStartedAt = (0, metrics_1.metricsNow)();
+    const session = await ensureSession(metricsSpans);
+    (0, metrics_1.recordSpan)(metricsSpans, "cli.session.ensure", ensureStartedAt);
+    try {
+        return await postSessionRun(session, payload, metricsSpans, "cli.session.request");
+    }
+    catch (error) {
+        removeSessionInfo();
+        if (!isRetryableSessionPayload(payload)) {
+            throw sessionTransportError(error);
+        }
+        const retryEnsureStartedAt = (0, metrics_1.metricsNow)();
+        const retrySession = await ensureSession(metricsSpans);
+        (0, metrics_1.recordSpan)(metricsSpans, "cli.session.retryEnsure", retryEnsureStartedAt);
+        try {
+            return await postSessionRun(retrySession, payload, metricsSpans, "cli.session.retryRequest");
+        }
+        catch (retryError) {
+            removeSessionInfo();
+            throw sessionTransportError(retryError, true);
+        }
+    }
+}
+async function postSessionRun(session, payload, metricsSpans, spanName) {
+    let response;
+    const requestStartedAt = (0, metrics_1.metricsNow)();
+    try {
+        response = await fetch(`${session.url}/run`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json"
+            },
+            body: JSON.stringify(payload)
+        });
+        (0, metrics_1.recordSpan)(metricsSpans, spanName, requestStartedAt);
+    }
+    catch (error) {
+        (0, metrics_1.recordSpan)(metricsSpans, spanName, requestStartedAt);
+        throw error;
+    }
+    const responseText = await response.text();
+    try {
+        return JSON.parse(responseText);
+    }
+    catch {
+        throw new errors_1.CliError("SESSION_INVALID_JSON", "The local aib CLI session returned non-JSON output.", {
+            responseText
+        });
+    }
+}
+function sessionTransportError(error, retried = false) {
+    return new errors_1.CliError("SESSION_TRANSPORT_ERROR", "Failed to reach the local aib CLI session.", {
+        cause: error instanceof Error ? error.message : String(error),
+        ...(retried ? { retried: true } : {})
+    });
+}
+function isRetryableSessionPayload(payload) {
+    const command = typeof payload.command === "string" ? payload.command : "";
+    if (command === "inspect" ||
+        command === "printConfig" ||
+        command === "findImporters" ||
+        command === "findUnusedImports") {
+        return true;
+    }
+    return false;
+}

package/dist/session/daemon-state.js

@@ -0,0 +1,185 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cliDaemonIdentityPath = cliDaemonIdentityPath;
+exports.currentCliDaemonPackage = currentCliDaemonPackage;
+exports.writeCliDaemonIdentity = writeCliDaemonIdentity;
+exports.tryWriteCliDaemonIdentity = tryWriteCliDaemonIdentity;
+exports.readCliDaemonIdentity = readCliDaemonIdentity;
+exports.daemonIdentityToJson = daemonIdentityToJson;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const product_storage_1 = require("../config/product-storage");
+function cliDaemonIdentityPath(root = (0, product_storage_1.productStorageRoot)()) {
+    return path.join(root, "ota", "daemon-identity.json");
+}
+function currentCliDaemonPackage() {
+    const cliPath = path.resolve(__dirname, "..", "bin", "aib.js");
+    return {
+        cliPath,
+        packageRoot: path.dirname(path.dirname(cliPath))
+    };
+}
+function writeCliDaemonIdentity(root, identity) {
+    writeJsonAtomically(cliDaemonIdentityPath(root), identity);
+}
+/** OTA identity is advisory metadata and must never break a product request. */
+function tryWriteCliDaemonIdentity(root, identity, writer = writeCliDaemonIdentity) {
+    try {
+        writer(root, identity);
+        return { ok: true };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            code: readErrorCode(error),
+            error: error instanceof Error ? error.message : String(error)
+        };
+    }
+}
+function readCliDaemonIdentity(root) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(cliDaemonIdentityPath(root), "utf8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return null;
+        }
+        const candidate = parsed;
+        if (candidate.schemaVersion !== 1 ||
+            typeof candidate.daemonId !== "string" ||
+            typeof candidate.pid !== "number" ||
+            (candidate.status !== "running" && candidate.status !== "stopped") ||
+            typeof candidate.startedAt !== "string" ||
+            typeof candidate.updatedAt !== "string" ||
+            typeof candidate.heartbeatAt !== "string" ||
+            candidate.invokeProtocol !== "http-session-v1" ||
+            !Array.isArray(candidate.supportedModes) ||
+            typeof candidate.activeInvokeCount !== "number" ||
+            !Array.isArray(candidate.runningExecutions) ||
+            typeof candidate.cliPath !== "string" ||
+            typeof candidate.packageRoot !== "string") {
+            return null;
+        }
+        return {
+            schemaVersion: 1,
+            daemonId: candidate.daemonId,
+            pid: candidate.pid,
+            status: candidate.status,
+            startedAt: candidate.startedAt,
+            updatedAt: candidate.updatedAt,
+            heartbeatAt: candidate.heartbeatAt,
+            invokeProtocol: "http-session-v1",
+            supportedModes: candidate.supportedModes.filter((mode) => mode === "structured" || mode === "process" || mode === "stream"),
+            activeInvokeCount: Math.max(0, Math.floor(candidate.activeInvokeCount)),
+            runningExecutions: candidate.runningExecutions
+                .filter((item) => isExecution(item))
+                .map((item) => ({
+                executionId: item.executionId,
+                command: item.command,
+                startedAt: item.startedAt
+            })),
+            ...(typeof candidate.lastActivityAt === "string" ? { lastActivityAt: candidate.lastActivityAt } : {}),
+            ...(typeof candidate.idleDeadlineAt === "string" || candidate.idleDeadlineAt === null
+                ? { idleDeadlineAt: candidate.idleDeadlineAt }
+                : {}),
+            ...(typeof candidate.idleTtlMs === "number" ? { idleTtlMs: Math.max(0, Math.floor(candidate.idleTtlMs)) } : {}),
+            ...(typeof candidate.acceptingRequests === "boolean" ? { acceptingRequests: candidate.acceptingRequests } : {}),
+            ...(Array.isArray(candidate.idleRetainers)
+                ? { idleRetainers: candidate.idleRetainers.filter((item) => typeof item === "string") }
+                : {}),
+            ...(typeof candidate.shutdownReason === "string" || candidate.shutdownReason === null
+                ? { shutdownReason: candidate.shutdownReason }
+                : {}),
+            cliPath: path.resolve(candidate.cliPath),
+            packageRoot: path.resolve(candidate.packageRoot)
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function daemonIdentityToJson(identity) {
+    return {
+        schemaVersion: identity.schemaVersion,
+        daemonId: identity.daemonId,
+        pid: identity.pid,
+        status: identity.status,
+        startedAt: identity.startedAt,
+        updatedAt: identity.updatedAt,
+        heartbeatAt: identity.heartbeatAt,
+        invokeProtocol: identity.invokeProtocol,
+        supportedModes: identity.supportedModes,
+        activeInvokeCount: identity.activeInvokeCount,
+        runningExecutions: identity.runningExecutions,
+        ...(identity.lastActivityAt !== undefined ? { lastActivityAt: identity.lastActivityAt } : {}),
+        ...(identity.idleDeadlineAt !== undefined ? { idleDeadlineAt: identity.idleDeadlineAt } : {}),
+        ...(identity.idleTtlMs !== undefined ? { idleTtlMs: identity.idleTtlMs } : {}),
+        ...(identity.acceptingRequests !== undefined ? { acceptingRequests: identity.acceptingRequests } : {}),
+        ...(identity.idleRetainers !== undefined ? { idleRetainers: identity.idleRetainers } : {}),
+        ...(identity.shutdownReason !== undefined ? { shutdownReason: identity.shutdownReason } : {}),
+        cliPath: identity.cliPath,
+        packageRoot: identity.packageRoot
+    };
+}
+function isExecution(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const candidate = value;
+    return typeof candidate.executionId === "string" &&
+        typeof candidate.command === "string" &&
+        typeof candidate.startedAt === "string";
+}
+function writeJsonAtomically(filePath, value) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const tempPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+    try {
+        fs.writeFileSync(tempPath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+        fs.renameSync(tempPath, filePath);
+    }
+    catch (error) {
+        try {
+            fs.rmSync(tempPath, { force: true });
+        }
+        catch {
+            // Best-effort cleanup; preserve the original write error.
+        }
+        throw error;
+    }
+}
+function readErrorCode(error) {
+    return error && typeof error === "object" && "code" in error && typeof error.code === "string"
+        ? error.code
+        : null;
+}

package/dist/session/external-tool-coordinator.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExternalToolCoordinator = void 0;
+const errors_1 = require("../shared/errors");
+class ExternalToolCoordinator {
+    maxConcurrent;
+    maxQueued;
+    timeoutMs;
+    queue = [];
+    active = new Set();
+    disposed = false;
+    constructor(options = {}) {
+        this.maxConcurrent = Math.max(1, Math.floor(options.maxConcurrent ?? 2));
+        this.maxQueued = Math.max(0, Math.floor(options.maxQueued ?? 4));
+        this.timeoutMs = Math.max(1, Math.floor(options.timeoutMs ?? 30 * 60_000));
+    }
+    get state() {
+        return { active: this.active.size, queued: this.queue.length, disposed: this.disposed };
+    }
+    execute(task, requestSignal) {
+        if (this.disposed)
+            return Promise.reject(coordinatorError("EXTERNAL_TOOL_SHUTDOWN", "External tool coordinator is shutting down."));
+        if (this.active.size >= this.maxConcurrent && this.queue.length >= this.maxQueued) {
+            return Promise.reject(coordinatorError("EXTERNAL_TOOL_BACKPRESSURE", "External tool queue is full."));
+        }
+        return new Promise((resolve, reject) => {
+            const item = { task, resolve, reject, ...(requestSignal ? { requestSignal } : {}) };
+            this.queue.push(item);
+            this.drain();
+        });
+    }
+    async shutdown() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        for (const item of this.queue.splice(0)) {
+            item.reject(coordinatorError("EXTERNAL_TOOL_SHUTDOWN", "External tool coordinator is shutting down."));
+        }
+        for (const controller of this.active)
+            controller.abort("shutdown");
+        while (this.active.size > 0)
+            await delay(10);
+    }
+    drain() {
+        while (!this.disposed && this.active.size < this.maxConcurrent && this.queue.length > 0) {
+            const item = this.queue.shift();
+            if (item.requestSignal?.aborted) {
+                item.reject(coordinatorError("EXTERNAL_TOOL_CANCELLED", "External tool request was cancelled."));
+                continue;
+            }
+            const controller = new AbortController();
+            this.active.add(controller);
+            let reason = null;
+            const onAbort = () => {
+                reason = "cancelled";
+                controller.abort("cancelled");
+            };
+            item.requestSignal?.addEventListener("abort", onAbort, { once: true });
+            const timer = setTimeout(() => {
+                reason = "timeout";
+                controller.abort("timeout");
+            }, this.timeoutMs);
+            timer.unref();
+            void item.task(controller.signal).then((value) => {
+                if (reason === "timeout")
+                    item.reject(coordinatorError("EXTERNAL_TOOL_TIMEOUT", "External tool execution timed out."));
+                else if (reason === "cancelled")
+                    item.reject(coordinatorError("EXTERNAL_TOOL_CANCELLED", "External tool request was cancelled."));
+                else if (controller.signal.aborted)
+                    item.reject(coordinatorError("EXTERNAL_TOOL_SHUTDOWN", "External tool coordinator is shutting down."));
+                else
+                    item.resolve(value);
+            }, (error) => item.reject(error)).finally(() => {
+                clearTimeout(timer);
+                item.requestSignal?.removeEventListener("abort", onAbort);
+                this.active.delete(controller);
+                this.drain();
+            });
+        }
+    }
+}
+exports.ExternalToolCoordinator = ExternalToolCoordinator;
+function coordinatorError(code, message) {
+    return new errors_1.CliError(code, message);
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}