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/file_get_text.go

@@ -0,0 +1,119 @@
+// file_get_text fetches a saved text file's content as plain text.
+// Only succeeds for text/* MIMEs; binary MIMEs return an error so the
+// agent knows to use a different path (file_get_metadata for
+// reasoning, send_attachments for delivery).
+//
+// Why a 64 KiB cap: the v10 byte-vs-reference principle says inline
+// text content stays under ~10KB ideally; we set the hard cap at 64
+// KiB to handle reasonable text artifacts (logs, configs, small
+// reports) without blowing the agent's context. Files larger than
+// the cap return an error pointing to send_attachments.
+//
+// Why a separate tool (vs file_get): file_get returns base64 +
+// metadata regardless of MIME, which agents misuse to dump 10MB PDFs
+// into the context window. file_get_text is the agent-friendly
+// alternative that explicitly fails fast on binary content.
+package tools
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strings"
+	"time"
+
+	"gitea.stevedudenhoeffer.com/steve/executus/tool"
+)
+
+const fileGetTextMaxBytes = 64 * 1024
+
+type fileGetTextArgs struct {
+	FileID string `json:"file_id" description:"Opaque file ID returned by file_save or file_list."`
+}
+
+type fileGetTextResult struct {
+	Text      string `json:"text"`
+	Mime      string `json:"mime"`
+	SizeBytes int64  `json:"size_bytes"`
+	CreatedAt string `json:"created_at"` // RFC3339
+}
+
+// NewFileGetText constructs the file_get_text tool. storage nil →
+// "not configured" at execute time.
+func NewFileGetText(storage FileStorage) tool.Tool {
+	return tool.NewGatedTool[fileGetTextArgs](
+		"file_get_text",
+		"Fetch a saved text file's content (text/* MIMEs only, capped at 64KB). For binary content use file_get_metadata + send_attachments. Errors with 'not_text' for non-text MIMEs and 'too_large' for files > 64KB.",
+		tool.Permission{
+			AuthoringRequirement: tool.RequirementAnyone,
+			OperatesOn:           tool.ScopeCaller,
+			SafeForShare:         true,
+			Categories:           []string{"storage", "read"},
+		},
+		func(ctx context.Context, inv tool.Invocation, args fileGetTextArgs) (string, error) {
+			if storage == nil {
+				return "", fmt.Errorf("file_get_text: not configured")
+			}
+			if args.FileID == "" {
+				return "", fmt.Errorf("file_get_text: file_id required")
+			}
+			meta, content, err := storage.FileGet(ctx, args.FileID)
+			if err != nil {
+				if errors.Is(err, ErrFileNotFound) {
+					return "", fmt.Errorf("file_get_text: not found")
+				}
+				return "", fmt.Errorf("file_get_text: %w", err)
+			}
+			// Descendant grant: a worker this run (transitively)
+			// dispatched may have produced the file — its scope is the
+			// WORKER's run, so the grant also stands in for the scope
+			// check below.
+			grantedViaDescendant := false
+			if meta.SkillID != inv.SkillID {
+				if !descendantFileGrant(ctx, storage, inv, meta.SkillID) {
+					return "", fmt.Errorf("file_get_text: file does not belong to this skill")
+				}
+				grantedViaDescendant = true
+			}
+			if !grantedViaDescendant {
+				if err := ValidateScope(inv, meta.Scope, false); err != nil {
+					return "", fmt.Errorf("file_get_text: %w", err)
+				}
+			}
+			if !isTextMime(meta.MimeType) {
+				return "", fmt.Errorf("file_get_text: not_text: mime %q is not text/*", meta.MimeType)
+			}
+			if int64(len(content)) > fileGetTextMaxBytes {
+				return "", fmt.Errorf("file_get_text: too_large: %d bytes exceeds 64KB cap; use send_attachments to deliver this file to Discord", len(content))
+			}
+			res := fileGetTextResult{
+				Text:      string(content),
+				Mime:      meta.MimeType,
+				SizeBytes: meta.SizeBytes,
+				CreatedAt: meta.CreatedAt.UTC().Format(time.RFC3339),
+			}
+			b, err := json.Marshal(res)
+			if err != nil {
+				return "", fmt.Errorf("file_get_text: marshal: %w", err)
+			}
+			return string(b), nil
+		},
+	)
+}
+
+// isTextMime reports whether the given MIME is a text/* type.
+// Accepts "text/plain", "text/markdown", "text/csv", "application/json"
+// and "application/xml" since those are conventionally text.
+func isTextMime(mime string) bool {
+	mime = strings.ToLower(strings.TrimSpace(mime))
+	if strings.HasPrefix(mime, "text/") {
+		return true
+	}
+	switch mime {
+	case "application/json", "application/xml", "application/xhtml+xml",
+		"application/javascript", "application/yaml", "application/x-yaml":
+		return true
+	}
+	return false
+}