P3: store group — kv_* + file_* tools (agent memory)

RegisterStore(reg, StoreDeps) registers the persistent-memory tools over the
host's KV and/or File backends:
- kv_get/set/list/delete (KVStorage seam)
- file_save/get/get_text/get_metadata/list/delete (FileStorage seam), plus
  file_search (FileSearcher) and create_file_url (FileTokenMinter) when wired.

Near-zero-config: Quota defaults to a generous static cap (staticQuota), the
per-value/per-file caps default, and the kv vs file groups register
independently (a host can take just one). Seams moved clean (interface-only):
kv_storage.go, quota_provider.go, file_descendant_grant.go. The default
in-memory KV/File backends come with contrib/store at P4.

Core go.sum still free of gorm/redis/discordgo/sqlite.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

tools/kv_list.go

@@ -0,0 +1,88 @@
+// kv_list returns metadata (key, size, expiry) for entries within a
+// scope, optionally filtered by key prefix. Values are NOT loaded —
+// listing is a hot path that should stay light, and dumping every
+// value byte into the LLM context would burn tokens for no benefit.
+package tools
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"time"
+
+	"gitea.stevedudenhoeffer.com/steve/executus/tool"
+)
+
+const (
+	kvListDefaultLimit = 100
+	kvListMaxLimit     = 1000
+)
+
+type kvListArgs struct {
+	Scope  string `json:"scope" description:"Storage scope: 'skill', 'user:<your_id>', 'run:<run_id>', or 'root_run:<root_run_id>'."`
+	Prefix string `json:"prefix,omitempty" description:"Optional key-prefix filter. Empty matches all keys in the scope."`
+	Limit  int    `json:"limit,omitempty" description:"Max entries to return. Default 100, hard cap 1000."`
+}
+
+type kvListEntry struct {
+	Key       string `json:"key"`
+	SizeBytes int    `json:"size_bytes"`
+	// ExpiresAt is RFC3339 when set, "" otherwise. JSON serialised this
+	// way so the LLM can reason about it as a string field consistently
+	// (rather than null vs. missing key).
+	ExpiresAt string `json:"expires_at,omitempty"`
+}
+
+// NewKVList constructs the kv_list tool. storage nil → "not configured"
+// at execute time.
+func NewKVList(storage KVStorage) tool.Tool {
+	return tool.NewGatedTool[kvListArgs](
+		"kv_list",
+		"List keys + sizes + expiries in a scope (optionally filtered by key prefix). Returns a JSON array. Does NOT include values — call kv_get to fetch a specific value.",
+		tool.Permission{
+			AuthoringRequirement: tool.RequirementAnyone,
+			OperatesOn:           tool.ScopeCaller,
+			SafeForShare:         true,
+			Categories:           []string{"storage", "read"},
+		},
+		func(ctx context.Context, inv tool.Invocation, args kvListArgs) (string, error) {
+			if storage == nil {
+				return "", fmt.Errorf("kv_list: not configured")
+			}
+			if err := ValidateScope(inv, args.Scope, false); err != nil {
+				return "", fmt.Errorf("kv_list: %w", err)
+			}
+
+			limit := args.Limit
+			if limit <= 0 {
+				limit = kvListDefaultLimit
+			}
+			if limit > kvListMaxLimit {
+				limit = kvListMaxLimit
+			}
+
+			rows, err := storage.KVList(ctx, kvPartition(inv, args.Scope), args.Scope, args.Prefix, limit)
+			if err != nil {
+				return "", fmt.Errorf("kv_list: %w", err)
+			}
+
+			out := make([]kvListEntry, 0, len(rows))
+			for _, r := range rows {
+				e := kvListEntry{
+					Key:       r.Key,
+					SizeBytes: len(r.Value),
+				}
+				if r.ExpiresAt != nil {
+					e.ExpiresAt = r.ExpiresAt.Format(time.RFC3339)
+				}
+				out = append(out, e)
+			}
+
+			b, err := json.Marshal(out)
+			if err != nil {
+				return "", fmt.Errorf("kv_list: marshal: %w", err)
+			}
+			return string(b), nil
+		},
+	)
+}