diff --git a/docs/01-agent-loop.md b/docs/01-agent-loop.md index f7e24a4d..22066c5c 100644 --- a/docs/01-agent-loop.md +++ b/docs/01-agent-loop.md @@ -723,70 +723,11 @@ Enabled via the `GOCLAW_TRACE_VERBOSE=1` environment variable. ## 14. File Reference -### Agent Loop (V2 & V3) +| Module | Path | Purpose | +|---|---|---| +| Agent loop & pipeline | `internal/agent/` | V2 runLoop, V3 pipeline adapter, system prompt, resolver, input guard, sanitize, compaction, tracing, orchestration mode, suggestion engine | +| V3 pipeline stages | `internal/pipeline/` | 8-stage pipeline (context→think→prune→tool→observe→checkpoint→finalize→memory flush), RunState, MessageBuffer | +| Memory consolidation & vault | `internal/consolidation/`, `internal/vault/` | Episodic/semantic/dreaming workers, vault retriever, L0 auto-injector, wikilinks, FS sync | +| Infrastructure | `internal/eventbus/`, `internal/tokencount/`, `internal/workspace/`, `internal/bootstrap/` | DomainEventBus, tiktoken counter, WorkspaceContext resolver, bootstrap file loading | -| File | Responsibility | -|------|---------------| -| `internal/agent/loop_run.go` | Run() entry point: dual-mode gate (v2 vs v3), trace creation, span management | -| `internal/agent/loop_pipeline_adapter.go` | Bridge v2 Loop to v3 Pipeline: state conversion, dependency injection, callback wiring | -| `internal/agent/loop.go` | runLoop() core loop: LLM iteration, tool execution, message buffering (v2 path) | -| `internal/agent/loop_history.go` | History pipeline: limitHistoryTurns, sanitizeHistory, summary injection | -| `internal/agent/pruning.go` | Context pruning: 2-pass soft trim and hard clear algorithm (opt-in via PruneStage) | -| `internal/agent/loop_compact.go` | Mid-loop compaction: in-memory message summarization during iterations | -| `internal/agent/systemprompt.go` | System prompt assembly (19+ sections), PromptFull and PromptMinimal modes | -| `internal/agent/systemprompt_sections.go` | Individual section builders (tooling, workspace, sandbox, skills, MCP, etc.) | -| `internal/agent/resolver.go` | ManagedResolver: lazy Loop creation from PostgreSQL, provider resolution, bootstrap loading | -| `internal/agent/loop_tracing.go` | Trace and span creation, verbose mode input capture, span finalization | -| `internal/agent/input_guard.go` | Input Guard: 6 regex patterns, 4 action modes, security logging | -| `internal/agent/sanitize.go` | 7-step output sanitization pipeline | -| `internal/agent/memoryflush.go` | Pre-compaction memory flush: embedded agent turn with write_file tool | -| `internal/agent/toolloop.go` | Tool execution and loop detection (no-progress warnings) | -| `internal/agent/orchestration_mode.go` | OrchestrationMode enum: spawn/delegate/team, mode resolution logic, prompt section data | -| `internal/agent/suggestion_engine.go` | SuggestionEngine: metrics analysis, rule evaluation, evolution suggestion generation | -| `internal/agent/evolution_guardrails.go` | AdaptationGuardrails: safety checks for auto-adaptation, delta constraints, rollback logic | -| `internal/bootstrap/files.go` | Bootstrap file loading and context file preparation | - -### V3 Pipeline - -| File | Responsibility | -|------|---------------| -| `internal/pipeline/pipeline.go` | Pipeline orchestrator: setup → iteration → finalize stage execution | -| `internal/pipeline/stage.go` | Stage interface: Execute(ctx, state), StageResult (Continue/BreakLoop/AbortRun) | -| `internal/pipeline/context_stage.go` | ContextStage: context injection, workspace resolution, per-user file setup | -| `internal/pipeline/think_stage.go` | ThinkStage: system prompt building, tool filtering, LLM call | -| `internal/pipeline/prune_stage.go` | PruneStage: context pruning (2-pass), memory flush trigger | -| `internal/pipeline/tool_stage.go` | ToolStage: tool execution (serial/parallel), result processing | -| `internal/pipeline/observe_stage.go` | ObserveStage: tool result stream handling, NO_REPLY detection | -| `internal/pipeline/checkpoint_stage.go` | CheckpointStage: iteration tracking, exit conditions | -| `internal/pipeline/finalize_stage.go` | FinalizeStage: output sanitization, message flush, metadata update | -| `internal/pipeline/memory_flush_stage.go` | MemoryFlushStage: pre-compaction memory persistence | -| `internal/pipeline/run_state.go` | RunState: mutable pipeline state, iteration tracking, exit codes | -| `internal/pipeline/substates.go` | Sub-state structures (messages, tool results, context) | -| `internal/pipeline/message_buffer.go` | MessageBuffer: deferred message persistence | - -### V3 Memory & Knowledge - -| File | Responsibility | -|------|---------------| -| `internal/consolidation/episodic_worker.go` | Episodic memory: extract facts from runs, cluster by topic, embed | -| `internal/consolidation/semantic_worker.go` | Semantic memory: reprocess episodic clusters, generate abstractions | -| `internal/consolidation/dreaming_worker.go` | Dreaming worker: synthesize insights, cross-link memories, drive evolution | -| `internal/consolidation/dedup_worker.go` | Dedup worker: prevent duplicate entries, maintain consistency | -| `internal/consolidation/workers.go` | Worker pool startup and lifecycle | -| `internal/vault/retriever_impl.go` | Vault retrieval: hybrid search (BM25+vector), RRF ranking | -| `internal/vault/auto_injector_impl.go` | L0 auto-injection: top-K vault entries into system prompt | -| `internal/vault/links.go` | Wikilink parsing and semantic mesh construction | -| `internal/vault/sync_worker.go` | Filesystem sync: vault → .md files, .md → vault re-import | - -### V3 Infrastructure - -| File | Responsibility | -|------|---------------| -| `internal/eventbus/domain_event_bus.go` | DomainEventBus interface: Publish, Subscribe, Start, Drain | -| `internal/eventbus/bus_impl.go` | BusImpl: worker pool, event dedup, retry with backoff | -| `internal/eventbus/event_types.go` | DomainEvent type definitions, EventType enums | -| `internal/tokencount/tiktoken_counter.go` | Tiktoken BPE token counter (cl100k_base for OpenAI models) | -| `internal/tokencount/token_counter.go` | TokenCounter interface and factory | -| `internal/tokencount/fallback_counter.go` | Fallback counter (linear estimation) if tiktoken unavailable | -| `internal/workspace/resolver_impl.go` | WorkspaceContext resolver: 6 scenarios, context variables | -| `internal/workspace/workspace_context.go` | WorkspaceContext data structure and context injection | +Use `grep` or your editor's symbol search for specific files. diff --git a/docs/09-security.md b/docs/09-security.md index b58b8a4b..c18e0767 100644 --- a/docs/09-security.md +++ b/docs/09-security.md @@ -460,29 +460,14 @@ When concurrency limits are hit, the error message is written for LLM reasoning: ## File Reference -| File | Description | -|------|-------------| -| `internal/agent/input_guard.go` | Injection pattern detection (6 patterns) | -| `internal/tools/scrub.go` | Credential scrubbing (regex-based redaction), dynamic scrub values | -| `internal/tools/shell.go` | Shell deny patterns, command validation | -| `internal/tools/web_fetch.go` | Web content wrapping, SSRF protection | -| `internal/permissions/policy.go` | RBAC (3 roles, scope-based access), method routing | -| `internal/gateway/ratelimit.go` | Gateway-level token bucket rate limiter (per user/IP) | -| `internal/sandbox/sandbox.go` | Docker sandbox configuration and modes | -| `internal/sandbox/docker.go` | Docker sandbox creation, execution, pruning | -| `internal/sandbox/fsbridge.go` | File operations in sandbox (read/write/list) | -| `internal/crypto/aes.go` | AES-256-GCM encrypt/decrypt | -| `internal/crypto/apikey.go` | API key generation (format, hash, display prefix) | -| `internal/tools/types.go` | PathDenyable interface definition | -| `internal/tools/filesystem.go` | Denied path checking (`checkDeniedPath` helper) | -| `internal/tools/filesystem_list.go` | Denied path support + directory filtering | -| `internal/gateway/methods/pairing.go` | Pairing RPC methods (request, approve, deny, list, revoke) | -| `internal/store/pg/pairing.go` | Pairing store implementation (code generation, TTLs) | -| `internal/store/pairing_store.go` | Pairing store interface definition | -| `cmd/pkg-helper/main.go` | Root-privileged helper for apk add/del via Unix socket | -| `internal/http/packages.go` | HTTP handlers for package management endpoints | -| `internal/skills/package_lister.go` | Query installed packages from apk/pip3/npm | -| `docker-entrypoint.sh` | Container initialization: setup runtime dirs, start pkg-helper, drop privileges | +| Module | Path | Purpose | +|---|---|---| +| Input & output protection | `internal/agent/input_guard.go`, `internal/tools/scrub.go`, `internal/tools/shell.go`, `internal/tools/web_fetch.go` | Injection detection, credential scrubbing, shell deny patterns, SSRF protection | +| Crypto, RBAC & rate limiting | `internal/crypto/`, `internal/permissions/policy.go`, `internal/gateway/ratelimit.go` | AES-256-GCM, API key generation, 3-role RBAC, token bucket | +| Sandbox & filesystem isolation | `internal/sandbox/`, `internal/tools/filesystem*.go`, `internal/tools/types.go` | Docker sandbox lifecycle, FsBridge, PathDenyable interface | +| Pairing, packages & container init | `internal/gateway/methods/pairing.go`, `internal/store/pg/pairing.go`, `cmd/pkg-helper/`, `docker-entrypoint.sh` | Browser pairing, pkg-helper Unix socket, container privilege drop | + +Use `grep` or your editor's symbol search for specific files. --- diff --git a/docs/11-agent-teams.md b/docs/11-agent-teams.md index e262a6ca..1d6e69d3 100644 --- a/docs/11-agent-teams.md +++ b/docs/11-agent-teams.md @@ -680,30 +680,14 @@ Teams emit events for real-time UI updates and observability. ## File Reference -| File | Purpose | -|------|---------| -| `internal/gateway/methods/teams_crud.go` | Team CRUD RPC: Get, Delete, Update settings, TaskList, KnownUsers, Scopes, Events | -| `internal/gateway/methods/teams_tasks.go` | Task board RPC: Get, Create, Assign, Comment, Comments, Events, Approve, Reject, Delete, TaskDispatch | -| `internal/gateway/methods/teams_workspace.go` | Workspace RPC: List, Read, Delete (with shared/isolated mode logic) | -| `internal/tools/team_tool_manager.go` | Shared backend for team tools, team cache (5-min TTL), team resolution | -| `internal/tools/team_tasks_tool.go` | Task board tool: list, get, create, claim, complete, cancel, search, approve, reject, comment, progress, attach, ask_user, update | -| `internal/tools/team_message_tool.go` | Mailbox tool: send, broadcast, read, message routing via bus | -| `internal/tools/team_access_policy.go` | Access control: checkTeamAccess validates user/channel against settings | -| `internal/tools/subagent_spawn_tool.go` | Subagent spawning: sync/async delegation, team task enforcement | -| `internal/tools/subagent_exec.go` | Delegation execution, artifact accumulation, session cleanup | -| `internal/tools/subagent_config.go` | Delegation configuration and concurrency control | -| `internal/tools/subagent_tracing.go` | Delegation tracing and event broadcasting | -| `internal/store/agent_link_store.go` | AgentLinkStore interface: CRUD for delegation links | -| `internal/store/pg/agent_links.go` | PostgreSQL agent link persistence and querying | -| `internal/gateway/methods/agent_links.go` | agent_links.* RPC handlers (v3 delegation graph management) | -| `internal/tools/workspace_dir.go` | WorkspaceDir helper, shared/isolated mode detection, file limits | -| `internal/tools/context_keys.go` | Tool context injection: team_id, team_workspace, team_task_id, workspace channel/chatid | -| `internal/agent/resolver.go` | TEAM.md generation (buildTeamMD), injection during agent resolution | -| `internal/agent/systemprompt_sections.go` | TEAM.md rendering in system prompt as `` | -| `internal/store/team_store.go` | TeamStore interface (~40 methods), data types: TeamData, TeamTaskData, TeamMessageData, TeamTaskCommentData, etc. | -| `internal/store/pg/teams.go` | PostgreSQL implementation: teams CRUD, members, tasks, messages, events, attachments | -| `cmd/gateway_managed.go` | Team tool wiring, cache invalidation subscription | -| `cmd/gateway_consumer.go` | Message routing for teammate/delegate (legacy) prefixes, task dispatch to agents | +| Module | Path | Purpose | +|---|---|---| +| Gateway RPC methods | `internal/gateway/methods/teams_*.go`, `internal/gateway/methods/agent_links.go` | Team CRUD, task board, workspace, agent links RPC handlers | +| Team tools | `internal/tools/team_*.go`, `internal/tools/subagent_*.go`, `internal/tools/workspace_dir.go`, `internal/tools/context_keys.go` | Task board tool, mailbox, access policy, delegation execution, workspace helpers | +| Store layer | `internal/store/team_store.go`, `internal/store/pg/teams.go`, `internal/store/agent_link_store.go`, `internal/store/pg/agent_links.go` | Team/task/message persistence, agent link persistence | +| Agent integration | `internal/agent/resolver.go`, `internal/agent/systemprompt_sections.go`, `cmd/gateway_managed.go`, `cmd/gateway_consumer.go` | TEAM.md generation, system prompt injection, message routing | + +Use `grep` or your editor's symbol search for specific files. --- diff --git a/docs/12-extended-thinking.md b/docs/12-extended-thinking.md index 687d90de..3bb70131 100644 --- a/docs/12-extended-thinking.md +++ b/docs/12-extended-thinking.md @@ -280,18 +280,13 @@ This makes silent downgrades or provider-default decisions visible in traces ins ## File Reference -| File | Purpose | -|------|---------| -| `internal/providers/types.go` | ThinkingCapable interface, StreamChunk.Thinking field, Opt* thinking constants | -| `internal/providers/anthropic.go` | Anthropic: budget mapping (4K/10K/32K), beta header injection, temperature stripping | -| `internal/providers/anthropic_stream.go` | Anthropic streaming: thinking_delta handling, raw block accumulation | -| `internal/providers/anthropic_request.go` | Anthropic request: thinking block preservation for tool loops | -| `internal/providers/openai.go` | OpenAI-compat: reasoning_effort mapping, reasoning_content streaming | -| `internal/providers/reasoning_capability.go` | Static GPT-5/Codex capability registry | -| `internal/providers/reasoning_resolution.go` | Requested-to-effective reasoning decision engine | -| `internal/providers/reasoning_observation.go` | Trace metadata merge helpers for reasoning decisions | -| `internal/providers/dashscope.go` | DashScope: model-specific thinking guard, budget mapping, tools+streaming fallback | -| `internal/providers/codex.go` | Codex: reasoning event streaming, OutputTokensDetails.ReasoningTokens tracking | +| Module | Path | Purpose | +|---|---|---| +| Provider types & reasoning | `internal/providers/types.go`, `internal/providers/reasoning_capability.go`, `internal/providers/reasoning_resolution.go`, `internal/providers/reasoning_observation.go` | ThinkingCapable interface, GPT-5/Codex capability registry, reasoning decision engine, trace metadata | +| Anthropic thinking | `internal/providers/anthropic.go`, `internal/providers/anthropic_stream.go`, `internal/providers/anthropic_request.go` | Budget mapping, beta header, thinking_delta streaming, block preservation for tool loops | +| OpenAI-compat, DashScope & Codex | `internal/providers/openai.go`, `internal/providers/dashscope.go`, `internal/providers/codex.go` | Reasoning effort mapping, DashScope tools+streaming fallback, Codex reasoning event streaming | + +Use `grep` or your editor's symbol search for specific files. --- diff --git a/docs/19-websocket-rpc.md b/docs/19-websocket-rpc.md index 15379845..347fd88e 100644 --- a/docs/19-websocket-rpc.md +++ b/docs/19-websocket-rpc.md @@ -832,43 +832,11 @@ Emitted whenever a trace status changes (e.g., `running` → `cancelled`, `runni ## File Reference -| File | Purpose | -|------|---------| -| `internal/gateway/router.go` | Method dispatch + auth + connect handler | -| `internal/gateway/client.go` | WebSocket client + frame reading | -| `internal/gateway/server.go` | Server + mux setup | -| `internal/gateway/methods/chat.go` | Chat send/history/abort/inject | -| `internal/gateway/methods/agents.go` | Agent list/status | -| `internal/gateway/methods/agents_create.go` | Agent creation | -| `internal/gateway/methods/agents_update.go` | Agent update | -| `internal/gateway/methods/agents_delete.go` | Agent deletion | -| `internal/gateway/methods/agents_files.go` | Agent context files | -| `internal/gateway/methods/agents_identity.go` | Agent identity | -| `internal/gateway/methods/config.go` | Config get/apply/patch/schema | -| `internal/gateway/methods/sessions.go` | Session CRUD | -| `internal/gateway/methods/skills.go` | Skill list/get/update | -| `internal/gateway/methods/cron.go` | Cron job management | -| `internal/gateway/methods/channels.go` | Channel listing | -| `internal/gateway/methods/channel_instances.go` | Channel instance CRUD | -| `internal/gateway/methods/pairing.go` | Device pairing flow | -| `internal/gateway/methods/teams.go` | Team list, create, get, delete, context methods | -| `internal/gateway/methods/teams_crud.go` | Team CRUD operations | -| `internal/gateway/methods/teams_members.go` | Team membership | -| `internal/gateway/methods/teams_tasks.go` | Team task management | -| `internal/gateway/methods/teams_workspace.go` | Team workspace | -| `internal/gateway/methods/exec_approval.go` | Exec approval flow | -| `internal/gateway/methods/agent_links.go` | Agent links management | -| `internal/gateway/methods/tenants.go` | Tenant management | -| `internal/gateway/methods/usage.go` | Usage records | -| `internal/gateway/methods/quota_methods.go` | Quota consumption | -| `internal/gateway/methods/api_keys.go` | API key management | -| `internal/gateway/methods/send.go` | Outbound messaging | -| `internal/gateway/methods/logs.go` | Log tailing | -| `internal/gateway/methods/agent_evolution.go` | Evolution metrics + suggestions + apply + rollback | -| `internal/gateway/methods/agent_episodic.go` | Episodic memory list + search | -| `internal/gateway/methods/agent_vault.go` | Knowledge vault documents + search + links | -| `internal/gateway/methods/agent_orchestration.go` | Orchestration mode info | -| `internal/gateway/methods/agent_v3flags.go` | V3 feature flags get/update | -| `internal/permissions/policy.go` | RBAC policy engine | -| `pkg/protocol/methods.go` | Method name constants | -| `pkg/protocol/events.go` | Event type constants (incl. v3 events) | +| Module | Path | Purpose | +|---|---|---| +| Gateway core | `internal/gateway/router.go`, `internal/gateway/client.go`, `internal/gateway/server.go` | Method dispatch, auth, WebSocket client, server mux | +| RPC method handlers | `internal/gateway/methods/` | One file per domain: chat, agents, config, sessions, skills, cron, channels, pairing, teams, exec_approval, agent_links, tenants, usage, api_keys, agent_evolution, agent_episodic, agent_vault, agent_orchestration, agent_v3flags | +| Auth & permissions | `internal/permissions/policy.go` | RBAC policy engine, role derivation | +| Wire protocol | `pkg/protocol/methods.go`, `pkg/protocol/events.go` | Method name constants, event type constants | + +Use `grep` or your editor's symbol search for specific files. diff --git a/docs/20-api-keys-auth.md b/docs/20-api-keys-auth.md index 83e6182d..b6591a65 100644 --- a/docs/20-api-keys-auth.md +++ b/docs/20-api-keys-auth.md @@ -399,19 +399,11 @@ curl -X POST -H "Authorization: Bearer gateway-admin-token" \ ## 11. File Reference -| File | Purpose | -|------|---------| -| `internal/crypto/apikey.go` | Key generation + SHA-256 hashing | -| `internal/store/api_key_store.go` | Store interface + `APIKeyData` struct | -| `internal/store/secure_cli_store.go` | SecureCLI store interface + `SecureCLIBinary` struct | -| `internal/store/pg/api_keys.go` | PostgreSQL API key implementation | -| `internal/store/pg/secure_cli.go` | PostgreSQL SecureCLI implementation | -| `internal/http/api_keys.go` | HTTP API handler for API keys | -| `internal/http/secure_cli.go` | HTTP API handler for SecureCLI | -| `internal/http/auth.go` | HTTP auth middleware (resolveAPIKey, tokenMatch) | -| `internal/http/api_key_cache.go` | In-memory API key cache with TTL + pubsub invalidation | -| `internal/gateway/router.go` | WebSocket connect auth (API key path) | -| `internal/gateway/methods/api_keys.go` | WebSocket RPC methods for API keys | -| `internal/permissions/policy.go` | RBAC policy engine + role derivation + scope validation | -| `migrations/000020_secure_cli_and_api_keys.up.sql` | Database migration (api_keys + secure_cli_binaries) | -| `ui/web/src/pages/api-keys/` | Web UI components | +| Module | Path | Purpose | +|---|---|---| +| Crypto & key generation | `internal/crypto/apikey.go` | Key generation, SHA-256 hashing | +| Store & persistence | `internal/store/api_key_store.go`, `internal/store/secure_cli_store.go`, `internal/store/pg/api_keys.go`, `internal/store/pg/secure_cli.go` | API key + SecureCLI interfaces and PostgreSQL implementations | +| HTTP & gateway auth | `internal/http/auth.go`, `internal/http/api_key_cache.go`, `internal/http/api_keys.go`, `internal/http/secure_cli.go`, `internal/gateway/router.go`, `internal/gateway/methods/api_keys.go` | Auth middleware, cache, HTTP handlers, WS connect auth | +| Permissions & UI | `internal/permissions/policy.go`, `ui/web/src/pages/api-keys/` | RBAC role derivation, scope validation, web management page | + +Use `grep` or your editor's symbol search for specific files. diff --git a/docs/21-agent-evolution-and-skill-management.md b/docs/21-agent-evolution-and-skill-management.md index 21e4fe0b..81642c26 100644 --- a/docs/21-agent-evolution-and-skill-management.md +++ b/docs/21-agent-evolution-and-skill-management.md @@ -504,35 +504,14 @@ When both features are disabled (default), zero token overhead. ## 7. File Reference -| File | Purpose | -|------|---------| -| `internal/agent/systemprompt.go` | `buildSelfEvolveSection()`, `buildSkillsSection()` | -| `internal/agent/loop.go` | Budget nudges (70%/90%), postscript, tool gating | -| `internal/agent/loop_history.go` | `HasSkillManage` flag, tool name filtering | -| `internal/agent/resolver.go` | Predefined-only enforcement for both features | -| `internal/store/agent_store.go` | `ParseSelfEvolve()`, `ParseSkillEvolve()`, `ParseSkillNudgeInterval()` | -| `internal/tools/skill_manage.go` | `skill_manage` tool (create/patch/delete) | -| `internal/tools/publish_skill.go` | `publish_skill` tool (directory-based) | -| `internal/tools/context_file_interceptor.go` | SOUL.md write validation for self-evolve | -| `internal/skills/guard.go` | Content security scanner (25 regex rules) | -| `internal/store/pg/skills_crud.go` | `CreateSkillManaged`, `GetNextVersionLocked`, advisory lock | -| `internal/store/pg/skills_content.go` | `GetSkillOwnerID`, `GetSkillOwnerIDBySlug` | -| `internal/store/pg/skills_grants.go` | Grant/revoke operations, visibility auto-promotion | -| `internal/http/skills.go` | HTTP skill management endpoints | -| `internal/http/skills_grants.go` | HTTP grant/revoke endpoints | -| `internal/gateway/methods/skills.go` | WebSocket skill methods | -| `internal/i18n/keys.go` | `MsgSkillNudgePostscript`, `MsgSkillNudge70Pct`, `MsgSkillNudge90Pct` | -| `internal/i18n/catalog_en.go` | English nudge translations | -| `internal/i18n/catalog_vi.go` | Vietnamese nudge translations | -| `internal/i18n/catalog_zh.go` | Chinese nudge translations | -| `cmd/gateway_builtin_tools.go` | `skill_manage` builtin tool seed entry | -| `internal/agent/suggestion_engine.go` | SuggestionEngine + pluggable rules interface | -| `internal/agent/suggestion_rules.go` | Concrete rules: LowRetrievalUsageRule, ToolFailureRule, RepeatedToolRule | -| `internal/agent/evolution_guardrails.go` | Guardrail validation, apply/rollback logic | -| `internal/store/evolution_store.go` | Store interfaces: EvolutionMetricsStore, EvolutionSuggestionStore | -| `internal/store/pg/evolution_metrics.go` | PostgreSQL evolution metrics CRUD + aggregation | -| `internal/store/pg/evolution_suggestions.go` | PostgreSQL evolution suggestions CRUD + status updates | -| `cmd/gateway_evolution_cron.go` | Daily cron job scheduler for suggestion generation | +| Module | Path | Purpose | +|---|---|---| +| Agent loop & system prompt | `internal/agent/systemprompt.go`, `internal/agent/loop.go`, `internal/agent/loop_history.go`, `internal/agent/resolver.go` | Self-evolve/skill sections, budget nudges, tool gating, predefined-only enforcement | +| Skill tools & security | `internal/tools/skill_manage.go`, `internal/tools/publish_skill.go`, `internal/tools/context_file_interceptor.go`, `internal/skills/guard.go` | skill_manage/publish_skill tools, SOUL.md validation, content security scanner | +| Skill store, HTTP & gateway | `internal/store/pg/skills_*.go`, `internal/http/skills*.go`, `internal/gateway/methods/skills.go`, `internal/store/agent_store.go` | Skill CRUD, grants, versioning, HTTP + WS methods, ParseSkillEvolve helpers | +| Evolution metrics & i18n | `internal/agent/suggestion_engine.go`, `internal/agent/evolution_guardrails.go`, `internal/store/pg/evolution_*.go`, `internal/i18n/`, `cmd/gateway_evolution_cron.go` | SuggestionEngine, guardrails, metrics/suggestions persistence, nudge translations, cron | + +Use `grep` or your editor's symbol search for specific files. --- diff --git a/docs/24-knowledge-vault.md b/docs/24-knowledge-vault.md index e4804a40..76d6c94c 100644 --- a/docs/24-knowledge-vault.md +++ b/docs/24-knowledge-vault.md @@ -545,10 +545,12 @@ Response (parallel results from vault + episodic + KG): --- -## File References +## File Reference -- **Vault service:** `internal/vault/*.go` -- **Store interface:** `internal/store/vault_store.go` -- **HTTP handlers:** `internal/http/vault_handlers.go` -- **Tools:** `internal/tools/vault_*.go` -- **Migration:** `migrations/000038_vault_tables.up.sql` +| Module | Path | Purpose | +|---|---|---| +| Vault service & sync | `internal/vault/` | VaultStore, VaultService, VaultSyncWorker, VaultRetriever, wikilink parsing | +| Store & HTTP | `internal/store/vault_store.go`, `internal/http/vault_handlers.go` | Store interface, REST endpoints (list, get, search, links) | +| Tools & migration | `internal/tools/vault_*.go`, `migrations/000038_vault_tables.up.sql` | vault_search and vault_link tools, schema migration | + +Use `grep` or your editor's symbol search for specific files.