feat(server): OpenAI-compatible serve path for forged agents

cmd/forge-agent/main.go

@@ -0,0 +1,83 @@
+// Command forge-agent serves forged agents behind a local OpenAI-compatible
+// endpoint. It is the runnable proof of the serve path: it wires demo agents
+// (defined in Go) to the OpenAI gateway so you can point any OpenAI client at
+// it.
+//
+// Usage:
+//
+//	export OPENAI_API_KEY=sk-...            # key for the upstream provider
+//	go run ./cmd/forge-agent --addr :8787
+//
+//	export OPENAI_BASE_URL=http://localhost:8787/v1
+//	export OPENAI_API_KEY=forge-local       # the gateway ignores this
+//	# now start Codex CLI / Grok Build, or just curl /v1/chat/completions
+//
+// The two demo agents share one provider and model and differ only in their
+// scaffold — the north-star demo: same model, same task, different package.
+package main
+
+import (
+	"flag"
+	"log"
+	"net/http"
+	"os"
+
+	"github.com/katasec/forge"
+	"github.com/katasec/forge/provider/openai"
+	"github.com/katasec/forge/server"
+)
+
+const forgedReviewerScaffold = `You are a repository reviewer operating under a mission scaffold.
+
+Operating rules:
+- Start from a small orientation layer; do not assume the whole repo.
+- Ground every finding in a concrete file, command, or repo fact — no generic advice.
+- Identify exactly one concrete, high-value next improvement.
+- Recommend the verification (build/test/lint) that proves the change.
+- Keep output structured: Findings, Next Improvement, Verification.`
+
+const vanillaScaffold = "You are a helpful coding assistant. Review the repository."
+
+func main() {
+	addr := flag.String("addr", ":8787", "address to listen on")
+	model := flag.String("model", string(openai.ModelGPT54Nano), "upstream model id")
+	baseURL := flag.String("base-url", "", "override upstream OpenAI base URL (e.g. for xAI)")
+	defaultAgent := flag.String("default-agent", "forged_reviewer",
+		"agent to use when a client requests an unknown model id (host GUIs send their own model names); empty for strict 404")
+	flag.Parse()
+
+	apiKey := os.Getenv("OPENAI_API_KEY")
+	if apiKey == "" {
+		log.Fatal("OPENAI_API_KEY is required (the upstream provider key)")
+	}
+
+	var opts []openai.Option
+	if *baseURL != "" {
+		opts = append(opts, openai.WithBaseURL(*baseURL))
+	}
+	provider := openai.New(apiKey, openai.Model(*model), opts...)
+
+	agents := map[string]*forge.Agent{
+		"vanilla_reviewer": mustAgent(provider, vanillaScaffold),
+		"forged_reviewer":  mustAgent(provider, forgedReviewerScaffold),
+	}
+
+	srv := server.New(agents, *defaultAgent)
+	log.Printf("forge-agent serving %d agents on %s (upstream model %s, default agent %q)", len(agents), *addr, *model, *defaultAgent)
+	log.Printf("point your client at: export OPENAI_BASE_URL=http://localhost%s/v1", *addr)
+	if err := http.ListenAndServe(*addr, srv); err != nil {
+		log.Fatal(err)
+	}
+}
+
+func mustAgent(provider forge.Provider, scaffold string) *forge.Agent {
+	agent, err := forge.NewAgent(forge.Config{
+		Provider:      provider,
+		SystemPrompt:  scaffold,
+		DisableMemory: true, // OpenAI clients are stateless; they resend history
+	})
+	if err != nil {
+		log.Fatal(err)
+	}
+	return agent
+}

go.mod

@@ -2,11 +2,15 @@ module github.com/katasec/forge
 
 go 1.25.6
 
+require (
+	github.com/google/uuid v1.6.0
+	github.com/invopop/jsonschema v0.13.0
+	github.com/klauspost/compress v1.18.6
+)
+
 require (
 	github.com/bahlo/generic-list-go v0.2.0 // indirect
 	github.com/buger/jsonparser v1.1.1 // indirect
-	github.com/google/uuid v1.6.0 // indirect
-	github.com/invopop/jsonschema v0.13.0 // indirect
 	github.com/mailru/easyjson v0.7.7 // indirect
 	github.com/wk8/go-ordered-map/v2 v2.1.8 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect

go.sum

@@ -2,15 +2,24 @@ github.com/bahlo/generic-list-go v0.2.0 h1:5sz/EEAK+ls5wF+NeqDpk5+iNdMDXrh3z3nPn
 github.com/bahlo/generic-list-go v0.2.0/go.mod h1:2KvAjgMlE5NNynlg/5iLrrCCZ2+5xWbdbCW3pNTGyYg=
 github.com/buger/jsonparser v1.1.1 h1:2PnMjfWD7wBILjqQbt530v576A/cAbQvEW9gGIpYMUs=
 github.com/buger/jsonparser v1.1.1/go.mod h1:6RYKKt7H4d4+iWqouImQ9R2FZql3VbhNgx27UK13J/0=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/invopop/jsonschema v0.13.0 h1:KvpoAJWEjR3uD9Kbm2HWJmqsEaHt8lBUpd0qHcIi21E=
 github.com/invopop/jsonschema v0.13.0/go.mod h1:ffZ5Km5SWWRAIN6wbDXItl95euhFz2uON45H2qjYt+0=
 github.com/josharian/intern v1.0.0/go.mod h1:5DoeVV0s6jJacbCEi61lwdGj/aVlrQvzHFFd8Hwg//Y=
+github.com/klauspost/compress v1.18.6 h1:2jupLlAwFm95+YDR+NwD2MEfFO9d4z4Prjl1XXDjuao=
+github.com/klauspost/compress v1.18.6/go.mod h1:cwPg85FWrGar70rWktvGQj8/hthj3wpl0PGDogxkrSQ=
 github.com/mailru/easyjson v0.7.7 h1:UGYAvKxe3sBsEDzO8ZeWOSlIQfWFlxbzLZe7hwFURr0=
 github.com/mailru/easyjson v0.7.7/go.mod h1:xzfreul335JAWq5oZzymOObrkdz5UnU4kGfJJLY9Nlc=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/testify v1.8.1 h1:w7B6lhMri9wdJUVmEZPGGhZzrYTPvgJArz7wNPgYKsk=
+github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
 github.com/wk8/go-ordered-map/v2 v2.1.8 h1:5h/BUHu93oj4gIdvHHHGsScSTMijfx5PeYkE/fJgbpc=
 github.com/wk8/go-ordered-map/v2 v2.1.8/go.mod h1:5nJHM5DyteebpVlHnWMV0rPz6Zp7+xBAnxjb1X5vnTw=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

scripts/demo.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# Exercise the forge-agent serve path end-to-end against a running server.
+#
+# Start the server first (see scripts/serve.ps1), then run this. No API key is
+# needed here — we only curl localhost; the server holds the upstream key.
+#
+#   ./scripts/demo.sh                         # default http://localhost:8787/v1
+#   ./scripts/demo.sh http://localhost:9000/v1
+set -euo pipefail
+
+BASE="${1:-http://localhost:8787/v1}"
+PROMPT='Review a small Go HTTP server package and suggest the single next useful improvement.'
+
+pp() { python3 -c 'import sys,json; d=json.load(sys.stdin); print(d.get("choices",[{}])[0].get("message",{}).get("content", d))'; }
+
+echo "== GET $BASE/models =="
+curl -s "$BASE/models" | python3 -m json.tool
+
+for model in vanilla_reviewer forged_reviewer; do
+  echo
+  echo "== POST $BASE/chat/completions  (model=$model) =="
+  curl -s "$BASE/chat/completions" \
+    -H 'Content-Type: application/json' \
+    -d "{\"model\":\"$model\",\"messages\":[{\"role\":\"user\",\"content\":\"$PROMPT\"}]}" \
+    | pp
+done
+
+echo
+echo "== streaming  (model=forged_reviewer, stream=true) =="
+curl -sN "$BASE/chat/completions" \
+  -H 'Content-Type: application/json' \
+  -d "{\"model\":\"forged_reviewer\",\"messages\":[{\"role\":\"user\",\"content\":\"$PROMPT\"}],\"stream\":true}"
+echo

scripts/serve.ps1

@@ -0,0 +1,31 @@
+#!/usr/bin/env pwsh
+# Launch forge-agent behind a local OpenAI-compatible endpoint.
+#
+# Reads OPENAI_API_KEY from your environment (your pwsh profile). Runs in the
+# foreground so you see logs; press Ctrl-C to stop.
+#
+#   ./scripts/serve.ps1                       # :8799, model gpt-5.4-nano
+#   ./scripts/serve.ps1 -Addr :9000           # custom port
+#   ./scripts/serve.ps1 -BaseUrl https://api.x.ai/v1   # point upstream at xAI
+#
+# Then, in another terminal:  ./scripts/demo.sh
+param(
+  [string]$Addr = ':8787',
+  [string]$Model = 'gpt-5.4-nano',
+  [string]$BaseUrl = ''
+)
+$ErrorActionPreference = 'Stop'
+Set-Location (Split-Path $PSScriptRoot -Parent)
+
+if (-not $env:OPENAI_API_KEY) {
+  Write-Error 'OPENAI_API_KEY is not set in this environment.'
+  exit 1
+}
+
+Write-Host "forge-agent -> http://localhost$Addr/v1   (upstream model $Model)"
+Write-Host "verify with:  ./scripts/demo.sh   (or: curl http://localhost$Addr/v1/models)"
+Write-Host ''
+
+$goArgs = @('run', './cmd/forge-agent', '--addr', $Addr, '--model', $Model)
+if ($BaseUrl) { $goArgs += @('--base-url', $BaseUrl) }
+& go @goArgs