forkit-connect 0.1.0 → 0.1.3

package/dist/v1/state.d.ts

@@ -77,6 +77,7 @@ export declare class LocalStateStore {
     private withDatabase;
     private getDb;
     private persistState;
+    private persistStateInPlace;
     private loadRawStateRecord;
     private readLegacyStateFile;
     private ensureStateDirectory;

package/dist/v1/state.js

@@ -74,6 +74,8 @@ const STATE_SECTION_NAMES = [
     'sync_queue',
     'pending_reviews',
     'lifecycle_monitor_records',
+    'smart_inbox_snapshot',
+    'smart_inbox_snapshot_updated_at',
 ];
 function hashCredentialRef(value) {
     return (0, node_crypto_1.createHash)('sha256').update(value, 'utf8').digest('hex').slice(0, 24);
@@ -430,6 +432,12 @@ function normalizeState(parsed) {
         sync_queue: Array.isArray(value.sync_queue) ? value.sync_queue : [],
         pending_reviews: Array.isArray(value.pending_reviews) ? value.pending_reviews : [],
         lifecycle_monitor_records: Array.isArray(value.lifecycle_monitor_records) ? value.lifecycle_monitor_records : [],
+        smart_inbox_snapshot: value.smart_inbox_snapshot && typeof value.smart_inbox_snapshot === 'object'
+            ? value.smart_inbox_snapshot
+            : null,
+        smart_inbox_snapshot_updated_at: typeof value.smart_inbox_snapshot_updated_at === 'string'
+            ? value.smart_inbox_snapshot_updated_at
+            : null,
     };
 }
 function buildInitialState() {
@@ -478,6 +486,8 @@ function buildInitialState() {
         sync_queue: [],
         pending_reviews: [],
         lifecycle_monitor_records: [],
+        smart_inbox_snapshot: null,
+        smart_inbox_snapshot_updated_at: null,
     };
 }
 function readJsonFile(filePath) {
@@ -1101,11 +1111,18 @@ class LocalStateStore {
         node_fs_1.default.rmSync(this.paths.legacyStateFile, { force: true });
     }
     mutateState(mutator) {
-        const state = this.ensureInitialized();
-        mutator(state);
-        const normalized = normalizeState(state);
-        this.writeState(normalized);
-        return normalized;
+        this.ensureInitializedInternal();
+        return this.withDatabase((db) => {
+            const mutate = db.transaction(() => {
+                const raw = this.loadRawStateRecord(db);
+                const state = raw ? normalizeState(raw) : buildInitialState();
+                mutator(state);
+                const normalized = normalizeState(state);
+                this.persistStateInPlace(db, normalized);
+                return normalized;
+            });
+            return mutate.immediate();
+        }, true);
     }
     ensureInitializedInternal() {
         this.withDatabase((db) => {
@@ -1199,6 +1216,12 @@ class LocalStateStore {
     }
     persistState(db, state) {
         const normalized = normalizeState(state);
+        const persist = db.transaction((nextState) => {
+            this.persistStateInPlace(db, nextState);
+        });
+        persist(normalized);
+    }
+    persistStateInPlace(db, state) {
         const updatedAt = nowIso();
         const upsertSection = db.prepare(`
       INSERT INTO connect_state_sections (section_name, payload_json, updated_at)
@@ -1214,13 +1237,10 @@ class LocalStateStore {
         value = excluded.value,
         updated_at = excluded.updated_at
     `);
-        const persist = db.transaction((nextState) => {
-            for (const sectionName of STATE_SECTION_NAMES) {
-                upsertSection.run(sectionName, JSON.stringify(nextState[sectionName] ?? null), updatedAt);
-            }
-            upsertMeta.run('last_state_write_at', updatedAt, updatedAt);
-        });
-        persist(normalized);
+        for (const sectionName of STATE_SECTION_NAMES) {
+            upsertSection.run(sectionName, JSON.stringify(state[sectionName] ?? null), updatedAt);
+        }
+        upsertMeta.run('last_state_write_at', updatedAt, updatedAt);
     }
     loadRawStateRecord(db) {
         const rows = db.prepare(`

package/dist/v1/types.d.ts

@@ -12,6 +12,7 @@ export type RegistrationState = 'registered' | 'unregistered' | 'unknown';
 export type ModelBindingStatus = 'pending' | 'bound' | 'ignored';
 export type ReviewStatus = 'new_unregistered' | 'known_unregistered' | 'pending_draft' | 'bound_passport' | 'shadow_candidate' | 'provider_unavailable';
 export type AgentType = 'coding_agent' | 'local_agent_runtime' | 'mcp_server' | 'ide_extension' | 'workflow_automation' | 'unknown_ai_tool';
+export type AgentClass = 'interactive_assistant' | 'background_automation' | 'evaluator_reviewer' | 'orchestrator' | 'retrieval_tool_worker';
 export type AgentStatus = 'detected' | 'connected' | 'inactive';
 export type AgentReviewStatus = 'new_agent' | 'known_agent' | 'linked_agent' | 'inactive_agent' | 'unknown_ai_tool';
 export type AgentDiscoverySource = 'process_scan' | 'daemon_scan' | 'manual_connect' | 'manual_link';
@@ -300,6 +301,16 @@ export interface ExistingPassportMatchSuggestion {
     match_confidence: RuntimePassportConfidence;
     match_reason: string;
 }
+/**
+ * SmartRegistrationInboxItem represents a single onboarding candidate in the Smart Inbox.
+ *
+ * **Scope (M1 Inbox Boundary Contract):**
+ * - This inbox is an ONBOARDING/EXCEPTION decision queue, NOT a long-term telemetry surface.
+ * - Items represent: unregistered runtimes/models/agents requiring user action, or known items needing exception handling.
+ * - Items with status='connected' and no action required are filtered out (deferred to C2 dashboard for telemetry).
+ * - `details_received_automatically` EXCLUDES long-term operational data: no cost, token usage, latency buckets, or provider-specific metrics.
+ * - This keeps inbox lightweight and focused on registration decisions, not performance analysis.
+ */
 export interface SmartRegistrationInboxItem {
     item_id: string;
     item_type: SmartRegistrationInboxItemType;
@@ -316,6 +327,12 @@ export interface SmartRegistrationInboxItem {
     confidence: RuntimePassportConfidence;
     recommended_action: SmartRegistrationInboxAction;
     allowed_actions: SmartRegistrationInboxAction[];
+    /**
+     * Automatic details captured during discovery/detection.
+     * Includes: model name, model digest, runtime name, agent type, match reason.
+     * EXCLUDES: cost, token counts, latency, provider metrics, usage aggregations.
+     * Kept lightweight to emphasize inbox is for registration decisions, not analytics.
+     */
     details_received_automatically: Record<string, string | number | boolean | null>;
     safe_metadata_only: true;
 }
@@ -327,7 +344,27 @@ export interface SmartRegistrationInboxSummary {
     ignored_count: number;
     next_recommended_action: SmartRegistrationInboxAction | null;
     privacy_summary: string;
-}
+    freshness_state?: 'fresh' | 'syncing' | 'stale';
+    snapshot_age_seconds?: number;
+}
+/**
+ * SmartRegistrationInbox (M1 Inbox Boundary Contract)
+ *
+ * **Purpose:** Onboarding/exception decision queue for local runtime/model/agent discovery.
+ *
+ * **Scope & Boundaries:**
+ * - INCLUDES: unregistered runtimes/models/agents requiring user action, exceptions (credential reconnect, unknown versions).
+ * - INCLUDES groups: ready_to_connect (high confidence, actionable), needs_confirmation (needs clarification),
+ *   connected (already linked but may need refresh), ignored (user-deferred).
+ * - EXCLUDES: long-term telemetry data (cost, token usage, latency metrics, provider operational stats).
+ * - NOT a performance/cost analytics surface; use RuntimeSignalsDashboard + C2 lifecycle events for that.
+ *
+ * **Items are NOT filtered out when connected and healthy** — user may want to inspect existing connections.
+ * Filtering happens at UI level: UX can show "all" or "action required" tabs, but inbox serves both.
+ *
+ * **Agent Metadata (M2):** Agents in inbox include agent_class enum for classification (interactive_assistant,
+ * background_automation, etc.), allowing UI to show agent-specific onboarding workflows.
+ */
 export interface SmartRegistrationInbox {
     summary: SmartRegistrationInboxSummary;
     groups: Record<SmartRegistrationInboxGroup, SmartRegistrationInboxItem[]>;
@@ -500,10 +537,17 @@ export interface BuildSession {
     lifecycle_events: BuildLifecycleEvent[];
     artifact_refs: BuildArtifactRef[];
 }
+/**
+ * DetectedAgent (M2: Agent Class Metadata)
+ *
+ * Represents a detected AI agent/process in the local runtime environment.
+ * Includes agent_class enum for architectural classification, enabling specialized onboarding workflows.
+ */
 export interface DetectedAgent {
     agent_id: string;
     agent_name: string;
     agent_type: AgentType;
+    agent_class?: AgentClass | null;
     process_name: string | null;
     process_signature_hash: string;
     detected_at: string;
@@ -513,9 +557,16 @@ export interface DetectedAgent {
     discovery_sources: AgentDiscoverySource[];
     metadata: Record<string, unknown>;
 }
+/**
+ * AgentLink (M2: Agent Class Metadata in linkage)
+ *
+ * Records the binding between a detected agent and a model it uses.
+ * Carries agent_class through the linkage for passport enrichment.
+ */
 export interface AgentLink {
     link_id: string;
     agent_id: string;
+    agent_class?: AgentClass | null;
     model_name: string;
     discoveryHash: string;
     registrationKey: string | null;
@@ -538,6 +589,7 @@ export interface AgentModelUsageRecord {
     agent_id: string;
     agent_name: string;
     agent_type: AgentType;
+    agent_class?: AgentClass | null;
     process_signature_hash: string;
     model_name: string;
     discoveryHash: string;
@@ -852,6 +904,8 @@ export interface ConnectState {
     sync_queue: SyncQueueItem[];
     pending_reviews: PendingReview[];
     lifecycle_monitor_records: LifecycleMonitorRecord[];
+    smart_inbox_snapshot: SmartRegistrationInbox | null;
+    smart_inbox_snapshot_updated_at: string | null;
 }
 export interface OllamaTagResponse {
     models?: Array<{

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "forkit-connect",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "Forkit Connect Local Engine - The Global AI Governance Fabric",
   "license": "MIT",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "engines": {
-    "node": ">=20.0.0"
+    "node": "20.x || 22.x || 24.x"
   },
   "files": [
     "dist",
@@ -14,25 +14,25 @@
     "QUICKSTART.md"
   ],
   "scripts": {
-    "build": "pnpm run clean && tsc -p tsconfig.build.json",
+    "build": "npm run clean && tsc -p tsconfig.build.json && node -e \"const fs = require('node:fs'); if (process.platform !== 'win32') fs.chmodSync('dist/cli.js', 0o755);\"",
     "dev": "tsc -w -p tsconfig.build.json",
-    "clean": "rm -rf dist",
-    "prepack": "pnpm run build && node ./scripts/prune-package-dist.js",
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true });\"",
+    "prepack": "npm run build && node ./scripts/prune-package-dist.js",
     "install:ubuntu": "bash ./scripts/install-ubuntu-local.sh",
-    "smoke:package": "bash ./scripts/smoke-package.sh",
+    "smoke:package": "node ./scripts/smoke-package.mjs",
+    "smoke:registry": "node ./scripts/smoke-registry.mjs",
     "desktop:dev": "pnpm run build && node dist/launcher.js",
     "desktop:build": "pnpm run build && node dist/launcher.js --build-shell",
     "deploy:local": "bash scripts/deploy-local.sh"
   },
   "bin": {
-    "forkit-connect": "./dist/cli.js"
+    "forkit-connect": "dist/cli.js"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.1",
-    "better-sqlite3": "^11.10.0",
+    "better-sqlite3": "^12.10.0",
     "cors": "^2.8.6",
     "express": "^4.19.2",
-    "keytar": "^7.9.0",
     "ps-list": "^8.1.1",
     "uuid": "^10.0.0",
     "ws": "^8.16.0",