@jitsusama/agentic-harness.core 0.1.0

package/dist/lsp/config.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Server discovery: a built-in default map, a config-override
+ * chain, and the resolution that routes a file to the server
+ * and project root that should serve it.
+ *
+ * The model follows omp's proven design: declare servers by
+ * the file types they handle and the root markers that mark a
+ * project, detect binaries rather than install them, and bind
+ * one server per resolved root. We ship the servers we use and
+ * grow the map, rather than omp's full catalogue.
+ */
+/** One server's declaration: how to run it and what it serves. */
+export interface ServerConfig {
+    /** Stable server name, the pool key's first half. */
+    readonly name: string;
+    /** Executable to spawn, resolved local-bin-first then on PATH. */
+    readonly command: string;
+    /** Arguments passed to the executable. */
+    readonly args: readonly string[];
+    /** File extensions (with the dot) this server handles. */
+    readonly fileTypes: readonly string[];
+    /** Files or dirs whose presence marks a project root. */
+    readonly rootMarkers: readonly string[];
+    /** LSP initialize options, passed through untouched. */
+    readonly initOptions?: Record<string, unknown>;
+    /**
+     * Resolve the command and args to run for a given project root,
+     * overriding the static command and args. Returns null when no
+     * compatible server exists for that project, so the backend
+     * degrades with a clear message instead of spawning one that
+     * cannot serve. Lets the TypeScript entry pick between the
+     * native LSP and the classic wrapper by the installed version.
+     */
+    readonly resolve?: (root: string, env: NodeJS.ProcessEnv) => {
+        command: string;
+        args: readonly string[];
+    } | null;
+    /** A disabled server is never spawned. */
+    readonly disabled?: boolean;
+    /** Linters and formatters contribute diagnostics only. */
+    readonly isLinter?: boolean;
+}
+/**
+ * The built-in server map. TypeScript first; Go and Ruby and
+ * the rest arrive as the harness reaches for them.
+ */
+export declare const DEFAULT_SERVERS: Readonly<Record<string, ServerConfig>>;
+/**
+ * The major version of the TypeScript package installed nearest to
+ * `fromDir`, walking up through node_modules, or null when none is
+ * found or its version cannot be read.
+ */
+export declare function typescriptMajorAt(fromDir: string): number | null;
+/** A server matched to a file, with the root it should run at. */
+export interface ResolvedServer {
+    readonly server: ServerConfig;
+    readonly root: string;
+}
+/**
+ * Candidate servers for a file: every non-disabled server
+ * whose fileTypes include the file's extension. A file can
+ * match a type server plus one or more linters.
+ */
+export declare function serversForFile(filePath: string, servers?: Readonly<Record<string, ServerConfig>>): ServerConfig[];
+/**
+ * The nearest ancestor directory of `filePath` that contains
+ * one of `rootMarkers`, or null when none is found up to the
+ * filesystem root.
+ */
+export declare function resolveRoot(filePath: string, rootMarkers: readonly string[]): string | null;
+/**
+ * Resolve a command to an executable path, preferring a
+ * project-local bin (`node_modules/.bin`, `.venv/bin` walked
+ * up from `fromDir`) over `$PATH`. Returns null when nothing
+ * resolves, so the caller can degrade to a clear message.
+ */
+export declare function resolveBinary(command: string, fromDir: string, env?: NodeJS.ProcessEnv): string | null;

package/dist/lsp/config.js

@@ -0,0 +1,154 @@
+/**
+ * Server discovery: a built-in default map, a config-override
+ * chain, and the resolution that routes a file to the server
+ * and project root that should serve it.
+ *
+ * The model follows omp's proven design: declare servers by
+ * the file types they handle and the root markers that mark a
+ * project, detect binaries rather than install them, and bind
+ * one server per resolved root. We ship the servers we use and
+ * grow the map, rather than omp's full catalogue.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { delimiter, dirname, join } from "node:path";
+/**
+ * The built-in server map. TypeScript first; Go and Ruby and
+ * the rest arrive as the harness reaches for them.
+ */
+export const DEFAULT_SERVERS = {
+    typescript: {
+        name: "typescript",
+        // The command and args are the TypeScript 7 default; `resolve`
+        // picks the actual server per project by its installed version.
+        command: "tsc",
+        args: ["--lsp", "--stdio"],
+        fileTypes: [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"],
+        rootMarkers: ["tsconfig.json", "jsconfig.json", "package.json"],
+        resolve: resolveTypescriptServer,
+    },
+};
+/**
+ * The major version of the TypeScript package installed nearest to
+ * `fromDir`, walking up through node_modules, or null when none is
+ * found or its version cannot be read.
+ */
+export function typescriptMajorAt(fromDir) {
+    let dir = fromDir;
+    while (true) {
+        const pkg = join(dir, "node_modules", "typescript", "package.json");
+        if (existsSync(pkg)) {
+            try {
+                const { version } = JSON.parse(readFileSync(pkg, "utf8"));
+                const major = Number.parseInt(String(version).split(".")[0], 10);
+                return Number.isNaN(major) ? null : major;
+            }
+            catch {
+                // An unreadable or malformed package.json tells us nothing.
+                return null;
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/**
+ * Choose the TypeScript language server for a project by its
+ * installed TypeScript version. TypeScript 7 and newer ship a
+ * native LSP reached through `tsc --lsp`; older releases need the
+ * classic tsserver wrapper, typescript-language-server. Returns
+ * null when neither is usable, so an older project without the
+ * wrapper degrades with a clear message rather than spawning a
+ * tsc that cannot speak LSP.
+ */
+function resolveTypescriptServer(root, env) {
+    const native = { command: "tsc", args: ["--lsp", "--stdio"] };
+    const classic = { command: "typescript-language-server", args: ["--stdio"] };
+    const has = (command) => resolveBinary(command, root, env) !== null;
+    const major = typescriptMajorAt(root);
+    if (major !== null && major < 7) {
+        return has(classic.command) ? classic : null;
+    }
+    // TypeScript 7 or newer, or an unknown version (tsc 7 is the
+    // current default): prefer the native server, fall back to the
+    // classic wrapper only if tsc is somehow absent.
+    if (has(native.command))
+        return native;
+    return has(classic.command) ? classic : null;
+}
+/**
+ * Candidate servers for a file: every non-disabled server
+ * whose fileTypes include the file's extension. A file can
+ * match a type server plus one or more linters.
+ */
+export function serversForFile(filePath, servers = DEFAULT_SERVERS) {
+    const ext = extname(filePath);
+    return Object.values(servers).filter((server) => !server.disabled && server.fileTypes.includes(ext));
+}
+/**
+ * The nearest ancestor directory of `filePath` that contains
+ * one of `rootMarkers`, or null when none is found up to the
+ * filesystem root.
+ */
+export function resolveRoot(filePath, rootMarkers) {
+    let dir = dirname(filePath);
+    while (true) {
+        for (const marker of rootMarkers) {
+            if (existsSync(join(dir, marker)))
+                return dir;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/**
+ * Resolve a command to an executable path, preferring a
+ * project-local bin (`node_modules/.bin`, `.venv/bin` walked
+ * up from `fromDir`) over `$PATH`. Returns null when nothing
+ * resolves, so the caller can degrade to a clear message.
+ */
+export function resolveBinary(command, fromDir, env = process.env) {
+    // An explicit path (absolute or containing a separator) is
+    // honoured as-is, so a config override can point straight at
+    // a nix store path or a custom binary.
+    if (command.includes("/"))
+        return existsSync(command) ? command : null;
+    const local = resolveLocalBin(command, fromDir);
+    if (local)
+        return local;
+    return resolveOnPath(command, env);
+}
+const LOCAL_BIN_DIRS = ["node_modules/.bin", ".venv/bin"];
+function resolveLocalBin(command, fromDir) {
+    let dir = fromDir;
+    while (true) {
+        for (const binDir of LOCAL_BIN_DIRS) {
+            const candidate = join(dir, binDir, command);
+            if (existsSync(candidate))
+                return candidate;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+function resolveOnPath(command, env) {
+    const path = env.PATH ?? "";
+    for (const entry of path.split(delimiter)) {
+        if (!entry)
+            continue;
+        const candidate = join(entry, command);
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+function extname(filePath) {
+    const base = filePath.slice(filePath.lastIndexOf("/") + 1);
+    const dot = base.lastIndexOf(".");
+    return dot <= 0 ? "" : base.slice(dot);
+}

package/dist/lsp/external.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Validation for LSP backends registered from another process or
+ * package boundary. A payload that crosses a trust boundary from
+ * a third-party emitter is rejected rather than trusted.
+ */
+import type { LspBackendEntry } from "./types.js";
+/**
+ * Validate an event payload as a backend entry, or return null when it
+ * does not structurally satisfy the contract. Checks the entry fields
+ * and that the backend carries every operation as a function plus a
+ * string name.
+ */
+export declare function toBackendEntry(data: unknown): LspBackendEntry | null;

package/dist/lsp/external.js

@@ -0,0 +1,52 @@
+/**
+ * Validation for LSP backends registered from another process or
+ * package boundary. A payload that crosses a trust boundary from
+ * a third-party emitter is rejected rather than trusted.
+ */
+/** Method names every backend must provide as functions. */
+const BACKEND_METHODS = [
+    "diagnostics",
+    "definition",
+    "references",
+    "hover",
+    "documentSymbols",
+    "workspaceSymbols",
+    "rename",
+    "codeActions",
+    "dispose",
+];
+/** Whether every value in the object is a function under the given keys. */
+function hasFunctions(value, keys) {
+    return keys.every((key) => typeof value[key] === "function");
+}
+/**
+ * Validate an event payload as a backend entry, or return null when it
+ * does not structurally satisfy the contract. Checks the entry fields
+ * and that the backend carries every operation as a function plus a
+ * string name.
+ */
+export function toBackendEntry(data) {
+    if (typeof data !== "object" || data === null)
+        return null;
+    const record = data;
+    if (typeof record.name !== "string" || record.name.length === 0)
+        return null;
+    if (typeof record.priority !== "number")
+        return null;
+    if (typeof record.isAvailable !== "function")
+        return null;
+    const backend = record.backend;
+    if (typeof backend !== "object" || backend === null)
+        return null;
+    const backendRecord = backend;
+    if (typeof backendRecord.name !== "string")
+        return null;
+    if (!hasFunctions(backendRecord, BACKEND_METHODS))
+        return null;
+    return {
+        name: record.name,
+        priority: record.priority,
+        isAvailable: record.isAvailable,
+        backend: backend,
+    };
+}

package/dist/lsp/format.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Plain-text rendering for LSP operation results. Shared by every
+ * adapter's tool/CLI output -- pure string formatting, no I/O.
+ */
+import type { CodeAction, Diagnostic, HoverInfo, LspLocation, SymbolInfo, WorkspaceEdit } from "./types.js";
+export declare function formatDiagnostics(diagnostics: readonly Diagnostic[]): string;
+export declare function formatLocations(locations: readonly LspLocation[]): string;
+export declare function formatSymbols(symbols: readonly SymbolInfo[]): string;
+export declare function formatHover(hover: HoverInfo): string;
+export declare function formatCodeActions(actions: readonly CodeAction[]): string;
+export declare function formatWorkspaceEdit(edit: WorkspaceEdit): string;

package/dist/lsp/format.js

@@ -0,0 +1,54 @@
+/**
+ * Plain-text rendering for LSP operation results. Shared by every
+ * adapter's tool/CLI output -- pure string formatting, no I/O.
+ */
+export function formatDiagnostics(diagnostics) {
+    if (diagnostics.length === 0)
+        return "No problems reported.";
+    return diagnostics
+        .map((d) => {
+        const where = `${d.path}:${d.range.start.line}:${d.range.start.character}`;
+        const tail = [d.source, d.code].filter(Boolean).join(" ");
+        return `${d.severity} ${where} ${d.message}${tail ? ` (${tail})` : ""}`;
+    })
+        .join("\n");
+}
+export function formatLocations(locations) {
+    if (locations.length === 0)
+        return "No results.";
+    return locations
+        .map((l) => `${l.path}:${l.range.start.line}:${l.range.start.character}`)
+        .join("\n");
+}
+export function formatSymbols(symbols) {
+    if (symbols.length === 0)
+        return "No symbols.";
+    return symbols
+        .map((s) => {
+        const where = `${s.location.path}:${s.location.range.start.line}`;
+        const container = s.containerName ? ` in ${s.containerName}` : "";
+        return `${s.kind} ${s.name}${container} (${where})`;
+    })
+        .join("\n");
+}
+export function formatHover(hover) {
+    return hover.contents.trim() || "No hover information.";
+}
+export function formatCodeActions(actions) {
+    if (actions.length === 0)
+        return "No code actions.";
+    return actions
+        .map((a) => (a.kind ? `${a.title} [${a.kind}]` : a.title))
+        .join("\n");
+}
+export function formatWorkspaceEdit(edit) {
+    if (edit.changes.length === 0)
+        return "Rename made no changes.";
+    const files = edit.changes.length;
+    const edits = edit.changes.reduce((n, c) => n + c.edits.length, 0);
+    const lines = edit.changes.map((c) => `- ${c.path}: ${c.edits.length} edits`);
+    return [
+        `Renamed and wrote ${edits} edits across ${files} files:`,
+        ...lines,
+    ].join("\n");
+}

package/dist/lsp/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Public surface of the LSP library.
+ *
+ * Semantic code intelligence behind one backend-agnostic
+ * contract. This package ships a standalone backend that spawns
+ * and supervises language servers itself; a downstream package
+ * (an editor integration, say) registers its own backend at a
+ * lower priority to take over when paired. Consumers resolve the
+ * active backend with `resolveLspBackend` and call the
+ * `LspBackend` operations without knowing which backend answered.
+ */
+export { DEFAULT_SERVERS, type ServerConfig } from "./config.js";
+export { toBackendEntry } from "./external.js";
+export { formatCodeActions, formatDiagnostics, formatHover, formatLocations, formatSymbols, formatWorkspaceEdit, } from "./format.js";
+export { clearLspBackends, getLspBackend, listLspBackends, registerLspBackend, resolveLspBackend, unregisterLspBackend, } from "./registry.js";
+export { createStandaloneBackend, MissingServerError, type StandaloneBackend, type StandaloneBackendOptions, } from "./standalone/backend.js";
+export type { CodeAction, Diagnostic, DiagnosticSeverity, HoverInfo, LspBackend, LspBackendEntry, LspLocation, LspPosition, LspRange, LspTarget, LspTextEdit, SymbolInfo, WorkspaceEdit, } from "./types.js";

package/dist/lsp/index.js

@@ -0,0 +1,16 @@
+/**
+ * Public surface of the LSP library.
+ *
+ * Semantic code intelligence behind one backend-agnostic
+ * contract. This package ships a standalone backend that spawns
+ * and supervises language servers itself; a downstream package
+ * (an editor integration, say) registers its own backend at a
+ * lower priority to take over when paired. Consumers resolve the
+ * active backend with `resolveLspBackend` and call the
+ * `LspBackend` operations without knowing which backend answered.
+ */
+export { DEFAULT_SERVERS } from "./config.js";
+export { toBackendEntry } from "./external.js";
+export { formatCodeActions, formatDiagnostics, formatHover, formatLocations, formatSymbols, formatWorkspaceEdit, } from "./format.js";
+export { clearLspBackends, getLspBackend, listLspBackends, registerLspBackend, resolveLspBackend, unregisterLspBackend, } from "./registry.js";
+export { createStandaloneBackend, MissingServerError, } from "./standalone/backend.js";

package/dist/lsp/offsets.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Column translation between the tool's UTF-8 byte columns
+ * and LSP's UTF-16 code-unit columns, both 0-indexed.
+ *
+ * A JavaScript string is already a sequence of UTF-16 code
+ * units, so `ch.length` gives a code point's unit width (1
+ * or 2). The byte width comes from the code point's value.
+ */
+/**
+ * Map a 0-indexed UTF-8 byte column to its 0-indexed UTF-16
+ * code-unit column. A byte column past the line's end clamps
+ * to the line's unit length; one that lands inside a
+ * multi-byte character rounds up to the next boundary.
+ */
+export declare function byteToUtf16(lineText: string, byteColumn: number): number;
+/**
+ * Map a 0-indexed UTF-16 code-unit column to its 0-indexed
+ * UTF-8 byte column. A unit column past the line's end
+ * clamps to the line's byte length; one that lands inside a
+ * surrogate pair rounds up to the next boundary.
+ */
+export declare function utf16ToByte(lineText: string, utf16Column: number): number;

package/dist/lsp/offsets.js

@@ -0,0 +1,51 @@
+/**
+ * Column translation between the tool's UTF-8 byte columns
+ * and LSP's UTF-16 code-unit columns, both 0-indexed.
+ *
+ * A JavaScript string is already a sequence of UTF-16 code
+ * units, so `ch.length` gives a code point's unit width (1
+ * or 2). The byte width comes from the code point's value.
+ */
+function utf8ByteLength(codePoint) {
+    if (codePoint < 0x80)
+        return 1;
+    if (codePoint < 0x800)
+        return 2;
+    if (codePoint < 0x10000)
+        return 3;
+    return 4;
+}
+/**
+ * Map a 0-indexed UTF-8 byte column to its 0-indexed UTF-16
+ * code-unit column. A byte column past the line's end clamps
+ * to the line's unit length; one that lands inside a
+ * multi-byte character rounds up to the next boundary.
+ */
+export function byteToUtf16(lineText, byteColumn) {
+    let bytes = 0;
+    let units = 0;
+    for (const ch of lineText) {
+        if (bytes >= byteColumn)
+            return units;
+        bytes += utf8ByteLength(ch.codePointAt(0) ?? 0);
+        units += ch.length;
+    }
+    return units;
+}
+/**
+ * Map a 0-indexed UTF-16 code-unit column to its 0-indexed
+ * UTF-8 byte column. A unit column past the line's end
+ * clamps to the line's byte length; one that lands inside a
+ * surrogate pair rounds up to the next boundary.
+ */
+export function utf16ToByte(lineText, utf16Column) {
+    let units = 0;
+    let bytes = 0;
+    for (const ch of lineText) {
+        if (units >= utf16Column)
+            return bytes;
+        units += ch.length;
+        bytes += utf8ByteLength(ch.codePointAt(0) ?? 0);
+    }
+    return bytes;
+}

package/dist/lsp/registry.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Backend registration and resolution. Mirrors the tree and
+ * terminal libraries: explicit registration, a resolve that
+ * ranks by priority, and an opt-out clear for tests.
+ *
+ * Resolution picks the available backend with the lowest
+ * priority number. The standalone backend registers at 100;
+ * a downstream editor-forwarding backend registers below that
+ * and reports itself available only under its own precondition,
+ * so it takes over transparently when present.
+ */
+import type { LspBackend, LspBackendEntry } from "./types.js";
+/** Register or overwrite a backend entry. */
+export declare function registerLspBackend(entry: LspBackendEntry): void;
+/** Remove a backend by name. Idempotent. */
+export declare function unregisterLspBackend(name: string): void;
+/** Look up a backend entry by name. */
+export declare function getLspBackend(name: string): LspBackendEntry | undefined;
+/** Snapshot of every registered backend entry. */
+export declare function listLspBackends(): LspBackendEntry[];
+/**
+ * Resolve the active backend: the available entry with the
+ * lowest priority number, or undefined when none is
+ * available.
+ */
+export declare function resolveLspBackend(): LspBackend | undefined;
+/** Empty the registry. Intended for tests. */
+export declare function clearLspBackends(): void;

package/dist/lsp/registry.js

@@ -0,0 +1,45 @@
+/**
+ * Backend registration and resolution. Mirrors the tree and
+ * terminal libraries: explicit registration, a resolve that
+ * ranks by priority, and an opt-out clear for tests.
+ *
+ * Resolution picks the available backend with the lowest
+ * priority number. The standalone backend registers at 100;
+ * a downstream editor-forwarding backend registers below that
+ * and reports itself available only under its own precondition,
+ * so it takes over transparently when present.
+ */
+import { clear, get, list, register, unregister, } from "../internal/lsp/registry.js";
+/** Register or overwrite a backend entry. */
+export function registerLspBackend(entry) {
+    register(entry);
+}
+/** Remove a backend by name. Idempotent. */
+export function unregisterLspBackend(name) {
+    unregister(name);
+}
+/** Look up a backend entry by name. */
+export function getLspBackend(name) {
+    return get(name);
+}
+/** Snapshot of every registered backend entry. */
+export function listLspBackends() {
+    return list();
+}
+/**
+ * Resolve the active backend: the available entry with the
+ * lowest priority number, or undefined when none is
+ * available.
+ */
+export function resolveLspBackend() {
+    const ranked = [...list()].sort((a, b) => a.priority - b.priority);
+    for (const entry of ranked) {
+        if (entry.isAvailable())
+            return entry.backend;
+    }
+    return undefined;
+}
+/** Empty the registry. Intended for tests. */
+export function clearLspBackends() {
+    clear();
+}

package/dist/lsp/standalone/backend.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The standalone backend: routing plus a live server pool.
+ *
+ * Every operation carries a file, so the file is the routing
+ * key. The backend resolves the file's candidate servers,
+ * walks up to each server's project root, resolves its binary
+ * local-bin-first then on PATH, and reuses or spawns one
+ * server per (serverName, root). Type-intelligence operations
+ * route to the single non-linter server for the root, while
+ * diagnostics aggregate across every server attached to the
+ * file. When nothing resolves, it fails with a clear message
+ * rather than a cryptic one.
+ *
+ * The live server pool lives in this closure's memory for the
+ * life of the process that constructs it. A stateless-per-call
+ * CLI adapter that wants warm servers across invocations needs
+ * its own keep-alive design on top of this (the same shape as
+ * quest's on-disk state file, or core/browser's file-backed
+ * session registry) -- not something this module does itself.
+ */
+import { type ServerConfig } from "../config.js";
+import type { LspBackend } from "../types.js";
+/** Raised when no server can serve a file, with why per candidate. */
+export declare class MissingServerError extends Error {
+    constructor(filePath: string, reasons: readonly string[]);
+}
+/** Options for constructing a standalone backend. */
+export interface StandaloneBackendOptions {
+    /** Server map to route against. Defaults to the built-in map. */
+    readonly servers?: Readonly<Record<string, ServerConfig>>;
+    /** Environment used for PATH resolution. Defaults to process.env. */
+    readonly env?: NodeJS.ProcessEnv;
+}
+/** A standalone backend with visibility into its live pool. */
+export interface StandaloneBackend extends LspBackend {
+    /** Number of live servers currently pooled. */
+    serverCount(): number;
+    /** Re-sync a document after the caller edited it. */
+    syncDocument(path: string, text: string): void;
+}
+/** Construct a standalone backend over the given (or default) server map. */
+export declare function createStandaloneBackend(options?: StandaloneBackendOptions): StandaloneBackend;