Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion .pre-commit-config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,10 @@ repos:
hooks:
- id: trailing-whitespace
# The plans embed unified diffs, whose blank context lines are a lone space.
exclude: ^docs/superpowers/plans/
# Golden files hold exact output bytes. A fixer must not change them.
exclude: ^docs/superpowers/plans/|\.golden$
- id: end-of-file-fixer
exclude: \.golden$
- id: check-added-large-files
args: ['--maxkb=1024']
- id: check-yaml
Expand Down
13 changes: 13 additions & 0 deletions cmd/agentop/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -704,6 +704,19 @@ refusal is believed for an hour, and a session keeps the model it was given.
creates the plugin's entry, last in the outbound pipeline. A key or a word
containing `$` is refused: the config loader would read it as an environment
variable.
- `--api <protocol>=<path>` (repeatable) names a protocol the server serves and
the path it serves it at: `anthropic-messages`, `chat-completions` or
`responses`. A second `--api` for one protocol replaces the first. With no
`--api`, requests go in the agent's protocol to the agent's path.
- `--auth-header <name>` names the header that carries the key: `authorization`
sends `Bearer <key>`, any other name sends the raw key.
- `--header <name>=<value>` (repeatable) sets a fixed header on every request to
the server. A value with `$` is refused, as a key is: write
`headers: {<name>: ${NAME}}` by hand. The key headers and the hop-by-hop
headers are refused.

`agentop server` shows these under the server: its `api`, its auth header, and
the header names, never their values.
- **`use <name> --agent <agent>`** routes the agent's new sessions to the server,
including an agent that has not run yet. **`reset --agent <agent>`** stops
routing it. Either way a session already running stays where it is: its pin holds
Expand Down
33 changes: 32 additions & 1 deletion cmd/agentop/cmd_server.go
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@ const serverUsage = `agentop server — choose the inference server each coding
Usage:
agentop server [--config PATH]
agentop server add <name> <url> --main WORD --helper WORD [--key-stdin] [--yes] [--config PATH]
[--api PROTOCOL=PATH]... [--auth-header NAME] [--header NAME=VALUE]...
agentop server remove <name> [--config PATH]
agentop server use <name> --agent <agent> [--config PATH]
agentop server reset --agent <agent> [--config PATH]
Expand All @@ -54,7 +55,9 @@ agent sends it.
"add" reads the server's API key at a prompt that does not echo, or from stdin
with --key-stdin; it is never an argument. Adding a name that exists asks before
replacing its URL, key and models (--yes skips the question), which is also how a
key is rotated.
key is rotated. --api names a protocol the server serves and its path
(anthropic-messages, chat-completions or responses), --auth-header the header
that carries the key, and --header a fixed header for every request.

A request goes with the model the agent asked for. Only when the server refuses
that model is it sent again, once and before the agent sees the refusal, with
Expand Down Expand Up @@ -256,8 +259,16 @@ func serverList(args []string, stdout, stderr io.Writer) int {
fmt.Fprintf(tw, " %s\t%s\t%s\t%s\n", name, servers.Host(s), resolvedWords(s), strings.Join(agentsOn(c, name), ", "))
}
tw.Flush()
// The detail lines go under each row after the table is aligned: a line with no
// tab would restart tabwriter's columns below it.
names := slices.Sorted(maps.Keys(c.Servers))
i := 0
for line := range strings.Lines(table.String()) {
fmt.Fprintln(stdout, strings.TrimRight(line, " \n"))
for _, d := range protocolLines(c.Servers[names[i]]) {
fmt.Fprintln(stdout, " "+d)
}
i++
}
fmt.Fprintln(stdout)

Expand All @@ -267,6 +278,26 @@ func serverList(args []string, stdout, stderr io.Writer) int {
return 0
}

// protocolLines is s's api, auth_header and header names, one line each that s has.
// Header values are never shown: they can hold a credential.
func protocolLines(s routerconfig.Server) []string {
var out []string
if len(s.API) > 0 {
var api []string
for _, p := range slices.Sorted(maps.Keys(s.API)) {
api = append(api, p+"="+s.API[p])
}
out = append(out, "api: "+strings.Join(api, ", "))
}
if s.AuthHeader != "" {
out = append(out, "auth header: "+s.AuthHeader)
}
if len(s.Headers) > 0 {
out = append(out, "headers: "+strings.Join(slices.Sorted(maps.Keys(s.Headers)), ", "))
}
return out
}

// resolvedWords is a server's main and helper words with the models they name on its
// list now, read with the server's own key, as the router resolves them. A server
// whose list cannot be read says why rather than showing a model it may not name.
Expand Down
38 changes: 38 additions & 0 deletions cmd/agentop/cmd_server_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -295,3 +295,41 @@ func TestServer_SaysWhenAServersModelListIsUnavailable(t *testing.T) {
t.Errorf("the listing prints a key:\n%s", out)
}
}

// Rule C4: the listing shows api, auth_header and the header names, never a header value.
func TestServer_ListsTheAPIAuthHeaderAndHeaderNames(t *testing.T) {
block := strings.Replace(routerBlock, " helper: haiku\n", ` helper: haiku
api:
chat-completions: /v1/chat/completions
anthropic-messages: /v1/messages
auth_header: x-api-key
headers:
X-Client: cortex
User-Agent: bob-shell
`, 1)
path := serverEnv(t, closedAddr(t), block)
code, out, errOut := runServerCmd(t, "", "--config", path)
if code != 0 {
t.Fatalf("exit %d: %s", code, errOut)
}
lines := strings.Split(out, "\n")
want := []string{
"api: anthropic-messages=/v1/messages, chat-completions=/v1/chat/completions",
"auth header: x-api-key",
"headers: User-Agent, X-Client",
}
if len(lines) < 5 || !strings.HasPrefix(flat(lines[0]), "ete ") || !strings.HasPrefix(flat(lines[4]), "glm ") {
t.Fatalf("the detail lines are not under ete:\n%s", out)
}
for i, w := range want {
if got := flat(lines[i+1]); got != w {
t.Errorf("line %d = %q, want %q", i+2, got, w)
}
}
if strings.Index(lines[0], "main") != strings.Index(lines[4], "main") {
t.Errorf("columns do not line up:\n%s", out)
}
if strings.Contains(out, "bob-shell") || strings.Contains(out, "cortex\n") {
t.Errorf("the listing shows a header value:\n%s", out)
}
}
74 changes: 72 additions & 2 deletions cmd/agentop/cmd_server_write.go
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ import (
"time"

"github.com/charmbracelet/x/term"
"gopkg.in/yaml.v3"

"github.com/rossoctl/cortex/cmd/agentop/apiclient"
"github.com/rossoctl/cortex/cmd/agentop/edit"
Expand Down Expand Up @@ -82,6 +83,10 @@ func serverAdd(args []string, stdin io.Reader, stdout, stderr io.Writer) int {
var models routerconfig.Server
flags.StringVar(&models.Main, "main", "", "a word naming the server's model for an agent's main work, such as opus or glm")
flags.StringVar(&models.Helper, "helper", "", "a word naming the server's model for an agent's helper calls, such as haiku")
api, headers := pairFlag{flag: "--api", want: "<protocol>=<path>"}, pairFlag{flag: "--header", want: "<name>=<value>"}
flags.Var(&api, "api", "a protocol the server serves and its path, such as chat-completions=/v1/chat/completions (repeatable)")
flags.StringVar(&models.AuthHeader, "auth-header", "", "the header that carries the key, such as x-api-key (default: the agent's)")
flags.Var(&headers, "header", "a fixed header set on every request to the server, as <name>=<value> (repeatable)")
pos, code, ok := serverFlags(flags, args, stdout, stderr)
if !ok {
return code
Expand Down Expand Up @@ -112,6 +117,11 @@ func serverAdd(args []string, stdin io.Reader, stdout, stderr io.Writer) int {
fmt.Fprintf(stderr, "agentop server add: %v\n", err)
return 2
}
models.API, models.Headers = api.m, headers.m
if err := checkProtocolFlags(models); err != nil {
fmt.Fprintf(stderr, "agentop server add: %v\n", err)
return 2
}
// Before anything is asked or read: --key-stdin reads stdin as typed, so on a
// terminal the key would echo, character by character, onto the screen and into
// any recording of it. The prompt without the flag reads it without echo.
Expand Down Expand Up @@ -186,9 +196,18 @@ func serverAdd(args []string, stdin io.Reader, stdout, stderr io.Writer) int {
fmt.Fprintf(stdout, "%s %s → %s\n", strings.TrimPrefix(w.flag, "--"), w.word, m)
}

pairs := []string{"url", ep.URL(), "key", key, "main", models.Main, "helper", models.Helper}
value := edit.MapValue("url", ep.URL(), "key", key, "main", models.Main, "helper", models.Helper)
if len(models.API) > 0 {
value.Content = append(value.Content, edit.ScalarValue("api"), sortedMap(models.API))
}
if models.AuthHeader != "" {
value.Content = append(value.Content, edit.ScalarValue("auth_header"), edit.ScalarValue(models.AuthHeader))
}
if len(models.Headers) > 0 {
value.Content = append(value.Content, edit.ScalarValue("headers"), sortedMap(models.Headers))
}
ch := edit.ConfigChange{Chain: "outbound", Plugin: routerName, Path: []string{"servers", name},
Value: edit.MapValue(pairs...), CreatePlugin: true}
Value: value, CreatePlugin: true}
done := "Added " + name + "."
if replacing {
done = "Replaced " + name + "."
Expand Down Expand Up @@ -217,6 +236,57 @@ func checkWordFlags(models routerconfig.Server) error {
return nil
}

// pairFlag is a repeatable <key>=<value> flag. A second value for one key replaces the first.
type pairFlag struct {
flag, want string
m map[string]string
}

func (f *pairFlag) String() string { return "" }

func (f *pairFlag) Set(s string) error {
k, v, ok := strings.Cut(s, "=")
if !ok || k == "" {
return fmt.Errorf("want %s", f.want)
}
if f.m == nil {
f.m = map[string]string{}
}
f.m[k] = v
return nil
}

// checkProtocolFlags checks add's --api, --auth-header and --header with the rules the
// router loads them by, and refuses a header value with $, which config.Load would expand.
// The errors never repeat a header value.
func checkProtocolFlags(s routerconfig.Server) error {
if err := routerconfig.CheckAPI(s.API); err != nil {
return fmt.Errorf("--%w", err)
}
if err := routerconfig.CheckAuthHeader(s.AuthHeader); err != nil {
return fmt.Errorf("--auth-header: %w", err)
}
if err := routerconfig.CheckHeaders(s.Headers, s.AuthHeader); err != nil {
return fmt.Errorf("--header: %w", err)
}
for _, name := range slices.Sorted(maps.Keys(s.Headers)) {
if strings.Contains(s.Headers[name], "$") {
return fmt.Errorf("--header %s: the value contains $, which Cortex reads as an environment variable when it "+
"loads the config; write headers: {%s: ${NAME}} by hand", name, name)
}
}
return nil
}

// sortedMap is m as a YAML mapping, its keys sorted, so the same flags write the same file.
func sortedMap(m map[string]string) *yaml.Node {
var pairs []string
for _, k := range slices.Sorted(maps.Keys(m)) {
pairs = append(pairs, k, m[k])
}
return edit.MapValue(pairs...)
}

func serverRemove(args []string, stdout, stderr io.Writer) int {
flags := flag.NewFlagSet("server remove", flag.ContinueOnError)
cfgPath := flags.String("config", "", "Cortex config file (default ~/.cortex/config.yaml)")
Expand Down
61 changes: 61 additions & 0 deletions cmd/agentop/cmd_server_write_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -1058,3 +1058,64 @@ func TestServerMove_AnEmptyListingPrunesNothing(t *testing.T) {
t.Errorf("config:\n%s", cfg)
}
}

// Rule C4: the three fields are written under the server, the maps sorted, and a
// second --api for one protocol replaces the first.
func TestServerAdd_WritesTheAPIAuthHeaderAndHeaders(t *testing.T) {
path := serverEnv(t, newFakeStats(t, 0).addr(), "")
code, _, errOut := runServerCmd(t, "sk-bob", "add", "bob", "https://bob.example.com", "--main", "opus", "--helper", "haiku",
"--api", "chat-completions=/x", "--api", "chat-completions=/v1/chat/completions", "--api", "anthropic-messages=/v1/messages",
"--auth-header", "x-api-key", "--header", "User-Agent=bob-shell", "--header", "X-Client=cortex",
"--key-stdin", "--config", path)
if code != 0 {
t.Fatalf("exit %d: %s", code, errOut)
}
want := ` bob:
url: https://bob.example.com
key: sk-bob
main: opus
helper: haiku
api:
anthropic-messages: /v1/messages
chat-completions: /v1/chat/completions
auth_header: x-api-key
headers:
User-Agent: bob-shell
X-Client: cortex
`
if got := readConfig(t, path); !strings.HasSuffix(got, want) {
t.Errorf("config does not end with the new entry:\n%s", got)
}
}

// Each bad flag is refused with exit 2 before the key is asked for, and the file is
// not written.
func TestServerAdd_RefusesABadAPIOrHeaderFlagBeforeAskingForAKey(t *testing.T) {
asked := stubKeyPrompt(t, "sk")
path := serverEnv(t, newFakeStats(t, 0).addr(), "")
before := readConfig(t, path)
for _, tc := range []struct {
flags []string
want string
}{
{[]string{"--api", "bogus=/x"}, "valid protocols: anthropic-messages, chat-completions, responses"},
{[]string{"--api", "chat-completions"}, "want <protocol>=<path>"},
{[]string{"--api", "chat-completions=v1"}, "must be absolute"},
{[]string{"--auth-header", "Host"}, "cannot carry the key"},
{[]string{"--header", "X-A=$HOME"}, "--header X-A: the value contains $"},
{[]string{"--header", "Authorization=x"}, `"Authorization" cannot be set here`},
{[]string{"--header", "X-A"}, "want <name>=<value>"},
} {
args := append([]string{"add", "bob", "https://bob.example.com", "--main", "opus", "--helper", "haiku", "--config", path}, tc.flags...)
code, _, errOut := runServerCmd(t, "", args...)
if code != 2 || !strings.Contains(errOut, tc.want) {
t.Errorf("%v: exit %d, stderr:\n%s", tc.flags, code, errOut)
}
if strings.Contains(errOut, "$HOME") {
t.Errorf("%v: stderr repeats the header value:\n%s", tc.flags, errOut)
}
}
if *asked != "" || readConfig(t, path) != before {
t.Error("a bad flag asked for a key or wrote the file")
}
}
19 changes: 19 additions & 0 deletions cmd/agentop/tui/detail_raw.go
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,17 @@ func withRaw(data []byte, raw *pipeline.RawCapture, e *pipeline.SessionEvent) []
case p.Body != "":
resp["body"] = bodyView(p.Body, nil)
}
if p.Upstream != nil || p.UpstreamBase64 != nil {
text := ""
if p.Upstream != nil {
text = *p.Upstream
}
resp["upstream"] = "server's reply before translation: " + formatBytes(int64(len(text)+len(p.UpstreamBase64)))
resp["upstreamBody"] = bodyView(text, p.UpstreamBase64)
if p.UpstreamTruncated {
resp["upstreamTruncated"] = true
}
}
r["response"] = resp
} else {
r["request"] = bodyView(raw.Request, raw.RequestBase64)
Expand All @@ -69,6 +80,14 @@ func withRaw(data []byte, raw *pipeline.RawCapture, e *pipeline.SessionEvent) []
default:
r["forwarded"] = "forwarded as sent"
}
if raw.Translated != nil || raw.TranslatedBase64 != nil {
text := ""
if raw.Translated != nil {
text = *raw.Translated
}
r["translated"] = "sent upstream, translated by Cortex: " + formatBytes(int64(len(text)+len(raw.TranslatedBase64)))
r["translatedBody"] = bodyView(text, raw.TranslatedBase64)
}
if len(raw.RequestHeaders) > 0 {
m["headers"] = flatHeaders(raw.RequestHeaders)
}
Expand Down
28 changes: 28 additions & 0 deletions cmd/agentop/tui/detail_raw_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -215,3 +215,31 @@ func TestDetailRaw_ReopenShowsTheHeldCapture(t *testing.T) {
t.Fatalf("the reopened row shows raw %+v, want the held capture", m.detailRow.raw)
}
}

// A translated request shows the body Cortex sent upstream, and its reply the server's reply
// before translation, each with its own label: neither is a plugin's rewrite.
func TestDetailRaw_ShowsTheTranslatedHop(t *testing.T) {
tr := `{"model":"c","messages":[{"role":"user","content":[{"type":"text","text":"translated text"}]}]}`
out := rawDetail(t, &pipeline.RawCapture{Request: `{"model":"m"}`, Translated: &tr})
for _, want := range []string{"sent upstream, translated by Cortex: 95B", "translatedBody", "translated text", "forwarded as sent"} {
if !strings.Contains(out, want) {
t.Errorf("request detail lacks %q:\n%s", want, out)
}
}

ev := &pipeline.SessionEvent{Seq: 4, Phase: pipeline.SessionResponse, Direction: pipeline.Outbound, Host: "h",
Inference: &pipeline.InferenceExtension{Model: "m"}}
m := detailModel(t, "s1", ev)
up := `{"choices":[{"message":{"content":"chat reply"}}]}`
m.applyDetailEvent(detailEventLoadedMsg{sessionID: "s1", seq: 4, event: ev, raw: &pipeline.RawCapture{
Response: &pipeline.RawBody{Status: 200, Body: `{}`, Upstream: &up}}})
m.detailFolds = map[string]foldChoice{"response.raw": {open: true}, "response.raw.response": {open: true},
"response.raw.response.upstreamBody": {open: true}}
m.renderDetail()
got := stripANSI(strings.Join(lineTexts(m.detailLines), "\n"))
for _, want := range []string{"server's reply before translation: 50B", "upstreamBody"} {
if !strings.Contains(got, want) {
t.Errorf("response detail lacks %q:\n%s", want, got)
}
}
}
5 changes: 4 additions & 1 deletion cmd/agentop/tui/server_route.go
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ import (
"maps"
"os"
"path/filepath"
"reflect"
"strings"

"github.com/rossoctl/cortex/cmd/agentop/servers"
Expand Down Expand Up @@ -88,7 +89,9 @@ func homeTilde(path string) string {
// sameRouter reports whether two router configs route alike, so a pipeline refetch repaints the
// SERVER columns only when what they show has changed.
func sameRouter(a, b routerconfig.Config) bool {
return maps.Equal(a.Servers, b.Servers) && maps.Equal(a.Agents, b.Agents)
// DeepEqual: a Server holds maps (api, headers), so it is not comparable.
return maps.EqualFunc(a.Servers, b.Servers, func(x, y routerconfig.Server) bool { return reflect.DeepEqual(x, y) }) &&
maps.Equal(a.Agents, b.Agents)
}

// localCortexTarget is the config file and stats URL of the Cortex on this machine, when the
Expand Down
Loading
Loading