@knightcodeai/cli 0.17.4 → 0.18.1

package/examples/sdk/14-codemode-mcp.ts

@@ -0,0 +1,61 @@
+/**
+ * Codemode, Tool Search, and MCP
+ *
+ * The CLI loads `codemode`, `tool_search`, and MCP as built-in extensions. SDK sessions add
+ * them to the resource loader's extension factories.
+ *
+ * `codemode` and `tool_search` are registered inactive. Enable them through the `defaultTools` setting
+ * (`tools` would also restrict the session to the named tools, which hides MCP tools), or let the
+ * MCP extension activate them: `codemode` for servers with `codemode` exposure, `tool_search` for
+ * servers with `deferred` exposure.
+ */
+
+import {
+	createAgentSession,
+	createCodemodeExtension,
+	createMcpExtension,
+	createToolSearchExtension,
+	DefaultResourceLoader,
+	getAgentDir,
+	SessionManager,
+	SettingsManager,
+} from "@knightcodeai/cli";
+
+const cwd = process.cwd();
+
+const resourceLoader = new DefaultResourceLoader({
+	cwd,
+	agentDir: getAgentDir(),
+	extensionFactories: [
+		createCodemodeExtension({ mode: "on" }),
+		createToolSearchExtension(),
+		// Reads mcp.json from the agent directory and the trusted project, like the CLI.
+		createMcpExtension(),
+	],
+});
+await resourceLoader.reload();
+
+const settingsManager = SettingsManager.create(cwd);
+// `+name` adds to the configured default tools instead of replacing them.
+settingsManager.applyOverrides({ defaultTools: ["+codemode", "+tool_search"] });
+
+const { session } = await createAgentSession({
+	resourceLoader,
+	settingsManager,
+	sessionManager: SessionManager.inMemory(),
+});
+
+try {
+	// Emits session_start, which connects the MCP servers in the background.
+	await session.bindExtensions({});
+	console.log("Active tools:", session.getActiveToolNames().join(", "));
+	session.subscribe((event) => {
+		if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+			process.stdout.write(event.assistantMessageEvent.delta);
+		}
+	});
+	await session.prompt("Use codemode to count the TypeScript files in src/ and list the three largest.");
+	console.log();
+} finally {
+	session.dispose();
+}

package/examples/sdk/README.md

@@ -0,0 +1,141 @@
+# SDK Examples
+
+Programmatic usage of @knightcodeai/cli via `createAgentSession()` and `createAgentSessionRuntime()`.
+
+The runtime example shows how to build a recreate function that closes over process-global fixed inputs and recreates cwd-bound services and sessions as the active session cwd changes.
+
+## Examples
+
+| File | Description |
+|------|-------------|
+| `01-minimal.ts` | Simplest usage with all defaults |
+| `02-custom-model.ts` | Select model and thinking level |
+| `03-custom-prompt.ts` | Replace or modify system prompt |
+| `04-skills.ts` | Discover, filter, or replace skills |
+| `05-tools.ts` | Built-in tool allowlists |
+| `06-extensions.ts` | Logging, blocking, result modification |
+| `07-context-files.ts` | AGENTS.md context files |
+| `08-prompt-templates.ts` | File-based prompt templates |
+| `09-api-keys-and-oauth.ts` | API key resolution, OAuth config |
+| `10-settings.ts` | Override compaction, retry, terminal settings |
+| `11-sessions.ts` | In-memory, persistent, continue, list sessions |
+| `12-full-control.ts` | Replace everything, no discovery |
+| `13-session-runtime.ts` | Manage runtime-backed session replacement |
+| `14-codemode-mcp.ts` | Add the `codemode`, `tool_search`, and MCP extensions |
+
+## Running
+
+```bash
+cd packages/cli
+bun examples/sdk/01-minimal.ts
+```
+
+## Quick Reference
+
+```typescript
+import { getModel } from "@knightcode/ai";
+import {
+  createAgentSession,
+  DefaultResourceLoader,
+  ModelRuntime,
+  SessionManager,
+  SettingsManager,
+} from "@knightcodeai/cli";
+
+const modelRuntime = await ModelRuntime.create();
+
+// Minimal
+const { session } = await createAgentSession({ modelRuntime });
+
+// Custom model
+const model = getModel("anthropic", "claude-opus-4-5");
+const { session } = await createAgentSession({ model, thinkingLevel: "high", modelRuntime });
+
+// Modify prompt
+const loader = new DefaultResourceLoader({
+  systemPromptOverride: (base) => `${base}\n\nBe concise.`,
+});
+await loader.reload();
+const { session } = await createAgentSession({ resourceLoader: loader, modelRuntime });
+
+// Read-only
+const { session } = await createAgentSession({ tools: ["read", "grep", "find", "ls"], modelRuntime });
+
+// In-memory
+const { session } = await createAgentSession({
+  sessionManager: SessionManager.inMemory(),
+  modelRuntime,
+});
+
+// Full control
+const customRuntime = await ModelRuntime.create({
+  authPath: "/my/app/auth.json",
+  modelsPath: "/my/app/models.json",
+});
+await customRuntime.setRuntimeApiKey("anthropic", process.env.MY_KEY!);
+
+const resourceLoader = new DefaultResourceLoader({
+  systemPromptOverride: () => "You are helpful.",
+  extensionFactories: [myExtension],
+  skillsOverride: () => ({ skills: [], diagnostics: [] }),
+  agentsFilesOverride: () => ({ agentsFiles: [] }),
+  promptsOverride: () => ({ prompts: [], diagnostics: [] }),
+});
+await resourceLoader.reload();
+
+const { session } = await createAgentSession({
+  model,
+  modelRuntime: customRuntime,
+  resourceLoader,
+  tools: ["read", "bash", "my_tool"],
+  customTools: [myTool],
+  sessionManager: SessionManager.inMemory(),
+  settingsManager: SettingsManager.inMemory(),
+});
+
+// Run prompts
+session.subscribe((event) => {
+  if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+    process.stdout.write(event.assistantMessageEvent.delta);
+  }
+});
+await session.prompt("Hello");
+```
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `modelRuntime` | Runtime using `agentDir/auth.json` and `models.json` | Canonical model and authentication runtime |
+| `cwd` | `process.cwd()` | Working directory |
+| `agentDir` | `~/.knightcode/agent` | Config directory |
+| `model` | From settings/first available | Model to use |
+| `thinkingLevel` | From settings/"off" | off, low, medium, high |
+| `tools` | `["read", "bash", "edit", "write"]` built-ins | Allowlist tool names across built-in, extension, and custom tools |
+| `customTools` | `[]` | Additional tool definitions |
+| `resourceLoader` | DefaultResourceLoader | Resource loader for extensions, skills, prompts, themes, and context files |
+| `sessionManager` | `SessionManager.create(cwd)` | Persistence |
+| `settingsManager` | `SettingsManager.create(cwd, agentDir)` | Settings overrides |
+
+## Events
+
+```typescript
+session.subscribe((event) => {
+  switch (event.type) {
+    case "message_update":
+      if (event.assistantMessageEvent.type === "text_delta") {
+        process.stdout.write(event.assistantMessageEvent.delta);
+      }
+      break;
+    case "tool_execution_start":
+      console.log(`Tool: ${event.toolName}`);
+      break;
+    case "tool_execution_end":
+      console.log(`Result: ${event.result}`);
+      break;
+    case "agent_settled":
+      console.log("Done");
+      break;
+  }
+});
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knightcodeai/cli",
-  "version": "0.17.4",
+  "version": "0.18.1",
   "description": "KnightCode — a local, BYOK terminal coding agent powered by OpenRouter.",
   "type": "module",
   "repository": {
@@ -13,7 +13,7 @@
     "configDir": ".knightcode"
   },
   "bin": {
-    "knightcode": "./bin/knightcode"
+    "knightcode": "./dist/bundle/cli.js"
   },
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -24,35 +24,37 @@
     "./*": "./src/*.ts"
   },
   "files": [
-    "bin/",
-    "README.md"
+    "dist/",
+    "docs/",
+    "examples/",
+    "README.md",
+    "CHANGELOG.md"
   ],
   "engines": {
-    "node": ">=22"
+    "node": ">=22.19.0"
   },
   "scripts": {
     "dev": "bun --env-file=../../.env run --watch src/bun/cli.ts",
     "start": "bun --env-file=../../.env run src/bun/cli.ts",
     "check-types": "tsc --noEmit -p ../../tsconfig.json",
     "test": "vitest --run",
-    "generate:schemas": "bun scripts/generate-schemas.ts"
+    "generate:schemas": "bun scripts/generate-schemas.ts",
+    "generate:references": "bun scripts/generate-references.ts"
   },
-  "optionalDependencies": {
-    "@knightcodeai/cli-linux-x64": "0.17.4",
-    "@knightcodeai/cli-linux-arm64": "0.17.4",
-    "@knightcodeai/cli-darwin-x64": "0.17.4",
-    "@knightcodeai/cli-darwin-arm64": "0.17.4",
-    "@knightcodeai/cli-win32-x64": "0.17.4"
+  "dependencies": {
+    "@silvia-odwyer/photon-node": "0.3.4",
+    "jiti": "2.7.0",
+    "quickjs-wasi": "3.6.2"
   },
   "devDependencies": {
     "@knightcode/agent": "workspace:*",
     "@knightcode/ai": "workspace:*",
+    "@knightcode/app-server-protocol": "workspace:*",
     "@knightcode/codemode": "workspace:*",
     "@knightcode/mcp": "workspace:*",
     "@knightcode/remote": "workspace:*",
     "@knightcode/tools": "workspace:*",
     "@knightcode/tui": "workspace:*",
-    "@silvia-odwyer/photon-node": "0.3.4",
     "@types/cross-spawn": "6.0.6",
     "@types/hosted-git-info": "3.0.5",
     "@types/proper-lockfile": "4.1.4",
@@ -65,11 +67,9 @@
     "highlight.js": "10.7.3",
     "hosted-git-info": "9.0.3",
     "ignore": "7.0.8",
-    "jiti": "2.7.0",
     "marked": "18.0.11",
     "minimatch": "10.2.6",
     "proper-lockfile": "4.1.2",
-    "quickjs-wasi": "3.6.2",
     "semver": "7.8.5",
     "typebox": "1.3.27",
     "undici": "8.10.2",

package/bin/knightcode

@@ -1,62 +0,0 @@
-#!/usr/bin/env node
-// Dependency-free launcher: resolves the platform-specific compiled binary
-// (shipped as an optional dependency) and spawns it, forwarding args, stdio,
-// signals, and the exit code. Uses only Node builtins.
-import { spawn } from "node:child_process";
-import { createRequire } from "node:module";
-
-const require = createRequire(import.meta.url);
-
-const forwardedSignals = ["SIGINT", "SIGTERM", "SIGHUP"];
-
-function run(target) {
-  const child = spawn(target, process.argv.slice(2), {
-    stdio: "inherit",
-  });
-
-  child.on("error", (error) => {
-    console.error(error.message);
-    process.exit(1);
-  });
-
-  const forwarders = {};
-  for (const signal of forwardedSignals) {
-    forwarders[signal] = () => {
-      try {
-        child.kill(signal);
-      } catch {
-        // The child may have already exited.
-      }
-    };
-    process.on(signal, forwarders[signal]);
-  }
-
-  child.on("exit", (code, signal) => {
-    for (const s of forwardedSignals) process.removeListener(s, forwarders[s]);
-    if (signal) {
-      process.kill(process.pid, signal);
-      return;
-    }
-    process.exit(typeof code === "number" ? code : 0);
-  });
-}
-
-const pkg = `@knightcodeai/cli-${process.platform}-${process.arch}`;
-const binary = process.platform === "win32" ? "knightcode.exe" : "knightcode";
-
-let target = process.env.KNIGHTCODE_BIN_PATH;
-if (!target) {
-  try {
-    target = require.resolve(`${pkg}/bin/${binary}`);
-  } catch {
-    console.error(
-      `knightcode: no prebuilt binary for ${process.platform}-${process.arch}.\n` +
-        `Your package manager may have skipped the optional dependency "${pkg}".\n` +
-        `Reinstall the CLI with your package manager (npm, yarn, pnpm, or bun), ` +
-        `or set KNIGHTCODE_BIN_PATH to a local knightcode binary.`,
-    );
-    process.exit(1);
-  }
-}
-
-run(target);