@openlucaskaka/kagent 0.1.7

package/npm/lib/update-manager.js

@@ -0,0 +1,334 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UPDATE_CHECK_TIMEOUT_MS = exports.UPDATE_CHECK_TTL_MS = exports.NPM_REGISTRY_URL = void 0;
+exports.resolveUpdateChannel = resolveUpdateChannel;
+exports.compareSemVer = compareSemVer;
+exports.checkForUpdate = checkForUpdate;
+exports.runUpgrade = runUpgrade;
+exports.NPM_REGISTRY_URL = "https://registry.npmjs.org/%40openlucaskaka%2Fkagent";
+exports.UPDATE_CHECK_TTL_MS = 24 * 60 * 60 * 1_000;
+exports.UPDATE_CHECK_TIMEOUT_MS = 3_000;
+const INSTALL_ARGS = {
+    latest: ["install", "--global", "@openlucaskaka/kagent@latest"],
+    next: ["install", "--global", "@openlucaskaka/kagent@next"],
+};
+class UpdateNetworkError extends Error {
+}
+class UpdateMetadataError extends Error {
+}
+function resolveUpdateChannel(env = process.env) {
+    const configured = env.KAGENT_UPDATE_CHANNEL?.trim().toLowerCase();
+    if (!configured || configured === "stable" || configured === "latest") {
+        return "latest";
+    }
+    if (configured === "beta" || configured === "next") {
+        return "next";
+    }
+    throw new Error(`KAGENT_UPDATE_CHANNEL ${JSON.stringify(configured)} is invalid; expected stable/latest or beta/next`);
+}
+function compareSemVer(left, right) {
+    const parsedLeft = parseSemVer(left);
+    const parsedRight = parseSemVer(right);
+    for (let index = 0; index < parsedLeft.core.length; index += 1) {
+        const compared = compareNumericIdentifier(parsedLeft.core[index], parsedRight.core[index]);
+        if (compared !== 0) {
+            return compared;
+        }
+    }
+    if (parsedLeft.prerelease === null && parsedRight.prerelease === null) {
+        return 0;
+    }
+    if (parsedLeft.prerelease === null) {
+        return 1;
+    }
+    if (parsedRight.prerelease === null) {
+        return -1;
+    }
+    const identifiers = Math.max(parsedLeft.prerelease.length, parsedRight.prerelease.length);
+    for (let index = 0; index < identifiers; index += 1) {
+        const leftIdentifier = parsedLeft.prerelease[index];
+        const rightIdentifier = parsedRight.prerelease[index];
+        if (leftIdentifier === undefined) {
+            return -1;
+        }
+        if (rightIdentifier === undefined) {
+            return 1;
+        }
+        const compared = comparePrereleaseIdentifier(leftIdentifier, rightIdentifier);
+        if (compared !== 0) {
+            return compared;
+        }
+    }
+    return 0;
+}
+async function checkForUpdate(options) {
+    parseSemVer(options.currentVersion);
+    const deps = options.deps ?? {};
+    const channel = resolveCheckChannel(options.channel, options.env);
+    const now = deps.now?.() ?? new Date();
+    const checkedAt = now.toISOString();
+    let cacheWarning;
+    if (!options.force && deps.readState) {
+        let cached;
+        try {
+            cached = await deps.readState();
+        }
+        catch (error) {
+            cacheWarning = `Unable to read update cache: ${errorMessage(error)}`;
+        }
+        if (isFreshState(cached, channel, now)) {
+            return {
+                current: options.currentVersion,
+                latest: cached.latest,
+                channel,
+                updateAvailable: compareSemVer(cached.latest, options.currentVersion) > 0,
+                checkedAt: cached.checkedAt,
+                skipped: true,
+                reason: "ttl",
+            };
+        }
+    }
+    let latest;
+    try {
+        latest = await fetchLatestVersion(channel, deps);
+    }
+    catch (error) {
+        const message = errorMessage(error);
+        if (options.force) {
+            if (error instanceof UpdateNetworkError) {
+                throw new Error(`Unable to check for kagent updates: ${message}`);
+            }
+            throw error;
+        }
+        return skippedCheck(options.currentVersion, channel, checkedAt, error instanceof UpdateMetadataError
+            ? "metadata-error"
+            : "network-error", error);
+    }
+    const state = { channel, latest, checkedAt };
+    try {
+        await deps.writeState?.(state);
+    }
+    catch (error) {
+        if (options.force) {
+            throw error;
+        }
+        const warning = `Unable to write update cache: ${errorMessage(error)}`;
+        cacheWarning = cacheWarning ? `${cacheWarning}; ${warning}` : warning;
+    }
+    return {
+        current: options.currentVersion,
+        latest,
+        channel,
+        updateAvailable: compareSemVer(latest, options.currentVersion) > 0,
+        checkedAt,
+        ...(cacheWarning ? { cacheWarning } : {}),
+    };
+}
+function resolveCheckChannel(channel, env) {
+    if (channel === undefined) {
+        return resolveUpdateChannel(env);
+    }
+    if (channel === "latest" || channel === "next") {
+        return channel;
+    }
+    throw new Error(`Update channel ${JSON.stringify(channel)} is invalid; expected latest or next`);
+}
+function skippedCheck(current, channel, checkedAt, reason, error) {
+    return {
+        current,
+        latest: null,
+        channel,
+        updateAvailable: false,
+        checkedAt,
+        skipped: true,
+        reason,
+        error: errorMessage(error),
+    };
+}
+async function runUpgrade(options) {
+    const deps = options.deps ?? {};
+    const checked = await checkForUpdate({
+        currentVersion: options.currentVersion,
+        channel: options.channel,
+        force: true,
+        env: options.env,
+        deps,
+    });
+    if (checked.latest === null) {
+        throw new Error("Forced update checks cannot be skipped");
+    }
+    if (!checked.updateAvailable) {
+        return {
+            ...checked,
+            upgraded: false,
+            installedVersion: options.currentVersion,
+        };
+    }
+    if (!deps.runInstall || !deps.readInstalledVersion) {
+        throw new Error("runUpgrade requires runInstall and readInstalledVersion dependencies");
+    }
+    const installArgs = INSTALL_ARGS[checked.channel];
+    const installSpec = installArgs[2];
+    try {
+        await deps.runInstall([...installArgs]);
+    }
+    catch (error) {
+        throw new Error(`Failed to install ${installSpec}: ${errorMessage(error)}`);
+    }
+    let installedVersion;
+    try {
+        installedVersion = await deps.readInstalledVersion();
+    }
+    catch (error) {
+        throw new Error(`Unable to verify the installed kagent version: ${errorMessage(error)}`);
+    }
+    try {
+        if (compareSemVer(installedVersion, checked.latest) < 0) {
+            throw new Error(`Installed version ${installedVersion} is below expected version ${checked.latest}`);
+        }
+    }
+    catch (error) {
+        if (error instanceof Error && /below expected version/.test(error.message)) {
+            throw error;
+        }
+        throw new Error(`Unable to verify installed version ${JSON.stringify(installedVersion)}: ${errorMessage(error)}`);
+    }
+    return { ...checked, upgraded: true, installedVersion };
+}
+function parseSemVer(version) {
+    const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/.exec(version);
+    if (!match) {
+        throw new Error(`Invalid SemVer: ${JSON.stringify(version)}`);
+    }
+    const prerelease = match[4]?.split(".") ?? null;
+    if (prerelease?.some((identifier) => /^\d+$/.test(identifier) && /^0\d/.test(identifier))) {
+        throw new Error(`Invalid SemVer: ${JSON.stringify(version)}`);
+    }
+    return {
+        core: [match[1], match[2], match[3]],
+        prerelease,
+    };
+}
+function compareNumericIdentifier(left, right) {
+    if (left.length !== right.length) {
+        return left.length < right.length ? -1 : 1;
+    }
+    return left === right ? 0 : left < right ? -1 : 1;
+}
+function comparePrereleaseIdentifier(left, right) {
+    const leftNumeric = /^\d+$/.test(left);
+    const rightNumeric = /^\d+$/.test(right);
+    if (leftNumeric && rightNumeric) {
+        return compareNumericIdentifier(left, right);
+    }
+    if (leftNumeric !== rightNumeric) {
+        return leftNumeric ? -1 : 1;
+    }
+    return left === right ? 0 : left < right ? -1 : 1;
+}
+function isFreshState(state, channel, now) {
+    if (!state || state.channel !== channel) {
+        return false;
+    }
+    const checkedAt = Date.parse(state.checkedAt);
+    const age = now.getTime() - checkedAt;
+    if (!Number.isFinite(checkedAt) || age < 0 || age >= exports.UPDATE_CHECK_TTL_MS) {
+        return false;
+    }
+    try {
+        parseSemVer(state.latest);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function fetchLatestVersion(channel, deps) {
+    const fetchFn = deps.fetch ?? defaultFetch;
+    const timeoutMs = deps.timeoutMs ?? exports.UPDATE_CHECK_TIMEOUT_MS;
+    const controller = new AbortController();
+    let timedOut = false;
+    let timer;
+    const timeout = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+            reject(new Error(`Registry request timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+    });
+    try {
+        let response;
+        try {
+            response = await Promise.race([
+                fetchFn(exports.NPM_REGISTRY_URL, { signal: controller.signal }),
+                timeout,
+            ]);
+        }
+        catch (error) {
+            const message = timedOut
+                ? `Registry request timed out after ${timeoutMs}ms`
+                : errorMessage(error);
+            throw new UpdateNetworkError(message);
+        }
+        if (!response.ok) {
+            releaseFailedResponse(response, controller);
+            throw new UpdateNetworkError(`npm registry returned HTTP ${response.status}`);
+        }
+        let metadata;
+        try {
+            metadata = await Promise.race([response.json(), timeout]);
+        }
+        catch (error) {
+            if (timedOut) {
+                throw new UpdateNetworkError(`Registry request timed out after ${timeoutMs}ms`);
+            }
+            if (error instanceof TypeError) {
+                throw new UpdateNetworkError(errorMessage(error));
+            }
+            throw new UpdateMetadataError(`npm registry metadata is not valid JSON: ${errorMessage(error)}`);
+        }
+        if (!isRecord(metadata)) {
+            throw new UpdateMetadataError("npm registry metadata must be a JSON object");
+        }
+        const distTags = metadata["dist-tags"];
+        if (!isRecord(distTags)) {
+            throw new UpdateMetadataError("npm registry metadata must contain dist-tags");
+        }
+        const version = distTags[channel];
+        if (typeof version !== "string" || !version.trim()) {
+            throw new UpdateMetadataError(`npm registry dist-tags.${channel} must be non-empty`);
+        }
+        try {
+            parseSemVer(version);
+        }
+        catch (error) {
+            throw new UpdateMetadataError(`npm registry dist-tags.${channel} is not valid SemVer: ${errorMessage(error)}`);
+        }
+        return version;
+    }
+    finally {
+        if (timer !== undefined) {
+            clearTimeout(timer);
+        }
+    }
+}
+function releaseFailedResponse(response, controller) {
+    try {
+        void response.body?.cancel().catch(() => undefined);
+    }
+    finally {
+        controller.abort();
+    }
+}
+function defaultFetch(input, init) {
+    if (typeof globalThis.fetch !== "function") {
+        return Promise.reject(new Error("global fetch is unavailable"));
+    }
+    return globalThis.fetch(input, init);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@openlucaskaka/kagent",
+  "version": "0.1.7",
+  "description": "Codex-style LangGraph agent runtime for internal non-coding workflows.",
+  "license": "UNLICENSED",
+  "bin": {
+    "kagent": "npm/bin/kagent.js",
+    "kagent-serve": "npm/bin/kagent-serve.js"
+  },
+  "files": [
+    "README.md",
+    "pyproject.toml",
+    "src",
+    "npm/bin",
+    "npm/lib"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "ink": "^5.0.1",
+    "react": "^18.3.1",
+    "string-width": "^4.2.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.15",
+    "@types/react": "^18.3.3",
+    "typescript": "^5.5.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "npm run build:cli",
+    "build:cli": "tsc -p tsconfig.json",
+    "test:cli": "npm run build:cli && node --test npm/lib/*.test.js",
+    "check": "npm run build:cli && node --test npm/lib/*.test.js && node --check npm/bin/kagent.js && node --check npm/bin/kagent-serve.js && node --check npm/lib/ink-runner.js && node --check npm/lib/python-runner.js"
+  }
+}

package/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["setuptools>=61", "wheel>=0.45,<1"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "kagent"
+version = "0.1.7"
+description = "A bounded kagent built with LangGraph."
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = [
+    "langgraph>=0.6.11,<0.7",
+    "prompt_toolkit>=3.0,<4",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8,<9",
+    "ruff>=0.8,<1",
+    "setuptools>=61",
+    "wheel>=0.45,<1",
+]
+
+[project.scripts]
+kagent = "kagent.cli:main"
+kagent-batch = "kagent.ops.batch:main"
+kagent-doctor = "kagent.ops.doctor:main"
+kagent-eval = "kagent.eval.evaluator:main"
+kagent-metrics = "kagent.ops.metrics:main"
+kagent-release-evidence = "kagent.ops.release_evidence:main"
+kagent-release-manifest = "kagent.ops.release_manifest:main"
+kagent-serve = "kagent.service:main"
+kagent-trace-prune = "kagent.service.trace_store:main"
+kagent-trace-replay = "kagent.ops.trace_replay:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+kagent = ["py.typed"]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]
+filterwarnings = [
+    "ignore:urllib3 v2 only supports OpenSSL 1.1.1+:urllib3.exceptions.NotOpenSSLWarning",
+    "ignore:The default value of `allowed_objects` will change in a future version:langchain_core._api.deprecation.LangChainPendingDeprecationWarning",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]

package/src/kagent/__init__.py

@@ -0,0 +1,90 @@
+"""kagent LangGraph agent package."""
+
+import re
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+
+def _source_tree_version() -> str:
+    for parent in Path(__file__).resolve().parents:
+        pyproject_path = parent / "pyproject.toml"
+        if not pyproject_path.exists():
+            continue
+        pyproject = pyproject_path.read_text(encoding="utf-8")
+        if 'name = "kagent"' not in pyproject:
+            continue
+        match = re.search(r'(?m)^version = "([^"]+)"$', pyproject)
+        if match:
+            return match.group(1)
+    return ""
+
+
+try:
+    __version__ = _source_tree_version() or version("kagent")
+except PackageNotFoundError:
+    __version__ = "0.1.7"
+
+__all__ = [
+    "AgentConfig",
+    "AgentStatus",
+    "FakeLLMProvider",
+    "LLMProviderConfig",
+    "ProviderKind",
+    "__version__",
+    "agent_topology",
+    "build_agent_graph",
+    "detect_provider_kind",
+    "evaluate_agent",
+    "preview_plan",
+    "registered_evaluation_cases",
+    "registered_tool_metadata",
+    "registered_tool_names",
+    "runtime_topology",
+    "run_agent",
+    "run_runtime_agent",
+    "summarize_run",
+]
+
+
+def __getattr__(name):
+    if name in {
+        "AgentConfig",
+        "AgentStatus",
+        "agent_topology",
+        "build_agent_graph",
+        "preview_plan",
+        "run_agent",
+    }:
+        from kagent.core import agent
+
+        return getattr(agent, name)
+    if name in {"evaluate_agent", "registered_evaluation_cases"}:
+        from kagent.eval import evaluator
+
+        return getattr(evaluator, name)
+    if name in {
+        "FakeLLMProvider",
+        "LLMProviderConfig",
+        "ProviderKind",
+        "detect_provider_kind",
+    }:
+        from kagent.providers import llm_provider
+
+        return getattr(llm_provider, name)
+    if name == "run_runtime_agent":
+        from kagent.runtime import run_runtime_agent
+
+        return run_runtime_agent
+    if name == "runtime_topology":
+        from kagent.runtime import runtime_topology
+
+        return runtime_topology
+    if name == "summarize_run":
+        from kagent.core.summary import summarize_run
+
+        return summarize_run
+    if name in {"registered_tool_metadata", "registered_tool_names"}:
+        from kagent.core import tools
+
+        return getattr(tools, name)
+    raise AttributeError(name)

package/src/kagent/cli/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from kagent.cli.main import _run_runtime_interactive, main
+
+__all__ = ["_run_runtime_interactive", "main"]

package/src/kagent/cli/__main__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from kagent.cli.main import main
+
+if __name__ == "__main__":
+    main()

package/src/kagent/cli/commands.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from difflib import get_close_matches
+
+
+@dataclass(frozen=True)
+class RuntimeInteractiveCommand:
+    primary: str
+    description: str
+    section: str
+    aliases: tuple[str, ...] = ()
+
+
+_RUNTIME_INTERACTIVE_COMMANDS: tuple[RuntimeInteractiveCommand, ...] = (
+    RuntimeInteractiveCommand("/pwd", "show working directory", "Session", ("/cwd",)),
+    RuntimeInteractiveCommand("/cd PATH", "change working directory", "Session", ("/cd",)),
+    RuntimeInteractiveCommand("/status", "show shell state", "Session", ("/stat",)),
+    RuntimeInteractiveCommand("/memory", "review compact memory", "Session", ("/mem",)),
+    RuntimeInteractiveCommand(
+        "/compact-memory",
+        "compact remembered context now",
+        "Session",
+        ("/compress-memory",),
+    ),
+    RuntimeInteractiveCommand("/clear", "clear remembered turns", "Session", ("/clear-memory",)),
+    RuntimeInteractiveCommand(
+        "/reset",
+        "clear memory and prompt history",
+        "Session",
+        ("/reset-session",),
+    ),
+    RuntimeInteractiveCommand("/last", "replay last answer", "Session", ("/last-run",)),
+    RuntimeInteractiveCommand(
+        "/config",
+        "show redacted provider config",
+        "Provider",
+        ("/provider",),
+    ),
+    RuntimeInteractiveCommand("/tools", "show available actions", "Provider", ("/actions",)),
+    RuntimeInteractiveCommand(
+        "/compact",
+        "clean transcript",
+        "Output",
+        ("/summary",),
+    ),
+    RuntimeInteractiveCommand(
+        "/json",
+        "full JSON traces",
+        "Output",
+        ("/full", "/debug"),
+    ),
+    RuntimeInteractiveCommand("/trace", "last JSON trace once", "Output", ("/last-json",)),
+    RuntimeInteractiveCommand(
+        "/save-trace PATH",
+        "save last JSON trace",
+        "Output",
+        ("/export-trace",),
+    ),
+    RuntimeInteractiveCommand(
+        "/doctor",
+        "show local diagnostics",
+        "Debug",
+        ("/diagnostics",),
+    ),
+    RuntimeInteractiveCommand("/help", "command palette", "Debug", ("/?",)),
+    RuntimeInteractiveCommand("exit", "quit", "Debug", ("quit", ":q")),
+)
+
+
+def runtime_interactive_commands() -> tuple[RuntimeInteractiveCommand, ...]:
+    return _RUNTIME_INTERACTIVE_COMMANDS
+
+
+def runtime_interactive_completion_words() -> list[str]:
+    words: list[str] = []
+    for command in _RUNTIME_INTERACTIVE_COMMANDS:
+        for word in (command.primary.split()[0], *command.aliases):
+            if word not in words:
+                words.append(word)
+    return words
+
+
+def is_runtime_interactive_command(text: str) -> bool:
+    command_name = _runtime_command_name(text)
+    if not command_name:
+        return False
+    return command_name in runtime_interactive_completion_words()
+
+
+def runtime_interactive_command_suggestions(text: str) -> list[str]:
+    command_name = _runtime_command_name(text)
+    if not command_name:
+        return []
+    return get_close_matches(
+        command_name,
+        runtime_interactive_completion_words(),
+        n=3,
+        cutoff=0.55,
+    )
+
+
+def runtime_interactive_command_usage(text: str) -> str:
+    command_name = _runtime_command_name(text)
+    for command in _RUNTIME_INTERACTIVE_COMMANDS:
+        if command_name == command.primary.split()[0] or command_name in command.aliases:
+            return command.primary
+    return ""
+
+
+def _runtime_command_name(text: str) -> str:
+    return str(text).strip().split(maxsplit=1)[0].lower()