diff --git a/docs/01-agent-loop.md b/docs/01-agent-loop.md index a550c4b1..0bdd0291 100644 --- a/docs/01-agent-loop.md +++ b/docs/01-agent-loop.md @@ -560,11 +560,11 @@ The Agent Router manages Loop instances with a cache layer. It supports lazy res ```mermaid flowchart TD - GET["Router.Get(agentID)"] --> CACHE{"Cache hit
and TTL valid?"} + GET["Router: get agent"] --> CACHE{"Cache hit
and TTL valid?"} CACHE -->|Yes| RETURN[Return cached Loop] CACHE -->|No or Expired| RESOLVE{"Resolver configured?"} RESOLVE -->|No| ERR["Error: agent not found"] - RESOLVE -->|Yes| DB["Resolver.Resolve(agentID)
Load from DB, create Loop"] + RESOLVE -->|Yes| DB["Resolver: load from DB, create Loop"] DB --> STORE[Store in cache with TTL] STORE --> RETURN ``` @@ -589,12 +589,12 @@ The Resolver lazy-creates Loop instances from PostgreSQL data when the Router en ```mermaid flowchart TD - MISS["Router cache miss"] --> LOAD["Step 1: Load agent from DB
AgentStore.GetByKey(agentKey)"] - LOAD --> PROV["Step 2: Resolve provider
ProviderRegistry.Get(provider)
Fallback: first provider in registry"] - PROV --> BOOT["Step 3: Load bootstrap files
bootstrap.LoadFromStore(agentID)"] - BOOT --> DEFAULTS["Step 4: Apply defaults
contextWindow <= 0 then 200K
maxIterations <= 0 then 20"] - DEFAULTS --> CREATE["Step 5: Create Loop
NewLoop(LoopConfig)"] - CREATE --> WIRE["Step 6: Wire hooks
EnsureUserFilesFunc, ContextFileLoaderFunc"] + MISS["Router cache miss"] --> LOAD["Step 1: Load agent from DB"] + LOAD --> PROV["Step 2: Resolve provider
Fallback: first provider in registry"] + PROV --> BOOT["Step 3: Load bootstrap files from store"] + BOOT --> DEFAULTS["Step 4: Apply defaults
contextWindow: 200K, maxIterations: 20"] + DEFAULTS --> CREATE["Step 5: Create Loop with resolved config"] + CREATE --> WIRE["Step 6: Wire hooks
(user files, context file loader)"] WIRE --> DONE["Return Loop to Router for caching"] ``` diff --git a/docs/03-tools-system.md b/docs/03-tools-system.md index e188980b..5280efc9 100644 --- a/docs/03-tools-system.md +++ b/docs/03-tools-system.md @@ -517,3 +517,5 @@ Subagents share the same `SecureCLIStore` as their parent — the credentialed b | MCP bridge | `internal/mcp/` | MCP server connections, tool bridge, access grants | | Custom tools | `internal/tools/` (`dynamic_loader.go`, `dynamic_tool.go`) | Runtime shell-based custom tool loading and execution | | Team tools | `internal/tools/` (`team_tasks_tool.go`, `team_tool_*.go`) | Task board backend, team tool dispatch and cache | + +Use `grep` or your editor's symbol search for specific files. diff --git a/docs/08-scheduling-cron.md b/docs/08-scheduling-cron.md index d62de27a..e3800e2f 100644 --- a/docs/08-scheduling-cron.md +++ b/docs/08-scheduling-cron.md @@ -204,40 +204,14 @@ Both jobs run with 5-minute timeout and tenant-scoped context. Failed analyses l ## File Reference -### Scheduler (Lane-Based Concurrency) -| File | Description | -|------|-------------| -| `internal/scheduler/lanes.go` | Lane and LaneManager (semaphore-based worker pools) | -| `internal/scheduler/queue.go` | SessionQueue, Scheduler, drop policies, debounce, cancel mechanics | -| `internal/scheduler/scheduler.go` | Scheduler top-level API, draining mode for graceful shutdown | -| `internal/scheduler/errors.go` | Error types: ErrQueueFull, ErrQueueDropped, ErrMessageStale, ErrGatewayDraining, ErrLaneCleared | +| Module | Path | Purpose | +|---|---|---| +| Scheduler | `internal/scheduler/` | Lane-based concurrency (lanes, queue, drop policies, debounce, cancel, draining) | +| Cron service | `internal/cron/` | In-memory run loop (1s tick), job CRUD, retry with backoff, schedule parsing, types | +| Cron store | `internal/store/pg/cron*.go`, `internal/store/cron_store.go` | CronStore interface + PostgreSQL persistence (create, list, update, delete, execution, scanning) | +| Gateway wiring | `cmd/gateway_cron.go`, `internal/gateway/methods/cron.go` | Scheduler lane routing, RPC handlers (list, create, update, delete, toggle, run, runs) | -### Cron Service (In-Memory) -| File | Description | -|------|-------------| -| `internal/cron/service.go` | Cron service lifecycle (start/stop), job CRUD | -| `internal/cron/service_execution.go` | Run loop (every 1s), job execution, schedule parsing, persistence | -| `internal/cron/retry.go` | Retry with exponential backoff + jitter, output truncation | -| `internal/cron/types.go` | Job, Schedule, JobState, RunLogEntry types | - -### Cron Persistence (PostgreSQL) -| File | Description | -|------|-------------| -| `internal/store/cron_store.go` | CronStore interface (jobs + run logs) | -| `internal/store/pg/cron.go` | PostgreSQL cron operations (create, list, update, delete) | -| `internal/store/pg/cron_crud.go` | CRUD helpers for job mutations | -| `internal/store/pg/cron_scheduler.go` | PG job cache, due-job detection, execution | -| `internal/store/pg/cron_exec.go` | Execution flow and result recording | -| `internal/store/pg/cron_scan.go` | Row scanning for jobs and run logs | -| `internal/store/pg/cron_update.go` | Job state updates in PostgreSQL | - -### Gateway Integration -| File | Description | -|------|-------------| -| `cmd/gateway_cron.go` | makeCronJobHandler (routes cron execution to scheduler) | -| `cmd/gateway_evolution_cron.go` | Evolution daily/weekly background jobs (v3 suggestion analysis + rollback evaluation) | -| `cmd/gateway_agents.go` | Agent initialization and run loop setup | -| `internal/gateway/methods/cron.go` | RPC method handlers (list, create, update, delete, toggle, run, runs) | +Use `grep` or your editor's symbol search for specific files. --- diff --git a/docs/10-tracing-observability.md b/docs/10-tracing-observability.md index 188b1916..8b32b859 100644 --- a/docs/10-tracing-observability.md +++ b/docs/10-tracing-observability.md @@ -218,20 +218,14 @@ Delegation history is automatically recorded by `DelegateManager.saveDelegationH ## File Reference -| File | Description | -|------|-------------| -| `internal/tracing/collector.go` | Collector buffer-flush, EmitSpan, FinishTrace, verbose mode | -| `internal/tracing/context.go` | Trace context propagation (TraceID, ParentSpanID, DelegateParentTraceID) | -| `internal/tracing/cost.go` | Cost calculation and pricing lookup | -| `internal/tracing/snapshot_worker.go` | Hourly usage aggregation into snapshots | -| `internal/tracing/otelexport/exporter.go` | OTel OTLP exporter (gRPC + HTTP) | -| `internal/store/tracing_store.go` | TracingStore interface, span/trace type constants | -| `internal/store/pg/tracing.go` | PostgreSQL trace/span persistence + aggregation | -| `internal/http/traces.go` | Trace HTTP API handler (GET /v1/traces) | -| `internal/agent/loop_tracing.go` | Span emission from agent loop (LLM, tool, agent spans) | -| `internal/http/delegations.go` | Delegation history HTTP API handler | -| `internal/gateway/methods/delegations.go` | Delegation history RPC handlers | -| `internal/pipeline/` | v3 agent loop pipeline (stages route to agent loop for span emission) | +| Module | Path | Purpose | +|---|---|---| +| Tracing engine | `internal/tracing/` | Collector (buffer-flush, EmitSpan, FinishTrace), context propagation, cost calculation, OTel OTLP exporter | +| Store & snapshots | `internal/store/tracing_store.go`, `internal/store/pg/tracing.go`, `internal/tracing/snapshot_worker.go` | TracingStore interface, PostgreSQL persistence + aggregation, hourly usage snapshots | +| Agent & pipeline integration | `internal/agent/loop_tracing.go`, `internal/pipeline/` | Span emission from agent loop (LLM, tool, agent spans), pipeline stage tracing | +| HTTP & RPC handlers | `internal/http/traces.go`, `internal/http/delegations.go`, `internal/gateway/methods/delegations.go` | GET /v1/traces, delegation history HTTP + RPC handlers | + +Use `grep` or your editor's symbol search for specific files. --- diff --git a/docs/15-core-skills-system.md b/docs/15-core-skills-system.md index 4b3a04ab..313f7c15 100644 --- a/docs/15-core-skills-system.md +++ b/docs/15-core-skills-system.md @@ -124,7 +124,7 @@ Supported frontmatter fields: ## 5. Hash-Based Change Detection (UpsertSystemSkill) -`UpsertSystemSkill` (`internal/store/pg/skills.go:410`) prevents unnecessary DB version bumps: +`UpsertSystemSkill` (`internal/store/pg/`) prevents unnecessary DB version bumps: ``` SELECT id, file_hash, file_path FROM skills WHERE slug = $1