refactor: Agents that depend on global tools now have all binaries compiled and stored in the agent's bin directory so multiple agents can run at once

2025-11-04 11:29:59 -07:00
parent 843abe0621
commit 2f3586cbbf
20 changed files with 342 additions and 48 deletions
@@ -0,0 +1,98 @@
+# Loki Shell Integrations
+Loki supports the following integrations with a handful of shell environments to enhance user experience and streamline workflows.
+
+## Tab Completions
+### Dynamic
+Dynamic tab completions are supported by Loki to assist users in quickly completing commands, options, and arguments.
+You can enable it by using the corresponding command for your shell. To enable dynamic tab completions for every
+shell session (i.e. persistently), add the corresponding command to your shell's configuration file as indicated:
+
+```shell
+# Bash
+# (add to: `~/.bashrc`)
+source <(COMPLETE=bash loki) 
+
+# Zsh
+# (add to: `~/.zshrc`)
+source <(COMPLETE=zsh loki)
+
+# Fish
+# (add to: `~/.config/fish/config.fish`)
+source <(COMPLETE=fish loki | psub)
+
+# Elvish
+# (add to: `~/.elvish/rc.elv`)
+eval (E:COMPLETE=elvish loki | slurp)
+
+# PowerShell
+# (add to: `$PROFILE`)
+$env:COMPLETE = "powershell"
+loki | Out-String | Invoke-Expression
+```
+
+At the time of writing, `nushell` is not yet fully supported for dynamic tab completions due to limitations
+in the [`clap`](https://crates.io/crates/clap) crate. However, `nushell` support is being actively developed, and will
+be added in a future release.
+
+Progress on this feature can be tracked in the following issue: [Clap Issue #5840](https://github.com/clap-rs/clap/issues/5840).
+
+### Static
+Static tab completions (i.e. pre-generated completion scripts that are not context aware) can also be generated using the
+`--completions` flag. You can enable static tab completions by using the corresponding commands for your shell. These commands
+will enable them for every shell session (i.e. persistently):
+
+```shell
+# Bash
+echo 'source <(loki --completions bash)' >> ~/.bashrc
+
+# Zsh
+echo 'source <(loki --completions zsh)' >> ~/.zshrc
+
+# Fish
+echo 'loki --completions fish | source' >> ~/.config/fish/config.fish
+
+# Elvish
+echo 'eval (loki --completions elvish | slurp)' >> ~/.elvish/rc.elv
+
+# Nushell
+[[ -d ~/.config/nushell/completions ]] || mkdir -p ~/.config/nushell/completions
+loki --completions nushell | save -f ~/.config/nushell/completions/loki.nu
+echo 'use ~/.config/nushell/completions/cli.nu *' >> ~/.config/nushell/config.nu
+
+# PowerShell
+Add-content $PROFILE "loki --completions powershell | Out-String | Invoke-Expression"
+```
+
+## Shell Assistant
+Loki has an `-e,--execute` flag that allows users to run natural language commands directly from the CLI. It accepts
+natural language input and translates it into executable shell commands.
+
+![Shell Assistant Demo](./images/shell_integrations/assistant.gif)
+
+## Intelligent Command Completions
+Loki also provides shell scripts that bind `Alt-e` to `loki -e "<current command line>"`, allowing users to generate
+commands from natural text directly without invoking the CLI.
+
+For example:
+
+```shell
+$ find all typescript files with more than 100 lines<Alt-e>
+# Gets replaced with
+$ find . -name '*.ts' -type f -exec awk 'NR>100{exit 1}' {} \; -print
+```
+
+To use the CLI helper, add the content of the appropriate integration script for your shell to your shell configuration file:
+* [Bash Integration](../scripts/shell-integration/bash-integration.sh) (add to: `~/.bashrc`)
+* [Zsh Integration](../scripts/shell-integration/zsh-integration.zsh) (add to: `~/.zshrc`)
+* [Elvish Integration](../scripts/shell-integration/elvish-integration.elv) (add to: `~/.elvish/rc.elv`)
+* [Fish Integration](../scripts/shell-integration/fish-integration.fish) (add to: `~/.config/fish/config.fish`)
+* [Nushell Integration](../scripts/shell-integration/nushell-integration.nu) (add to: `~/.config/nushell/config.nu`)
+* [PowerShell Integration](../scripts/shell-integration/powershell-integration.ps1) (add to: `$PROFILE`)
+
+## Code Generation
+Users can also directly generate code snippets from natural language prompts using the `-c,--code` flag.
+
+![Code Generation Demo](./images/shell_integrations/code-generation.gif)
+
+**Pro Tip:** Pipe the output of the code generation directly into `tee` to ensure the generated code is properly extracted
+from any generated Markdown (i.e. remove any triple backticks).
@@ -0,0 +1,111 @@
+# The Loki Vault
+The Loki vault lets users store sensitive secrets and credentials securely so that there's no plaintext secrets
+anywhere in your configurations. 
+
+It's based on the [G-Man library](https://github.com/Dark-Alex-17/gman) (which also comes in a binary format) which
+functions as a universal secret management tool.
+
+![Vault Demo](./images/vault/vault-demo.gif)
+
+## Usage
+The Loki vault can be used in one of two ways: via the CLI or via the REPL for interactive usage.
+
+### CLI Usage
+The vault is utilized from the CLI with the following flags:
+
+```bash
+--add-secret <SECRET_NAME>       Add a secret to the Loki vault
+--get-secret <SECRET_NAME>       Decrypt a secret from the Loki vault and print the plaintext
+--update-secret <SECRET_NAME>    Update an existing secret in the Loki vault
+--delete-secret <SECRET_NAME>    Delete a secret from the Loki vault
+--list-secrets                   List all secrets stored in the Loki vault
+```
+(The above is also documented in `loki --help`)
+
+Loki will guide you through manipulating your secrets to make usage easier.
+
+### REPL Usage
+The vault can be access from within the Loki REPL using the `.vault` commands:
+
+![Loki Vault REPL](./images/vault/vault-repl.png)
+![Loki Vault REPL Commands](./images/vault/vault-repl-commands.png)
+
+The manipulation of your vault is guided in the same way as the CLI usage, ensuring ease of use.
+
+## Motivation
+Loki is intended to be highly configurable and adaptable to many different use cases. This means that users of Loki
+should be able to share configurations for agents, tools, roles, etc. with other users or even entire teams.
+
+My objective is to encourage this, and to make it so that users can easily version their configurations using version
+control. Good VCS hygiene dictates that one *never* commits secrets or sensitive information to a repository.
+
+Since a number of files and configurations in Loki may contain sensitive information, the vault exists to solve this problem.
+
+Users can either share the vault password with a team, making it so a single configuration can be pulled from VCS and used
+by said team. Alternatively, each user can maintain their own vault password and expect other users to replace secret values
+with their user-specific secrets.
+
+## How it works
+When you first start Loki, if you don't already have a vault password file, it will prompt you to create one. This file
+houses the password that is used to encrypt and decrypt secrets within Loki. This file exists so that you are not prompted
+for a password every time Loki attempts to decrypt a secret.
+
+When you encrypt a secret, it uses the local provider for `gman` to securely store those secrets in the Loki vault file.
+This file is typically located at your Loki configuration directory under `vault.yml`. If you open this file, you'll see a
+bunch of gibberish. This is because all secrets are encrypted using the password you provided, meaning only you can decrypt them.
+
+Secrets are specified in Loki configurations using the same variable templating as the [Jinja templating engine](https://jinja.palletsprojects.com/en/stable/):
+
+```
+{{some_variable}}
+```
+
+So whenever you want Loki to use a secret from the vault, you simply specify the secret name in this format in the applicable
+file.
+
+**Example:**
+Suppose my vault has a secret called `GITHUB_TOKEN` in it, and I want to use that in the MCP configuration. Then, I simply replace
+the expected value in my `mcp.json` with the templated secret:
+
+```json
+{
+  "mcpServers": {
+    "atlassian": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://mcp.atlassian.com/v1/sse"]
+    },
+    "github": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-e",
+        "GITHUB_PERSONAL_ACCESS_TOKEN",
+        "ghcr.io/github/github-mcp-server"
+      ],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "{{GITHUB_TOKEN}}"
+      }
+    }
+  }
+}
+```
+
+At runtime, Loki will detect the templated secret and replace it with the decrypted value from the vault before executing.
+
+## Supported Files
+At the time of writing, the following files support Loki secret injection:
+
+| File Type            | Description                       | Limitations                                                    |
+|----------------------|-----------------------------------|----------------------------------------------------------------|
+| `config.yaml`        | The main Loki configuration file  | Cannot use secret injection on the `vault_password_file` field |
+| `functions/mcp.json` | The MCP server configuration file |                                                                |
+
+
+Note that all paths are relative to the Loki configuration directory. The directory varies by system, so you can find yours by
+running
+
+```shell
+dirname $(loki --info | grep config_file | awk '{print $2}')
+```