forkit-ai-footprints 0.2.0

package/dist/monitor.js

@@ -0,0 +1,285 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActivityMonitor = void 0;
+const agents_1 = require("./agents");
+const DEFAULT_INTERVAL_MS = 1000;
+const DEFAULT_HISTORY_LIMIT = 900;
+function rounded(value, digits = 1) {
+    const factor = 10 ** digits;
+    return Math.round(value * factor) / factor;
+}
+function sum(values) {
+    const measured = values.filter((value) => value !== null);
+    return measured.length === 0 ? null : rounded(measured.reduce((total, value) => total + value, 0));
+}
+function percentile(values, fraction) {
+    if (values.length === 0)
+        return null;
+    const sorted = [...values].sort((left, right) => left - right);
+    const index = Math.min(sorted.length - 1, Math.max(0, Math.ceil(sorted.length * fraction) - 1));
+    return rounded(sorted[index]);
+}
+function localContextFromEnvironment() {
+    const chat = process.env.FORKIT_AI_FOOTPRINTS_CONTEXT_CHAT?.trim() || null;
+    const workspace = process.env.FORKIT_AI_FOOTPRINTS_CONTEXT_WORKSPACE?.trim() || null;
+    return {
+        chat,
+        workspace,
+        source: chat || workspace ? 'cooperating-app-metadata' : null,
+    };
+}
+function groupProcesses(processes) {
+    const result = new Map();
+    for (const entry of processes)
+        result.set(entry.signature, [...(result.get(entry.signature) ?? []), entry]);
+    return result;
+}
+function historyByteSize(snapshot) {
+    return Buffer.byteLength(JSON.stringify({
+        started_at: snapshot.started_at,
+        observed_seconds: snapshot.observed_seconds,
+        active_seconds: snapshot.active_seconds,
+        products: snapshot.products,
+        timeline: snapshot.timeline,
+    }));
+}
+class ActivityMonitor {
+    sampleProcesses;
+    now;
+    intervalMs;
+    historyLimit;
+    excludedRootPid;
+    context;
+    classifyProcesses;
+    lifecycle = 'stopped';
+    startedAt = null;
+    stoppedAt = null;
+    previousAt = null;
+    observationId = 0;
+    previousCpuTimes = new Map();
+    observedMs = 0;
+    activeMs = 0;
+    products = new Map();
+    timeline = [];
+    timer = null;
+    sampling = false;
+    nodeCpuUsage = null;
+    nodeCpuAt = null;
+    overheadCpuSamples = [];
+    overheadMemorySamples = [];
+    constructor(options = {}) {
+        this.sampleProcesses = options.sampleProcesses ?? agents_1.listSystemProcesses;
+        this.now = options.now ?? Date.now;
+        this.intervalMs = Math.max(500, options.intervalMs ?? DEFAULT_INTERVAL_MS);
+        this.historyLimit = Math.max(10, options.historyLimit ?? DEFAULT_HISTORY_LIMIT);
+        this.excludedRootPid = options.excludedRootPid === undefined ? process.pid : options.excludedRootPid;
+        this.context = options.context ?? localContextFromEnvironment;
+        this.classifyProcesses = options.classifyProcesses ?? ((entries) => (0, agents_1.classifyAgentProcessTrees)(entries, this.excludedRootPid));
+    }
+    async start(options = {}) {
+        if (this.lifecycle === 'monitoring')
+            return this.snapshot();
+        const now = this.now();
+        this.lifecycle = 'monitoring';
+        this.observationId += 1;
+        this.startedAt = now;
+        this.stoppedAt = null;
+        this.previousAt = null;
+        this.previousCpuTimes.clear();
+        this.nodeCpuUsage = process.cpuUsage();
+        this.nodeCpuAt = now;
+        await this.sampleNow();
+        if (options.schedule !== false) {
+            this.timer = setInterval(() => { void this.sampleNow(); }, this.intervalMs);
+            this.timer.unref();
+        }
+        return this.snapshot();
+    }
+    async sampleNow() {
+        if (this.lifecycle !== 'monitoring' || this.sampling)
+            return this.snapshot();
+        this.sampling = true;
+        try {
+            const entries = await this.sampleProcesses();
+            const now = this.now();
+            const elapsed = this.previousAt === null ? 0 : Math.max(0, now - this.previousAt);
+            const validElapsed = elapsed > 0 && elapsed <= this.intervalMs * 3 ? elapsed : 0;
+            const grouped = groupProcesses(await this.classifyProcesses(entries));
+            const signatures = new Set([...this.products.keys(), ...grouped.keys()]);
+            for (const signature of signatures) {
+                const current = grouped.get(signature) ?? [];
+                const previous = this.products.get(signature);
+                let cpuDeltaMs = 0;
+                let deltaCount = 0;
+                for (const entry of current) {
+                    const currentTime = entry.cpu_time_ms;
+                    const previousTime = this.previousCpuTimes.get(entry.pid);
+                    if (currentTime === null || previousTime === undefined || currentTime < previousTime)
+                        continue;
+                    cpuDeltaMs += currentTime - previousTime;
+                    deltaCount += 1;
+                }
+                const measuredDelta = deltaCount > 0 ? cpuDeltaMs : null;
+                const strongSignal = current.length > 0
+                    && validElapsed > 0
+                    && measuredDelta !== null
+                    && measuredDelta >= Math.max(20, validElapsed * 0.02);
+                const signals = [...(previous?.signals ?? []), strongSignal].slice(-3);
+                let state;
+                if (current.length === 0)
+                    state = 'not-running';
+                else if (previous?.state === 'working-now')
+                    state = signals.every((value) => !value) ? 'open-idle' : 'working-now';
+                else
+                    state = signals.slice(-2).length === 2 && signals.slice(-2).every(Boolean) ? 'working-now' : 'open-idle';
+                const activeMs = (previous?.activeMs ?? 0) + (validElapsed > 0 && state === 'working-now' ? validElapsed : 0);
+                const first = current[0];
+                this.products.set(signature, {
+                    signature,
+                    name: first?.name ?? previous?.name ?? signature,
+                    kind: first?.kind ?? previous?.kind ?? 'unknown',
+                    state,
+                    signals,
+                    activeMs,
+                    processCount: current.length,
+                    cpuPercent: sum(current.map((entry) => entry.cpu_percent)),
+                    memoryPercent: sum(current.map((entry) => entry.memory_percent)),
+                    cpuDeltaMs: measuredDelta,
+                });
+            }
+            if (validElapsed > 0) {
+                this.observedMs += validElapsed;
+                if ([...this.products.values()].some((product) => product.state === 'working-now'))
+                    this.activeMs += validElapsed;
+            }
+            this.updateTimeline(now);
+            this.previousCpuTimes = new Map(entries.flatMap((entry) => Number.isFinite(entry.cpu_time_ms)
+                ? [[entry.pid, Number(entry.cpu_time_ms)]]
+                : []));
+            this.previousAt = now;
+            this.sampleOverhead(now, entries);
+            return this.snapshot();
+        }
+        finally {
+            this.sampling = false;
+        }
+    }
+    stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+        if (this.lifecycle === 'monitoring')
+            this.stoppedAt = this.now();
+        this.lifecycle = 'stopped';
+        return this.snapshot();
+    }
+    clearHistory() {
+        const now = this.now();
+        this.startedAt = this.lifecycle === 'monitoring' ? now : null;
+        this.stoppedAt = null;
+        this.previousAt = null;
+        this.previousCpuTimes.clear();
+        this.observedMs = 0;
+        this.activeMs = 0;
+        this.products.clear();
+        this.timeline = [];
+        this.overheadCpuSamples = [];
+        this.overheadMemorySamples = [];
+        this.nodeCpuUsage = process.cpuUsage();
+        this.nodeCpuAt = now;
+        return this.snapshot();
+    }
+    updateTimeline(now) {
+        const working = [...this.products.values()].filter((product) => product.state === 'working-now');
+        const running = [...this.products.values()].filter((product) => product.state !== 'not-running');
+        const state = working.length > 0
+            ? 'working-now'
+            : running.length > 0 ? 'open-idle' : 'not-running';
+        const signatures = (working.length > 0 ? working : running).map((product) => product.signature).sort();
+        const at = new Date(now).toISOString();
+        const latest = this.timeline.at(-1);
+        if (latest && latest.observation_id === this.observationId && latest.state === state && latest.product_signatures.join('|') === signatures.join('|'))
+            latest.ended_at = at;
+        else
+            this.timeline.push({ started_at: at, ended_at: at, state, product_signatures: signatures, observation_id: this.observationId });
+        if (this.timeline.length > this.historyLimit)
+            this.timeline.splice(0, this.timeline.length - this.historyLimit);
+    }
+    sampleOverhead(now, entries) {
+        const included = new Set([process.pid]);
+        if (process.env.FORKIT_AI_FOOTPRINTS_APP_BUNDLE === '1' && process.ppid > 1)
+            included.add(process.ppid);
+        let changed = true;
+        while (changed) {
+            changed = false;
+            for (const entry of entries) {
+                if (included.has(entry.pid) || entry.ppid === undefined || !included.has(entry.ppid))
+                    continue;
+                included.add(entry.pid);
+                changed = true;
+            }
+        }
+        const ownEntries = entries.filter((entry) => included.has(entry.pid));
+        const measuredMemory = ownEntries.reduce((total, entry) => total + (Number.isFinite(entry.rss_bytes) ? Number(entry.rss_bytes) : 0), 0);
+        const memory = measuredMemory > 0 ? measuredMemory : process.memoryUsage().rss;
+        this.overheadMemorySamples.push(memory);
+        if (this.overheadMemorySamples.length > this.historyLimit)
+            this.overheadMemorySamples.shift();
+        if (this.nodeCpuUsage && this.nodeCpuAt !== null && now - this.nodeCpuAt >= this.intervalMs * 0.5) {
+            const usage = process.cpuUsage(this.nodeCpuUsage);
+            const nodeCpu = ((usage.user + usage.system) / ((now - this.nodeCpuAt) * 1000)) * 100;
+            const measuredTreeCpu = ownEntries.reduce((total, entry) => total + (Number.isFinite(entry.cpu_percent) ? Number(entry.cpu_percent) : 0), 0);
+            const cpu = process.env.FORKIT_AI_FOOTPRINTS_APP_BUNDLE === '1' && measuredTreeCpu > 0 ? measuredTreeCpu : nodeCpu;
+            this.overheadCpuSamples.push(rounded(Math.max(0, cpu)));
+            if (this.overheadCpuSamples.length > this.historyLimit)
+                this.overheadCpuSamples.shift();
+        }
+        this.nodeCpuUsage = process.cpuUsage();
+        this.nodeCpuAt = now;
+    }
+    snapshot() {
+        const products = [...this.products.values()].map((product) => ({
+            signature: product.signature,
+            name: product.name,
+            kind: product.kind,
+            state: product.state,
+            process_count: product.processCount,
+            cpu_percent: product.cpuPercent,
+            memory_percent: product.memoryPercent,
+            recent_cpu_time_delta_ms: product.cpuDeltaMs,
+            active_seconds: rounded(product.activeMs / 1000),
+            context: this.context(),
+        })).sort((left, right) => left.name.localeCompare(right.name));
+        const base = {
+            schema_version: '1.0',
+            lifecycle: this.lifecycle,
+            started_at: this.startedAt === null ? null : new Date(this.startedAt).toISOString(),
+            stopped_at: this.stoppedAt === null ? null : new Date(this.stoppedAt).toISOString(),
+            observed_seconds: rounded(this.observedMs / 1000),
+            active_seconds: rounded(this.activeMs / 1000),
+            activity_ratio: this.observedMs > 0 ? rounded(this.activeMs / this.observedMs, 3) : null,
+            products,
+            timeline: this.timeline.map((segment) => ({ ...segment, product_signatures: [...segment.product_signatures] })),
+            sample_interval_ms: this.intervalMs,
+            history_limit: this.historyLimit,
+            evidence: 'repeated-process-tree-cpu-time-deltas',
+            limitation: 'Working now means sustained recent work in a supported app process tree; it is not prompt, task, token, energy, or cost attribution.',
+        };
+        const memory = this.overheadMemorySamples.at(-1) ?? process.memoryUsage().rss;
+        return {
+            ...base,
+            overhead: {
+                current_cpu_percent: this.overheadCpuSamples.at(-1) ?? null,
+                current_memory_bytes: memory,
+                history_bytes: historyByteSize(base),
+                sample_count: this.overheadCpuSamples.length,
+                median_cpu_percent: percentile(this.overheadCpuSamples, 0.5),
+                p95_cpu_percent: percentile(this.overheadCpuSamples, 0.95),
+                max_memory_bytes: Math.max(memory, ...this.overheadMemorySamples),
+                measurement: 'forkit-process-tree',
+            },
+        };
+    }
+}
+exports.ActivityMonitor = ActivityMonitor;
+//# sourceMappingURL=monitor.js.map

package/dist/providers/base.d.ts

@@ -0,0 +1,34 @@
+import type { CensusModel, CensusRuntime, Confidence, RuntimeKind, RuntimeStatus } from '../types';
+export declare function fetchJson(url: string, init: RequestInit, fetchImpl: typeof fetch, timeoutMs?: number): Promise<{
+    ok: boolean;
+    status: number;
+    body: unknown;
+    error: string | null;
+}>;
+export declare function createRuntime(input: {
+    name: RuntimeKind;
+    endpoint: string | null;
+    status: RuntimeStatus;
+    modelCount: number;
+    observedAt: string;
+    errorCode?: string | null;
+}): CensusRuntime;
+export declare function createModel(input: {
+    name: string;
+    runtime: RuntimeKind;
+    identityKind: CensusModel['identity_kind'];
+    identity: string;
+    source: CensusModel['source'];
+    confidence: Confidence;
+    sizeBytes?: number | null;
+    modifiedAt?: string | null;
+    quantization?: string | null;
+    architecture?: string | null;
+    parameterSize?: string | null;
+    locationHint?: string | null;
+}): CensusModel;
+export declare function readRecord(value: unknown): Record<string, unknown> | null;
+export declare function readArray(value: unknown): unknown[];
+export declare function readString(value: unknown): string | null;
+export declare function readNumber(value: unknown): number | null;
+//# sourceMappingURL=base.d.ts.map

package/dist/providers/base.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchJson = fetchJson;
+exports.createRuntime = createRuntime;
+exports.createModel = createModel;
+exports.readRecord = readRecord;
+exports.readArray = readArray;
+exports.readString = readString;
+exports.readNumber = readNumber;
+const hash_1 = require("../hash");
+async function fetchJson(url, init, fetchImpl, timeoutMs = 3000) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetchImpl(url, { ...init, signal: controller.signal });
+        let body = null;
+        try {
+            body = await response.json();
+        }
+        catch {
+            body = null;
+        }
+        return {
+            ok: response.ok,
+            status: response.status,
+            body,
+            error: response.ok ? null : `http_${response.status}`,
+        };
+    }
+    catch (error) {
+        const code = error instanceof Error && error.name === 'AbortError'
+            ? 'timeout'
+            : 'connection_unavailable';
+        return { ok: false, status: 0, body: null, error: code };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function createRuntime(input) {
+    return {
+        runtime_id: (0, hash_1.stableId)('runtime', `${input.name}:${input.endpoint ?? 'local-inventory'}`),
+        name: input.name,
+        status: input.status,
+        endpoint: input.endpoint,
+        model_count: input.modelCount,
+        observed_at: input.observedAt,
+        error_code: input.errorCode ?? null,
+        evidence_status: input.status === 'available'
+            ? 'online'
+            : input.status === 'inventory-only'
+                ? 'configured'
+                : 'unavailable',
+    };
+}
+function createModel(input) {
+    return {
+        model_id: (0, hash_1.stableId)('model', `${input.runtime}:${input.name}:${input.identity}`),
+        name: input.name,
+        runtime: input.runtime,
+        identity_kind: input.identityKind,
+        identity: input.identity,
+        size_bytes: input.sizeBytes ?? null,
+        modified_at: input.modifiedAt ?? null,
+        quantization: input.quantization ?? null,
+        architecture: input.architecture ?? null,
+        parameter_size: input.parameterSize ?? null,
+        source: input.source,
+        location_hint: input.locationHint ?? null,
+        confidence: input.confidence,
+        evidence_status: 'discovered',
+    };
+}
+function readRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function readArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function readString(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+function readNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+//# sourceMappingURL=base.js.map

package/dist/providers/index.d.ts

@@ -0,0 +1,6 @@
+import type { RuntimeProvider } from '../types';
+export { LMStudioProvider } from './lmstudio';
+export { OllamaProvider } from './ollama';
+export { OpenAICompatibleProvider, configuredOpenAICompatibleProviders } from './openai-compatible';
+export declare function createDefaultProviders(fetchImpl?: typeof fetch): RuntimeProvider[];
+//# sourceMappingURL=index.d.ts.map

package/dist/providers/index.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configuredOpenAICompatibleProviders = exports.OpenAICompatibleProvider = exports.OllamaProvider = exports.LMStudioProvider = void 0;
+exports.createDefaultProviders = createDefaultProviders;
+const lmstudio_1 = require("./lmstudio");
+const ollama_1 = require("./ollama");
+const openai_compatible_1 = require("./openai-compatible");
+var lmstudio_2 = require("./lmstudio");
+Object.defineProperty(exports, "LMStudioProvider", { enumerable: true, get: function () { return lmstudio_2.LMStudioProvider; } });
+var ollama_2 = require("./ollama");
+Object.defineProperty(exports, "OllamaProvider", { enumerable: true, get: function () { return ollama_2.OllamaProvider; } });
+var openai_compatible_2 = require("./openai-compatible");
+Object.defineProperty(exports, "OpenAICompatibleProvider", { enumerable: true, get: function () { return openai_compatible_2.OpenAICompatibleProvider; } });
+Object.defineProperty(exports, "configuredOpenAICompatibleProviders", { enumerable: true, get: function () { return openai_compatible_2.configuredOpenAICompatibleProviders; } });
+function createDefaultProviders(fetchImpl = fetch) {
+    if (process.env.FORKIT_CENSUS_DISABLE_DEFAULT_RUNTIMES === '1')
+        return [];
+    return [
+        new ollama_1.OllamaProvider('http://localhost:11434', fetchImpl),
+        new lmstudio_1.LMStudioProvider('http://localhost:1234', fetchImpl),
+        ...(0, openai_compatible_1.configuredOpenAICompatibleProviders)(process.env.FORKIT_CENSUS_OPENAI_ENDPOINTS ?? 'http://localhost:8000', fetchImpl),
+    ];
+}
+//# sourceMappingURL=index.js.map

package/dist/providers/lmstudio.d.ts

@@ -0,0 +1,9 @@
+import type { RuntimeProvider, RuntimeScanResult } from '../types';
+export declare class LMStudioProvider implements RuntimeProvider {
+    private readonly fetchImpl;
+    readonly name: "lmstudio";
+    private readonly endpoint;
+    constructor(endpoint?: string, fetchImpl?: typeof fetch);
+    scan(observedAt: string): Promise<RuntimeScanResult>;
+}
+//# sourceMappingURL=lmstudio.d.ts.map

package/dist/providers/lmstudio.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LMStudioProvider = void 0;
+const endpoints_1 = require("../endpoints");
+const hash_1 = require("../hash");
+const base_1 = require("./base");
+class LMStudioProvider {
+    fetchImpl;
+    name = 'lmstudio';
+    endpoint;
+    constructor(endpoint = 'http://localhost:1234', fetchImpl = fetch) {
+        this.fetchImpl = fetchImpl;
+        const safeEndpoint = (0, endpoints_1.parseLoopbackEndpoint)(endpoint);
+        if (!safeEndpoint)
+            throw new Error('LM Studio endpoint must be loopback HTTP(S).');
+        this.endpoint = safeEndpoint;
+    }
+    async scan(observedAt) {
+        const v0 = await (0, base_1.fetchJson)(`${this.endpoint.url}/api/v0/models`, { method: 'GET' }, this.fetchImpl);
+        const result = v0.ok
+            ? v0
+            : 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)(`lmstudio:${name}`),
+                    source: 'runtime-api',
+                    confidence: 'medium',
+                    quantization: (0, base_1.readString)(entry?.quantization),
+                    architecture: (0, base_1.readString)(entry?.arch),
+                    parameterSize: (0, base_1.readNumber)(entry?.parameter_size) === null
+                        ? (0, base_1.readString)(entry?.parameter_size)
+                        : String((0, base_1.readNumber)(entry?.parameter_size)),
+                })];
+        });
+        return {
+            runtime: (0, base_1.createRuntime)({
+                name: this.name,
+                endpoint: this.endpoint.display,
+                status: 'available',
+                modelCount: models.length,
+                observedAt,
+            }),
+            models,
+            warnings: [],
+        };
+    }
+}
+exports.LMStudioProvider = LMStudioProvider;
+//# sourceMappingURL=lmstudio.js.map

package/dist/providers/ollama.d.ts

@@ -0,0 +1,12 @@
+import { type RuntimeIdentityVerifier } from '../runtime-identity';
+import type { RuntimeProvider, RuntimeScanResult } from '../types';
+export declare class OllamaProvider implements RuntimeProvider {
+    private readonly fetchImpl;
+    private readonly verifyIdentity;
+    readonly name: "ollama";
+    private readonly endpoint;
+    private readonly detailsCache;
+    constructor(endpoint?: string, fetchImpl?: typeof fetch, verifyIdentity?: RuntimeIdentityVerifier);
+    scan(observedAt: string): Promise<RuntimeScanResult>;
+}
+//# sourceMappingURL=ollama.d.ts.map