god-eye/internal/agent/agent.go

// Package agent defines the Fase 3 AI agentic v2 interfaces: Planner,
// Worker, and Tool. Unlike Fase 0.6 adapters that merely wrap v1 Ollama
// calls, a v2 Agent plans multi-step investigations and executes tools
// via the event bus.
//
// The Agent lifecycle:
//
//  1. Planner receives the target + existing store snapshot, produces a
//     Plan (ordered list of Tasks).
//  2. Each Task is dispatched to a Worker (specialized agent: XSS, auth,
//     API, crypto, secrets, etc.) with a Tool set.
//  3. Workers call Tools (dns_resolve, http_request, check_sqli_blind,
//     fetch_js, query_cve, ...) and reason over the results.
//  4. Results feed back into Plan revision; new Tasks may be scheduled.
//
// This file defines the contracts. Implementations land incrementally;
// for now a Basic Planner delegates to the Fase 0.6 v1 Ollama wrapper,
// and a native tool-using implementation follows.
package agent

import (
	"context"
	"time"

	"god-eye/internal/eventbus"
	"god-eye/internal/store"
)

// Tool is a capability an agent can invoke. Tools should be idempotent
// where possible and must respect ctx cancellation.
type Tool interface {
	// Name is the machine identifier (e.g., "http_request", "dns_resolve").
	// Used in tool-call serialization for LLMs.
	Name() string

	// Description is a short human-readable blurb used in the LLM tool
	// descriptor. Keep it action-oriented: "fetch an HTTP URL and return
	// the response headers + first 2KB of body".
	Description() string

	// Schema returns the JSON-schema of the tool's argument object. Used
	// to build function-calling descriptors and to validate inputs.
	Schema() map[string]interface{}

	// Call invokes the tool with the given arguments. Returns a JSON-encoded
	// result (often just a text summary). Errors should be returned — the
	// agent decides how to react.
	Call(ctx context.Context, args map[string]interface{}) (string, error)
}

// Task is a single unit of agent work.
type Task struct {
	ID          string
	Kind        string            // e.g. "investigate-xss", "audit-auth", "chain-finding"
	Description string            // natural-language goal the worker pursues
	Subject     string            // target URL / subdomain / evidence the task focuses on
	Context     map[string]string // additional hints for the worker
	CreatedAt   time.Time
}

// Plan is an ordered list of Tasks produced by the Planner.
type Plan struct {
	Target string
	Tasks  []Task
	Reason string // planner's rationale, logged for debugging
}

// Planner decides what to investigate next given the current store state.
type Planner interface {
	// Plan produces a new Plan. Called at the start of the analysis phase
	// and whenever enough new evidence accumulates to justify replanning.
	Plan(ctx context.Context, target string, storeSnap store.Store, bus *eventbus.Bus) (*Plan, error)

	// Name identifies the planner implementation for logs.
	Name() string
}

// Worker executes a single Task using a Toolset.
type Worker interface {
	// Name identifies the worker (usually its specialization, e.g. "xss",
	// "auth", "api", "crypto").
	Name() string

	// CanHandle reports whether the worker is a good fit for task. Workers
	// are consulted in priority order.
	CanHandle(task Task) bool

	// Execute carries out the task. The worker may call tools, update the
	// store via bus events (VulnerabilityFound, SecretFound, AIFinding),
	// and return a short natural-language summary for the planner.
	Execute(ctx context.Context, task Task, tools Toolset, bus *eventbus.Bus, st store.Store) (summary string, err error)
}

// Toolset is an indexed collection of Tools available to a worker. It is
// intentionally separate from Registry so workers receive a curated subset
// (e.g., a "crypto" worker gets oracle-style tools but not "send_slack").
type Toolset map[string]Tool

// Get returns the named tool, or nil if absent.
func (ts Toolset) Get(name string) Tool { return ts[name] }

// Names returns every tool name in the set. Order is not guaranteed.
func (ts Toolset) Names() []string {
	out := make([]string, 0, len(ts))
	for n := range ts {
		out = append(out, n)
	}
	return out
}