@lensagent/core 0.1.0

package/dist/core/host.js

@@ -0,0 +1,249 @@
+import { mkdir, readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { id } from './codec.js';
+import { PairStore } from './access.js';
+import { ConfigRuntime } from '../config/runtime.js';
+import { openDatabase } from '../store/database.js';
+import { Store } from '../store/store.js';
+import { EventLog } from '../store/event-log.js';
+import { EventBus } from '../runtime/events.js';
+import { Scheduler } from '../runtime/scheduler.js';
+import { ArtifactStore } from '../runtime/artifacts.js';
+import { AiModelGateway } from '../runtime/model.js';
+import { AutoReviewer } from '../runtime/review.js';
+import { ProjectRuntimes } from '../runtime/projects.js';
+import { Observability } from '../runtime/observability.js';
+import { adapterTarget, assertManifestSet, coreManifests } from '../runtime/manifests.js';
+import { ExecutorClient, executorCapabilities } from '../adapters/executor.js';
+import { mcpCapabilities } from '../adapters/mcp.js';
+import { LspPool, lspCapabilities } from '../adapters/lsp.js';
+import { revertCapabilities } from '../adapters/revert.js';
+import { applyPurge } from '../runtime/cleanup.js';
+import { createServer } from '../http/server.js';
+export async function launchCore(options = {}) {
+    const root = resolve(options.installRoot ?? process.cwd());
+    const config = new ConfigRuntime(root, options.configPath);
+    await config.load();
+    const target = adapterTarget(options.runtime ?? 'node');
+    assertManifestSet(coreManifests(config.current.config), target);
+    const blockers = new Set();
+    const observability = new Observability(root, config.current.config.observability);
+    const events = new EventBus(id('instance'), config.current.config.sse, () => config.current.metadataRevision + pair.metadataRevision);
+    const pair = new PairStore(root, config.current.config.pairPath ?? 'config/pair.json', (clientId) => events.revoke(clientId));
+    try {
+        await pair.load();
+    }
+    catch (error) {
+        blockers.add('pair');
+        observability.record('access', 'pair_load', 'failed', 0, { error_code: errorCode(error) });
+    }
+    const eventLogConfig = config.current.config.persistence?.eventLog;
+    const eventLog = eventLogConfig?.enabled === true ? new EventLog(root, eventLogConfig.path, eventLogConfig.fsync) : undefined;
+    await eventLog?.load();
+    const store = new Store(openDatabase(root, config.current.config.database.path), events, eventLog);
+    const interrupted = store.recover();
+    if (interrupted.length > 0)
+        observability.record('store', 'recovery', 'success', 0, { interrupted: interrupted.length });
+    // Not `root`. The app root is where config/lens.jsonc holds the Provider API keys and where
+    // config/pair.json holds the client allowlist, so making it the default Workspace put both inside
+    // the one directory an Agent's file Capabilities are allowed to reach: `read_file` would reach the
+    // credentials, and `write_file` on the pair file would let an Agent mark its own client verified.
+    // A dedicated subdirectory keeps a working default without making the containment boundary and the
+    // secret store the same path.
+    const defaultWorkspace = resolve(root, 'workspace');
+    await mkdir(defaultWorkspace, { recursive: true });
+    const defaultProject = store.defaultProject() ?? store.createProject('Project', [defaultWorkspace]);
+    const defaultProjectId = string(defaultProject.id);
+    const executor = await ExecutorClient.create(root, config);
+    try {
+        await executor.health();
+    }
+    catch (error) {
+        blockers.add('executor');
+        observability.record('executor', 'health', 'failed', 0, { error_code: errorCode(error) });
+    }
+    const scheduler = new Scheduler(config.current.config.concurrency);
+    const artifacts = new ArtifactStore(root, config.current.config.artifacts.directory, store, config.current.config.persistence?.contentStore?.mode ?? 'filesystem');
+    const models = new AiModelGateway(config, target);
+    const reviewer = new AutoReviewer(models, config);
+    const lsp = new LspPool(config.current.config.lspServers ?? {});
+    const sharedCapabilities = [
+        ...executorCapabilities(executor),
+        ...lspCapabilities(config.current.config.lspServers ?? {}, lsp),
+        ...revertCapabilities(store, executor)
+    ];
+    // An MCP server that cannot be reached loses its own tools and nothing else. It used to add a
+    // startup blocker, which put the whole runtime into health_only: one unreachable optional
+    // integration returned 503 from readiness and no client could sync. 02A also fixes the readiness
+    // blocker codes at PAIR_FILE_INVALID, MIGRATION_FAILED, RECOVERY_INCOMPLETE and STORE_UNAVAILABLE,
+    // so `mcp:<id>` was never a documented reason to be unready.
+    const degradedMcpServers = [];
+    for (const [serverId, serverConfig] of Object.entries(config.current.config.mcpServers ?? {})) {
+        try {
+            sharedCapabilities.push(...await mcpCapabilities(serverId, serverConfig));
+        }
+        catch (error) {
+            degradedMcpServers.push(serverId);
+            observability.record('mcp', 'discover', 'failed', 0, { server_id: serverId, error_code: errorCode(error) });
+        }
+    }
+    const runtimes = new ProjectRuntimes(store, config, scheduler, artifacts, models, reviewer, sharedCapabilities, target, events, defaultProjectId);
+    runtimes.get(defaultProjectId);
+    runtimes.startIdleEviction();
+    // Graceful stop arrives as a request on the Server's control path, not as an OS signal, so the
+    // runtime needs a way to hand that request outwards. The Promise is created before the Server so
+    // the Route can never fire into an unset resolver.
+    let signalShutdown = () => undefined;
+    const shutdownRequested = new Promise((resolve) => { signalShutdown = resolve; });
+    const https = await httpsOptions(root, config);
+    const server = createServer({
+        ...(https === undefined ? {} : { https }),
+        config,
+        pair,
+        store,
+        events,
+        runtime: (projectId) => runtimes.get(projectId),
+        refreshProject: (projectId) => runtimes.refresh(projectId),
+        models,
+        artifacts,
+        observability,
+        executor,
+        defaultProjectId,
+        ready: () => ({ mode: blockers.size === 0 ? 'full' : 'health_only', blockers: [...blockers] }),
+        requestShutdown: () => { signalShutdown(); }
+    });
+    await server.listen({ ...config.current.config.listen });
+    for (const serverId of degradedMcpServers) {
+        events.emit(defaultProjectId, store.stateRevision(), 'runtime.notice', {
+            code: 'mcp_server_unavailable',
+            server_id: serverId
+        });
+    }
+    pair.start((error) => {
+        observability.record('access', 'pair_reload', 'failed', 0, { error_code: errorCode(error) });
+        events.emit(defaultProjectId, store.stateRevision(), 'config.changed', { component: 'pair', error: error.message });
+    });
+    config.start((snapshot) => {
+        scheduler.updateLimits(snapshot.config.concurrency);
+        events.updateLimits(snapshot.config.sse);
+        events.emit(defaultProjectId, store.stateRevision(), 'config.changed', {
+            config_digest: snapshot.digest,
+            file_digest: snapshot.fileDigest,
+            pending_restart: snapshot.pendingRestart,
+            error: snapshot.error
+        });
+    });
+    const maintenanceTimer = setInterval(() => {
+        void runRetention(store, artifacts, executor, config).catch((error) => {
+            observability.record('maintenance', 'retention', 'failed', 0, { error_code: errorCode(error) });
+        });
+    }, 60 * 60 * 1000);
+    maintenanceTimer.unref();
+    let closing;
+    return {
+        url: `${config.current.config.tls.enabled ? 'https' : 'http'}://${config.current.config.listen.host}:${config.current.config.listen.port}`,
+        shutdownRequested,
+        close: () => {
+            if (closing !== undefined)
+                return closing;
+            closing = (async () => {
+                const graceMs = config.current.config.shutdown?.graceMs ?? 30_000;
+                const ordered = (async () => {
+                    const serverClosing = server.close();
+                    clearInterval(maintenanceTimer);
+                    config.close();
+                    pair.close();
+                    await runtimes.close();
+                    scheduler.close();
+                    events.close();
+                    await lsp.close();
+                    executor.close();
+                    await serverClosing;
+                    await observability.close();
+                    await store.close();
+                })();
+                // Bounded, because an unbounded wait here is worse than an imperfect stop. A stage that
+                // never settles -- a Worker ignoring cancellation, an LSP child not exiting -- would strand
+                // the process with no way out but a hard kill, and a hard kill discards this whole ordered
+                // sequence. Section 10 already leaves unconfirmable objects to Recovery and SQLite/WAL is
+                // crash-safe, so returning after the grace period loses no committed state.
+                await withinGrace(ordered, graceMs, observability);
+            })();
+            return closing;
+        }
+    };
+}
+/**
+ * Waits for the ordered shutdown, but not forever.
+ *
+ * The diagnostic is recorded the moment the grace period expires rather than afterwards, because
+ * `observability.close()` is itself one of the last stages: recording later could be writing to a
+ * sink that the sequence has already closed.
+ */
+async function withinGrace(ordered, graceMs, observability) {
+    let timer;
+    const expired = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            try {
+                observability.record('runtime', 'shutdown', 'failed', graceMs, { reason: 'grace_expired', grace_ms: graceMs });
+            }
+            catch {
+                // A sink that is already gone must not turn a slow stop into a crash.
+            }
+            resolve('expired');
+        }, graceMs);
+        // Never the reason the process stays alive.
+        timer.unref();
+    });
+    // Settled either way, so a stage that rejects after the grace period cannot surface as an
+    // unhandled rejection once nothing is awaiting it any more.
+    const settled = ordered.then(() => 'closed', (error) => {
+        try {
+            observability.record('runtime', 'shutdown', 'failed', 0, { error_code: errorCode(error) });
+        }
+        catch {
+            // As above.
+        }
+        return 'failed';
+    });
+    await Promise.race([settled, expired]);
+    if (timer !== undefined)
+        clearTimeout(timer);
+}
+async function runRetention(store, artifacts, executor, config) {
+    const retention = config.current.config.historyRetention;
+    if (retention.purgeMode !== 'after_days' || retention.purgeArchivedAfterDays === null)
+        return;
+    const before = new Date(Date.now() - retention.purgeArchivedAfterDays * 24 * 60 * 60 * 1000).toISOString();
+    const projectIds = [];
+    let cursor;
+    do {
+        const page = store.listProjects({ ...(cursor === undefined ? {} : { cursor }), limit: 500 }, 'all');
+        for (const project of page.items) {
+            if (typeof project.id === 'string')
+                projectIds.push(project.id);
+        }
+        cursor = page.nextCursor ?? undefined;
+    } while (cursor !== undefined);
+    for (const projectId of projectIds) {
+        await applyPurge(store.purgeArchived(projectId, before), artifacts, executor);
+    }
+}
+async function httpsOptions(root, config) {
+    const tls = config.current.config.tls;
+    if (!tls.enabled)
+        return undefined;
+    if (tls.keyFile === null || tls.certFile === null)
+        throw new Error('TLS keyFile and certFile are required when TLS is enabled.');
+    return { key: await readFile(resolve(root, tls.keyFile)), cert: await readFile(resolve(root, tls.certFile)) };
+}
+function string(value) {
+    if (typeof value !== 'string')
+        throw new Error('Expected a string value.');
+    return value;
+}
+function errorCode(error) {
+    if (typeof error === 'object' && error !== null && 'code' in error && typeof error.code === 'string')
+        return error.code;
+    return error instanceof Error ? error.name : 'UNKNOWN_ERROR';
+}

package/dist/core/identity.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Component identity as the Launcher design defines it: component kind, independent software
+ * version and the integer protocol versions this build speaks.
+ *
+ * `package.json` is the single source. The Launcher rereads installed metadata offline after an
+ * Update and before a Start, so the values cannot live only in a running Server's response, and
+ * a second hand-maintained copy in source would be free to disagree with the published version.
+ *
+ * The two protocol versions are independent integers compared by strict equality against the
+ * adjacent component; they are not SemVer and carry no range or negotiation semantics.
+ * `runtime_contract_digest` is unrelated and is not a protocol version.
+ */
+export interface ComponentIdentity {
+    readonly component: string;
+    readonly softwareVersion: string;
+    readonly protocols: Readonly<Record<string, number>>;
+}
+/** Reads the installed package metadata once per process. */
+export declare function componentIdentity(): ComponentIdentity;

package/dist/core/identity.js

@@ -0,0 +1,54 @@
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+// Anchored to this module's own URL rather than `cwd`, for the same reason as the bundled
+// `executor.proto` path: the process `cwd` is the component's app root, which is not the
+// directory the package was installed into.
+const manifestPath = resolve(dirname(fileURLToPath(import.meta.url)), '../../package.json');
+let cached;
+/** Reads the installed package metadata once per process. */
+export function componentIdentity() {
+    cached ??= readManifest();
+    return cached;
+}
+function readManifest() {
+    let document;
+    try {
+        document = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`Package metadata at ${manifestPath} could not be read: ${message(error)}`);
+    }
+    const manifest = object(document, 'package.json');
+    const lens = object(manifest.lens, 'package.json "lens"');
+    return {
+        component: string(lens.component, 'package.json "lens.component"'),
+        softwareVersion: string(manifest.version, 'package.json "version"'),
+        protocols: protocols(lens.protocols)
+    };
+}
+function protocols(value) {
+    const entries = object(value, 'package.json "lens.protocols"');
+    const result = {};
+    for (const [name, version] of Object.entries(entries)) {
+        if (typeof version !== 'number' || !Number.isInteger(version)) {
+            throw new Error(`Protocol version "${name}" in ${manifestPath} must be an integer.`);
+        }
+        result[name] = version;
+    }
+    return result;
+}
+function object(value, field) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new Error(`${field} in ${manifestPath} must be an object.`);
+    }
+    return value;
+}
+function string(value, field) {
+    if (typeof value !== 'string' || value === '')
+        throw new Error(`${field} in ${manifestPath} must be a non-empty string.`);
+    return value;
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/entry/bun.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/entry/bun.js

@@ -0,0 +1,2 @@
+import { run } from './run.js';
+await run('bun');

package/dist/entry/node.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/entry/node.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from './run.js';
+await run('node');

package/dist/entry/rebuild.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/entry/rebuild.js

@@ -0,0 +1,47 @@
+import { dirname, resolve } from 'node:path';
+import { mkdir } from 'node:fs/promises';
+import { openDatabase } from '../store/database.js';
+import { readEventLog } from '../store/event-log.js';
+const eventLog = argument('--event-log');
+const output = argument('--output');
+await mkdir(dirname(resolve(output)), { recursive: true });
+const records = await readEventLog(resolve(eventLog));
+const state = records.at(-1)?.state;
+if (typeof state !== 'object' || state === null || Array.isArray(state))
+    throw new Error('Event Log has no rebuildable state.');
+const stateRecord = state;
+const database = openDatabase(process.cwd(), output);
+const tables = Object.keys(stateRecord);
+database.pragma('foreign_keys = OFF');
+const restore = database.transaction(() => {
+    for (const table of [...tables].reverse())
+        database.prepare(`DELETE FROM ${table}`).run();
+    for (const table of tables) {
+        const rows = stateRecord[table];
+        if (!Array.isArray(rows))
+            throw new Error(`Event Log table ${table} is invalid.`);
+        for (const row of rows) {
+            if (typeof row !== 'object' || row === null || Array.isArray(row))
+                throw new Error(`Event Log row ${table} is invalid.`);
+            const rowRecord = row;
+            const columns = Object.keys(rowRecord);
+            database.prepare(`INSERT INTO ${table}(${columns.join(', ')}) VALUES (${columns.map(() => '?').join(', ')})`).run(...columns.map((column) => scalar(rowRecord[column])));
+        }
+    }
+});
+restore();
+database.pragma('foreign_keys = ON');
+database.close();
+process.stdout.write(`rebuilt ${output} at revision ${records.at(-1)?.revision ?? 0}\n`);
+function argument(name) {
+    const index = process.argv.indexOf(name);
+    const value = process.argv[index + 1];
+    if (index < 0 || value === undefined)
+        throw new Error(`${name} is required.`);
+    return value;
+}
+function scalar(value) {
+    if (value === null || typeof value === 'string' || typeof value === 'number')
+        return value;
+    throw new Error('Event Log contains a non-scalar database value.');
+}

package/dist/entry/run.d.ts

@@ -0,0 +1 @@
+export declare function run(runtime: 'node' | 'bun'): Promise<void>;

package/dist/entry/run.js

@@ -0,0 +1,43 @@
+import { launch } from '../launch.js';
+export async function run(runtime) {
+    ignoreStdoutErrors();
+    const server = await launch({ runtime });
+    announce(`lens-core listening at ${server.url}\n`);
+    listenForShutdown(server);
+}
+function listenForShutdown(server) {
+    let closing = false;
+    const close = () => {
+        if (closing)
+            return;
+        closing = true;
+        void server.close().finally(() => process.exit(0));
+    };
+    // The graceful stop a process manager is expected to use: a request on the Server's control
+    // path, not a signal. The signal handlers stay for an interactive terminal and for anything that
+    // does send one, but they are not the documented Stop mechanism.
+    void server.shutdownRequested.then(close);
+    process.once('SIGINT', close);
+    process.once('SIGTERM', close);
+}
+/**
+ * A detached Core keeps running after the program that started it exits, and it must not depend on
+ * that program's stdio pipes. When the read end of an inherited stdout pipe closes, the next write
+ * raises EPIPE — asynchronously, as a stream `error` event, so `try`/`catch` around the write does
+ * not see it and the default handling ends the process. Swallowing it here keeps a healthy runtime
+ * alive; stdout is a startup courtesy, not a runtime dependency. Diagnostics go to the
+ * Observability log sink, which is unaffected.
+ */
+function ignoreStdoutErrors() {
+    process.stdout.on('error', () => undefined);
+}
+function announce(line) {
+    // Also guarded synchronously: an already-closed or non-writable stdout throws from `write`
+    // itself rather than emitting.
+    try {
+        process.stdout.write(line);
+    }
+    catch {
+        // Nothing to report to, and nothing about the runtime is wrong.
+    }
+}

package/dist/execution/lsp-process.d.ts

@@ -0,0 +1,14 @@
+export declare class LspProcess {
+    #private;
+    readonly maxFrameBytes: number;
+    readonly maxBufferBytes: number;
+    constructor(command: string, args: readonly string[], cwd: string, maxFrameBytes: number, maxBufferBytes: number);
+    get pid(): number | undefined;
+    get initialized(): boolean;
+    get closed(): boolean;
+    markInitialized(): void;
+    request(method: string, params: unknown, signal?: AbortSignal, allowClosing?: boolean): Promise<unknown>;
+    notify(method: string, params: unknown, allowClosing?: boolean): void;
+    drainNotifications(): readonly unknown[];
+    close(): Promise<void>;
+}