@minasoft/mina-ai-router 0.1.5 → 0.2.1

package/dist/packages/core/src/router.js

@@ -1,9 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AgentRouter = void 0;
+exports.AgentRouter = exports.AgentNotRouteReadyError = void 0;
 const ids_1 = require("./ids");
 const prompt_envelope_1 = require("./prompt-envelope");
 const response_parser_1 = require("./response-parser");
+const rawEvidenceExcerptLimit = 4000;
+const defaultAgentStaleAfterMs = 15 * 60 * 1000;
+class RequestNoLongerOpenError extends Error {
+    constructor(request) {
+        super(`Request "${request.id}" is ${request.status} and can no longer be updated by the active router call.`);
+        this.request = request;
+    }
+}
+class AgentNotRouteReadyError extends Error {
+    constructor(agentId, reason) {
+        super(`Agent "${agentId}" is not ready to receive routed work: ${reason}`);
+        this.agentId = agentId;
+        this.reason = reason;
+    }
+}
+exports.AgentNotRouteReadyError = AgentNotRouteReadyError;
 class AgentRouter {
     constructor(options) {
         this.busyAgents = new Set();
@@ -12,6 +28,7 @@ class AgentRouter {
         this.transports = options.transports;
         this.defaultSourceAgent = options.defaultSourceAgent ?? "main";
         this.defaultTimeoutMs = options.defaultTimeoutMs ?? 300000;
+        this.agentStaleAfterMs = options.agentStaleAfterMs ?? defaultAgentStaleAfterMs;
         this.onStateChanged = options.onStateChanged;
     }
     listAgents() {
@@ -20,8 +37,10 @@ class AgentRouter {
     listRequests() {
         return this.requestStore.list();
     }
-    async listAgentStatuses() {
+    async listAgentStatuses(options = {}) {
         const requests = this.requestStore.list();
+        const checkedAt = new Date().toISOString();
+        let healthChanged = false;
         return Promise.all(this.registry.list().map(async (agent) => {
             const agentRequests = requests.filter((request) => request.targetAgent === agent.id);
             const lastRequest = agentRequests[agentRequests.length - 1];
@@ -29,6 +48,39 @@ class AgentRouter {
             const status = transport.status
                 ? await transport.status(agent)
                 : { status: "unknown" };
+            const bootstrapStatus = status.bootstrapStatus ?? agent.bootstrapStatus;
+            if (status.bootstrapStatus && status.bootstrapStatus !== agent.bootstrapStatus) {
+                this.registry.register({
+                    ...agent,
+                    bootstrapStatus: status.bootstrapStatus,
+                });
+                healthChanged = true;
+            }
+            const lastActivityAt = lastRequest?.updatedAt ?? agent.lastActivityAt;
+            const lastSeenAt = status.status === "available" ? checkedAt : agent.lastSeenAt;
+            const healthStatus = classifyAgentHealth({
+                transportStatus: status.status,
+                bootstrapStatus,
+                registrationStatus: agent.registrationStatus,
+                mcpPreflightStatus: agent.mcpPreflightStatus,
+                busy: this.busyAgents.has(agent.id),
+                lastSeenAt,
+                lastActivityAt,
+                lastRequest,
+                checkedAt,
+                staleAfterMs: this.agentStaleAfterMs,
+            });
+            const routeReadiness = classifyRouteReadiness({
+                healthStatus: healthStatus.status,
+                healthDetail: healthStatus.detail ?? status.detail,
+                bootstrapStatus,
+                registrationStatus: agent.registrationStatus,
+                mcpPreflightStatus: agent.mcpPreflightStatus,
+            });
+            if (lastSeenAt !== agent.lastSeenAt || lastActivityAt !== agent.lastActivityAt) {
+                this.registry.updateHealth(agent.id, { lastSeenAt, lastActivityAt });
+                healthChanged = true;
+            }
             return {
                 id: agent.id,
                 name: agent.name,
@@ -38,22 +90,127 @@ class AgentRouter {
                 projectRoot: agent.projectRoot,
                 capabilitySummary: agent.capabilitySummary,
                 capabilitySources: agent.capabilitySources,
-                status: this.busyAgents.has(agent.id) ? "busy" : status.status,
-                detail: status.detail,
+                capabilitySource: agent.capabilitySource,
+                capabilityUpdatedAt: agent.capabilityUpdatedAt,
+                lastCapabilityRefreshAt: agent.lastCapabilityRefreshAt,
+                capabilityProfile: agent.capabilityProfile,
+                bootstrapStatus,
+                registrationSource: agent.registrationSource,
+                registrationStatus: agent.registrationStatus,
+                lastRegistrationAttemptAt: agent.lastRegistrationAttemptAt,
+                confirmedByAgentAt: agent.confirmedByAgentAt,
+                sessionFingerprint: agent.sessionFingerprint,
+                registrationHistory: agent.registrationHistory,
+                registrationWarnings: agent.registrationWarnings,
+                permissionProfile: agent.permissionProfile,
+                permissionProfileStatus: agent.permissionProfileStatus,
+                permissionProfileDetail: agent.permissionProfileDetail,
+                permissionPrompt: status.permissionPrompt,
+                mcpPreflightStatus: agent.mcpPreflightStatus,
+                mcpPreflightDetail: agent.mcpPreflightDetail,
+                mcpSetupCommand: agent.mcpSetupCommand,
+                mcpVerifyCommand: agent.mcpVerifyCommand,
+                mcpRemoveCommand: agent.mcpRemoveCommand,
+                mcpUrl: agent.mcpUrl,
+                lastSeenAt,
+                lastActivityAt,
+                activeRequestId: agent.activeRequestId,
+                leaseStatus: agent.leaseStatus,
+                leaseStartedAt: agent.leaseStartedAt,
+                leaseExpiresAt: agent.leaseExpiresAt,
+                leaseReleasedAt: agent.leaseReleasedAt,
+                healthCheckedAt: checkedAt,
+                staleAfterMs: this.agentStaleAfterMs,
+                status: healthStatus.status,
+                detail: healthStatus.detail ?? status.detail,
+                routeReady: routeReadiness.routeReady,
+                routeBlockedReason: routeReadiness.routeBlockedReason,
                 lastRequestStatus: lastRequest?.status,
+                isSelf: options.callerAgentId === agent.id || undefined,
             };
-        }));
+        })).finally(() => {
+            if (healthChanged) {
+                this.persistState();
+            }
+        });
     }
     getRequest(requestId) {
         return this.requestStore.require(requestId);
     }
+    recoverRequestLease(requestId, source, message = "Marked recovered by operator.") {
+        const updated = this.requestStore.markRecovered(requestId, source, message);
+        const agentId = updated.leaseOwnerAgentId ?? updated.targetAgent;
+        this.releaseAgentLease(agentId, updated.id);
+        this.persistState();
+        return this.requestStore.require(updated.id);
+    }
+    archiveRequest(requestId, source, reason = "Archived by operator.") {
+        const updated = this.requestStore.archive(requestId, reason, source);
+        if (updated.leaseStatus === "released") {
+            const agentId = updated.leaseOwnerAgentId ?? updated.targetAgent;
+            this.releaseAgentLease(agentId, updated.id);
+        }
+        this.persistState();
+        return this.requestStore.require(updated.id);
+    }
     async callAgent(input) {
         const target = this.registry.require(input.target);
+        if (input.sourceAgent && input.sourceAgent === target.id && !input.allowSelfCall) {
+            throw new Error(`Refusing self-call from agent "${target.id}" to itself. Choose another target from list_agents or pass allowSelfCall: true for diagnostics.`);
+        }
         if (this.busyAgents.has(target.id)) {
             throw new Error(`Agent "${target.id}" is busy with another request.`);
         }
+        const transport = this.transports.get(target.transport);
+        const checkedAt = new Date().toISOString();
+        const transportStatus = transport.status
+            ? await transport.status(target)
+            : { status: "unknown" };
+        const bootstrapStatus = transportStatus.bootstrapStatus ?? target.bootstrapStatus;
+        if (transportStatus.bootstrapStatus && transportStatus.bootstrapStatus !== target.bootstrapStatus) {
+            this.registry.register({
+                ...target,
+                bootstrapStatus: transportStatus.bootstrapStatus,
+            });
+            this.persistState();
+        }
+        const agentRequests = this.requestStore.list().filter((request) => request.targetAgent === target.id);
+        const lastRequest = agentRequests[agentRequests.length - 1];
+        const healthStatus = classifyAgentHealth({
+            transportStatus: transportStatus.status,
+            bootstrapStatus,
+            registrationStatus: target.registrationStatus,
+            mcpPreflightStatus: target.mcpPreflightStatus,
+            busy: false,
+            lastSeenAt: transportStatus.status === "available" ? checkedAt : target.lastSeenAt,
+            lastActivityAt: lastRequest?.updatedAt ?? target.lastActivityAt,
+            lastRequest,
+            checkedAt,
+            staleAfterMs: this.agentStaleAfterMs,
+        });
+        const routeReadiness = classifyRouteReadiness({
+            healthStatus: healthStatus.status,
+            healthDetail: healthStatus.detail ?? transportStatus.detail,
+            bootstrapStatus,
+            registrationStatus: target.registrationStatus,
+            mcpPreflightStatus: target.mcpPreflightStatus,
+        });
+        if (!routeReadiness.routeReady) {
+            throw new AgentNotRouteReadyError(target.id, routeReadiness.routeBlockedReason ?? "Agent is not route-ready.");
+        }
         this.busyAgents.add(target.id);
         const now = new Date().toISOString();
+        const timeoutMs = input.timeoutMs ?? this.defaultTimeoutMs;
+        const leaseExpiresAt = new Date(Date.now() + timeoutMs).toISOString();
+        this.registry.register({
+            ...target,
+            activeRequestId: undefined,
+            leaseStatus: undefined,
+            leaseStartedAt: undefined,
+            leaseExpiresAt: undefined,
+            leaseReleasedAt: undefined,
+            lastActivityAt: now,
+        });
         const request = this.requestStore.create({
             id: (0, ids_1.createRequestId)(),
             sourceAgent: input.sourceAgent ?? this.defaultSourceAgent,
@@ -62,19 +219,49 @@ class AgentRouter {
             status: "created",
             createdAt: now,
             updatedAt: now,
+            retryOfRequestId: input.retryOfRequestId,
+            leaseStatus: "active",
+            leaseStartedAt: now,
+            leaseExpiresAt,
+            leaseOwnerAgentId: target.id,
+            leaseTargetSessionId: target.sessionId,
+            leaseTargetSessionFingerprint: target.sessionFingerprint,
+        });
+        this.registry.register({
+            ...target,
+            activeRequestId: request.id,
+            leaseStatus: "active",
+            leaseStartedAt: now,
+            leaseExpiresAt,
+            leaseReleasedAt: undefined,
+            lastActivityAt: now,
         });
         this.persistState();
-        const transport = this.transports.get(target.transport);
         const prompt = (0, prompt_envelope_1.buildPromptEnvelope)(request, target);
+        this.requestStore.patch(request.id, {
+            promptEvidence: rawEvidenceFromOutput(prompt, "prompt_envelope"),
+        });
+        let output = "";
         try {
             await transport.send(target, prompt, request.id);
-            this.requestStore.updateStatus(request.id, "sent");
+            this.updateOpenRequestStatus(request.id, "sent");
             this.persistState();
-            this.requestStore.updateStatus(request.id, "waiting");
+            this.updateOpenRequestStatus(request.id, "waiting");
             this.persistState();
-            const output = await transport.waitForResponse(target, request.id, input.timeoutMs ?? this.defaultTimeoutMs);
-            const answer = (0, response_parser_1.parseMarkedResponse)(output, request.id);
-            this.requestStore.updateStatus(request.id, "answered", { answer });
+            output = await transport.waitForResponse(target, request.id, input.timeoutMs ?? this.defaultTimeoutMs);
+            const parsed = (0, response_parser_1.inspectMarkedResponse)(output, request.id);
+            if (!parsed.ok) {
+                throw new response_parser_1.ResponseParseError(parsed.diagnostics);
+            }
+            const answer = parsed.answer;
+            this.updateOpenRequestStatus(request.id, "answered", {
+                answer,
+                diagnosticStatus: "answered",
+                parserDiagnostics: parsed.diagnostics,
+                rawEvidence: rawEvidenceFromOutput(output),
+                ...releasedLeasePatch(),
+            });
+            this.releaseAgentLease(target.id, request.id);
             this.persistState();
             return {
                 requestId: request.id,
@@ -83,18 +270,226 @@ class AgentRouter {
             };
         }
         catch (error) {
+            if (error instanceof RequestNoLongerOpenError) {
+                this.releaseAgentLease(target.id, request.id);
+                this.persistState();
+                throw error;
+            }
             const message = error instanceof Error ? error.message : String(error);
             const status = /time(?:d)?\s*out|timeout/i.test(message) ? "timeout" : "failed";
-            this.requestStore.updateStatus(request.id, status, { error: message });
+            const capturedOutput = output || extractLastCapture(message);
+            const updated = this.requestStore.updateOpenStatus(request.id, status, {
+                error: message,
+                diagnosticStatus: diagnosticStatusForError(error, status),
+                parserDiagnostics: error instanceof response_parser_1.ResponseParseError ? error.diagnostics : undefined,
+                rawEvidence: capturedOutput ? rawEvidenceFromOutput(capturedOutput) : undefined,
+                ...(status === "timeout" ? orphanedLeasePatch() : releasedLeasePatch()),
+            });
+            if (!updated) {
+                this.releaseAgentLease(target.id, request.id);
+                throw new RequestNoLongerOpenError(this.requestStore.require(request.id));
+            }
+            if (status === "timeout") {
+                this.orphanAgentLease(target.id, request.id);
+            }
+            else {
+                this.releaseAgentLease(target.id, request.id);
+            }
             this.persistState();
             throw error;
         }
         finally {
-            this.busyAgents.delete(target.id);
+            const current = this.registry.get(target.id);
+            if (current?.activeRequestId !== request.id) {
+                this.busyAgents.delete(target.id);
+            }
+        }
+    }
+    updateOpenRequestStatus(requestId, status, patch = {}) {
+        const updated = this.requestStore.updateOpenStatus(requestId, status, patch);
+        if (!updated) {
+            throw new RequestNoLongerOpenError(this.requestStore.require(requestId));
         }
+        return updated;
     }
     persistState() {
         this.onStateChanged?.();
     }
+    releaseAgentLease(agentId, requestId) {
+        const current = this.registry.get(agentId);
+        if (!current || current.activeRequestId !== requestId) {
+            this.busyAgents.delete(agentId);
+            return;
+        }
+        this.registry.register({
+            ...current,
+            activeRequestId: undefined,
+            leaseStatus: "released",
+            leaseReleasedAt: new Date().toISOString(),
+        });
+        this.busyAgents.delete(agentId);
+    }
+    orphanAgentLease(agentId, requestId) {
+        const current = this.registry.get(agentId);
+        if (!current || current.activeRequestId !== requestId) {
+            return;
+        }
+        this.registry.register({
+            ...current,
+            activeRequestId: requestId,
+            leaseStatus: "orphaned",
+        });
+    }
 }
 exports.AgentRouter = AgentRouter;
+function releasedLeasePatch() {
+    return {
+        leaseStatus: "released",
+        leaseReleasedAt: new Date().toISOString(),
+    };
+}
+function orphanedLeasePatch() {
+    return {
+        leaseStatus: "orphaned",
+    };
+}
+function diagnosticStatusForError(error, status) {
+    if (status === "timeout") {
+        return "timeout";
+    }
+    if (error instanceof response_parser_1.ResponseParseError) {
+        return "parse_failure";
+    }
+    return "transport_failure";
+}
+function classifyAgentHealth(input) {
+    if (input.lastRequest?.leaseStatus === "orphaned") {
+        return { status: "busy", detail: `Request "${input.lastRequest.id}" timed out in the router, but the target session lease is still attached for recovery.` };
+    }
+    if (input.lastRequest?.leaseStatus === "active" && ["created", "sent", "waiting"].includes(input.lastRequest.status)) {
+        return { status: "busy", detail: `Request "${input.lastRequest.id}" still has an active lease.` };
+    }
+    if (input.busy) {
+        return { status: "busy", detail: "Agent is currently handling a routed request." };
+    }
+    if (input.transportStatus === "missing") {
+        return { status: "missing" };
+    }
+    if (input.transportStatus === "needs-attention") {
+        return { status: "needs-attention" };
+    }
+    if (input.bootstrapStatus === "permission-required") {
+        return {
+            status: "needs-attention",
+            detail: "Agent is waiting for operator permission before it can receive routed work.",
+        };
+    }
+    if (input.bootstrapStatus === "client-update-required") {
+        return {
+            status: "needs-attention",
+            detail: "Agent CLI is waiting at an update prompt before Mina can continue registration.",
+        };
+    }
+    if (input.bootstrapStatus === "mcp-configuring") {
+        return {
+            status: "needs-attention",
+            detail: "Agent is waiting for Mina MCP setup before it can self-register or receive routed work.",
+        };
+    }
+    if (input.bootstrapStatus === "registration-pending" || input.registrationStatus === "pending") {
+        return {
+            status: "needs-attention",
+            detail: "Agent self-registration has not been confirmed yet.",
+        };
+    }
+    if (input.mcpPreflightStatus === "missing" || input.mcpPreflightStatus === "stale") {
+        return {
+            status: "needs-attention",
+            detail: "Agent MCP preflight is not ready; fix MCP setup before routing work.",
+        };
+    }
+    const attentionStatuses = new Set(["failed", "timeout"]);
+    if (input.lastRequest && attentionStatuses.has(input.lastRequest.status) && input.lastRequest.recoveryStatus !== "recovered") {
+        return {
+            status: "needs-attention",
+            detail: input.lastRequest.error
+                ? `Last request ${input.lastRequest.status}: ${input.lastRequest.error}`
+                : `Last request is ${input.lastRequest.status}.`,
+        };
+    }
+    const staleReference = input.lastSeenAt ?? input.lastActivityAt;
+    if (staleReference && isOlderThan(staleReference, input.checkedAt, input.staleAfterMs)) {
+        return {
+            status: "stale",
+            detail: `No confirmed agent reachability within ${Math.round(input.staleAfterMs / 1000)} seconds.`,
+        };
+    }
+    if (input.transportStatus === "available") {
+        return { status: "available" };
+    }
+    if (input.transportStatus === "stale") {
+        return { status: input.transportStatus };
+    }
+    return { status: "unknown" };
+}
+function classifyRouteReadiness(input) {
+    const blocker = routeBlocker(input);
+    return blocker
+        ? { routeReady: false, routeBlockedReason: blocker }
+        : { routeReady: true };
+}
+function routeBlocker(input) {
+    if (input.bootstrapStatus === "permission-required") {
+        return "Agent is waiting for operator permission before it can receive routed work.";
+    }
+    if (input.bootstrapStatus === "client-update-required") {
+        return "Agent CLI is waiting at an update prompt before Mina can continue registration.";
+    }
+    if (input.bootstrapStatus === "mcp-configuring") {
+        return "Agent is waiting for Mina MCP setup before it can self-register or receive routed work.";
+    }
+    if (input.bootstrapStatus === "registration-pending" || input.registrationStatus === "pending") {
+        return "Agent self-registration has not been confirmed yet.";
+    }
+    if (input.mcpPreflightStatus === "missing" || input.mcpPreflightStatus === "stale") {
+        return "Agent MCP preflight is not ready; fix MCP setup before routing work.";
+    }
+    if (input.healthStatus === "busy") {
+        return input.healthDetail ?? "Agent is currently handling a routed request.";
+    }
+    if (input.healthStatus === "missing") {
+        return input.healthDetail ?? "Agent transport is missing.";
+    }
+    if (input.healthStatus === "stale") {
+        return input.healthDetail ?? "Agent health is stale.";
+    }
+    if (input.healthStatus === "needs-attention") {
+        return input.healthDetail ?? "Agent needs operator attention before it can receive routed work.";
+    }
+    return undefined;
+}
+function isOlderThan(timestamp, now, staleAfterMs) {
+    const timestampMs = Date.parse(timestamp);
+    const nowMs = Date.parse(now);
+    return Number.isFinite(timestampMs)
+        && Number.isFinite(nowMs)
+        && nowMs - timestampMs > staleAfterMs;
+}
+function rawEvidenceFromOutput(output, kind = "transport_capture") {
+    const excerpt = output.slice(-rawEvidenceExcerptLimit);
+    return {
+        kind,
+        capturedAt: new Date().toISOString(),
+        characterCount: output.length,
+        excerpt,
+        truncated: output.length > excerpt.length,
+    };
+}
+function extractLastCapture(message) {
+    const marker = "Last capture:\n";
+    const index = message.indexOf(marker);
+    if (index === -1) {
+        return undefined;
+    }
+    return message.slice(index + marker.length);
+}

package/dist/packages/core/src/runtime-paths.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultRuntimeDir = defaultRuntimeDir;
+exports.defaultRouterStatePath = defaultRouterStatePath;
+exports.defaultServerPidPath = defaultServerPidPath;
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+function defaultRuntimeDir() {
+    return process.env.MINA_RUNTIME_DIR ?? (0, node_path_1.join)((0, node_os_1.homedir)(), ".mair");
+}
+function defaultRouterStatePath() {
+    return (0, node_path_1.join)(defaultRuntimeDir(), "router-state.json");
+}
+function defaultServerPidPath() {
+    return (0, node_path_1.join)(defaultRuntimeDir(), "mair-server.json");
+}

package/dist/packages/core/src/version.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.packageVersion = packageVersion;
+exports.packageRoot = packageRoot;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const fallbackVersion = "0.0.0";
+const packageName = "@minasoft/mina-ai-router";
+function packageVersion() {
+    const packagePath = findPackageJson();
+    if (!packagePath) {
+        return fallbackVersion;
+    }
+    try {
+        const parsed = JSON.parse((0, node_fs_1.readFileSync)(packagePath, "utf8"));
+        return typeof parsed.version === "string" && parsed.version.trim()
+            ? parsed.version
+            : fallbackVersion;
+    }
+    catch {
+        return fallbackVersion;
+    }
+}
+function packageRoot() {
+    const packagePath = findPackageJson();
+    return packagePath ? (0, node_path_1.dirname)(packagePath) : undefined;
+}
+function findPackageJson() {
+    return findUpPackageJson(__dirname);
+}
+function findUpPackageJson(start) {
+    let current = (0, node_path_1.resolve)(start);
+    for (let depth = 0; depth < 10; depth += 1) {
+        const candidate = (0, node_path_1.join)(current, "package.json");
+        if (isMinaPackageJson(candidate)) {
+            return candidate;
+        }
+        const parent = (0, node_path_1.dirname)(current);
+        if (parent === current) {
+            return undefined;
+        }
+        current = parent;
+    }
+    return undefined;
+}
+function isMinaPackageJson(candidate) {
+    if (!(0, node_fs_1.existsSync)(candidate)) {
+        return false;
+    }
+    try {
+        const parsed = JSON.parse((0, node_fs_1.readFileSync)(candidate, "utf8"));
+        return parsed.name === packageName;
+    }
+    catch {
+        return false;
+    }
+}