@brendangraham/steer 0.1.21

package/README.md

@@ -0,0 +1,285 @@
+# Steer
+
+Steer is an AI coding agent written in Rust.
+
+It includes a TUI, supports headless execution, and exposes a gRPC interface for programmatic usage.
+
+https://github.com/user-attachments/assets/5a31ccc9-6a96-4005-ab5a-ae3aa7ae34c4
+
+---
+
+## Install
+
+### Shell Script
+```
+curl --proto '=https' --tlsv1.2 -LsSf https://github.com/BrendanGraham14/steer/releases/latest/download/steer-installer.sh | sh
+```
+
+### Cargo
+
+```bash
+cargo install steer
+```
+
+## Quick Start
+
+Simply run `steer` to start the TUI in a local session.
+
+More options:
+
+```
+❯ steer --help
+Command-line interface for Steer coding agent.
+
+Usage: steer [OPTIONS] [COMMAND]
+
+Commands:
+  tui          Launch the interactive terminal UI (default)
+  preferences  Manage user preferences
+  headless     Run in headless mode
+  server       Start the gRPC server
+  session      Session management commands
+  help         Print this message or the help of the given subcommand(s)
+
+Options:
+      --session <SESSION>
+          Resume an existing session instead of starting a new one (local or remote modes)
+  -d, --directory <DIRECTORY>
+          Optional directory to work in
+  -m, --model <MODEL>
+          Model to use [default: claude-opus-4-20250514] [possible values: claude-3-5-sonnet-20240620, claude-3-5-sonnet-20241022, claude-3-7-sonnet-20250219, claude-3-5-haiku-20241022, claude-sonnet-4-20250514, claude-opus-4-20250514, gpt-4.1-2025-04-14, gpt-4.1-mini-2025-04-14, gpt-4.1-nano-2025-04-14, o3-2025-04-16, o3-pro-2025-06-10, o4-mini-2025-04-16, gemini-2.5-flash-preview-04-17, gemini-2.5-pro-preview-05-06, gemini-2.5-pro-preview-06-05, grok-3, grok-3-mini, grok-4-0709]
+      --remote <REMOTE>
+          Connect to a remote gRPC server instead of running locally
+      --system-prompt <SYSTEM_PROMPT>
+          Custom system prompt to use instead of the default
+      --session-config <SESSION_CONFIG>
+          Path to session configuration file (TOML format) for new sessions
+      --theme <THEME>
+          Theme to use for the TUI (defaults to "default")
+  -h, --help
+          Print help
+  -V, --version
+          Print version
+```
+
+### Headless mode
+
+```bash
+# Read prompt from stdin and return a single JSON response
+echo "What is 2+2?" | steer headless
+
+# Provide a JSON file containing `Vec<Message>` in the Steer message format
+steer headless --messages-json /tmp/messages.json
+
+# Run inside an existing session (keeps history / tool approvals), pipe the prompt from a file
+steer headless --session b4e1a7de-2e83-45ad-977c-2c4efdb3d9c6 < prompt.txt
+
+# Supply a custom session configuration (tool approvals, MCP backends, etc.)
+steer headless --session-config config.toml < prompt.txt
+```
+
+### Authentication
+
+```bash
+# Launch Steer and follow the first-run setup wizard
+steer
+
+# Re-run the wizard any time inside the chat
+/auth
+```
+
+### gRPC server / remote mode
+
+```bash
+# Start a standalone server (default 127.0.0.1:50051)
+steer server --port 50051
+
+# Connect to an already running server
+steer tui --remote 192.168.1.10:50051
+```
+
+### Sessions
+
+Steer persists data to a session. You may create, list, delete, and resume sessions.
+
+```bash
+# List saved sessions
+steer session list --limit 20
+
+# Delete a session
+steer session delete <SESSION_ID> --force
+
+# Create a new session with a config file
+steer session create --session-config config.toml
+
+# Create with overrides
+steer session create --session-config config.toml --system-prompt "Custom prompt"
+
+# Resume a session
+steer --session <SESSION_ID>
+```
+
+### Session Configuration Files
+
+Sessions can be configured using TOML configuration files. This is useful for:
+- Consistent project-specific configurations
+- Setting up MCP (Model Context Protocol) backends
+- Pre-approving tools or bash commands
+- Sharing configurations with your team
+
+#### Example: Minimal Configuration
+```toml
+# session-minimal.toml
+[tool_config]
+backends = [
+  { type = "mcp", server_name = "calculator", transport = { type = "stdio", command = "python", args = ["-m", "mcp_calculator"] }, tool_filter = "all" }
+]
+```
+
+#### Example: Pre-approved Tools
+```toml
+# session-preapproved.toml
+system_prompt = "You are a helpful coding assistant."
+
+[tool_config]
+visibility = "all"
+approval_policy = { type = "pre_approved", tools = ["grep", "ls", "view", "glob", "todo_read"] }
+```
+
+#### Example: Full Configuration
+```toml
+# session-full.toml
+system_prompt = "You are a helpful assistant with access to calculator and web tools."
+
+[workspace]
+type = "local"
+
+[tool_config]
+backends = [
+  { type = "mcp", server_name = "calculator", transport = { type = "stdio", command = "python", args = ["-m", "mcp_calculator"] }, tool_filter = "all" },
+  { type = "mcp", server_name = "web-tools", transport = { type = "tcp", host = "127.0.0.1", port = 3000 }, tool_filter = "all" }
+]
+visibility = "all"
+approval_policy = "always_ask"
+
+[metadata]
+project = "my-project"
+environment = "development"
+```
+
+See the `examples/` directory for more configuration examples.
+
+### MCP Transport Options
+
+Steer supports multiple transport types for connecting to MCP servers:
+
+#### Stdio
+```toml
+transport = { type = "stdio", command = "python", args = ["-m", "mcp_server"] }
+```
+
+#### TCP
+```toml
+transport = { type = "tcp", host = "127.0.0.1", port = 3000 }
+```
+
+#### Unix Socket
+```toml
+transport = { type = "unix", path = "/tmp/mcp.sock" }
+```
+
+#### SSE
+```toml
+transport = { type = "sse", url = "http://localhost:3000/events", headers = { "Authorization" = "Bearer token" } }
+```
+
+#### HTTP
+```toml
+transport = { type = "http", url = "http://localhost:3000", headers = { "X-API-Key" = "secret" } }
+```
+
+---
+
+## Slash commands (inside the chat UI)
+
+```
+/help        Show help
+/auth        Set up authentication for AI providers
+/model       Show or change the current model
+/clear       Clear conversation history and tool approvals
+/compact     Summarize the current conversation
+/theme       Change or list available themes
+/mcp         Show MCP server connection status
+```
+
+---
+
+## Notifications
+
+Steer supports desktop and audio notifications when certain events occur.
+
+### Notification Types
+
+| Notification Type | When |
+|---|---|
+| **Processing Complete** | Assistant finishes processing your request |
+| **Tool Approval** | A tool needs your approval (e.g., `bash`, `edit_file`) |
+| **Error** | An error occurs during processing |
+
+### Configuration
+
+Both sound and desktop notifications are enabled by default. To disable either of them, edit the configuration via `steer preferences edit`:
+
+```toml
+[ui.notifications]
+sound = true
+desktop = true
+```
+
+---
+
+## Authentication
+
+Steer supports multiple methods for providing credentials.
+
+### Interactive Setup
+
+The first time you start Steer it should launch a setup wizard. The auth flow can also be triggered via the `/auth` command.
+
+All providers (Anthropic, OpenAI, Gemini, xAI) support API key authentication.
+ 
+For Claude Pro/Max users, Steer also supports authenticating via OAuth. **Note**: If OAuth tokens and an API key are saved for Anthropic, the OAuth token takes precedence.
+
+Credentials are stored securely using the OS-native keyring.
+
+### Environment Variables
+
+Steer can also load credentials via environment variables. It will detect the following environment variables:
+
+* `ANTHROPIC_API_KEY` or `CLAUDE_API_KEY`
+* `OPENAI_API_KEY`
+* `GOOGLE_API_KEY` or `GEMINI_API_KEY`
+* `XAI_API_KEY` or `GROK_API_KEY` 
+
+Environment variables take precedence over stored credentials.
+
+---
+
+## Tool approval system
+
+Read-only tools run automatically ( `view`, `grep`, `ls`, `glob`, `fetch`, `todo.read` ).  Mutating tools ( `edit`, `replace`, `bash`, etc.) require approval on first use, with the option to remember the decision for the rest of the session.
+
+
+### Bash Command Approval
+
+You can pre-approve specific bash commands using glob patterns in your session configuration:
+
+```toml
+[tool_config.tools.bash]
+approved_patterns = [
+    "git status",
+    "git log*",
+    "npm run*",
+    "cargo build*"
+]
+```

package/binary-install.js

@@ -0,0 +1,192 @@
+const { createWriteStream, existsSync, mkdirSync, mkdtemp } = require("fs");
+const { join, sep } = require("path");
+const { spawnSync } = require("child_process");
+const { tmpdir } = require("os");
+
+const axios = require("axios");
+const rimraf = require("rimraf");
+const tmpDir = tmpdir();
+
+const error = (msg) => {
+  console.error(msg);
+  process.exit(1);
+};
+
+class Package {
+  constructor(name, url, filename, zipExt, binaries) {
+    let errors = [];
+    if (typeof url !== "string") {
+      errors.push("url must be a string");
+    } else {
+      try {
+        new URL(url);
+      } catch (e) {
+        errors.push(e);
+      }
+    }
+    if (name && typeof name !== "string") {
+      errors.push("package name must be a string");
+    }
+    if (!name) {
+      errors.push("You must specify the name of your package");
+    }
+    if (binaries && typeof binaries !== "object") {
+      errors.push("binaries must be a string => string map");
+    }
+    if (!binaries) {
+      errors.push("You must specify the binaries in the package");
+    }
+
+    if (errors.length > 0) {
+      let errorMsg =
+        "One or more of the parameters you passed to the Binary constructor are invalid:\n";
+      errors.forEach((error) => {
+        errorMsg += error;
+      });
+      errorMsg +=
+        '\n\nCorrect usage: new Package("my-binary", "https://example.com/binary/download.tar.gz", {"my-binary": "my-binary"})';
+      error(errorMsg);
+    }
+    this.url = url;
+    this.name = name;
+    this.filename = filename;
+    this.zipExt = zipExt;
+    this.installDirectory = join(__dirname, "node_modules", ".bin_real");
+    this.binaries = binaries;
+
+    if (!existsSync(this.installDirectory)) {
+      mkdirSync(this.installDirectory, { recursive: true });
+    }
+  }
+
+  exists() {
+    for (const binaryName in this.binaries) {
+      const binRelPath = this.binaries[binaryName];
+      const binPath = join(this.installDirectory, binRelPath);
+      if (!existsSync(binPath)) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  install(fetchOptions, suppressLogs = false) {
+    if (this.exists()) {
+      if (!suppressLogs) {
+        console.error(
+          `${this.name} is already installed, skipping installation.`,
+        );
+      }
+      return Promise.resolve();
+    }
+
+    if (existsSync(this.installDirectory)) {
+      rimraf.sync(this.installDirectory);
+    }
+
+    mkdirSync(this.installDirectory, { recursive: true });
+
+    if (!suppressLogs) {
+      console.error(`Downloading release from ${this.url}`);
+    }
+
+    return axios({ ...fetchOptions, url: this.url, responseType: "stream" })
+      .then((res) => {
+        return new Promise((resolve, reject) => {
+          mkdtemp(`${tmpDir}${sep}`, (err, directory) => {
+            let tempFile = join(directory, this.filename);
+            const sink = res.data.pipe(createWriteStream(tempFile));
+            sink.on("error", (err) => reject(err));
+            sink.on("close", () => {
+              if (/\.tar\.*/.test(this.zipExt)) {
+                const result = spawnSync("tar", [
+                  "xf",
+                  tempFile,
+                  // The tarballs are stored with a leading directory
+                  // component; we strip one component in the
+                  // shell installers too.
+                  "--strip-components",
+                  "1",
+                  "-C",
+                  this.installDirectory,
+                ]);
+                if (result.status == 0) {
+                  resolve();
+                } else if (result.error) {
+                  reject(result.error);
+                } else {
+                  reject(
+                    new Error(
+                      `An error occurred untarring the artifact: stdout: ${result.stdout}; stderr: ${result.stderr}`,
+                    ),
+                  );
+                }
+              } else if (this.zipExt == ".zip") {
+                const result = spawnSync("unzip", [
+                  "-q",
+                  tempFile,
+                  "-d",
+                  this.installDirectory,
+                ]);
+                if (result.status == 0) {
+                  resolve();
+                } else if (result.error) {
+                  reject(result.error);
+                } else {
+                  reject(
+                    new Error(
+                      `An error occurred unzipping the artifact: stdout: ${result.stdout}; stderr: ${result.stderr}`,
+                    ),
+                  );
+                }
+              } else {
+                reject(
+                  new Error(`Unrecognized file extension: ${this.zipExt}`),
+                );
+              }
+            });
+          });
+        });
+      })
+      .then(() => {
+        if (!suppressLogs) {
+          console.error(`${this.name} has been installed!`);
+        }
+      })
+      .catch((e) => {
+        error(`Error fetching release: ${e.message}`);
+      });
+  }
+
+  run(binaryName, fetchOptions) {
+    const promise = !this.exists()
+      ? this.install(fetchOptions, true)
+      : Promise.resolve();
+
+    promise
+      .then(() => {
+        const [, , ...args] = process.argv;
+
+        const options = { cwd: process.cwd(), stdio: "inherit" };
+
+        const binRelPath = this.binaries[binaryName];
+        if (!binRelPath) {
+          error(`${binaryName} is not a known binary in ${this.name}`);
+        }
+        const binPath = join(this.installDirectory, binRelPath);
+        const result = spawnSync(binPath, args, options);
+
+        if (result.error) {
+          error(result.error);
+        }
+
+        process.exit(result.status);
+      })
+      .catch((e) => {
+        error(e.message);
+        process.exit(1);
+      });
+  }
+}
+
+module.exports.Package = Package;

package/binary.js

@@ -0,0 +1,126 @@
+const { Package } = require("./binary-install");
+const os = require("os");
+const cTable = require("console.table");
+const libc = require("detect-libc");
+const { configureProxy } = require("axios-proxy-builder");
+
+const error = (msg) => {
+  console.error(msg);
+  process.exit(1);
+};
+
+const {
+  name,
+  artifactDownloadUrl,
+  supportedPlatforms,
+  glibcMinimum,
+} = require("./package.json");
+
+const builderGlibcMajorVersion = glibcMinimum.major;
+const builderGlibcMInorVersion = glibcMinimum.series;
+
+const getPlatform = () => {
+  const rawOsType = os.type();
+  const rawArchitecture = os.arch();
+
+  // We want to use rust-style target triples as the canonical key
+  // for a platform, so translate the "os" library's concepts into rust ones
+  let osType = "";
+  switch (rawOsType) {
+    case "Windows_NT":
+      osType = "pc-windows-msvc";
+      break;
+    case "Darwin":
+      osType = "apple-darwin";
+      break;
+    case "Linux":
+      osType = "unknown-linux-gnu";
+      break;
+  }
+
+  let arch = "";
+  switch (rawArchitecture) {
+    case "x64":
+      arch = "x86_64";
+      break;
+    case "arm64":
+      arch = "aarch64";
+      break;
+  }
+
+  if (rawOsType === "Linux") {
+    if (libc.familySync() == "musl") {
+      osType = "unknown-linux-musl-dynamic";
+    } else if (libc.isNonGlibcLinuxSync()) {
+      console.warn(
+        "Your libc is neither glibc nor musl; trying static musl binary instead",
+      );
+      osType = "unknown-linux-musl-static";
+    } else {
+      let libcVersion = libc.versionSync();
+      let splitLibcVersion = libcVersion.split(".");
+      let libcMajorVersion = splitLibcVersion[0];
+      let libcMinorVersion = splitLibcVersion[1];
+      if (
+        libcMajorVersion != builderGlibcMajorVersion ||
+        libcMinorVersion < builderGlibcMInorVersion
+      ) {
+        // We can't run the glibc binaries, but we can run the static musl ones
+        // if they exist
+        console.warn(
+          "Your glibc isn't compatible; trying static musl binary instead",
+        );
+        osType = "unknown-linux-musl-static";
+      }
+    }
+  }
+
+  // Assume the above succeeded and build a target triple to look things up with.
+  // If any of it failed, this lookup will fail and we'll handle it like normal.
+  let targetTriple = `${arch}-${osType}`;
+  let platform = supportedPlatforms[targetTriple];
+
+  if (!platform) {
+    error(
+      `Platform with type "${rawOsType}" and architecture "${rawArchitecture}" is not supported by ${name}.\nYour system must be one of the following:\n\n${Object.keys(
+        supportedPlatforms,
+      ).join(",")}`,
+    );
+  }
+
+  return platform;
+};
+
+const getPackage = () => {
+  const platform = getPlatform();
+  const url = `${artifactDownloadUrl}/${platform.artifactName}`;
+  let filename = platform.artifactName;
+  let ext = platform.zipExt;
+  let binary = new Package(name, url, filename, ext, platform.bins);
+
+  return binary;
+};
+
+const install = (suppressLogs) => {
+  if (!artifactDownloadUrl || artifactDownloadUrl.length === 0) {
+    console.warn("in demo mode, not installing binaries");
+    return;
+  }
+  const package = getPackage();
+  const proxy = configureProxy(package.url);
+
+  return package.install(proxy, suppressLogs);
+};
+
+const run = (binaryName) => {
+  const package = getPackage();
+  const proxy = configureProxy(package.url);
+
+  package.run(binaryName, proxy);
+};
+
+module.exports = {
+  install,
+  run,
+  getPackage,
+};

package/install.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+const { install } = require("./binary");
+install(false);