forkit-connect 0.1.0

package/dist/v1/heartbeat.js

@@ -0,0 +1,463 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readBoundModelName = readBoundModelName;
+exports.listBoundBindings = listBoundBindings;
+exports.selectBoundBinding = selectBoundBinding;
+exports.sendAllBoundHeartbeats = sendAllBoundHeartbeats;
+exports.sendBoundHeartbeat = sendBoundHeartbeat;
+const api_1 = require("./api");
+const discovery_1 = require("./discovery");
+const DEFAULT_BASE_URL = process.env.FORKIT_API_URL ?? process.env.FORKIT_BASE_URL ?? 'https://www.forkit.dev';
+function isDeploymentCheckinResponse(body) {
+    return !!body && typeof body === 'object';
+}
+function readBackendCode(body) {
+    if (!body || typeof body !== 'object' || Array.isArray(body))
+        return null;
+    const code = body.code;
+    return typeof code === 'string' && code.trim() ? code : null;
+}
+function isConnectBindingFailureCode(code) {
+    return typeof code === 'string' && code.startsWith('CONNECT_BINDING_');
+}
+function buildRuntimeSyncBindingFailure(service, backendCode, status, details) {
+    const runtimeSyncStatus = service.getBindingActionStatus('runtime_session_sync');
+    switch (runtimeSyncStatus.reasonCode) {
+        case 'binding_revoked':
+            return {
+                ok: false,
+                code: 'credential_reconnect_needed',
+                message: 'Device revoked. Reconnect Forkit Connect to continue.',
+                status,
+                details,
+            };
+        case 'binding_paused':
+            return {
+                ok: false,
+                code: 'binding_paused',
+                message: 'Sync paused. Local observations continue, but runtime sync is held.',
+                status,
+                details,
+            };
+        case 'binding_stale':
+            return {
+                ok: false,
+                code: 'binding_stale',
+                message: 'Connection stale. Runtime sync is held until Connect refreshes the binding.',
+                status,
+                details,
+            };
+        case 'binding_reconsent_required':
+            return {
+                ok: false,
+                code: 'binding_reconsent_required',
+                message: 'Consent update required before runtime sync can continue.',
+                status,
+                details,
+            };
+        case 'binding_missing':
+        case 'binding_scope_required':
+            return {
+                ok: false,
+                code: 'missing_binding',
+                message: runtimeSyncStatus.message,
+                status,
+                details,
+            };
+        default:
+            if (backendCode === 'CONNECT_BINDING_REVOKED') {
+                return {
+                    ok: false,
+                    code: 'credential_reconnect_needed',
+                    message: 'Device revoked. Reconnect Forkit Connect to continue.',
+                    status,
+                    details,
+                };
+            }
+            if (backendCode === 'CONNECT_BINDING_PAUSED') {
+                return {
+                    ok: false,
+                    code: 'binding_paused',
+                    message: 'Sync paused. Local observations continue, but runtime sync is held.',
+                    status,
+                    details,
+                };
+            }
+            if (backendCode === 'CONNECT_BINDING_STALE' || backendCode === 'CONNECT_BINDING_NOT_ACTIVE') {
+                return {
+                    ok: false,
+                    code: 'binding_stale',
+                    message: 'Connection stale. Runtime sync is held until Connect refreshes the binding.',
+                    status,
+                    details,
+                };
+            }
+            if (backendCode === 'CONNECT_BINDING_RECONSENT_REQUIRED' || backendCode === 'CONNECT_BINDING_CONSENT_REQUIRED') {
+                return {
+                    ok: false,
+                    code: 'binding_reconsent_required',
+                    message: 'Consent update required before runtime sync can continue.',
+                    status,
+                    details,
+                };
+            }
+            return {
+                ok: false,
+                code: 'missing_binding',
+                message: 'Runtime sync is waiting for an active Forkit.dev workspace and project binding.',
+                status,
+                details,
+            };
+    }
+}
+function normalizeHeartbeatSessionMode(runtimeMode, revokedAt) {
+    if (revokedAt)
+        return 'revoked';
+    switch (String(runtimeMode || '').trim().toLowerCase()) {
+        case 'paused':
+            return 'paused';
+        case 'standby':
+        case 'draining':
+            return 'standby';
+        case 'sleeping':
+            return 'sleeping';
+        case 'offline':
+            return 'offline';
+        case 'revoked':
+            return 'revoked';
+        default:
+            return 'active';
+    }
+}
+function readBoundModelName(modelKey) {
+    const [name] = String(modelKey || '').split('#');
+    return name?.trim() || 'unknown';
+}
+function listBoundBindings(state) {
+    if (!Array.isArray(state.model_bindings)) {
+        return [];
+    }
+    return state.model_bindings
+        .filter((item) => item.status === 'bound' && typeof item.gaid === 'string' && item.gaid.trim())
+        .sort((left, right) => String(right.updatedAt || '').localeCompare(String(left.updatedAt || '')))
+        .map((binding) => ({
+        binding,
+        detectedModel: state.detected_models.find((item) => `${item.model}#${item.digest}` === binding.modelKey),
+    }));
+}
+function selectBoundBinding(state) {
+    return listBoundBindings(state)[0] ?? null;
+}
+function buildSessionId(state, gaid) {
+    return `connect:${state.runtime_identity.runtimeId}:${String(gaid).slice(0, 32)}`;
+}
+async function sendHeartbeatForSelection(service, selected, options) {
+    const state = service.getStateStore().readState();
+    const storedSessionRef = String(service.readSessionRef() || '').trim();
+    const effectiveBinding = service.getEffectiveBinding();
+    const runtimeScope = service.getActionScope('runtime_session_sync', state);
+    const runtimeSyncStatus = service.getBindingActionStatus('runtime_session_sync');
+    if (!storedSessionRef) {
+        return {
+            ok: false,
+            code: 'not_authenticated',
+            message: 'Not authenticated. Run forkit-connect login first.',
+        };
+    }
+    if (!runtimeSyncStatus.allowed) {
+        if (runtimeSyncStatus.reasonCode === 'binding_revoked') {
+            return {
+                ok: false,
+                code: 'credential_reconnect_needed',
+                message: runtimeSyncStatus.message,
+            };
+        }
+        if (runtimeSyncStatus.reasonCode === 'binding_paused') {
+            return {
+                ok: false,
+                code: 'binding_paused',
+                message: runtimeSyncStatus.message,
+            };
+        }
+        if (runtimeSyncStatus.reasonCode === 'binding_stale') {
+            return {
+                ok: false,
+                code: 'binding_stale',
+                message: runtimeSyncStatus.message,
+            };
+        }
+        if (runtimeSyncStatus.reasonCode === 'binding_reconsent_required') {
+            return {
+                ok: false,
+                code: 'binding_reconsent_required',
+                message: runtimeSyncStatus.message,
+            };
+        }
+        return {
+            ok: false,
+            code: 'missing_binding',
+            message: runtimeSyncStatus.message,
+        };
+    }
+    const boundWorkspaceId = String(runtimeScope?.workspaceId || '').trim();
+    const boundProjectId = String(runtimeScope?.projectId || '').trim();
+    if (!boundWorkspaceId || !boundProjectId) {
+        return {
+            ok: false,
+            code: 'missing_binding',
+            message: 'No active workspace/project binding is available for runtime sync.',
+        };
+    }
+    if (!selected.binding.gaid) {
+        return {
+            ok: false,
+            code: 'missing_model',
+            message: 'No bound model passport found. Run forkit-connect register/publish first.',
+        };
+    }
+    const runtimeName = selected.detectedModel?.runtime || 'ollama';
+    const runtime = state.detected_runtimes.find((item) => (item.runtime === runtimeName
+        && (!selected.binding.runtimeDiscoveryHash || item.discoveryHash === selected.binding.runtimeDiscoveryHash))) ?? state.detected_runtimes.find((item) => item.runtime === runtimeName);
+    const modelName = selected.detectedModel?.model || readBoundModelName(selected.binding.modelKey);
+    const sessionId = buildSessionId(state, selected.binding.gaid);
+    const api = new api_1.ConnectApiClient({
+        baseUrl: options?.baseUrl ?? DEFAULT_BASE_URL,
+        sessionRef: storedSessionRef,
+    });
+    try {
+        const heartbeatResult = await api.sendDeploymentCheckin(selected.binding.gaid, {
+            binding_id: runtimeScope?.bindingId ?? null,
+            sessionId,
+            sessionLabel: `Forkit Connect ${modelName}`,
+            environment: 'local',
+            hostLabel: state.runtime_identity.hostname,
+            runtimeLabel: 'Forkit Connect',
+            runtimeMode: 'active',
+            resourceAccuracy: 'unknown',
+            metadata: {
+                provider: runtimeName,
+                runtime: runtimeName,
+                source: 'Verified by Runtime',
+                sourceLabel: 'Verified by Runtime',
+                workspaceId: boundWorkspaceId,
+                projectId: boundProjectId,
+                workspace_id: boundWorkspaceId,
+                project_id: boundProjectId,
+                binding_id: runtimeScope?.bindingId ?? null,
+                connect_device_id: runtimeScope?.connectDeviceId ?? effectiveBinding?.binding.connectDeviceId ?? null,
+                evidence_type: 'observed_runtime_session',
+                model: modelName,
+                digest: selected.detectedModel?.digest ?? null,
+                endpoint_hash: runtime?.endpoint ? (0, discovery_1.buildEndpointHash)(runtime.endpoint) : null,
+                source_endpoint_label: runtime?.endpoint ? (0, discovery_1.buildSourceEndpointLabel)(runtime.endpoint) : null,
+                runtimeId: state.runtime_identity.runtimeId,
+                hostname: state.runtime_identity.hostname,
+                platform: state.runtime_identity.platform,
+                arch: state.runtime_identity.arch,
+                originTool: 'forkit-connect',
+            },
+        });
+        if (!heartbeatResult.ok) {
+            const backendCode = readBackendCode(heartbeatResult.body);
+            if (isConnectBindingFailureCode(backendCode)) {
+                try {
+                    await service.refreshEffectiveBinding();
+                }
+                catch {
+                    // The backend failure is still authoritative enough to surface to the caller.
+                }
+                return buildRuntimeSyncBindingFailure(service, backendCode, heartbeatResult.status, heartbeatResult.body);
+            }
+            const observedSession = service.observeBackendCommunicationState({
+                passportGaid: selected.binding.gaid,
+                runtimeGaid: selected.binding.runtimeGaid ?? null,
+                modelName,
+                sessionId: selected.binding.activeSessionId ?? sessionId,
+                status: heartbeatResult.status,
+                body: heartbeatResult.body,
+                source: 'heartbeat',
+            });
+            if (observedSession?.local_sync_state === 'credential_reconnect_needed') {
+                return {
+                    ok: false,
+                    code: 'credential_reconnect_needed',
+                    message: 'Reconnect Forkit Connect to continue governed communication.',
+                    status: heartbeatResult.status,
+                    details: heartbeatResult.body,
+                };
+            }
+            if (observedSession?.session_mode === 'paused') {
+                return {
+                    ok: false,
+                    code: 'governor_paused',
+                    message: 'Passport communication is currently paused by Forkit governance.',
+                    status: heartbeatResult.status,
+                    details: heartbeatResult.body,
+                };
+            }
+            if (observedSession?.session_mode === 'revoked') {
+                return {
+                    ok: false,
+                    code: 'access_revoked',
+                    message: 'Passport communication access has been revoked by Forkit governance.',
+                    status: heartbeatResult.status,
+                    details: heartbeatResult.body,
+                };
+            }
+            if (heartbeatResult.status === 403 || heartbeatResult.status === 404) {
+                return {
+                    ok: false,
+                    code: 'passport_inaccessible',
+                    message: 'Bound passport not found or not accessible.',
+                    status: heartbeatResult.status,
+                };
+            }
+            if (heartbeatResult.status >= 500) {
+                service.observeTransientRuntimeSyncFailure({
+                    passportGaid: selected.binding.gaid,
+                    runtimeGaid: selected.binding.runtimeGaid ?? null,
+                    modelName,
+                    sessionId: selected.binding.activeSessionId ?? sessionId,
+                    source: 'heartbeat',
+                    status: heartbeatResult.status,
+                    reason: `heartbeat_${heartbeatResult.status}`,
+                    details: heartbeatResult.body,
+                });
+            }
+            return {
+                ok: false,
+                code: 'heartbeat_failed',
+                message: `[forkit-connect] Heartbeat failed (${heartbeatResult.status}).`,
+                status: heartbeatResult.status,
+                details: heartbeatResult.body,
+            };
+        }
+        if (!isDeploymentCheckinResponse(heartbeatResult.body) || !heartbeatResult.body.session) {
+            return {
+                ok: false,
+                code: 'heartbeat_failed',
+                message: `[forkit-connect] Heartbeat failed (${heartbeatResult.status}).`,
+                status: heartbeatResult.status,
+                details: heartbeatResult.body,
+            };
+        }
+        service.getStateStore().addEvidenceEvent({
+            type: 'runtime_heartbeat_sent',
+            details: {
+                gaid: selected.binding.gaid,
+                model: modelName,
+                workspaceId: boundWorkspaceId,
+                projectId: boundProjectId,
+                runtime: runtimeName,
+                provider: runtimeName,
+                source: 'Verified by Runtime',
+                sessionId: heartbeatResult.body.session.sessionId ?? sessionId,
+                sessionLabel: heartbeatResult.body.session.sessionLabel ?? `Forkit Connect ${modelName}`,
+                runtimeMode: heartbeatResult.body.session.runtimeMode ?? 'active',
+                lastCheckinAt: heartbeatResult.body.session.lastCheckinAt ?? null,
+                backendStatus: heartbeatResult.status,
+            },
+        });
+        service.observeDeploymentSession({
+            sessionId: heartbeatResult.body.session.sessionId ?? sessionId,
+            passportGaid: selected.binding.gaid,
+            runtimeGaid: selected.binding.runtimeGaid ?? null,
+            modelName,
+            workspaceId: boundWorkspaceId,
+            projectId: boundProjectId,
+            sessionMode: normalizeHeartbeatSessionMode(heartbeatResult.body.session.runtimeMode ?? 'active', heartbeatResult.body.session.revokedAt ?? null),
+            controlSource: 'website',
+            lastSeenAt: heartbeatResult.body.session.lastCheckinAt ?? null,
+            lastControlSeenAt: heartbeatResult.body.session.revokedAt ?? heartbeatResult.body.session.lastCheckinAt ?? null,
+            metadata: {
+                session_label: heartbeatResult.body.session.sessionLabel ?? `Forkit Connect ${modelName}`,
+                runtime_mode: heartbeatResult.body.session.runtimeMode ?? 'active',
+                resource_accuracy: heartbeatResult.body.session.resourceAccuracy ?? null,
+            },
+        });
+        return {
+            ok: true,
+            gaid: selected.binding.gaid,
+            modelName,
+            sessionId: heartbeatResult.body.session.sessionId ?? sessionId,
+            lastCheckinAt: heartbeatResult.body.session.lastCheckinAt ?? null,
+        };
+    }
+    catch (error) {
+        service.observeTransientRuntimeSyncFailure({
+            passportGaid: selected.binding.gaid,
+            runtimeGaid: selected.binding.runtimeGaid ?? null,
+            modelName,
+            sessionId: selected.binding.activeSessionId ?? sessionId,
+            source: 'heartbeat',
+            reason: error instanceof Error ? error.message : 'heartbeat_transport_failed',
+            details: error instanceof Error ? error.message : error,
+        });
+        return {
+            ok: false,
+            code: 'heartbeat_failed',
+            message: '[forkit-connect] Heartbeat failed (transport).',
+            details: error instanceof Error ? error.message : error,
+        };
+    }
+}
+async function sendAllBoundHeartbeats(service, options) {
+    const selections = listBoundBindings(service.getStateStore().readState());
+    const results = [];
+    let attempted = 0;
+    let succeeded = 0;
+    let failed = 0;
+    let runtimeSignalQueued = 0;
+    for (const selection of selections) {
+        if (!selection.binding.gaid) {
+            continue;
+        }
+        attempted += 1;
+        const result = await sendHeartbeatForSelection(service, selection, options);
+        const runtimeSignalQueueId = result.ok && options?.queueRuntimeSignal !== false
+            ? service.queueConfiguredHeartbeatRuntimeSignal(result.gaid)
+            : null;
+        if (result.ok) {
+            succeeded += 1;
+        }
+        else {
+            failed += 1;
+        }
+        if (runtimeSignalQueueId) {
+            runtimeSignalQueued += 1;
+        }
+        results.push({
+            gaid: selection.binding.gaid,
+            modelName: selection.detectedModel?.model || readBoundModelName(selection.binding.modelKey),
+            runtimeSignalQueueId,
+            result,
+        });
+        if (!result.ok && (result.code === 'not_authenticated'
+            || result.code === 'missing_binding'
+            || result.code === 'credential_reconnect_needed'
+            || result.code === 'binding_paused'
+            || result.code === 'binding_stale'
+            || result.code === 'binding_reconsent_required')) {
+            break;
+        }
+    }
+    return {
+        attempted,
+        succeeded,
+        failed,
+        runtimeSignalQueued,
+        results,
+    };
+}
+async function sendBoundHeartbeat(service, options) {
+    const selected = selectBoundBinding(service.getStateStore().readState());
+    if (!selected) {
+        return {
+            ok: false,
+            code: 'missing_model',
+            message: 'No bound model passport found. Run forkit-connect register/publish first.',
+        };
+    }
+    return sendHeartbeatForSelection(service, selected, options);
+}
+//# sourceMappingURL=heartbeat.js.map

package/dist/v1/lifecycle-monitor.d.ts

@@ -0,0 +1,78 @@
+/**
+ * lifecycle-monitor.ts
+ * ─────────────────────────────────────────────────────────────────────────────
+ * Deep AI model and agent lifecycle observability engine for Forkit Connect.
+ *
+ * Capabilities (fully automatic, 24/7, login-only onboarding):
+ *
+ * 1. Silent model change detection
+ *    Tracks digest, size, and weights-layer hash per model binding.
+ *    Emits `connect_silent_model_change` when any of these change without an
+ *    announced version event, queuing a PendingReview for human acknowledgement.
+ *
+ * 2. Model drift detection (metadata-based)
+ *    Tracks quantization label and parameter count changes over scan cycles.
+ *    Emits `connect_model_drift_detected` on capability-class changes.
+ *
+ * 3. Agent behavioral drift detection
+ *    Computes a hash of each agent's distinct observed tool set. If the tool
+ *    fingerprint changes significantly (tools added or removed) it emits
+ *    `connect_agent_drift_detected`.
+ *
+ * 4. Prompt injection detection
+ *    Scans agent tool-call observations for known injection patterns:
+ *    system-override phrases, base64-encoded instruction payloads, DAN-style
+ *    prompts. Emits `connect_prompt_injection_suspected` with confidence level.
+ *
+ * 5. Adversarial influence detection
+ *    Correlates: (a) multiple injection signals within the same scan window,
+ *    (b) a prompt injection AND a silent model change on the same agent/model
+ *    pair. When correlated, emits `connect_adversarial_influence_observed`.
+ *
+ * Human-in-the-loop flow:
+ *    Every detection writes a PendingReview. Humans can confirm/dismiss via
+ *    `c2 reviews` CLI commands. Once a pattern is confirmed once, subsequent
+ *    detections of the same kind for the same subject are auto-confirmed,
+ *    giving full automation with initial oversight.
+ *
+ * Privacy contract:
+ *    This module never reads prompt content or model outputs directly.
+ *    It only inspects: model metadata (name, digest, size, quantization label,
+ *    parameter count), agent tool names (not arguments), and detection signals
+ *    already recorded in the evidence chain.
+ */
+import type { ConnectState, C2LiteEventType, LifecycleMonitorRecord, PendingReview, PendingReviewKind } from './types';
+export interface LifecycleMonitorDependencies {
+    state: ConnectState;
+    upsertPendingReview: (review: PendingReview) => void;
+    upsertLifecycleMonitorRecord: (record: LifecycleMonitorRecord) => void;
+    recordC2Event: (input: {
+        eventType: C2LiteEventType;
+        passportGaid?: string | null;
+        agentId?: string | null;
+        runtimeGaid?: string | null;
+        modelName?: string | null;
+        metadata?: Record<string, unknown>;
+    }) => void;
+}
+export interface MonitorPassResult {
+    checksRun: number;
+    detections: MonitorDetection[];
+    reviewsQueued: number;
+    reviewsAutoConfirmed: number;
+}
+export interface MonitorDetection {
+    kind: PendingReviewKind;
+    subjectId: string;
+    subjectType: 'model' | 'agent' | 'runtime';
+    confidence: 'high' | 'medium' | 'low';
+    summary: string;
+}
+export declare function runLifecycleMonitoringPass(deps: LifecycleMonitorDependencies): MonitorPassResult;
+/**
+ * Returns the list of passport GAIDs owned by the session that do not yet
+ * have a runtime-signal API key stored locally. Used by the service to decide
+ * which passports need auto-provisioning.
+ */
+export declare function findPassportsNeedingApiKeyProvisioning(state: ConnectState): string[];
+//# sourceMappingURL=lifecycle-monitor.d.ts.map