@truss-harness/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Truss contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,93 @@
+# Truss CLI
+
+<p align="center"><img src="./logo.png" width="96" alt="Truss logo"></p>
+
+Truss is a local-first coding-agent runtime. The CLI runs one-shot agent tasks and hosts the runtime service used by editor clients.
+
+## Requirements
+
+- Node.js 20 or newer
+- Ollama, LM Studio, llama.cpp, or another compatible local model server
+- A model with native tool calling for Agent and Plan workflows
+
+## Install
+
+```sh
+npm install -g @truss-harness/cli
+```
+
+The global installer prints a short first-run checklist. You can display the complete reference at any time:
+
+```sh
+truss-cli
+truss-cli help
+```
+
+## First run
+
+Start your local model server, open a terminal in the project you want Truss to work on, and run:
+
+```sh
+truss-cli models
+truss-cli chat "Explain this workspace"
+```
+
+Truss probes the standard Ollama, LM Studio, and llama.cpp endpoints when no model is configured. Create a reusable workspace profile when you want explicit settings:
+
+```sh
+truss-cli config init
+truss-cli config path
+```
+
+## Agent tasks
+
+```sh
+truss-cli chat --mode chat "Explain the architecture"
+truss-cli chat --mode plan "Plan an authentication refactor"
+truss-cli chat --mode edit "Fix the failing tests"
+truss-cli chat --internet-access "Check the current library documentation"
+```
+
+Direct CLI chat is non-interactive and auto-allows registered tools. Run it only in a trusted workspace. Public internet tools are disabled unless `--internet-access`, a profile, or the environment explicitly enables them.
+
+## Workspace commands
+
+These deterministic commands work without a configured model:
+
+```text
+truss-cli init                 Create or refresh generated AGENTS.md context
+truss-cli update [note]        Record Git state and a durable handoff note
+truss-cli status               Show Git state and recent durable records
+truss-cli clear-memory         Remove durable workspace memory
+truss-cli commands             Show slash commands used by interactive clients
+```
+
+## Configuration
+
+`truss-cli config init` creates `.truss-harness/config.json`. Profiles support `provider`, `baseUrl`, `model`, `mode`, `permission`, `internetAccess`, `systemPrompt`, `apiKeyEnv`, and `mcpServers`.
+
+```json
+{
+  "defaultProfile": "ollama",
+  "profiles": {
+    "ollama": {
+      "provider": "ollama",
+      "baseUrl": "http://127.0.0.1:11434",
+      "model": "qwen3:8b",
+      "mode": "edit",
+      "permission": "ask",
+      "internetAccess": false
+    }
+  }
+}
+```
+
+Keep endpoint tokens out of JSON. Set the token in an environment variable and place that variable's name in `apiKeyEnv`.
+
+MCP stdio servers can be defined under `mcpServers`. User-level definitions load normally. Workspace definitions can launch local processes and are ignored unless the user configuration sets `"allowWorkspaceMcpServers": true`. Plan mode loads only servers marked `"readOnly": true`; Agent mode loads all enabled servers. MCP calls follow the selected approval policy.
+
+## Service mode
+
+`truss-cli serve` starts the newline-delimited JSON runtime protocol used by clients such as the VS Code extension. Standard output is reserved for protocol messages.
+
+Run `truss-cli help` for every command, flag, environment variable, mode, permission policy, and example.

package/dist/bin.d.ts

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

package/dist/bin.js

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+import { cwd } from "node:process";
+import { detectLocalEndpoints, listLocalModels } from "@truss-harness/provider-openai-compatible";
+import { brand } from "@truss-harness/branding";
+import { executeWorkspaceCommand, workspaceCommandHelp } from "@truss-harness/runtime";
+import { createClientRuntime } from "./runtime.js";
+import { configurationPaths, initializeWorkspaceConfiguration, parseConfigurationOverrides, resolveConfiguration } from "./config.js";
+import { ProtocolToolApproval, runService } from "./protocol.js";
+const help = `${brand.productName} CLI
+
+Local-first coding agent and runtime service.
+
+Usage:
+  ${brand.cliCommand} <command> [options]
+
+Quick start:
+  1. Start Ollama, LM Studio, llama.cpp, or a compatible local server.
+  2. Run: ${brand.cliCommand} models
+  3. Run: ${brand.cliCommand} chat "Explain this workspace"
+  4. Optional: ${brand.cliCommand} config init
+
+Commands:
+  chat <prompt>          Stream one agent response in the current workspace
+  models                List detected local servers and models
+  config path           Print user and workspace configuration paths
+  config init           Create a workspace configuration template
+  init                  Create or refresh generated AGENTS.md workspace context
+  update [note]         Record Git state and a durable handoff note
+  status                Show Git state and recent durable agent records
+  clear-memory          Delete this workspace's durable agent memory
+  commands              Print slash commands shared by interactive clients
+  serve                 Start the JSONL runtime service for editor clients
+  help                  Show this reference
+
+Options:
+  --profile <name>       Select a named configuration profile
+  --provider <name>      ollama or openai-compatible
+  --base-url <url>       Local server endpoint
+  --model <name>         Model identifier
+  --mode <name>          chat, plan, or edit
+  --permission <name>    ask, auto-read, or auto-all
+  --internet-access      Enable public web search and page fetching
+  --no-internet-access   Disable internet tools
+
+Modes:
+  chat                   Conversation only; optional internet tools
+  plan                   Read-only inspection and a saved implementation plan
+  edit                   Filesystem, planning, and terminal tools
+
+Permissions:
+  ask                    Ask interactive clients before each tool
+  auto-read              Auto-allow workspace reads; ask for writes, commands, and web
+  auto-all               Auto-allow every registered tool
+
+  Direct '${brand.cliCommand} chat' runs non-interactively and auto-allows tools.
+  Use it only in a trusted workspace. Internet tools remain off unless enabled.
+
+Environment:
+  TRUSS_HARNESS_MODEL       Required model identifier
+  TRUSS_HARNESS_PROVIDER    ollama (default) or openai-compatible
+  TRUSS_HARNESS_BASE_URL    Local server base URL (default depends on provider)
+  TRUSS_HARNESS_AGENT_MODE  chat (default), plan, or edit
+  TRUSS_HARNESS_PERMISSION_MODE ask (default), auto-read, or auto-all
+  TRUSS_HARNESS_INTERNET_ACCESS true or 1 to enable public web tools
+  TRUSS_HARNESS_API_KEY     Optional bearer token
+  TRUSS_HARNESS_SYSTEM_PROMPT Optional system prompt
+  TRUSS_HARNESS_MCP_SERVERS JSON object containing local stdio MCP servers
+
+Examples:
+  ${brand.cliCommand} chat --mode plan "Plan the authentication change"
+  ${brand.cliCommand} chat --mode edit "Fix the failing tests"
+  ${brand.cliCommand} chat --internet-access "Check the current library documentation"
+  ${brand.cliCommand} chat --profile lm-studio "Review the active file structure"
+
+${workspaceCommandHelp()}
+`;
+async function main() {
+    const [command = "help", ...rawArgs] = process.argv.slice(2);
+    if (command === "help" || command === "--help" || command === "-h") {
+        process.stdout.write(help);
+        return;
+    }
+    if (command === "models") {
+        const endpoints = await detectLocalEndpoints();
+        const models = await Promise.all(endpoints.map(async (endpoint) => ({ endpoint, models: await listLocalModels(endpoint) })));
+        process.stdout.write(`${JSON.stringify(models, null, 2)}\n`);
+        return;
+    }
+    if (command === "config") {
+        const [action = "path"] = rawArgs;
+        const paths = configurationPaths(cwd());
+        if (action === "path") {
+            process.stdout.write(`${JSON.stringify(paths, null, 2)}\n`);
+            return;
+        }
+        if (action === "init") {
+            process.stdout.write(`Created ${await initializeWorkspaceConfiguration(cwd(), paths)}\n`);
+            return;
+        }
+        throw new Error(`Use ${brand.cliCommand} config path or ${brand.cliCommand} config init`);
+    }
+    const { overrides, rest: args } = parseConfigurationOverrides(rawArgs);
+    const workspaceCommand = command === "init" ? "/init"
+        : command === "update" ? `/update ${args.join(" ")}`.trim()
+            : command === "status" ? "/status"
+                : command === "clear-memory" ? "/clear-memory"
+                    : command === "commands" ? "/help"
+                        : undefined;
+    if (workspaceCommand) {
+        const result = await executeWorkspaceCommand({ workspaceRoot: cwd(), input: workspaceCommand });
+        process.stdout.write(`${result.message}\n`);
+        if (!result.ok)
+            process.exitCode = 1;
+        return;
+    }
+    if (command === "chat") {
+        const prompt = args.join(" ").trim();
+        if (!prompt)
+            throw new Error(`Provide a prompt: ${brand.cliCommand} chat <prompt>`);
+        const result = await executeWorkspaceCommand({ workspaceRoot: cwd(), input: prompt });
+        if (result.handled) {
+            process.stdout.write(`${result.message}\n`);
+            if (!result.ok)
+                process.exitCode = 1;
+            return;
+        }
+    }
+    const configuration = await resolveConfiguration({ workspaceRoot: cwd(), overrides });
+    if (command === "serve") {
+        const approval = new ProtocolToolApproval(configuration.permission);
+        const client = await createClientRuntime({ ...configuration, approval });
+        for (const server of client.mcpServers) {
+            process.stderr.write(`[mcp] ${server.name}: ${server.state}${server.error ? ` (${server.error})` : ` (${server.toolCount} tools)`}\n`);
+        }
+        try {
+            await runService(client.runtime, client.events, approval);
+        }
+        finally {
+            await client.dispose();
+        }
+        return;
+    }
+    const client = await createClientRuntime(configuration);
+    const { runtime, events } = client;
+    for (const server of client.mcpServers) {
+        process.stderr.write(`[mcp] ${server.name}: ${server.state}${server.error ? ` (${server.error})` : ` (${server.toolCount} tools)`}\n`);
+    }
+    if (command === "chat") {
+        const prompt = args.join(" ").trim();
+        events.subscribe((event) => {
+            if (event.type === "text_delta")
+                process.stdout.write(event.text);
+            if (event.type === "tool_call_requested")
+                process.stderr.write(`\n[tool] ${event.tool}\n`);
+            if (event.type === "plan_updated") {
+                process.stderr.write(`\n[plan] ${event.plan.title}\n${event.plan.steps.map((step) => `  ${step.status === "completed" ? "[x]" : step.status === "in_progress" ? "[..]" : "[ ]"} ${step.content}`).join("\n")}\n`);
+            }
+        });
+        try {
+            const session = await runtime.createSession();
+            await runtime.run(session.id, prompt);
+            process.stdout.write("\n");
+        }
+        finally {
+            await client.dispose();
+        }
+        return;
+    }
+    throw new Error(`Unknown command: ${command}\n\n${help}`);
+}
+main().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+});

package/dist/config.d.ts

@@ -0,0 +1,49 @@
+import { type McpServerConfigurations } from "@truss-harness/mcp";
+import { type LocalEndpointKind } from "@truss-harness/provider-openai-compatible";
+import type { AgentMode, ClientConfiguration } from "./runtime.js";
+import type { PermissionMode } from "./protocol.js";
+export interface ProfileConfiguration {
+    readonly provider?: LocalEndpointKind;
+    readonly baseUrl?: string;
+    readonly model?: string;
+    readonly mode?: AgentMode;
+    readonly permission?: PermissionMode;
+    readonly internetAccess?: boolean;
+    readonly systemPrompt?: string;
+    /** Name of an environment variable containing a local endpoint token. */
+    readonly apiKeyEnv?: string;
+    readonly mcpServers?: McpServerConfigurations;
+}
+export interface HarnessConfiguration extends ProfileConfiguration {
+    readonly defaultProfile?: string;
+    readonly profiles?: Readonly<Record<string, ProfileConfiguration>>;
+    /** User-level opt-in for executable MCP definitions from workspace configuration. */
+    readonly allowWorkspaceMcpServers?: boolean;
+}
+export interface ConfigurationOverrides extends ProfileConfiguration {
+    readonly profile?: string;
+}
+export interface ResolvedConfiguration extends ClientConfiguration {
+    readonly profile?: string;
+    readonly permission: PermissionMode;
+    readonly paths: {
+        readonly user: string;
+        readonly workspace: string;
+    };
+}
+export interface ConfigurationPaths {
+    readonly user: string;
+    readonly workspace: string;
+}
+export declare function configurationPaths(workspaceRoot: string, environment?: NodeJS.ProcessEnv): ConfigurationPaths;
+export declare function resolveConfiguration(options: {
+    readonly workspaceRoot: string;
+    readonly overrides?: ConfigurationOverrides;
+    readonly environment?: NodeJS.ProcessEnv;
+    readonly paths?: ConfigurationPaths;
+}): Promise<ResolvedConfiguration>;
+export declare function initializeWorkspaceConfiguration(workspaceRoot: string, paths?: ConfigurationPaths): Promise<string>;
+export declare function parseConfigurationOverrides(arguments_: readonly string[]): {
+    readonly overrides: ConfigurationOverrides;
+    readonly rest: readonly string[];
+};

package/dist/config.js

@@ -0,0 +1,256 @@
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { brand } from "@truss-harness/branding";
+import { parseMcpServerConfigurations } from "@truss-harness/mcp";
+import { detectActiveLocalModel } from "@truss-harness/provider-openai-compatible";
+function validProvider(value) {
+    return value === "ollama" || value === "openai-compatible" ? value : undefined;
+}
+function validMode(value) {
+    return value === "chat" || value === "plan" || value === "edit" ? value : undefined;
+}
+function validPermission(value) {
+    return value === "ask" || value === "auto-read" || value === "auto-all" ? value : undefined;
+}
+function object(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+}
+function parseProfile(value) {
+    const source = object(value);
+    if (!source)
+        return {};
+    return {
+        provider: validProvider(source.provider),
+        baseUrl: typeof source.baseUrl === "string" ? source.baseUrl : undefined,
+        model: typeof source.model === "string" ? source.model : undefined,
+        mode: validMode(source.mode),
+        permission: validPermission(source.permission),
+        internetAccess: typeof source.internetAccess === "boolean" ? source.internetAccess : undefined,
+        systemPrompt: typeof source.systemPrompt === "string" ? source.systemPrompt : undefined,
+        apiKeyEnv: typeof source.apiKeyEnv === "string" ? source.apiKeyEnv : undefined,
+        mcpServers: source.mcpServers === undefined ? undefined : parseMcpServerConfigurations(source.mcpServers)
+    };
+}
+function parseConfiguration(value) {
+    const source = object(value);
+    if (!source)
+        throw new Error("Configuration root must be a JSON object.");
+    const profilesSource = object(source.profiles);
+    const profiles = profilesSource
+        ? Object.fromEntries(Object.entries(profilesSource).map(([name, profile]) => [name, parseProfile(profile)]))
+        : undefined;
+    return {
+        ...parseProfile(source),
+        defaultProfile: typeof source.defaultProfile === "string" ? source.defaultProfile : undefined,
+        profiles,
+        allowWorkspaceMcpServers: source.allowWorkspaceMcpServers === true
+    };
+}
+async function readConfiguration(path) {
+    try {
+        return parseConfiguration(JSON.parse(await readFile(path, "utf8")));
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return {};
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Unable to read ${brand.productName} configuration at ${path}: ${message}`);
+    }
+}
+function environmentConfiguration(environment) {
+    let mcpServers;
+    if (environment.TRUSS_HARNESS_MCP_SERVERS) {
+        try {
+            mcpServers = parseMcpServerConfigurations(JSON.parse(environment.TRUSS_HARNESS_MCP_SERVERS));
+        }
+        catch (error) {
+            throw new Error(`TRUSS_HARNESS_MCP_SERVERS must contain valid MCP server JSON: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return {
+        provider: validProvider(environment.TRUSS_HARNESS_PROVIDER),
+        baseUrl: environment.TRUSS_HARNESS_BASE_URL,
+        model: environment.TRUSS_HARNESS_MODEL,
+        mode: validMode(environment.TRUSS_HARNESS_AGENT_MODE),
+        permission: validPermission(environment.TRUSS_HARNESS_PERMISSION_MODE),
+        internetAccess: environment.TRUSS_HARNESS_INTERNET_ACCESS === undefined
+            ? undefined
+            : environment.TRUSS_HARNESS_INTERNET_ACCESS === "true" || environment.TRUSS_HARNESS_INTERNET_ACCESS === "1",
+        systemPrompt: environment.TRUSS_HARNESS_SYSTEM_PROMPT,
+        apiKeyEnv: environment.TRUSS_HARNESS_API_KEY ? "TRUSS_HARNESS_API_KEY" : undefined,
+        mcpServers
+    };
+}
+const profileKeys = [
+    "provider",
+    "baseUrl",
+    "model",
+    "mode",
+    "permission",
+    "internetAccess",
+    "systemPrompt",
+    "apiKeyEnv",
+    "mcpServers"
+];
+function mergeProfiles(...sources) {
+    const merged = {};
+    for (const source of sources) {
+        if (!source)
+            continue;
+        for (const key of profileKeys) {
+            const value = source[key];
+            if (value !== undefined)
+                merged[key] = value;
+        }
+    }
+    return merged;
+}
+export function configurationPaths(workspaceRoot, environment = process.env) {
+    const userRoot = process.platform === "win32"
+        ? environment.APPDATA ?? join(homedir(), "AppData", "Roaming")
+        : environment.XDG_CONFIG_HOME ?? join(homedir(), ".config");
+    return {
+        user: join(userRoot, brand.productSlug, "config.json"),
+        workspace: join(workspaceRoot, brand.workspaceDirectory, "config.json")
+    };
+}
+export async function resolveConfiguration(options) {
+    const environment = options.environment ?? process.env;
+    const paths = options.paths ?? configurationPaths(options.workspaceRoot, environment);
+    const [user, workspace] = await Promise.all([readConfiguration(paths.user), readConfiguration(paths.workspace)]);
+    const profile = options.overrides?.profile ?? workspace.defaultProfile ?? user.defaultProfile ?? environment.TRUSS_HARNESS_PROFILE;
+    const userProfile = profile ? user.profiles?.[profile] : undefined;
+    const workspaceProfile = profile ? workspace.profiles?.[profile] : undefined;
+    const environmentProfile = environmentConfiguration(environment);
+    const merged = mergeProfiles(environmentProfile, user, userProfile, workspace, workspaceProfile, options.overrides);
+    const workspaceMcpServers = user.allowWorkspaceMcpServers
+        ? workspaceProfile?.mcpServers ?? workspace.mcpServers
+        : undefined;
+    const mcpServers = options.overrides?.mcpServers
+        ?? workspaceMcpServers
+        ?? userProfile?.mcpServers
+        ?? user.mcpServers
+        ?? environmentProfile.mcpServers;
+    let provider = merged.provider ?? "ollama";
+    let baseUrl = merged.baseUrl;
+    let model = merged.model;
+    if (!model) {
+        const hasConfiguredEndpoint = merged.provider !== undefined || baseUrl !== undefined;
+        const configuredEndpoint = hasConfiguredEndpoint ? [{
+                id: "configured",
+                label: "Configured endpoint",
+                kind: provider,
+                baseUrl: baseUrl ?? (provider === "ollama" ? "http://127.0.0.1:11434" : "http://127.0.0.1:1234/v1")
+            }] : undefined;
+        const detected = await detectActiveLocalModel({ endpoints: configuredEndpoint });
+        if (detected) {
+            provider = detected.endpoint.kind;
+            baseUrl = detected.endpoint.baseUrl;
+            model = detected.model.name;
+        }
+    }
+    if (!model)
+        throw new Error(`Set a model with --model, TRUSS_HARNESS_MODEL, a ${brand.productName} config profile, or start a local model server.`);
+    const apiKey = merged.apiKeyEnv ? environment[merged.apiKeyEnv] : undefined;
+    return {
+        workspaceRoot: options.workspaceRoot,
+        provider,
+        baseUrl: baseUrl ?? (provider === "ollama" ? "http://127.0.0.1:11434" : "http://127.0.0.1:1234/v1"),
+        model,
+        mode: merged.mode ?? "chat",
+        permission: merged.permission ?? "ask",
+        internetAccess: merged.internetAccess ?? false,
+        apiKey,
+        systemPrompt: merged.systemPrompt,
+        mcpServers,
+        profile,
+        paths
+    };
+}
+export async function initializeWorkspaceConfiguration(workspaceRoot, paths = configurationPaths(workspaceRoot)) {
+    try {
+        await access(paths.workspace);
+        throw new Error(`Configuration already exists at ${paths.workspace}`);
+    }
+    catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+            throw error;
+    }
+    await mkdir(dirname(paths.workspace), { recursive: true });
+    await writeFile(paths.workspace, `${JSON.stringify({
+        defaultProfile: "ollama",
+        profiles: {
+            ollama: {
+                provider: "ollama",
+                baseUrl: "http://127.0.0.1:11434",
+                model: "qwen3:8b",
+                mode: "edit",
+                permission: "ask",
+                internetAccess: false
+            },
+            "lm-studio": {
+                provider: "openai-compatible",
+                baseUrl: "http://127.0.0.1:1234/v1",
+                model: "local-model-id",
+                mode: "plan",
+                permission: "auto-read"
+            }
+        },
+        mcpServers: {
+            filesystem: {
+                enabled: false,
+                command: "npx",
+                args: ["-y", "@modelcontextprotocol/server-filesystem", "."],
+                readOnly: false
+            }
+        }
+    }, null, 2)}\n`, "utf8");
+    return paths.workspace;
+}
+export function parseConfigurationOverrides(arguments_) {
+    const overrides = {};
+    const rest = [];
+    for (let index = 0; index < arguments_.length; index++) {
+        const argument = arguments_[index];
+        const value = () => {
+            const next = arguments_[++index];
+            if (!next || next.startsWith("--"))
+                throw new Error(`Missing value for ${argument}`);
+            return next;
+        };
+        if (argument === "--profile")
+            overrides.profile = value();
+        else if (argument === "--provider") {
+            const provider = validProvider(value());
+            if (!provider)
+                throw new Error("--provider must be ollama or openai-compatible");
+            overrides.provider = provider;
+        }
+        else if (argument === "--base-url")
+            overrides.baseUrl = value();
+        else if (argument === "--model")
+            overrides.model = value();
+        else if (argument === "--mode") {
+            const mode = validMode(value());
+            if (!mode)
+                throw new Error("--mode must be chat, plan, or edit");
+            overrides.mode = mode;
+        }
+        else if (argument === "--permission") {
+            const permission = validPermission(value());
+            if (!permission)
+                throw new Error("--permission must be ask, auto-read, or auto-all");
+            overrides.permission = permission;
+        }
+        else if (argument === "--internet-access") {
+            overrides.internetAccess = true;
+        }
+        else if (argument === "--no-internet-access") {
+            overrides.internetAccess = false;
+        }
+        else
+            rest.push(argument);
+    }
+    return { overrides, rest };
+}

package/dist/protocol.d.ts

@@ -0,0 +1,50 @@
+import type { AgentRuntime, ChatMessage, ContextBlock, RuntimeEvent, ToolApproval, ToolCall, Session } from "@truss-harness/runtime";
+export type RuntimeServiceRequest = {
+    readonly type: "run";
+    readonly requestId: string;
+    readonly prompt: string;
+    readonly sessionId?: string;
+    readonly context?: readonly ContextBlock[];
+} | {
+    readonly type: "create_session";
+    readonly requestId: string;
+    readonly messages?: readonly ChatMessage[];
+} | {
+    readonly type: "abort";
+    readonly requestId: string;
+} | {
+    readonly type: "tool_approval";
+    readonly requestId: string;
+    readonly callId: string;
+    readonly approved: boolean;
+};
+export type RuntimeServiceMessage = {
+    readonly type: "event";
+    readonly requestId: string;
+    readonly event: RuntimeEvent;
+} | {
+    readonly type: "response";
+    readonly requestId: string;
+    readonly result: {
+        readonly sessionId?: string;
+        readonly aborted?: boolean;
+    };
+} | {
+    readonly type: "error";
+    readonly requestId?: string;
+    readonly message: string;
+};
+export type PermissionMode = "ask" | "auto-read" | "auto-all";
+/** Bridges runtime approval requests to a client using the JSONL service protocol. */
+export declare class ProtocolToolApproval implements ToolApproval {
+    private readonly mode;
+    private readonly pending;
+    constructor(mode?: PermissionMode);
+    approve(call: ToolCall, _session: Session): Promise<boolean>;
+    resolve(callId: string, approved: boolean): boolean;
+    denyAll(): void;
+}
+/** Starts a newline-delimited JSON service suitable for editor clients and process isolation. */
+export declare function runService(runtime: AgentRuntime, events: {
+    subscribe(listener: (event: RuntimeEvent) => void): () => void;
+}, approval?: ProtocolToolApproval): Promise<void>;

package/dist/protocol.js

@@ -0,0 +1,101 @@
+import { createInterface } from "node:readline";
+import { stdin, stdout } from "node:process";
+const readOnlyTools = new Set(["read_file", "list_directory", "search_files", "grep"]);
+function write(message) {
+    stdout.write(`${JSON.stringify(message)}\n`);
+}
+/** Bridges runtime approval requests to a client using the JSONL service protocol. */
+export class ProtocolToolApproval {
+    mode;
+    pending = new Map();
+    constructor(mode = "ask") {
+        this.mode = mode;
+    }
+    approve(call, _session) {
+        if (this.mode === "auto-all")
+            return Promise.resolve(true);
+        if (this.mode === "auto-read" && readOnlyTools.has(call.name))
+            return Promise.resolve(true);
+        return new Promise((resolve) => this.pending.set(call.id, resolve));
+    }
+    resolve(callId, approved) {
+        const pending = this.pending.get(callId);
+        if (!pending)
+            return false;
+        this.pending.delete(callId);
+        pending(approved);
+        return true;
+    }
+    denyAll() {
+        for (const resolve of this.pending.values())
+            resolve(false);
+        this.pending.clear();
+    }
+}
+/** Starts a newline-delimited JSON service suitable for editor clients and process isolation. */
+export async function runService(runtime, events, approval) {
+    const requestsBySession = new Map();
+    const controllers = new Map();
+    events.subscribe((event) => {
+        const requestId = requestsBySession.get(event.sessionId);
+        if (requestId)
+            write({ type: "event", requestId, event });
+    });
+    const lines = createInterface({ input: stdin, crlfDelay: Infinity });
+    for await (const line of lines) {
+        let request;
+        try {
+            request = JSON.parse(line);
+        }
+        catch {
+            write({ type: "error", message: "Invalid JSON request." });
+            continue;
+        }
+        if (request.type === "abort") {
+            const controller = controllers.get(request.requestId);
+            if (!controller)
+                write({ type: "error", requestId: request.requestId, message: "Unknown active request." });
+            else {
+                controller.abort();
+                approval?.denyAll();
+                write({ type: "response", requestId: request.requestId, result: { aborted: true } });
+            }
+            continue;
+        }
+        if (request.type === "tool_approval") {
+            approval?.resolve(request.callId, request.approved);
+            continue;
+        }
+        if (request.type === "create_session") {
+            const session = await runtime.createSession(request.messages ?? []);
+            write({ type: "response", requestId: request.requestId, result: { sessionId: session.id } });
+            continue;
+        }
+        if (request.type !== "run" || typeof request.requestId !== "string" || typeof request.prompt !== "string") {
+            write({ type: "error", requestId: request.requestId, message: "Invalid service request." });
+            continue;
+        }
+        const session = request.sessionId ? await runtime.getSession(request.sessionId) : await runtime.createSession();
+        if (!session) {
+            write({ type: "error", requestId: request.requestId, message: `Unknown session: ${request.sessionId}` });
+            continue;
+        }
+        const controller = new AbortController();
+        requestsBySession.set(session.id, request.requestId);
+        controllers.set(request.requestId, controller);
+        const requestContext = Array.isArray(request.context)
+            ? request.context.filter((block) => Boolean(block)
+                && typeof block === "object"
+                && typeof block.source === "string"
+                && typeof block.content === "string"
+                && (block.priority === undefined || typeof block.priority === "number"))
+            : [];
+        void runtime.run(session.id, request.prompt, controller.signal, requestContext)
+            .then(() => write({ type: "response", requestId: request.requestId, result: { sessionId: session.id } }))
+            .catch((error) => write({ type: "error", requestId: request.requestId, message: error instanceof Error ? error.message : String(error) }))
+            .finally(() => {
+            requestsBySession.delete(session.id);
+            controllers.delete(request.requestId);
+        });
+    }
+}

package/dist/runtime.d.ts

@@ -0,0 +1,26 @@
+import { type LocalEndpointKind } from "@truss-harness/provider-openai-compatible";
+import { type McpServerConfigurations, type McpServerStatus } from "@truss-harness/mcp";
+import { AgentRuntime, EventBus, type ToolApproval, type RuntimeEvent } from "@truss-harness/runtime";
+export type AgentMode = "chat" | "plan" | "edit";
+export interface ClientRuntimeOptions {
+    readonly workspaceRoot: string;
+    readonly provider: LocalEndpointKind;
+    readonly baseUrl: string;
+    readonly model: string;
+    readonly apiKey?: string;
+    readonly systemPrompt?: string;
+    readonly approval?: ToolApproval;
+    readonly mode?: AgentMode;
+    readonly internetAccess?: boolean;
+    readonly mcpServers?: McpServerConfigurations;
+}
+export interface ClientRuntime {
+    readonly runtime: AgentRuntime;
+    readonly events: EventBus<RuntimeEvent>;
+    readonly mcpServers: readonly McpServerStatus[];
+    dispose(): Promise<void>;
+}
+export declare function createClientRuntime(options: ClientRuntimeOptions): Promise<ClientRuntime>;
+export interface ClientConfiguration extends ClientRuntimeOptions {
+}
+export declare function configurationFromEnvironment(workspaceRoot: string, environment?: NodeJS.ProcessEnv): ClientConfiguration;

package/dist/runtime.js

@@ -0,0 +1,79 @@
+import { createLocalModelProvider } from "@truss-harness/provider-openai-compatible";
+import { parseMcpServerConfigurations, registerMcpServers } from "@truss-harness/mcp";
+import { AgentRuntime, CompositeContextManager, EventBus, FileWorkspaceMemoryStore, InMemorySessionStore, ToolRegistry, WorkspaceMemoryContextProvider, WorkspacePlanContextProvider, FileWorkspacePlanStore, createUpdatePlanTool, grepTool, listDirectoryTool, readFileTool, registerCoreTools, registerWebTools, searchFilesTool } from "@truss-harness/runtime";
+export async function createClientRuntime(options) {
+    const events = new EventBus();
+    const tools = new ToolRegistry();
+    const memory = new FileWorkspaceMemoryStore(options.workspaceRoot);
+    const plans = new FileWorkspacePlanStore(options.workspaceRoot);
+    const mode = options.mode ?? "chat";
+    if (mode === "edit") {
+        registerCoreTools(tools);
+        tools.register(createUpdatePlanTool(plans));
+    }
+    if (mode === "plan") {
+        tools.register(readFileTool);
+        tools.register(listDirectoryTool);
+        tools.register(searchFilesTool);
+        tools.register(grepTool);
+    }
+    if (options.internetAccess)
+        registerWebTools(tools);
+    const enabledMcpServers = mode === "edit"
+        ? options.mcpServers
+        : mode === "plan"
+            ? Object.fromEntries(Object.entries(options.mcpServers ?? {}).filter(([, server]) => server.readOnly))
+            : {};
+    const mcp = await registerMcpServers(tools, enabledMcpServers, { workspaceRoot: options.workspaceRoot });
+    return {
+        events,
+        mcpServers: mcp.statuses,
+        dispose: () => mcp.close(),
+        runtime: new AgentRuntime({
+            provider: createLocalModelProvider({
+                kind: options.provider,
+                baseUrl: options.baseUrl,
+                model: options.model,
+                apiKey: options.apiKey
+            }),
+            tools,
+            sessions: new InMemorySessionStore(),
+            context: new CompositeContextManager([new WorkspacePlanContextProvider(plans), new WorkspaceMemoryContextProvider(memory)]),
+            events,
+            workspaceRoot: options.workspaceRoot,
+            systemPrompt: [
+                options.systemPrompt,
+                mode === "plan" ? "You are in Plan mode. Inspect the workspace with read-only tools as needed, then finish with a concise Markdown checklist exactly in this form: a heading '# Plan: <title>' followed by 3 to 8 actionable '- [ ] <step>' lines. Do not make changes." : undefined,
+                mode === "edit" ? "You have no direct filesystem access: tools are the only way to inspect or change the workspace. For a request to modify a file, use read_file as needed and then a successful write_file or replace_in_file call. The terminal is for builds, tests, Git, and inspection; never use shell redirection, echo, PowerShell content commands, or any terminal command to write source files. Never simulate tool calls, invent file contents, or claim that a file was created, changed, or verified unless that write tool completed successfully during this run. After a successful file write, read the file to verify it and then finish the task; do not write the same file again unless that verification shows a further focused change is required. If no write succeeds, say plainly that no file was changed and state why. When an active plan is present in context, use update_plan to mark a step in_progress before work and completed after verifying it. Keep the checklist accurate." : undefined
+            ].filter(Boolean).join("\n\n"),
+            approval: options.approval,
+            memory,
+            plans,
+            savePlanOnCompletion: mode === "plan"
+        })
+    };
+}
+export function configurationFromEnvironment(workspaceRoot, environment = process.env) {
+    const provider = environment.TRUSS_HARNESS_PROVIDER === "openai-compatible" ? "openai-compatible" : "ollama";
+    const mode = environment.TRUSS_HARNESS_AGENT_MODE === "edit" || environment.TRUSS_HARNESS_AGENT_MODE === "plan"
+        ? environment.TRUSS_HARNESS_AGENT_MODE
+        : "chat";
+    const baseUrl = environment.TRUSS_HARNESS_BASE_URL ?? (provider === "ollama" ? "http://localhost:11434" : "http://localhost:1234/v1");
+    const model = environment.TRUSS_HARNESS_MODEL;
+    if (!model) {
+        throw new Error("Set TRUSS_HARNESS_MODEL to the model name exposed by your OpenAI-compatible server.");
+    }
+    return {
+        workspaceRoot,
+        provider,
+        baseUrl,
+        model,
+        apiKey: environment.TRUSS_HARNESS_API_KEY,
+        systemPrompt: environment.TRUSS_HARNESS_SYSTEM_PROMPT,
+        mode,
+        internetAccess: environment.TRUSS_HARNESS_INTERNET_ACCESS === "true" || environment.TRUSS_HARNESS_INTERNET_ACCESS === "1",
+        mcpServers: environment.TRUSS_HARNESS_MCP_SERVERS
+            ? parseMcpServerConfigurations(JSON.parse(environment.TRUSS_HARNESS_MCP_SERVERS))
+            : undefined
+    };
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@truss-harness/cli",
+  "version": "0.1.0",
+  "description": "Command-line client and runtime service for Truss.",
+  "type": "module",
+  "exports": {
+    "./runtime": {
+      "types": "./dist/runtime.d.ts",
+      "default": "./dist/runtime.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "default": "./dist/config.js"
+    }
+  },
+  "bin": {
+    "truss-cli": "./dist/bin.js"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "postinstall": "node scripts/postinstall.mjs",
+    "prepack": "node ../../scripts/clean-publish-tests.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "dist",
+    "scripts/postinstall.mjs",
+    "README.md",
+    "logo.png"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/truss-agent/truss-harness.git"
+  },
+  "bugs": {
+    "url": "https://github.com/truss-agent/truss-harness/issues"
+  },
+  "homepage": "https://github.com/truss-agent/truss-harness#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "ai",
+    "coding-agent",
+    "cli",
+    "ollama",
+    "lm-studio",
+    "local-first"
+  ],
+  "dependencies": {
+    "@truss-harness/branding": "0.1.0",
+    "@truss-harness/mcp": "0.1.0",
+    "@truss-harness/provider-openai-compatible": "0.1.0",
+    "@truss-harness/runtime": "0.1.0"
+  }
+}

package/scripts/postinstall.mjs

@@ -0,0 +1,12 @@
+if (process.env.npm_config_global === "true" || process.env.npm_config_global === "1") {
+  process.stdout.write(`
+Truss CLI installed.
+
+Next steps:
+  truss-cli models
+  truss-cli config init
+  truss-cli chat "Explain this workspace"
+
+Run truss-cli help for modes, permissions, configuration, and examples.
+`);
+}