forkit-ai-footprints 0.2.0

package/dist/providers/ollama.js

@@ -0,0 +1,171 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OllamaProvider = void 0;
+const endpoints_1 = require("../endpoints");
+const hash_1 = require("../hash");
+const runtime_identity_1 = require("../runtime-identity");
+const base_1 = require("./base");
+function parseSha256(value) {
+    if (!value)
+        return null;
+    const match = /^(?:sha256:)?([0-9a-f]{64})$/i.exec(value);
+    return match?.[1]?.toLowerCase() ?? null;
+}
+function validOllamaVersion(value) {
+    const body = (0, base_1.readRecord)(value);
+    const version = (0, base_1.readString)(body?.version);
+    return version !== null && /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(version);
+}
+function validModelArray(value) {
+    const body = (0, base_1.readRecord)(value);
+    return body !== null && Array.isArray(body.models) ? body.models : null;
+}
+class OllamaProvider {
+    fetchImpl;
+    verifyIdentity;
+    name = 'ollama';
+    endpoint;
+    detailsCache = new Map();
+    constructor(endpoint = 'http://localhost:11434', fetchImpl = fetch, verifyIdentity = runtime_identity_1.verifyMacosLoopbackRuntimeIdentity) {
+        this.fetchImpl = fetchImpl;
+        this.verifyIdentity = verifyIdentity;
+        const safeEndpoint = (0, endpoints_1.parseLoopbackEndpoint)(endpoint);
+        if (!safeEndpoint)
+            throw new Error('Ollama endpoint must be loopback HTTP(S).');
+        this.endpoint = safeEndpoint;
+    }
+    async scan(observedAt) {
+        if (!await this.verifyIdentity(this.endpoint.url, 'ollama')) {
+            return {
+                runtime: (0, base_1.createRuntime)({
+                    name: this.name,
+                    endpoint: this.endpoint.display,
+                    status: 'unavailable',
+                    modelCount: 0,
+                    observedAt,
+                    errorCode: 'runtime_identity_unverified',
+                }),
+                models: [],
+                warnings: [{
+                        code: 'runtime_identity_unverified',
+                        message: 'A loopback response could not be tied to the supported Ollama executable.',
+                        scope: 'runtime',
+                    }],
+            };
+        }
+        const [version, tags, running] = await Promise.all([
+            (0, base_1.fetchJson)(`${this.endpoint.url}/api/version`, { method: 'GET' }, this.fetchImpl),
+            (0, base_1.fetchJson)(`${this.endpoint.url}/api/tags`, { method: 'GET' }, this.fetchImpl),
+            (0, base_1.fetchJson)(`${this.endpoint.url}/api/ps`, { method: 'GET' }, this.fetchImpl),
+        ]);
+        const tagEntries = tags.ok ? validModelArray(tags.body) : null;
+        if (!version.ok || !validOllamaVersion(version.body) || tagEntries === null) {
+            return {
+                runtime: (0, base_1.createRuntime)({
+                    name: this.name,
+                    endpoint: this.endpoint.display,
+                    status: 'unavailable',
+                    modelCount: 0,
+                    observedAt,
+                    errorCode: !version.ok ? version.error : !tags.ok ? tags.error : 'invalid_ollama_api_shape',
+                }),
+                models: [],
+                warnings: [{
+                        code: 'ollama_api_unverified',
+                        message: 'The listener owner matched Ollama, but its version or inventory response was not valid.',
+                        scope: 'runtime',
+                    }],
+            };
+        }
+        const validatedRunning = running.ok ? validModelArray(running.body) : null;
+        const runningEntries = validatedRunning ?? [];
+        const runningNames = new Set(runningEntries.flatMap((value) => {
+            const entry = (0, base_1.readRecord)(value);
+            const name = (0, base_1.readString)(entry?.name) ?? (0, base_1.readString)(entry?.model);
+            return name ? [name.toLowerCase()] : [];
+        }));
+        const entries = tagEntries;
+        const models = await Promise.all(entries.map(async (entryValue) => {
+            const entry = (0, base_1.readRecord)(entryValue);
+            const name = (0, base_1.readString)(entry?.name) ?? (0, base_1.readString)(entry?.model);
+            if (!name)
+                return null;
+            const manifestDigest = parseSha256((0, base_1.readString)(entry?.digest));
+            const cacheKey = manifestDigest ?? name.toLowerCase();
+            let detailsValue = this.detailsCache.get(cacheKey);
+            if (detailsValue === undefined) {
+                const detailsResult = await (0, base_1.fetchJson)(`${this.endpoint.url}/api/show`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ model: name, verbose: false }),
+                }, this.fetchImpl, 4000);
+                if (detailsResult.ok) {
+                    detailsValue = detailsResult.body;
+                    this.detailsCache.set(cacheKey, detailsValue);
+                }
+            }
+            const detailsBody = (0, base_1.readRecord)(detailsValue);
+            const layers = (0, base_1.readArray)(detailsBody?.layers);
+            const modelLayer = layers
+                .map((layer) => (0, base_1.readRecord)(layer))
+                .find((layer) => (0, base_1.readString)(layer?.mediaType) === 'application/vnd.ollama.image.model');
+            const weightsDigest = parseSha256((0, base_1.readString)(modelLayer?.digest));
+            const details = (0, base_1.readRecord)(detailsBody?.details);
+            const contentIdentity = weightsDigest ?? manifestDigest;
+            const identity = contentIdentity ?? (0, hash_1.sha256)(`ollama:${name}`);
+            const model = (0, base_1.createModel)({
+                name,
+                runtime: this.name,
+                identityKind: contentIdentity ? 'content-sha256' : 'provider-id',
+                identity,
+                source: 'runtime-api',
+                confidence: contentIdentity ? 'high' : 'medium',
+                sizeBytes: (0, base_1.readNumber)(entry?.size),
+                modifiedAt: (0, base_1.readString)(entry?.modified_at),
+                quantization: (0, base_1.readString)(details?.quantization_level),
+                architecture: (0, base_1.readString)(details?.family),
+                parameterSize: (0, base_1.readString)(details?.parameter_size),
+            });
+            return {
+                ...model,
+                evidence_status: runningNames.has(name.toLowerCase()) ? 'confirmed-running' : 'discovered',
+            };
+        }));
+        const detectedModels = models.filter((model) => model !== null);
+        const detectedNames = new Set(detectedModels.map((model) => model.name.toLowerCase()));
+        for (const value of runningEntries) {
+            const entry = (0, base_1.readRecord)(value);
+            const name = (0, base_1.readString)(entry?.name) ?? (0, base_1.readString)(entry?.model);
+            if (!name || detectedNames.has(name.toLowerCase()))
+                continue;
+            const digest = parseSha256((0, base_1.readString)(entry?.digest));
+            const model = (0, base_1.createModel)({
+                name,
+                runtime: this.name,
+                identityKind: digest ? 'content-sha256' : 'provider-id',
+                identity: digest ?? (0, hash_1.sha256)(`ollama:${name}`),
+                source: 'runtime-api',
+                confidence: digest ? 'high' : 'medium',
+                sizeBytes: (0, base_1.readNumber)(entry?.size),
+            });
+            detectedModels.push({ ...model, evidence_status: 'confirmed-running' });
+        }
+        return {
+            runtime: (0, base_1.createRuntime)({
+                name: this.name,
+                endpoint: this.endpoint.display,
+                status: 'available',
+                modelCount: detectedModels.length,
+                observedAt,
+            }),
+            models: detectedModels,
+            warnings: validatedRunning !== null ? [] : [{
+                    code: 'ollama_running_state_unavailable',
+                    message: 'Ollama inventory was available, but confirmed loaded-model state could not be read.',
+                    scope: 'runtime',
+                }],
+        };
+    }
+}
+exports.OllamaProvider = OllamaProvider;
+//# sourceMappingURL=ollama.js.map

package/dist/providers/openai-compatible.d.ts

@@ -0,0 +1,10 @@
+import type { RuntimeProvider, RuntimeScanResult } from '../types';
+export declare class OpenAICompatibleProvider implements RuntimeProvider {
+    private readonly fetchImpl;
+    readonly name: "openai-compatible";
+    private readonly endpoint;
+    constructor(endpoint?: string, fetchImpl?: typeof fetch);
+    scan(observedAt: string): Promise<RuntimeScanResult>;
+}
+export declare function configuredOpenAICompatibleProviders(raw?: string, fetchImpl?: typeof fetch): OpenAICompatibleProvider[];
+//# sourceMappingURL=openai-compatible.d.ts.map

package/dist/providers/openai-compatible.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenAICompatibleProvider = void 0;
+exports.configuredOpenAICompatibleProviders = configuredOpenAICompatibleProviders;
+const endpoints_1 = require("../endpoints");
+const hash_1 = require("../hash");
+const base_1 = require("./base");
+class OpenAICompatibleProvider {
+    fetchImpl;
+    name = 'openai-compatible';
+    endpoint;
+    constructor(endpoint = 'http://localhost:8000', fetchImpl = fetch) {
+        this.fetchImpl = fetchImpl;
+        const safeEndpoint = (0, endpoints_1.parseLoopbackEndpoint)(endpoint);
+        if (!safeEndpoint)
+            throw new Error('OpenAI-compatible endpoint must be loopback HTTP(S).');
+        this.endpoint = safeEndpoint;
+    }
+    async scan(observedAt) {
+        const result = await (0, base_1.fetchJson)(`${this.endpoint.url}/v1/models`, { method: 'GET' }, this.fetchImpl);
+        if (!result.ok) {
+            return {
+                runtime: (0, base_1.createRuntime)({
+                    name: this.name,
+                    endpoint: this.endpoint.display,
+                    status: 'unavailable',
+                    modelCount: 0,
+                    observedAt,
+                    errorCode: result.error,
+                }),
+                models: [],
+                warnings: [],
+            };
+        }
+        const body = (0, base_1.readRecord)(result.body);
+        const models = (0, base_1.readArray)(body?.data).flatMap((value) => {
+            const entry = (0, base_1.readRecord)(value);
+            const name = (0, base_1.readString)(entry?.id);
+            if (!name)
+                return [];
+            return [(0, base_1.createModel)({
+                    name,
+                    runtime: this.name,
+                    identityKind: 'provider-id',
+                    identity: (0, hash_1.sha256)(`openai-compatible:${this.endpoint.id}:${name}`),
+                    source: 'runtime-api',
+                    confidence: 'medium',
+                })];
+        });
+        return {
+            runtime: (0, base_1.createRuntime)({
+                name: this.name,
+                endpoint: this.endpoint.display,
+                status: 'available',
+                modelCount: models.length,
+                observedAt,
+            }),
+            models,
+            warnings: [],
+        };
+    }
+}
+exports.OpenAICompatibleProvider = OpenAICompatibleProvider;
+function configuredOpenAICompatibleProviders(raw = process.env.FORKIT_CENSUS_OPENAI_ENDPOINTS ?? 'http://localhost:8000', fetchImpl = fetch) {
+    return (0, endpoints_1.parseLoopbackEndpointList)(raw)
+        .map((endpoint) => new OpenAICompatibleProvider(endpoint.url, fetchImpl));
+}
+//# sourceMappingURL=openai-compatible.js.map

package/dist/resource-evidence.d.ts

@@ -0,0 +1,17 @@
+export type ResourceEvidenceState = 'measured' | 'hardware-fact' | 'not-available';
+export type AttributionStrength = 'detected-process-window' | 'device' | 'none';
+export interface ResourceEvidenceCapability {
+    metric: 'cpu' | 'memory' | 'gpu' | 'hardware' | 'network_traffic';
+    state: ResourceEvidenceState;
+    attribution: AttributionStrength;
+    source: string;
+    exclusive_task_proof: false;
+    limitation: string;
+}
+export interface ResourceEvidenceManifest {
+    schema_version: '1.0';
+    platform: 'macos';
+    capabilities: ResourceEvidenceCapability[];
+}
+export declare function macosResourceEvidenceManifest(): ResourceEvidenceManifest;
+//# sourceMappingURL=resource-evidence.d.ts.map

package/dist/resource-evidence.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.macosResourceEvidenceManifest = macosResourceEvidenceManifest;
+function macosResourceEvidenceManifest() {
+    return {
+        schema_version: '1.0',
+        platform: 'macos',
+        capabilities: [
+            {
+                metric: 'cpu',
+                state: 'measured',
+                attribution: 'detected-process-window',
+                source: 'operating-system-process-sample',
+                exclusive_task_proof: false,
+                limitation: 'Detected process work is measured; concurrent background work inside the same process can be included.',
+            },
+            {
+                metric: 'memory',
+                state: 'measured',
+                attribution: 'detected-process-window',
+                source: 'operating-system-process-sample',
+                exclusive_task_proof: false,
+                limitation: 'Memory is shared and may persist across tasks; the window cannot prove which task owns every byte.',
+            },
+            {
+                metric: 'gpu',
+                state: 'not-available',
+                attribution: 'none',
+                source: 'no-supported-cross-process-proof-source',
+                exclusive_task_proof: false,
+                limitation: 'Metal counters can measure work submitted by an instrumented app, not arbitrary third-party AI process work as exclusive task proof.',
+            },
+            {
+                metric: 'hardware',
+                state: 'hardware-fact',
+                attribution: 'device',
+                source: 'operating-system-hardware-metadata',
+                exclusive_task_proof: false,
+                limitation: 'Hardware inventory identifies device capability; it does not prove task-specific utilization.',
+            },
+            {
+                metric: 'network_traffic',
+                state: 'not-available',
+                attribution: 'none',
+                source: 'no-supported-per-process-proof-source-integrated',
+                exclusive_task_proof: false,
+                limitation: 'The current release does not use privileged packet inspection or unsupported per-process network APIs.',
+            },
+        ],
+    };
+}
+//# sourceMappingURL=resource-evidence.js.map

package/dist/runtime-activity.d.ts

@@ -0,0 +1,5 @@
+import type { ClassifiedAgentProcess } from './agents';
+import type { ProcessEntry, RuntimeProvider } from './types';
+export declare function loadedRuntimeSignatures(providers: RuntimeProvider[], observedAt: string): Promise<Set<string>>;
+export declare function classifyLoadedRuntimeProcesses(processes: ProcessEntry[], loaded: Set<string>, excludedRootPid?: number | null): ClassifiedAgentProcess[];
+//# sourceMappingURL=runtime-activity.d.ts.map

package/dist/runtime-activity.js

@@ -0,0 +1,66 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadedRuntimeSignatures = loadedRuntimeSignatures;
+exports.classifyLoadedRuntimeProcesses = classifyLoadedRuntimeProcesses;
+const node_path_1 = __importDefault(require("node:path"));
+function basename(value) {
+    return node_path_1.default.basename(String(value || '').replaceAll('\\', '/')).toLowerCase().replace(/\.exe$/i, '');
+}
+async function loadedRuntimeSignatures(providers, observedAt) {
+    const loaded = new Set();
+    const results = await Promise.all(providers.map(async (provider) => {
+        try {
+            return await provider.scan(observedAt);
+        }
+        catch {
+            return null;
+        }
+    }));
+    for (const result of results) {
+        if (!result)
+            continue;
+        if (result.models.some((model) => model.evidence_status === 'confirmed-running'))
+            loaded.add(result.runtime.name);
+    }
+    return loaded;
+}
+function classifyLoadedRuntimeProcesses(processes, loaded, excludedRootPid = process.pid) {
+    const definitions = [
+        { signature: 'runtime:ollama', runtime: 'ollama', name: 'Ollama', executables: ['ollama'] },
+        { signature: 'runtime:lmstudio', runtime: 'lmstudio', name: 'LM Studio', executables: ['lm studio', 'lmstudio'] },
+    ];
+    const excluded = new Set();
+    if (excludedRootPid !== null) {
+        excluded.add(excludedRootPid);
+        let changed = true;
+        while (changed) {
+            changed = false;
+            for (const entry of processes)
+                if (!excluded.has(entry.pid) && entry.ppid !== undefined && excluded.has(entry.ppid)) {
+                    excluded.add(entry.pid);
+                    changed = true;
+                }
+        }
+    }
+    const result = [];
+    for (const entry of processes) {
+        if (excluded.has(entry.pid))
+            continue;
+        const executable = basename(entry.name || String(entry.cmd || '').split(/\s+/)[0] || '');
+        const definition = definitions.find((candidate) => loaded.has(candidate.runtime) && candidate.executables.includes(executable));
+        if (!definition)
+            continue;
+        result.push({
+            pid: entry.pid, ppid: entry.ppid ?? null, signature: definition.signature, name: definition.name,
+            kind: 'local-model-runtime', confidence: 'high', relationship: 'direct',
+            cpu_percent: Number.isFinite(entry.cpu_percent) ? Number(entry.cpu_percent) : null,
+            memory_percent: Number.isFinite(entry.memory_percent) ? Number(entry.memory_percent) : null,
+            cpu_time_ms: Number.isFinite(entry.cpu_time_ms) ? Number(entry.cpu_time_ms) : null,
+        });
+    }
+    return result;
+}
+//# sourceMappingURL=runtime-activity.js.map

package/dist/runtime-identity.d.ts

@@ -0,0 +1,7 @@
+export type RuntimeIdentityVerifier = (endpoint: string, expectedExecutable: string) => Promise<boolean>;
+/**
+ * Correlates a loopback listener with an exact executable name. Only the
+ * boolean result leaves this adapter; PID and executable path stay ephemeral.
+ */
+export declare const verifyMacosLoopbackRuntimeIdentity: RuntimeIdentityVerifier;
+//# sourceMappingURL=runtime-identity.d.ts.map

package/dist/runtime-identity.js

@@ -0,0 +1,66 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyMacosLoopbackRuntimeIdentity = void 0;
+const node_path_1 = __importDefault(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const node_util_1 = require("node:util");
+const execFileAsync = (0, node_util_1.promisify)(node_child_process_1.execFile);
+function exactBasename(value) {
+    return node_path_1.default.basename(value.trim()).toLowerCase();
+}
+/**
+ * Correlates a loopback listener with an exact executable name. Only the
+ * boolean result leaves this adapter; PID and executable path stay ephemeral.
+ */
+const verifyMacosLoopbackRuntimeIdentity = async (endpoint, expectedExecutable) => {
+    if (process.platform !== 'darwin')
+        return false;
+    let parsed;
+    try {
+        parsed = new URL(endpoint);
+    }
+    catch {
+        return false;
+    }
+    const port = Number(parsed.port || (parsed.protocol === 'https:' ? 443 : 80));
+    if (!Number.isSafeInteger(port) || port < 1 || port > 65535)
+        return false;
+    try {
+        const { stdout } = await execFileAsync('lsof', [
+            '-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-Fpc',
+        ], {
+            encoding: 'utf8',
+            maxBuffer: 1_000_000,
+            env: { ...process.env, LC_ALL: 'C', LANG: 'C' },
+        });
+        let currentPid = null;
+        const candidates = [];
+        for (const line of stdout.split('\n')) {
+            if (line.startsWith('p'))
+                currentPid = Number(line.slice(1));
+            else if (line.startsWith('c') && currentPid !== null
+                && exactBasename(line.slice(1)) === expectedExecutable.toLowerCase())
+                candidates.push(currentPid);
+        }
+        for (const pid of candidates) {
+            if (!Number.isSafeInteger(pid) || pid < 1)
+                continue;
+            const { stdout: command } = await execFileAsync('ps', ['-p', String(pid), '-o', 'comm='], {
+                encoding: 'utf8',
+                maxBuffer: 64_000,
+                env: { ...process.env, LC_ALL: 'C', LANG: 'C' },
+            });
+            if (exactBasename(command) === expectedExecutable.toLowerCase())
+                return true;
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+};
+exports.verifyMacosLoopbackRuntimeIdentity = verifyMacosLoopbackRuntimeIdentity;
+//# sourceMappingURL=runtime-identity.js.map

package/dist/server.d.ts

@@ -0,0 +1,21 @@
+import http from 'node:http';
+import { type LocalDeviceJournal } from './local-device';
+import { ActivityMonitor } from './monitor';
+import type { CensusReport } from './types';
+export interface AiFootprintsServerOptions {
+    hostname?: '127.0.0.1';
+    port?: number;
+    scan?: () => Promise<CensusReport>;
+    recordScan?: (generatedAt: string) => Promise<LocalDeviceJournal>;
+    monitor?: ActivityMonitor;
+    nativeToken?: string | null;
+}
+export interface AiFootprintsServer {
+    server: http.Server;
+    url: string;
+    sessionToken: string;
+    monitor: ActivityMonitor;
+    close: () => Promise<void>;
+}
+export declare function startAiFootprintsServer(options?: AiFootprintsServerOptions): Promise<AiFootprintsServer>;
+//# sourceMappingURL=server.d.ts.map