@lensagent/core 0.1.0

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@lensagent/core",
+  "version": "0.1.0",
+  "description": "Lens Harness kernel and HTTP server.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LensAgent/lens-core.git"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/launch.d.ts",
+      "import": "./dist/launch.js"
+    }
+  },
+  "types": "./dist/launch.d.ts",
+  "bin": {
+    "lens-core": "dist/entry/node.js"
+  },
+  "lens": {
+    "component": "lens-core",
+    "protocols": {
+      "facet-core-api": 4,
+      "core-executor-rpc": 4
+    }
+  },
+  "files": [
+    "dist",
+    "proto",
+    "config/lens.example.jsonc",
+    "config/pair.example.json",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@ai-sdk/anthropic": "4.0.30",
+    "@ai-sdk/openai": "4.0.30",
+    "@ai-sdk/openai-compatible": "3.0.23",
+    "@grpc/grpc-js": "1.14.4",
+    "@grpc/proto-loader": "0.8.1",
+    "@sinclair/typebox": "0.34.52",
+    "ai": "7.0.52",
+    "ajv": "8.20.0",
+    "better-sqlite3": "13.0.3",
+    "fastify": "5.11.2",
+    "json-canonicalize": "2.0.0",
+    "jsonc-parser": "3.3.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "9.39.2",
+    "@types/better-sqlite3": "7.6.13",
+    "@types/node": "24.10.1",
+    "eslint": "9.39.2",
+    "tsx": "4.21.0",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.53.1"
+  },
+  "scripts": {
+    "build": "node --input-type=module -e \"import{rmSync}from'node:fs';rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
+    "dev": "tsx src/entry/node.ts",
+    "start": "node dist/entry/node.js",
+    "storage:rebuild": "tsx src/entry/rebuild.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint .",
+    "secret-scan": "node scripts/secret-scan.mjs"
+  }
+}

package/proto/executor.proto

@@ -0,0 +1,314 @@
+syntax = "proto3";
+
+package lens.executor.v1;
+
+service Executor {
+  rpc Health(HealthRequest) returns (HealthResponse);
+  rpc Identity(IdentityRequest) returns (IdentityResponse);
+  rpc Shutdown(ShutdownRequest) returns (ShutdownResponse);
+  rpc ReadFile(ReadFileRequest) returns (ReadFileResponse);
+  rpc WriteFile(WriteFileRequest) returns (WriteFileResponse);
+  rpc EditFile(EditFileRequest) returns (EditFileResponse);
+  rpc RevertCall(RevertCallRequest) returns (RevertCallResponse);
+  rpc DescribeCallHistory(DescribeCallHistoryRequest) returns (DescribeCallHistoryResponse);
+  rpc DeleteCallHistory(DeleteCallHistoryRequest) returns (DeleteCallHistoryResponse);
+  rpc Glob(GlobRequest) returns (GlobResponse);
+  rpc Grep(GrepRequest) returns (GrepResponse);
+  rpc BrowseProject(BrowseProjectRequest) returns (BrowseProjectResponse);
+  rpc RunCommand(RunCommandRequest) returns (RunCommandResponse);
+  rpc GitRun(GitRunRequest) returns (GitRunResponse);
+  rpc InternetSearch(InternetSearchRequest) returns (InternetSearchResponse);
+  rpc ListAllowedParent(ListAllowedParentRequest) returns (ListAllowedParentResponse);
+  rpc ValidateWorkspacePaths(ValidateWorkspacePathsRequest) returns (ValidateWorkspacePathsResponse);
+  rpc OpenInFileManager(OpenInFileManagerRequest) returns (OpenInFileManagerResponse);
+  rpc ChooseWorkspaceFolder(ChooseWorkspaceFolderRequest) returns (ChooseWorkspaceFolderResponse);
+}
+
+message HealthRequest {}
+message HealthResponse {
+  string status = 1;
+  string allowed_parent_dir = 2;
+  // Where the file history lives and a stable id for that store. A new state_id from the same
+  // Executor means the store was replaced and every earlier Call is now unrevertable.
+  string state_dir = 3;
+  string state_id = 4;
+  string state_created_at = 5;
+}
+
+// Identity for an external process manager: which program answers this port, which independent
+// software version it is, which integer protocol version it speaks, and which OS process serves it.
+//
+// Deliberately separate from Health rather than added to it. Health requires a verified client and
+// reports allowed_parent_dir and state_dir, so it cannot answer a manager: identifying the process
+// is what a manager does *before* it can be verified, and it has to work while the Executor is
+// unhealthy. This message therefore carries no filesystem paths and no client-identifying values,
+// which is what lets it be served without verification.
+message IdentityRequest {}
+message IdentityResponse {
+  string component = 1;
+  string software_version = 2;
+  // Compared against the adjacent component by strict equality. Not SemVer, no ranges.
+  map<string, int32> protocols = 3;
+  int32 pid = 4;
+  string status = 5;
+}
+
+// Graceful stop as a component control path rather than an OS signal. Served without client
+// verification for the same reason as Identity -- stopping an Executor whose pair file is invalid
+// is the main case -- and therefore restricted to loopback callers, since the listen host may be
+// reachable from a LAN and an unauthenticated remote stop would be a trivial denial of service.
+message ShutdownRequest {}
+message ShutdownResponse {
+  string status = 1;
+  string component = 2;
+  string software_version = 3;
+  map<string, int32> protocols = 4;
+  int32 pid = 5;
+}
+
+message ReadFileRequest {
+  repeated string workspace_paths = 1;
+  string path = 2;
+  bool full_access = 3;
+}
+message ReadFileResponse {
+  string content = 1;
+  bool truncated = 2;
+}
+
+message WriteFileRequest {
+  repeated string workspace_paths = 1;
+  string path = 2;
+  string content = 3;
+  bool full_access = 4;
+  // Identify the change in the Executor's file history. Both are required: the Executor records
+  // the exact before/after bytes under (workspace_id, call_id) so RevertCall can restore them.
+  string workspace_id = 5;
+  string call_id = 6;
+}
+message WriteFileResponse {
+  string relative_path = 1;
+  int64 bytes = 2;
+}
+
+message EditFileRequest {
+  repeated string workspace_paths = 1;
+  string path = 2;
+  string old_string = 3;
+  string new_string = 4;
+  bool replace_all = 5;
+  bool full_access = 6;
+  string workspace_id = 7;
+  string call_id = 8;
+}
+message EditFileResponse {
+  string relative_path = 1;
+  int32 replacements = 2;
+  int64 bytes = 3;
+}
+
+// Restores the files recorded for one or more previous WriteFile/EditFile Calls. The Executor
+// orders them by its own per-Workspace sequence and verifies, for every path, that the content on
+// disk is still what the Call left behind. Any mismatch is reported in `conflicts` and nothing is
+// written unless `force` is set.
+message RevertCallRequest {
+  repeated string workspace_paths = 1;
+  string workspace_id = 2;
+  repeated string call_ids = 3;
+  bool force = 4;
+  bool full_access = 5;
+  // The reverting Call itself, recorded as a new change so a revert can be reverted.
+  string call_id = 6;
+}
+message RevertCallResponse {
+  repeated RevertedCall calls = 1;
+  repeated RevertConflict conflicts = 2;
+}
+message RevertedCall {
+  string call_id = 1;
+  repeated RevertedFile files = 2;
+}
+message RevertedFile {
+  string path = 1;
+  // restored | deleted
+  string action = 2;
+}
+message RevertConflict {
+  string call_id = 1;
+  string path = 2;
+  // content_changed: the file no longer holds what the Call wrote.
+  // unresolved: the record's outcome could not be determined.
+  // missing_record: this Workspace has history, but not for that Call id.
+  // no_history: this Workspace has no history store at all.
+  // outside_workspace: the recorded path is no longer inside the Workspace roots. `force` never
+  //   waives this one -- it is a containment boundary, not a content disagreement.
+  string reason = 3;
+}
+
+// Answers what RevertCall would do right now, without doing it. Runs the identical simulation, so a
+// clean preview and a failing revert cannot disagree about the same input. Read-only: the answer is
+// a snapshot another writer can invalidate, so RevertCall re-simulates rather than trusting it.
+message DescribeCallHistoryRequest {
+  repeated string workspace_paths = 1;
+  string workspace_id = 2;
+  repeated string call_ids = 3;
+  bool full_access = 4;
+}
+message DescribeCallHistoryResponse {
+  bool revertable = 1;
+  repeated DescribedCall calls = 2;
+  repeated RevertConflict conflicts = 3;
+  // The net effect on each path if the revert ran now.
+  repeated RevertedFile files = 4;
+}
+message DescribedCall {
+  string call_id = 1;
+  bool found = 2;
+  // PREPARED | COMMITTED | ABORTED | UNKNOWN, empty when found is false.
+  string status = 3;
+  int64 sequence = 4;
+  repeated string paths = 5;
+}
+
+// Drops the recorded history for these Calls, making them permanently unrevertable, and frees the
+// objects. Driven by Core's controlled cleanup: the Executor never expires history on its own.
+message DeleteCallHistoryRequest {
+  string workspace_id = 1;
+  repeated string call_ids = 2;
+}
+message DeleteCallHistoryResponse {
+  int32 deleted = 1;
+  int32 missing = 2;
+}
+
+message GlobRequest {
+  repeated string workspace_paths = 1;
+  string pattern = 2;
+  string path = 3;
+  bool include_hidden = 4;
+  int32 max_results = 5;
+  bool full_access = 6;
+}
+message GlobResponse {
+  repeated string matches = 1;
+  int32 count = 2;
+  bool truncated = 3;
+}
+
+message GrepRequest {
+  repeated string workspace_paths = 1;
+  string pattern = 2;
+  string path = 3;
+  string glob = 4;
+  bool include_hidden = 5;
+  bool literal = 6;
+  bool case_insensitive = 7;
+  int32 max_results = 8;
+  int32 max_bytes_per_file = 9;
+  bool full_access = 10;
+}
+message GrepMatch {
+  string path = 1;
+  int32 line = 2;
+  string text = 3;
+}
+message GrepResponse {
+  repeated GrepMatch matches = 1;
+  int32 count = 2;
+  bool truncated = 3;
+}
+
+message BrowseProjectRequest {
+  repeated string workspace_paths = 1;
+  string path = 2;
+  bool full_access = 3;
+}
+message BrowseEntry {
+  string name = 1;
+  bool is_directory = 2;
+}
+message BrowseProjectResponse {
+  string relative_path = 1;
+  repeated BrowseEntry entries = 2;
+}
+
+message RunCommandRequest {
+  repeated string workspace_paths = 1;
+  string command = 2;
+  repeated string args = 3;
+  string cwd = 4;
+  map<string, string> env = 5;
+  int32 timeout_ms = 6;
+  int32 output_limit_bytes = 7;
+  bool full_access = 8;
+}
+message RunCommandResponse {
+  int32 exit_code = 1;
+  string signal = 2;
+  string stdout = 3;
+  string stderr = 4;
+  int64 duration_ms = 5;
+  bool stdout_truncated = 6;
+  bool stderr_truncated = 7;
+}
+
+message GitRunRequest {
+  repeated string workspace_paths = 1;
+  repeated string args = 2;
+  string cwd = 3;
+  int32 timeout_ms = 4;
+  int32 output_limit_bytes = 5;
+  bool full_access = 6;
+}
+message GitRunResponse {
+  int32 exit_code = 1;
+  string stdout = 2;
+  string stderr = 3;
+  int64 duration_ms = 4;
+  bool stdout_truncated = 5;
+  bool stderr_truncated = 6;
+}
+
+message InternetSearchRequest {
+  string query = 1;
+  int32 max_results = 2;
+}
+message SearchResult {
+  string title = 1;
+  string url = 2;
+  string snippet = 3;
+}
+message InternetSearchResponse {
+  repeated SearchResult results = 1;
+  string provider = 2;
+}
+
+message ListAllowedParentRequest { string path = 1; }
+message ListAllowedParentResponse {
+  string allowed_parent_dir = 1;
+  string relative_path = 2;
+  repeated BrowseEntry entries = 3;
+}
+message ValidateWorkspacePathsRequest {
+  repeated string workspace_paths = 1;
+  bool create_if_missing = 2;
+}
+message ValidateWorkspacePathsResponse {
+  repeated string resolved_paths = 1;
+  bool created = 2;
+}
+message OpenInFileManagerRequest {
+  repeated string workspace_paths = 1;
+  string path = 2;
+  bool full_access = 3;
+}
+message OpenInFileManagerResponse {
+  string opened_path = 1;
+  string platform = 2;
+}
+message ChooseWorkspaceFolderRequest {}
+message ChooseWorkspaceFolderResponse {
+  bool cancelled = 1;
+  string chosen_path = 2;
+  string platform = 3;
+}