Merge pull request #15 from achetronic/feat/extract-contextguard-adkutils

Feat/extract contextguard adkutils

Author: achetronic

.agents/ADK_TOOLS.md

@@ -223,9 +223,9 @@ filtered := tool.FilterToolset(myToolset, func(ctx agent.ReadonlyContext, t tool
 
 ### Memory tools: `adk-utils-go` vs ADK official
 
-Magec currently uses custom memory tools from `adk-utils-go/tools/memory` (v0.2.2 in use):
+Magec currently uses custom memory tools from `adk-utils-go/tools/memory` (v0.7.0 in use):
 
-| Tool | `adk-utils-go` (current v0.2.2) | ADK official (`main`) |
+| Tool | `adk-utils-go` (current v0.7.0) | ADK official (`main`) |
 |------|----------------------|----------------------|----------------------|
 | **Search** | `search_memory` (with entry IDs) | `loadmemorytool` (`load_memory`) |
 | **Save** | `save_to_memory` | — (no equivalent) |

.agents/AGENTS.md

@@ -60,13 +60,7 @@ magec/
 │   │       └── docs/           # Generated swagger (userapi)
 │   ├── a2a/                   # A2A protocol handler
 │   │   └── handler.go          # Per-agent/flow JSON-RPC endpoints, agent cards, SSE streaming
-│   ├── plugin/                # ADK plugins
-│   │   └── contextguard/      # Context window management plugin
-│   │       ├── contextguard.go # BeforeModelCallback plugin, strategy dispatch, summary persistence
-│   │       ├── threshold.go    # Token-based strategy (estimates tokens, summarizes when near limit)
-│   │       └── sliding_window.go # Turn-count strategy (compacts after maxTurns content entries)
-│   ├── contextwindow/         # Remote model metadata registry
-│   │   └── contextwindow.go   # Fetches provider.json, caches context window sizes per model (6h refresh)
+
 │   ├── middleware/
 │   │   ├── middleware.go       # AccessLog (httpsnoop), CORS, ClientAuth, AdminAuth (rate-limited)
 │   │   ├── recorder.go         # ConversationRecorder + ConversationRecorderSSE (dual-perspective)
@@ -234,8 +228,7 @@ log:
 - **MCP headers/TLS**: `MCPServer` struct has `Headers map[string]string` and `Insecure bool`. `httpClientForMCP()` creates transport with optional `InsecureSkipVerify`
 - **Skill injection**: Skills are injected into the agent system prompt at build time. Instructions appended as `--- Skill: {name} ---`, reference file contents appended as `[Reference: {filename}]`. Files read from `data/skills/{skillId}/`
 - **Encryption key**: `server.encryptionKey` in config.yaml. Independent from `adminPassword`. Used to encrypt secrets at rest (AES-256-GCM, PBKDF2-derived)
-- **ContextGuard plugin**: ADK `plugin.Plugin` with `BeforeModelCallback`. Two strategies: `threshold` (token-based, summarizes when near context limit) and `sliding_window` (turn-count, compacts after maxTurns). Each agent summarizes with its own LLM. Summary persisted in session state
-- **Context window registry**: `server/contextwindow/` fetches model context sizes from remote `provider.json` (6h cache, 128k default fallback). Used by ContextGuard threshold strategy
+- **ContextGuard plugin**: Externalized to `adk-utils-go/plugin/contextguard` (v0.7.0). Builder API: `contextguard.New(registry)` + `guard.Add(agentID, llm, opts...)` + `guard.PluginConfig()`. Two strategies: `threshold` (token-based, auto-detect via CrushRegistry or manual `WithMaxTokens`) and `sliding_window` (turn-count via `WithSlidingWindow`). Each agent summarizes with its own LLM. Summary persisted in session state with `{agentName}` suffix keys. `CrushRegistry` fetches model metadata from Crush's provider.json with 6h background refresh
 - **A2A protocol**: Agents/flows with `A2A.Enabled` get JSON-RPC endpoints via `a2a-go` + ADK `adka2a`. Agent cards auto-generated with capabilities and skills. SSE streaming for responses
 - **Dual-perspective conversation recording**: Middleware chains recorder twice: "admin" perspective (all events, before FlowResponseFilter) and "user" perspective (filtered, after). Each conversation has a `ParentID` linking the pair
 - **Store dual-copy pattern**: Store maintains `rawData` (unexpanded, with `${VAR}` refs) and `data` (env-expanded). API responses use raw data, runtime uses expanded. Secret values injected as env vars before expansion
@@ -304,7 +297,7 @@ GPU section commented out by default. Users who want cloud providers create diff
 **Go backend:**
 - `google.golang.org/adk` — Agent Development Kit (v0.4.0)
 - `google.golang.org/genai` — Google GenAI SDK (v1.40.0)
-- `github.com/achetronic/adk-utils-go` — ADK utilities (v0.2.2): providers, session, memory tools
+- `github.com/achetronic/adk-utils-go` — ADK utilities (v0.7.0): providers, session, memory tools, ContextGuard plugin
 - `github.com/a2aproject/a2a-go` — A2A protocol library (v0.3.3)
 - `github.com/modelcontextprotocol/go-sdk` — MCP client (v1.2.0)
 - `github.com/gorilla/mux` — HTTP router (v1.8.1)

.agents/TODO.md

@@ -390,17 +390,17 @@ ADK supports agents as tools — orchestrator decides at runtime which specialis
 **Solution (requires real user identity)**:
 1. Implement per-client user identity: each client generates a meaningful `userID` (e.g. `discord_123456`, `slack_U0ABC`, `telegram_98765`) instead of `default_user`
 2. Move ContextGuard state keys to `user:` tier (`session.KeyPrefixUser` prefix) so summaries are scoped per-user across all that user's sessions with a given agent
-3. The `user:` tier in `adk-utils-go` v0.5.0 already supports differentiated TTL (defaults to no expiration), so summaries survive indefinitely
+3. The `user:` tier in `adk-utils-go` v0.7.0 already supports differentiated TTL (defaults to no expiration), so summaries survive indefinitely
 
 **What's already in place**:
-- `adk-utils-go` v0.5.0 has full tier support (`app:`, `user:`, `temp:`) with independent TTLs for app/user state (default: no expiration, matching canonical ADK DatabaseService behaviour)
-- ContextGuard state keys are simple string constants in `server/plugin/contextguard/contextguard.go` — adding the prefix is a one-line change per key
+- `adk-utils-go` v0.7.0 has full tier support (`app:`, `user:`, `temp:`) with independent TTLs for app/user state (default: no expiration, matching canonical ADK DatabaseService behaviour)
+- ContextGuard state keys are simple string constants in `adk-utils-go/plugin/contextguard/contextguard.go` — adding the prefix is a one-line change per key
 - The Redis session service stores `user:` state in a dedicated HASH (`userstate:{appName}:{userID}`) separate from session data
 
 **Cross-client identity (future)**:
 If a single person uses Discord AND Telegram, they'd have two `userID`s and two separate summaries — which is actually correct (different conversational contexts). True cross-client identity (linking `discord_123` and `telegram_456` as the same person) is a separate, larger problem.
 
-**Modify**: `server/plugin/contextguard/contextguard.go`, `server/clients/telegram/bot.go`, `server/clients/slack/bot.go`, `server/clients/discord/bot.go`, `server/clients/executor.go`
+**Modify**: `adk-utils-go/plugin/contextguard/contextguard.go` (state key prefixes), `server/clients/telegram/bot.go`, `server/clients/slack/bot.go`, `server/clients/discord/bot.go`, `server/clients/executor.go`
 
 ---
 

frontend/admin-ui/src/views/agents/AgentDialog.vue

@@ -58,6 +58,32 @@
             </div>
           </div>
 
+          <!-- LLM Headers -->
+          <div>
+            <FormLabel label="Headers" />
+            <div class="space-y-2">
+              <div v-for="(h, i) in form.llmHeaders" :key="i" class="flex gap-2 items-center">
+                <input
+                  v-model="h.key"
+                  placeholder="anthropic-beta"
+                  class="flex-1 bg-piedra-800 border border-piedra-700 rounded-lg px-3 py-1.5 text-sm focus:ring-1 focus:ring-sol-500 focus:border-sol-500 outline-none"
+                />
+                <input
+                  v-model="h.value"
+                  placeholder="context-1m-2025-08-07"
+                  class="flex-[2] bg-piedra-800 border border-piedra-700 rounded-lg px-3 py-1.5 text-sm focus:ring-1 focus:ring-sol-500 focus:border-sol-500 outline-none"
+                />
+                <button @click="form.llmHeaders.splice(i, 1)" class="p-1.5 hover:bg-piedra-800 rounded-lg text-arena-400 hover:text-lava-400 flex-shrink-0" title="Remove header">
+                  <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" width="14" height="14"><path d="M18 6L6 18M6 6l12 12"/></svg>
+                </button>
+              </div>
+              <button @click="form.llmHeaders.push({ key: '', value: '' })" class="text-xs text-sol-400 hover:text-sol-500 transition-colors">
+                + Add header
+              </button>
+            </div>
+            <p class="text-[10px] text-arena-500 mt-1">Extra HTTP headers for this agent's LLM requests. Override backend-level headers.</p>
+          </div>
+
           <!-- Context Guard -->
           <div class="border-t border-piedra-700/30 pt-3">
             <div class="flex items-center justify-between">
@@ -234,6 +260,7 @@ const form = reactive({
   systemPrompt: '',
   llmBackend: '',
   llmModel: '',
+  llmHeaders: [],
   mcpServers: [],
   skills: [],
   tags: [],
@@ -250,6 +277,20 @@ const form = reactive({
   a2aEnabled: false,
 })
 
+function headersToList(obj) {
+  if (!obj || !Object.keys(obj).length) return []
+  return Object.entries(obj).map(([key, value]) => ({ key, value }))
+}
+
+function listToHeaders(list) {
+  const obj = {}
+  for (const h of list) {
+    const k = h.key.trim()
+    if (k) obj[k] = h.value
+  }
+  return Object.keys(obj).length ? obj : undefined
+}
+
 function toggleMcp(id) {
   const idx = form.mcpServers.indexOf(id)
   if (idx === -1) form.mcpServers.push(id)
@@ -283,6 +324,7 @@ function open(agent = null) {
   form.systemPrompt = agent?.systemPrompt || ''
   form.llmBackend = agent?.llm?.backend || ''
   form.llmModel = agent?.llm?.model || ''
+  form.llmHeaders = headersToList(agent?.llm?.headers)
   form.mcpServers = [...(agent?.mcpServers || [])]
   form.skills = [...(agent?.skills || [])]
   form.tags = [...(agent?.tags || [])]
@@ -306,7 +348,7 @@ async function save() {
     description: form.description.trim(),
     outputKey: form.outputKey.trim(),
     systemPrompt: form.systemPrompt.trim(),
-    llm: { backend: form.llmBackend, model: form.llmModel.trim() },
+    llm: { backend: form.llmBackend, model: form.llmModel.trim(), headers: listToHeaders(form.llmHeaders) },
     transcription: { backend: form.transcriptionBackend, model: form.transcriptionModel.trim() },
     tts: {
       backend: form.ttsBackend,

frontend/admin-ui/src/views/backends/BackendDialog.vue

@@ -21,6 +21,30 @@
         <FormLabel label="API Key" />
         <FormInput v-model="form.apiKey" type="password" placeholder="sk-..." />
       </div>
+      <div>
+        <FormLabel label="Headers" />
+        <div class="space-y-2">
+          <div v-for="(h, i) in form.headers" :key="i" class="flex gap-2 items-center">
+            <input
+              v-model="h.key"
+              placeholder="Authorization"
+              class="flex-1 bg-piedra-800 border border-piedra-700 rounded-lg px-3 py-1.5 text-sm focus:ring-1 focus:ring-sol-500 focus:border-sol-500 outline-none"
+            />
+            <input
+              v-model="h.value"
+              placeholder="Bearer sk-..."
+              class="flex-[2] bg-piedra-800 border border-piedra-700 rounded-lg px-3 py-1.5 text-sm focus:ring-1 focus:ring-sol-500 focus:border-sol-500 outline-none"
+            />
+            <button @click="form.headers.splice(i, 1)" class="p-1.5 hover:bg-piedra-800 rounded-lg text-arena-400 hover:text-lava-400 flex-shrink-0" title="Remove header">
+              <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" width="14" height="14"><path d="M18 6L6 18M6 6l12 12"/></svg>
+            </button>
+          </div>
+          <button @click="form.headers.push({ key: '', value: '' })" class="text-xs text-sol-400 hover:text-sol-500 transition-colors">
+            + Add header
+          </button>
+        </div>
+        <p class="text-[10px] text-arena-500 mt-1">Extra HTTP headers sent with every request to this backend. Agent-level headers override these.</p>
+      </div>
     </div>
   </AppDialog>
 </template>
@@ -44,20 +68,38 @@ const form = reactive({
   type: 'openai',
   url: '',
   apiKey: '',
+  headers: [],
 })
 
+function headersToList(obj) {
+  if (!obj || !Object.keys(obj).length) return []
+  return Object.entries(obj).map(([key, value]) => ({ key, value }))
+}
+
+function listToHeaders(list) {
+  const obj = {}
+  for (const h of list) {
+    const k = h.key.trim()
+    if (k) obj[k] = h.value
+  }
+  return Object.keys(obj).length ? obj : undefined
+}
+
 function open(backend = null) {
   isEdit.value = !!backend
   editId.value = backend?.id || null
   form.name = backend?.name || ''
   form.type = backend?.type || 'openai'
   form.url = backend?.url || ''
   form.apiKey = backend?.apiKey || ''
+  form.headers = headersToList(backend?.headers)
   dialogRef.value?.open()
 }
 
 async function save() {
   const data = { name: form.name, type: form.type, url: form.url, apiKey: form.apiKey }
+  const headers = listToHeaders(form.headers)
+  if (headers) data.headers = headers
   try {
     if (isEdit.value) {
       await backendsApi.update(editId.value, data)

frontend/admin-ui/src/views/conversations/ConversationsList.vue

@@ -60,8 +60,10 @@
         <option value="">All sources</option>
         <option value="voice-ui">Voice UI</option>
         <option value="telegram">Telegram</option>
+        <option value="discord">Discord</option>
         <option value="slack">Slack</option>
-        <option value="executor">Executor</option>
+        <option value="webhook">Webhook</option>
+        <option value="cron">Cron</option>
         <option value="flow">Flow</option>
         <option value="direct">Direct</option>
       </select>
@@ -297,6 +299,8 @@ function sourceIcon(source) {
   const map = {
     'voice-ui': 'phone',
     telegram: 'phone',
+    discord: 'chat',
+    slack: 'chat',
     executor: 'command',
     flow: 'flow',
     direct: 'phone',
@@ -310,6 +314,8 @@ function sourceBg(source) {
   const map = {
     'voice-ui': 'bg-teal-500/15',
     telegram: 'bg-atlantico-500/15',
+    discord: 'bg-violet-500/15',
+    slack: 'bg-emerald-500/15',
     executor: 'bg-indigo-500/15',
     flow: 'bg-rose-500/15',
     direct: 'bg-teal-500/15',
@@ -323,6 +329,8 @@ function sourceText(source) {
   const map = {
     'voice-ui': 'text-teal-400',
     telegram: 'text-atlantico-400',
+    discord: 'text-violet-400',
+    slack: 'text-emerald-400',
     executor: 'text-indigo-400',
     flow: 'text-rose-400',
     direct: 'text-teal-400',
@@ -336,6 +344,8 @@ function formatSource(source) {
   const map = {
     'voice-ui': 'Voice UI',
     telegram: 'Telegram',
+    discord: 'Discord',
+    slack: 'Slack',
     executor: 'Executor',
     flow: 'Flow',
     direct: 'Direct',