mcpgw

type AuditEntry struct {
	Timestamp  time.Time
	AgentID    string
	SessionID  string
	TenantID   string
	Scope      string
	Command    string
	Path       string
	Domain     string
	URL        string
	Decision   string
	Rule       string
	Reason     string
	DurationMs float64
	Meta       map[string]interface{}
}

type Bridge struct {

	// PolicyCheck is the hook A18 wires. The default (nil) ALLOWs
	// every tool call — useful for early bring-up before the policy
	// engine is integrated. A18 sets this to a function that:
	//   1. Builds a policy.ActionRequest from the ToolsCallRequest
	//      (scope: "mcp_tool", command: "<ns>:<tool>", agent_id from
	//      clientInfo, etc.).
	//   2. Optionally also dispatches a second Engine.Check against
	//      the mapped scope per the dual-check pattern (governed by
	//      Config.PolicyMode == "strict").
	//   3. Returns a Decision struct.
	//
	// The bridge calls PolicyCheck with the bridge's context so a
	// cancellation propagates into the hook.
	PolicyCheck func(ctx context.Context, req *ToolsCallRequest) (Decision, error)

	// AuditEmit is the hook A19 wires. The default (nil) is a no-op.
	// A19 sets this to a function that writes one audit.Entry via
	// the shared BufferedAsyncLogger with Transport: "mcp_gateway".
	// The hook MUST NOT block the request hot path — A19 is expected
	// to fan out to its own goroutines internally.
	AuditEmit func(entry AuditEntry)

	// SSEEmit is the hook A19 wires. The default (nil) is a no-op.
	// A19 sets this to a function that pushes one SSE event into
	// the existing pkg/proxy ApprovalQueue's broadcast channel so
	// the dashboard sees MCP traffic with the `mcp_gateway` chip.
	SSEEmit func(event SSEEvent)
	// contains filtered or unexported fields
}

type ClientInfo struct {
	Name    string `json:"name"`
	Version string `json:"version,omitempty"`
}

type CommandFactory func(ctx context.Context, argv []string) (*exec.Cmd, error)

type Config struct {
	// Upstreams is the ordered list of downstream MCP servers the
	// gateway brokers. Repeatable via --upstream. At least one entry
	// is required.
	Upstreams []UpstreamSpec

	// GuardURL is the central AgentGuard server's base URL (the host
	// of /v1/check). Default "http://127.0.0.1:8080".
	GuardURL string

	// APIKey is the bearer token sent to /v1/check. Falls back to the
	// AGENTGUARD_API_KEY env var when the flag is empty. May be empty
	// (the central server runs without auth in that case — a WARNING
	// is logged at startup).
	APIKey string

	// TenantID is the tenant header value. Default "local".
	TenantID string

	// FailMode controls behaviour when /v1/check is unreachable.
	// One of "deny", "allow", "fail-closed-with-audit". Default "deny".
	// Mirrors the SDK fail-mode contract documented in
	// docs/PROXY_ARCHITECTURE.md § 6.1.
	FailMode string

	// PolicyMode is "strict" (dual-check: mcp_tool + mapped scope) or
	// "fast" (single-check: mcp_tool only). Default "strict".
	// docs/MCP_GATEWAY.md § 4.4.3 — A18 wires the actual dual-check;
	// the bridge passes this value through to the policy hook.
	PolicyMode string

	// LogLevel controls stderr verbosity. "info" or "debug". Default
	// "info". A18/A19 may extend this set.
	LogLevel string

	// UpstreamTimeout caps how long the bridge waits for a response
	// from a single upstream Send. Default 30s.
	UpstreamTimeout time.Duration

	// ReconnectCap caps the upper bound on reconnect backoff between
	// upstream restart attempts. Default 60s.
	ReconnectCap time.Duration

	// SupportedProtocolVersions is the set of MCP protocol versions
	// the gateway will accept on `initialize`. Defaults to
	// DefaultSupportedProtocolVersions; populated by ParseConfig so
	// tests can pin a custom set.
	SupportedProtocolVersions []string

	// PolicyPath is the filesystem path to the same policy YAML the
	// central AgentGuard server loads. The gateway opens this file at
	// startup so it can resolve `tool_scope_map` locally for the
	// dual-check pattern (see docs/MCP_GATEWAY.md § 4.4 and gate.go).
	// Required when --policy-mode strict is in effect; tests may leave
	// it empty and supply a *policy.Policy directly via the gate's
	// constructor instead.
	PolicyPath string
}

type ContentBlock struct {
	Type string `json:"type"`
	Text string `json:"text,omitempty"`

	// Extra carries image/resource fields, annotations, etc., so a
	// content block from an upstream round-trips losslessly.
	Extra map[string]json.RawMessage `json:"-"`
}

type Decision struct {
	Allow       bool
	Reason      string
	Rule        string
	ApprovalID  string // set when REQUIRE_APPROVAL
	ApprovalURL string
	// RequiresApproval is set when the policy engine returned
	// REQUIRE_APPROVAL. The bridge surfaces it as an isError=true
	// content block (per docs/MCP_GATEWAY.md § 6.1) rather than a
	// JSON-RPC error.
	RequiresApproval bool
}

type Error struct {
	Code    int             `json:"code"`
	Message string          `json:"message"`
	Data    json.RawMessage `json:"data,omitempty"`
}

type HTTPPolicyClient struct {
	GuardURL   string // e.g. "http://127.0.0.1:8080"
	APIKey     string // bearer token; empty if --api-key not set
	TenantID   string // "local" for v0.5
	PolicyMode string // "strict" | "fast"
	FailMode   string // "deny" | "allow" | "fail-closed-with-audit"

	// HTTPClient is reused across calls. Set to a custom client in
	// tests; otherwise the constructor defaults to a 5s-timeout client.
	HTTPClient *http.Client
	// contains filtered or unexported fields
}

type InitializeParams struct {
	ProtocolVersion string                 `json:"protocolVersion"`
	Capabilities    map[string]interface{} `json:"capabilities,omitempty"`
	ClientInfo      ClientInfo             `json:"clientInfo"`
}

type InitializeResult struct {
	ProtocolVersion string                 `json:"protocolVersion"`
	Capabilities    map[string]interface{} `json:"capabilities"`
	ServerInfo      ServerInfo             `json:"serverInfo"`
}

type Notification struct {
	JSONRPC string          `json:"jsonrpc"`
	Method  string          `json:"method"`
	Params  json.RawMessage `json:"params,omitempty"`
}

type Request struct {
	JSONRPC string          `json:"jsonrpc"`
	ID      RequestID       `json:"id,omitempty"`
	Method  string          `json:"method"`
	Params  json.RawMessage `json:"params,omitempty"`
}

type RequestID = interface{}

type Response struct {
	JSONRPC string          `json:"jsonrpc"`
	ID      RequestID       `json:"id"`
	Result  json.RawMessage `json:"result,omitempty"`
	Error   *Error          `json:"error,omitempty"`
}

type SSEEvent struct {
	Type      string // "check" | "denied" | "approval_required"
	Timestamp time.Time
	AgentID   string
	Decision  string
	Scope     string
	Command   string
	Meta      map[string]interface{}
}

type ServerInfo struct {
	Name    string `json:"name"`
	Version string `json:"version"`
}

type StdioUpstream struct {
	// contains filtered or unexported fields
}

type StdioUpstreamOptions struct {
	Backoff        []time.Duration
	CommandFactory CommandFactory
	Logger         *transportLogger
}

type ToolDescriptor struct {
	Name        string                 `json:"name"`
	Description string                 `json:"description,omitempty"`
	InputSchema map[string]interface{} `json:"inputSchema,omitempty"`

	// Annotations / outputSchema / future fields are preserved so the
	// gateway forwards the descriptor verbatim. We marshal/unmarshal
	// through a custom helper to keep this clean — see toolDescriptorFromRaw.
	Extra map[string]json.RawMessage `json:"-"`
}

type ToolsCallParams struct {
	Name      string                 `json:"name"`
	Arguments map[string]interface{} `json:"arguments,omitempty"`
	Meta      map[string]interface{} `json:"_meta,omitempty"`
}

type ToolsCallRequest struct {
	Namespace  string                 // resolved from the prefixed name
	ToolName   string                 // un-prefixed name as the upstream sees it
	FullName   string                 // the prefixed name as the host sent it
	Arguments  map[string]interface{} // tool arguments verbatim
	Meta       map[string]interface{} // _meta with `dev.agentguard/*` keys preserved
	TenantID   string                 // from cfg.TenantID
	AgentID    string                 // synthesised from ClientInfo.Name
	SessionID  string                 // session-scoped key (clientInfo + pid hint)
	ApprovalID string                 // populated from _meta.dev.agentguard/approval_id if present
}

type ToolsCallResult struct {
	Content []ContentBlock `json:"content"`
	IsError bool           `json:"isError,omitempty"`
}

type ToolsListResult struct {
	Tools      []ToolDescriptor       `json:"tools"`
	NextCursor string                 `json:"nextCursor,omitempty"`
	Meta       map[string]interface{} `json:"_meta,omitempty"`
}

type Upstream interface {
	// Namespace returns the namespace label this upstream answers to
	// (e.g. "fs", "github").
	Namespace() string

	// Status returns one of the Status* constants.
	Status() string

	// Initialize handshakes the protocol version + capabilities with
	// the upstream. Called by the supervisor immediately after the
	// subprocess starts (and again on every reconnect). The
	// `clientCaps` arg is the host's capabilities, forwarded verbatim
	// per docs/MCP_GATEWAY.md § 3.2 step 3.
	Initialize(ctx context.Context, protocolVersion string, clientCaps map[string]interface{}, clientInfo ClientInfo) (*InitializeResult, error)

	// Send dispatches a request to the upstream and waits for its
	// matching response. The caller-supplied `req.ID` is replaced
	// with a gateway-internal id (the upstream's id space is per
	// connection); the original id is preserved so the bridge can
	// surface it back to the host. Honors ctx for cancellation.
	Send(ctx context.Context, req *Request) (*Response, error)

	// Notify dispatches a one-way notification (no response). The
	// upstream MUST NOT reply.
	Notify(ctx context.Context, n *Notification) error

	// Close terminates the upstream gracefully. Idempotent.
	Close() error
}

type UpstreamSpec struct {
	Namespace string // e.g. "fs", "github"
	Command   string // raw command string, shell-tokenized at start time

	// Transport is reserved for future use. v0.5 always uses stdio.
	Transport string
}