Agent Executor (AX) is Google's open agentic orchestration runtime
Go
Add Gemini Enterprise Skill Registry integration for local harnesses (#300)
zbl9437718e20bf2e
diff --git a/cmd/ax/internal/cliutil/cliutil.go b/cmd/ax/internal/cliutil/cliutil.goindex f8d0ebb..04b1b12 100644--- a/cmd/ax/internal/cliutil/cliutil.go+++ b/cmd/ax/internal/cliutil/cliutil.go@@ -26,6 +26,7 @@ import ("github.com/google/ax/internal/harness/antigravity""github.com/google/ax/internal/harness/antigravityinteractions""github.com/google/ax/internal/harness/substrate"+ "github.com/google/ax/internal/skills/geminienterprise")// Controller is the active controller type for this build.@@ -64,6 +65,22 @@ func NewControllerFromConfig(ctx context.Context, cfg *Config) (*controller.Contvar defaultHarnessID stringvar err error+ // Materialize registry skills once, up front (skills config is top-level and+ // harness-agnostic; each actor runs a single harness that consumes the+ // materialized folder). Unconditional when configured. Fail-safe: a registry+ // error degrades capability but never blocks harness creation. The+ // interactions harness (no SKILLS_DIR concept) is told where the materialized+ // skills are via a pointer appended to its system instruction. Only the local+ // path materializes; substrate/pod does not yet read ax.yaml.+ //+ // TODO(joycel): wire the Antigravity SDK harness too. It discovers skills via+ // SKILLS_DIR, so its SKILLS_DIR needs to be pointed at the materialized+ // target_dir; currently only the interactions harness is fully wired.+ var skillsPointer string+ if !substrateMode {+ skillsPointer = antigravityinteractions.SkillsSystemInstruction(geminienterprise.Materialize(ctx, cfg.Skills))+ }+// Built-in Antigravity harness.var antigravityHarness harness.Harnessif !substrateMode {@@ -98,7 +115,8 @@ func NewControllerFromConfig(ctx context.Context, cfg *Config) (*controller.Cont// Built-in Antigravity Interactions harness.var antigravityInteractionsHarness harness.Harnessif !substrateMode {- agent := cfg.Harnesses.AntigravityInteractions.Agent+ aiCfg := cfg.Harnesses.AntigravityInteractions+ agent := aiCfg.Agentif agent == "" {agent = antigravityinteractions.DefaultAgent}@@ -108,9 +126,12 @@ func NewControllerFromConfig(ctx context.Context, cfg *Config) (*controller.Contif sErr != nil {return nil, fmt.Errorf("antigravity-interactions harness: %w", sErr)}+ // skillsPointer was built once, up front, from the top-level skills+ // config (see above). Append it to any configured system instruction.antigravityInteractionsHarness, err = antigravityinteractions.New(antigravityinteractions.AntigravityInteractionsConfig{- Agent: agent,- StateDir: stateDir,+ Agent: agent,+ SystemInstruction: antigravityinteractions.JoinSystemInstruction(aiCfg.SystemInstruction, skillsPointer),+ StateDir: stateDir,})} else {antigravityInteractionsHarness, err = substrate.New(config.AntigravityInteractionsHarnessID, "", "", config.AntigravityInteractionsTemplate, 80)diff --git a/internal/config/config.go b/internal/config/config.goindex 21ec968..58ec500 100644--- a/internal/config/config.go+++ b/internal/config/config.go@@ -48,6 +48,11 @@ type Config struct {Server ServerConfig `yaml:"server"`EventLog EventLogConfig `yaml:"eventlog"`Harnesses HarnessesConfig `yaml:"harnesses,omitempty"`+ // Skills sources skills from the Gemini Enterprise Skill Registry into on-disk folders+ // before the harness starts. It is harness-agnostic: each actor runs exactly+ // one harness, which consumes the materialized folder(s). Optional; disabled+ // when no registry is enabled.+ Skills SkillsConfig `yaml:"skills,omitempty"`Telemetry TelemetryConfig `yaml:"telemetry,omitempty"`}@@ -105,6 +110,101 @@ type AntigravityHarnessConfig struct {type AntigravityInteractionsHarnessConfig struct {Default bool `yaml:"default,omitempty"` // Default harness or notAgent string `yaml:"agent,omitempty"` // Interactions API agent (default: antigravityinteractions.DefaultAgent)+ // SystemInstruction is a free-form system prompt sent on every turn.+ SystemInstruction string `yaml:"system_instruction,omitempty"`+}++// SkillsConfig configures optional skill sources (top-level, harness-agnostic).+// Today the only source type is the Gemini Enterprise Skill Registry; it may source from more+// than one registry (e.g. a shared org-wide registry plus a team-specific one),+// each with its own project/location, selection, and target directory.+type SkillsConfig struct {+ Registries []SkillsRegistryConfig `yaml:"registries,omitempty"`+}++// Validate checks the (top-level) skills config.+func (s SkillsConfig) Validate() error {+ for i := range s.Registries {+ if err := s.Registries[i].validate(i); err != nil {+ return err+ }+ }+ return nil+}++// validate enforces that, when this registry source is enabled, exactly one+// selection mode is set (skills, query, or all) — a config-level "oneof". idx is+// the registry's index within the registries list, for error context.+func (rc SkillsRegistryConfig) validate(idx int) error {+ if !rc.Enabled {+ return nil+ }+ if rc.TargetDir == "" {+ return fmt.Errorf("skills.registries[%d] requires target_dir (skills materialize to <target_dir>/<skill-id>/)", idx)+ }+ modes := 0+ if len(rc.Skills) > 0 {+ modes+++ }+ if rc.Query != nil {+ modes+++ }+ if rc.All {+ modes+++ }+ switch {+ case modes == 0:+ return fmt.Errorf("skills.registries[%d] requires exactly one selection mode (set one of skills, query, or all)", idx)+ case modes > 1:+ return fmt.Errorf("skills.registries[%d] sets multiple selection modes; set exactly one of skills, query, or all", idx)+ }+ if rc.Query != nil && rc.Query.Text == "" {+ return fmt.Errorf("skills.registries[%d].query requires a non-empty text", idx)+ }+ return nil+}++// SkillsRegistryConfig sources agentskills.io skills from the Gemini Skill+// Registry. When Enabled, exactly one selection mode should be set (Skills,+// Query, or All); if none is set, all skills are materialized.+type SkillsRegistryConfig struct {+ Enabled bool `yaml:"enabled,omitempty"`+ // Project owns the skills (projects/{Project}/locations/{Location}/skills).+ // Empty falls back to the GOOGLE_CLOUD_PROJECT environment variable.+ Project string `yaml:"project,omitempty"`+ // Location is the registry region, e.g. "us-central1". Empty falls back to+ // GOOGLE_CLOUD_LOCATION, then a built-in default.+ Location string `yaml:"location,omitempty"`++ // --- selection (choose one) ---++ // Skills is an explicit allowlist of skills, each optionally pinned to a+ // revision. Takes precedence over Query and All.+ Skills []SkillRefConfig `yaml:"skills,omitempty"`+ // Query is a semantic search selection; its top matches are materialized.+ // TopK lives inside it because it only has meaning for a query.+ Query *SkillsQueryConfig `yaml:"query,omitempty"`+ // All materializes every skill in the project/location (used when neither+ // Skills nor Query is set; can also be set explicitly).+ All bool `yaml:"all,omitempty"`++ // TargetDir is the base directory skills are materialized into: each skill+ // is written to <TargetDir>/<skill-id>/. Required when Enabled.+ TargetDir string `yaml:"target_dir,omitempty"`+}++// SkillsQueryConfig selects skills by semantic search.+type SkillsQueryConfig struct {+ // Text is the semantic search string (required for query selection).+ Text string `yaml:"text"`+ // TopK bounds the number of matches (<=0 uses the server default).+ TopK int `yaml:"top_k,omitempty"`+}++// SkillRefConfig identifies a skill to materialize, optionally pinned.+type SkillRefConfig struct {+ ID string `yaml:"id"`+ Revision string `yaml:"revision,omitempty"`}// SubstrateHarnessConfig registers a custom harness deployed on substrate@@ -216,6 +316,10 @@ func (c *Config) Validate() error {return fmt.Errorf("multiple harnesses marked as default")}+ if err := c.Skills.Validate(); err != nil {+ return err+ }+return nil}diff --git a/internal/config/config_test.go b/internal/config/config_test.goindex 149b7a6..baebb03 100644--- a/internal/config/config_test.go+++ b/internal/config/config_test.go@@ -168,3 +168,180 @@ func TestLoadFromBytes_Invalid(t *testing.T) {t.Fatal("LoadFromBytes(invalid): got nil error, want error")}}++func TestParse_SkillsByID(t *testing.T) {+ data := `+skills:+ registries:+ - enabled: true+ project: my-proj+ location: us-central1+ target_dir: /tmp/ax-skills+ skills:+ - id: emoji+ - id: lowercase+ revision: rev-3+`+ var cfg Config+ if err := yaml.Unmarshal([]byte(data), &cfg); err != nil {+ t.Fatalf("Unmarshal failed: %v", err)+ }+ if len(cfg.Skills.Registries) != 1 {+ t.Fatalf("registries = %d, want 1", len(cfg.Skills.Registries))+ }+ reg := cfg.Skills.Registries[0]+ if !reg.Enabled || reg.Project != "my-proj" || reg.Location != "us-central1" || reg.TargetDir != "/tmp/ax-skills" {+ t.Errorf("registry = %+v, want enabled my-proj/us-central1 /tmp/ax-skills", reg)+ }+ if len(reg.Skills) != 2 {+ t.Fatalf("skills = %d, want 2", len(reg.Skills))+ }+ if reg.Skills[0].ID != "emoji" || reg.Skills[0].Revision != "" {+ t.Errorf("skills[0] = %+v, want {emoji }", reg.Skills[0])+ }+ if reg.Skills[1].ID != "lowercase" || reg.Skills[1].Revision != "rev-3" {+ t.Errorf("skills[1] = %+v, want {lowercase rev-3}", reg.Skills[1])+ }+ if reg.Query != nil {+ t.Errorf("Query = %+v, want nil in by-id mode", reg.Query)+ }+}++func TestParse_SkillsByQuery(t *testing.T) {+ data := `+skills:+ registries:+ - enabled: true+ project: my-proj+ target_dir: /tmp/ax-skills+ query:+ text: "find gcp skills"+ top_k: 5+`+ var cfg Config+ if err := yaml.Unmarshal([]byte(data), &cfg); err != nil {+ t.Fatalf("Unmarshal failed: %v", err)+ }+ regs := cfg.Skills.Registries+ if len(regs) != 1 || regs[0].Query == nil {+ t.Fatalf("registries = %+v, want one with a query block", regs)+ }+ if regs[0].Query.Text != "find gcp skills" || regs[0].Query.TopK != 5 {+ t.Errorf("Query = %+v, want {find gcp skills 5}", *regs[0].Query)+ }+}++func TestParse_MultipleRegistries(t *testing.T) {+ data := `+skills:+ registries:+ - enabled: true+ project: org-proj+ target_dir: /tmp/org+ all: true+ - enabled: true+ project: team-proj+ target_dir: /tmp/team+ skills:+ - id: teamskill+`+ var cfg Config+ if err := yaml.Unmarshal([]byte(data), &cfg); err != nil {+ t.Fatalf("Unmarshal failed: %v", err)+ }+ regs := cfg.Skills.Registries+ if len(regs) != 2 {+ t.Fatalf("registries = %d, want 2", len(regs))+ }+ if regs[0].Project != "org-proj" || regs[0].TargetDir != "/tmp/org" || !regs[0].All {+ t.Errorf("registries[0] = %+v, want org-proj /tmp/org all", regs[0])+ }+ if regs[1].Project != "team-proj" || regs[1].TargetDir != "/tmp/team" || len(regs[1].Skills) != 1 {+ t.Errorf("registries[1] = %+v, want team-proj /tmp/team [teamskill]", regs[1])+ }+ // Each registry has exactly one selection mode + target_dir, so validation passes.+ if err := cfg.Skills.Validate(); err != nil {+ t.Errorf("Skills.Validate() = %v, want nil", err)+ }+}++func TestValidate_SkillsSelectionOneof(t *testing.T) {+ // withRegistry returns a valid config carrying a single top-level registry.+ // It fills TargetDir (a required field) unless the caller already set one, so+ // selection-mode assertions aren't masked by the target_dir check.+ withRegistry := func(rc SkillsRegistryConfig) *Config {+ if rc.Enabled && rc.TargetDir == "" {+ rc.TargetDir = "/tmp/skills"+ }+ c := validConfig()+ c.Skills.Registries = []SkillsRegistryConfig{rc}+ return c+ }++ t.Run("disabled skips validation", func(t *testing.T) {+ if err := withRegistry(SkillsRegistryConfig{Enabled: false}).Validate(); err != nil {+ t.Fatalf("Validate() = %v, want nil", err)+ }+ })++ t.Run("enabled without target_dir is an error", func(t *testing.T) {+ c := validConfig()+ c.Skills.Registries = []SkillsRegistryConfig{+ {Enabled: true, Project: "p", All: true}, // valid mode, but no target_dir+ }+ err := c.Validate()+ if err == nil || !strings.Contains(err.Error(), "target_dir") {+ t.Fatalf("Validate() = %v, want target_dir error", err)+ }+ })++ t.Run("zero selection modes is an error", func(t *testing.T) {+ err := withRegistry(SkillsRegistryConfig{Enabled: true, Project: "p"}).Validate()+ if err == nil || !strings.Contains(err.Error(), "exactly one selection mode") {+ t.Fatalf("Validate() = %v, want exactly-one error", err)+ }+ })++ t.Run("multiple selection modes is an error", func(t *testing.T) {+ err := withRegistry(SkillsRegistryConfig{+ Enabled: true, Project: "p",+ Skills: []SkillRefConfig{{ID: "emoji"}},+ All: true,+ }).Validate()+ if err == nil || !strings.Contains(err.Error(), "multiple selection modes") {+ t.Fatalf("Validate() = %v, want multiple-modes error", err)+ }+ })++ t.Run("exactly one is valid", func(t *testing.T) {+ err := withRegistry(SkillsRegistryConfig{+ Enabled: true, Project: "p",+ Skills: []SkillRefConfig{{ID: "emoji"}},+ }).Validate()+ if err != nil {+ t.Fatalf("Validate() = %v, want nil", err)+ }+ })++ t.Run("query with empty text is an error", func(t *testing.T) {+ err := withRegistry(SkillsRegistryConfig{+ Enabled: true, Project: "p",+ Query: &SkillsQueryConfig{Text: ""},+ }).Validate()+ if err == nil || !strings.Contains(err.Error(), "non-empty text") {+ t.Fatalf("Validate() = %v, want empty-text error", err)+ }+ })++ t.Run("second registry invalid is caught", func(t *testing.T) {+ c := validConfig()+ c.Skills.Registries = []SkillsRegistryConfig{+ {Enabled: true, Project: "p", TargetDir: "/tmp/a", All: true},+ {Enabled: true, Project: "p", TargetDir: "/tmp/b"}, // no selection mode+ }+ err := c.Validate()+ if err == nil || !strings.Contains(err.Error(), "registries[1]") {+ t.Fatalf("Validate() = %v, want error citing registries[1]", err)+ }+ })+}diff --git a/internal/harness/antigravityinteractions/skills.go b/internal/harness/antigravityinteractions/skills.gonew file mode 100644index 0000000..5e0d57f--- /dev/null+++ b/internal/harness/antigravityinteractions/skills.go@@ -0,0 +1,61 @@+// Copyright 2026 Google LLC+//+// Licensed under the Apache License, Version 2.0 (the "License");+// you may not use this file except in compliance with the License.+// You may obtain a copy of the License at+//+// http://www.apache.org/licenses/LICENSE-2.0+//+// Unless required by applicable law or agreed to in writing, software+// distributed under the License is distributed on an "AS IS" BASIS,+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+// See the License for the specific language governing permissions and+// limitations under the License.++package antigravityinteractions++import (+ "fmt"+ "strings"++ "github.com/google/ax/internal/skills/geminienterprise"+)++// SkillsSystemInstruction builds a system-instruction pointer telling the agent+// where its materialized skills live and lists them.+//+// This is discovery logic specific to the Antigravity Interactions harness: it+// has no SKILLS_DIR concept, so it must be told where to find skills via its+// system instruction (its built-in file tools then read that directory).+// Harnesses that auto-discover a skills directory (e.g. the Antigravity SDK+// harness via SKILLS_DIR) do not use this.+func SkillsSystemInstruction(res geminienterprise.Result) string {+ if res.Empty() {+ return ""+ }+ var b strings.Builder+ for _, w := range res.Written {+ if b.Len() > 0 {+ b.WriteString("\n")+ }+ fmt.Fprintf(&b, "Agent skills are available under %s. Available skills:", w.Dir)+ for _, s := range w.Skills {+ fmt.Fprintf(&b, " %s", s.SkillID)+ }+ b.WriteString(". Read a skill's SKILL.md before using it.")+ }+ return b.String()+}++// JoinSystemInstruction combines a user-configured system instruction with an+// optional skills pointer (from SkillsSystemInstruction), dropping empties.+func JoinSystemInstruction(base, pointer string) string {+ parts := make([]string, 0, 2)+ if strings.TrimSpace(base) != "" {+ parts = append(parts, base)+ }+ if strings.TrimSpace(pointer) != "" {+ parts = append(parts, pointer)+ }+ return strings.Join(parts, "\n\n")+}diff --git a/internal/harness/antigravityinteractions/skills_test.go b/internal/harness/antigravityinteractions/skills_test.gonew file mode 100644index 0000000..151e993--- /dev/null+++ b/internal/harness/antigravityinteractions/skills_test.go@@ -0,0 +1,68 @@+// Copyright 2026 Google LLC+//+// Licensed under the Apache License, Version 2.0 (the "License");+// you may not use this file except in compliance with the License.+// You may obtain a copy of the License at+//+// http://www.apache.org/licenses/LICENSE-2.0+//+// Unless required by applicable law or agreed to in writing, software+// distributed under the License is distributed on an "AS IS" BASIS,+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+// See the License for the specific language governing permissions and+// limitations under the License.++package antigravityinteractions++import (+ "strings"+ "testing"++ "github.com/google/ax/internal/skills/geminienterprise"+)++func TestSkillsSystemInstruction(t *testing.T) {+ t.Run("empty result yields empty pointer", func(t *testing.T) {+ if got := SkillsSystemInstruction(geminienterprise.Result{}); got != "" {+ t.Errorf("empty result pointer = %q, want empty", got)+ }+ })++ t.Run("mentions dir and skill ids", func(t *testing.T) {+ res := geminienterprise.Result{Written: []geminienterprise.Written{{+ Dir: "/workspace",+ Skills: []geminienterprise.MaterializedSkill{{SkillID: "emoji"}, {SkillID: "lowercase"}},+ }}}+ got := SkillsSystemInstruction(res)+ if !strings.Contains(got, "/workspace") || !strings.Contains(got, "emoji") || !strings.Contains(got, "lowercase") {+ t.Errorf("pointer = %q, want it to mention dir and skill ids", got)+ }+ })++ t.Run("multiple registries produce multiple lines", func(t *testing.T) {+ res := geminienterprise.Result{Written: []geminienterprise.Written{+ {Dir: "/a", Skills: []geminienterprise.MaterializedSkill{{SkillID: "s1"}}},+ {Dir: "/b", Skills: []geminienterprise.MaterializedSkill{{SkillID: "s2"}}},+ }}+ got := SkillsSystemInstruction(res)+ if !strings.Contains(got, "/a") || !strings.Contains(got, "/b") || !strings.Contains(got, "\n") {+ t.Errorf("pointer = %q, want both dirs on separate lines", got)+ }+ })+}++func TestJoinSystemInstruction(t *testing.T) {+ cases := []struct {+ base, ptr, want string+ }{+ {"", "", ""},+ {"base only", "", "base only"},+ {"", "ptr only", "ptr only"},+ {"base", "ptr", "base\n\nptr"},+ }+ for _, c := range cases {+ if got := JoinSystemInstruction(c.base, c.ptr); got != c.want {+ t.Errorf("join(%q,%q) = %q, want %q", c.base, c.ptr, got, c.want)+ }+ }+}diff --git a/internal/skills/geminienterprise/client.go b/internal/skills/geminienterprise/client.gonew file mode 100644index 0000000..93e4f72--- /dev/null+++ b/internal/skills/geminienterprise/client.go@@ -0,0 +1,400 @@+// Copyright 2026 Google LLC+//+// Licensed under the Apache License, Version 2.0 (the "License");+// you may not use this file except in compliance with the License.+// You may obtain a copy of the License at+//+// http://www.apache.org/licenses/LICENSE-2.0+//+// Unless required by applicable law or agreed to in writing, software+// distributed under the License is distributed on an "AS IS" BASIS,+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+// See the License for the specific language governing permissions and+// limitations under the License.++// This file is the internal Gemini Enterprise Skill Registry transport client: it talks to the+// Vertex AI v1beta1 REST API (ListSkills / GetSkill / GetSkillRevision /+// skills:retrieve), fetches skill payloads, and safe-unzips them to disk. The+// public, config-driven orchestration lives in materialize.go.++package geminienterprise++import (+ "context"+ "encoding/base64"+ "encoding/json"+ "errors"+ "fmt"+ "io"+ "log"+ "net/http"+ "net/url"+ "os"+ "path/filepath"+ "strings"+ "time"++ "golang.org/x/oauth2"+ "golang.org/x/oauth2/google"+)++// cloudPlatformScope is the OAuth2 scope required to call Vertex AI (read path+// needs roles/aiplatform.viewer).+const cloudPlatformScope = "https://www.googleapis.com/auth/cloud-platform"++// apiVersion is the Vertex AI API version the Skill Registry is exposed under.+const apiVersion = "v1beta1"++// defaultHTTPTimeout bounds a single registry HTTP call.+const defaultHTTPTimeout = 60 * time.Second++// client fetches a selected set of skills from the Gemini Enterprise Skill Registry and+// writes them into a target directory as agentskills.io skill folders.+type client struct {+ baseURL string // .../v1beta1/projects/{project}/locations/{location}/skills+ http *http.Client+ ts oauth2.TokenSource+ caps unzipCaps+}++// clientOptions configures a client. newClient fills defaults for optional fields.+type clientOptions struct {+ // --- Required ---++ // Project is the Google Cloud project that owns the skills.+ Project string+ // Location is the registry region, e.g. "us-central1". Selects the Vertex+ // host (https://{Location}-aiplatform.googleapis.com) unless Endpoint is set.+ Location string++ // --- Optional (newClient fills defaults) ---++ // Endpoint overrides the API host (scheme+host, no trailing slash), e.g. a+ // sandbox host or an httptest.Server URL in unit tests.+ Endpoint string+ // HTTPClient is the client used for all registry calls. Defaults to+ // http.Client{Timeout: 60s}.+ HTTPClient *http.Client+ // TokenSource provides the OAuth2 bearer token. If nil, ADC is used+ // (roles/aiplatform.viewer). Set to a static source in tests.+ TokenSource oauth2.TokenSource+ // Caps bounds a defensive local unzip of untrusted payloads.+ Caps unzipCaps+}++// newClient constructs a client from options. It validates required fields and+// fills defaults; it performs no network I/O.+func newClient(opts clientOptions) (*client, error) {+ if opts.Project == "" {+ return nil, errors.New("registry: Project is required")+ }+ if opts.Location == "" {+ return nil, errors.New("registry: Location is required")+ }++ host := opts.Endpoint+ if host == "" {+ host = fmt.Sprintf("https://%s-aiplatform.googleapis.com", opts.Location)+ }+ host = strings.TrimSuffix(host, "/")+ baseURL := fmt.Sprintf("%s/%s/projects/%s/locations/%s/skills",+ host, apiVersion, opts.Project, opts.Location)++ httpClient := opts.HTTPClient+ if httpClient == nil {+ httpClient = &http.Client{Timeout: defaultHTTPTimeout}+ }++ ts := opts.TokenSource+ if ts == nil {+ creds, err := google.FindDefaultCredentials(context.Background(), cloudPlatformScope)+ if err != nil {+ return nil, fmt.Errorf("registry: finding application default credentials: %w", err)+ }+ ts = creds.TokenSource+ }++ return &client{+ baseURL: baseURL,+ http: httpClient,+ ts: ts,+ caps: opts.Caps.withDefaults(),+ }, nil+}++// selection describes WHICH skills to fetch. Exactly one of the three modes+// should be set (all / by-id / by-query).+type selection struct {+ // All fetches every skill returned by ListSkills for the project/location.+ All bool+ // SkillRefs is an explicit allowlist, each optionally pinned to a revision.+ SkillRefs []skillRef+ // Query is a semantic search string; the top matches are fetched. TopK bounds+ // the result count (<=0 means the server default).+ Query string+ TopK int+}++// skillRef identifies a single skill to fetch, optionally pinned.+type skillRef struct {+ SkillID string+ Revision string // empty => latest default revision+}++// fetchResult reports the outcome of a fetch call. fetch is fail-safe: a skill+// that cannot be fetched or unzipped is recorded in skipped.+type fetchResult struct {+ materialized []MaterializedSkill+ skipped []skippedSkill+}++// skippedSkill records a skill that was intentionally not written, and why.+type skippedSkill struct {+ skillID string+ reason error+}++// fetch resolves the selection, fetches each skill's payload, and safe-unzips it+// into targetDir as <targetDir>/<skillID>/... targetDir is created if missing.+//+// claimed enforces first-wins across the whole operation: a skill id whose+// (targetDir, id) was already materialized (by this registry's own selection or+// an earlier registry sharing the dir) is skipped with a warning rather than+// overwriting the winner. regIdx is the registry's index, for log context.+//+// It is fail-safe: individual skill failures are collected in fetchResult.skipped;+// fetch returns a non-nil error only for whole-operation failures.+func (c *client) fetch(ctx context.Context, sel selection, targetDir string, claimed *claimSet, regIdx int) (*fetchResult, error) {+ refs, err := c.resolveSelection(ctx, sel)+ if err != nil {+ return nil, fmt.Errorf("registry: resolving selection: %w", err)+ }+ if err := os.MkdirAll(targetDir, 0o755); err != nil {+ return nil, fmt.Errorf("registry: creating target dir %q: %w", targetDir, err)+ }++ res := &fetchResult{}+ for _, ref := range refs {+ // First-wins: skip (with a warning) any id already materialized into this+ // dir, rather than overwriting it.+ if won, byRegistry := claimed.claim(targetDir, ref.SkillID, regIdx); !won {+ log.Printf("skills: registries[%d] skill %q already materialized into %s by registries[%d]; keeping the first, skipping this one",+ regIdx, ref.SkillID, targetDir, byRegistry)+ continue+ }+ mat, err := c.fetchAndWrite(ctx, ref, targetDir)+ if err != nil {+ res.skipped = append(res.skipped, skippedSkill{skillID: ref.SkillID, reason: err})+ continue+ }+ res.materialized = append(res.materialized, *mat)+ }+ return res, nil+}++// resolveSelection turns a selection into a concrete list of skillRefs to fetch.+func (c *client) resolveSelection(ctx context.Context, sel selection) ([]skillRef, error) {+ switch {+ case len(sel.SkillRefs) > 0:+ return sel.SkillRefs, nil+ case sel.Query != "":+ ids, err := c.retrieveSkillIDs(ctx, sel.Query, sel.TopK)+ if err != nil {+ return nil, err+ }+ return toRefs(ids), nil+ case sel.All:+ ids, err := c.listSkillIDs(ctx)+ if err != nil {+ return nil, err+ }+ return toRefs(ids), nil+ default:+ return nil, errors.New("empty selection: set All, SkillRefs, or Query")+ }+}++// fetchAndWrite fetches one skill's payload (latest or pinned) and unzips it.+func (c *client) fetchAndWrite(ctx context.Context, ref skillRef, targetDir string) (*MaterializedSkill, error) {+ if ref.SkillID == "" {+ return nil, errors.New("skill ref has empty SkillID")+ }+ payloadB64, revision, err := c.fetchPayload(ctx, ref)+ if err != nil {+ return nil, err+ }+ zipped, err := base64.StdEncoding.DecodeString(payloadB64)+ if err != nil {+ return nil, fmt.Errorf("decoding payload: %w", err)+ }+ skillDir := filepath.Join(targetDir, ref.SkillID)+ // Replace any prior materialization of this skill so stale files don't linger.+ if err := os.RemoveAll(skillDir); err != nil {+ return nil, fmt.Errorf("clearing %q: %w", skillDir, err)+ }+ if err := safeUnzip(zipped, skillDir, c.caps); err != nil {+ // Leave no partial dir behind on failure.+ _ = os.RemoveAll(skillDir)+ return nil, fmt.Errorf("unzipping: %w", err)+ }+ return &MaterializedSkill{SkillID: ref.SkillID, Revision: revision, Dir: skillDir}, nil+}++// fetchPayload returns the base64 zippedFilesystem and the concrete revision id+// for a skill ref (GetSkill for latest, GetSkillRevision when pinned).+func (c *client) fetchPayload(ctx context.Context, ref skillRef) (payloadB64, revision string, err error) {+ if ref.Revision != "" {+ // GetSkillRevision: payload is nested under "skill".+ var resp skillRevisionResponse+ if err := c.getJSON(ctx, c.baseURL+"/"+ref.SkillID+"/revisions/"+ref.Revision, &resp); err != nil {+ return "", "", err+ }+ if resp.Skill.ZippedFilesystem == "" {+ return "", "", errors.New("GetSkillRevision: empty zippedFilesystem")+ }+ return resp.Skill.ZippedFilesystem, ref.Revision, nil+ }+ // GetSkill: payload at top level.+ var resp skillResponse+ if err := c.getJSON(ctx, c.baseURL+"/"+ref.SkillID, &resp); err != nil {+ return "", "", err+ }+ if resp.ZippedFilesystem == "" {+ return "", "", errors.New("GetSkill: empty zippedFilesystem")+ }+ return resp.ZippedFilesystem, resp.currentRevision(), nil+}++// listSkillIDs pages through ListSkills and returns all skill ids.+func (c *client) listSkillIDs(ctx context.Context) ([]string, error) {+ var ids []string+ pageToken := ""+ for {+ u := c.baseURL+ if pageToken != "" {+ u += "?pageToken=" + url.QueryEscape(pageToken)+ }+ var resp listSkillsResponse+ if err := c.getJSON(ctx, u, &resp); err != nil {+ return nil, err+ }+ for _, s := range resp.Skills {+ if id := s.id(); id != "" {+ ids = append(ids, id)+ }+ }+ if resp.NextPageToken == "" {+ return ids, nil+ }+ pageToken = resp.NextPageToken+ }+}++// retrieveSkillIDs runs semantic search (skills:retrieve) and returns skill ids.+func (c *client) retrieveSkillIDs(ctx context.Context, query string, topK int) ([]string, error) {+ u := c.baseURL + ":retrieve?query=" + url.QueryEscape(query)+ if topK > 0 {+ u += fmt.Sprintf("&topK=%d", topK)+ }+ var resp retrieveSkillsResponse+ if err := c.getJSON(ctx, u, &resp); err != nil {+ return nil, err+ }+ var ids []string+ for _, r := range resp.RetrievedSkills {+ if id := lastSegment(r.SkillName); id != "" {+ ids = append(ids, id)+ }+ }+ return ids, nil+}++// getJSON issues an authenticated GET and decodes the JSON body into out.+func (c *client) getJSON(ctx context.Context, rawURL string, out any) error {+ req, err := http.NewRequestWithContext(ctx, http.MethodGet, rawURL, nil)+ if err != nil {+ return err+ }+ tok, err := c.ts.Token()+ if err != nil {+ return fmt.Errorf("obtaining token: %w", err)+ }+ tok.SetAuthHeader(req)+ req.Header.Set("Content-Type", "application/json")++ resp, err := c.http.Do(req)+ if err != nil {+ return err+ }+ defer resp.Body.Close()+ body, _ := io.ReadAll(resp.Body)+ if resp.StatusCode != http.StatusOK {+ return fmt.Errorf("HTTP %d: %s", resp.StatusCode, truncate(string(body), 512))+ }+ if err := json.Unmarshal(body, out); err != nil {+ return fmt.Errorf("decoding response: %w", err)+ }+ return nil+}++// --- Wire types (AIP-standard shapes; see the design doc appendix). ---++type listSkillsResponse struct {+ Skills []skillResponse `json:"skills"`+ NextPageToken string `json:"nextPageToken"`+}++// retrieveSkillsResponse is a skills:retrieve result. Each hit carries the skill+// resource name in a flat "skillName" field (not a nested skill object).+type retrieveSkillsResponse struct {+ RetrievedSkills []struct {+ SkillName string `json:"skillName"` // projects/.../skills/{id}+ } `json:"retrievedSkills"`+}++// skillResponse is a Skill resource. GetSkill returns the payload at top level.+type skillResponse struct {+ Name string `json:"name"` // projects/.../skills/{id}+ DisplayName string `json:"displayName"`+ Description string `json:"description"`+ State string `json:"state"`+ DefaultRevision string `json:"defaultRevision"`+ ZippedFilesystem string `json:"zippedFilesystem"`+}++// skillRevisionResponse is a GetSkillRevision result; the payload is nested+// under "skill".+type skillRevisionResponse struct {+ Name string `json:"name"` // projects/.../skills/{id}/revisions/{rev}+ Skill skillResponse `json:"skill"`+}++// id extracts the trailing skill id from a resource name.+func (s skillResponse) id() string { return lastSegment(s.Name) }++// currentRevision reports the skill's default revision id, if the server provided+// one (best-effort; may be empty for "latest").+func (s skillResponse) currentRevision() string { return lastSegment(s.DefaultRevision) }++func lastSegment(resourceName string) string {+ if resourceName == "" {+ return ""+ }+ parts := strings.Split(resourceName, "/")+ return parts[len(parts)-1]+}++func toRefs(ids []string) []skillRef {+ refs := make([]skillRef, 0, len(ids))+ for _, id := range ids {+ refs = append(refs, skillRef{SkillID: id})+ }+ return refs+}++func truncate(s string, n int) string {+ if len(s) <= n {+ return s+ }+ return s[:n] + "...(truncated)"+}diff --git a/internal/skills/geminienterprise/client_test.go b/internal/skills/geminienterprise/client_test.gonew file mode 100644index 0000000..39285b5--- /dev/null+++ b/internal/skills/geminienterprise/client_test.go@@ -0,0 +1,414 @@+// Copyright 2026 Google LLC+//+// Licensed under the Apache License, Version 2.0 (the "License");+// you may not use this file except in compliance with the License.+// You may obtain a copy of the License at+//+// http://www.apache.org/licenses/LICENSE-2.0+//+// Unless required by applicable law or agreed to in writing, software+// distributed under the License is distributed on an "AS IS" BASIS,+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+// See the License for the specific language governing permissions and+// limitations under the License.++package geminienterprise++import (+ "archive/zip"+ "bytes"+ "context"+ "encoding/base64"+ "encoding/json"+ "fmt"+ "net/http"+ "net/http/httptest"+ "os"+ "path/filepath"+ "strings"+ "testing"++ "golang.org/x/oauth2"+)++// zipFixtureB64 builds an in-memory zip from name->content and returns the base64+// string the registry would return in `zippedFilesystem`.+func zipFixtureB64(t *testing.T, files map[string]string) string {+ t.Helper()+ var buf bytes.Buffer+ zw := zip.NewWriter(&buf)+ for name, content := range files {+ w, err := zw.Create(name)+ if err != nil {+ t.Fatalf("zip create %q: %v", name, err)+ }+ if _, err := w.Write([]byte(content)); err != nil {+ t.Fatalf("zip write %q: %v", name, err)+ }+ }+ if err := zw.Close(); err != nil {+ t.Fatalf("zip close: %v", err)+ }+ return base64.StdEncoding.EncodeToString(buf.Bytes())+}++// rawZipFixture returns the raw zip bytes (for direct safeUnzip tests).+func rawZipFixture(t *testing.T, files map[string]string) []byte {+ t.Helper()+ b, err := base64.StdEncoding.DecodeString(zipFixtureB64(t, files))+ if err != nil {+ t.Fatalf("decode fixture: %v", err)+ }+ return b+}++// newFakeClient returns a client pointed at an httptest.Server whose handler is+// provided by the caller, with a no-op token source.+func newFakeClient(t *testing.T, handler http.HandlerFunc) *client {+ t.Helper()+ srv := httptest.NewServer(handler)+ t.Cleanup(srv.Close)+ c, err := newClient(clientOptions{+ Project: "test-project",+ Location: "us-central1",+ Endpoint: srv.URL,+ TokenSource: oauth2.StaticTokenSource(&oauth2.Token{AccessToken: "fake"}),+ })+ if err != nil {+ t.Fatalf("newClient: %v", err)+ }+ return c+}++func TestFetchByID_Latest(t *testing.T) {+ payload := zipFixtureB64(t, map[string]string{+ "SKILL.md": "---\nname: emoji\n---\n# do stuff",+ "scripts/x.sh": "echo hi",+ })+ c := newFakeClient(t, func(w http.ResponseWriter, r *http.Request) {+ // GetSkill: .../skills/emoji -> zippedFilesystem at top level.+ if !strings.HasSuffix(r.URL.Path, "/skills/emoji") {+ http.Error(w, "unexpected path "+r.URL.Path, http.StatusNotFound)+ return+ }+ writeJSON(t, w, skillResponse{+ Name: "projects/p/locations/us-central1/skills/emoji",+ DefaultRevision: "projects/p/locations/us-central1/skills/emoji/revisions/rev-7",+ ZippedFilesystem: payload,+ })+ })++ dir := t.TempDir()+ res, err := c.fetch(context.Background(),+ selection{SkillRefs: []skillRef{{SkillID: "emoji"}}}, dir, newClaimSet(), 0)+ if err != nil {+ t.Fatalf("fetch: %v", err)+ }+ if len(res.skipped) != 0 {+ t.Fatalf("unexpected skipped: %+v", res.skipped)+ }+ if len(res.materialized) != 1 {+ t.Fatalf("materialized = %d, want 1", len(res.materialized))+ }+ got := res.materialized[0]+ if got.SkillID != "emoji" || got.Revision != "rev-7" {+ t.Errorf("got %+v, want SkillID=emoji Revision=rev-7", got)+ }+ assertFile(t, filepath.Join(dir, "emoji", "SKILL.md"), "---\nname: emoji\n---\n# do stuff")+ assertFile(t, filepath.Join(dir, "emoji", "scripts", "x.sh"), "echo hi")+}++func TestFetchByID_PinnedRevision(t *testing.T) {+ payload := zipFixtureB64(t, map[string]string{"SKILL.md": "pinned"})+ c := newFakeClient(t, func(w http.ResponseWriter, r *http.Request) {+ // GetSkillRevision: .../skills/emoji/revisions/rev-3 -> nested under "skill".+ if !strings.HasSuffix(r.URL.Path, "/skills/emoji/revisions/rev-3") {+ http.Error(w, "unexpected path "+r.URL.Path, http.StatusNotFound)+ return+ }+ writeJSON(t, w, skillRevisionResponse{+ Name: "projects/p/locations/us-central1/skills/emoji/revisions/rev-3",+ Skill: skillResponse{ZippedFilesystem: payload},+ })+ })++ dir := t.TempDir()+ res, err := c.fetch(context.Background(),+ selection{SkillRefs: []skillRef{{SkillID: "emoji", Revision: "rev-3"}}}, dir, newClaimSet(), 0)+ if err != nil {+ t.Fatalf("fetch: %v", err)+ }+ if len(res.materialized) != 1 || res.materialized[0].Revision != "rev-3" {+ t.Fatalf("got %+v, want one skill pinned at rev-3", res.materialized)+ }+ assertFile(t, filepath.Join(dir, "emoji", "SKILL.md"), "pinned")+}++func TestFetchAll_Paginated(t *testing.T) {+ pa := zipFixtureB64(t, map[string]string{"SKILL.md": "a"})+ pb := zipFixtureB64(t, map[string]string{"SKILL.md": "b"})+ c := newFakeClient(t, func(w http.ResponseWriter, r *http.Request) {+ switch {+ case strings.HasSuffix(r.URL.Path, "/skills") && r.URL.Query().Get("pageToken") == "":+ writeJSON(t, w, listSkillsResponse{+ Skills: []skillResponse{{Name: ".../skills/a"}},+ NextPageToken: "TOK",+ })+ case strings.HasSuffix(r.URL.Path, "/skills") && r.URL.Query().Get("pageToken") == "TOK":+ writeJSON(t, w, listSkillsResponse{Skills: []skillResponse{{Name: ".../skills/b"}}})+ case strings.HasSuffix(r.URL.Path, "/skills/a"):+ writeJSON(t, w, skillResponse{Name: ".../skills/a", ZippedFilesystem: pa})+ case strings.HasSuffix(r.URL.Path, "/skills/b"):+ writeJSON(t, w, skillResponse{Name: ".../skills/b", ZippedFilesystem: pb})+ default:+ http.Error(w, "unexpected "+r.URL.String(), http.StatusNotFound)+ }+ })++ dir := t.TempDir()+ res, err := c.fetch(context.Background(), selection{All: true}, dir, newClaimSet(), 0)+ if err != nil {+ t.Fatalf("fetch: %v", err)+ }+ if len(res.materialized) != 2 {+ t.Fatalf("materialized = %d, want 2 (paged)", len(res.materialized))+ }+ assertFile(t, filepath.Join(dir, "a", "SKILL.md"), "a")+ assertFile(t, filepath.Join(dir, "b", "SKILL.md"), "b")+}++func TestFetchByQuery(t *testing.T) {+ payload := zipFixtureB64(t, map[string]string{"SKILL.md": "found"})+ c := newFakeClient(t, func(w http.ResponseWriter, r *http.Request) {+ switch {+ case strings.Contains(r.URL.Path, "/skills:retrieve"):+ if got := r.URL.Query().Get("query"); got != "emoji stuff" {+ t.Errorf("query = %q, want %q", got, "emoji stuff")+ }+ writeJSON(t, w, retrieveSkillsResponse{+ RetrievedSkills: []struct {+ SkillName string `json:"skillName"`+ }{{SkillName: ".../skills/emoji"}},+ })+ case strings.HasSuffix(r.URL.Path, "/skills/emoji"):+ writeJSON(t, w, skillResponse{Name: ".../skills/emoji", ZippedFilesystem: payload})+ default:+ http.Error(w, "unexpected "+r.URL.String(), http.StatusNotFound)+ }+ })++ dir := t.TempDir()+ res, err := c.fetch(context.Background(),+ selection{Query: "emoji stuff", TopK: 3}, dir, newClaimSet(), 0)+ if err != nil {+ t.Fatalf("fetch: %v", err)+ }+ if len(res.materialized) != 1 {+ t.Fatalf("materialized = %d, want 1", len(res.materialized))+ }+ assertFile(t, filepath.Join(dir, "emoji", "SKILL.md"), "found")+}++func TestFetchFailSafe_OneBadSkillSkipped(t *testing.T) {+ good := zipFixtureB64(t, map[string]string{"SKILL.md": "ok"})+ c := newFakeClient(t, func(w http.ResponseWriter, r *http.Request) {+ switch {+ case strings.HasSuffix(r.URL.Path, "/skills/good"):+ writeJSON(t, w, skillResponse{Name: ".../skills/good", ZippedFilesystem: good})+ case strings.HasSuffix(r.URL.Path, "/skills/bad"):+ http.Error(w, "boom", http.StatusInternalServerError)+ default:+ http.Error(w, "unexpected", http.StatusNotFound)+ }+ })++ dir := t.TempDir()+ res, err := c.fetch(context.Background(),+ selection{SkillRefs: []skillRef{{SkillID: "good"}, {SkillID: "bad"}}}, dir, newClaimSet(), 0)+ if err != nil {+ t.Fatalf("fetch returned whole-op error, want fail-safe: %v", err)+ }+ if len(res.materialized) != 1 || res.materialized[0].SkillID != "good" {+ t.Errorf("materialized = %+v, want only 'good'", res.materialized)+ }+ if len(res.skipped) != 1 || res.skipped[0].skillID != "bad" {+ t.Errorf("skipped = %+v, want only 'bad'", res.skipped)+ }+ // The bad skill left no directory behind.+ if _, err := os.Stat(filepath.Join(dir, "bad")); !os.IsNotExist(err) {+ t.Errorf("expected no dir for 'bad', stat err = %v", err)+ }+}++func TestFetch_FirstWinsAcrossSharedClaimSet(t *testing.T) {+ // Two fetches (simulating two registries) into the SAME dir with a SHARED+ // claim set. Both offer skill id "dup"; only the first should be written.+ payloadA := zipFixtureB64(t, map[string]string{"SKILL.md": "from-A"})+ payloadB := zipFixtureB64(t, map[string]string{"SKILL.md": "from-B"})++ makeClient := func(payload string) *client {+ return newFakeClient(t, func(w http.ResponseWriter, r *http.Request) {+ if !strings.HasSuffix(r.URL.Path, "/skills/dup") {+ http.Error(w, "unexpected "+r.URL.Path, http.StatusNotFound)+ return+ }+ writeJSON(t, w, skillResponse{Name: ".../skills/dup", ZippedFilesystem: payload})+ })+ }++ dir := t.TempDir()+ claimed := newClaimSet()+ sel := selection{SkillRefs: []skillRef{{SkillID: "dup"}}}++ // Registry 0 wins.+ res0, err := makeClient(payloadA).fetch(context.Background(), sel, dir, claimed, 0)+ if err != nil {+ t.Fatalf("fetch #0: %v", err)+ }+ if len(res0.materialized) != 1 {+ t.Fatalf("registry 0 materialized %d, want 1", len(res0.materialized))+ }++ // Registry 1 offers the same id into the same dir -> skipped (not written).+ res1, err := makeClient(payloadB).fetch(context.Background(), sel, dir, claimed, 1)+ if err != nil {+ t.Fatalf("fetch #1: %v", err)+ }+ if len(res1.materialized) != 0 {+ t.Errorf("registry 1 materialized %d, want 0 (first-wins)", len(res1.materialized))+ }+ // The content on disk must be the FIRST writer's.+ assertFile(t, filepath.Join(dir, "dup", "SKILL.md"), "from-A")+}++func TestNewClientValidation(t *testing.T) {+ if _, err := newClient(clientOptions{Location: "us-central1"}); err == nil {+ t.Error("expected error for missing Project")+ }+ if _, err := newClient(clientOptions{Project: "p"}); err == nil {+ t.Error("expected error for missing Location")+ }+}++// --- safeUnzip unit tests ---++func TestSafeUnzip_Basic(t *testing.T) {+ z := rawZipFixture(t, map[string]string{+ "SKILL.md": "hi",+ "scripts/tool.sh": "run",+ "references/a.txt": "ref",+ })+ dir := t.TempDir()+ if err := safeUnzip(z, filepath.Join(dir, "s"), unzipCaps{}.withDefaults()); err != nil {+ t.Fatalf("safeUnzip: %v", err)+ }+ assertFile(t, filepath.Join(dir, "s", "SKILL.md"), "hi")+ assertFile(t, filepath.Join(dir, "s", "scripts", "tool.sh"), "run")+}++func TestSafeUnzip_PreservesExecutableMode(t *testing.T) {+ // Build a zip with an executable script (0755) and a normal file (0644),+ // setting per-entry modes via CreateHeader.+ var buf bytes.Buffer+ zw := zip.NewWriter(&buf)+ writeEntry := func(name, content string, mode os.FileMode) {+ hdr := &zip.FileHeader{Name: name, Method: zip.Deflate}+ hdr.SetMode(mode)+ w, err := zw.CreateHeader(hdr)+ if err != nil {+ t.Fatalf("CreateHeader %q: %v", name, err)+ }+ if _, err := w.Write([]byte(content)); err != nil {+ t.Fatalf("write %q: %v", name, err)+ }+ }+ writeEntry("scripts/tool.sh", "#!/bin/sh\necho hi\n", 0o755)+ writeEntry("SKILL.md", "hi", 0o644)+ if err := zw.Close(); err != nil {+ t.Fatalf("zip close: %v", err)+ }++ dir := t.TempDir()+ if err := safeUnzip(buf.Bytes(), filepath.Join(dir, "s"), unzipCaps{}.withDefaults()); err != nil {+ t.Fatalf("safeUnzip: %v", err)+ }++ scriptInfo, err := os.Stat(filepath.Join(dir, "s", "scripts", "tool.sh"))+ if err != nil {+ t.Fatal(err)+ }+ if scriptInfo.Mode().Perm()&0o100 == 0 {+ t.Errorf("script mode = %v, want owner-execute bit set (0755 preserved)", scriptInfo.Mode().Perm())+ }+ mdInfo, err := os.Stat(filepath.Join(dir, "s", "SKILL.md"))+ if err != nil {+ t.Fatal(err)+ }+ if mdInfo.Mode().Perm()&0o111 != 0 {+ t.Errorf("SKILL.md mode = %v, want no execute bits (0644)", mdInfo.Mode().Perm())+ }+}++func TestSafeUnzip_ZipSlipRejected(t *testing.T) {+ for _, bad := range []string{"../evil.txt", "a/../../evil.txt", "/etc/evil"} {+ z := rawZipFixture(t, map[string]string{bad: "x"})+ dir := t.TempDir()+ err := safeUnzip(z, filepath.Join(dir, "s"), unzipCaps{}.withDefaults())+ if err == nil {+ t.Errorf("entry %q: expected rejection, got nil", bad)+ continue+ }+ if _, statErr := os.Stat(filepath.Join(dir, "evil.txt")); !os.IsNotExist(statErr) {+ t.Errorf("entry %q: file escaped destination", bad)+ }+ }+}++func TestSafeUnzip_TooManyFiles(t *testing.T) {+ files := map[string]string{}+ for i := 0; i < 5; i++ {+ files[fmt.Sprintf("f%d.txt", i)] = "x"+ }+ z := rawZipFixture(t, files)+ err := safeUnzip(z, t.TempDir(), unzipCaps{MaxFiles: 3}.withDefaults())+ if err == nil || !strings.Contains(err.Error(), "exceeds cap") {+ t.Fatalf("expected MaxFiles cap error, got %v", err)+ }+}++func TestSafeUnzip_TooLarge(t *testing.T) {+ z := rawZipFixture(t, map[string]string{"big.txt": strings.Repeat("A", 1000)})+ err := safeUnzip(z, t.TempDir(), unzipCaps{MaxTotalUnzippedBytes: 100}.withDefaults())+ if err == nil || !strings.Contains(err.Error(), "size") {+ t.Fatalf("expected size cap error, got %v", err)+ }+}++func TestSafeUnzip_TooDeep(t *testing.T) {+ z := rawZipFixture(t, map[string]string{"a/b/c/d/e/f/g/h/i/j/deep.txt": "x"})+ err := safeUnzip(z, t.TempDir(), unzipCaps{MaxDepth: 3}.withDefaults())+ if err == nil || !strings.Contains(err.Error(), "depth") {+ t.Fatalf("expected depth cap error, got %v", err)+ }+}++// --- helpers ---++func writeJSON(t *testing.T, w http.ResponseWriter, v any) {+ t.Helper()+ w.Header().Set("Content-Type", "application/json")+ if err := json.NewEncoder(w).Encode(v); err != nil {+ t.Fatalf("encode response: %v", err)+ }+}++func assertFile(t *testing.T, path, want string) {+ t.Helper()+ got, err := os.ReadFile(path)+ if err != nil {+ t.Fatalf("reading %q: %v", path, err)+ }+ if string(got) != want {+ t.Errorf("%q = %q, want %q", path, got, want)+ }+}diff --git a/internal/skills/geminienterprise/materialize.go b/internal/skills/geminienterprise/materialize.gonew file mode 100644index 0000000..9c2f942--- /dev/null+++ b/internal/skills/geminienterprise/materialize.go@@ -0,0 +1,173 @@+// Copyright 2026 Google LLC+//+// Licensed under the Apache License, Version 2.0 (the "License");+// you may not use this file except in compliance with the License.+// You may obtain a copy of the License at+//+// http://www.apache.org/licenses/LICENSE-2.0+//+// Unless required by applicable law or agreed to in writing, software+// distributed under the License is distributed on an "AS IS" BASIS,+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+// See the License for the specific language governing permissions and+// limitations under the License.++// Package geminienterprise turns a harness's skills configuration into on-disk+// skill folders. It sources agentskills.io skills from the Gemini Enterprise+// Skill Registry (a managed, versioned catalog exposed over the Vertex AI+// v1beta1 REST API) and writes each skill to <target_dir>/<skill-id>/.+//+// It is harness-agnostic: it only writes files and reports what it wrote (see+// Result). It knows nothing about specific harnesses, SKILLS_DIR, or discovery+// pointers — callers decide how a given harness is told where its skills are.+//+// Scope: read-only. This package never creates, updates, or deletes registry+// skills (authoring is out of scope).+package geminienterprise++import (+ "context"+ "log"+ "os"+ "strings"++ "github.com/google/ax/internal/config"+)++// Environment fallbacks for project/location (the registry target_dir is a+// required config field, so it has no env fallback).+const (+ envCloudProject = "GOOGLE_CLOUD_PROJECT"+ envCloudLocation = "GOOGLE_CLOUD_LOCATION"++ defaultRegistryLocation = "us-central1"+)++// Result reports what Materialize wrote: one Written entry per registry that+// produced skills, grouping the skills with the directory they landed in.+type Result struct {+ Written []Written+}++// Written groups the skills materialized from one registry with the directory+// they were written into (each skill at <Dir>/<skill-id>/).+type Written struct {+ Dir string+ Skills []MaterializedSkill+}++// Empty reports whether nothing was materialized.+func (r Result) Empty() bool { return len(r.Written) == 0 }++// MaterializedSkill records one skill written to disk.+type MaterializedSkill struct {+ SkillID string+ Revision string+ Dir string // path of the written skill folder (<target_dir>/<skill-id>/)+}++// Materialize materializes every enabled registry in sc into its configured+// target_dir (each skill at <target_dir>/<skill-id>/) and reports what it wrote.+//+// target_dir is a required, validated config field (see config.SkillsConfig), so+// this does not fall back to any env var or the working directory. It is+// fail-safe: disabled registries are skipped, and any registry error is logged+// and swallowed so a skill problem never blocks harness creation. When the same+// skill id would be written into the same dir more than once (within one+// registry's selection, or across registries sharing a dir), the FIRST writer+// wins and later duplicates are skipped with a warning. Substrate/pod+// materialization is a separate, later path; this wires the local flow only.+func Materialize(ctx context.Context, sc config.SkillsConfig) Result {+ var res Result+ // claimed tracks (target_dir, skill-id) pairs already written across all+ // registries so the FIRST writer of an id into a dir wins; later duplicates+ // (within one registry's selection, or across registries sharing a dir) are+ // skipped with a warning instead of silently overwriting.+ claimed := newClaimSet()+ // TODO: fetches are sequential (both here and per-skill in client.fetch);+ // consider bounded-concurrent download/unzip to speed up materialization.+ // TODO: bound overall materialization with a deadline (only per-call HTTP+ // timeouts exist today); e.g. a default ~120s that users can override.+ for i := range sc.Registries {+ rc := sc.Registries[i]+ if !rc.Enabled {+ continue+ }+ project := firstNonEmpty(rc.Project, os.Getenv(envCloudProject))+ if project == "" {+ log.Printf("skills: registries[%d] enabled but no project (config or %s); skipping", i, envCloudProject)+ continue+ }+ location := firstNonEmpty(rc.Location, os.Getenv(envCloudLocation), defaultRegistryLocation)++ c, err := newClient(clientOptions{Project: project, Location: location})+ if err != nil {+ log.Printf("skills: registries[%d] client init failed: %v; skipping", i, err)+ continue+ }+ out, err := c.fetch(ctx, selectionFromConfig(rc), rc.TargetDir, claimed, i)+ if err != nil {+ log.Printf("skills: registries[%d] fetch failed: %v; continuing", i, err)+ continue+ }+ for _, s := range out.skipped {+ log.Printf("skills: registries[%d] skipped %q: %v", i, s.skillID, s.reason)+ }+ if len(out.materialized) == 0 {+ continue+ }+ log.Printf("skills: registries[%d] materialized %d skill(s) into %s (skipped %d)",+ i, len(out.materialized), rc.TargetDir, len(out.skipped))+ res.Written = append(res.Written, Written{Dir: rc.TargetDir, Skills: out.materialized})+ }+ return res+}++// claimSet tracks which (dir, skill-id) pairs have already been materialized, so+// the first writer of a given id into a given dir wins.+type claimSet struct {+ seen map[string]int // key -> registry index that first claimed it+}++func newClaimSet() *claimSet { return &claimSet{seen: map[string]int{}} }++func claimKey(dir, id string) string { return dir + "\x00" + id }++// claim records (dir, id) as owned by registry regIdx and returns true if this+// is the first claim. If already claimed, it returns false and the index of the+// registry that won.+func (c *claimSet) claim(dir, id string, regIdx int) (won bool, byRegistry int) {+ key := claimKey(dir, id)+ if prev, ok := c.seen[key]; ok {+ return false, prev+ }+ c.seen[key] = regIdx+ return true, regIdx+}++// selectionFromConfig maps a SkillsRegistryConfig to a selection:+// - explicit Skills list => by-id (with optional revision pin)+// - else Query => by-query+// - else => all+func selectionFromConfig(rc config.SkillsRegistryConfig) selection {+ if len(rc.Skills) > 0 {+ refs := make([]skillRef, 0, len(rc.Skills))+ for _, s := range rc.Skills {+ refs = append(refs, skillRef{SkillID: s.ID, Revision: s.Revision})+ }+ return selection{SkillRefs: refs}+ }+ if rc.Query != nil && strings.TrimSpace(rc.Query.Text) != "" {+ return selection{Query: rc.Query.Text, TopK: rc.Query.TopK}+ }+ return selection{All: true}+}++func firstNonEmpty(vals ...string) string {+ for _, v := range vals {+ if v != "" {+ return v+ }+ }+ return ""+}diff --git a/internal/skills/geminienterprise/materialize_test.go b/internal/skills/geminienterprise/materialize_test.gonew file mode 100644index 0000000..2779a37--- /dev/null+++ b/internal/skills/geminienterprise/materialize_test.go@@ -0,0 +1,100 @@+// Copyright 2026 Google LLC+//+// Licensed under the Apache License, Version 2.0 (the "License");+// you may not use this file except in compliance with the License.+// You may obtain a copy of the License at+//+// http://www.apache.org/licenses/LICENSE-2.0+//+// Unless required by applicable law or agreed to in writing, software+// distributed under the License is distributed on an "AS IS" BASIS,+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+// See the License for the specific language governing permissions and+// limitations under the License.++package geminienterprise++import (+ "context"+ "testing"++ "github.com/google/ax/internal/config"+)++func TestSelectionFromConfig(t *testing.T) {+ t.Run("explicit skills take precedence", func(t *testing.T) {+ rc := config.SkillsRegistryConfig{+ Skills: []config.SkillRefConfig{{ID: "emoji"}, {ID: "lowercase", Revision: "rev-3"}},+ Query: &config.SkillsQueryConfig{Text: "ignored"},+ }+ sel := selectionFromConfig(rc)+ if sel.All || sel.Query != "" {+ t.Fatalf("got %+v, want by-id", sel)+ }+ if len(sel.SkillRefs) != 2 ||+ sel.SkillRefs[0].SkillID != "emoji" || sel.SkillRefs[0].Revision != "" ||+ sel.SkillRefs[1].SkillID != "lowercase" || sel.SkillRefs[1].Revision != "rev-3" {+ t.Fatalf("refs = %+v", sel.SkillRefs)+ }+ })++ t.Run("query when no explicit skills", func(t *testing.T) {+ sel := selectionFromConfig(config.SkillsRegistryConfig{+ Query: &config.SkillsQueryConfig{Text: "find gcp", TopK: 5},+ })+ if sel.Query != "find gcp" || sel.TopK != 5 {+ t.Fatalf("got %+v, want query=find gcp topK=5", sel)+ }+ })++ t.Run("empty query text falls through to all", func(t *testing.T) {+ sel := selectionFromConfig(config.SkillsRegistryConfig{Query: &config.SkillsQueryConfig{Text: " "}})+ if !sel.All {+ t.Fatalf("got %+v, want All (blank query text)", sel)+ }+ })++ t.Run("all when nothing set", func(t *testing.T) {+ if sel := selectionFromConfig(config.SkillsRegistryConfig{}); !sel.All {+ t.Fatalf("got %+v, want All", sel)+ }+ })+}++func TestClaimSet_FirstWins(t *testing.T) {+ cs := newClaimSet()+ if won, by := cs.claim("/dir", "s1", 0); !won || by != 0 {+ t.Fatalf("first claim = (%v,%d), want (true,0)", won, by)+ }+ // Same (dir,id) again -> loses, reports the first registry (0).+ if won, by := cs.claim("/dir", "s1", 2); won || by != 0 {+ t.Fatalf("dup claim = (%v,%d), want (false,0)", won, by)+ }+ // Same id, different dir -> independent, wins.+ if won, _ := cs.claim("/other", "s1", 1); !won {+ t.Fatal("same id in different dir should win")+ }+ // Different id, same dir -> wins.+ if won, _ := cs.claim("/dir", "s2", 1); !won {+ t.Fatal("different id in same dir should win")+ }+}++func TestMaterialize_DisabledIsEmpty(t *testing.T) {+ // Disabled config => no-op, empty result, no error/panic.+ if res := Materialize(context.Background(), config.SkillsConfig{}); !res.Empty() {+ t.Errorf("disabled Materialize = %+v, want empty", res)+ }+}++func TestMaterialize_EnabledNoProjectIsEmpty(t *testing.T) {+ // Enabled with a target_dir but no project (config empty, GOOGLE_CLOUD_PROJECT+ // unset) => fail-safe empty result (no panic, no materialization).+ t.Setenv(envCloudProject, "")+ sc := config.SkillsConfig{Registries: []config.SkillsRegistryConfig{+ {Enabled: true, TargetDir: t.TempDir()},+ }}+ if res := Materialize(context.Background(), sc); !res.Empty() {+ t.Errorf("no-project Materialize = %+v, want empty", res)+ }+}diff --git a/internal/skills/geminienterprise/unzip.go b/internal/skills/geminienterprise/unzip.gonew file mode 100644index 0000000..df1046b--- /dev/null+++ b/internal/skills/geminienterprise/unzip.go@@ -0,0 +1,202 @@+// Copyright 2026 Google LLC+//+// Licensed under the Apache License, Version 2.0 (the "License");+// you may not use this file except in compliance with the License.+// You may obtain a copy of the License at+//+// http://www.apache.org/licenses/LICENSE-2.0+//+// Unless required by applicable law or agreed to in writing, software+// distributed under the License is distributed on an "AS IS" BASIS,+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+// See the License for the specific language governing permissions and+// limitations under the License.++package geminienterprise++import (+ "archive/zip"+ "bytes"+ "fmt"+ "io"+ "os"+ "path/filepath"+ "strings"+)++// unzipCaps bounds a defensive local unzip of an untrusted skill payload. Even+// though the registry validates payloads server-side, the local unzip must+// independently guard against Zip-Slip (entries with "..", absolute paths, or+// symlinks) and resource exhaustion.+type unzipCaps struct {+ // MaxFiles caps the number of entries per skill archive.+ MaxFiles int+ // MaxTotalUnzippedBytes caps the total unzipped size per skill archive.+ MaxTotalUnzippedBytes int64+ // MaxDepth caps directory nesting depth within a skill archive.+ MaxDepth int+}++// The registry's documented payload caps, used as defaults.+const (+ defaultMaxFiles = 10_000+ defaultMaxTotalBytes = 500 << 20 // 500 MiB+ defaultMaxDepth = 8+)++// withDefaults fills any zero-valued cap with the registry's documented limit.+func (c unzipCaps) withDefaults() unzipCaps {+ if c.MaxFiles <= 0 {+ c.MaxFiles = defaultMaxFiles+ }+ if c.MaxTotalUnzippedBytes <= 0 {+ c.MaxTotalUnzippedBytes = defaultMaxTotalBytes+ }+ if c.MaxDepth <= 0 {+ c.MaxDepth = defaultMaxDepth+ }+ return c+}++// safeUnzip extracts a zip archive into destDir, defensively rejecting unsafe+// entries and enforcing caps. destDir must not exist yet or must be safe to+// write into; callers clear it beforehand.+//+// Guards:+// - Zip-Slip: every entry must resolve to a path inside destDir.+// - Absolute paths and paths containing ".." are rejected.+// - Symlinks (and any non-regular, non-dir mode) are rejected.+// - MaxFiles / MaxDepth / MaxTotalUnzippedBytes are enforced; the running+// total is checked while copying so a lying uncompressed-size can't be used+// to blow past the cap.+func safeUnzip(archive []byte, destDir string, caps unzipCaps) error {+ zr, err := zip.NewReader(bytes.NewReader(archive), int64(len(archive)))+ if err != nil {+ return fmt.Errorf("opening zip: %w", err)+ }+ if len(zr.File) > caps.MaxFiles {+ return fmt.Errorf("archive has %d entries, exceeds cap %d", len(zr.File), caps.MaxFiles)+ }++ // Resolve destDir to an absolute, clean base for containment checks.+ absDest, err := filepath.Abs(destDir)+ if err != nil {+ return fmt.Errorf("resolving dest: %w", err)+ }+ if err := os.MkdirAll(absDest, 0o755); err != nil {+ return fmt.Errorf("creating dest: %w", err)+ }++ var total int64+ for _, f := range zr.File {+ if err := validateEntryName(f.Name, caps.MaxDepth); err != nil {+ return err+ }+ // Reject symlinks and any special modes; only dirs and regular files.+ mode := f.Mode()+ if mode&os.ModeSymlink != 0 {+ return fmt.Errorf("entry %q is a symlink (rejected)", f.Name)+ }+ if !mode.IsDir() && !mode.IsRegular() {+ return fmt.Errorf("entry %q has unsupported mode %v (rejected)", f.Name, mode)+ }++ target := filepath.Join(absDest, filepath.FromSlash(f.Name))+ // Containment: target must be within absDest.+ if !withinBase(absDest, target) {+ return fmt.Errorf("entry %q escapes destination (zip-slip)", f.Name)+ }++ if f.FileInfo().IsDir() {+ if err := os.MkdirAll(target, 0o755); err != nil {+ return fmt.Errorf("creating dir %q: %w", f.Name, err)+ }+ continue+ }++ if err := os.MkdirAll(filepath.Dir(target), 0o755); err != nil {+ return fmt.Errorf("creating parent of %q: %w", f.Name, err)+ }+ written, err := writeCappedFile(f, target, caps.MaxTotalUnzippedBytes-total)+ if err != nil {+ return err+ }+ total += written+ if total > caps.MaxTotalUnzippedBytes {+ return fmt.Errorf("archive exceeds unzipped size cap %d bytes", caps.MaxTotalUnzippedBytes)+ }+ }+ return nil+}++// validateEntryName rejects absolute paths, "..", and over-deep nesting.+func validateEntryName(name string, maxDepth int) error {+ if name == "" {+ return fmt.Errorf("empty entry name")+ }+ // Reject Windows-style and POSIX absolute paths.+ if filepath.IsAbs(name) || strings.HasPrefix(name, "/") || strings.HasPrefix(name, `\`) {+ return fmt.Errorf("entry %q is an absolute path (rejected)", name)+ }+ slashed := strings.ReplaceAll(name, `\`, "/")+ for _, seg := range strings.Split(slashed, "/") {+ if seg == ".." {+ return fmt.Errorf("entry %q contains '..' (rejected)", name)+ }+ }+ depth := 0+ for _, seg := range strings.Split(strings.Trim(slashed, "/"), "/") {+ if seg != "" && seg != "." {+ depth+++ }+ }+ if depth > maxDepth {+ return fmt.Errorf("entry %q nesting depth %d exceeds cap %d", name, depth, maxDepth)+ }+ return nil+}++// withinBase reports whether target is inside base (after cleaning).+func withinBase(base, target string) bool {+ rel, err := filepath.Rel(base, target)+ if err != nil {+ return false+ }+ return rel != ".." && !strings.HasPrefix(rel, ".."+string(os.PathSeparator))+}++// writeCappedFile copies one zip entry to disk, refusing to write more than+// remaining bytes (so a mismatched declared size can't overrun the cap).+func writeCappedFile(f *zip.File, target string, remaining int64) (int64, error) {+ if remaining < 0 {+ return 0, fmt.Errorf("unzipped size cap exceeded before %q", f.Name)+ }+ rc, err := f.Open()+ if err != nil {+ return 0, fmt.Errorf("opening entry %q: %w", f.Name, err)+ }+ defer rc.Close()++ // Preserve the archive entry's permission bits so executable skill scripts+ // (e.g. under scripts/) stay executable after extraction. Chmod after create+ // so the mode sticks regardless of the process umask.+ perm := f.Mode().Perm()+ out, err := os.OpenFile(target, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, perm)+ if err != nil {+ return 0, fmt.Errorf("creating file %q: %w", f.Name, err)+ }+ defer out.Close()+ if err := out.Chmod(perm); err != nil {+ return 0, fmt.Errorf("setting mode on %q: %w", f.Name, err)+ }++ // Limit the copy to remaining+1 so we can detect overrun deterministically.+ n, err := io.Copy(out, io.LimitReader(rc, remaining+1))+ if err != nil {+ return n, fmt.Errorf("writing %q: %w", f.Name, err)+ }+ if n > remaining {+ return n, fmt.Errorf("entry %q exceeds remaining unzipped size budget", f.Name)+ }+ return n, nil+}