@phuetz/code-buddy 2.0.0 → 2.2.0

package/dist/fleet/fleet-listener.js

@@ -49,8 +49,24 @@ import { EventEmitter } from 'events';
 import { WebSocket } from 'ws';
 import { logger } from '../utils/logger.js';
 import { ReconnectionManager, } from '../channels/reconnection-manager.js';
+/** Close a superseded socket without letting ws emit an unhandled error while CONNECTING. */
+function closeReplacedSocket(ws) {
+    ws.removeAllListeners();
+    ws.on('error', () => {
+        /* ws emits when close() interrupts a CONNECTING handshake */
+    });
+    try {
+        if (ws.readyState === 0 /* CONNECTING */ || ws.readyState === 1 /* OPEN */) {
+            ws.close();
+        }
+    }
+    catch {
+        /* best-effort replacement cleanup */
+    }
+}
 export class FleetListener extends EventEmitter {
     ws = null;
+    cancelConnectAttempt = null;
     connected = false;
     authenticated = false;
     // Set true once we have completed an `authenticated` handshake at least
@@ -156,49 +172,83 @@ export class FleetListener extends EventEmitter {
         return this.connectInternal();
     }
     async connectInternal() {
+        const replacingSocket = this.ws !== null;
+        // Reject and clean up an in-flight attempt before replacing its socket.
+        // In particular, ws.close() on CONNECTING emits an error; the replacement
+        // cleanup installs a sink so that cannot become an uncaught exception.
+        this.cancelConnectAttempt?.();
+        this.cancelConnectAttempt = null;
         // Cleanup any leftover ws from a previous attempt. Important for the
         // reconnect path so the new ws's events don't interleave with the
         // old one's. Mirrors the discord adapter's reconnect cleanup.
         if (this.ws) {
-            try {
-                this.ws.removeAllListeners();
-                if (this.ws.readyState === 1 /* OPEN */) {
-                    this.ws.close();
-                }
-            }
-            catch {
-                /* ignore */
-            }
+            closeReplacedSocket(this.ws);
             this.ws = null;
         }
+        if (replacingSocket) {
+            this.connected = false;
+            this.authenticated = false;
+            this.rejectPendingRequests('connection replaced');
+        }
         return new Promise((resolve, reject) => {
             let settled = false;
+            let cancelAttempt = null;
+            let connectTimer = null;
+            let authTimer = null;
+            const clearAttemptTimers = () => {
+                if (connectTimer) {
+                    clearTimeout(connectTimer);
+                    connectTimer = null;
+                }
+                if (authTimer) {
+                    clearTimeout(authTimer);
+                    authTimer = null;
+                }
+            };
             const settle = (err) => {
                 if (settled)
                     return;
                 settled = true;
+                clearAttemptTimers();
+                if (cancelAttempt && this.cancelConnectAttempt === cancelAttempt) {
+                    this.cancelConnectAttempt = null;
+                }
                 if (err)
                     reject(err);
                 else
                     resolve();
             };
-            const connectTimer = setTimeout(() => {
+            const ws = new WebSocket(this.options.url);
+            this.ws = ws;
+            cancelAttempt = () => {
+                if (this.ws === ws)
+                    this.ws = null;
+                settle(new Error('Fleet listener connection attempt replaced'));
+                closeReplacedSocket(ws);
+            };
+            this.cancelConnectAttempt = cancelAttempt;
+            connectTimer = setTimeout(() => {
                 settle(new Error(`Fleet listener connect timeout (${this.options.connectTimeoutMs ?? 10_000}ms)`));
                 try {
-                    this.ws?.close();
+                    ws.close();
                 }
                 catch {
                     /* ignore */
                 }
             }, this.options.connectTimeoutMs ?? 10_000);
-            let authTimer = null;
-            this.ws = new WebSocket(this.options.url);
-            this.ws.on('open', () => {
-                clearTimeout(connectTimer);
+            ws.on('open', () => {
+                if (this.ws !== ws)
+                    return;
+                if (connectTimer) {
+                    clearTimeout(connectTimer);
+                    connectTimer = null;
+                }
                 this.connected = true;
                 this.emit('connected');
             });
-            this.ws.on('message', (data) => {
+            ws.on('message', (data) => {
+                if (this.ws !== ws)
+                    return;
                 let msg;
                 try {
                     msg = JSON.parse(data.toString());
@@ -212,12 +262,24 @@ export class FleetListener extends EventEmitter {
                         clearTimeout(authTimer);
                         authTimer = null;
                     }
+                }, () => {
+                    if (settled || authTimer)
+                        return;
+                    authTimer = setTimeout(() => {
+                        settle(new Error(`Fleet listener auth timeout (${this.options.authTimeoutMs ?? 5_000}ms)`));
+                        try {
+                            ws.close();
+                        }
+                        catch {
+                            /* ignore */
+                        }
+                    }, this.options.authTimeoutMs ?? 5_000);
                 });
             });
-            this.ws.on('close', () => {
-                if (authTimer)
-                    clearTimeout(authTimer);
-                clearTimeout(connectTimer);
+            ws.on('close', () => {
+                if (this.ws !== ws)
+                    return;
+                clearAttemptTimers();
                 this.connected = false;
                 this.authenticated = false;
                 this.emit('disconnected');
@@ -250,36 +312,15 @@ export class FleetListener extends EventEmitter {
                     this.scheduleReconnectDeferred();
                 }
             });
-            this.ws.on('error', (err) => {
-                clearTimeout(connectTimer);
-                if (authTimer)
-                    clearTimeout(authTimer);
+            ws.on('error', (err) => {
+                if (this.ws !== ws)
+                    return;
                 this.emit('error', err);
                 settle(err instanceof Error ? err : new Error(String(err)));
             });
-            // After 'connected' from the server, send the auth message. Set up
-            // an auth timeout in case the server never responds.
-            this.once('connected', () => {
-                // 'connected' here is OUR emitted event when ws opened; we still
-                // need to wait for the SERVER's 'connected' message. The
-                // handleIncomingMessage path does the auth-send — see below.
-            });
-            // Bound auth wait: schedule the timeout after we send authenticate.
-            // We'll trigger this from handleIncomingMessage after sending auth.
-            this.once('__internal:auth-sent', () => {
-                authTimer = setTimeout(() => {
-                    settle(new Error(`Fleet listener auth timeout (${this.options.authTimeoutMs ?? 5_000}ms)`));
-                    try {
-                        this.ws?.close();
-                    }
-                    catch {
-                        /* ignore */
-                    }
-                }, this.options.authTimeoutMs ?? 5_000);
-            });
         });
     }
-    handleIncomingMessage(msg, settle, clearAuthTimer) {
+    handleIncomingMessage(msg, settle, clearAuthTimer, startAuthTimer) {
         // Server's welcome → send authenticate.
         if (msg.type === 'connected') {
             const auth = {};
@@ -288,7 +329,7 @@ export class FleetListener extends EventEmitter {
             if (this.options.jwt)
                 auth.token = this.options.jwt;
             this.send('authenticate', auth);
-            this.emit('__internal:auth-sent');
+            startAuthTimer();
             return;
         }
         if (msg.type === 'authenticated') {

package/dist/fleet/fleet-registry.d.ts

@@ -19,6 +19,8 @@
  * full listener module (avoids pulling ws at handler-load time).
  */
 export interface FleetListenerPublicAPI {
+    /** Actual transport state when supplied by the listener. */
+    isConnected?: () => boolean;
     disconnect: () => Promise<void>;
     getReconnectAttempts: () => number;
     isReconnecting: () => boolean;

package/dist/fleet/resource-catalog.d.ts

@@ -0,0 +1,245 @@
+import { z } from 'zod';
+export declare const resourceSchema: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodEnum<["inference", "comfyui", "storage", "rag", "database", "docker", "code-explorer", "camera", "microphone"]>;
+    hostId: z.ZodString;
+    declaredCapabilities: z.ZodArray<z.ZodString, "many">;
+    endpointRef: z.ZodString;
+    healthPath: z.ZodEnum<["/health", "/healthz", "/api/health", "/v1/models", "/api/tags", "/system_stats", "/_ping"]>;
+    permissions: z.ZodObject<{
+        probe: z.ZodBoolean;
+        use: z.ZodBoolean;
+    }, "strict", z.ZodTypeAny, {
+        use: boolean;
+        probe: boolean;
+    }, {
+        use: boolean;
+        probe: boolean;
+    }>;
+    ttlMs: z.ZodDefault<z.ZodNumber>;
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    timeoutMs: number;
+    id: string;
+    kind: "docker" | "inference" | "comfyui" | "storage" | "rag" | "database" | "code-explorer" | "camera" | "microphone";
+    ttlMs: number;
+    permissions: {
+        use: boolean;
+        probe: boolean;
+    };
+    hostId: string;
+    declaredCapabilities: string[];
+    endpointRef: string;
+    healthPath: "/health" | "/v1/models" | "/api/tags" | "/api/health" | "/healthz" | "/system_stats" | "/_ping";
+}, {
+    id: string;
+    kind: "docker" | "inference" | "comfyui" | "storage" | "rag" | "database" | "code-explorer" | "camera" | "microphone";
+    permissions: {
+        use: boolean;
+        probe: boolean;
+    };
+    hostId: string;
+    declaredCapabilities: string[];
+    endpointRef: string;
+    healthPath: "/health" | "/v1/models" | "/api/tags" | "/api/health" | "/healthz" | "/system_stats" | "/_ping";
+    timeoutMs?: number | undefined;
+    ttlMs?: number | undefined;
+}>;
+export type Resource = z.infer<typeof resourceSchema>;
+declare const observationSchema: z.ZodObject<{
+    state: z.ZodEnum<["online", "offline", "unknown"]>;
+    checkedAt: z.ZodNumber;
+    lastSeen: z.ZodNullable<z.ZodNumber>;
+    latencyMs: z.ZodNullable<z.ZodNumber>;
+    endpointFingerprint: z.ZodString;
+    reason: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    reason: string;
+    state: "unknown" | "offline" | "online";
+    lastSeen: number | null;
+    latencyMs: number | null;
+    checkedAt: number;
+    endpointFingerprint: string;
+}, {
+    reason: string;
+    state: "unknown" | "offline" | "online";
+    lastSeen: number | null;
+    latencyMs: number | null;
+    checkedAt: number;
+    endpointFingerprint: string;
+}>;
+export type Observation = z.infer<typeof observationSchema>;
+declare const entrySchema: z.ZodObject<{
+    resource: z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<["inference", "comfyui", "storage", "rag", "database", "docker", "code-explorer", "camera", "microphone"]>;
+        hostId: z.ZodString;
+        declaredCapabilities: z.ZodArray<z.ZodString, "many">;
+        endpointRef: z.ZodString;
+        healthPath: z.ZodEnum<["/health", "/healthz", "/api/health", "/v1/models", "/api/tags", "/system_stats", "/_ping"]>;
+        permissions: z.ZodObject<{
+            probe: z.ZodBoolean;
+            use: z.ZodBoolean;
+        }, "strict", z.ZodTypeAny, {
+            use: boolean;
+            probe: boolean;
+        }, {
+            use: boolean;
+            probe: boolean;
+        }>;
+        ttlMs: z.ZodDefault<z.ZodNumber>;
+        timeoutMs: z.ZodDefault<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        timeoutMs: number;
+        id: string;
+        kind: "docker" | "inference" | "comfyui" | "storage" | "rag" | "database" | "code-explorer" | "camera" | "microphone";
+        ttlMs: number;
+        permissions: {
+            use: boolean;
+            probe: boolean;
+        };
+        hostId: string;
+        declaredCapabilities: string[];
+        endpointRef: string;
+        healthPath: "/health" | "/v1/models" | "/api/tags" | "/api/health" | "/healthz" | "/system_stats" | "/_ping";
+    }, {
+        id: string;
+        kind: "docker" | "inference" | "comfyui" | "storage" | "rag" | "database" | "code-explorer" | "camera" | "microphone";
+        permissions: {
+            use: boolean;
+            probe: boolean;
+        };
+        hostId: string;
+        declaredCapabilities: string[];
+        endpointRef: string;
+        healthPath: "/health" | "/v1/models" | "/api/tags" | "/api/health" | "/healthz" | "/system_stats" | "/_ping";
+        timeoutMs?: number | undefined;
+        ttlMs?: number | undefined;
+    }>;
+    observation: z.ZodNullable<z.ZodObject<{
+        state: z.ZodEnum<["online", "offline", "unknown"]>;
+        checkedAt: z.ZodNumber;
+        lastSeen: z.ZodNullable<z.ZodNumber>;
+        latencyMs: z.ZodNullable<z.ZodNumber>;
+        endpointFingerprint: z.ZodString;
+        reason: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        reason: string;
+        state: "unknown" | "offline" | "online";
+        lastSeen: number | null;
+        latencyMs: number | null;
+        checkedAt: number;
+        endpointFingerprint: string;
+    }, {
+        reason: string;
+        state: "unknown" | "offline" | "online";
+        lastSeen: number | null;
+        latencyMs: number | null;
+        checkedAt: number;
+        endpointFingerprint: string;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    resource: {
+        timeoutMs: number;
+        id: string;
+        kind: "docker" | "inference" | "comfyui" | "storage" | "rag" | "database" | "code-explorer" | "camera" | "microphone";
+        ttlMs: number;
+        permissions: {
+            use: boolean;
+            probe: boolean;
+        };
+        hostId: string;
+        declaredCapabilities: string[];
+        endpointRef: string;
+        healthPath: "/health" | "/v1/models" | "/api/tags" | "/api/health" | "/healthz" | "/system_stats" | "/_ping";
+    };
+    observation: {
+        reason: string;
+        state: "unknown" | "offline" | "online";
+        lastSeen: number | null;
+        latencyMs: number | null;
+        checkedAt: number;
+        endpointFingerprint: string;
+    } | null;
+}, {
+    resource: {
+        id: string;
+        kind: "docker" | "inference" | "comfyui" | "storage" | "rag" | "database" | "code-explorer" | "camera" | "microphone";
+        permissions: {
+            use: boolean;
+            probe: boolean;
+        };
+        hostId: string;
+        declaredCapabilities: string[];
+        endpointRef: string;
+        healthPath: "/health" | "/v1/models" | "/api/tags" | "/api/health" | "/healthz" | "/system_stats" | "/_ping";
+        timeoutMs?: number | undefined;
+        ttlMs?: number | undefined;
+    };
+    observation: {
+        reason: string;
+        state: "unknown" | "offline" | "online";
+        lastSeen: number | null;
+        latencyMs: number | null;
+        checkedAt: number;
+        endpointFingerprint: string;
+    } | null;
+}>;
+export type ResourceStatus = z.infer<typeof entrySchema> & {
+    state: 'online' | 'offline' | 'unknown' | 'stale';
+    reason: string;
+    /** No heuristic RAM or inferred utilisation. This tranche has no load collector. */
+    load: null;
+    usageConfirmed: false;
+};
+/** Declarations and observations only: never the resolved endpoint value or the internal fingerprint. */
+export declare function publicResourceStatus(entry: ResourceStatus): {
+    resource: {
+        timeoutMs: number;
+        id: string;
+        kind: "docker" | "inference" | "comfyui" | "storage" | "rag" | "database" | "code-explorer" | "camera" | "microphone";
+        ttlMs: number;
+        permissions: {
+            use: boolean;
+            probe: boolean;
+        };
+        hostId: string;
+        declaredCapabilities: string[];
+        endpointRef: string;
+        healthPath: "/health" | "/v1/models" | "/api/tags" | "/api/health" | "/healthz" | "/system_stats" | "/_ping";
+    };
+    state: "unknown" | "offline" | "online" | "stale";
+    reason: string;
+    checkedAt: number | null;
+    lastSeen: number | null;
+    latencyMs: number | null;
+    load: null;
+    usageConfirmed: false;
+};
+export type PublicResourceStatus = ReturnType<typeof publicResourceStatus>;
+/** The RagChat connector reads this reference only; a selection never redirects it. */
+export declare const RAGCHAT_ENDPOINT_REF = "RAGCHAT_BASE_URL";
+export declare function selectionWarning(selected: Pick<ResourceStatus, 'resource'> | null): string | undefined;
+export declare class ResourceCatalog {
+    readonly filename: string;
+    private readonly now;
+    constructor(filename?: string, now?: () => number);
+    private read;
+    private update;
+    add(input: unknown): Promise<Resource>;
+    remove(id: string): Promise<{
+        removed: string;
+    }>;
+    private status;
+    list(): Promise<ResourceStatus[]>;
+    probe(id: string): Promise<ResourceStatus>;
+    select(capability: string, kind?: Resource['kind']): Promise<{
+        selected: ResourceStatus | null;
+        excluded: Array<{
+            id: string;
+            reason: string;
+        }>;
+        reason: string;
+    }>;
+}
+export {};

package/dist/fleet/resource-catalog.js

@@ -0,0 +1,211 @@
+/** Explicit resources; health is not proof that a model/capability works. */
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+import { writeJsonAtomic } from '../utils/atomic-write.js';
+const identifier = z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,95}$/);
+export const resourceSchema = z.object({
+    id: identifier,
+    kind: z.enum(['inference', 'comfyui', 'storage', 'rag', 'database', 'docker', 'code-explorer', 'camera', 'microphone']),
+    hostId: identifier,
+    declaredCapabilities: z.array(identifier).min(1).max(32),
+    endpointRef: z.string().regex(/^[A-Z][A-Z0-9_]{0,95}$/),
+    healthPath: z.enum(['/health', '/healthz', '/api/health', '/v1/models', '/api/tags', '/system_stats', '/_ping']),
+    permissions: z.object({ probe: z.boolean(), use: z.boolean() }).strict(),
+    ttlMs: z.number().int().min(1000).max(3600000).default(60000),
+    timeoutMs: z.number().int().min(50).max(5000).default(1000),
+}).strict();
+const observationSchema = z.object({
+    state: z.enum(['online', 'offline', 'unknown']),
+    checkedAt: z.number().nonnegative(),
+    lastSeen: z.number().nonnegative().nullable(),
+    latencyMs: z.number().nonnegative().nullable(),
+    endpointFingerprint: z.string(),
+    reason: z.string(),
+}).strict();
+const entrySchema = z.object({ resource: resourceSchema, observation: observationSchema.nullable() }).strict();
+const storeSchema = z.object({ version: z.literal(1), entries: z.array(entrySchema).max(100) }).strict();
+/** Declarations and observations only: never the resolved endpoint value or the internal fingerprint. */
+export function publicResourceStatus(entry) {
+    return { resource: entry.resource, state: entry.state, reason: entry.reason,
+        checkedAt: entry.observation?.checkedAt ?? null, lastSeen: entry.observation?.lastSeen ?? null,
+        latencyMs: entry.observation?.latencyMs ?? null, load: entry.load, usageConfirmed: entry.usageConfirmed };
+}
+/** The RagChat connector reads this reference only; a selection never redirects it. */
+export const RAGCHAT_ENDPOINT_REF = 'RAGCHAT_BASE_URL';
+export function selectionWarning(selected) {
+    if (!selected || selected.resource.kind !== 'rag' || selected.resource.endpointRef === RAGCHAT_ENDPOINT_REF)
+        return undefined;
+    return `ragchat_search interroge toujours ${RAGCHAT_ENDPOINT_REF} ; cette ressource référence ${selected.resource.endpointRef} et la sélection ne redirige pas le connecteur.`;
+}
+const allowedPaths = {
+    inference: ['/health', '/healthz', '/v1/models', '/api/tags'],
+    comfyui: ['/system_stats'],
+    rag: ['/health', '/healthz', '/api/health'],
+    docker: ['/_ping'],
+    'code-explorer': ['/health', '/healthz', '/api/health'],
+};
+function endpoint(resource) {
+    const raw = process.env[resource.endpointRef];
+    if (!raw)
+        throw new Error('ENDPOINT_UNCONFIGURED');
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error('ENDPOINT_INVALID');
+    }
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash || url.pathname !== '/') {
+        throw new Error('ENDPOINT_INVALID');
+    }
+    url.pathname = resource.healthPath;
+    return { url, fingerprint: createHash('sha256').update(url.href).digest('hex') };
+}
+export class ResourceCatalog {
+    filename;
+    now;
+    constructor(filename = path.join(os.homedir(), '.codebuddy', 'resources', 'catalog.json'), now = Date.now) {
+        this.filename = filename;
+        this.now = now;
+    }
+    async read() {
+        try {
+            const stat = await fs.lstat(this.filename);
+            if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1024 * 1024)
+                throw new Error('INVALID_CATALOG_FILE');
+            const parsed = storeSchema.safeParse(JSON.parse(await fs.readFile(this.filename, 'utf8')));
+            if (!parsed.success || new Set(parsed.data.entries.map(e => e.resource.id)).size !== parsed.data.entries.length) {
+                throw new Error('INVALID_CATALOG');
+            }
+            return parsed.data;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return { version: 1, entries: [] };
+            throw new Error('INVALID_CATALOG: existing data was not replaced');
+        }
+    }
+    async update(action) {
+        const directory = path.dirname(this.filename);
+        await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+        const stat = await fs.lstat(directory);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            throw new Error('INVALID_CATALOG_DIRECTORY');
+        await fs.chmod(directory, 0o700);
+        const lock = `${this.filename}.lock`;
+        try {
+            await fs.mkdir(lock, { mode: 0o700 });
+        }
+        catch {
+            throw new Error('CATALOG_BUSY: another writer or unrecovered lock');
+        }
+        try {
+            const store = await this.read();
+            const result = await action(store);
+            await writeJsonAtomic(this.filename, store, { mode: 0o600 });
+            return result;
+        }
+        finally {
+            await fs.rmdir(lock);
+        }
+    }
+    async add(input) {
+        const parsed = resourceSchema.safeParse(input);
+        if (!parsed.success)
+            throw new Error('INVALID_RESOURCE: check schema; inline endpoints and extra fields are forbidden');
+        return this.update(async (store) => {
+            if (store.entries.some(e => e.resource.id === parsed.data.id))
+                throw new Error('RESOURCE_EXISTS');
+            if (store.entries.length >= 100)
+                throw new Error('CATALOG_FULL');
+            store.entries.push({ resource: parsed.data, observation: null });
+            return parsed.data;
+        });
+    }
+    async remove(id) {
+        return this.update(async (store) => {
+            const index = store.entries.findIndex(e => e.resource.id === id);
+            if (index < 0)
+                throw new Error('RESOURCE_NOT_FOUND');
+            store.entries.splice(index, 1);
+            return { removed: id };
+        });
+    }
+    status(entry) {
+        const { resource, observation } = entry;
+        let state = observation?.state ?? 'unknown';
+        let reason = observation?.reason ?? 'NEVER_PROBED';
+        if (observation && (this.now() - observation.checkedAt >= resource.ttlMs || observation.checkedAt > this.now())) {
+            state = 'stale';
+            reason = 'OBSERVATION_EXPIRED';
+        }
+        try {
+            if (observation && observation.endpointFingerprint !== endpoint(resource).fingerprint) {
+                state = 'unknown';
+                reason = 'ENDPOINT_CHANGED';
+            }
+        }
+        catch {
+            state = 'unknown';
+            reason = 'ENDPOINT_UNCONFIGURED_OR_INVALID';
+        }
+        return { ...entry, state, reason, load: null, usageConfirmed: false };
+    }
+    async list() { return (await this.read()).entries.map(e => this.status(e)); }
+    async probe(id) {
+        // Lock covers the bounded probe so a later probe cannot be overwritten by an older completion.
+        return this.update(async (store) => {
+            const entry = store.entries.find(e => e.resource.id === id);
+            if (!entry)
+                throw new Error('RESOURCE_NOT_FOUND');
+            const r = entry.resource;
+            if (!r.permissions.probe)
+                throw new Error('PROBE_NOT_PERMITTED');
+            if (!allowedPaths[r.kind]?.includes(r.healthPath))
+                throw new Error('NO_READ_ONLY_PROBE_FOR_KIND_PATH');
+            const target = endpoint(r);
+            const start = this.now();
+            let state = 'offline';
+            let reason = 'PROBE_FAILED';
+            try {
+                const response = await fetch(target.url, { method: 'GET', redirect: 'manual', signal: AbortSignal.timeout(r.timeoutMs) });
+                state = response.ok ? 'online' : 'offline';
+                reason = response.ok ? 'HTTP_HEALTH_OK_NOT_USAGE_PROOF' : `HTTP_${response.status}`;
+                // Never parse service content, model lists, database contents or device frames.
+                await response.body?.cancel();
+            }
+            catch {
+                state = 'offline';
+                reason = 'UNREACHABLE_OR_TIMEOUT';
+            }
+            const checkedAt = this.now();
+            entry.observation = { state, reason, checkedAt, lastSeen: state === 'online' ? checkedAt
+                    : entry.observation?.endpointFingerprint === target.fingerprint ? entry.observation.lastSeen : null,
+                latencyMs: state === 'online' ? Math.max(0, checkedAt - start) : null, endpointFingerprint: target.fingerprint };
+            return this.status(entry);
+        });
+    }
+    async select(capability, kind) {
+        if (!identifier.safeParse(capability).success)
+            throw new Error('INVALID_CAPABILITY');
+        const excluded = [];
+        const candidates = (await this.list()).filter(e => {
+            const reason = kind && e.resource.kind !== kind ? 'KIND_MISMATCH'
+                : !e.resource.declaredCapabilities.includes(capability) ? 'CAPABILITY_NOT_DECLARED'
+                    : !e.resource.permissions.use ? 'USE_NOT_PERMITTED'
+                        : e.state !== 'online' ? e.reason : null;
+            if (reason)
+                excluded.push({ id: e.resource.id, reason });
+            return !reason;
+        });
+        // Load unknown: do not fabricate free capacity. Stable deterministic latency/id choice only.
+        candidates.sort((a, b) => (a.observation?.latencyMs ?? Infinity) - (b.observation?.latencyMs ?? Infinity)
+            || a.resource.id.localeCompare(b.resource.id));
+        return { selected: candidates[0] ?? null, excluded,
+            reason: candidates.length ? 'FRESH_HEALTH_DECLARED_CAPABILITY_LOAD_UNKNOWN' : 'NO_ELIGIBLE_RESOURCE' };
+    }
+}
+//# sourceMappingURL=resource-catalog.js.map